[objectstack-fleet]

Requested by Yibo Wang · project thread

Part of #29985

维护者速读

• 改了什么：新增 codemod scripts/codemod-split-protocol.mjs，按 ruling E（E1 host 模式）把 ObjectStackProtocolImplementation 的 61/284 个方法体移入 9 个分节模块，类上只留签名、docblock 和一行 stub。生成文件未手改。按裁决 6597555122 第 3 点，8 个按路径读 protocol.ts 的普查测试和 check-durability-degradation-log-level 跟随代码读新模块（host. 与 this. 同义），ADR 锚点为 3 个接收受管代码的模块各加一条。
• 为什么改：[Decision] Large source files: replace the hand-cut split with a script-generated split per file, so the remaining monoliths split in days, not months #29465 大文件拆分的 Phase 0，在试点 refactor(driver-sql): codemod pilot — generated, byte-identity-proved section split of sql-driver.ts (#29520) #29598 之后做 protocol.ts。
• 风险与回滚：纯搬移。61/61 方法体逐字节相同；撤销拆分逐字节还原 base 的 protocol.ts 和 protocol-host.ts（只剩 80 个仅被移出方法体读的 import，证明从 head 重新推出这次修剪）。测试计数 base 22,339 → head 22,340（多 1 条非空检查），门禁读数 base = head，打包 .d.ts 按 6441032442 B 第二归一化相等。回滚即 revert。
• 先看：① 下方「按路径读 protocol.ts 的读者」表；② codemod 的 STAY_REASONS（尤其 inferred-return-type，.d.ts 对比抓到过它）；③ check-durability-degradation-log-level.mjs 的两处 host 调用改动和 3 条自测。
• 两分钟验证：pnpm install --frozen-lockfile 后运行 node scripts/codemod-split-protocol.mjs --verify --base 9049be26，预期 61/61 moved bodies restore to the base body exactly、23135 -> 15318 lines，退出码 0；node scripts/codemod-split-protocol.mjs --self-test 42 例通过。
• 需要你做的：一个读数待定：试点的 13,000 行门槛这里没有达到（15,318 行），见下方「未达到的读数」。超过 3,000 行，需您批准后在您定的窗口落地；本 PR 保持草稿。

Clause-②: no
Metadata-protocol: none

What changes

• scripts/codemod-split-protocol.mjs (new): plans, writes and proves the split. It reuses packages/metadata-protocol/scripts/host-split.mjs (E1's rewrite set: this.x → host.x, a private static → host.x) for every move, so a moved function has the shape of the 87 existing protocol-*.ts modules.
  • Sections are named by their first member (SECTION_ANCHORS, after [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's section table); the five sections the hand series already emptied write no module.
  • A method stays when moving it would change what the published .d.ts says, what a by-path reader sees, or when the move cannot be undone byte for byte. Measured on this file (a method can carry several): already-moved 190, no-yield 18, inferred-return-type 8, closed-set 4, name-taken 3, no-host-read 2, host-entry-predicate 1.
  • Three rules were found by building the output, not by reading it:
    • inferred-return-type (the pilot's rule, back): without it getDiscovery's printed return type lost the @deprecated docblock on apiName.
    • no-host-read: a body that reads no member would leave host unread (noUnusedParameters).
    • host-entry-predicate: a forwarding closure drops a type predicate (TS2322).
  • The imports only the moved bodies read are pruned from protocol.ts (noUnusedLocals); a JSDoc {@link X} counts as a read, as tsc counts it. The proof recomputes the prune from the head's own references.
  • --self-test: 42 cases in 6 pinned batteries, each proof fed an input it must refuse.
• The generated split: --write on base 9049be26, unedited. protocol.ts and protocol-host.ts change; new: protocol-class-head.ts, protocol-discovery-and-bases.ts, protocol-search-and-cache.ts, protocol-write-gates.ts, protocol-registry-hydration.ts, protocol-save.ts, protocol-history-and-publish.ts, protocol-package-commits.ts, protocol-diff-delete-load.ts. Nothing re-exports them.
• Readers widened (ruling 6597555122 point 3). These migrate path readers; they are not edits of generated output.
• scripts/check-durability-degradation-log-level.mjs:
  • A moved body's host.guard(error) reaches the class's guard through the HOST CALL rule isReadCall already follows.
  • A host.x() call resolves to the class member x first, even when the module declares x itself (that member's own moved body, whose extra host parameter failed the arity check and dropped rollbackToPackageCommit's seam).
  • FAILURE_PROPAGATION_SITES keys migrateStoredMetadata and duplicatePackage by their new modules.
  • Three new self-test rows; the read-seam floor goes 67 → 70.
• scripts/adr-anchors/: three new entries. protocol-registry-hydration.ts gets ADR-0029 and ADR-0126, protocol-diff-delete-load.ts gets ADR-0029, and protocol-save.ts gets ADR-0005 and ADR-0087. Each carries the host entry's own invariant paragraphs, in the pilot's shape. The host entry stays.

Verification

Reading	Base 9049be26	Head
protocol.ts lines	23,135	15,318 (8,207 body lines out, 244 stub lines in)
Byte-identity		61/61 bodies identical; host-split check 61/61 (366 member, 41 private static, 0 constructor rewrites); undo rebuilds both base files
Determinism		output tree sha256 af32bb253715742dca426de0417e7d3ccf91ba461c4b69637e2289756cdd6916 on two runs; regenerating on base reproduces the committed tree with zero diff
metadata-protocol typecheck	exit 0	exit 0
metadata-protocol test	312 files, 22,339 passed, 26 skipped	312 files, 22,340 passed, 26 skipped (+1: the reconcile census's non-vacuity row)
check:durability-log-level	51 seams (9 propagating), 102 read seams (13 discriminated)	the same
core / objectql / spec test:repo		94, 5, 1,524 passed
pnpm lint		exit 0
dispatch-gates --commands at head 32c7bc04		73 derived, 73 run, every exit 0; --ran: 0 NOT-MEASURED, 0 UNRUN

.d.ts: ruling 6441032442 item 1, second normalisation

The reading uses the dtsnorm reader over the built dist/ of base and head (index.d.ts, index.d.cts).

Reading	index.d.ts	index.d.cts
raw	differs (one union's member order, in getDiscovery's printed type)	differs (the same)
union order (6348891160 item 1)	equal	equal
second normalisation	equal	equal
declared surface	equal	equal

A positive control plants a private → public change and is caught (normalised and surface both differ). On the previous generation, which had no inferred-return-type rule, the same reading refused the split.

Readers of protocol.ts by path

Reader	Now
protocol.recovery-doors-mutation-projector.test.ts, protocol.recovery-doors-emit-mutation.test.ts	counts over protocol.ts plus every split module, (this|host).; the receive-path body is read in protocol-class-head.ts
protocol.object-registry-write-through-spelling.test.ts	caller sets and the 'objects' scan over every split module
protocol.register-item-call-sites.test.ts	every split module; moved sites keyed by file
protocol.lookup-artifact-item-call-sites.test.ts	already read every module; ten rows gain file
protocol.read-verb-canonical-fold.test.ts	a wrapper's moved body is followed; the signature is read off the class member
protocol.view-expansion-reconcile-call-sites.test.ts	protocol.ts plus the codemod's modules (see Findings)
protocol.hydrate-overlay-canonical-type.test.ts	the assert is read in protocol-registry-hydration.ts
check-durability-degradation-log-level	see above; base = head
ADR anchors	three entries; check:adr-anchors exit 0
protocol.query-transport-dialect.test.ts, core second-object-read-exposure pin, objectql core-boundary ratchet, spec liveness / absence pins, check-filter-alias-parity, check-nul-bytes, check-system-context-census	unchanged (their text stayed in protocol.ts, or they read the directory)

Every widened census was ablated once: a moved call renamed, an await dropped, a fold argument changed, or an assert code changed. Each one fails at head. A one-character hand edit in protocol-save.ts makes --verify exit 1.

Not met: the line bar

protocol.ts ends at 15,318 lines, against the 13,000 that ruling 6591753301 item 3 set for the pilot and carried to the next three files. What is left is mostly docblocks and signatures that stay on the class by E1's design: the .d.ts prints them. Another 190 methods are already stubs from the hand series. Reaching 13,000 needs a decision the codemod cannot make, such as moving the docblocks, or a different decomposition. It is raised with the seat and is not hand-cut here.

Findings outside this PR

protocol-packageless-overlay-migration.ts (hand series) calls repository.delete( on sys_metadata. That call is outside the #23198 stored-row census, which reads only the repo. spelling. Widening the census to every module would have turned it red, so the census reads the codemod's modules and the hand-series module stays outside, as before. This was reported to the seat.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WGufzgddMBbTQd9yVo4Yuz

[github-actions]

📓 Docs Drift Check

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

75 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 0b99c2b1645b101459b1dd9fd4fecdf996194a76.

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

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: sys_user (literal, 49 pages)
• 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 0b99c2b1645b101459b1dd9fd4fecdf996194a76 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 1c98876e6d60e1593a6a1f9f1a593f722b81b80d — the merge of head 32c7bc04abfde7f2bf4962e70ffde52da50f3d1a into base 0b99c2b1645b101459b1dd9fd4fecdf996194a76, 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 1c98876e6d60e1593a6a1f9f1a593f722b81b80d && git checkout 1c98876e6d60e1593a6a1f9f1a593f722b81b80d
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 0b99c2b1645b101459b1dd9fd4fecdf996194a76 32c7bc04abfde7f2bf4962e70ffde52da50f3d1a && git checkout -B drift-repro 0b99c2b1645b101459b1dd9fd4fecdf996194a76 && git merge --no-ff 32c7bc04abfde7f2bf4962e70ffde52da50f3d1a

node scripts/docs-audit/affected-docs.mjs --json 0b99c2b1645b101459b1dd9fd4fecdf996194a76

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