fix(cli): multiple: true takes a JSON column in both migration generators

[os-trump]

Fixes #14829

os generate types honoured multiple: true and neither migration generator did, so one authored field produced two incompatible answers from one config in one run — an array TS type and a scalar column. This threads the flag through both migration generators, answering it where the platform answers it: before the type is consulted at all.

Re-measured on origin/main (5bc2f27) — every number with the command that produced it

Anchor	Command	Result
multiple occurrences in generate.ts	git grep -n multiple origin/main -- packages/cli/src/commands/generate.ts	4, at :562 :564 :607 :831, all TypeScript-side. Card's numbers hold; the triage comment's :502/:504/:547/:771 are the stale pair
fieldTypeToSql arity	sed -n '1030,1033p'	took (fieldType: string) only — the flag could not reach it
The driver's rule, statement 1	sed -n '15342,15370p' packages/drivers/driver-sql/src/sql-driver.ts	createColumn opens with if (field.multiple) { this.jsonColumn(table, name); return; }, above its switch (type)
statement 2	sed -n '15867p' same file	isJsonField is JSON_COLUMN_TYPES.has(type) || !!field.multiple
statement 3	sed -n '541,544p' packages/drivers/driver-sql/src/schema-drift.ts	fieldHasColumn opens if (field?.multiple) return true;, documented as "Mirrors SqlDriver.createColumn exactly … including multiple (a JSON column)"
The spec's value predicate	sed -n '213,236p' packages/spec/src/data/field-value.zod.ts	isMultiValueField = MULTI_OPTION_TYPES.has(type) OR (MULTI_CAPABLE_TYPES.has(type) AND multiple === true) — type-gated
Is the combination authorable off that roster?	grep -n multiple packages/spec/src/data/field.zod.ts	multiple is a plain z.boolean().default(false) on every field; only radio + multiple is refused by name (:1818)

One correction worth recording: the card and the triage comment both spell the driver path driver-sql; it is packages/drivers/driver-sql. A git grep pathspec of packages/**/src matches zero there (git pathspec ** is not recursive without :(glob)), which is a silent zero rather than an error.

Which surface is authoritative — the driver, and not the spec predicate

The three surfaces answer two different questions and only one of them is about a column:

• isMultiValueField is the ADR-0104 D1 value contract — "is the persisted value an array". Gated on MULTI_CAPABLE_TYPES.
• createColumn / isJsonField / fieldHasColumn decide which column exists. Gated on the flag alone, three times over.

A migration generator's subject is the column, so the column authority governs. There is a fourth statement of the same rule, found while bounding a residue note, and it is the one that shows what the defect COST. schema-drift.ts's base-type check opens its emission site with const declaresJsonColumn = field.multiple === true; and reports expected: 'json' — flag alone again — gated on acceptsStringifiedJson(col.type), which is /char|text/i. Run that against what each generator emitted for a flagged lookup before this PR:

Emitted by	Column	acceptsStringifiedJson	Consequence on Postgres
--format sql (pre-fix)	VARCHAR(36)	true	an error-severity needs_confirm drift finding against a table the CLI itself generated — "arrays are being written as the STRINGIFIED literal"
typescript (pre-fix)	table.uuid	false	no finding; the database refuses the write instead
either (this PR)	JSONB	false	none — the column is what the platform wants

So the two pre-fix answers were wrong in two different ways, and neither was silent for the platform — only for the author. The triage comment's steer — derive from isMultiValueField — would have answered VARCHAR(255) for a text field flagged multiple: true while the driver gives that same field a JSON column: the same drift one notch narrower. And the combination is reachable, because FieldSchema does not refuse it and the CLI generators sit downstream of validation (their own default: arm is documented as serving the unvalidated authoring door). So the implementation gates on the flag, with no list at all — the "fourth hand-copied vocabulary" the card warned about is avoided by not needing one. MULTI_CAPABLE_TYPES is still imported by the pin, as the roster it sweeps.

Red-first, and which arm fired

The pin was written and committed before the fix (a59b393f20), and run against the unfixed generators:

Tests  9 failed | 6 passed (15)
AssertionError: os generate migration --format sql gave a flagged lookup a scalar column …
  expected 'VARCHAR(36)' to be 'JSONB'     pin.test.ts:177

The 9 failures are the discriminating arms; all 6 controls passed — the roster control, the emission control, the "same type without the flag keeps its scalar column" control, the two driver-authority reads and the scope fence. The red is the negative arm at line 177, not the harness.

Re-proved as a full ablation on the finished tree (os-verify-lock.sh, one hold):

green baseline           Tests 15 passed (15)
mutation on disk         both branch markers 0/0 · blob a3fd631b… != HEAD 6cc1e93a… · 57593 -> 57420 bytes
ablated                  Tests 9 failed | 6 passed (15)  — the same 9 arms, same 6 controls green
restore                  hash-object == HEAD blob 6cc1e93a… · git diff HEAD -> 0 files
re-run                   Tests 15 passed (15)

Mutation and restore are both proved by bytes, never by an editor's exit code, under trap … EXIT INT TERM on absolute paths. No build/dist leg: the pin imports its subject by relative specifier (./generate.js), which vitest resolves to the sibling source, so there is no exports hop that a stale dist could answer for.

Verification

Check	Result
pnpm lint (whole repo, eslint . --no-inline-config)	exit 0 at ba72049628 — the final commit, no narrowing claimed
the pin + the neighbouring vocabulary pin + generate-file-name-registry-parity	61 passed
check:cross-package-test-inputs, check:ci-filter-parity, check:turbo-task-graph, check:entry-guard, check:nul-bytes, check:test-source-alias, check:engine-double-contract, check:where-matcher, check:query-options-erasure, check:published-files, check:undeclared-dep-imports, check:doc-authoring, check:type-source-resolution, check:slot-lookup, check:parse-guard, check:pnpm-filter-targets, check:cli-command-ids, check:objectui-changeset, check:empty-changeset, check:changeset-no-major, check:adr-0087-registration, check:changeset-gate-self-tests, check:pm-half-states, check:self-test-wired, check:ratchet-remedy-authority, check:agent-test-spelling	all exit 0
packages/cli tsc --noEmit and check:test-typecheck	NOT MEASURED — 194 of 234 errors are TS2307 for workspace modules, the unbuilt-closure signature, and the three check:test-typecheck files named are ones this diff does not touch

For that last row the question was narrowed rather than dropped, and the narrowing is measured: an A/B on the same unbuilt tree — census at HEAD vs census with generate.ts reverted to 5bc2f2727a and the pin file removed — is 234 error lines both ways with an empty diff, and zero errors name either of my files. So this diff adds no type error; what is unmeasured locally is the pre-existing state, which CI measures on a built workspace. Non-vacuity for the coverage claim itself: tsc --noEmit --listFiles lists 988 files and the new pin is one of them (grep -c = 1), so packages/cli's include: ["src"] really does typecheck it — the new test is deliberately under src/, not test/, for that reason.

File face

File	Why
packages/cli/src/commands/generate.ts	the fix: fieldTypeToSql takes the flag and answers it first; generateMigrationTs emits the JSON column before its per-type switch; three functions gain a named export so the pin can drive them
packages/cli/src/commands/generate-multiple-json-column.pin.test.ts	new — the cross-surface pin
turbo.json + scripts/cross-package-test-inputs.mjs	the pin reads two driver-sql sources, so check:cross-package-test-inputs demanded both declarations. This is the pin's point, not paperwork: if the driver moves the rule and cli's suite does not re-run, the two sides drift again by the cache
.changeset/generate-migration-multiple-json-column.md	patch for @objectstack/cli

Changeset fork, measured: packages/cli's files is ["dist","README.md","CHANGELOG.md"], so a src/** comment publishes nothing — but this card changes emitted output (os generate migration's DDL), which compiles into dist/commands/generate.js and ships. patch, not skip-changeset.

The three named exports do not widen the published surface: @objectstack/cli's exports map is . and ./console only, so src/commands/generate.ts is not an entrypoint. The file already carried a named export used by a test (GENERATOR_SCAFFOLD_TARGETS).

What I did NOT do

• ⛔ The five disputed scalar vocabulary entries are byte-for-byte untouched — out of scope: [finding] packages/cli generate.ts: five field-type vocabulary entries that DO exist disagree with what the platform stores (autonumber SERIAL, formula's column, multiselect TEXT, vector VECTOR, lookup uuid) #14828, and it is a shipped-behaviour decision. The honest fix never came near them: the new branch runs before the type is read, so autonumber, formula, multiselect, vector and lookup/master_detail keep the answers they had. A test block asserts exactly that, labelled as a scope fence rather than an endorsement — whoever takes [finding] packages/cli generate.ts: five field-type vocabulary entries that DO exist disagree with what the platform stores (autonumber SERIAL, formula's column, multiselect TEXT, vector VECTOR, lookup uuid) #14828 must update it deliberately.
  Worth stating precisely, because the fix does change the answer for formula/autonumber when flagged (TEXT/SERIAL -> JSONB). That is not the fenced decision: the driver gives a flagged field of any type a JSON column (fieldHasColumn returns true for a flagged formula, which is otherwise virtual), so those shapes move toward the platform, while the scalar entries — the ones [finding] packages/cli generate.ts: five field-type vocabulary entries that DO exist disagree with what the platform stores (autonumber SERIAL, formula's column, multiselect TEXT, vector VECTOR, lookup uuid) #14828 owns — do not move at all.
• ⛔ No new field-type list. The rule is one flag; adding a fourth vocabulary is the defect, not the fix.
• ⛔ packages/spec read, never edited. packages/rest/src/error-response.ts untouched.
• ⛔ Not flipped out of draft; no auto-merge.

Residue

• The generators spell a JSON column JSONB / table.jsonb(…) while the driver emits json (or text on SQLite). That predates this card and lives in the existing json vocabulary entry, so it is left alone; the new branch reuses each generator's own existing spelling rather than introducing a third. Bounded before deciding not to file it: the only check that could care is schema-drift.ts's base-type finding, and it is gated on acceptsStringifiedJson = /char|text/i, which jsonb does not match. So the divergence raises nothing and is cosmetic — a measurement, not an assumption, and the reason there is no drive-by card for it.
• A previously generated migration file is not rewritten by a generator change. An app that already ran one has a scalar column where the platform wants JSON; the schema sync is additive and will not retype it. That drift pre-exists this PR — it is what the defect was — and closing it would be a migration story, not a generator one.

Authored in Claude Code session https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza (recorded here in prose because editing a PR body rewrites the footer below back to its bare form).

🤖 Generated with Claude Code

https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/cli, touching 5 documentable anchor(s).

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/api/data-flow.mdx (via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/deployment/cli.mdx (via os generate (command, read off packages/cli/src/commands/generate.ts))
• content/docs/protocol/kernel/lifecycle.mdx (via os generate (command, read off packages/cli/src/commands/generate.ts))

What this run could not see

• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 22 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 5bc2f2727aef5d697530c63d64dd5592df445776 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from d8e8e896abd2eadc963ba94a11c58d937310ead6 — the merge of head ba7204962888e968b98bee7b3d47ead13015eb94 into base 5bc2f2727aef5d697530c63d64dd5592df445776, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin d8e8e896abd2eadc963ba94a11c58d937310ead6 && git checkout d8e8e896abd2eadc963ba94a11c58d937310ead6
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 5bc2f2727aef5d697530c63d64dd5592df445776 ba7204962888e968b98bee7b3d47ead13015eb94 && git checkout -B drift-repro 5bc2f2727aef5d697530c63d64dd5592df445776 && git merge --no-ff ba7204962888e968b98bee7b3d47ead13015eb94

node scripts/docs-audit/affected-docs.mjs --json 5bc2f2727aef5d697530c63d64dd5592df445776

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 5bc2f2727aef5d697530c63d64dd5592df445776 → pass the list as
args.docs, on the commit named under Which tree this was computed on.