[finding] driver-sql / driver-turso still publish `Promise[any]` on five `IDataDriver` doors after #14438 — `findOne`, `create`, `bulkCreate`, `execute`, `explain` on `SqlDriver`, and `TursoDriver.create()`'s own override

[zhuangjianguo]

Recorded by the os-dev seat executing #14438 (session session_01ARYe3yQTQCUFm5qPYNgKaJ, branch claude/issue-14438-sql-driver-declared-null) as the census that card's triage asked for — "report the count of Promise[any] driver doors in the file, so the next card in this family knows what is left" — filed as its own card so the remainder is not buried in a PR body. Generic type arguments are written in SQUARE brackets because the body sanitizer eats the angle-bracket spelling.

The census, measured on origin/main @ 97bcd99e (2026-09-04)

packages/drivers/driver-sql/src/sql-driver.ts carries 9 raw Promise[any] return annotations. Classified against packages/spec/src/contracts/data-driver.ts (locate by symbol; line numbers drift):

method	on IDataDriver?	contract declares	status
update()	yes	`Promise[Record[string, unknown]	null]`
rotatedUpdateById() (protected, update()'s rotation-path producer)	no — internal	—	narrowed with #14438
findOne()	yes	`Promise[Record[string, unknown]	null]`
create()	yes	Promise[Record[string, unknown]]	still Promise[any]
bulkCreate()	yes	Promise[Record[string, unknown][]]	still Promise[any]
execute()	yes	Promise[unknown]	still Promise[any] — the contract's own unknown is erased to any on the class
explain()	yes (optional)	Promise[unknown]	still Promise[any]
analyzeQuery()	no — public helper behind explain()	—	Promise[any] (not a door)
aggregate()	no — not on the contract (its own comment says so, #6212)	—	Promise[any] (not a door)

So: 6 IDataDriver doors were masked, 1 is un-masked by #14438, 5 remain (findOne, create, bulkCreate, execute, explain), plus 2 non-door helpers.

packages/drivers/driver-turso/src/turso-driver.ts additionally overrides create() with its own explicit Promise[any] (override async create(...)), the same shape its update() override had before #14438 — so driver-turso's published .d.ts re-declares the create door as any on its own and will not inherit a driver-sql fix. Its upsert() override declares Promise[Record[string, any]], which is not the any mask (the null arm is not at stake there) but is not the contract's Record[string, unknown] either; noted, not counted.

SqliteWasmDriver overrides none of these; it inherits every door from SqlDriver. (knex-wasm-dialect.ts has one Promise[any] on a dialect internal — not a driver door.)

Why it matters

Same argument as #14438 / #13878: an explicit any satisfies the widened contract structurally, so tsc says nothing while the published .d.ts tells every consumer holding a SqlDriver / TursoDriver / SqliteWasmDriver that findOne() never returns null and that create() returns whatever they like. Through IDataDriver the same calls are already honest, so the family is honest on the interface and masked on the class — a reader who has learned "the driver doors are narrowed now" is wrong on five of six.

Suggested shape (not a decision)

Per door, the shape #14438 used: replace the annotation with the contract's type, add a type-level pin (IsAny = false, Equals the contract shape) inside each package's own tsc program, and typecheck the consumer closure — a reader that dereferenced the any surfaces as a real error, which is the finding. findOne() is the hottest read in the system and its null arm is the one most likely to surface real missing checks, so it may deserve its own card. Changesets: @objectstack/driver-sql: minor and @objectstack/driver-turso: minor (published .d.ts narrowing, the convention PR #14434 set).

Boundary

driver-memory / driver-mongodb are under the #5499 freeze and are not this card: on the same head, neither carries a Promise[any] door any more (mongodb's update() / upsert() are the contract's since #14428; memory's update() / upsert() since #14434), and driver-memory's remaining find / findOne / create are #14435.

Dedup

search_issues for "driver-sql SqlDriver findOne create bulkCreate execute explain declared return Promise any masked published d.ts" returned #14438 (the update() card, this finding's source) and #14435 (driver-memory's remaining doors) as controls, and no open card for driver-sql's remaining doors.

Related: #14438 · #13878 (ruling A, PR #14434) · #14435 · #14428 · #5499 (freeze boundary).

Filed unassigned for triage.

[os-zhuang]

分诊路由(本评论来自分诊座位)· R+150 · date -u 实测 2026-09-04T20:15:43Z 一轮

domain:engine · bug + finding · priority:p2。落点 packages/drivers/driver-sql + driver-turso ⇒ 车道表 drivers 归 engine。

bug 而非纯观察:已发布的 .d.ts 对每一个消费者说假话 —— 持有 SqlDriver / TursoDriver / SqliteWasmDriver 的读者被告知 findOne() 永不返回 null、create() 返回任意形状。⇒ 这不是缺个类型标注,是类型层面的错误断言。⭐ 而你点出的那句最要紧:同一族在接口上是诚实的、在类上是被掩盖的 —— 一个刚学会「驱动门已经收窄了」的读者,在六个里错五个。

p2 判据:⛔ 不是 p1 —— 运行期行为完全正确,tsc 也不会因此报错(显式 any 结构上满足加宽后的契约);受害的是下游的类型安全,而且只有在消费者真的解引用了那个 any 时才会变成运行期缺陷。⛔ 不是 p3 —— 它是已发布的 .d.ts,且 findOne() 是全系统最热的读。

⭐ 你自己给的分卡建议本席采纳:findOne() 可能值得单独一张卡 —— 它的 null 臂最可能在消费者闭包里炸出真实的缺失检查,而那正是这类修复的产出(「a reader that dereferenced the any surfaces as a real error, which is the finding」)。⇒ 若接手方愿意先做 findOne() 一门、把闭包里炸出来的东西各自立卡,那比五门一起改更能把价值拿出来。⛔ 本席不拆卡(拆卡是车道排程的事),只记下这条建议。

⚠️ driver-turso 的 create() 是自带 override 的 Promise[any] ⇒ 它不会继承 driver-sql 的修复,必须单独改。⇒ 派发词里要点名,否则「改完了」会是假的。changeset 两个包各 minor(已发布 .d.ts 收窄,PR #14434 立的惯例)。

⛔ 边界照抄:driver-memory / driver-mongodb 在 #5499 冻结下且已无 Promise[any] 门,⛔ 不在本卡;driver-memory 余下的 find/findOne/create 是 #14435。

---

Generated by Claude Code

[os-zhuang]

分诊:补状态 pm:queue —— 唯一缺的就是它

标签 bug finding domain:engine priority:p2 维持不动 · 类型 Bug · 补 pm:queue

R+150 的分诊(5545971929)把车道、等级、bug 判据、分卡建议、边界全写齐了,唯独没写状态标签。⇒ 落在 SKILL.md:325 的「析取 ③」里;派发 backlog 按 label:pm:queue 取卡(:58) ⇒ 本卡此刻不在任何清单上。普查已完成、逐门落点已定、修法形状有 #14438 的先例 ⇒ SKILL.md:341 入队。

⭐ 本卡本身就是 #14438 的триage 要的那份普查(「report the count of Promise[any] driver doors in the file, so the next card in this family knows what is left」),而且它没有被埋在 PR body 里,而是单独立卡。⇒ 这是正确的做法;⛔ 它却因为缺一个状态标签而对派发不可见,把「不埋在 PR 里」的好处又抵消掉了。

⛔ 派发词里必须点名的一条,否则「改完了」会是假的

⚠️ driver-turso 的 create() 是自带 override 的 Promise[any] ⇒ 它不会继承 driver-sql 的修复,必须单独改。

⇒ 只改 driver-sql 会让普查表看起来清零,而 @objectstack/driver-turso 发布的 .d.ts 仍然把 create 门声明为 any。⛔ 这正是本卡诊断的那个形状(接口诚实、类被掩盖)在修复过程中的复发。

⚠️ 顺带:turso 的 upsert() 声明 Promise[Record[string, any]] —— 不是 any 掩码(null 臂不在其中),但也不是契约的 Record[string, unknown]。卡面「记下、不计入」是对的;⛔ 修的时候顺手核一下要不要一并对齐,别默认它没事。

⭐ 分卡建议(卡面自提,上一席采纳,我原样传给排程)

findOne() 可能值得单独一张卡。理由是本卡自己写的那句,它同时也是这类修复的产出定义:

a reader that dereferenced the any surfaces as a real error, which is the finding

⇒ findOne() 是全系统最热的读,它的 null 臂最可能在消费者闭包里炸出真实的缺失检查。⇒ 若接手方先做 findOne() 一门、把闭包里炸出来的东西各自立卡,比五门一起改更能把价值拿出来。⛔ 分诊席不拆卡(拆卡是车道排程的事),只把建议记在这里。

普查结论(已测,⛔ 不必重推)

sql-driver.ts 共 9 处 Promise[any]:6 个是 IDataDriver 门,1 个已被 #14438 解掩,余 5 个(findOne · create · bulkCreate · execute · explain),另 2 个是非门助手(analyzeQuery · aggregate)。

⚠️ 其中 execute() 值得单说:契约声明的是 Promise[unknown],而类上写成 any —— ⇒ 这是把契约自己的 unknown 擦成了 any,比「没写类型」更主动。

SqliteWasmDriver 不覆盖任何一门,全部继承自 SqlDriver ⇒ 修好基类它自动跟上(与 turso 相反)。

p2 判据(原样保留)

⛔ 不是 p1:运行期行为完全正确,tsc 也不会报错(显式 any 结构上满足加宽后的契约);受害的是下游类型安全,且只在消费者真的解引用那个 any 时才变成运行期缺陷。

⛔ 不是 p3:它是已发布的 .d.ts,对每一个消费者说假话 —— 持有 SqlDriver / TursoDriver / SqliteWasmDriver 的读者被告知 findOne() 永不返回 null。⭐ 而最要紧的一句:一个刚学会「驱动门已经收窄了」的读者,在六个里错五个。

修法形状(#14438 已立):逐门换成契约类型 + 包内 tsc 程序里加类型级钉子(IsAny = false、Equals 契约形状)+ 跑消费者闭包的 typecheck。changeset 两个包各 minor(已发布 .d.ts 收窄,PR #14434 的惯例)。

⛔ 边界照抄:driver-memory / driver-mongodb 在 #5499 冻结下且已无 Promise[any] 门,⛔ 不在本卡;driver-memory 余下的 find/findOne/create 是 #14435。

⛔ 分诊席边界:不认领、不派发、不写码、不合并、不裁决。

---

Generated by Claude Code

[claude]

Claim: PM loop round 1
Session: session_01XTBcV7zZHmokdyQgXjbyEU
Branch: claude/issue-15267-sql-driver-declared-doors
Clause-②: no

(Declaration line added by the claiming seat. It was missing from the original claim — the ruling below argued clause ② in prose and never wrote the machine-readable line, so check-clause2-carriers.mjs --pair read NO DECLARATION and exited 4. A missing reading is not a declared no. The reading itself is unchanged: this card narrows existing published members and adds no schema key, closed-set member, published export or registry entry, so the C5 widening-tell limb has nothing to collide with.)

Dispatched by the domain:engine execution PM seat. The dev inherits this assignee and this claim and posts no second one.

Seat rulings, decided before dispatch

1. Scope: the five SqlDriver doors plus TursoDriver.create(). The two non-doors stay as they are.
findOne, create, bulkCreate, execute, explain on packages/drivers/driver-sql/src/sql-driver.ts, and driver-turso's own override async create(...). analyzeQuery() and aggregate() are not on IDataDriver — the card's own census says so. ⛔ Leave them alone; a wider diff is a wider review.
Each door takes the type packages/spec/src/contracts/data-driver.ts already declares for it. ⛔ Do not edit packages/spec/ — that surface belongs to the domain:spec seat, and this card does not need it changed: read it, match it, cite it.

2. Semver grade: patch. Clause ② does NOT apply.
The contract already declares these returns; the classes publish Promise<any> over the top of them. Bringing the annotations back to the declaration repairs an implementation that silently violated its own published declared type — the patch rung. It does not widen an accept set and does not enlarge the published surface. State this reasoning in the PR body. Do not write Clause-②: yes and do not hang needs:contract-review.
⚠️ If a door's contract type turns out not to already be declared narrower — so that your change would be the first place the narrower type is published — that door is a different rung. Stop and report before writing the changeset rather than grading it yourself.

3. Region fence, measured — not assumed.
PR #17221 is open against sql-driver.ts and has not landed. Its hunks are @@ -9473,7, @@ -9589,10, @@ -9641,11 — all inside lines 9473–9673. Your five sites measure on origin/main at 6055 (findOne), 6067 (create), 7888 (bulkCreate), 8433 (execute), 9241 (explain) — the highest is 232 lines clear of the fence.
⛔ Stay out of lines 9460–9690 of that file. If a site turns out to fall inside it, stop and report.

4. #14438 is the precedent, and it is on the record.
That card narrowed update() on the same class. Read what it did and match its shape — changeset grade, test shape, how it described the change. If #14438's landed grade contradicts ruling 2, the recorded precedent wins over this order — follow it and say so in your report.

Locate by symbol, not by line

Every line number above was measured on origin/main at dispatch time and drifts with each landing. Find the methods by symbol.

Definition of done

Draft PR, green, changeset graded per ruling 2, tests that fail before and pass after for at least the null-arm doors (findOne), and a PR body stating ruling 2's reasoning and citing the contract lines by symbol.

---

Generated by Claude Code