An operator-run command to migrate a stale column to json when a field went multi-value (ruled C on #11700)

[huangyiirene]

Filed by the domain:engine seat (session session_01VK8rFDtg8eREaxBGX99Csn) as the execution half of the #11700 ruling.

The ruling this card executes

Maintainer, 2026-08-24, live PM chat. ⛔ Quoted verbatim, not translated:

「11700 11693 不需要考虑历史数据，其他按照你的建议继续」

Ruled: C — the platform warns and ships an explicit, operator-run migration command. ⛔ It is never run automatically at boot. Option A (unattended auto-migration) is rejected: on the four facets it was the only route that has the platform altering a customer's production table structure with nobody watching. B (warn only) survives solely as C's degenerate form if this command is never shipped — which is what this card exists to prevent.

⚠️ Amendment, from the ruling's own words — historical data is OUT of scope. The #11700 analysis carried a confidence gap flagging that no route repairs rows corrupted before detection landed. That rider is struck: rows already corrupted are the customer's to repair, as the reporting customer already did. ⛔ Do not add backfill or row-repair to this command, and ⛔ do not file a card for it.

What to build

A command an operator runs deliberately, on their own schedule, having taken their own backup. The shape the ruling names:

• the migration itself — the dialect-correct statement for moving a stale varchar/text column to json when its field declares multiple: true;
• a dry run — show exactly what would run, and against what, without running it;
• rollback notes — what the operator does if it goes wrong;
• docs — so the finding's message can point at something real.

⚠️ The SQL is already written and, more importantly, already measured. PR #11720 (the detection half) emits the remedy statement per dialect, and its suite executes that statement against live Postgres 16.13 and MySQL 8.0.46 over four row states, asserting the finding then clears. ⛔ Do not re-derive it — reuse it, and read the two corrections that were forced by measurement rather than preference:

• to_json(col) turns a legacy single value into a JSON scalar under a now-multi-value field (Array.isArray === false), so json_build_array is used instead, which makes Postgres agree with MySQL's JSON_ARRAY;
• json_build_array(NULL) is [null] — a one-element array — so an explicit IS NULL arm exists. It was added after the version without it was run on the live server and observed to give every NULL row a value.

Dialect scope, measured: the corruption occurs on Postgres and MySQL and does not on SQLite (which reads back a real array). SQLite is excluded.

Before dispatching, re-verify rather than assume

• The detection half must have landed: check that PR fix(driver-sql): report a multi-value field left on a stale varchar/text column #11720 is merged and that manual_column_type_change is emitted on origin/main
  (git grep -n "manual_column_type_change" origin/main -- packages/drivers/driver-sql/src/schema-drift.ts).
• ⚠️ Confirm where the command belongs. The drift finding lives in packages/drivers/driver-sql, but an operator-facing command plausibly lives in packages/cli next to the other os migrate surfaces — which is another seat's lane. If it lands there, this becomes a cross-lane card and goes to that queue, ⛔ not into a driver-sql PR. Establish the landing point before writing code; it may change this card's domain:*.
• ⛔ The reconciler must still not execute this op automatically. fix(driver-sql): report a multi-value field left on a stale varchar/text column #11720 ships manual_column_type_change with no reconciler arm by design; this command is a separate, deliberate path the operator invokes. A change that quietly gives the op an arm would convert C back into A, which was rejected.

Related

• [Decision] 老客户把「选一个人」的字段改成「选多个人」时,平台该自己动客户的库,还是只报警要人来动?(#11535 的自动迁移半边) #11700 — the decision card (ruled C); closes once this card exists
• driver-sql: single→multi-value field change never migrates the existing column type (varchar/text kept), arrays silently stored as stringified literals — data corruption on Postgres #11535 — the customer's original corruption report; flips pm:blocked pointing here once the detection half lands
• fix(driver-sql): report a multi-value field left on a stale varchar/text column #11720 — the detection half, carrying the measured remedy SQL
• [finding] The drift category vocabulary has no "report only" state, so a finding the platform will never reconcile must borrow needs_confirm and be declined by the reconciler #11721 — the drift category vocabulary has no report-only state (the op currently borrows needs_confirm)

[huangyiirene]

pm:retriage — I graded this card domain:engine and the measurement says that is wrong

Filed and graded by me (domain:engine PM seat, session session_01VK8rFDtg8eREaxBGX99Csn). The card's own dispatch checklist told the next reader to settle the landing point before writing code, because it may change this card's domain:*. I settled it, and it does. ⛔ Not self-correcting the label — an execution seat does not produce domain:* grading, including when correcting its own. Handing the reading to triage.

Precondition 1 — satisfied

The detection half landed. PR #11720 merged 2026-08-24T14:52:14Z, verified by content on origin/main, ⛔ not by the API's merged field:

packages/drivers/driver-sql/src/schema-drift.ts:169 | { type: 'manual_column_type_change'; table: string; column: string; to: string; from: string }
packages/drivers/driver-sql/src/schema-drift.ts:691 op: { type: 'manual_column_type_change', table, column: fieldName, to: 'json', from: col.type },

Precondition 2 — the landing point is packages/cli, which is not this lane

os migrate already carries a family of operator-run, one-off data migrations, and the command this card describes is a member of it by shape:

packages/cli/src/commands/migrate/duplicates.ts
packages/cli/src/commands/migrate/value-shapes.ts
packages/cli/src/commands/migrate/recorded-by.ts
packages/cli/src/commands/migrate/files-to-references.ts
packages/cli/src/commands/migrate/summary-nulls.ts

packages/cli is domain:cli by this lane's own red line, so the deliverable — the command, its dry run, its rollback notes, its docs — sits outside domain:engine entirely.

How much of it is genuinely engine: one line

Worth stating precisely, because it decides whether this splits or moves whole. The remedy SQL is already written and already measured (#11720 executes it against live Postgres 16.13 and MySQL 8.0.46 over four row states). It lives in a function that is exported from its module but not re-exported from the package:

packages/drivers/driver-sql/src/schema-drift.ts:499 export function manualJsonConversionSql(dialect: SqlDialectName, table: string, column: string): string

packages/drivers/driver-sql/src/index.ts re-exports two blocks from schema-drift.js (values at ~L75–88, types at ~L89–104); manualJsonConversionSql is in neither. So a CLI command reusing it needs one added export line, or it re-derives SQL that was corrected twice by live measurement (json_build_array over to_json, and the explicit IS NULL arm) — which is exactly the outcome the card was written to prevent.

⇒ My reading for triage: move the card whole to domain:cli, with the one-line driver-sql re-export inside its scope, rather than splitting off an engine card whose entire deliverable is an export with no consumer. I flag rather than decide whether a cli-lane card may touch packages/drivers/driver-sql/src/index.ts — it is a different file from the sql-driver.ts serial queue, but that is a triage call, not mine.

Carried forward unchanged — these survive any regrade

• ⛔ The reconciler must still have no arm for manual_column_type_change. fix(driver-sql): report a multi-value field left on a stale varchar/text column #11720 ships it armless by design. Giving it one converts ruled C back into rejected A.
• ⛔ Historical data is out of scope by the ruling's own words (「不需要考虑历史数据」). No backfill, no row repair, and no card for one.
• SQLite is excluded by measurement, not convenience — it reads back a real array.

Card stays pm:retriage, unassigned, off this lane's queue until regraded.

---

Generated by Claude Code