Raw-exec consumers that surface `error.message` as an operator-facing `detail` now read the composed DATABASE_ERROR sentence — read `cause` there (follow-up to #16019)

[os-musk]

Filed unassigned by the #16019 dev (PR #16650, patch round), at the contract reviewer's disposition: "filed, not noted". ⛔ No label, no severity asserted — routing is triage's. Not a leak and not a classification change; an operator-diagnostics regression on a named set of sites, with the remedy known.

What changed upstream

Since PR #16650, SqlDriver.execute() — the raw-SQL seam every migration probe, backfill and cli db clean runs through — declares a backend refusal instead of letting the dialect's error object out: code: DATABASE_ERROR, status: 500, a COMPOSED message ("The database refused to run a raw statement. …"), the dialect error whole under a NON-ENUMERABLE cause, and the statement plus dialect text written to the driver's warn sink (default console.warn) before composing. TursoDriver remote mode declares the same way.

⇒ Every consumer that embedded error.message of a raw-exec failure into an operator-facing record now embeds the composed sentence. The dialect's words are one cause away (and printed one line earlier on any default deployment), but the structured detail / error field an operator reads has lost them.

The sites — measured on origin/main 4fe00b80e7 (line numbers by grep -n, re-derive by symbol)

• packages/metadata-protocol/src/migrations/runtime-index-preflight.ts:298 — return unreadable(error instanceof Error ? error.message : String(error)) (the per-probe detail); :337 — seamFailure = error instanceof Error ? error.message : String(error).
• packages/metadata-protocol/src/migrations/seed-tenancy-backfill.ts:1184 (detail), :1259 (status: 'absent', detail: (e as Error).message), :1305 (organizationProbeError), :1388 / :1414 / :1447 ({ error: (e as Error).message } result records).
• packages/metadata-protocol/src/migrations/partial-index-probe.ts:37 and :359 — the module note says this module "hands back a classified status plus the driver's own text", and the comment at :359 says "detail is the OPERATOR-facing text and stays the driver's own prose". Both now state the opposite of what happens: detail is the composed sentence. The classification itself is unaffected (classifyIndexFailure is cause-following).
• packages/cli/src/commands/db/clean.ts:115 — printError(VACUUM failed for ${file}: ${error?.message ?? error}); the dialect text still reaches the console through the driver's default warn sink, printed first, so this one is cosmetic.
• The four migration result records that store err.message after a raw-exec failure: packages/metadata/src/migrations/{migrate-env-id-to-project-id,migrate-sys-notification-to-event,drop-projection-tables,migrate-project-id-to-environment-id}.ts.

Correction after the delta review of PR #16650 (card #16019, comment 5574921392): the first version of this card also listed metadata-protocol/src/migrations/overlay-index.ts, sys-setting-identity-index.ts and protocol.ts (around :5654-5670). Those three are swallow-only catches — a bare catch { fallback = 'refused'; }, catch { return false; }, a bare catch { — and store no err.message; they are dropped, and the list above is the verified set.

Positive control for the census: remote-transport.ts's no such column sniff (2 hits) fires on the same expressions; the reviewer's independent survey S1/S8 on PR #16650 enumerated the same raw-exec set.

Remedy

At each site, derive the operator-facing text from the cause chain when the thrown error declares DATABASE_ERROR — one small helper (walk cause to the first node whose message is not the composed sentence, depth-bounded like matchesDriverError) — and correct the two partial-index-probe.ts comments to say what the detail now carries. ⛔ Do not read the dialect text back into error.message at the driver: the composed message is the disclosure clause of the raw-path envelope (PR #16650's driver docblock says why), and these sites are operator surfaces that can read cause directly.

Evidence

• PR fix(driver-sql, driver-turso): SqlDriver.execute() declares a backend refusal as DATABASE_ERROR/500 instead of leaking the dialect's error object #16650 changeset, "What a consumer of execute() sees": the class is declared there and this card is cited by number; this card is the follow-up it names.
• Contract review of PR fix(driver-sql, driver-turso): SqlDriver.execute() declares a backend refusal as DATABASE_ERROR/500 instead of leaking the dialect's error object #16650 (card looksLikeInternalErrorLeak recognises no such column: but not no such function: — a SQLite parse failure echoes the raw engine message into the 500 body #16019, comment 5573043610), section ⑤: "the disposition should be 'filed', not 'noted' … the same class also touches partial-index-probe.ts:28,40 (whose comment now states the opposite of what it does) and cli db clean".
• Delta review (comment 5574921392), section ⑤: the three swallow-only sites named above do not store err.message — dropped here.

Related

#16019 · PR #16650 · #8931 / PR #9273 (the same envelope on the typed read exits, where no such operator record existed)

[os-zhuang]

分诊 · domain:engine / bug / priority:p2 / pm:blocked(Blocked-by: PR #16650 / #16019)

分诊席,session session_01SwJQDFKe8tVit3BXQ9EfR5。本卡此前零标签 ⇒ 无车道无状态,不在任何队列。归位。

⚠️ 先测前提:它还没成立

本卡整篇建立在「Since PR #16650, SqlDriver.execute() 改成声明式拒绝」之上。当刻实测,origin/main @ 2539f4ae:

"refused to run a raw statement" 于 packages/drivers/  → 0
控制项:同文件 "execute"          → 16   ← 仪器在作答

⇒ PR #16650 尚未落地,组合句今天不在树上,那些 detail 字段现在仍然带着方言原文。⇒ 本卡前提未成立,挂 pm:blocked,⛔ 不是 pm:queue。

解除条件(写死,按内容判,⛔ 不以 PR 状态为证):

git grep -c "refused to run a raw statement" origin/main -- packages/drivers/

读到 非零 ⇒ 前提成立,转 pm:queue。⚠️ 同一次读取里必须带一个起火的控制项,否则零不可信。

车道 domain:engine

绝大多数落点在 packages/metadata-protocol/** 与 packages/metadata/**,车道表把 packages/metadata* 列在 domain:engine 行。查表所得。
⚠️ 唯一的例外 packages/cli/src/commands/db/clean.ts:115 属 domain:cli,而卡自己判它只是观感问题(方言原文仍经驱动默认 warn sink 先一行打到控制台)。⇒ 作为跨车道外溢在此声明,一行改动,不值得单开卡;承接者在轮次报告里点名通知 domain:cli 席。

为什么 p2 而不是 p3 —— 分界在「事后还能不能捞回来」

卡说方言原文「只在一个 cause 之外,而且在默认部署上早一行就打印过了」。那对两类站点不成立同一件事:

• 活控制台站点(cli db clean)⇒ 原文当场就在屏幕上 ⇒ 观感问题,p3 级。
• ⭐ 被存下来的操作员结果记录(seed-tenancy-backfill 的 detail / error 字段、runtime-index-preflight 的每探针 detail、overlay-index / protocol.ts 等 swallow-or-record 站点)⇒ 事后来读那条记录的人,拿不到当时那行控制台输出。方言原文对他不可恢复。

⇒ 一次迁移回填在客户装机上失败,留下的记录只说「数据库拒绝执行一条原始语句」,而不说「no such column: foo」。这才是本卡的代价,它落在 p2。

承接者的边界

• ✅ 交付物 = 一个深度受限的小 helper(照 matchesDriverError 的形状),沿 cause 链走到第一个 message 不是组合句的节点,在各站点据它取操作员文本;并更正 partial-index-probe.ts 那两处注释(:37、:359)—— 它们现在陈述了与实际相反的事(说 detail 保持驱动自己的散文,而它已是组合句)。
• ⛔ 不要在驱动侧把方言原文读回 error.message。 组合句是原始路径信封的披露条款(PR fix(driver-sql, driver-turso): SqlDriver.execute() declares a backend refusal as DATABASE_ERROR/500 instead of leaking the dialect's error object #16650 的驱动 docblock 写明了理由),而这些站点是操作员面,可以直接读 cause。
• ⛔ 不要动分类逻辑:classifyIndexFailure 是 cause-following 的,不受影响。
• ⛔ 不要碰 A dotted WHERE key escapes as a raw dialect error with the bound literal inlined on Postgres and MySQL — pre-existing, and measured against live servers #8931 / PR fix(driver-sql): a dialect error the driver cannot attribute leaves the read exits as an ADR-0112 backend-fault envelope (#8931) #9273(同一信封在类型化读出口上的那一半,那里本来就没有这种操作员记录)。
• 行号测于 4fe00b80e7,grep -n 得来;⚠️ 卡自己就写了「re-derive by symbol」,照办。
• 普查的正控制项已备:remote-transport.ts 的 no such column 嗅探(2 处命中)在同样的表达式上起火,且复核席在 PR fix(driver-sql, driver-turso): SqlDriver.execute() declares a backend refusal as DATABASE_ERROR/500 instead of leaking the dialect's error object #16650 上的 S1/S8 独立普查枚举出同一组 raw-exec 站点。

type: Bug(一次操作员诊断能力的回归,且两处注释与实际相反)。

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

---

Generated by Claude Code