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

[os-zhuang]

Restart-when: any PR touches sqliteCanonicalDatetimeSql or backfillCanonicalDatetimes in packages/drivers/driver-sql/src/sql-driver.ts (price the backfill-SET-side guard, NOT the cloud#1005-rejected shared-read heuristic), or unresolvedEpochTextRows counts non-zero on real data, or a bare-numeric-TEXT Field.datetime site is reported

观察项,不是今天有人会撞上的缺陷 —— 在做 #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)。

---

Generated by Claude Code

[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

[claude]

Findings triage round (#4949 discipline): HOLD maintained (finding kept), domain stays domain:drivers. Stale-premise check @ origin/main 80f7dc6.

The file moved — the function did not

packages/drivers/driver-sql/src/sql-driver.ts did change since the 20:59Z reading-correction: acf34e32 (#6050 / PR #6142, 2026-08-07T03:44:09Z, "refuse an undefined filter comparand before any emitter or guard reads it"). Read the patch rather than the file list, because restart condition 2 is about one function, not the file:

• fix(drivers): undefined 比较数一律拒收 —— 闸落在任何发射器/守卫之前,两个毛病同闸消灭 (#6050) #6142 adds a refusal gate and its doc block around sql-driver.ts:887 plus two new test files (sql-driver-undefined-comparand-refusal.test.ts, and the turso-side pair), and touches driver-turso/src/remote-transport.ts;
• sqliteCanonicalDatetimeSql (:6079) and backfillCanonicalDatetimes (:4118) are untouched — the else branch this issue is about is still coalesce(strftime('%Y-%m-%dT%H:%M:%fZ', col), col), and the call sites that wrap it (:4130, :4503, :6247, :6267, :6412) are unchanged in shape.

⇒ restart condition 2 is NOT triggered. Recorded explicitly so the next round does not re-measure this commit: a sql-driver.ts commit in the log is not by itself a trigger for this issue.

The other two conditions

1. No real-world "a Field.datetime column holding bare-numeric TEXT" site has been reported (remote/Turso customer data or a migration ticket) — no signal.
2. The write-down surface has not widened again — feat(driver-turso): remote 模式补 canonical 时间列 backfill 通道(分批、可恢复、完成标记) (#5770) #6006 was the widening this issue already accounts for (see the 20:59Z correction), and nothing since has extended backfillCanonicalDatetimes.

Freeze-face check (#5499)

Unchanged: the landing site is driver-sql (surfaced through the driver-turso remote face), which is not inside the 2026-08-05 driver-memory / driver-mongodb investment freeze ⇒ normal triage, no pm:on-hold.

Verdict: HOLD

The three reasons stand: reaching the shape still requires dirty data (a legal canonical spelling always carries - / : / T / Z), local's NUMERIC affinity still routes around it and only remote/TEXT is reachable, and the fix direction still collides with the maintainer's 2026-08-03 cloud#1005 refusal of heuristics inside the shared read expression. The filer's preferred shape (⛔ do not touch the shared read expression; add a migration-window guard on the backfill SET side, reusing #6006's unresolvedEpochTextRows counter and its 1e12 ≤ v < 4102444800000 band) remains the one to price when a real pull appears.

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

---

Generated by Claude Code

[os-zhuang]

PM 分诊 —— 维持 parked，不派。但把「否决覆盖到哪」写清楚

采纳本单自己的建议（「不建议在没有真实业务拉动前动手」）。定级 observation，挂 status:parked，不进 pm:queue。

理由三条，都是既有依据，没有新判断：

1. 触达需要脏数据 + 单侧路径。 要有「Field.datetime 列里存着裸数字 TEXT」，而合法的 canonical 拼写一定带 - / : / T / Z。且本单已实测 local / knex datetime 是 NUMERIC 亲和，入库即转 INTEGER、走 epoch 分支绕开了；只有 remote（mapFieldTypeToSQL 声明为 TEXT）这一侧命中。
2. 不是回归。 误读自 [17.0.0-rc.0] SQLite datetime window filters return empty: filter comparands coerced to epoch-ms while writes store ISO TEXT #3912 起就在，fix(analytics): $ne / $nin / $notContains 在 Cube 面保留无值行 (#5298 第二批) (#5977) #6004 / feat(driver-turso): remote 模式补 canonical 时间列 backfill 通道(分批、可恢复、完成标记) (#5770) #6006 没有改变任何查询答案 —— backfill 写下去的正是读路径本来就返回的值。这一点本单自己已经讲清楚了，我原样采纳。
3. 共享表达式加启发式这条路已被否决（维护者 2026-08-03，cloud#1005）：公共契约 + 每次读都跑 + 会误读合法的数字字符串列。

但请注意否决的边界 —— 它没有覆盖 backfill 守卫这一支

这一条单独写下来，是为了防止将来有人把本单读成「已经裁过了，不用再想」：

cloud#1005 否掉的是在共享读表达式里加启发式。而本单末尾提的是另一个形状 —— 在 backfill 的 SET 侧加一道「不把 strftime 的儒略日结果写下去」的守卫，读路径原样不动。两者的成本结构完全不同：

	被否决的方案	backfill 守卫
作用面	公共契约、所有读	纯迁移期、一次性
执行频率	每次读都跑	每列一次
误伤面	会误读合法的数字字符串列	可按声明类型收窄

所以 cloud#1005 的否决不构成对 backfill 守卫的否决。将来若真出现业务拉动，起点应是这一支，而不是重新去撞已被否掉的那一支。

真正值钱的那句话，本单已经说了

读是临时的，backfill 是永久的。

误读本身不新，变的是原始字节还在不在。这是本单唯一不可逆的部分，也是将来若要重估优先级时该看的那个变量 —— 不是「答案对不对」（那没变），而是「还能不能恢复」。

重估触发条件（写下来，免得靠人记）

出现下列任一情形，请把本单从 parked 取回重估，不必再走一次分诊：

• 有真实业务在 remote / TEXT 亲和侧对 Field.datetime 列跑 backfill；
• unresolvedEpochTextRows 在真实数据上有非零计数（feat(driver-turso): remote 模式补 canonical 时间列 backfill 通道(分批、可恢复、完成标记) (#5770) #6006 那条恢复限带 1e12 ≤ v < 4102444800000 正是为把这类小数字留出来并计数的）；
• 出现任何一例原始字节已被儒略日误读覆盖、且需要恢复的报告。

---

Generated by Claude Code

[claude]

Triage (state repair): finding + status:parked → pm:on-hold. domain:drivers and priority:p3 unchanged.

Date: 2026-08-07. Why the change: this card carried two hold mechanisms at once, and they interfered. status:parked is excluded from the triage sweep, so a card holding both could never reach a findings round to be graded — it was held by a label that guarantees it is never looked at again. pm:on-hold is the state machine's own way to say the same thing, and it says it correctly: a decision was made, do not dispatch, do not nag, wait for the restart condition.

Reason for the hold — adopted wholesale from the lane's 15:17Z ruling and the three prior findings rounds, not re-derived: (1) reaching the shape needs dirty data — a bare numeric TEXT value in a Field.datetime column, where every legal canonical spelling carries - / : / T / Z; local/knex NUMERIC affinity converts such values to INTEGER and takes the epoch branch, so only the remote/TEXT side is reachable; (2) it is not a regression — the misread dates from #3912, and #6004 / #6006 changed no query answer; (3) the neighbouring fix direction (heuristics inside the shared read expression) was already ruled out by the maintainer on 2026-08-03 in cloud#1005.

Restart conditions (any one ⇒ pull it back and re-price; no re-triage needed):

1. a real site appears — remote/Turso-side customer data or a migration ticket with bare numeric TEXT in a Field.datetime column;
2. sqliteCanonicalDatetimeSql has to be touched for another reason, in which case price the filer's preferred shape opportunistically;
3. the backfill's write surface widens again (⛔ feat(driver-turso): remote 模式补 canonical 时间列 backfill 通道(分批、可恢复、完成标记) (#5770) #6006 does not count — it is the widening this card already priced).

⚠️ Boundary preserved verbatim, because it is the part most likely to be misread as "already decided": cloud#1005 rejected heuristics in the shared read expression. It did not reject a guard on the backfill's SET side that leaves the read path untouched — different blast radius, different frequency, different mis-fire surface. Anyone restarting this card should start from that branch, not from the rejected one.

No time window is set: the freeze that shapes this area is indefinite, and an invented date would only manufacture a false expiry.

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

---

Generated by Claude Code