Converging driver-turso's two transports onto one physical column type for Field.json — and the measured reason VALUE_ROUNDTRIP cannot adjudicate it

[claude]

The measurement

While pinning the declared Field.json column-type asymmetry for #12586 (local json, remote TEXT), the pin's ablation performed a convergence — RemoteTransport.mapFieldTypeToSQL's JSON arm changed from TEXT to json, so both transports declare the same physical column — and ran the named instrument against it.

Result, measured on driver-turso at commit db8db7c7:

turso-value-roundtrip-conformance.test.ts 88 passed (88) <- UNCHANGED under convergence
turso-json-column-type-asymmetry.test.ts 4 failed 2 passed

⇒ The VALUE_ROUNDTRIP case-set cannot distinguish a converged driver from today's driver. Every value in the shared table round-trips faithfully either way. The only thing that moved was the new asymmetry pin, which is measuring the declaration and the storage class rather than the round trip.

Why that is a reason to card it, not a reason to do it

The charter on #12586 deferred convergence because the question "why did remote choose TEXT?" is un-measured. This result does not answer that question, and it should not be read as "convergence is safe":

• Converging in the direction the ablation took (remote emits json) gives the remote transport NUMERIC affinity it does not have today. Measured: with the mutation in place, a bare '0123' written into the remote column by raw SQL comes back as the integer 123; today it comes back as the string '0123'. That is the remote half acquiring the exact exposure [finding] driver-sql's SQLite json codec is not round-trip faithful for a string whose content is valid JSON — '123' reads back as a number, and Postgres does not agree #12380 had to defeat on the local half — plausibly the wrong direction.
• Converging the other way (local emits TEXT) is not exercised by anything here and would change what knex declares for every SqlDriver dialect, not just SQLite.
• Either direction changes what new columns are physically declared as on existing deployments, which is a migration question no test in the tree asks.

So the useful content of this card is the negative result: whoever takes convergence on must bring an instrument other than VALUE_ROUNDTRIP, because that one is green on both sides of the decision.

Why a separate card

Disposition 1 was recorded in the triage comment on #12586, and that card is being closed by the PR that lands the declaration and the pin. Without a card of its own the convergence option has no home once #12586 closes. #12586 is not addressed by this card and this card does not supersede it; #11535 tracks the class and is already closed.

Where the pin is

packages/drivers/driver-turso/src/turso-json-column-type-asymmetry.test.ts. Its header carries the instruction this card is the other half of: when convergence is genuinely taken on, delete or invert that pin as part of the change — never edit its expectations to match new output.

Filed unassigned by the os-dev seat that implemented #12586, recording only — not claimed.

---

Generated by Claude Code

---

Generated by Claude Code

[huangyiirene]

Triage: healing a half-annotated card — domain:engine was already right (packages/drivers/driver-turso) and stays; adding the pm-state and type it was missing. Type Task: convergence adds no capability and widens no accept set, and it is not a Bug either — after #12586 landed, the asymmetry is declared and pinned as intended, so nothing is currently violating a contract.

needs-user-decision, and this one is a literal match for the criterion rather than a judgement call: the card states that either convergence direction "changes what new columns are physically declared as on existing deployments, which is a migration question no test in the tree asks." 存量数据/迁移形状 is on the manual floor by name. ⛔ Not proxy-adjudicable at this seat, whatever the prisms below say — the recommendation is an input, never a release.

⚠️ Note for the reader: #12586 closed at 2026-08-27T16:36:00Z, during this triage round. That is the event this card was filed to survive — the card exists precisely so the convergence option keeps a home once #12586 closes — so the timing confirms the filing decision rather than undermining it. The pin it points at is now landed tree state, not pending PR state.

<!-- os-decision-facets -->

一句话问题:同一个声明为 JSON 的字段,在两种连接方式下被存成了两种不同的物理列类型。今天没有任何客户因此丢数据或看到差异,但「两边长得不一样」这件事本身,直到 #12586 之前没有任何东西解释过。

选项 × 真实代价

	做什么	真实代价
A	现在不收敛,保留 #12586 落地的声明与 pin(推荐)	两条通道对同一个声明字段永远物理不同;但已被 pin 记录成有意为之,下一个读到的人不会再当缺陷重报
B	收敛到 remote 也用 json	实测:裸 '0123' 用原生 SQL 写进 remote 列,收敛后读回变成整数 123,今天读回仍是字符串 '0123' —— 客户可感知的后果是一个带前导零的编号或条码字段静默变成数字。这正是 #12380 在 local 半边费力挡掉的暴露面,B 等于把它请回 remote 半边
C	收敛到 local 也用 TEXT	改变 knex 对每一个 SqlDriver dialect 的声明,不只是 SQLite;本卡的实测完全没有覆盖这个方向

B 与 C 共有一项代价:改变已有部署上新建列的物理声明,而树里没有任何测试问过这个迁移形状。

四棱

• ① 项目长远合理性:A 保留一个已记录的特例 —— 今天的分裂有 pin 也有墓碑式说明,不是无主状态;B/C 消除分裂,但都没有测量支撑,且 C 的作用域远大于本卡自己的题目。
• ② 实际业务拉动:零,而且是实测出来的零 —— 88 个值的共享用例集在收敛前后逐项相同(turso-value-roundtrip-conformance.test.ts 88 passed,收敛后不变)。没有客户撞上,没有报告。零拉动 ⇒ 默认 defer。
• ③ 防 AI 犯错:A 最安全。pin 的头部已经写明「真要收敛时删掉或反转这个 pin,永远不要把它的期望改成新输出」—— 这句话防的正是 AI 用「改测试让它变绿」收场。反过来 B 制造的是静默类型转换(前导零变数字),属于最难被发现的一类错。
• ④ 创业阶段不扩散:B/C 都是无拉动的改造,而且各自拖着一个没人问过的迁移问题。

推荐:A(现在不收敛)。回退:若出现任何一例可复现、且可直接归因于该不对称的客户可见缺陷,按 B 或 C 重开 —— 但必须带 VALUE_ROUNDTRIP 以外的仪器。这正是本卡唯一的、也是真正有价值的产出:那套用例集在决定的两侧都全绿,⛔ 它无法裁决方向,拿它当证据是错的。

置信缺口(本分析看不见什么):看不见 remote 当初为什么选 TEXT。#12586 的 charter 推迟收敛就是因为这个问题未经测量,本卡同样没有回答它 —— 若那是一个有意的、记录在别处的决定,B 可能直接出局;若只是疏忽,B 与 C 的取舍要重算。

裁后我会怎么执行(你不用管):裁 A ⇒ 翻 pm:on-hold,Restart-touch: 锚在 packages/drivers/driver-turso/src/turso-json-column-type-asymmetry.test.ts,任何人删除或反转该 pin 即唤醒本卡;裁 B 或 C ⇒ 翻 pm:queue 派 engine 席,派发令强制两件事 —— 非 VALUE_ROUNDTRIP 的仪器,以及一份迁移形状说明。

---

Generated by Claude Code

[os-elon]

Maintainer ruling applied — C′: unify onto the dialect-correct type — SQLite-family JSON columns declare TEXT; server dialects keep native JSON

Source: maintainer, 2026-08-28, live director session (summon #2, session session_016SG9S6V15MqeAgkehDcTwk), batch #3 item 3. The maintainer's direction (「从长远看统一是最好的吧」) plus the mechanism analysis produced a revised shape, adopted verbatim: 「其他接受你的最新建议。」

• Neither of the card's directions is taken as written. B (remote→json) unifies onto the trap side: in SQLite a declared type json matches no affinity keyword and lands NUMERIC affinity — the measured '0123'→123 exposure. C as written (change the shared knex arm for all dialects) would also strip Postgres's native json/jsonb and MySQL's JSON, which are correct and stay.
• C′ adopted: each dialect declares the semantically correct JSON column type. PG/MySQL: native JSON types, untouched. SQLite family (turso local via the shared SqlDriver mapping, plus any sibling SQLite dialects the dev verifies share the arm): JSON columns declare TEXT — what SQLite's JSON1 actually operates on, and what RemoteTransport.mapFieldTypeToSQL already does. The two turso transports converge naturally, onto the side without the affinity trap; the exposure [finding] driver-sql's SQLite json codec is not round-trip faithful for a string whose content is valid JSON — '123' reads back as a number, and Postgres does not agree #12380 had to defeat is removed at the root for new columns.
• Long-term rationale on record: turso's embedded-replica model means the physical schema is decided by whichever side ran DDL — differing mappings make a deployment's physical schema depend on migration provenance. ⚠️ The replica DDL-sync detail is reasoned from the product model, not measured; the dev verifies before relying on it.
• Dispatch fences:
  1. Pre-work verification: knex's actual DDL output for t.json() under the sqlite dialect and the shared mapping's structure (the C′ scope claim rests on it; read, not assumed).
  2. Instrument: ⛔ NOT VALUE_ROUNDTRIP (green on both sides — this card's own negative result). New affinity-level pins: typeof(col) storage-class assertions + raw-SQL '0123' preserved as text, run on BOTH transports.
  3. The [finding] driver-turso puts one declared Field.json in two different physical column types — json on the local transport, TEXT on the remote one — and nothing records that as intended #12586 asymmetry pin (turso-json-column-type-asymmetry.test.ts) is inverted or deleted per its own header — never expectation-edited to match new output.
  4. Changeset (MINOR) states the migration shape: new columns only; existing columns keep their declared type; platform write-path behaviour unchanged ([finding] driver-sql's SQLite json codec is not round-trip faithful for a string whose content is valid JSON — '123' reads back as a number, and Postgres does not agree #12380 pins stay green and stay in force for legacy columns); the visible difference is raw-SQL-only and in the safe direction.
• Labels this stroke: needs-user-decision → pm:queue; domain:engine unchanged. Dispatch guidance: M / opus.

---

Generated by Claude Code