[objectstack-fleet]

Requested by Yibo Wang · project thread

Fixes #30051

维护者速读

• 改了什么：scripts/codemod-split-engine.mjs 改为每个 facet 只建一个共享 host（每个引擎实例一份，首次调用时由类的 static 块安装的工厂建成，存在新模块 engine-facet-hosts.ts），类上的 stub 从「每次调用现建一个 host 字面量」变成一行 Facet.x.call(xHost.of(this), …)。从 base 重新生成，生成物未手改。engine.ts 14,140 → 13,548 行（−592）。protocol.ts 不动：它的 codemod 存根本来就走共享的 protocolHost(this)，没有可压缩的。
• 为什么改：维护者在 refactor(objectql): generate the engine.ts section split with a deterministic codemod #30012 上要求进一步压缩 engine.ts（「我觉得文件还是太长，还有进一步的拆分优化空间吗」「可以后续立卡处理」），本卡是其中的 stub 压缩一项。
• 风险与回滚：只改 stub 和新增 host 模块，161/161 方法体、146/146 顶层声明逐字节不变，撤销拆分逐字节还原 base engine.ts；打包后 6 个 .d.ts 与 main 逐字节相同；objectql 测试 base 547 文件/10,833 = head；回滚就是 revert。
• 先看：① packages/objectql/src/engine-facet-hosts.ts（FacetHost 缓存，78 行）；② engine.ts 类末尾第二个 static 块（16 个 host 工厂）；③ codemod 里的 hostsTexts / stubBody 和 verify 新增的 stub 与 host 校验。
• 两分钟验证：pnpm install --frozen-lockfile 后运行 node scripts/codemod-split-engine.mjs --verify --base c2d353d2，应看到 161/161 moved bodies identical、23245 -> 13548 lines，退出码 0；--self-test 应通过 68 例。
• 需要你做的：改动共 1,996 行（未超过 3,000 行线），但按席位裁决本 PR 保持草稿，在您定的窗口里落地。

Clause-②: no
Metadata-protocol: none

What changes

• scripts/codemod-split-engine.mjs. Each facet's host is now built ONCE per engine instead of once per call.
  • hostsTexts writes a new module, engine-facet-hosts.ts. It holds FacetHost, a WeakMap cache keyed by engine with a factory slot, and one exported instance per facet module (actionsHost, cascadePlanningHost, …, 16 in all). The module imports types only, so it forms no evaluation cycle and is evaluated before the class whichever module loads first. This matters because 4 facet modules import ObjectQLStatics from engine.ts by value, so a cache inside a facet module could be in its temporal dead zone when the class's static block runs.
  • A second static block at the end of ObjectQL installs each facet's factory: xHost.install((engine) => ({ … })). The factory forwards each member as the per-call literal did. A method is a closure called on the engine at call time (m: (...a) => engine.m(...a)), so a spy or subclass override installed later is still reached. A field or accessor is a getter, and a field a body assigns also gets a setter. The host is the facet's whole host interface (ActionsHost and so on), which satisfies every body's Pick. A static block adds no class member, so the .d.ts does not move.
  • stubBody writes return Facet.x.call(xHost.of(this), …args); (a generic method still calls its body instantiated with its own type parameters). A stub whose body reads no member is unchanged.
  • A facet host can be told apart from a per-call literal only by identity across calls. No moved body can observe that: a body that reads this bare already stays on the class (bare-this).
  • verify now also checks that (1) every stub equals the generated one-call stub for its method, facet and host, (2) engine-facet-hosts.ts equals the generated text for the host interfaces on disk, and (3) the install block equals the generated block. Each member is forwarded by its BASE class kind: a method as a closure, anything else as a getter, plus a setter when the interface does not mark it readonly. The undo drops the block and the import.
  • Generation refuses when engine.ts already binds a host name, or when a moving method has a parameter named after its facet's host.
  • --self-test: 68 cases in 6 batteries. "facets, statics and docblocks" goes from 11 to 17 cases, and its floor is raised to 17. The new refusals: a stub handing another facet's host, an edited host module, and a written field's setter left out.
• The regenerated split. --write on engine.ts at c2d353d2 (main's last unsplit engine.ts; nothing has touched engine*.ts since refactor(objectql): generate the engine.ts section split with a deterministic codemod #30012 merged as 237f5137), unedited. The diff: engine.ts (145 stubs lose their literal, plus the install block and one import), the new engine-facet-hosts.ts, and the header prose of the 16 facet modules (the host paragraph). No body moved.
• protocol.ts / scripts/codemod-split-protocol.mjs: no change. The card's premise does not hold for this file. Its 85 codemod stubs already reach their bodies through one shared host per instance, ProtocolClassHeadFacet.x(protocolHost(this), …) (protocol-host.ts, a WeakMap cache installed by the class's static block). That is the shape this PR gives engine.ts. grep -c 'const host: ThisParameterType' scripts/codemod-split-protocol.mjs reads 0. The per-call literals left in protocol.ts (164 stubs, 774 lines) are all hand-series stubs that the codemod did not write (see Acceptance notes).

Line counts

File	Before (main c23501b2)	After	Δ
packages/objectql/src/engine.ts	14,140	13,548	−592
packages/objectql/src/engine-facet-hosts.ts	—	78	+78
packages/metadata-protocol/src/protocol.ts	13,647	13,647	0

The card estimated about 1,000 lines off engine.ts. The measured figure is 592. The 145 per-call literals were 869 lines, and the install block adds back one line per host member (207 across 16 facets, plus 31 setters and 2 lines per facet). PR size: 847 additions + 1,149 deletions = 1,996 changed lines.

Tests

Proofs (all at head 73a7605 unless stated)

• node scripts/codemod-split-engine.mjs --verify --base c2d353d2: exit 0. 161/161 moved bodies identical (body, parameters, return type, async), 146/146 top-level declarations identical, every stub equals the generated one, the host module and install block are the generated ones, and the undo rebuilds base engine.ts byte for byte once 107 import bindings are pruned. engine.ts 23245 -> 13548 lines.
• Determinism: two --write runs from base engine.ts (sha256 dc5677f3…), one in a separate worktree, print the same output tree sha256 09c80319211a965b89820ab7bb650d74cf6aaaec0afc0afb9cd75f2b867e3554. The second worktree's regenerated tree equals the committed head (git status empty).
• .d.ts: packages/objectql/dist built at main (c23501b2) ×2 and at head ×2. All 6 declaration files (index, core, util-BWl1U61F, each .d.ts + .d.mts) are byte-identical base vs head. The public-surface reading (pubsurface.mjs from Codemod split: generate the objectql engine.ts split with a deterministic script, verified byte-identical #29986) passes base1=base2, head1=head2, base1=head1 and base2=head2, and its controls behave (a private member made public is caught, a public type change is caught, a private docblock edit is not).
• objectql test: base (main c23501b2) 547 files / 10,833 passed = head 547 / 10,833. test:repo: 1 file / 5 = 5.
• objectql typecheck (tsc + check:test-typecheck): exit 0.
• Built-dist smoke (ESM index.mjs and CJS index.js): two engines keep separate hosts (residualOwnerSource set on one reads undefined on the other), a host setter writes through (setDefaultBodyRunner first-wins true, then false).
• Facade gate node scripts/check-facade-delegation-only.mjs: exit 0, registry unchanged (2 facades, 60 exceptions). The engine.ts delegation kinds move from 217 host-literal stubs to 144 host delegations plus 73 host-literal stubs (the hand series). The new install block reads as a second static host factory.
• Durability census check-durability-degradation-log-level.mjs: base (main) and head output byte-identical (51 seams, 9 propagating; 101 read seams, 13 discriminated). --self-test exit 0.

Ablations (each red, then restored; file hash back to its HEAD blob)

Done through scripts/ablation-replace.mjs.

1. verify's stub check turned off: the self-test case "a stub handing another facet's host fails" goes red.
2. verify's host-module comparison turned off: "an edited host module fails" goes red.
3. verify's install-block comparison turned off: "a written field's setter left out of the host fails" goes red.
4. On the real tree, one engine.ts stub pointed at another facet's host: --verify --base c2d353d2 exits 1 with recordResidualOwner: its stub is not the generated one-call stub.

Acceptance notes

• The hand-series stubs keep their per-call literals. In engine.ts that is 73 stubs (454 lines; the [maintainer] refactor(objectql): split src/engine.ts (23,903 lines, +7,501 in 30 days) along its ObjectQL seams, one move-only slice per PR #25522 hand modules). In protocol.ts it is 164 stubs (774 lines; the [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 hand modules). The codemods do not write those stubs, and this card's ruling is codemod-only. The same mechanism would apply (route them through the facet hosts or protocolHost, after widening ProtocolHost). By arithmetic, not a generated run, that is about −400 lines in engine.ts and about −700 in protocol.ts. Carrier: the seat, if it wants a card.
• No changeset, following refactor(objectql): generate the engine.ts section split with a deterministic codemod #30012 and pilot refactor(driver-sql): codemod pilot — generated, byte-identity-proved section split of sql-driver.ts (#29520) #29598 (skip-changeset): the behaviour and the published declaration files do not change.

Verification

Local, at head 73a7605b:

• npx turbo run build --concurrency=2: 120/120 tasks, exit 0. pnpm lint: exit 0. objectql typecheck: exit 0.
• node scripts/pm/dispatch-gates.mjs --commands: 64 families derived, each run, all exit 0. Three exited 3 on the first sweep because a prerequisite was missing (check-plugin-teardown-shape --self-test needs the pinned fixture commit fetched; check:dual-build-cjs-loads and check:lean-entry-closure need the full build). Each passed when rerun after its prerequisite was in place. --ran: 64 derived, 64 run, 0 NOT-MEASURED, 0 UNRUN.
• Run by hand, outside the derivation: check-facade-delegation-only.mjs (exit 0, registry unchanged), check-durability-degradation-log-level.mjs (base = head output), codemod-split-engine.mjs --self-test (68 cases).
• Declared to CI: the full lint workflow battery, core test:repo, and dogfood (the title has no ! and there is no narrowing arm).

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. (skip-changeset, see above)
• 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.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/objectql, touching 268 documentable anchor(s). ⚠️ 16 changed file(s) yielded no anchor (packages/objectql/src/engine-actions.ts, packages/objectql/src/engine-cascade-planning.ts, packages/objectql/src/engine-compatibility-section.ts, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

28 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 d79eecfe5b78598f9117726b542615ca2332d58f.

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

What this run could not see

• 16 changed file(s) yielded no anchor (packages/objectql/src/engine-actions.ts, packages/objectql/src/engine-cascade-planning.ts, packages/objectql/src/engine-compatibility-section.ts, …) — pages documenting those are invisible to this run
• 1 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 80 pages)
• 20 name(s) were too generic to anchor anything (single lowercase words)
• 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 — 21 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 d79eecfe5b78598f9117726b542615ca2332d58f → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json d79eecfe5b78598f9117726b542615ca2332d58f

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

[objectstack-fleet]

domain:server#6 · os-support-ai · session_01WGufzibcN9oHa8kDbTTnL5

席位核对

Verdict: ACCEPT at head 73a7605b3ad6f41c02b5f9d08804f8dc6db51733 · 2026-11-04T12:45Z

• Shape: the engine.ts codemod now builds each facet's host once, as a generated host module plus an install block, instead of a per-call host literal. engine.ts goes from 14,140 to 13,548 lines (−592). The 869 literal lines come back as 207 host members and 31 setters. protocol.ts is unchanged at 13,647, because its 85 codemod stubs already use the shared protocolHost(this). So half of the card's premise was false, and codemod-split-protocol.mjs is untouched.
• Proofs (dev report 6630903193):
  • verify --base c2d353d2 exits 0: 161/161 bodies and 146/146 declarations. Every stub is the generated one-call stub, and the host module plus install block are generated.
  • Determinism: the same tree sha on two runs, and that tree equals the head.
  • .d.ts: 6/6 files byte-identical to main, and the public surface is EQUAL.
  • objectql 10,833 tests (= base), test:repo 5 = 5, typecheck 0.
  • The tooling: a structural gate that keeps a registered facade class delegation-only #30030 facade gate exits 0 with the registry unchanged, and the durability census base = head.
  • Build 120/120, pnpm lint 0, dispatch-gates 64/64 exit 0 with --ran 0 NOT-MEASURED. 4 ablations went red and were restored.
• Declaration: Clause-②: no, Metadata-protocol: none, skip-changeset, no runtime change. Reviewed as consistent.
• Window: 2,033 changed lines, which is under the 3,000-line human-merge bar. No other open PR touches packages/objectql/src/engine*. The maintainer asked for these follow-ups (refactor: compress the codemod facade stubs in engine.ts and protocol.ts — one shared host per facet instead of a per-call host literal (body-identical; about 1,000 lines off engine.ts) #30051, filed at their word), so the seat lands it on all-green.
• Accepted deviations: the harness-pinned branch claude/project-thread-uq12fq. The protocol half was a no-op, measured. Carried: the hand-series stubs still build per-call literals (engine.ts 74, about −400; protocol.ts 164, about −700, by arithmetic). That folds into refactor: move the private docblocks of the hand-series stubs into their hand modules — about 1,900 lines off engine.ts (86 stubs) and about 4,000 off protocol.ts (157 stubs) #30053's hand-module pass.
• Landing: on all-green at this head, the seat sends pr_ready + automerge_enable through the relay.