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

`os generate types` honoured the flag and neither migration generator did, so
one authored `Field.lookup({ multiple: true })` produced an array TS type and a
scalar `VARCHAR(36)` / `table.uuid` column from the same config in the same run.

The column authority is `driver-sql`, and its answer is the flag alone:
`createColumn` short-circuits on `field.multiple` above its own per-type switch,
`isJsonField` is `JSON_COLUMN_TYPES.has(type) || !!field.multiple`, and
`fieldHasColumn` opens with the same check. Both generators now answer it in the
same place — before the type is consulted — so the element type gets no vote.

Deliberately NOT the spec's `isMultiValueField`: that is the ADR-0104 D1 value
contract, gated on `MULTI_CAPABLE_TYPES`, and it would answer VARCHAR for a
`text` field the driver gives a JSON column — the same drift one notch narrower.

The per-type vocabularies are untouched; the disputed scalar answers stay
byte-for-byte and are pinned as a scope fence.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016yfqQh2dBgPAymYd7xipza

Author: claude

.changeset/generate-migration-multiple-json-column.md

@@ -0,0 +1,11 @@
+---
+"@objectstack/cli": patch
+---
+
+`os generate migration` now gives a `multiple: true` field a JSON column, in both formats. One authored field used to produce two incompatible answers from one config in one run: `Field.lookup({ reference: 'account', multiple: true })` emitted `account?: string[]` from `os generate types` and a scalar `VARCHAR(36)` / `table.uuid('account')` column from the two migration generators, because `multiple` appeared exactly four times in `generate.ts` and all four were on the TypeScript side — `fieldTypeToSql` did not even take the parameter. Nothing warned: the scaffold looks right, the generated TypeScript IS right, and only the column is wrong, so the first symptom was a write of an array into a scalar column. That is the `#field-zoo` failure one layer out — there the DDL switch and `isJsonField` had drifted into two lists inside the driver; here the platform and the *generated* DDL were the two lists.
+
+The authority is the driver's, and it is the flag alone. `SqlDriver.createColumn` short-circuits on `field.multiple` **above** its own `switch (type)`; `isJsonField` is `JSON_COLUMN_TYPES.has(type) || !!field.multiple`; and `fieldHasColumn` opens with `if (field?.multiple) return true` under the comment "Mirrors `SqlDriver.createColumn` exactly … including `multiple` (a JSON column)". Three statements of one rule: a flagged field is a JSON column whatever its element type would have been. Both generators now answer it the same way and in the same place — before the type is consulted at all.
+
+Deliberately **not** the spec's `isMultiValueField`. That predicate is the ADR-0104 D1 *value* contract ("is the persisted value an array") and gates on `MULTI_CAPABLE_TYPES`, so asking it here would answer `VARCHAR` for a `text` field flagged `multiple: true` while the driver gives that same field a JSON column — the identical drift one notch narrower. `FieldSchema` does not refuse the combination either (`multiple` is a plain `z.boolean()` on every field; only `radio` + `multiple` is refused by name), and the generators sit downstream of validation. The two questions have two different owners: the value shape is the spec's, the column is the driver's.
+
+Nothing about the existing per-type vocabularies changes. The scalar answers — including the five that are separately disputed — are byte-for-byte what they were, and a new pin asserts that as a scope fence rather than leaving it to a reading of the diff. `generate-multiple-json-column.pin.test.ts` drives all three generators on one config and pins the agreement across every member of the spec's `MULTI_CAPABLE_TYPES` plus a type outside it, so the type-blindness of the rule is an assertion rather than a comment; it also reads the driver's two statements of the rule, so moving them there fails here.

packages/cli/src/commands/generate.ts

@@ -1027,7 +1027,33 @@ const FIELD_TYPE_SQL_MAP: Record<string, string> = {
   address: 'JSONB',
 } satisfies Record<FieldType, string>;
 
-function fieldTypeToSql(fieldType: string): string {
+/**
+ * The column one field takes.
+ *
+ * `multiple` is answered FIRST, before the type is looked up at all, because
+ * that is what the platform does. `SqlDriver.createColumn` short-circuits on
+ * `field.multiple` ABOVE its own `switch (type)`; `isJsonField` is
+ * `JSON_COLUMN_TYPES.has(type) || !!field.multiple`; and `fieldHasColumn`
+ * opens with `if (field?.multiple) return true` under the comment "Mirrors
+ * `SqlDriver.createColumn` exactly ... including `multiple` (a JSON column)".
+ * Three statements of one rule: a flagged field is a JSON column whatever its
+ * element type would have been, so the element type gets no vote here either
+ * (#14829). Before this, one authored `Field.lookup({ multiple: true })`
+ * produced `account?: string[]` from `os generate types` and a scalar
+ * `VARCHAR(36)` column from this generator, in the same run.
+ *
+ * WARNING: this is deliberately NOT the spec's `isMultiValueField`. That is the
+ * ADR-0104 D1 VALUE contract ("is the persisted value an array"), gated on
+ * `MULTI_CAPABLE_TYPES`; asking it here would answer VARCHAR for a `text`
+ * field the driver gives a JSON column - the same drift one notch narrower.
+ * The column question belongs to the driver, and the driver's answer is the
+ * flag alone. `generate-multiple-json-column.pin.test.ts` pins both halves.
+ *
+ * The JSON spelling is READ from this table's own `json` entry rather than
+ * restated, so the two cannot drift about what a JSON column is spelled here.
+ */
+function fieldTypeToSql(fieldType: string, multiple?: boolean): string {
+  if (multiple) return FIELD_TYPE_SQL_MAP.json;
   return FIELD_TYPE_SQL_MAP[fieldType] || 'TEXT';
 }
 
@@ -1063,7 +1089,7 @@ export function generateMigrationSql(config: Record<string, unknown>): string {
 
     const fieldLines: string[] = [];
     for (const [fieldName, fieldDef] of Object.entries(fields)) {
-      const sqlType = fieldTypeToSql(String(fieldDef.type || 'text'));
+      const sqlType = fieldTypeToSql(String(fieldDef.type || 'text'), !!fieldDef.multiple);
       const notNull = fieldDef.required ? ' NOT NULL' : '';
       fieldLines.push(`  "${fieldName}" ${sqlType}${notNull}`);
     }
@@ -1117,8 +1143,21 @@ export function generateMigrationTs(config: Record<string, unknown>): string {
     for (const [fieldName, fieldDef] of Object.entries(fields)) {
       const fType = String(fieldDef.type || 'text');
       const required = fieldDef.required ? '.notNullable()' : '.nullable()';
-      let colMethod: string;
 
+      // #14829 - `multiple` before the type, exactly as `SqlDriver.createColumn`
+      // does it: the driver short-circuits on the flag above its own per-type
+      // switch, so a flagged field is a JSON column whatever its element type
+      // would have been. Emitted here rather than as a switch arm because the
+      // switch cases on the TYPE and the type has no vote in this decision;
+      // the spelling is this generator's own JSON arm, stated once more.
+      // See `fieldTypeToSql` for why the authority is the driver's flag rule
+      // and not the spec's `isMultiValueField` value predicate.
+      if (fieldDef.multiple) {
+        lines.push(`    table.jsonb('${fieldName}')${required};`);
+        continue;
+      }
+
+      let colMethod: string;
       switch (fType) {
         case 'text': case 'email': case 'phone': case 'url': case 'select':
         case 'password': case 'color':

scripts/cross-package-test-inputs.mjs

@@ -391,6 +391,27 @@ export const CROSS_PACKAGE_TEST_INPUTS = {
       // One file, not `packages/create-objectstack/**`: the test reads that
       // template and nothing else across the boundary.
       'packages/create-objectstack/src/templates/blank/pnpm-workspace.yaml',
+      // The two files that hold the COLUMN authority the CLI's migration
+      // generators mirror, READ by
+      // src/commands/generate-multiple-json-column.pin.test.ts (#14829). That
+      // pin asserts a `multiple: true` field gets a JSON column from both
+      // `os generate migration` formats because `SqlDriver.createColumn`
+      // short-circuits on the flag ABOVE its per-type switch, and
+      // `fieldHasColumn` mirrors that decision for the drift differ. Source-read
+      // rather than imported: `createColumn` is `protected` and needs a knex
+      // table builder, so driving it would mean a live driver and a built
+      // `dist`, while the SHAPE of its decision — flag first, type second — is
+      // exactly what has to stay true and is legible in the source.
+      //
+      // The declaration is the whole point of the pin, not paperwork around it:
+      // if the driver moves that rule and cli's suite does not re-run, the two
+      // sides drift again in silence, which is the #14829 defect returning by
+      // the cache. Two files rather than `packages/drivers/driver-sql/src/**`:
+      // the pin reads these two and nothing else across the boundary, and that
+      // package's `src` is edited often enough that the subtree glob would put
+      // cli's whole suite on every driver commit.
+      'packages/drivers/driver-sql/src/sql-driver.ts',
+      'packages/drivers/driver-sql/src/schema-drift.ts',
     ],
   },
   '@objectstack/client': {

turbo.json

@@ -107,7 +107,9 @@
         "$TURBO_ROOT$/scripts/cross-package-test-inputs.mjs",
         "$TURBO_ROOT$/packages/spec/src/system/translation.zod.ts",
         "$TURBO_ROOT$/scripts/check-cross-package-test-inputs.mjs",
-        "$TURBO_ROOT$/packages/create-objectstack/src/templates/blank/pnpm-workspace.yaml"
+        "$TURBO_ROOT$/packages/create-objectstack/src/templates/blank/pnpm-workspace.yaml",
+        "$TURBO_ROOT$/packages/drivers/driver-sql/src/sql-driver.ts",
+        "$TURBO_ROOT$/packages/drivers/driver-sql/src/schema-drift.ts"
       ]
     },
     "@objectstack/client#test": {