[objectstack-fleet]

Requested by Yibo Wang · project thread

Part of #30147 (phase 2d, the last of 2a-2d: the codemod writes applyFilterCondition's return type, so it moves. The phase 3 measurement is posted on the card.)

维护者速读

• 改了什么:codemod 的 EXPLICIT_RETURN_TYPES 新增 applyFilterCondition: 'void'(取自 base 构建出的 dist/index.d.ts),重新生成后它的方法体移到 sql-driver-filter-helpers.ts,登记表删去这一条(68 → 67)。
• 为什么改:它留在类上只因为 base 没写返回类型(Facade codemods: retire the codemod-limit exception rows in the facade gate registry (protocol.ts, engine.ts, sql-driver.ts) #30147 第 2d 步,2a 已为同类成员建好这张表)。
• 风险与回滚:方法体逐字节不变(181/181),公开 .d.ts 与 base 逐字节相同;回滚即 revert。
• 先看:codemod 里新增的那一行,以及 sql-driver.ts 上 applyFilterCondition 的 stub。
• 两分钟验证:node scripts/codemod-split-sql-driver.mjs --verify --base 21510bba(181/181,退出 0)和 node scripts/check-facade-delegation-only.mjs(67 条具名例外,退出 0)。
• 需要你做的:无,席位审阅并落地。

Clause-②: no
Metadata-protocol: none

What changes

• Codemod (scripts/codemod-split-sql-driver.mjs). EXPLICIT_RETURN_TYPES gains applyFilterCondition: 'void'. The type is copied from the base dist/index.d.ts (protected applyFilterCondition(builder: Knex.QueryBuilder, condition: any, logicalOp?: 'and' | 'or', tableHint?: string | null, rootFilter?: unknown, options?: DriverOptions): void;).
• Regenerated from 21510bba. The body of applyFilterCondition moves to sql-driver-filter-helpers.ts, and the class keeps its signature with : void written as a one-call stub. sql-driver.ts goes from 9,741 to 9,354 lines. No generated file is edited by hand.
• Registry. The row is deleted, so 68 rows become 67.

card	before	after
#30020	19	19
#30054	16	16
#30055	6	6
#30147	27	26 (sql-driver.ts 3 → 2)
total	68	67

The two sql-driver.ts rows left on #30147 are get supports and static DIALECT_CONNECT_TIMEOUT. The phase 3 report on #30147 recommends that both stay as accepted exceptions.

Tests

• No test file changes. The codemod's --self-test already pins the EXPLICIT_RETURN_TYPES mechanism (battery "codemod-limit retirements (Facade codemods: retire the codemod-limit exception rows in the facade gate registry (protocol.ts, engine.ts, sql-driver.ts) #30147)" from refactor(driver-sql): the sql-driver codemod retires 15 facade-gate exception rows (knex calls, spelled return types, comments in parameters, accessors, computed defaults, the logger default) (#30147 phase 2a) #30249). All 106 cases in 7 batteries pass.
• The suites below ran at base d3f23d20 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)	97 files; 2,514 passed, 34 skipped	the same
driver-sqlite-wasm (subclasses SqlDriver)	40 files; 750 passed	the same
cli by-path pins (9 files)	9 files; 116 passed	the same
types / metadata / metadata-protocol by-path tests, spec check-liveness.test	53 / 11 / 33 / 74 passed	the same

Acceptance notes

• The facade gate script and its self-test are untouched.
• No changeset, as refactor(driver-sql): put SqlDriver into facade form with the sql-driver codemod (sql-driver.ts 18,334 -> 10,979, body-identical) #30139, refactor(driver-sql): the sql-driver codemod retires 15 facade-gate exception rows (knex calls, spelled return types, comments in parameters, accessors, computed defaults, the logger default) (#30147 phase 2a) #30249, refactor(driver-sql): the durability gate and the compile-refusal enumeration read the sql-driver facade, so the codemod moves four more members (#30147 phase 2b) #30306 and refactor(driver-sql): the by-path readers read the sql-driver facade, so the codemod moves the five path-reader members (#30147 phase 2c) #30363 (skip-changeset): no published behaviour or surface changes (the public .d.ts is byte-identical).

Verification

Head 322898a6, base origin/main d3f23d20.

Proof readings

• Byte-identity: node scripts/codemod-split-sql-driver.mjs --verify --base 21510bba exit 0: "181/181 moved bodies identical to base (body, parameters, return type, async); 129/129 moved top-level declarations identical to base (leading comments included); sql-driver.ts 18334 -> 9354 lines; undoing the split does rebuild the base byte-for-byte".
• Determinism: two --write runs from the unsplit input give output tree sha256 b8a840238252ab67a7a7ae782a0870e03200f1da9d55cc75f4f07f16f9ac0272 both times (input sha256 2d2ebebd…), and the tree on disk is unchanged by either.
• Public .d.ts: dts-public.mjs over the base and head dist exit 0, pass: true, both files raw-equal (index.d.ts sha256 92e2cfb2… on both sides).
• Typecheck: pnpm --filter @objectstack/driver-sql typecheck exit 0.
• check-tenant-chokepoint: 24/21/3/4/0 across 39 files at base and head; --self-test exit 0.
• Durability gate --list: byte-identical output at base and head (52 seams).
• Facade gate exit 0, "5 facade class(es) in 3 file(s) hold delegations only, 67 named exception(s)"; --self-test exit 0.
• node scripts/pm/dispatch-gates.mjs --commands: 65 derived commands, each run, all exit 0; --ran reconciles 65 derived, 65 run, 0 NOT-MEASURED. Also run: the codemod, check-keyed-text-bounds, durability, check-tenant-chokepoint and facade gate --self-tests, check:lean-entry-closure, eslint over the changed files, all exit 0.
• Changed lines 873 (+456 / -417), under the 3,000 threshold.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

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

• content/docs/data-modeling/drivers.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/data-modeling/external-datasources.mdx (via remoteColumn (literal, a string literal in applyFilterCondition))
• content/docs/data-modeling/index.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/data-modeling/queries.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/permissions/tenant-audit-census.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/plugins/packages.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/protocol/kernel/index.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/protocol/kernel/lifecycle.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/protocol/objectql/query-syntax.mdx (via SqlDriver (symbol, a top-level class), coerceFilterValue (literal, a string literal in applyFilterCondition))
• content/docs/protocol/objectql/types.mdx (via SqlDriver (symbol, a top-level class))

⛔ 4 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17/17-0.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/releases/v17/17-5.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/releases/v17/17-6.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/releases/v18/18-1.mdx (via SqlDriver (symbol, a top-level class))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 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 f18adce2f65b9de8ce3b7de1c3ba870bebb53420 → packageMentionDocs.

Which tree this was computed on

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

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

⚠️ 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 f18adce2f65b9de8ce3b7de1c3ba870bebb53420 → 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-05T11:35Z
Head-sha: 322898a

维护者速读

• 改了什么: codemod 的显式返回类型表新增 applyFilterCondition: 'void'，类型从 base 的 d.ts 取得。重新生成后，这个 474 行的方法体移进 sql-driver-filter-helpers.ts，类上只留一行委托。sql-driver.ts 从 9,741 行降到 9,354 行，例外从 68 条降到 67 条。
• 为什么改: Facade codemods: retire the codemod-limit exception rows in the facade gate registry (protocol.ts, engine.ts, sql-driver.ts) #30147 第二阶段的最后一步 2d。
• 风险与回滚: 方法体逐字节相同，公共 .d.ts 原样相同，各套件测试数量与 base 一致。回滚就是 revert。
• 先看: sql-driver.ts 里 applyFilterCondition 的一行委托，以及 filter-helpers host 新增的转发。
• 两分钟验证: node scripts/codemod-split-sql-driver.mjs --verify --base 21510bba，退出 0，181/181 个方法体相同。
• 需要你做的: 无，由席位落地。
• 席位意见: ACCEPT。

席位核对

• 形态: 4 个文件，+456/−417。check-governed-merges.mjs --pr 30441 判 NOT governed（873 行，不超过 3000）。
• 前提实测: 席位读了 sql-driver.ts 相对新 main 的 diff：只有一行委托、一行 import 和 host 的转发项。席位读的 head 登记表：67 条。sql-driver.ts 只剩 3 条：constructor 挂 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，static DIALECT_CONNECT_TIMEOUT 和 get supports 挂 Facade codemods: retire the codemod-limit exception rows in the facade gate registry (protocol.ts, engine.ts, sql-driver.ts) #30147。
• 门禁 check-runs: 钉 322898a6，CI 还在跑，auto-merge 会等全绿。dev 本地读数，都是 exit 0：
  • --verify 181/181；两次 --write 的 sha 相同（b8a84023）；
  • dts-public 原样相同；typecheck 通过；
  • 各套件测试数量与 base 一致；
  • tenant-chokepoint 与 durability 的读数不变；
  • facade 门禁 67 条；dispatch-gates 65/65；eslint 0。
• 接受的偏差: dev 先在本地分支做好，2c 合并后挑到新 main 上重新生成，只推了一次。
• 范围外去向: 第三阶段测量见 /mnt/project-files/issue-30147/report-phase3.md。protocol.ts 和 engine.ts 剩下的行属于 domain:server，要等 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: sweep the #4918 as any sites in engine.ts's six erasure-pinned methods so the codemod can move them (about 550 lines) #30055 做完。get supports 和 DIALECT_CONNECT_TIMEOUT 建议作为长期接受的例外，需要维护者裁决。
• 落地条款: 席位 pr_ready + automerge_enable。合并后 Facade codemods: retire the codemod-limit exception rows in the facade gate registry (protocol.ts, engine.ts, sql-driver.ts) #30147 不关，转回队列，由席位写交接说明。