[objectstack-fleet]

Requested by Yibo Wang · project thread

Part of #29986

维护者速读

• 改了什么：codemod scripts/codemod-split-engine.mjs 按裁决 6624345766 的门面形态拆分 engine.ts。ObjectQL 的 161/278 个方法体（未修改）移进 16 个无状态 facet 类（每个分节模块一个类，类里是静态方法）。146/146 个顶层声明移进叶子模块 engine-top-level.ts。类上留下签名和一个调用 facet 的 stub。私有方法的 docblock 随方法体移走，公开方法和受保护方法的 docblock 留在类上。方法体读私有静态成员时经 ObjectQLStatics 转发。状态仍在 ObjectQL 上。生成的文件没有手改。按路径读 engine.ts 的读者跟着代码读新模块。
• 为什么改：[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 大文件拆分；裁决 6624345766 把 13,000 行门槛换成结构门禁（门面文件里不留方法体，例外具名列出，见 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）。
• 风险与回滚：只是搬移。161/161 个方法体、146/146 个顶层声明逐字节相同。撤销拆分会逐字节还原 base 的 engine.ts。objectql 测试 base 10,829 = head 10,829，typecheck 0 错。打包后的 .d.ts 公开面相等（裁决 6624345766 第 1 条）。回滚方式是 revert。
• 先看：① 下方「例外」表（31 个方法体留在类上，以及原因）；② ObjectQLStatics 和类末尾的 static 块；③ 下方「按路径读的读者」表。
• 两分钟验证：pnpm install --frozen-lockfile 之后运行 node scripts/codemod-split-engine.mjs --verify --base 0b99c2b1，应输出 161/161 moved bodies identical、146/146 moved top-level declarations identical、23245 -> 14140 lines，退出码 0；node scripts/codemod-split-engine.mjs --self-test 应通过 62 例。
• 需要你做的：改动超过 3,000 行，需要您批准，并在您定的窗口里落地；本 PR 保持草稿。

Clause-②: no
Metadata-protocol: none

What changes

• scripts/codemod-split-engine.mjs (new). It plans the split, writes it and proves it. It follows the pilot's form (refactor(driver-sql): codemod pilot — generated, byte-identity-proved section split of sql-driver.ts (#29520) #29598) and these rulings: 6591753301 A (levers (a) and (b)), 6597555122 A (by-path readers widen in the same PR) and 6624345766 (the facade shape, below).
  • Stateless facets. Each section module holds one class, <Section>Facet, whose static methods are the moved bodies, unedited (static name(this: Pick<SectionHost, …>, …)). A class member can take any name, so a reserved word (delete) or a name an import already takes no longer keeps a body on the class.
  • Host pattern. The stub hands the body one literal holding the members it reads. Methods go as closures called on the engine at call time, so spies and overrides still work. Fields and accessors go as getters. A field a body assigns also gets a setter (31 stubs).
  • Docblock ownership. A private method's docblock moves with its body (87 moved). A public or protected method keeps its docblock on the class, and the facet member carries a one-line placeholder that points there.
  • Private-static-through-host. engine.ts declares ObjectQLStaticsHost (each member typed (typeof ObjectQL)['x']) and ObjectQLStatics. A static block at the end of the class fills the object with forwarders: a method is called on the class, a field is read when read. A facet module whose bodies read a private static imports ObjectQLStatics AS ObjectQL, so the body text does not change (4 modules, 12 statics). index.ts re-exports neither.
  • Generic methods call their body instantiated with their own type parameters, (Facet.name<T>).call(host, …). A defaulted parameter forwards the value the stub's default produced. A static method whose body reads no this moves too.
  • The no-yield rule is dropped, because the structural gate counts bodies, not lines.
  • PATH_READER_PINS keeps six methods that carry a lint 规则:禁止对引擎/驱动查询选项做 as any / : any 擦除(#4721 的顺带项,已实测残余量) #4918 opts as any site on the class. The guard grandfathers by file, and its baseline may only shrink.
  • --self-test: 62 cases in 6 batteries (stay rules 20; facets, statics and docblocks 11; top-level moves 11; byte-identity proof 10; import prune 4; refusals 6). Each proof is fed an input it must refuse.
• The generated split. --write on main 9d1a465f (its engine.ts is the base 0b99c2b1 one), unedited. New files: engine-compatibility-section.ts, engine-migration-state.ts, engine-transactions-section.ts. Changed: the 13 earlier section modules and engine.ts.

Facets

Module	Facet	Bodies
engine-hooks-and-functions.ts	HooksAndFunctionsFacet	14
engine-actions.ts	ActionsFacet	11
engine-security-resolvers.ts	SecurityResolversFacet	13
engine-middleware-and-context.ts	MiddlewareAndContextFacet	11
engine-defaults-and-autonumbers.ts	DefaultsAndAutonumbersFacet	10
engine-registration.ts	RegistrationFacet	12
engine-references-and-master-detail.ts	ReferencesAndMasterDetailFacet	11
engine-secrets-and-routing.ts	SecretsAndRoutingFacet	11
engine-migration-state.ts	MigrationStateFacet	12
engine-summaries-and-expansion.ts	SummariesAndExpansionFacet	8
engine-find.ts	FindFacet	7
engine-insert.ts	InsertFacet	5
engine-cascade-planning.ts	CascadePlanningFacet	20
engine-delete-and-aggregate.ts	DeleteAndAggregateFacet	2
engine-transactions-section.ts	TransactionsSectionFacet	5
engine-compatibility-section.ts	CompatibilitySectionFacet	9

Another 86 methods were already stubs from the hand series (#25522). Their docblocks stay on the class, because this codemod does not edit the hand-series modules.

Exceptions: bodies that stay on the class (31, for the #30019 allow-list)

Reason	Methods (body lines)
bare this (16)	update 2099, insert 1384, delete 690, find 225, findOne 191, recomputeSummaries 99, resolveReadableIdsSecurity 35, bindHooks 32, readMigrationFlagRowMemoized 27, createContext 18, ownershipQueueService 14, buildHookApi 10, setHookMetricsRecorder 9, setStrictHookBinding 8, setWarnLegacyHandler 4, getHookMetricsRecorder 4
inferred public return type (8)	registerApp 149, registerHook 89, registerDriver 82, init 68, triggerHooks 52, destroy 22, setDatasourceMapping 17, getStatus 12
#4918 erasure pin (6)	seedAutonumber 152, probeReferencingRows 116, resolveMasterDetailParent 110, resolveMasterDetailParents 75, inspectDanglingReferences 67, referenceExists 35
field call (1)	homeAmountServing 54 (it calls the field homeLocalizationResolver, and the host would change the receiver)

ObjectRepository and ScopedContext (696 lines) are not facaded by this codemod.

Tests

Reading	Base	Head
objectql test (local)	547 files, 10,829 passed	547 files, 10,829 passed
objectql test:repo	5 passed	5 passed
objectql typecheck (tsc + check:test-typecheck)	exit 0	exit 0
core test:repo		94 passed

Readers of engine.ts by path

Reader	Now
engine-middleware-operation-vocabulary.test.ts (#7809 weld)	reads engine.ts and engine-top-level.ts
federated-injected-column-readers.test.ts (#21918)	rows keyed to the facet module holding each site; ENGINE_SPLIT_FILES names all 16 modules and the leaf, and a via resolves across them
scripts/check-stack-collection-maps.mjs	the METADATA_ARRAY_KEYS row reads engine-top-level.ts
core second-object-read-exposure.pin.test.ts	the executes row names engine-summaries-and-expansion.ts; two not-a-served-read rows for engine-security-resolvers.ts and engine-top-level.ts
check:liveness	field/summaryOperations, field/autonumberFormat and datasource/external.rowCap cite the facet modules
check-system-context-census	site register regenerated with --write; no row changed
check-adr-anchors, functional-completeness.ts	anchors name engine-top-level.ts
eslint query-options/no-any-erasure, check:query-options-erasure	unchanged: the six sites stay in engine.ts

Ablations, each red and then restored: a federated row re-keyed back to engine.ts (3 tests red); the core executes row put back on engine.ts (2 red); 'purge' added to OperationContext in the leaf (both weld tests red); 'ablatedCollection' added to METADATA_ARRAY_KEYS (check-stack-collection-maps red). The liveness and census reds were observed before their fixes.

.d.ts: public surface (ruling 6624345766 item 1)

The reading is /mnt/project-files/issue-29986/pubsurface.mjs. It applies dtsnorm's second normalisation (ruling 6441032442 B) after removing each private class member, with its leading docblock. Built dist: main 1 = main 2 and head 1 = head 2, byte for byte.

File	statements	private members	public surface	exported names
core.d.ts, core.d.mts	16 / 16	0 / 0	equal	equal
index.d.ts, index.d.mts	168 / 168	94 / 94	equal	equal
util-HASH.d.ts, util-HASH.d.mts	190 / 190	332 / 332	equal	equal

Controls: a private member made public is caught; a public member's printed type changed is caught; a private docblock edit is not caught. Strict 6441032442 B, for reference: util-HASH differs in one statement (the ObjectQL class, by its moved private docblocks), and its surface digest is equal. ObjectQLStatics and the facets appear in no .d.ts.

Verification

Reading	Result
Byte-identity (--verify --base 0b99c2b1)	exit 0: 161/161 bodies and 146/146 declarations identical; the moved docblocks and the placeholders are checked, the statics block is rebuilt from the base class, and the undo rebuilds the base engine.ts once the 107 pruned bindings are re-derived
Determinism	two generations from the same input are identical; tree sha256 2723df98712b1831ad01067458bcfaa3695ff9a3eb8a7e0c46e1566f007c8e73 (input dc5677f3ef529f5272d95855361202d9948cb802a89fc3df80dca16dea3e1384), the same as the tree on disk
pnpm build, pnpm lint, check-nul-bytes	exit 0
dispatch-gates --commands	126 derived, 126 run, all exit 0; --ran: 0 NOT-MEASURED, 0 UNRUN

No changeset: the pilot #29598 shipped none (skip-changeset), and this PR follows it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WGufzhfKpcY1cmybduYBcp

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/objectql, @objectstack/spec, touching 668 documentable anchor(s). ⚠️ 3 changed file(s) yielded no anchor (packages/spec/liveness/datasource.json, packages/spec/liveness/field.json, packages/spec/src/kernel/functional-completeness.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

118 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 140d8ce805dc55245d9841a6ece6dfb956d9e071.

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

What this run could not see

• 3 changed file(s) yielded no anchor (packages/spec/liveness/datasource.json, packages/spec/liveness/field.json, packages/spec/src/kernel/functional-completeness.ts) — pages documenting those are invisible to this run
• 1 cross-cutting symbol(s) contributed no route anchor: packageId (4 routes)
• 5 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 80 pages), current_user (literal, 44 pages), master_detail (literal, 40 pages), organization_id (literal, 38 pages), /data/:object (route, 76 pages)
• 54 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 — 171 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 140d8ce805dc55245d9841a6ece6dfb956d9e071 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 140d8ce805dc55245d9841a6ece6dfb956d9e071

⚠️ 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 140d8ce805dc55245d9841a6ece6dfb956d9e071 → 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 f48078bb671eee96feaac7f33c281416dd25f0dc · 2026-11-04T10:05Z

• Shape: a deterministic codemod (facade form, ruling 6624345766) moves 161 of 278 ObjectQL bodies into 16 stateless facet classes and all 146 top-level declarations into the leaf. engine.ts goes from 23,245 to 14,140 lines. 87 private docblocks move with their bodies, and the public and protected ones stay on the facade. 31 bodies stay on the class as named exceptions for 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: bare this 16, inferred public return type 8, lint 规则:禁止对引擎/驱动查询选项做 as any / : any 擦除(#4721 的顺带项,已实测残余量) #4918 erasure pins 6, field call 1.
• Proofs (dev report 6626513858): --verify 161/161 and 146/146, and the undo rebuilds the base. The tree sha is equal across two runs and on disk. The self-test passes 62 cases. objectql has 10,829 tests (= base). tsc and test-typecheck are 0. Core test:repo 94. The public .d.ts surface is EQUAL on 6/6 files, and the controls were caught. 126/126 gates exit 0, with --ran showing 0 NOT-MEASURED. Each re-keyed by-path reader was ablated red.
• Declaration: Clause-②: no, Metadata-protocol: none, no runtime change. Reviewed as consistent: the bodies are byte-identical and the public surface is equal.
• Window: the maintainer approved at this head (review, 10:03Z). No open PR touches engine.ts. CI at head: 57 success, 12 skipped, 0 failed.
• Accepted deviations: the harness-pinned branch. The follow-up splits (stub compression, hand-series docblocks, facading ObjectRepository / ScopedContext, explicit return types, the lint 规则:禁止对引擎/驱动查询选项做 as any / : any 擦除(#4721 的顺带项,已实测残余量) #4918 sweep) are filed after merge, at the maintainer's word. The bare-this hot bodies go to 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.
• Landing: the seat sends pr_ready + automerge_enable through the relay. The tooling: a structural gate that keeps a registered facade class delegation-only #30030 gate lands after both facades.