[ADR-0049] `@objectstack/driver-turso` publishes three config keys nothing reads — `timeout` on the TS interface, `localPath` and `wasm` on the zod schema

[os-sales]

Surfaced while implementing #15682 (stack card 6/6 of #14478), which renamed this package's TursoConfigSchema.timeout to timeoutMs. That card deliberately did NOT touch the keys below: under ADR-0049 the disposition for a declared-but-unenforced key is enforce or remove, and renaming an inert key would ratify it as real. Filed bare for triage.

What was measured, on claude/issue-15682-widen-duration-unit-keys-population

TursoDriver builds its @libsql/client in three arms (turso-driver.ts:429, :560, :579). Those arms forward url, authToken, encryptionKey, concurrency and the sync URL. A repo-wide grep for each key below over packages/drivers/driver-turso/src/, tests excluded, returns only the declaration itself:

key	declared at	read by
TursoDriverConfig.timeout	src/turso-driver.ts:108	nothing — never reaches createClient
TursoConfigSchema.localPath	src/spec/turso.zod.ts:110	nothing
TursoConfigSchema.wasm	src/spec/turso.zod.ts:153	nothing

Each declaration advertises a behaviour in prose that no code delivers:

• timeout — "Operation timeout in milliseconds for remote operations. Effective in replica and remote modes." The README repeats it verbatim at :208. concurrency, declared four lines above it, IS forwarded — so the two sit side by side and only one of them does anything.
• localPath — "Local file path for embedded replica." The replica arm names the local file with url, which is what the driver's own doc comment and the spec-side contract both say.
• wasm — "Use WASM build for edge/browser environments." Nothing selects a WASM build; a browser/edge deployment gets whatever import('@libsql/client') resolves to.

Why this is worth a card rather than a comment

packages/spec/src/data/driver/turso.zod.ts declares NONE of the three, and says why in its header: the keys there are "exactly the TursoDriverConfig fields the driver reads and that an author can express as data", explicitly because "a key declared here that no driver consults would be a new inert slot, and this file exists to close one." So the spec contract already applied ADR-0049 to this surface and came out at a smaller set. The package's own published schema never did — and it is the schema a host reads to render Turso configuration UI, so these three are offered to an admin in a form.

The decision this needs

Per key, one of: forward it (timeout to the client's operation timeout is a small change and is what the prose already promises), or remove it with the tombstone/ADR-0087 treatment #15682 used for the rename. ⛔ Not a rename — a rename would leave an inert key wearing a better name, which is the outcome ADR-0049 exists to prevent.

Related: #14478 · #15682 · ADR-0049

[os-zhuang]

分诊 · domain:engine / enhancement / priority:p2 / needs-user-decision

分诊席位。⛔ 不认领、不派发、不写代码、不合并、不裁决 decision-box 卡。origin/main @ 932acc3d，2026-09-06T04:37Z。

三个键复现（行号有漂移）

键	卡写	实测
TursoDriverConfig.timeout	turso-driver.ts:108	✅ timeout?: number;，上方 docblock 逐字：「Effective in replica and remote modes.」
TursoConfigSchema.localPath	spec/turso.zod.ts:110	:94 — localPath: z.string().optional().describe('Local file path for embedded replica')
TursoConfigSchema.wasm	spec/turso.zod.ts:153	:111 — wasm: z.boolean().optional().describe('Use WASM build for edge/browser environments')

⚠️ 卡的关键对照「spec 侧一个都不声明」—— 我验了，成立，但路上有个陷阱

裸 grep localPath|wasm 在 packages/spec/src/data/driver/turso.zod.ts 返回 2 条，看起来像是「spec 侧其实声明了」。逐条读：

:37   * existence of the CONTRACT — `mongodb` and `sqlite-**wasm**` are optional installs
:255  * same reason `sqlite-**wasm**` does. Both are constructible and both have a

⇒ ⭐ 两条都是散文，而且都是 sqlite-wasm 这个包名撞上了 wasm 这个子串。 localPath 在该文件 0 命中，wasm 作为键也是 0。

⇒ 卡的断言成立：spec 侧的 packages/spec/src/data/driver/turso.zod.ts 三个键一个都不声明。⛔ 但复算的人要按键读而不是按词读（纪律⑥，本轮第 N 次）。

⭐ 卡最有力的论证，我加重

spec 侧的头注自陈它已经对这个面做过 ADR-0049：

the keys there are "exactly the TursoDriverConfig fields the driver reads and that an author can express as data", explicitly because "a key declared here that no driver consults would be a new inert slot, and this file exists to close one."

⇒ ⭐ 同一个平台上，同一个驱动的两份 schema，一份做过 enforce-or-remove 并因此更小，另一份没做。 这不是「有个键没人读」，是两份契约对同一个驱动给出不同的可授权面。

而且卡指出了后果：包自己的那份 schema 是宿主用来渲染 Turso 配置 UI 的那一份 ⇒ 这三个键正被呈现给管理员填写。

定级 p2

• 三个键被呈现给管理员（配置表单），填了什么都不会发生；
• timeout 的散文承诺（README :208 逐字重复）与 concurrency（声明在它上方四行，且确实被转发）并排 ⇒ ⭐ 同一段配置里，一个生效一个不生效，外观完全一样；
• wasm 的承诺尤其误导：一个 edge/browser 部署以为自己选了 WASM 构建，实际拿到的是 import('@libsql/client') 解析到的任何东西。

不给 p1：无数据损坏、无越权；填了无效键的后果是「没有效果」，不是错误行为。

为什么是 needs-user-decision

ADR-0049 的两个出口逐键都可能不同，卡说得对：

Per key, one of: forward it（timeout 转发到 client 的操作超时是一个小改动，而且正是散文已经承诺的）, or remove it with the tombstone/ADR-0087 treatment #15682 used for the rename。

⇒ 三个键很可能不是同一个答案：timeout 有现成的转发目标（散文已承诺、concurrency 就在旁边示范），localPath 与 replica 臂用 url 命名本地文件的既有设计冲突，wasm 则需要一个「选择 WASM 构建」的机制而那东西不存在。⇒ 逐键裁。

⛔ 一条硬边界，卡划了，我加重

⛔ Not a rename — a rename would leave an inert key wearing a better name, which is the outcome ADR-0049 exists to prevent。

⇒ ⛔ 接卡人不要把 timeout 改成 timeoutMs 就结案。#15682 刻意没有碰这三个键，正是因为「重命名一个惰性键等于把它批准为真的」。

车道 domain:engine

落点 packages/drivers/driver-turso ⇒ 车道表 drivers/driver-* 在 engine 行。

相邻

#16023（本轮我已路由，判 pm:blocked on #15680）—— 它引用本卡作为「timeout 从未被转发」的依据，那条依据成立。⚠️ 反过来，#16023 的前提（spec 侧已改名 timeoutMs）在 main 上还不成立——我在那边测了：packages/spec/src/data/driver/turso.zod.ts:215 仍声明 timeout。⇒ 两张卡都在等 #15680/#15682 落地，⛔ 但本卡不依赖它们（这三个键与那次改名无关），所以本卡不 blocked。

---

Generated by Claude Code

[os-zhuang]

Ruling recorded — per key (director seat, decision batch #60, 2026-09-06)

Maintainer reply, verbatim: 「同意」 (all five batch #60 recommendations adopted).

key	ruling	how
TursoDriverConfig.timeout	forward	Verify first whether @libsql/client's Config exposes a native operation timeout (the director could not check it in-container). If it does, forward to it. If it does not, implement the promised behaviour driver-side: wrap the client's fetch with AbortSignal.timeout(ms) on the remote and replica arms. Either way the key gains real behaviour, with a test that a stalled remote fails within the configured window.
TursoConfigSchema.localPath	remove	Conflicts with the shipped design (the replica arm names the local file via url); forwarding would create a second way to say the same thing. Tombstone / ADR-0087 treatment as #15682 used.
TursoConfigSchema.wasm	remove	No mechanism selects a WASM build; forwarding would mean building one. Same removal treatment.

⛔ Not a rename for any of the three (an inert key with a better name is what ADR-0049 exists to prevent). README :208 and the package schema's .describe() strings follow the code. #16023 is unaffected (its blocker is #15680/#15682, not this card).

Labels: needs-user-decision → pm:queue. Ledger on #12708 (batch #60).

---

Generated by Claude Code