drivers(sql): 共享 canonical 修复表达式把「裸数字文本」当儒略日读,backfill 会把这个误读写进盘里(观察项)

[os-zhuang]

观察项,不是今天有人会撞上的缺陷 —— 在做 #5770(driver-turso remote backfill,PR #6006)时实测到,顺手记录。不建议在没有真实业务拉动前动手。

实测

SqlDriver.sqliteCanonicalDatetimeSql 的 else 分支是 coalesce(strftime('%Y-%m-%dT%H:%M:%fZ', col), col)。SQLite 的 strftime 接受裸数字并按儒略日解释,于是一个 Field.datetime 列里的裸数字文本会被读成公元前的日期(better-sqlite3 13.0.2 实测):

'12'                       -> -4713-12-06T12:00:00.000Z
'0'                        -> -4713-11-24T12:00:00.000Z
'1999'                     -> -4707-05-15T12:00:00.000Z
'2026'                     -> -4707-06-11T12:00:00.000Z
'86400'                    -> -4476-06-15T12:00:00.000Z
'2440587.5'                -> 1970-01-01T00:00:00.000Z   (儒略日纪元,确实是这个语义)
'2026-08-06'               -> 2026-08-06T00:00:00.000Z   (正常)
'2026-08-06T00:00:00.000Z' -> 2026-08-06T00:00:00.000Z   (正常,不动点)

coalesce 的兜底在这里帮不上忙:strftime 不返回 NULL,它返回了一个自信的错误答案,所以「解析不了的值原样保留」这条设计意图在这一支上不成立。

为什么今天基本撞不上

需要「Field.datetime 列里存着裸数字 TEXT」。两种 affinity 的行为不同:

• local / knex datetime 列是 NUMERIC 亲和:'12' / '2026' 入库即被转成 INTEGER(实测 typeof 为 integer),于是走的是表达式的 integer/real 分支(按 epoch 毫秒),不是儒略日分支。所以 local 基本绕开了。
• remote / RemoteTransport.mapFieldTypeToSQL 把时间列声明为 TEXT:值保持 TEXT,儒略日分支就会命中。这是唯一比较容易到达的一侧。

而要有这种值,本身就得是脏数据(合法的 canonical 拼写一定带 - / : / T / Z)。

值得记一笔的地方:读是临时的,backfill 是永久的

误读本身自 #3912 起就存在,但那时它只是每次读临时算出来,盘上的原始字节还在。backfillCanonicalDatetimes 的 SET 表达式就是同一个表达式,所以它会把这个儒略日误读写回磁盘,原值不可恢复。PR #6006 让 remote 也有了 backfill,于是这条路径在 remote 侧也从「临时误读」变成了「落盘」。

需要说清楚的是:#6004/#6006 没有改变任何查询答案 —— backfill 写下去的正是读路径本来就返回的值(这也是那个模块的核心不变量)。变的只是「原始字节是否还留着」。#6006 的 epoch 恢复限带在 1e12 ≤ v 小于 4102444800000,正是为了不去碰这类小数字,把它们留给共享表达式并计入 unresolvedEpochTextRows。

如果将来要处理

倾向不要在共享表达式里加启发式 —— 维护者 2026-08-03 在 cloud#1005 已就近似的提案裁过否决(公共契约 + 每次读都跑 + 会误读合法的数字字符串列)。真要做,更像是在 backfill 的 SET 侧加一道「不把 strftime 的儒略日结果写下去」的守卫(纯迁移期、一次性、可按声明类型收窄),读路径保持原样。

判断留给 PM/维护者分诊。

参考:packages/drivers/driver-sql/src/sql-driver.ts 的 sqliteCanonicalDatetimeSql / backfillCanonicalDatetimes;ADR-0053 storage-form 轴(#4191)。

[claude]

发现分诊:持有(finding 保留)+ 补 domain:drivers

判级 — 持有。同意立单人的自评:到达此形状需要「Field.datetime 列里存着裸数字 TEXT」,而合法 canonical 拼写必带 - / : / T / Z,即前提是脏数据;local 侧 NUMERIC 亲和已把它绕开,只有 remote/TEXT 一侧可达。且修法方向上已有一条同源裁决:维护者 2026-08-03 在 cloud#1005 就「在共享读表达式里加启发式」的近似提案裁过否决(公共契约 + 每次读都跑 + 会误读合法数字字符串列)。在没有真实业务拉动前动手,大概率是重跑一遍那次已经付过的讨论。

域 — 落点 packages/drivers/driver-sql/src/sql-driver.ts(sqliteCanonicalDatetimeSql / backfillCanonicalDatetimes)⇒ domain:drivers。

⚠️ 冻结面核验(#5499) — 不在冻结面内。维护者 2026-08-05 的投入冻结只覆盖 driver-memory / driver-mongodb 两族;本单落点是 driver-sql(经 driver-turso remote 面暴露),按正常规则分诊,不挂 pm:on-hold。

重启条件(三选一,任一成立即回发现轮重判):

1. 出现真实的「datetime 列存裸数字 TEXT」现场(remote/Turso 侧客户数据或迁移工单);
2. sqliteCanonicalDatetimeSql 因其它原因要动时顺手评估 —— 立单人已给出倾向修法(不改共享读表达式,只在 backfill 的 SET 侧加一道「不把 strftime 的儒略日结果写下去」的迁移期守卫),该方向与 cloud#1005 的否决不冲突;
3. backfillCanonicalDatetimes 的落盘面再次扩大(本单的严重性完全来自「读是临时的、backfill 是永久的」这一层)。

在飞提示 — PR #6006(#5770,remote backfill)仍 open。它正是把这条路径从「临时误读」变成「落盘」的那次改动;若将来做守卫,应在其落地后、并复用它已有的 unresolvedEpochTextRows 计数与 1e12 ≤ v < 4102444800000 的限带(立单人已说明该限带正是为了不碰这类小数字)。

过时前提检查 — origin/main 44106d9:sql-driver.ts 的两个函数均在,正文所述 else 分支形状未变。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[claude]

读数订正(不改判级,finding 持有维持)—— 本轮发现分诊的过时前提检查产物。

本单 14:56:15Z 的分诊评论在「在飞提示」一节写道:

PR #6006(#5770,remote backfill)仍 open。

这条读数在写下时已经过期 34 秒:PR #6006 实际 MERGED 于 2026-08-06T14:55:41Z。按 SKILL notes 7(诊断结论一旦公开发出又被推翻,更正要发在同样公开的位置),在此订正。

对本单的实际影响 —— 判级不变,但两处前提已翻转

1. 落盘面已经在 main 上了,不再是「即将」:feat(driver-turso): remote 模式补 canonical 时间列 backfill 通道(分批、可恢复、完成标记) (#5770) #6006 让 remote 侧的 backfillCanonicalDatetimes 落地 ⇒ 正文所述「读是临时的、backfill 是永久的」那层严重性已经生效,不是待观察的将来态。⚠️ 但这不触发重启条件 3(「落盘面再次扩大」)—— feat(driver-turso): remote 模式补 canonical 时间列 backfill 通道(分批、可恢复、完成标记) (#5770) #6006 正是正文自己点名的那一次扩大,已计入原判,不构成新信息。
2. 重启条件 2 的前置已满足:该条要求将来做守卫时「复用 feat(driver-turso): remote 模式补 canonical 时间列 backfill 通道(分批、可恢复、完成标记) (#5770) #6006 已有的 unresolvedEpochTextRows 计数与 1e12 ≤ v < 4102444800000 限带」,并写着「应在其落地后」—— 现在已落地,该文件锁已释放,届时可直接在 main 上对着成品形状定价,不必再等。

判级维持持有,三条理由未被上述翻转动摇:① 到达形状仍需「Field.datetime 列里存裸数字 TEXT」即脏数据前提,local 侧 NUMERIC 亲和仍绕开,只有 remote/TEXT 一侧可达;② 修法方向上维护者 2026-08-03 在 cloud#1005 对「在共享读表达式里加启发式」的近似提案已裁否决,该裁决不受本次 merge 影响;③ 真实业务拉动仍未出现。

重启条件(逐条重申,仅第 2 条的前置状态更新,其余原样)

1. 出现真实的「datetime 列存裸数字 TEXT」现场(remote/Turso 侧客户数据或迁移工单);
2. sqliteCanonicalDatetimeSql 因其它原因要动时顺手评估,按立单人倾向的修法(⛔ 不改共享读表达式,只在 backfill 的 SET 侧加迁移期守卫)—— 前置已满足,feat(driver-turso): remote 模式补 canonical 时间列 backfill 通道(分批、可恢复、完成标记) (#5770) #6006 已在 main;
3. backfillCanonicalDatetimes 的落盘面再次扩大(⛔ feat(driver-turso): remote 模式补 canonical 时间列 backfill 通道(分批、可恢复、完成标记) (#5770) #6006 不算,见上)。

冻结面核验(#5499):维持原判 —— 落点 driver-sql(经 driver-turso remote 面暴露),不在 driver-memory / driver-mongodb 冻结面内,不挂 pm:on-hold。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code