`os migrate multi-value-columns` has no arm for a SINGLE-value JSON-class column — its repair wraps every value in a one-element array, so the new #15771 findings are deliberately routed to `remedy_not_recognized` instead

[zhuangjianguo]

Found while implementing #15771 (widening the base-type drift detector to the writer's own JSON-class predicate). Filed unassigned; no severity asserted.

The gap

manualJsonConversionSql (packages/drivers/driver-sql/src/schema-drift.ts) repairs a stale textual column by WRAPPING each stored value in a one-element JSON array — the ELSE json_build_array(col) arm on Postgres, UPDATE ... SET col = JSON_ARRAY(col) WHERE LEFT(col, 1) is not a bracket on MySQL. That is the correct repair for a field whose declared value IS an array, and the wrong one for a field whose declared value is a scalar or an object.

Measured with the command's own planner (planStaleColumnTargets, packages/cli/src/commands/migrate/multi-value-columns.ts) before #15771's message split, on a synthesized single-value file finding carrying the multi-value message:

targets: 1  refusals: 0
dialect: postgres
  ALTER TABLE "proj_task" ALTER COLUMN "doc" TYPE json USING (CASE WHEN "doc" IS NULL THEN NULL
  WHEN "doc" = '' THEN NULL WHEN "doc" LIKE '[%' THEN "doc"::json
  ELSE json_build_array("doc") END)

The stored value for a single-value file field is the JSON scalar the write path produces — measured byte-for-byte on an in-memory SQLite cell, the column holds "file_01HXYZ" including its quotes, identically for the stale varchar(2048) column and the driver's own column. Wrapping that yields a one-element array whose element still carries the quotes. Read back through the driver on the same cell:

ok      : value="file_01HXYZ"          typeof=string  isArray=false
wrapped : value=["\"file_01HXYZ\""]    typeof=object  isArray=true

(The wrap itself is the repo's own live measurement, recorded in manualJsonConversionSql's docblock from Postgres 16.13 and MySQL 8.0.46: a legacy single value becomes ['a']. There is no live Postgres/MySQL cell in this container, so that limb is quoted, not re-measured.)

What #15771 shipped instead, and what is still missing

#15771 does NOT point the new findings at that command. The array-valued half (multiple: true, plus the inherently-multi option types) keeps its message character for character and keeps the remedy. The single-value half gets a message carrying neither the command's name nor the statement, so planStaleColumnTargets recovers no dialect and REFUSES the entry with remedy_not_recognized — the command's own designed branch for a message it cannot read. Nothing wrong is executed, and the refusal's detail already tells the operator to run os migrate plan and apply the finding's statement by hand.

What is still missing is an automated repair for the single-value population, and the finding's message says so in words rather than printing DDL nobody has run. The shape of that repair is a CAST rather than a wrap — rows written through ObjectStack already hold valid JSON text — but writing it is not a change that should ship unmeasured: manualJsonConversionSql's two existing forms are EXECUTED against live servers by schema-drift.base-type-mismatch.test.ts over rows in every state a stale column can be in, and its own docblock records two arms that were corrected only by running an earlier version against a live database.

Options for whoever picks this up

1. Extend the existing command with a value-shape arm — one command, two statement builders, the shape chosen from the finding rather than from the command's name. Costs the command's name accuracy ("multi-value" would no longer describe what it does).
2. A sibling command for the scalar/object population, leaving os migrate multi-value-columns exactly as it is. Costs an operator one more thing to know about.
3. Leave it refused and keep the by-hand route. Costs every affected deployment a manual conversion, which is the status quo driver-sql schema-drift: the json-vs-text type_mismatch finding is keyed to field.multiple only, so a SINGLE-value JSON-class column (file family, STRUCTURED_JSON_TYPES) on a char/text column is never reported — the column a hand-run generated migration creates today #15771 ships.

Either of the first two needs a live Postgres and MySQL cell to land, for the same reason the existing forms did.

Related: #15771 (the detector), #15041 (the VARCHAR(2048)-vs-json-column generator divergence that makes the stale column reachable).

[os-zhuang]

分诊 · domain:cli / enhancement / priority:p3 / needs-user-decision

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

两侧位置复现

packages/drivers/driver-sql/src/schema-drift.ts:768        export function manualJsonConversionSql(dialect, table, column): string {
packages/cli/src/commands/migrate/multi-value-columns.ts:141  export function planStaleColumnTargets(
packages/cli/src/commands/migrate/multi-value-columns.ts:96   reason: 'remedy_not_recognized';
packages/cli/src/commands/migrate/multi-value-columns.ts:163  reason: 'remedy_not_recognized',

⇒ 修复器与规划器都在，remedy_not_recognized 是已设计的分支而不是意外落点 —— 这正是卡说的「Nothing wrong is executed」。

车道 domain:cli

选项 1 与 2 的主落点都是 os migrate 的命令面（packages/cli/src/commands/migrate/）⇒ 车道表 packages/cli 在 domain:cli 行。⚠️ 语句构造器在 packages/drivers/driver-sql/src/schema-drift.ts（domain:engine），是随动的第二处。⇒ 落地时是一个跨两包的 PR，⛔ 但主落点决定车道。

定级 p3

• 今天没有错误被执行：单值人口被 remedy_not_recognized 拒掉，拒绝详情已经告诉操作员去跑 os migrate plan 并手工套用语句；
• driver-sql schema-drift: the json-vs-text type_mismatch finding is keyed to field.multiple only, so a SINGLE-value JSON-class column (file family, STRUCTURED_JSON_TYPES) on a char/text column is never reported — the column a hand-run generated migration creates today #15771 出的消息也刻意不印任何 DDL，而是用文字说明 —— ⭐ 这个设计是对的，卡说得准：「the finding's message says so in words rather than printing DDL nobody has run」。

⇒ 缺的是自动化，不是正确性。p3。

为什么是 needs-user-decision

三条选项的差别不在实现，在命令面该长什么样：

1. 扩展现有命令（一个命令、两个语句构造器，形状由 finding 决定而非命令名）⇒ 代价是命令名不再描述它做的事（"multi-value" 会变成谎话）；
2. 兄弟命令 ⇒ 代价是操作员多记一个命令；
3. 维持拒绝 ⇒ 代价是每个受影响部署做一次手工转换（= driver-sql schema-drift: the json-vs-text type_mismatch finding is keyed to field.multiple only, so a SINGLE-value JSON-class column (file family, STRUCTURED_JSON_TYPES) on a char/text column is never reported — the column a hand-run generated migration creates today #15771 出货的现状）。

⇒ 这是产品面的取舍，⛔ 不是执行席位能选的。⭐ 而且选项 1 有一条隐性成本值得裁决者单独看：一个名字撒谎的命令，比多一个命令更贵——本轮我在 #16114、#16125、#15869 上反复看到「一个能解析、但说错话的名字/引用比没有更糟」。

⛔ 一条硬前置，两条臂都适用

Either of the first two needs a live Postgres and MySQL cell to land, for the same reason the existing forms did。

卡把理由给全了，我加重：manualJsonConversionSql 现有的两个 arm 是被 schema-drift.base-type-mismatch.test.ts 对着活服务器执行验证的，且它自己的 docblock 记录了两个 arm 是靠对活库跑一次早期版本才纠正过来的。

⇒ ⛔ 不接受纯静态实现。派发时必须带上「有活的 PG + MySQL cell」这个条件，否则会重演那两个 arm 的历史。
⚠️ 卡也诚实标了它自己的限制：本容器没有活 PG/MySQL cell，所以 wrap 行为那一限是引用而非重测；只有 SQLite cell 上的逐字节读数是它自己测的。

⭐ 修法方向卡已经指出，⛔ 但不要当成处方

The shape of that repair is a CAST rather than a wrap — rows written through ObjectStack already hold valid JSON text。

这条由它的实测支撑（SQLite cell 上单值 file 字段存的是 "file_01HXYZ"，含引号；wrap 之后变成 ["\"file_01HXYZ\""]，元素仍带引号）。⇒ 方向可信，但 ⛔ 仍需在活库上验证，理由同上。

相邻

#15771（检测器，已出货且刻意把单值人口路由到 remedy_not_recognized）、#15041（VARCHAR(2048) 与 json 列的生成器分歧，正是让陈旧列可达的原因）。
⚠️ 顺带一提：本轮我刚路由的 #16091 也是 packages/cli/src/commands/generate.ts 的生成器与 driver 不一致（text 的 255 vs 无界），与 #15041 同族。⇒ 三张卡都在「生成器与 driver 对同一份元数据给出不同的列」这条线上，⛔ 不合并但值得同一个人一次读完。

---

Generated by Claude Code