[objectstack-fleet]

Requested by Yibo Wang · project thread

Part of #30105

维护者速读

• 改了什么：给 scripts/codemod-split-sql-driver.mjs（Codemod split pilot: generate the sql-driver.ts split with a deterministic script, verified byte-identical #29520 的试点脚本）加上 engine.ts / protocol.ts 已有的门面层，并重新生成 sql-driver.ts。SqlDriver 成为门面：158 个方法体移入 21 个无状态 facet 类（静态方法，this 是一个具名 host），类上各留一行 .call(xHost.of(this), …) 委派；私有方法的文档块随方法体移走（21 个），公开和受保护方法的文档块留在门面；状态全部留在门面。生成文件未手改。
• 为什么改：[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 大文件拆分，裁决 6632500982 把门面形态（6624258595）扩展到本文件；.d.ts 门槛按 6624345766 取「公开面相等」。
• 风险与回滚：纯搬移。158/158 个方法体逐字节等于 base，撤销拆分逐字节重建 base 的 sql-driver.ts；两次 --write 输出树 sha256 相同。公开面 .d.ts 相等（对照抓到）。driver-sql 测试 base 与 head 都是 3,859 通过；turso、sqlite-wasm 两个子类驱动计数不变。回滚即 revert。
• 先看：① 「Facade reading」一节的 28 条例外（其中哪些是 codemod 限制、需另立卡）；② codemod 的 CLASS_HEAD_SECTION 和新加的 logDurabilityFailure pin；③ check-tenant-chokepoint.mjs 新登记的 4 个模块。
• 两分钟验证：pnpm install --frozen-lockfile 后运行 node scripts/codemod-split-sql-driver.mjs --verify --base 21510bba，预期 158/158 moved bodies identical to base、sql-driver.ts 18334 -> 10979 lines，退出码 0；--self-test 67 例通过；node scripts/check-facade-delegation-only.mjs 退出码 0。
• 需要你做的：改动超过 3,000 行（+4,990 / −3,121，含生成文件），需您批准后落地，并在您定的窗口冻结 sql-driver.ts；本 PR 保持草稿。

Clause-②: no
Metadata-protocol: none

What changes

• scripts/codemod-split-sql-driver.mjs gains the facade layer scripts/codemod-split-engine.mjs carries (refactor(objectql): generate the engine.ts section split with a deterministic codemod #30012, refactor(objectql): one shared host per facet in the engine.ts codemod stubs (body-identical; engine.ts 14,140 -> 13,548) #30083):
  • Each section module's moved bodies become the static methods of one stateless facet class (sql-driver-crud.ts → CrudFacet), at class indentation, unedited. Their this is one named host interface typed AS the class members (SqlDriver['x']), so a private member is reached like a public one.
  • The stub on the class keeps its modifiers and signature byte-for-byte (only async is dropped) and makes one call: return CrudFacet.x.call(crudHost.of(this), …). Each host is built once per driver by a factory the class's static block installs into sql-driver-facet-hosts.ts (types-only module). Methods go as closures called on the driver at call time, so a subclass override or an instance spy is still the one reached; getBuilder goes as a bound getter (BOUND_HOST_METHODS) so check-tenant-chokepoint still counts the binding in the moved body; fields and accessors go as getters, assigned fields with a setter.
  • Private statics the moved bodies read go through SqlDriverStatics, which a facet module imports AS SqlDriver (private-static-through-host, 6624174693).
  • Docblock ownership (6624345766 item 1): a private method's docblock moves with its body; a public or protected one stays on the facade and the facet member carries a one-line placeholder pointing back.
  • The members above the first banner form one more section, the class head (CLASS_HEAD_SECTION → sql-driver-class-head.ts). Three sections whose hand-series seam exists already take a -section suffix; sql-driver-deferred-ddl.ts and sql-driver-transactions-section.ts are new.
  • No import prune: driver-sql compiles without noUnusedLocals, so an import only a moved body reads stays, as the pilot left them.
  • The pilot's --dts byte-equality reading is dropped: a facade cannot meet it by construction (the bundled .d.ts prints every private member). The bar is now the public-surface reading below, taken outside scripts/ (6441032442 item 3).
  • parameter-shadows now fires only for a parameter named like the stub's facet class or host variable (it freed 4 methods).
  • One new PATH_READER_PINS row, logDurabilityFailure (see readers below).
  • --self-test: 67 cases in 5 pinned batteries (class-head section, the bound getter and two banner refusals added; the import-prune battery removed).
• The generated split is --write on the unsplit sql-driver.ts of 21510bba (the parent of the pilot's landing), unedited. 158/254 methods move into 21 facet modules; sql-driver.ts goes 18,334 → 10,979 lines (12,460 on main). The leaf sql-driver-top-level.ts is byte-identical to main. index.ts re-exports none of the new modules.
• scripts/facade-delegation-registry.json: the sql-driver.ts / SqlDriver facade row (card Codemod split: put driver-sql sql-driver.ts into facade form with a deterministic script, like protocol.ts and engine.ts #30105) and 28 exception rows, all carded 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.
• By-path readers (6597555122 item 3):
  • check-durability-degradation-log-level judges the two MySQL widening catches that stay on the class (migrateMysqlDatetimeColumns, migrateMysqlTimeColumns) by following this.logDurabilityFailure(…) to its body in the same file. A one-call stub there cannot be followed, so both read "swallowed, no log" (measured red). The helper is pinned to stay rather than widening the gate's same-file helper walk across files; the gate's readings are then equal to base.
  • check-tenant-chokepoint's DECLARED_WATCH_HINTS names the four new sql-driver-*.ts modules (its self-test requires every scanned file to be declared).
  • Every other reader of sql-driver.ts by path (the packages/cli generate pins, check-keyed-text-bounds, sql-driver-compile-refusal-seam.test.ts, the liveness and checklist anchors, the ADR anchors) reads text the codemod keeps on the class through its existing pin and needle tables, and passes unchanged.
• No changeset, as refactor(driver-sql): codemod pilot — generated, byte-identity-proved section split of sql-driver.ts (#29520) #29598 and refactor(objectql): generate the engine.ts section split with a deterministic codemod #30012 (both skip-changeset): no published behaviour or surface changes.

Tests

No test file changes. The suites below ran at base f68b47ca and at head; the counts are equal.

Suite	Base	Head
driver-sql (vitest run)	238 files passed, 12 skipped; 3,859 passed, 216 skipped	the same
driver-turso (subclasses SqlDriver)	96 files; 2,496 passed, 34 skipped	96 files; 2,496 passed, 34 skipped
driver-sqlite-wasm (subclasses SqlDriver)	40 files; 750 passed	40 files; 750 passed
cli by-path pins (9 files: generate-* pins, clean.operator-text-21418)	9 files; 131 passed	9 files; 131 passed
types / metadata / metadata-protocol by-path tests, spec check-liveness.test	22 / 11 / 28 / 74 passed	22 / 11 / 28 / 74 passed

Acceptance notes

• Phase 0: this PR stays a draft. It is over the 3,000-line human-merge threshold, so it lands on a maintainer approval, after sql-driver.ts is frozen for a window. At landing the script runs on the latest main's unsplit text (regenerate, never rebase, ruling A on [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).
• Codemod-limit exception rows the seat may card separately (the rest are state-owning, 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): the five accessors (the codemod moves methods, not accessors); rotateShards / ensureRotation (a computed parameter default stays in the byte-for-byte signature); the path-reader pins (ensureShardTable, initObjects, migrateMysqlDatetimeColumns, migrateMysqlTimeColumns, resolveWithheldFilterRefusal, createAuditTimestampColumn, varcharColumnChars, createColumn, logDurabilityFailure), which move once their readers read the facet modules; and the field-call: knex, inferred-return-type and comment-in-parameters stays.
• dts-public.mjs's built-in --private-control fails on this dist: it deletes the first private x; line but leaves that member's docblock, which then attaches to the next (public) member. Dropping the whole private member with its docblock passes (reading below).

Verification

Reading	Base	Head
sql-driver.ts lines	18,334 (21510bba) · 12,460 (main)	10,979
Byte-identity (--write, and --verify --base 21510bba, exit 0)		158/158 bodies, 127/127 top-level declarations identical; undoing the split rebuilds the base byte-for-byte
Determinism		two --write runs: output tree sha256 eab675141cad9efdb5217f65f044a246474c973777c575d9f5ee00b8c63d8154 both times; regeneration reproduces the committed tree
driver-sql typecheck	exit 0	exit 0
check:facade-delegation-only (+ --self-test 36)		exit 0: SqlDriver 352 members, 244 delegations, 80 fields, 28 named exceptions
check:tenant-chokepoint	24 bindings, 21 read doors, 3 insert builders, 4 tenant predicates, 0 D8 arms, 34 files	the same readings, 38 files
check:durability-log-level	51 seams (9 propagating), 101 read seams (13 discriminated)	the same; the output is byte-identical
pnpm build (whole repo, 119 tasks)		exit 0
pnpm lint		exit 0
dispatch-gates --commands (67)		67 run, every exit 0; --ran: 67 derived, 0 NOT-MEASURED, 0 UNRUN

.d.ts: ruling 6624345766 item 1, "public surface EQUAL"

Read with dts-public.mjs (project files issue-29985/dts-public.mjs, sha256 211b32062250606e658acd7fb8880e0079b4043121fb7b970c658b4b57bf5020, the reading #29985 used). driver-sql's .d.ts build is deterministic on both sides (two builds each, byte-identical), so one pair is read.

Reading	index.d.ts	index.d.mts
raw (sha256 base 69d9162d… / head fac28979…)	differs (private members)	differs
private members cut, union order, second normalisation	equal (106 / 106 statements)	equal
declared surface	equal	equal

• The control that edits one public docblock is caught.
• Dropping one whole private member (fileColumnsMovedDeclared with its docblock) passes.
• The facet classes and hosts do not appear in the .d.ts.

Facade reading

Facet	Members	Docblocks moved
ClassHead	12	6
Lifecycle	11	6
Crud	7	2
SequenceSemantics	23	3
BulkOperations	7	0
TransactionsSection	1	0
Aggregation	3	0
Distinct	1	0
WindowFunctions	1	0
QueryPlan	2	0
SchemaSyncSection	3	0
Rotation	9	0
DeferredDdl	3	0
ManagedDrift	8	0
InternalHelpers	7	0
FilterHelpers	30	3
FieldMapping	6	0
WindowFunctionBuilder	1	0
ColumnCreation	14	1
DatabaseHelpers	7	0
SqliteSerialisation	2	0
Total	158	21

The 28 exception rows (all #30020):

Reason	Members
state: constructor logic, field / static initializers holding arrows	constructor, logger, static DIALECT_CONNECT_TIMEOUT
accessor (codemod moves methods only)	get supports, get insertReturnsStoredRows, get dateGranularityCapabilities, get supportsWalJournal, get dialectName
a computed parameter default	rotateShards, ensureRotation
path-reader	logDurabilityFailure, ensureShardTable, initObjects, migrateMysqlDatetimeColumns, migrateMysqlTimeColumns, resolveWithheldFilterRefusal, createAuditTimestampColumn, varcharColumnChars, createColumn
field-call: knex	listPhysicalColumns, getBuilder, explainUnkeyableTextColumn, explainHashShadowDuplicate
inferred-return-type	applyFilters, applyFilterCondition, ensureDatabaseExists, createDatabase
comment-in-parameters	assertOperatorAppliesToColumn

The 78 hand-series stubs stay as they were (their modules are the hand series', not facets) and read as delegations.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01WGufzhBZia3VxBbmZ7wCkS

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/driver-sql, touching 526 documentable anchor(s).

36 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 a9fb14bdeeb5e09fec341ead4e0fffd8d8ed00bb.

⛔ 12 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: created_at (literal, 43 pages)
• 16 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 — 13 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 a9fb14bdeeb5e09fec341ead4e0fffd8d8ed00bb → packageMentionDocs.

Which tree this was computed on

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

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

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

[objectstack-fleet]

domain:devx#1 · os-support-ai · session_01WGufzgBDcBNVmSmo7VFHpj

Stamp: 2026-11-04T16:28Z
Head-sha: 61c98d1

维护者速读

• 改了什么: packages/drivers/driver-sql/src/sql-driver.ts 改为 facade 形式，由扩展后的 scripts/codemod-split-sql-driver.mjs 生成。254 个方法里有 158 个移进 21 个无状态 facet，类上只留一行委托。文件从 12,460 行降到 10,979 行。SqlDriver 已登记进 facade 门禁的登记表，带 28 条例外：3 条状态类挂 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，25 条 codemod 局限挂 Facade codemods: retire the codemod-limit exception rows in the facade gate registry (protocol.ts, engine.ts, sql-driver.ts) #30147。
• 为什么改: 维护者 13:55Z 在决策卡上选了「直接立卡拆」（裁决 6632500982），按 protocol.ts / engine.ts 的 facade 方案处理 sql-driver.ts。
• 风险与回滚: 移动的方法体逐字节相同：--verify 有 158/158 相同，撤销后能逐字节还原原文件。公开 .d.ts EQUAL。base 与 head 的测试数相同：driver-sql 3,859、turso 2,496、sqlite-wasm 750。租户 chokepoint 读数相同（24/21/3/4/0）。回滚就是 revert。
• 先看: facade 门禁对 SqlDriver 的读数（352 个成员：244 个委托、80 个字段、28 条例外），以及 codemod-split-sql-driver.mjs 新增的 facade 层。
• 两分钟验证: 跑 node scripts/codemod-split-sql-driver.mjs --verify --base 21510bba，预期 exit 0；跑 pnpm check:facade-delegation-only，预期 exit 0。
• 需要你做的: 改动共 8,111 行，超过 3,000 行，需要授权账户（os-zhuang 或 hotlong）在本 PR 上 APPROVE。批准后由席位挂 auto-merge 落地。check-owed-reviews 没有列出本 PR（非受管、非 spec 面），所以不欠契约复核，与 refactor(metadata-protocol): generate the protocol.ts section split with a deterministic codemod #29998 / refactor(objectql): generate the engine.ts section split with a deterministic codemod #30012 同例。
• 席位意见: ACCEPT。证明齐全，生成产物没有手改。例外的去向都已分好：状态类归 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，codemod 局限归 Facade codemods: retire the codemod-limit exception rows in the facade gate registry (protocol.ts, engine.ts, sql-driver.ts) #30147。

席位核对

• 形态: 26 个文件，+4,990/−3,121。没有受管路径，按行数归 Tier H（check-governed-merges.mjs --pr 30139：8,111 行 > 3000）。席位确认了 head 上 sql-driver.ts 为 10,979 行，登记表含 SqlDriver（card Codemod split: put driver-sql sql-driver.ts into facade form with a deterministic script, like protocol.ts and engine.ts #30105）及其 28 条例外，卡号只有 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 和 Facade codemods: retire the codemod-limit exception rows in the facade gate registry (protocol.ts, engine.ts, sql-driver.ts) #30147 两种。
• 前提实测: dev 的 codemod 从拆分前的原始文件 21510bba（18,334 行）重新生成，与试点同一做法。base f68b47ca。两次 --write 产出相同（sha eab67514）。d.ts 构建是确定的（spec build: two builds of the same main source write different .d.ts files (10 files, chunk hash rename) #30061 / PR fix(build): emit spec .d.ts in program order so two builds of one sha match byte for byte #30131 的修复正在合并队列里）。
• 门禁 check-runs: 席位读数，钉 61c98d18：CI 刚开始跑。上一个 head 38ab3e30 读数为 32 success、14 skipped、2 in_progress、0 failure，与本 head 只差登记表 25 行的卡号。dev 本地：dispatch-gates 67 条全部 exit 0，--ran 0 NOT-MEASURED；新 head 上 facade 门禁 exit 0，自测 36/36；全量 build（119 个任务）和 lint exit 0。
• 接受的偏差: logDurabilityFailure 按 pin 留在原文件，因为 durability 门禁在同一文件里跟着它；tenant-chokepoint 声明了 4 个新模块；dts-public --private-control 不过（有一段孤立 docblock），但手工整成员删除的对照能抓到；两条未发布的提交改成了不带模型名的 trailer。PR 正文里「The 28 exception rows (all 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)」已过时，以本记录为准（3 条 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，25 条 Facade codemods: retire the codemod-limit exception rows in the facade gate registry (protocol.ts, engine.ts, sql-driver.ts) #30147）。
• 范围外去向: 25 条 codemod 局限 → Facade codemods: retire the codemod-limit exception rows in the facade gate registry (protocol.ts, engine.ts, sql-driver.ts) #30147（新立）；3 条状态类 → 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。Skills-docs: none。
• 落地条款: 等授权 APPROVED（GOVERNED_APPROVERS），批准后不随推送过期。之后席位重读 CI 全绿，执行 pr_ready + automerge_enable；合并后关卡 Codemod split: put driver-sql sql-driver.ts into facade form with a deterministic script, like protocol.ts and engine.ts #30105。