[objectstack-fleet]

Requested by Warren · project thread
Fixes #29510

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么:getMetaTypes() 现在声明具名返回类型 Promise<MetaTypesListing>,由 spec 已导出的类型组合而成;方法体内一行编译期 Equal 断言把它钉成与方法体推断出的类型完全相等。
• 为什么改:原来是推断类型,index.d.ts 内联展开 793 行,[maintainer] refactor(metadata-protocol): split src/protocol.ts (33,065 lines, +10,169 in 30 days) along its ObjectStackProtocolImplementation seams, one move-only slice per PR #25467 每一刀都要人工读这一块原始 diff。现在 d.ts 只印别名,类型一旦漂移 tsc 直接报错。
• 风险与回滚:无运行时改动,公开类型不变(已对 main 构建出的 d.ts 做过一次类型相等证明);MetaTypesListing 不从包导出,不新增公开名。回滚即 revert。
• 先看:packages/metadata-protocol/src/protocol-meta-types-listing.ts(类型定义,注意 actions 的两臂);protocol.ts 中 getMetaTypes() 的签名与结尾 exact 一行。
• 两分钟验证:pnpm --filter @objectstack/metadata-protocol typecheck,预期 exit 0;把类型里 schemaId: string; 改成 schemaId?: string; 再跑,预期只在 exact 那一行报 TS2322。
• 需要你做的:无,席位落地。

What changes

• packages/metadata-protocol/src/protocol-meta-types-listing.ts (new, 68 lines): MetaTypesListingEntry, MetaTypesListing and a strict Equal type. The entry is MetadataTypeRegistryEntryParsed (minus type, allowEnvironmentOverlay, actions) plus the fields the listing adds or overrides: type: string, schemaId, allowEnvironmentOverlay: boolean, overrideSource, schema: Record<string, unknown>, form: FormView, createSeed?: {} | null, and actions?: Action[] | NonNullable<MetadataTypeRegistryEntryParsed['actions']>. The second actions arm is in main's type because the row spreads the registry entry before it overrides actions; leaving it out fails the pin. A mapped Flatten turns the intersection into one object type, which the strict Equal needs to compare equal to an inferred object literal. Nothing new is exported from the package index.
• packages/metadata-protocol/src/protocol.ts: getMetaTypes() declares Promise<MetaTypesListing>. The body is unchanged up to its last line, which now builds const listing = { types: allTypes, entries }, holds const exact: Equal<typeof listing, MetaTypesListing> = true, and returns listing. One type-only import. 11 lines, +9/-2.
• .changeset/29510-meta-types-named-return.md: @objectstack/metadata-protocol patch, both declaration lines.

Why

The #25467 E1 seat ruling (PR #29488) kept getMetaTypes() inferred so E1's index.d.ts stayed byte-identical, and moved the explicit return type to its own step, option B of the E1 report: a named composed type with a type-equality pin. Triage audit 6592554479 kept it p3, domain:server.

What retires the per-cut raw-diff reading of getMetaTypes()

The exact line. typeof listing is the type the body infers, which is the type main emitted. If a cut or any later edit changes what the body builds, or changes the declared name, tsc fails at that line in typecheck and in the tsup declaration build. The .d.ts now prints getMetaTypes(): Promise<MetaTypesListing> and an alias, so there is no 793-line inline block left for a cut to read, and no inferred block a stray class comment can surface inside.

What this does not retire: ruling 6348891160's whole-index.d.ts reading still applies to each cut, because other public members of the class stay inferred (getDiscovery, getMetaItems, getMetaItem, findData, … as listed in 6385903828). The module comment above the protocol-meta-type-schema.js import in protocol.ts ("read its raw diff after any edit here") is still true for them, so it is left as it is.

Tests

Measured on main 1c1a5d4 before the edit: the dependency closure built under the lock (pnpm --filter '@objectstack/metadata-protocol...' build, VERDICT command-exit 0). dist/index.d.ts lines 3057–3849 hold getMetaTypes(): 793 lines, sha256 b0f7f61a…c85bf, starting getMetaTypes(): Promise<{ and ending }>;. No comment sits inside that block on this tree.

Type equality against main's emitted type (one-time proof, not committed)

A scratch probe beside the package imported ObjectStackProtocolImplementation from a copy of main's dist/index.d.ts and from this branch's rebuilt dist/index.d.ts, and compiled Equal<Before, After> and Equal<Before['entries'][number], After['entries'][number]> with true: tsc exit 0. Negative control, same probe plus Equal<Before['entries'][number], Omit<After['entries'][number], 'schemaId'>> = true: exit 2, TS2322: Type 'true' is not assignable to type 'false'. The probe was deleted afterwards.

The .d.ts text diff, main vs this branch: the 793-line block becomes getMetaTypes(): Promise<MetaTypesListing>;, 39 lines of alias declarations are added (not exported), and two import lines change (FormFieldInput was only used inside the old inline block; FormView, Action and MetadataTypeRegistryEntryParsed are now imported). Nothing else in the file moves.

Ablation: the pin fails on a member drift

Committed first (6525242), then node scripts/ablation-replace.mjs --file …/protocol-meta-types-listing.ts --anchor "schemaId: string;" --replacement "schemaId?: string;" -- pnpm --filter @objectstack/metadata-protocol typecheck, with an EXIT INT TERM trap restoring from HEAD:

• mutation landed: anchor 1 → 0, replacement 0 → 1, blob 81483bc18bca → b5392c1a893c;
• tsc --noEmit: one error, src/protocol.ts(3297,15): error TS2322: Type 'true' is not assignable to type 'false' (the exact line), exit 2;
• restored: blob == HEAD (81483bc18bca), git diff HEAD empty.

Making a member optional is assignable to the declared type, so return alone would not catch it. Only the pin did.

Gates on 94b9d02 (final head, after merging main c9636f1)

• Builds under the lock: pnpm turbo run build --concurrency=2 --filter=@objectstack/metadata-protocol... --filter=@objectstack/objectql (VERDICT command-exit 0).
• pnpm --filter @objectstack/metadata-protocol test under the lock: Test Files 308 passed, 4 skipped (312); Tests 22264 passed, 26 skipped (22290); VERDICT command-exit 0. (On 6525242, before the merge: 22262 passed, VERDICT 0.)
• pnpm --filter @objectstack/metadata-protocol typecheck: exit 0 (the pin holds on the merged tree).
• pnpm lint: exit 0.
• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack: 54 families (3 paths vs merge base, +87/-2), the same list before and after the merge. Each run once, exit captured before any pipe: 53 exit 0.
• pnpm check:dual-build-cjs-loads: exit 3, PREREQUISITE NOT MET (about 70 workspace packages unbuilt in this container). NOT MEASURED locally; CI runs it on a full build.
• dispatch-gates --ran: 54 derived, 53 run, 1 NOT-MEASURED (dual-build, from its recorded exit 3), 0 UNRUN.
• Prerequisites met on the first round: check-plugin-teardown-shape --self-test needed its pinned fixture commit fetched (shallow clone), check:lean-entry-closure needed objectql built; both then exit 0.

Acceptance notes

• The .d.ts text changes and the type does not; that is the card's stated bar, measured above.
• MetaTypesListing and MetaTypesListingEntry are not exported from @objectstack/metadata-protocol, so no new public name.

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic. (not touched)
• 2. Every name I added uses the casing for its kind.
• 3. No formatter ran; pnpm lint passes.
• 4. One issue, one branch off an up-to-date main, one pull request.
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset.
• 6. packages/spec touched: its generated artifacts are regenerated and committed. (not touched)
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English. (the 维护者速读 section is the repo's required Chinese brief)
• The Before Submitting list in CONTRIBUTING.md is done.

domain:server#3 · os-warren · session_01JQwxbWaMuBU5CquKAT7ZmH

🤖 Generated with Claude Code

https://claude.ai/code/session_01JQwxbWaMuBU5CquKAT7ZmH

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-protocol, touching 5 documentable anchor(s).

12 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/ai/agents.mdx (via allowEnvironmentOverlay (literal, a string literal in Omit))
• content/docs/api/declarative-endpoints.mdx (via allowEnvironmentOverlay (literal, a string literal in Omit))
• content/docs/api/metadata-api.mdx (via allowEnvironmentOverlay (literal, a string literal in Omit))
• content/docs/automation/jobs.mdx (via allowEnvironmentOverlay (literal, a string literal in Omit))
• content/docs/concepts/metadata-lifecycle.mdx (via ObjectStackProtocolImplementation (symbol, a top-level class), allowEnvironmentOverlay (literal, a string literal in Omit))
• content/docs/deployment/environment-variables.mdx (via allowEnvironmentOverlay (literal, a string literal in Omit))
• content/docs/kernel/contracts/metadata-service.mdx (via allowEnvironmentOverlay (literal, a string literal in Omit))
• content/docs/kernel/services-checklist.mdx (via getMetaTypes (symbol, a method of class ObjectStackProtocolImplementation))
• content/docs/permissions/authorization.mdx (via allowEnvironmentOverlay (literal, a string literal in Omit))
• content/docs/permissions/capabilities.mdx (via allowEnvironmentOverlay (literal, a string literal in Omit))
• content/docs/plugins/adding-a-metadata-type.mdx (via getMetaTypes (symbol, a method of class ObjectStackProtocolImplementation), allowEnvironmentOverlay (literal, a string literal in Omit))
• content/docs/protocol/objectui/concept.mdx (via allowEnvironmentOverlay (literal, a string literal in Omit))

⛔ 3 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx (via ObjectStackProtocolImplementation (symbol, a top-level class))
• content/docs/releases/v17/17-0.mdx (via ObjectStackProtocolImplementation (symbol, a top-level class))
• content/docs/releases/v18/18-0.mdx (via allowEnvironmentOverlay (literal, a string literal in Omit))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 61 of 218 client-bound route-ledger rows — the other 157 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 157: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 10 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 87956dcc33b47d5c8bed301a87d6d4c8bdd87262 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 5e903068369fe128e16608870df2e187a6a3f812 — the merge of head 94b9d02b30f1873a89c1b310453b115ff0f94acc into base 87956dcc33b47d5c8bed301a87d6d4c8bdd87262, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 5e903068369fe128e16608870df2e187a6a3f812 && git checkout 5e903068369fe128e16608870df2e187a6a3f812
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 87956dcc33b47d5c8bed301a87d6d4c8bdd87262 94b9d02b30f1873a89c1b310453b115ff0f94acc && git checkout -B drift-repro 87956dcc33b47d5c8bed301a87d6d4c8bdd87262 && git merge --no-ff 94b9d02b30f1873a89c1b310453b115ff0f94acc

node scripts/docs-audit/affected-docs.mjs --json 87956dcc33b47d5c8bed301a87d6d4c8bdd87262

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 87956dcc33b47d5c8bed301a87d6d4c8bdd87262 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

domain:server#3 · os-warren · session_01JQwxbYyp6wSRcywGFK2L4A

维护者速读

• 改了什么：getMetaTypes() 声明具名返回类型 Promise<MetaTypesListing>，由 spec 已导出类型组合而成；方法体内一行编译期 Equal 断言把它钉成与方法体推断类型完全相等。
• 为什么改：原先是推断类型，index.d.ts 内联展开 793 行，[maintainer] refactor(metadata-protocol): split src/protocol.ts (33,065 lines, +10,169 in 30 days) along its ObjectStackProtocolImplementation seams, one move-only slice per PR #25467 每一刀都要人工读这块原始 diff；现在 d.ts 只印别名，类型一漂移 tsc 就报错。
• 风险与回滚：无运行时改动，公开类型不变（已对 main 构建出的 d.ts 做过一次类型相等证明）；MetaTypesListing 不从包导出，无新公开名。回滚即 revert。
• 先看：packages/metadata-protocol/src/protocol-meta-types-listing.ts（注意 actions 两臂）；protocol.ts 中 getMetaTypes() 签名与结尾 exact 一行。
• 两分钟验证：pnpm --filter @objectstack/metadata-protocol typecheck 预期 exit 0；把 schemaId: string; 改成 schemaId?: string; 再跑，预期只在 exact 行报 TS2322。
• 需要你做的：无，席位落地。
• 席位意见：只退役 getMetaTypes() 这一块的逐刀原始 diff 阅读；其余仍为推断类型的公开成员照旧按裁决 6348891160 整读 d.ts，PR 正文已写明。

席位核对

ACCEPT · domain:server#3 · head 94b9d02b30f1873a89c1b310453b115ff0f94acc · 2026-11-03T03:23Z · seat review of record at TIER_DEFAULT (not governed: check-governed-merges --pr 29730 NOT governed, 89 lines; no packages/spec path; Clause-②: no holds — nothing new exported, emitted type proved equal; no contract face, so no second agent)

1. Shape: draft, base main, Fixes #29510, Clause-②: no, Metadata-protocol: none (body and changeset agree; @objectstack/metadata-protocol patch). 3 files, +87/-2. Seat read the diff: the body is unchanged up to its last line, which builds listing, holds exact: Equal<typeof listing, MetaTypesListing> = true, and returns it; MetaTypesListing is absent from the package index.
2. Premise measured: main 1c1a5d4 dist/index.d.ts L3057–3849, 793 lines, inferred. One-time probe: Equal<Before, After> true (exit 0), negative control Omit<…,'schemaId'> exit 2. Ablation schemaId?: string → single TS2322 at the exact line, restored to HEAD blob.
3. Gates on this head: check-runs pinned to 94b9d02b: 48 total, 35 success, 13 skipped, 0 failed (Lint & Repo Gates and TypeScript Type Check success); mergeable_state clean. Dev on the same head: 53/54 derived gates exit 0, check:dual-build-cjs-loads NOT MEASURED locally (prereq) and answered by CI, --ran 0 unrun, pnpm lint 0, metadata-protocol 22264 passed, typecheck 0.
4. Prose checked against the diff: the changeset's "No behaviour change and no type change" (body unchanged up to the last line; equality probe), "composed from @objectstack/spec's MetadataTypeRegistryEntryParsed, Action and FormView" (the three imports in the new module), and "MetaTypesListing is not exported from the package" (absent from src/index.ts) each hold against the diff.
5. Out of scope: the other inferred public members (getDiscovery, getMetaItems, …) keep the whole-d.ts reading of ruling 6348891160; no card owed now (each would be its own [maintainer] refactor(metadata-protocol): split src/protocol.ts (33,065 lines, +10,169 in 30 days) along its ObjectStackProtocolImplementation seams, one move-only slice per PR #25467 step). Skills-docs: not owed (Metadata-protocol: none).
6. Landing: not governed, under 3000 lines ⇒ the seat lands it (pr_ready + automerge_enable). protocol.ts serial: no E2 cut or freeze in flight. At MERGED: landing record on metadata-protocol: give getMetaTypes() a named composed return type, held equal to main's emitted d.ts by a type-equality pin (#25467 E1 follow-up) #29510 (closed by Fixes), pm:dispatched removed, card thread released.