refactor(metadata-protocol): spell the inferred return types of the eight protocol.ts doors the facade keeps (.d.ts byte-equal) by objectstack-fleet[bot] · Pull Request #30516 · objectstack-ai/objectstack

objectstack-fleet · 2026-11-05T13:56:44Z

Requested by Bill · project thread

domain:server#5 · os-bill · session_01Utp6CYVV6fcAQrNTDQRvPb

维护者速读

改了什么：protocol.ts 门面上 8 个因返回类型靠推断而留在类上的公开方法（getDiscovery、findData、getData、cloneData 和四个 *MetaItem）把返回类型写明在签名上，类型逐字取自它今天被推断进的 .d.ts；方法体一行未动。
为什么改：返回类型靠推断时，方法体一挪走，.d.ts 就会经新位置重新推断（拆分时实测 getDiscovery 丢过一个 @deprecated 注释），所以它们只能留在门面上；写明之后类型不再取决于方法体放在哪。
风险与回滚：没有行为变化，公开 index.d.ts / index.d.cts 改前改后逐字节相同；只有 source map 随新增行变动。回滚即撤本 PR。
先看：packages/metadata-protocol/src/protocol.ts 里 getDiscovery 的新签名（最长的一段），再看 scripts/facade-delegation-registry.json 改了理由的 8 行。
两分钟验证：pnpm --filter @objectstack/metadata-protocol exec vitest run src/protocol.facade-door-return-types.pin.test.ts，预期 9 条全绿；在 main 的 protocol.ts 上其中 8 条是红的。
需要你做的：无，席位落地。方法体搬进 facet 这一步本 PR 没做（codemod 已不能在拆好的文件上重跑，见 Acceptance notes），engine.ts 那一半排在 refactor: sweep the #4918 as any sites in engine.ts's six erasure-pinned methods so the codemod can move them (about 550 lines) #30055 之后。

Part of #30054 (the protocol.ts half, step 1 only: the return types are spelled; the bodies stay, and the engine.ts half is owed. Both are listed under Acceptance notes.)

Clause-②: no — the published index.d.ts and index.d.cts of @objectstack/metadata-protocol are byte-equal before and after, so no exported member changes.
Metadata-protocol: none
Skills-docs: none — an internal refactor of eight method signatures whose printed types do not change; no skill text names them.

What changes

packages/metadata-protocol/src/protocol.ts. The eight doors the tooling: a structural gate that refuses any method body in a facade file once protocol.ts and engine.ts land in facade form (ruling 6624258595) #30019 gate lists as inferred-return-type exceptions on card refactor: give the inferred-return-type public methods on the engine.ts and protocol.ts facades explicit return types (.d.ts unchanged), so the codemod can move their bodies #30054 now declare their return type: getDiscovery, findData, getData, cloneData, saveMetaItem, publishMetaItem, rollbackMetaItem, deleteMetaItem. Each type is copied, text for text, from the line the base build printed for that method in dist/index.d.ts: the type literals, their docblocks (the @deprecated on getDiscovery's apiName, the ones publishMetaItem carries), the double-quoted string unions and the | undefined the printer writes are all kept, so the declaration emit reprints them unchanged. No body, parameter or modifier changes. tsc --noEmit accepts every body against its spelled type.
scripts/facade-delegation-registry.json. The eight rows stay (their bodies are still on the class, and the gate refuses a row whose member is already a delegation). Their reason no longer says "stays until the return type is spelled", which is now false; it says the type is spelled and why the body still stays.
Pin. protocol.facade-door-return-types.pin.test.ts parses protocol.ts and requires each of the eight doors to carry a return type annotation, so an edit cannot quietly drop one before a later move would re-infer it.
Changeset. @objectstack/metadata-protocol patch: the published declarations are byte-equal, but the shipped source maps move with the new lines, so the package's published files do change.

Tests

New pin: 9/9 pass at head. On origin/main's protocol.ts (restored unstaged, then put back from HEAD, git diff HEAD empty) 8 of 9 fail, one per door.
Ablation (once, through scripts/ablation-replace.mjs): rollbackMetaItem's annotation removed, anchor 1 → 0, blob 0a87e4f8 → ec11148a; the pin goes 1 failed / 8 passed, naming rollbackMetaItem; restored to the HEAD blob with git diff HEAD empty.
@objectstack/metadata-protocol full suite at head 1777fb2d2: 317 files passed, 4 skipped; 22,434 tests passed, 26 skipped. pnpm typecheck exit 0. (The same suite ran at 63a626492, before the second merge: 316 files, 22,419 tests, all passing.)
pnpm lint (eslint . --no-inline-config) exit 0 at 63a626492; at head 1777fb2d2, eslint --no-inline-config over the two changed source files exit 0.

Acceptance notes

The move (step 2) is not mechanical today, so it is not in this PR. scripts/codemod-split-protocol.mjs cannot re-run on the landed facade: on origin/main it refuses with "protocol.ts already carries [Codemod split: generate the rest of the metadata-protocol protocol.ts split with a deterministic script, verified byte-identical #29985 codemod] stubs: run the script on an unsplit file". Its regenerate-from-base route no longer holds either: --verify --base 48914fdc^ (the Codemod split: generate the rest of the metadata-protocol protocol.ts split with a deterministic script, verified byte-identical #29985 split's base) now reports 79/85 moved bodies identical and 71/78 host-split checks passing, because later PRs edited moved bodies in the facet modules (fix(plugin-auth)!: an organization cannot require MFA while two-factor enrollment is off (#30201) #30293, fix(metadata-protocol,rest): a .custom pair's declared override is labelled in the ruled order on every /meta read #30353, fix(metadata-protocol,cli): os migrate packageless-overlays lists a package-less view container cannot_declare, and --apply never attempts it #30380, fix(metadata-protocol): duplicating a package copies a permission set that grants on an optional plugin's object not installed here #30414), and two facet modules gained top-level statements that are not facet methods (PackagedArtifactBaseType in protocol-discovery-and-bases.ts, storedGrantObjectKeys in protocol-package-commits.ts), which the facade layer's unlift refuses. Moving the eight bodies needs a pass over the landed facade, as the engine codemod has (--scoped, --hand-docs, and refactor: sweep the #4918 as any sites in engine.ts's six erasure-pinned methods so the codemod can move them (about 550 lines) #30055's --members). That is an edit to scripts/codemod-split-protocol.mjs, outside this card's file surface; carrier: the seat.
Rows still owed on refactor: give the inferred-return-type public methods on the engine.ts and protocol.ts facades explicit return types (.d.ts unchanged), so the codemod can move their bodies #30054. protocol.ts (body move): getDiscovery, findData, getData, cloneData, saveMetaItem, publishMetaItem, rollbackMetaItem, deleteMetaItem. engine.ts (types and move, serial behind refactor: sweep the #4918 as any sites in engine.ts's six erasure-pinned methods so the codemod can move them (about 550 lines) #30055): registerApp, registerHook, registerDriver, init, triggerHooks, destroy, setDatasourceMapping, getStatus.
A spelled type is now the published shape, so it must move with the body. TypeScript does not refuse a body that returns a wider object than its signature (a non-literal return gets no excess-property check), and the .d.ts prints the signature, not the body. Measured on this branch: origin/main gained seedApplied.landed on the publish receipt (feat(spec,metadata-protocol): the publish receipt names the rows a seed created and the rows it only matched #30427, a7b8876f5) while this PR was open; the branch's first spelling (copied at c5800818) merged with no conflict, and would have dropped landed from the published publishMetaItem type. The type was re-copied from a1d0b1ee9's build (commit 1777fb2d2), and the proof below is against that base. A later change to what one of these doors returns edits the signature too.
No packages/objectql file changes, so its declaration files are not re-proved here.

Verification

Head 1777fb2d2 (branch merged with origin/main a1d0b1ee9), base a1d0b1ee9.

Declaration-file proof

Base: origin/main a1d0b1ee9's protocol.ts restored into the merged tree (the merged file differs from it only by the eight annotations), turbo run build --filter=@objectstack/metadata-protocol..., dist/index.d.ts and dist/index.d.cts copied aside. The eight types were copied from that index.d.ts.
Head 1777fb2d2: pnpm build in packages/metadata-protocol (tsup with DTS, then check-dts-emitted: 2/2 declaration files present); cmp against the base copies: index.d.ts byte-equal, index.d.cts byte-equal (index.d.ts sha256 f7c56a2155a2b77a… on both sides).
The same proof ran first at base c5800818 (byte-equal, sha256 2f93f627839cccd7…), before the merge that brought feat(spec,metadata-protocol): the publish receipt names the rows a seed created and the rows it only matched #30427.
The diff of the emitted declarations is empty.

Gates

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at head 1777fb2d2: 69 derived commands (change set: 4 paths, +251 / -16, under the 3,000 threshold). Each was run with its exit code recorded before any pipe; all 69 exit 0. --ran reconciles 69 derived, 69 run, 0 NOT-MEASURED, 0 UNRUN. check-plugin-teardown-shape --self-test needed git fetch origin 621a4876… first (shallow clone).
The first pass at 63a626492 (same 69 commands) had 68 exit 0 and check:dual-build-cjs-loads exit 3 (no full workspace build then); at the final head it ran and passed.
pnpm check:facade-delegation-only: "5 facade class(es) in 3 file(s) hold delegations only", exit 0; the registry still carries the eight rows.
eslint over the two changed source files exit 0 at head; pnpm lint exit 0 at 63a626492.

Generated by Claude Code

…ight protocol.ts doors kept on the facade Claude-Session: https://claude.ai/code/session_01Utp6CXZTh9qvT24wTN6dd6 Co-authored-by: Claude <noreply@anthropic.com>

…ypes Claude-Session: https://claude.ai/code/session_01Utp6CXZTh9qvT24wTN6dd6 Co-authored-by: Claude <noreply@anthropic.com>

… is spelled and why the body stays Claude-Session: https://claude.ai/code/session_01Utp6CXZTh9qvT24wTN6dd6 Co-authored-by: Claude <noreply@anthropic.com>

… types Claude-Session: https://claude.ai/code/session_01Utp6CXZTh9qvT24wTN6dd6 Co-authored-by: Claude <noreply@anthropic.com>

…-alkkr9

…he seed receipt's landed rows from main Claude-Session: https://claude.ai/code/session_01Utp6CXZTh9qvT24wTN6dd6 Co-authored-by: Claude <noreply@anthropic.com>

github-actions · 2026-11-05T13:58:05Z

📓 Docs Drift Check

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

30 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 455b4f095a1c71252bbebac4e1bc8b43ab9a2dae.

⛔ 11 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

1 cross-cutting symbol(s) contributed no route anchor: findData (4 routes)
the SDK route bridge reached 61 of 219 client-bound route-ledger rows — the other 158 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 158: 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; 103 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 455b4f095a1c71252bbebac4e1bc8b43ab9a2dae → packageMentionDocs.

Which tree this was computed on

This run read content/docs from db73d84694c4bdb187b1a73963d1d00506b9be8f — the merge of head 1777fb2d2cdf6ff6057a9f53ed1bafb023033809 into base 455b4f095a1c71252bbebac4e1bc8b43ab9a2dae, 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 db73d84694c4bdb187b1a73963d1d00506b9be8f && git checkout db73d84694c4bdb187b1a73963d1d00506b9be8f
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 455b4f095a1c71252bbebac4e1bc8b43ab9a2dae 1777fb2d2cdf6ff6057a9f53ed1bafb023033809 && git checkout -B drift-repro 455b4f095a1c71252bbebac4e1bc8b43ab9a2dae && git merge --no-ff 1777fb2d2cdf6ff6057a9f53ed1bafb023033809

node scripts/docs-audit/affected-docs.mjs --json 455b4f095a1c71252bbebac4e1bc8b43ab9a2dae

⚠️ 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 455b4f095a1c71252bbebac4e1bc8b43ab9a2dae → pass the list as
args.docs, on the commit named under Which tree this was computed on.

objectstack-fleet · 2026-11-05T14:00:33Z

domain:server#5 · os-bill · session_01Utp6CYVV6fcAQrNTDQRvPb

维护者速读

改了什么：protocol.ts 门面上有 8 个公开方法（getDiscovery、findData、getData、cloneData，以及四个 *MetaItem）原来靠推断得出返回类型，现在都把返回类型写明在签名上。写的类型逐字取自它们今天推断出的 .d.ts。方法体一行没动。
为什么改：返回类型靠推断时，方法体一搬走，.d.ts 就会按新位置重新推断，所以这些方法只能留在门面上。写明之后，类型就不再取决于方法体放在哪里，后面才搬得动。
风险与回滚：没有行为变化，公开的 index.d.ts 和 index.d.cts 改前改后逐字节相同。代价是 getDiscovery 等方法的签名把结构写死了：以后 spec 改了发现响应的形状，这里要手工同步，由类型检查兜底。回滚只需撤掉本 PR。
先看：packages/metadata-protocol/src/protocol.ts 里 getDiscovery 的新签名；scripts/facade-delegation-registry.json 里改了理由的 8 行。
两分钟验证：运行 pnpm --filter @objectstack/metadata-protocol exec vitest run src/protocol.facade-door-return-types.pin.test.ts，预期 9 条全绿。
需要你做的：无，席位落地。

席位意见：同意落地，作为 #30054 的第一部分。方法体搬进 facet 现在做不了，因为 codemod 不能在已拆好的文件上重跑，已另立工具卡 #30518。engine.ts 那一半排在 #30055（PR #30463）之后，由同一线程续做。

席位核对

Head 1777fb2d2cdf6ff6057a9f53ed1bafb023033809 · 2026-11-05T14:00Z

形态: step 1 of the order's protocol.ts half. Eight doors carry spelled return types, the bodies stay, and the eight registry rows keep their entries with a rewritten reason. The engine.ts half is not touched (serial behind refactor: sweep the #4918 as any sites in engine.ts's six erasure-pinned methods so the codemod can move them (about 550 lines) #30055, per the Claim).
前提实测: the public index.d.ts / index.d.cts are byte-equal to base a1d0b1ee9 (empty diff, re-taken after feat(spec,metadata-protocol): the publish receipt names the rows a seed created and the rows it only matched #30427 widened publishMetaItem). The pin goes red on main for 8 of 9 cases, and was ablated once.
门禁 check-runs: in progress at this head. Auto-merge waits on the required checks. check-governed-merges.mjs --pr 30516 reports NOT governed (+251 / −16).
接受的偏差: step 2 (moving the bodies) is not done. The dev measured that the codemod refuses its own output and that --verify no longer re-proves the split (79/85, 71/78). It is filed as codemod-split-protocol: add a pass that moves a member of the landed protocol.ts facade into its facet (it refuses its own output, and the split no longer re-proves from its #29985 base) #30518.
范围外去向 + Skills-docs:: codemod-split-protocol: add a pass that moves a member of the landed protocol.ts facade into its facet (it refuses its own output, and the split no longer re-proves from its #29985 base) #30518. Skills-docs: none, since there is no skill text for an internal signature.
落地条款: Part of #30054. refactor: give the inferred-return-type public methods on the engine.ts and protocol.ts facades explicit return types (.d.ts unchanged), so the codemod can move their bodies #30054 stays claimed for the engine.ts half, Blocked-by: #30055. Non-governed, Clause-②: no, landed by the seat.

claude added 7 commits November 5, 2026 12:23

refactor(metadata-protocol): spell the inferred return types of the e…

6e3d614

…ight protocol.ts doors kept on the facade Claude-Session: https://claude.ai/code/session_01Utp6CXZTh9qvT24wTN6dd6 Co-authored-by: Claude <noreply@anthropic.com>

test(metadata-protocol): pin the eight facade doors' spelled return t…

24ba36f

…ypes Claude-Session: https://claude.ai/code/session_01Utp6CXZTh9qvT24wTN6dd6 Co-authored-by: Claude <noreply@anthropic.com>

chore(scripts): the eight protocol.ts door rows say their return type…

80bec6d

… is spelled and why the body stays Claude-Session: https://claude.ai/code/session_01Utp6CXZTh9qvT24wTN6dd6 Co-authored-by: Claude <noreply@anthropic.com>

chore(changeset): metadata-protocol patch for the spelled door return…

be02383

… types Claude-Session: https://claude.ai/code/session_01Utp6CXZTh9qvT24wTN6dd6 Co-authored-by: Claude <noreply@anthropic.com>

Merge remote-tracking branch 'origin/main' into claude/project-thread…

63a6264

…-alkkr9

Merge remote-tracking branch 'origin/main' into claude/project-thread…

5c255a7

…-alkkr9

refactor(metadata-protocol): publishMetaItem's spelled type carries t…

1777fb2

…he seed receipt's landed rows from main Claude-Session: https://claude.ai/code/session_01Utp6CXZTh9qvT24wTN6dd6 Co-authored-by: Claude <noreply@anthropic.com>

github-actions Bot added the size/m label Nov 5, 2026

objectstack-fleet Bot mentioned this pull request Nov 5, 2026

refactor: give the inferred-return-type public methods on the engine.ts and protocol.ts facades explicit return types (.d.ts unchanged), so the codemod can move their bodies #30054

Open

github-actions Bot added documentation Improvements or additions to documentation tests tooling Fix lands in tooling, not a product package — enters pm:queue only with Unblocks: or a named surface labels Nov 5, 2026

objectstack-fleet Bot mentioned this pull request Nov 5, 2026

codemod-split-protocol: add a pass that moves a member of the landed protocol.ts facade into its facet (it refuses its own output, and the split no longer re-proves from its #29985 base) #30518

Open

objectstack-fleet Bot marked this pull request as ready for review November 5, 2026 14:01

objectstack-fleet Bot enabled auto-merge November 5, 2026 14:01

objectstack-fleet Bot added this pull request to the merge queue Nov 5, 2026

Merged via the queue into main with commit 43faa22 Nov 5, 2026
49 checks passed

objectstack-fleet Bot deleted the claude/project-thread-alkkr9 branch November 5, 2026 15:39

This was referenced Nov 5, 2026

refactor(objectql): spell the eight ObjectQL facade methods' inferred return types and move five bodies into their facets (.d.ts byte-equal) #30571

Merged

[PM seat] domain:server · seat 5 — ⏳ vacant #28677

Open

Navigation Menu

Repository navigation

refactor(metadata-protocol): spell the inferred return types of the eight protocol.ts doors the facade keeps (.d.ts byte-equal) - #30516

refactor(metadata-protocol): spell the inferred return types of the eight protocol.ts doors the facade keeps (.d.ts byte-equal)#30516
objectstack-fleet[bot] merged 7 commits into
mainfrom
claude/project-thread-alkkr9

objectstack-fleet Bot commented Nov 5, 2026

Uh oh!

github-actions Bot commented Nov 5, 2026

Uh oh!

objectstack-fleet Bot commented Nov 5, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

objectstack-fleet Bot commented Nov 5, 2026

维护者速读

What changes

Tests

Acceptance notes

Verification

Uh oh!

github-actions Bot commented Nov 5, 2026

📓 Docs Drift Check

Uh oh!

objectstack-fleet Bot commented Nov 5, 2026

维护者速读

席位核对

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant