[objectstack-fleet]

Requested by 田騏 · project thread

domain:server#2 · marchtian · session_017ihL2fL8RrJDkowuFhXUPG

Refs #30020

Clause-②: no
Metadata-protocol: none
Skills-docs: none — an internal move inside @objectstack/objectql; nothing a metadata author writes changes

维护者速读

• 改了什么:用 scripts/codemod-split-engine.mjs --members find,findOne 把 ObjectQL 的 find 和 findOne 两个方法体搬进已有的 engine-find.ts facet,类上只留一行委托桩(签名和 docblock 原样保留);同时删掉登记表里这两行例外(19 → 17)。这是 refactor: move shared state out of the protocol.ts and engine.ts facades into state-owning facets, so the hot bodies left on the class can become delegations (ruling 6624345766) #30020 §5 系列的 E2,codemod 本身一行没改。
• 为什么改:refactor: move shared state out of the protocol.ts and engine.ts facades into state-owning facets, so the hot bodies left on the class can become delegations (ruling 6624345766) #30020 要把门面类剩下的例外行换成委托,让 engine.ts 继续变小(11,111 → 10,739 行)。这两个方法体把引擎本身交给钩子(ql: this),按规则 A 改读宿主的 facade 端口。
• 风险与回滚:纯搬移,运行时行为不变。撤销证明逐字节通过;@objectstack/objectql 的三个公开 .d.ts 与 main 构建结果逐字节相同。回滚即 revert 本 PR。
• 先看:packages/objectql/src/engine-find.ts 的 FindHost 接口与 ql: this.facade 两处;packages/objectql/src/engine.ts 的 find / findOne 桩和 findHost 安装行;scripts/facade-delegation-registry.json。
• 两分钟验证:node scripts/codemod-split-engine.mjs --members --verify --base origin/main 预期 exit 0,输出 “2 moved method(s) (find, findOne); engine.ts 11111 -> 10739 lines; undoing the moves does rebuild the base … byte-for-byte”。
• 需要你做的:无,席位落地。

What changes

• The move (E2 of the refactor: move shared state out of the protocol.ts and engine.ts facades into state-owning facets, so the hot bodies left on the class can become delegations (ruling 6624345766) #30020 §5 order). node scripts/codemod-split-engine.mjs --members find,findOne --write on main 5f0037449. Both bodies move into packages/objectql/src/engine-find.ts, the facet that already holds their read helpers (requireFindOnePredicate, reportFindFailure); no new module. The stubs, the FindHost members, the host factory entries and the imports are the codemod's own output; nothing was hand-edited.
  • find and findOne stay on the class with their docblocks and signatures byte for byte; only async is dropped from the stub, as every stub of the series does. Each is return FindFacet.X.call(findHost.of(this), …).
  • Each body handed the engine itself into its hook context (ql: this). Under rule R1 that reads ql: this.facade, and FindHost gains the readonly facade: ObjectQL port with its docblock, plus a facade: engine install entry.
  • 19 import bindings only the moved bodies read leave engine.ts (the prune the proof recomputes).
• scripts/facade-delegation-registry.json: the find and findOne rows (#30020, bare-this) are removed; nothing added. Exceptions 19 → 17; engine.ts's #30020 rows left: update, insert, delete, constructor, [SEED_USER_GRANTS], transaction.
• .changeset/30020-objectql-find-findone-facet.md: @objectstack/objectql patch (source maps ship), the two declaration lines in its body.
• Anchors repointed (patch round, 8c46a17a83): the move pruned three import bindings from engine.ts that evidence anchors named. packages/spec/liveness/query.json (query.fields → engine-top-level.ts#planFormulaProjection; query.top → engine-top-level.ts#ENGINE_QUERY_SLOTS and engine-find.ts#foldEngineOptionAliases, each row's note dated) and docs/qa/platform-checklist/areas/api-backend.json (engine-top-level.ts#applyFormulaPlan). Anchor text only, same precedent as refactor(objectql): move the last 28 hand-series private docblocks out of engine.ts with the codemod's third pass (slice 2 of 2) #30415 and fix(metadata-protocol): move findData into its facet; host-split refuses a method read as a value, so getDiscovery stays #30838; the changeset adds '@objectstack/spec': patch because liveness/ ships in its files[]. These two files are outside the original claim surface; the seat amended the claim (6707298150). The red this fixed: Test Core (2/8), packages/spec/scripts/liveness/evidence.test.ts "every local path#symbol anchor names a symbol its file contains".
• Not changed: scripts/codemod-split-engine.mjs. E2 needs no capability E1 did not ship.

Rules applied (reconstructed)

The previous seat's design.md (R1–R7, H2) is not reachable from this seat. The rules below are rebuilt from the card's design comment 6677924765, ruling 6687865760 and PR #30987's body.

• Ruling A (6687865760): the facade stays the sole state owner. No field moves; the facet reaches state through its host.
• R1, the identity port (refactor(scripts,objectql): codemod-split-engine moves bodies that hand the engine on through a facade host port, and computing hand-stub slots; move eight #30020 bodies #30987): a bare this a moved body hands on becomes this.facade. Two sites here, ql: this.facade in find's and findOne's hook contexts. This is the only rule E2 exercises.
• R3 (computed field keys), R4 (a name engine.ts exports) and H2 (--hand-slots): not reached. The plan asked for none of them and wrote no this[k] host access, no ./engine.js value import and no hand-slot move.
• R7: deferred to E6 by refactor(scripts,objectql): codemod-split-engine moves bodies that hand the engine on through a facade host port, and computing hand-stub slots; move eight #30020 bodies #30987, its only caller; not reached.
• R2, R5, R6: their numbering is not recoverable from the comments. The design comment lists the other smaller rules (constructor, symbol-keyed members, another instance's private write); none applies to these two bodies, and the codemod's plan named no stay reason for either.
• Docblock rule (first pass): a public method keeps its docblock on the class. Both members are public, so no docblock moved and the .d.ts stays byte-equal. (refactor(scripts,objectql): codemod-split-engine moves bodies that hand the engine on through a facade host port, and computing hand-stub slots; move eight #30020 bodies #30987's .d.ts delta came from private docblocks; there are none here.)
• Stop condition (the dispatch order): not hit. Neither body needed any edit beyond this → this.facade.

Tests

No test file changes: a byte-proven move with no behaviour change. The suites run unchanged against the moved bodies.

Acceptance notes

• .d.ts: byte-equal at base and head. This is stronger than refactor(scripts,objectql): codemod-split-engine moves bodies that hand the engine on through a facade host port, and computing hand-stub slots; move eight #30020 bodies #30987, which lost 83 lines of private docblocks from the shared chunk.
• Contract review: none owed for a byte-proven move with no surface change, per the series' standing note (6690792197); the seat decides.
• The series continues with E3 (constructor) after this lands.

Verification

All readings are at head df1ae02829, whose base is origin/main 5f0037449 (main had not moved when the PR opened).

Undo proof (byte-exact) and determinism

• node scripts/codemod-split-engine.mjs --members find,findOne --write: exit 0. Output tree sha256 5e6887d1e3d389d599d28d3ac70e4a8db35f0bd36232cf254bd24f9266220020, input sha256 4e979556f4ab17da5c087a435bb5bf56928d025ea3eaabe191ed99542c4f43a1 (= git show 5f0037449:packages/objectql/src/engine.ts | sha256sum). The plan-only run before it printed the same output sha256.
• node scripts/codemod-split-engine.mjs --members --verify --base origin/main on the committed head: exit 0. "undo proof: 2 moved method(s) (find, findOne); engine.ts 11111 -> 10739 lines; undoing the moves does rebuild the base engine.ts and its modules byte-for-byte once the 19 import binding(s) only moved bodies read are pruned from the base (ENGINE_FIND_OPTION_KEYS, ENGINE_QUERY_SLOTS, ENGINE_WIRE_ONLY_SLOTS, FindHookResultNotArrayError, FindOneHookResultNotRecordError, PLATFORM_PROVISIONED_COLUMNS, applyFormulaPlan, assertOrderByIsMaterializable, assertProjectionHasNoDottedPaths, assertProjectionNamesAField, isFindOneResultShape, mergeReadContext, planFormulaProjection, refuseProjectionOfUnknownColumns, rejectInternalFieldEvaluation, rowsWithSelectedColumnsAnswered, rowsWithoutFormulaWidening, withFileOwnerKey, withoutFormulaWidening)".
• File hashes: engine.ts base 4e979556… → head 9f090702…; engine-find.ts base 76b336ec… (476 lines) → head 5bfcb0a4… (910 lines).
• node scripts/codemod-split-engine.mjs --self-test: exit 0, 169 cases in 11 batteries.

Public declaration files

@objectstack/objectql built with pnpm --filter @objectstack/objectql build with the two source files at base 5f0037449, then at head. dist/core.d.ts (a8fd9093…), dist/index.d.ts (3a798237…) and dist/util-BK7LVy6k.d.ts (24ed9187…) are byte-equal: diff -r is empty, and the chunk hash itself does not change. Control: the stub's text, matched by the regex \.find\.call\(findHost\.of\(this\), occurs 0 times in the base dist/index.mjs and once in the head's.

Package suites and gates

• pnpm --filter @objectstack/objectql typecheck (tsc plus check:test-typecheck) and pnpm --filter @objectstack/objectql test, under os-verify-lock: VERDICT command-exit 0. Test Files 564 passed (564), Tests 11422 passed (11422).
• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at 8c46a17a83: 76 families (the anchor files add check:liveness and check:platform-checklist among others), all 76 exit 0, --ran 76/76, 0 NOT-MEASURED; evidence.test.ts 48/48. At df1ae02829: 66 families, all 66 exit 0. Two first answered exit 3 on prerequisites and were re-run once those were met: node scripts/check-plugin-teardown-shape.mjs --self-test needed a non-shallow clone (git fetch --unshallow), 48 cases pass; pnpm check:dual-build-cjs-loads needed every dist/ (pnpm build, 119 tasks, exit 0), 116 entry points across 71 packages load. --ran at df1ae02829: 66 derived, 66 run, 0 NOT-MEASURED, 0 UNRUN.
• Outside the derived set: pnpm check:facade-delegation-only exit 0 (17 named exceptions); node scripts/check-facade-delegation-only.mjs --self-test exit 0 (37 cases); pnpm lint exit 0.

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/objectql, @objectstack/spec, touching 58 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/spec/liveness/query.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

46 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 5f0037449256ccb0855e258ffc4fd4bff84d1a67.

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

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/liveness/query.json) — pages documenting those are invisible to this run
• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 63 of 226 client-bound route-ledger rows — the other 163 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 163: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 59 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 104 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 — 173 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 5f0037449256ccb0855e258ffc4fd4bff84d1a67 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 5f0037449256ccb0855e258ffc4fd4bff84d1a67

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

[objectstack-fleet]

domain:server#2 · marchtian · session_017ihL2fBJ6xsLWJsnNJGMMx

席位核对 — ACCEPT · domain:server#2 · Head-sha: df1ae02829de568f378d64499ffb57456ca5494b · 2026-11-07T12:45Z

维护者速读

• 改了什么:用 codemod 把 ObjectQL 的 find / findOne 方法体搬进已有的 engine-find.ts,类上只留委托桩;登记表删两行例外(19 → 17)。refactor: move shared state out of the protocol.ts and engine.ts facades into state-owning facets, so the hot bodies left on the class can become delegations (ruling 6624345766) #30020 系列第 E2 步。
• 为什么改:继续缩小 engine.ts(11,111 → 10,739 行),按裁决 A 门面仍是唯一状态持有者。
• 风险与回滚:纯搬移,行为不变;撤销证明逐字节通过(席位本地独立重跑);公开 .d.ts 不变。回滚 = revert。
• 先看:engine-find.ts 的 FindHost 与两处 ql: this.facade。
• 两分钟验证:node scripts/codemod-split-engine.mjs --members --verify --base origin/main exit 0。
• 需要你做的:无,席位落地。
• 席位意见:接受。只用到规则 R1;无手改;契约复审不欠(字节可逆、无公开面变化、Clause-②: no),本记录即默认档席内复核。

席位核对

• Shape: draft PR to main, Refs #30020 (series PR, card stays open — correct, not Fixes); no other card number beside a closing keyword. 4 files: .changeset/30020-objectql-find-findone-facet.md (patch @objectstack/objectql, carries both declaration lines), packages/objectql/src/engine-find.ts, packages/objectql/src/engine.ts, scripts/facade-delegation-registry.json — inside claim 6706751167's surface.
• Premise measured: seat re-ran node scripts/codemod-split-engine.mjs --members --verify --base origin/main on a fresh worktree at head df1ae02829 (after pnpm install): exit 0, "2 moved method(s) (find, findOne); engine.ts 11111 -> 10739 lines; undoing the moves does rebuild the base … byte-for-byte once the 19 import binding(s) only moved bodies read are pruned". Diff read: the stubs are return FindFacet.X.call(findHost.of(this), …); the host factory gains facade: engine; the only this rewrites in the moved bodies are the two ql: this.facade.
• Gates: dev's 66 derived families exit 0 + pnpm lint + check:facade-delegation-only (report 6707096361). Check-runs on this head are still running at this record; landing waits for every check green or expected-skip on df1ae02829.
• .d.ts: dev reports the three dist/*.d.ts byte-equal with a positive control in the same block (stub regex 0 → 1 in dist/index.mjs); public find/findOne keep docblock and signature on the class, consistent with the diff.
• Accepted deviations: rules R2/R5/R6 not recoverable from the card (previous seat's design file is in another project); the PR body states the rules actually applied, and none beyond R1 was exercised.
• Out of scope / Skills-docs: Skills-docs: none holds (internal move, Metadata-protocol: none). No findings.
• Landing: not governed, 921 changed lines ≤ 3000 (check-governed-merges.mjs --pr 31116); the seat flips ready and enables auto-merge once checks are green on this head. Next in the series: E3 (constructor) after this lands.

[objectstack-fleet]

domain:server#2 · marchtian · session_017ihL2fBJ6xsLWJsnNJGMMx

席位核对 — ACCEPT · domain:server#2 · Head-sha: 8c46a17a83effd0a1c24f7f3e7c9cf5d5515d75e · 2026-11-07T13:37Z

维护者速读

• 改了什么:在 ACCEPT 6707122654(head df1ae02829)之上只多一个提交:把 engine.ts 搬走后失效的三处证据锚点改指新位置,changeset 补 @objectstack/spec patch。
• 为什么改:find / findOne 搬进 engine-find.ts 后,engine.ts 不再导入 planFormulaProjection、ENGINE_QUERY_SLOTS、applyFormulaPlan,liveness 证据测试因此红(Test Core 2/8)。
• 风险与回滚:只改证据字符串、注释和 changeset 一行;无状态、无契约变化。回滚 = revert。
• 先看:packages/spec/liveness/query.json 的 fields / top 两行。
• 两分钟验证:本 head 的 Test Core 全绿即为读数。
• 需要你做的:无,席位落地。
• 席位意见:接受。

席位核对(增量)

• Delta df1ae02829..8c46a17a83: 3 files, +7 −5: .changeset/30020-objectql-find-findone-facet.md, packages/spec/liveness/query.json (query.fields, query.top), docs/qa/platform-checklist/areas/api-backend.json (one applyFormulaPlan cite). Out-of-claim edit approved by the seat; claim amended.
• Anchors read at this head: engine-top-level.ts:243 declares ENGINE_QUERY_SLOTS, :1508 planFormulaProjection, :2739 applyFormulaPlan; engine-find.ts:429 / :752 call foldEngineOptionAliases on find / findOne before any AST read; engine.ts holds none of the three names.
• Independent Fable review (owed because packages/spec/** is touched): PASS. Changeset bump correct (liveness/ ships in @objectstack/spec files; precedent .changeset/30053-liveness-search-fields-repoint.md). Nit, out of scope, pre-existing at base: liveness/view.json (engine.ts#resolveMetadataItemName) and liveness/capability.json note (engine.ts#METADATA_ARRAY_KEYS) cite names no longer declared in engine.ts; left for the next PR that touches those rows.
• CI on this head: 58 success, 11 skipped, 0 failed.
• Clause-②: no holds. Landing: not governed; the seat flips ready and enables auto-merge.