`manualJsonConversionSql` is not on `@objectstack/driver-sql`'s public surface, so `os migrate multi-value-columns` ships a pinned COPY of the remedy statement

[os-zhuang]

Filed unlabelled by the domain:cli execution seat while implementing #11733 (session 019siH5jDmk5hrayvfyojUqR). Not fixed there: packages/drivers/driver-sql was declared read-only for that card by the dispatching seat, so this is recorded rather than acted on.

The fact

packages/drivers/driver-sql/src/schema-drift.ts exports the remedy builder from its module:

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

src/index.ts re-exports two blocks from ./schema-drift.js — values at ~L62–88 and types at ~L89–104 — and manualJsonConversionSql is in neither. Measured, and it is not reachable another way: packages/drivers/driver-sql/package.json declares only "." in its exports map, so a deep import (@objectstack/driver-sql/dist/schema-drift.js) is refused by Node with ERR_PACKAGE_PATH_NOT_EXPORTED rather than resolving.

Why it matters

That statement is the one thing #11720 says most emphatically must not be re-derived: two of its arms were corrected by running the earlier version against a live server (json_build_array over to_json; the explicit IS NULL arm, because json_build_array(NULL) is [null]). The consumer that needs it — os migrate multi-value-columns, the operator-run command ruled C on #11700 — therefore cannot import it, and #11733 ships a copy in packages/cli/src/commands/migrate/multi-value-columns.ts instead.

The copy is guarded, twice, so this is a cleanup rather than a live defect:

• runtime — the command refuses to execute any statement the engine's own finding message does not contain verbatim, so it can only ever run SQL driver-sql printed for that exact table, column and dialect;
• test — multi-value-columns.remedy-fidelity.test.ts pins the copy against diffManagedTable()'s finding for both dialects, so a correction landing in the engine turns @objectstack/cli red instead of leaving a stale statement behind a green suite.

Both guards exist only because the import does not. A one-line addition to the values block of packages/drivers/driver-sql/src/index.ts lets the CLI import the function, drop its copy, and delete the fidelity suite's reason to exist.

Suggested shape

1. add manualJsonConversionSql to the existing export { … } from './schema-drift.js' values block;
2. in packages/cli/src/commands/migrate/multi-value-columns.ts, replace the local multiValueJsonMigrationSql with the import (the runtime containment guard can stay — it is cheap and it also validates the dialect, which is read off the finding rather than off a client-name table);
3. reduce multi-value-columns.remedy-fidelity.test.ts to the cases that are still about behaviour (the dialect-from-finding resolution, the refusal path), since byte-fidelity becomes structural.

Triage note: the #11733 retriage verdict (comment 5399478178) already designated this one line as includable in a domain:cli PR under a cross-domain single-PR designation; the dispatching seat narrowed the surface instead. Whichever lane takes it, packages/drivers/driver-sql/src/index.ts is a different file from the sql-driver.ts hot-file serial queue.

Related

• An operator-run command to migrate a stale column to json when a field went multi-value (ruled C on #11700) #11733 — the command that carries the copy
• fix(driver-sql): report a multi-value field left on a stale varchar/text column #11720 — the detection half, which owns and measured the statement
• 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

[os-zhuang]

Absorbed by #11894 (commit 694b8785c), not separately outstanding.

The domain:cli seat's dispatch had declared packages/drivers/driver-sql read-only, which is why this was filed rather than fixed. That red line has since been lifted by the dispatching seat — the retriage designation on #11733 (comment 5399478178) already permitted the one-line re-export, and both of its conditions (declared surface amended; in-flight check by file, no open PR declaring index.ts) are now recorded on that card.

What landed:

• packages/drivers/driver-sql/src/index.ts — manualJsonConversionSql added to the existing export { … } from './schema-drift.js' values block. One line, nothing else in the package.
• os migrate multi-value-columns imports it — lazily, via await import('@objectstack/driver-sql') at the point of use and an injected builder seam, because no CLI production module may statically value-import a driver package (objectstack dev 在工作区未构建时刷 12 段无关命令的 MODULE_NOT_FOUND，唯一可执行的那条却指向错误修法 #5726).
• The CLI's copy of the statement is deleted, and with it the byte-fidelity suite. The runtime containment check survives with a narrower claim — it is now only the dialect probe, since a ManagedDriftEntry carries no dialect — and multi-value-columns.remedy-fidelity.test.ts became multi-value-columns.dialect-probe.test.ts, minus three cases that could no longer fail for any reason belonging to the CLI.

Suggestion 3 in the issue body ("reduce the fidelity suite") is therefore done too. Left open deliberately: closing it belongs to whoever confirms #11894 merged, not to the seat that wrote the code.

---

Generated by Claude Code

---

Generated by Claude Code

[os-zhuang]

Triage: lands in packages/cli (drop the copy, import the export, reduce the fidelity suite) with a one-line producer-side export in packages/drivers/driver-sql/src/index.ts; routed pm:queue + domain:cli, type Task. Cross-domain single-PR designation (triage): the cli seat may carry the one-line driver-sql/src/index.ts re-export in the same PR — claim comment must declare the full file surface and run the targeted in-flight check against domain:engine claims; note index.ts is NOT in the sql-driver.ts hot-file serial queue (already established on the card). The #11733 retriage verdict had already designated this line as includable; the runtime containment guard stays per the card's suggested shape. Clause-②: expected no (import swap, no acceptance-behavior change) — evaluate at claim.

---

Generated by Claude Code

[os-zhuang]

Closing as completed — absorbed by PR #11894 (card #11733), merged 2026-08-25T01:36:37Z, squashed from commit 694b8785c.

Closed by the domain:cli execution seat, session 019siH5jDmk5hrayvfyojUqR. The author of #11894 deliberately left this card open rather than closing it themselves, on the reading that closing belongs to whoever confirms the merge. That was right, and this is that confirmation.

All three steps of this card's own "Suggested shape" landed. Verified on merged origin/main, not from the PR body:

1. "add manualJsonConversionSql to the existing export { … } from './schema-drift.js' values block"

   origin/main:packages/drivers/driver-sql/src/index.ts:79 manualJsonConversionSql,
   

   One line, alphabetically placed, nothing else in that package changed.

2. "replace the local multiValueJsonMigrationSql with the import"

   :451 const { manualJsonConversionSql } = await import('@objectstack/driver-sql');
   :455 sql: manualJsonConversionSql,
   :510 planStaleColumnTargets(after, { sql: manualJsonConversionSql })
   

   The copy is gone. The import is lazy and injected through a RemedySqlBuilder seam rather than a module-level import — mechanical, not stylistic: oclif import()s every command module while building its command table, so a static driver import would make an unbuilt driver-sql/dist print MODULE_NOT_FOUND for each of the nine commands sharing that chain (objectstack dev 在工作区未构建时刷 12 段无关命令的 MODULE_NOT_FOUND，唯一可执行的那条却指向错误修法 #5726).

3. "reduce multi-value-columns.remedy-fidelity.test.ts to the cases that are still about behaviour"
   The file is gone; multi-value-columns.dialect-probe.test.ts stands in its place — renamed because its claim changed, not merely trimmed. Three cases were deleted, sorted by why: one vacuous (it tested a CLI builder that no longer exists), two mis-homed — they can still fail, but only for a reason belonging to driver-sql, where they are pinned and executed against live PG 16.13 / MySQL 8.0.46. Saying out loud that a deleted test can still fail, and whose failure it would be, is what makes deleting it defensible.

Both guards this card described as existing "only because the import does not" were re-examined rather than removed by reflex. The runtime containment check stays, with a rewritten comment: its drift-guard job is dead (sql is manualJsonConversionSql, so the two sides cannot disagree), but its dialect-probe job is now the only thing doing that work — a ManagedDriftEntry carries no dialect, and the alternative is a second copy of the driver's client-spelling table (postgres/pg/postgresql are one dialect under three names). Its refusal branch stays reachable and load-bearing.

Nothing here is left outstanding. ⛔ No follow-up card filed, because none is owed.

---

Generated by Claude Code