[objectstack-fleet]

Requested by Bill · project thread

domain:server#5 · os-bill · session_01Utp6CYVV6fcAQrNTDQRvPb

维护者速读

• 改了什么：engine.ts 门面上 8 个因返回类型靠推断而留在类上的 ObjectQL 方法把返回类型写明在签名上（逐字取自今天的 .d.ts）；其中 getStatus、triggerHooks、setDatasourceMapping、init、destroy 五个再用 codemod 第四遍（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 的 --members）把方法体搬进各自的 facet 模块，类上只留一行转调；allow-list 删掉这 5 行。
• 为什么改：返回类型写明后，方法体放在哪都不会改变公开类型，门面才能只剩转调（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 第二半，第一半是已合并的 refactor(metadata-protocol): spell the inferred return types of the eight protocol.ts doors the facade keeps (.d.ts byte-equal) #30516）。
• 风险与回滚：没有行为变化；@objectstack/objectql 的三个公开 .d.ts 改前改后逐字节相同，codemod 的撤销证明逐字节通过。回滚即撤本 PR。
• 先看：packages/objectql/src/engine.ts 里 init / destroy 的新 stub，再看 engine-secrets-and-routing.ts 里搬进来的 init 方法体。
• 两分钟验证：node scripts/codemod-split-engine.mjs --members --verify --base 405373c08 预期 exit 0、“5 moved method(s) … does rebuild the base … byte-for-byte”；node scripts/check-facade-delegation-only.mjs 预期 exit 0、56 条具名例外。
• 需要你做的：无，席位落地。registerApp、registerDriver、registerHook 三个 codemod 拒绝搬，留在类上（见 Acceptance notes）。

Part of #30054 (the engine.ts half: all eight return types spelled, five bodies moved; three engine.ts bodies and the eight protocol.ts bodies stay, see Acceptance notes)

Clause-②: no — the published index.d.ts, core.d.ts and the shared declaration chunk of @objectstack/objectql are byte-equal before and after, so no exported member changes.
Metadata-protocol: none
Skills-docs: none — an internal refactor of eight method signatures and five method bodies' location; no published type or behaviour changes, and no skill text names them.

What changes

• Return types (engine.ts). registerApp, registerHook, registerDriver, init, triggerHooks, destroy, setDatasourceMapping and getStatus declare their return type, copied from the line the base build printed for each in dist/util-*.d.ts (the ObjectQL class), re-indented to the file's two spaces. getStatus spells name: "data" with the printer's double quotes, which the declaration emit keeps.
• Moves (--members). node scripts/codemod-split-engine.mjs --members getStatus,triggerHooks,setDatasourceMapping,init,destroy --write: getStatus and triggerHooks go to engine-hooks-and-functions.ts, setDatasourceMapping and init to engine-secrets-and-routing.ts, destroy to engine-migration-state.ts. Each method stays on the class with its docblock and signature as a one-call stub. Nothing generated is edited by hand.
• Registry. The five moved members' rows are deleted (the gate refuses a row whose member is already a delegation). The three rows that stay keep 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 and say why each body stays.
• Pin. engine.facade-return-types.pin.test.ts parses engine.ts and requires each of the eight methods to carry its exact return type text.
• Changeset. @objectstack/objectql patch: the declarations are byte-equal, but the shipped source maps move.

Tests

• New pin: 9/9 at head. On origin/main's engine.ts (restored unstaged, then put back from HEAD, git diff HEAD empty) 8 of 9 fail, one per method.
• Ablation (once, scripts/ablation-replace.mjs): init's stub annotation removed, anchor 1 → 0, blob 2fa8f560 → 20c28b40; the pin goes 1 failed / 8 passed, naming init; restored to the HEAD blob with git diff HEAD empty.
• The facade gate is the pin for the moves: with the five rows deleted it is red on origin/main (five members with a body and no row) and green at head.
• @objectstack/objectql full suite: 554 files passed, 11,019 tests passed at head 2ea0deb9d (and the same counts before the branch moved onto c23eafa88).
• pnpm --filter @objectstack/objectql typecheck exit 0 at head.

Acceptance notes

• Three bodies the --members pass will not move. registerApp and registerDriver: the pass refuses with "engine-registration.ts: its header is not as the first pass wrote it" (that module's header was edited by hand when isExternalWriteForbidden was written there, Effective object permissions ignore the external write gate, so the console offers New, Import, Edit and Delete on a read-only external object #30370). registerHook: the pass writes the move but its undo proof fails ("undoing the moves out of engine-hooks-and-functions.ts does not rebuild its base (first difference at line 44)", in that module's import block). Each is measured alone and together; the order lands only what is mechanical, so their rows stay with the reason.
• What 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 still owes. engine.ts: registerApp, registerDriver, registerHook (types spelled, bodies stay). protocol.ts: the eight doors typed by refactor(metadata-protocol): spell the inferred return types of the eight protocol.ts doors the facade keeps (.d.ts byte-equal) #30516, whose move waits on the protocol codemod's missing facade pass (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). The seat decides whether those eleven rows move to 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 or a sibling card and the card closes, or the card stays open.
• A spelled type is now the published shape (as on refactor(metadata-protocol): spell the inferred return types of the eight protocol.ts doors the facade keeps (.d.ts byte-equal) #30516): a later change to what one of these methods returns edits its signature too, because a wider body return is not refused and the .d.ts prints the signature.
• The branch. refactor(metadata-protocol): spell the inferred return types of the eight protocol.ts doors the facade keeps (.d.ts byte-equal) #30516 was squash-merged from this same branch. A force-push to restart it from main was refused in this session, so the branch merges origin/main over refactor(metadata-protocol): spell the inferred return types of the eight protocol.ts doors the facade keeps (.d.ts byte-equal) #30516's old commits (the merged tree equals main exactly: git diff origin/main was empty before this PR's commits), and the PR's commit list shows those old commits. The diff is this PR's seven files only.

Verification

Head 2ea0deb9d, base origin/main c23eafa88.

Declaration-file proof

• Base: origin/main c23eafa88's engine.ts and its three facet modules restored into the head tree, turbo run build --filter=@objectstack/objectql..., core.d.ts, index.d.ts and util-DJB5AN6K.d.ts copied aside (byte-equal to the first base build at 8e5fabe58, from which the types were copied).
• Head: pnpm build in packages/objectql (tsup with DTS, then check-dts-emitted); cmp against the base copies: all three byte-equal (util-DJB5AN6K.d.ts sha256 7f1e928b2f3aceac…). The same held after the annotation commit alone, before the move.
• The diff of the emitted declarations is empty.

Codemod proof

• --members getStatus,triggerHooks,setDatasourceMapping,init,destroy plan, then --write: output tree sha256 ebff07ef5c50e416… both times; "5 moved method(s) … engine.ts 11321 -> 11223 lines; undoing the moves does rebuild the base engine.ts and its modules byte-for-byte once the 7 import binding(s) only moved bodies read are pruned from the base".
• --members --verify --base 405373c08 (the annotation commit, on this base) exit 0 with the same reading.

Gates

• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at head 2ea0deb9d: 70 derived commands (change set: 7 paths, +262 / -168, under the 3,000 threshold). Each ran with its exit code recorded before any pipe; all 70 exit 0. --ran reconciles 70 derived, 70 run, 0 NOT-MEASURED, 0 UNRUN.
• node scripts/check-facade-delegation-only.mjs: "5 facade class(es) in 3 file(s) hold delegations only, 56 named exception(s)", exit 0. Against origin/main's tree (--root a detached c23eafa88 worktree, --registry this head's): exit 1, five problems, one per moved member.
• eslint --no-inline-config over the five changed source files exit 0 at head.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/objectql, touching 13 documentable anchor(s).

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

• content/docs/data-modeling/external-datasources.mdx (via datasourceMapping (symbol, a field of interface SecretsAndRoutingHost; a method of class ObjectQL), datasourceMapping (literal, a string literal in datasourceMapping; a string literal in setDatasourceMapping))
• content/docs/getting-started/quick-start.mdx (via datasourceMapping (symbol, a field of interface SecretsAndRoutingHost; a method of class ObjectQL), datasourceMapping (literal, a string literal in datasourceMapping; a string literal in setDatasourceMapping))
• content/docs/protocol/kernel/error-handling.mdx (via registerApp (symbol, a method of class ObjectQL))

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 80 pages)
• 2 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 db04e5ce581a92f349a532f52786c95acd7ec4ac → packageMentionDocs.

Which tree this was computed on

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

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

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

[objectstack-fleet]

domain:server#5 · os-bill · session_01Utp6CYVV6fcAQrNTDQRvPb

维护者速读

• 改了什么：engine.ts 门面上 8 个 ObjectQL 方法原来靠推断得出返回类型，现在都写明在签名上，类型逐字取自今天的 .d.ts。其中 getStatus、triggerHooks、setDatasourceMapping、init、destroy 五个再用 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 的 codemod --members 把方法体搬进各自的 facet 模块，类上只留一行转调，门面登记表删掉这 5 行例外。
• 为什么改：返回类型写明后，方法体放在哪里都不改变公开类型，门面才能只剩转调。这是 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 的 engine.ts 半边，protocol.ts 半边的第一步是已合并的 refactor(metadata-protocol): spell the inferred return types of the eight protocol.ts doors the facade keeps (.d.ts byte-equal) #30516。
• 风险与回滚：没有行为变化，@objectstack/objectql 的三个公开 .d.ts 改前改后逐字节相同，codemod 的撤销证明逐字节通过。代价同 refactor(metadata-protocol): spell the inferred return types of the eight protocol.ts doors the facade keeps (.d.ts byte-equal) #30516：以后这几个方法的返回形状变了，要手改签名。回滚只需撤掉本 PR。
• 先看：packages/objectql/src/engine.ts 里 init / destroy 的新转调；engine-secrets-and-routing.ts 里搬进来的 init 方法体；scripts/facade-delegation-registry.json 删掉的 5 行。
• 两分钟验证：运行 pnpm --filter @objectstack/objectql exec vitest run src/engine.facade-return-types.pin.test.ts，预期 9 条全绿；再运行 node scripts/check-facade-delegation-only.mjs，预期 exit 0、56 条具名例外。
• 需要你做的：无，席位落地。

席位意见：同意落地，作为 #30054 的 engine.ts 半边。registerApp、registerDriver、registerHook 三个方法体 codemod 搬不动，已另立工具卡 #30572；protocol.ts 的 8 个方法体等 #30518。这 11 行登记仍挂在 #30054 上，所以 #30054 保持打开，Blocked-by #30518 和 #30572，不在本 PR 里改挂登记表。

席位核对

Head 2ea0deb9d1f7dcf0aca872e2b5543e96e372fb9a · 2026-11-05T16:27Z

• 形态: the order's engine.ts half. Eight return types are spelled; five bodies move with 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 pass; three bodies stay with a rewritten reason. 7 files, +262 / −168.
• 前提实测: the seat read the three-dot diff against a fresh origin/main. Exactly five registry rows are deleted (init, triggerHooks, destroy, setDatasourceMapping, getStatus), and each of them is now a one-call stub into its facet in engine.ts. The .d.ts byte-equality, the --members --verify undo proof, the red-on-main pin and the one ablation are the dev's readings (os-dev-report 6663232806). The seat's own run of the facade gate here stopped at exit 3 (no node_modules, nothing measured), so CI's gate run carries it.
• 门禁 check-runs: in progress at this head. Auto-merge waits on the required checks. check-governed-merges.mjs --pr 30571 reports NOT governed (+262 / −168).
• 接受的偏差: three of the eight engine.ts bodies are not moved, because the --members pass refuses or cannot prove them; they are filed as codemod-split-engine --members: move registerApp, registerDriver and registerHook out of the landed engine.ts facade (hand-edited engine-registration.ts header; registerHook's undo proof fails at the import block) #30572. The PR's commit list carries refactor(metadata-protocol): spell the inferred return types of the eight protocol.ts doors the facade keeps (.d.ts byte-equal) #30516's old commits, because a force-push restart was refused in the dev's session; the diff is this PR's seven files only.
• 范围外去向 + Skills-docs:: codemod-split-engine --members: move registerApp, registerDriver and registerHook out of the landed engine.ts facade (hand-edited engine-registration.ts header; registerHook's undo proof fails at the import block) #30572 (three engine.ts bodies) and 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 (eight protocol.ts bodies). Skills-docs: none, since there is no skill text for an internal signature or a body's location.
• 落地条款: 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 open with Blocked-by: #30518, #30572, since its 11 registry rows still name it. Non-governed, Clause-②: no, landed by the seat.