@unboundcx/sdk 4.1.3 → 4.4.0

package/schemas/layouts/action.js

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { ConditionSpec, MustacheTemplate } from './primitives.js';
+
+// New primitive, per V2-PLAN's exact definition.
+export const ActionSpec = z.object({
+  id: z.string().min(1),
+  type: z.enum(['create', 'edit', 'delete', 'custom']),
+  label: z.string().optional(),
+  target: z.string().optional(),      // object name (create/edit/delete) or custom-action registry key
+  mode: z.enum(['modal', 'tab', 'inline']).default('modal'),
+  layout: z.string().optional(),      // compactLayoutId, used when mode:'modal' for create/edit
+  placement: z.enum(['header', 'section', 'row', 'card']),
+  visibility: ConditionSpec.optional(),
+  prefill: z.record(MustacheTemplate).optional(), // e.g. {relatedId: '{{id}}'} — create-with-prefilled-relationship
+}).refine((v) => v.type !== 'custom' || !!v.target, {
+  message: 'custom action requires target', path: ['target'],
+});

package/schemas/layouts/compact.js

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { FieldSpec } from './field.js';
+
+// Per V2-PLAN §1.4: "just { fields: FieldSpec[] } — capped list, no sections."
+// Reused everywhere a short field summary is needed: kanban cardFields,
+// hover cards, modal create/edit forms.
+export const CompactLayoutDoc = z.object({
+  schemaVersion: z.literal(2).default(2),
+  objectName: z.string().min(1),
+  fields: z.array(FieldSpec).min(1).max(12),
+});

package/schemas/layouts/field.js

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { ConditionSpec } from './primitives.js';
+import { MustacheTemplate } from './primitives.js';
+import { FormatType } from './format.js';
+import { JoinSpec } from './join.js';
+import { SelectDynamicSpec } from './selectDynamic.js';
+
+const SecurityConfigSpec = z.object({
+  editWithoutValue: z.boolean().default(false),
+  readOnly: z.boolean().default(false),
+  showChars: z.number().int().min(0).optional(),
+  hideLength: z.boolean().default(false),
+});
+
+const LinkSpec = z.object({
+  path: MustacheTemplate,
+  tabName: z.string().optional(),
+  tabIcon: z.string().optional(),
+});
+
+// DEVIATION from spec's literal DISPLAY_FIELD_TYPES list (see SPEC-PHASE-1.md
+// A6): added 'select'/'selectDynamic'. Verified against real stored data
+// (app1-api/src/services/layouts/examples.json) — display.fieldType commonly
+// mirrors edit.fieldType for select-backed fields (5 occurrences of
+// display.fieldType:'selectDynamic' in the two-doc fixture); the literal spec
+// list omitted them, which would warn on effectively every select field in
+// production data — a false-positive, not the genuine defect this schema is
+// meant to surface. Flagged for reviewer per task instructions.
+const DISPLAY_FIELD_TYPES = [
+  'input', 'textArea', 'code', 'readOnly', 'spacer', 'composite',
+  'select', 'selectDynamic',
+  'securityBlurHover', 'securityBlurAlways', 'securityLastX', 'securityFirstX', 'securityFirstLastX',
+];
+
+const FieldDisplaySpec = z.object({
+  label: z.string().default(''),
+  value: z.string().min(1),                       // dot-path ok, e.g. "company.name"
+  fieldType: z.enum(DISPLAY_FIELD_TYPES),
+  formatType: FormatType.optional(),
+  format: z.string().optional(),
+  relatedKey: z.string().optional(),
+  relatedObject: z.string().optional(),
+  code: z.object({
+    language: z.string().default('plaintext'),
+    width: z.string().optional(),
+    height: z.string().optional(),
+  }).optional(),
+  securityConfig: SecurityConfigSpec.optional(),
+  link: LinkSpec.optional(),
+});
+
+const SelectStaticSpec = z.object({
+  options: z.array(z.object({ name: z.string(), value: z.string() })).optional(),
+  optionSource: z.string().optional(),             // e.g. 'local.timezones', resolved by client static-option registry
+}).refine((v) => (v.options && v.options.length > 0) || v.optionSource, {
+  message: 'select requires options[] or optionSource',
+});
+
+const EditEntrySpec = z.object({
+  field: z.string().min(1),
+  label: z.string().optional(),
+  required: z.boolean().default(false),
+  editableOnCreateOnly: z.boolean().default(false),
+  hiddenOnCreate: z.boolean().default(false),
+  fieldType: z.enum(['input', 'select', 'selectDynamic', 'textArea', 'code', 'spacer']),
+  fieldTypeSub: z.enum(['text', 'email', 'tel', 'url', 'number', 'date', 'datetime-local', 'time']).optional(),
+  placeholder: z.string().optional(),
+  textArea: z.object({ rows: z.number().int().positive().default(4) }).optional(),
+  code: z.object({ language: z.string().default('plaintext') }).optional(),
+  select: z.union([SelectStaticSpec, SelectDynamicSpec]).optional(),
+}).superRefine((v, ctx) => {
+  if (v.fieldType === 'select' && !v.select) {
+    ctx.addIssue({ code: 'custom', message: 'select fieldType requires select config', path: ['select'] });
+  }
+  if (v.fieldType === 'selectDynamic' && !(v.select && 'queryConfig' in v.select)) {
+    ctx.addIssue({ code: 'custom', message: 'selectDynamic fieldType requires SelectDynamicSpec (queryConfig)', path: ['select'] });
+  }
+});
+
+// `component` stays z.string() (open), not a closed enum — see ASSUMPTION in
+// §7 re: Open Decision #4 (component roadmap not yet settled).
+export const FieldSpec = z.object({
+  id: z.string().min(1),
+  type: z.enum(['content', 'component', 'empty']),
+  object: z.string().optional(),
+  hideOnCreate: z.boolean().default(false),
+  conditions: ConditionSpec.optional(),
+  join: JoinSpec.optional(),                        // only meaningful when type:'component'
+  component: z.string().optional(),
+  componentConfig: z.record(z.unknown()).optional(), // NOT type-checked here — see Risks §7
+  display: FieldDisplaySpec.optional(),
+  edit: z.union([EditEntrySpec, z.array(EditEntrySpec)]).optional(), // array = composite (defect #7 contract)
+}).superRefine((v, ctx) => {
+  if (v.type === 'content' && !v.object) {
+    ctx.addIssue({ code: 'custom', message: 'content field requires object', path: ['object'] });
+  }
+  if (v.type === 'component' && !v.component) {
+    ctx.addIssue({ code: 'custom', message: 'component field requires component', path: ['component'] });
+  }
+  if (v.display?.fieldType === 'composite' && !Array.isArray(v.edit)) {
+    ctx.addIssue({ code: 'custom', message: 'composite fieldType requires edit as an array', path: ['edit'] });
+  }
+});

package/schemas/layouts/format.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+// Canonical set of display-formatting behaviors, unified across the three
+// duplicated call sites (Column.svelte, ModernField.svelte,
+// SectionTableRowColumn.svelte) plus formatDisplayValue.js's switch — see
+// maps.md §1.8. 'user' renders a linked-user chip (relatedKey/relatedObject
+// pair on the owning FieldSpec/TableFieldSpec resolves who to show).
+export const FormatType = z.enum([
+  'timestamp', 'phone', 'currency', 'number', 'percentage', 'boolean', 'user',
+  'securityBlurHover', 'securityBlurAlways', 'securityLastX', 'securityFirstX', 'securityFirstLastX',
+  'none',
+]);
+
+// `format` is the free-form, formatType-specific option string (e.g. a
+// date-fns pattern for 'timestamp', a comma/rounded mode for 'number') —
+// deliberately left as z.string() rather than a per-type union: the shapes
+// are too varied (date pattern vs. numeric mode vs. a related-object field
+// name for 'user') to usefully close without duplicating
+// formatDisplayValue.js's switch here. Resolution stays a client concern.
+export const FormatSpec = z.object({
+  formatType: FormatType,
+  format: z.string().optional(),
+});

package/schemas/layouts/index.js

@@ -0,0 +1,16 @@
+export * from './primitives.js';
+export * from './format.js';
+export * from './join.js';
+export * from './selectDynamic.js';
+export * from './field.js';
+export * from './kanban.js';
+export * from './relatedList.js';
+export * from './action.js';
+export * from './section.js';
+export * from './compact.js';
+export * from './layoutDoc.js';
+export { validateLayoutDoc } from './validate.js';
+export {
+  migrateLayoutSchema, migrateToLatest, MIGRATIONS, CURRENT_SCHEMA_VERSION,
+} from './migrations/index.js';
+export { migrateV1toV2 } from './migrations/migrateV1toV2.js';

package/schemas/layouts/join.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+
+// Today's shape is {column, value} reused by three consumers with different
+// meanings (maps.md §2.6, confirmed): table/component joins use `column` =
+// child FK, `value` = Mustache template against the *parent* record (e.g.
+// "{{id}}"); kanban child-records joins use {childField, parentField} where
+// `parentField` names the field on the parent record directly (no template
+// wrapper). Canonical shape unifies on the kanban naming (it's already
+// un-templated and clearer) — table/component's `value:"{{x}}"` form is
+// normalized to `parentField: "x"` by normalizeJoinSpec below.
+export const JoinSpec = z.object({
+  childField: z.string().min(1)
+    .describe('FK column on the child/related object that stores the parent id (legacy: table/component join.column, kanban join.childField)'),
+  parentField: z.string().min(1).default('id')
+    .describe('Field read off the parent record to match (legacy: kanban join.parentField; table/component join.value as "{{parentField}}")'),
+});
+
+const MUSTACHE_RE = /^\{\{\s*([\w.]+)\s*\}\}$/;
+
+// legacyKind: 'table' | 'component' | 'kanbanChildRecords' — all three raw
+// shapes observed in maps.md §1.6/§1.7/§1.10 map onto one JoinSpec.
+export function normalizeJoinSpec(raw, legacyKind) {
+  if (!raw) return undefined;
+  if (legacyKind === 'kanbanChildRecords') {
+    return { childField: raw.childField, parentField: raw.parentField || 'id' };
+  }
+  // table / component: {column, value: "{{field}}"}
+  const match = typeof raw.value === 'string' ? raw.value.match(MUSTACHE_RE) : null;
+  return {
+    childField: raw.column,
+    parentField: match ? match[1] : (raw.value || 'id'),
+  };
+}

package/schemas/layouts/kanban.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { JoinSpec } from './join.js';
+import { FormatType } from './format.js';
+
+// Reconciles the 3-modes-described-3-different-ways problem (maps.md §1.7)
+// into one discriminated union, and replaces ad hoc cardFields[] with
+// compactLayoutId (inline cardFields[] still tolerated, per V2-PLAN §1.4:
+// "with inline override still allowed").
+const KanbanCardFieldRef = z.object({
+  field: z.string().min(1),
+  display: z.string().optional(),
+  formatType: FormatType.optional(),
+  format: z.string().optional(),
+  type: z.enum(['link']).optional(),
+  linkObject: z.string().optional(),
+  linkField: z.string().optional(),
+});
+
+const KanbanCardSourceSpec = z.object({
+  compactLayoutId: z.string().optional(),           // canonical, v2-preferred
+  cardFields: z.array(KanbanCardFieldRef).optional(), // legacy inline fallback, tolerated indefinitely
+}).refine((v) => v.compactLayoutId || (v.cardFields && v.cardFields.length > 0), {
+  message: 'kanban requires compactLayoutId or a non-empty cardFields[]',
+});
+
+const KanbanSummarySpec = z.object({
+  type: z.enum(['count', 'sum', 'avg', 'min', 'max']),
+  field: z.string().optional(),
+  enabled: z.boolean().default(true),
+  formatType: z.enum(['currency', 'number']).optional(),
+  format: z.string().optional(),
+}).refine((v) => v.type === 'count' || !!v.field, {
+  message: 'field is required unless type is "count"', path: ['field'],
+});
+
+const KanbanActionsSpec = z.object({
+  create: z.boolean().default(false),
+  edit: z.boolean().default(true),
+  delete: z.boolean().default(false),
+  cardClick: z.enum(['tab', 'modal', 'none']).default('modal'),
+});
+
+const KanbanShared = z.object({
+  summaries: z.array(KanbanSummarySpec).default([]),
+  actions: KanbanActionsSpec.default({}),
+});
+
+const KanbanSimple = KanbanCardSourceSpec.and(KanbanShared).and(z.object({
+  mode: z.literal('simple'),
+  columnField: z.string().min(1),
+  columnSort: z.enum(['asc', 'desc']).default('asc'),
+}));
+
+const KanbanRelated = KanbanCardSourceSpec.and(KanbanShared).and(z.object({
+  mode: z.literal('related'),
+  configObject: z.string().min(1),
+  configObjectField: z.string().min(1),
+  stagesObject: z.string().min(1),
+  stagesColumnField: z.string().min(1),
+  stagesOrderField: z.string().optional(),
+  stagesSortDirection: z.enum(['asc', 'desc']).default('asc'),
+  relationship: z.object({
+    configToStages: z.object({ field: z.string().min(1), relatedField: z.string().min(1) }),
+    mainToConfig: z.object({ field: z.string().min(1), relatedField: z.string().min(1) }),
+  }),
+  stageMapping: z.object({ mainField: z.string().min(1), stageField: z.string().min(1) }),
+  autoSelect: z.object({
+    enabled: z.boolean().default(false),
+    field: z.string().optional(),
+    value: z.string().optional(),
+  }).default({ enabled: false }),
+}));
+
+const KanbanChildRecords = KanbanCardSourceSpec.and(KanbanShared).and(z.object({
+  mode: z.literal('child-records'),
+  childObject: z.string().min(1),
+  join: JoinSpec,
+  stageMapping: z.object({
+    field: z.string().min(1),
+    lookupObject: z.string().optional(),
+    lookupDisplayField: z.string().optional(),
+    lookupOrderField: z.string().optional(),
+    filterByParent: z.boolean().default(false),
+    stageParentField: z.string().optional(),
+    parentRecordField: z.string().optional(),
+  }),
+}));
+
+// z.union (not discriminatedUnion) because each branch is itself a .and()
+// intersection — zod's discriminatedUnion requires each member to be a bare
+// ZodObject with the literal at the top level, which intersections aren't.
+// Runtime cost is negligible (3 candidates, small objects); revisit if this
+// list grows.
+export const KanbanConfigSpec = z.union([KanbanSimple, KanbanRelated, KanbanChildRecords]);

package/schemas/layouts/layoutDoc.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { MustacheTemplate } from './primitives.js';
+import { SectionSpec } from './section.js';
+import { ActionSpec } from './action.js';
+
+const ToggleSpec = z.object({
+  enabled: z.boolean().default(false),
+  hideOnCreate: z.boolean().default(false),
+});
+
+export const LayoutDoc = z.object({
+  schemaVersion: z.literal(2).default(2),
+  objectName: z.string().min(1),     // canonical key — legacy `object` normalized away by migrateV1toV2
+  type: z.enum(['list', 'detail']),  // 'compact' docs validate against CompactLayoutDoc instead
+  tabName: MustacheTemplate.default('{{objectName}}'),
+  tabIcon: z.string().default('fa-database'),
+  sections: z.array(SectionSpec).default([]),
+  feeds: ToggleSpec.optional(),
+  notes: ToggleSpec.optional(),
+  aiInsights: ToggleSpec.optional(),
+  aiGoals: ToggleSpec.optional(),
+  googleDrive: z.object({
+    enabled: z.boolean().default(false),
+    hideOnCreate: z.boolean().default(false),
+    sharedDriveId: z.string().optional(),
+    folderPath: z.string().optional(),
+  }).optional(),
+  filterPanel: z.object({
+    enabled: z.boolean().default(true),
+    defaultCollapsed: z.boolean().default(false),
+  }).optional(),
+  // v2 canonical: array of ActionSpec, replaces v1's bespoke {create?, edit?}
+  // object — see migrations/deriveActions.js for the additive v1→v2 mapping.
+  actions: z.array(ActionSpec).default([]),
+});

package/schemas/layouts/migrations/deriveActions.js

@@ -0,0 +1,70 @@
+// Pure fn, no zod import. Maps legacy `layout.actions{create,edit}` (a
+// bespoke boolean-flag object — real stored docs mostly have this as `{}`)
+// plus per-table action booleans (TableSpec.actions.{create,edit,delete})
+// into the v2-canonical ActionSpec[] shape (schemas/layouts/action.js).
+// Additive only: if `doc.actions` is already an array (already v2-shaped),
+// it's passed through unchanged rather than re-derived.
+//
+// `skipTableIds` (optional Set, Phase 5 addition): table ids already
+// promoted to RelatedListSpec by promoteRelatedLists.js. A promoted table's
+// create/delete already surface via the promoted section-placed ActionSpec
+// (create) and RelatedListSpec.rowActions.delete (delete) — deriving a
+// second, row-placed ActionSpec here for the same table would double the
+// affordance. See migrateV1toV2.js for how the two derivations are composed.
+export function deriveActions(doc, { skipTableIds } = {}) {
+  if (Array.isArray(doc.actions)) {
+    return doc.actions;
+  }
+
+  const legacy = doc.actions || {};
+  const objectName = doc.objectName || doc.object;
+  const skip = skipTableIds || new Set();
+  const derived = [];
+
+  if (legacy.create) {
+    derived.push({
+      id: 'header-create',
+      type: 'create',
+      target: objectName,
+      mode: 'modal',
+      placement: 'header',
+    });
+  }
+  if (legacy.edit) {
+    derived.push({
+      id: 'header-edit',
+      type: 'edit',
+      target: objectName,
+      mode: 'modal',
+      placement: 'header',
+    });
+  }
+
+  // Per-table create/delete booleans surface as row-placed ActionSpecs so
+  // Phase 4's action registry has one uniform ActionSpec[] to read,
+  // regardless of where the boolean originally lived. (Per-table `edit` is
+  // deliberately not derived: it's the default row-click behavior already,
+  // not a distinct affordance — see TableSpec.actions.edit default:true.)
+  for (const section of doc.sections || []) {
+    const tables = section.tables || (section.object ? [section] : []);
+    for (const table of tables) {
+      if (!table.actions) continue;
+      const tableId = table.id || section.id;
+      if (skip.has(tableId)) continue;
+      if (table.actions.create) {
+        derived.push({
+          id: `${tableId}-create`, type: 'create', target: table.object,
+          mode: 'modal', placement: 'row',
+        });
+      }
+      if (table.actions.delete) {
+        derived.push({
+          id: `${tableId}-delete`, type: 'delete', target: table.object,
+          mode: 'modal', placement: 'row',
+        });
+      }
+    }
+  }
+
+  return derived;
+}

package/schemas/layouts/migrations/deriveCompactFields.js

@@ -0,0 +1,19 @@
+// Pure fn, no zod import. Flattens a detail-shaped `sections[]` doc into
+// CompactLayoutDoc.fields[] when `type==='compact'` — only invoked by
+// migrateV1toV2 when a compact-typed legacy doc has `sections` but no
+// `fields` yet (see migrateV1toV2.js). CompactLayoutDoc caps at 12 fields
+// (schemas/layouts/compact.js), so this stops collecting once it hits that.
+export function deriveCompactFields(doc) {
+  const fields = [];
+
+  for (const section of doc.sections || []) {
+    for (const row of section.rows || []) {
+      for (const column of row.columns || []) {
+        fields.push(column);
+        if (fields.length >= 12) return fields;
+      }
+    }
+  }
+
+  return fields;
+}

package/schemas/layouts/migrations/index.js

@@ -0,0 +1,43 @@
+import { migrateV1toV2 } from './migrateV1toV2.js';
+
+export const CURRENT_SCHEMA_VERSION = 2;
+
+// v0 -> v1: no-op placeholder. No genuinely un-versioned document has ever
+// existed in production (schemaVersion was introduced alongside v2 itself),
+// but the step is defined so migrateToLatest's version-walking loop has no
+// gap for the `doc.schemaVersion` absent/0 default case — see
+// SPEC-PHASE-5.md §2.1's registry sample.
+function v0ToV1(json) {
+  return { json, schemaVersion: 1, changes: [] };
+}
+
+export const MIGRATIONS = { 1: v0ToV1, 2: migrateV1toV2 };
+
+/**
+ * Runs every migration step from `fromVersion` (exclusive) up to
+ * CURRENT_SCHEMA_VERSION (inclusive), threading `changes[]` through.
+ * @param {object} json
+ * @param {number} fromVersion
+ * @param {{ objectName?: string, layoutKind?: 'list'|'detail'|'compact' }} [ctx]
+ * @returns {{ json: object, schemaVersion: number, changes: string[] }}
+ */
+export function migrateToLatest(json, fromVersion, ctx) {
+  let out = { json, schemaVersion: fromVersion || 0, changes: [] };
+  for (let v = (fromVersion || 0) + 1; v <= CURRENT_SCHEMA_VERSION; v++) {
+    const step = MIGRATIONS[v];
+    if (!step) continue;
+    const result = step(out.json, ctx);
+    out = { json: result.json, schemaVersion: v, changes: [...out.changes, ...result.changes] };
+  }
+  return out;
+}
+
+// Convenience wrapper: migrate a stored doc, reading its own schemaVersion
+// (public API — announced in CHANGELOG.md 4.2.0 as
+// `sdk.layouts.schema.migrateLayoutSchema(doc)`). Docs that predate the
+// schemaVersion column entirely default to 0 (equivalent in practice to 1 —
+// the v0->v1 step is a no-op — since either way only migrateV1toV2 does
+// real work).
+export function migrateLayoutSchema(doc, ctx = {}) {
+  return migrateToLatest(doc, doc?.schemaVersion ?? 0, ctx);
+}

package/schemas/layouts/migrations/migrateV1toV2.js

@@ -0,0 +1,162 @@
+import { normalizeJoin } from './normalizeJoin.js';
+import { normalizeKanban } from './normalizeKanban.js';
+import { deriveActions } from './deriveActions.js';
+import { deriveCompactFields } from './deriveCompactFields.js';
+import { promoteRelatedLists } from './promoteRelatedLists.js';
+
+/**
+ * @param {object} doc
+ * @param {string[]} changes
+ * @returns {{ rest: object, objectName: string }}
+ */
+// SPEC-PHASE-5.md §2.1 step 1. `object`/`objectName` are written together,
+// same value, by loadLayoutFromJson (client, builder) — canonicalize to
+// `objectName`, drop `object`. On drift (both present, disagree), keep
+// objectName's value per `edit/[id]/+page.svelte`'s own source-of-truth
+// convention, and record the drift for backfill-sweep review rather than
+// silently picking one.
+function canonicalizeObjectName(doc, changes) {
+  const { object, objectName, ...rest } = doc;
+  if (object && objectName && object !== objectName) {
+    changes.push(`objectName: drift detected (object="${object}" vs objectName="${objectName}") — kept objectName`);
+  } else if (object && !objectName) {
+    changes.push('objectName: canonicalized from legacy "object" key');
+  }
+  return { rest, objectName: objectName || object };
+}
+
+// TableSpec.join (schemas/layouts/section.js) is canonical-JoinSpec-only —
+// unlike the raw document's other legacy keys, there's no dual
+// legacy-shape + relationship pair for a table's join, so a successful
+// normalization REPLACES `join` in place. A skipped (carve-out) join is
+// dropped entirely rather than left as a legacy shape that would fail
+// JoinSpec validation — TableSpec.join is `.optional()` precisely for this
+// ("absent = top-level list table, no parent record").
+function normalizeTableJoin(table, changes, sectionId) {
+  if (!table.join) return table;
+  const { relationship, skipped } = normalizeJoin(table.join, 'table');
+  if (skipped) {
+    changes.push(`section "${sectionId}" table "${table.id}": join left as legacy shape (non-trivial template or missing column)`);
+    const { join, ...rest } = table;
+    return rest;
+  }
+  changes.push(`section "${sectionId}" table "${table.id}": join normalized to relationship`);
+  return { ...table, join: relationship };
+}
+
+// SPEC-PHASE-5.md §2.1 step 2. Wraps a legacy flat single-table section
+// (section.object/fields/join/actions/orderBy/additionalWhere, no
+// tables[]) into `section.tables = [{...}]`, field-for-field — does NOT
+// reuse sectionOperations.js:initializeTablesArray (client-side), which
+// builds a *blank* table config and would discard the existing values (see
+// spec §2.1 step 2 and the sibling app1-client work item fixing that
+// function for the same reason). `header` is carried into the new table
+// (multi-table sections can give each table its own sub-header) but also
+// LEFT at the section level, since BaseSection.header is required and this
+// same value is what the section's own title already reads today.
+function wrapLegacyTable(section, changes) {
+  const id = section.id ? `${section.id}-table` : 'legacy-table';
+  changes.push(`section "${section.id}": legacy single-table shape wrapped into tables[]`);
+  const { object, fields, join, actions, orderBy, additionalWhere, ...rest } = section;
+  const table = normalizeTableJoin({
+    id, object, fields: fields || [], join, actions: actions || {}, orderBy, additionalWhere,
+    header: section.header,
+  }, changes, section.id);
+  return { ...rest, tables: [table] };
+}
+
+// FieldSpec.join (component-typed fields) is likewise canonical-only — see
+// normalizeTableJoin above. DEVIATION from SPEC-PHASE-5.md's literal step
+// list, which doesn't call out component fields separately: real stored
+// data (examples.json's company-detail "Related Engagements" section) has
+// `field.join = {column, value}` on a type:'component' field, using the
+// same 3-consumer semantics table row as component joins generally. Added
+// per the same reasoning Phase 1 already documented for this exact gap.
+function normalizeRows(rows, changes) {
+  if (!Array.isArray(rows)) return rows;
+  return rows.map((row) => ({
+    ...row,
+    columns: (row.columns || []).map((column) => {
+      if (column.type !== 'component' || !column.join) return column;
+      const { relationship, skipped } = normalizeJoin(column.join, 'component');
+      if (skipped) {
+        changes.push(`field "${column.id}": join left as legacy shape (non-trivial template or missing column)`);
+        return column;
+      }
+      changes.push(`field "${column.id}": component join normalized to relationship`);
+      return { ...column, join: relationship };
+    }),
+  }));
+}
+
+// DEVIATION (Phase 5, found reading real fixture data, not called out in
+// SPEC-PHASE-5.md): a section can carry `type: "table"` while also having
+// a `kanban` block, `tables[]`, and `defaultView` — i.e. it's actually a
+// table-kanban hybrid, but the builder never updated `type` when the
+// kanban toggle was added (examples.json's company-detail "Opportunities"
+// section, id "section4"). SectionSpec's discriminated union has no
+// `kanban` key on the `type:'table'` branch (TableSection), so leaving the
+// tag wrong means a `.safeParse()` silently drops the kanban config from
+// validated output. Retag before validation ever sees it.
+function normalizeSectionType(section, changes) {
+  if (section.type === 'table' && section.kanban && (section.tables || section.object)) {
+    changes.push(`section "${section.id}": type normalized "table" -> "table-kanban" (kanban block present alongside tables)`);
+    return 'table-kanban';
+  }
+  return section.type;
+}
+
+/**
+ * @param {object} layoutJson - raw stored layout.layout / layoutVersions.layoutJson (schemaVersion 0/1)
+ * @param {{ objectName?: string, layoutKind?: 'list'|'detail'|'compact' }} [ctx]
+ * @returns {{ json: object, schemaVersion: 2, changes: string[] }}
+ */
+export function migrateV1toV2(layoutJson, ctx = {}) {
+  const changes = [];
+  const { rest, objectName: docObjectName } = canonicalizeObjectName(layoutJson, changes);
+  const objectName = docObjectName || ctx.objectName;
+
+  const promotedCreateActions = [];
+  const allPromotedIds = new Set();
+
+  const sections = (rest.sections || []).map((section) => {
+    let next = { ...section, type: normalizeSectionType(section, changes), rows: normalizeRows(section.rows, changes) };
+
+    if (next.type === 'table' && !section.tables && section.object) {
+      next = wrapLegacyTable(next, changes);
+    } else if (section.tables) {
+      next.tables = section.tables.map((t) => normalizeTableJoin(t, changes, section.id));
+    }
+
+    if (section.kanban) {
+      next.kanban = normalizeKanban(section.kanban, changes, section.id);
+    }
+
+    if (next.tables && next.tables.length) {
+      const { relatedLists, createActions, promotedIds } = promoteRelatedLists(next, objectName, changes);
+      if (relatedLists.length) next.relatedLists = relatedLists;
+      promotedCreateActions.push(...createActions);
+      promotedIds.forEach((id) => allPromotedIds.add(id));
+    }
+
+    return next;
+  });
+
+  const migrated = {
+    ...rest,
+    schemaVersion: 2,
+    objectName,
+    sections,
+    actions: [
+      ...deriveActions({ ...rest, objectName, sections }, { skipTableIds: allPromotedIds }),
+      ...promotedCreateActions,
+    ],
+  };
+
+  if (rest.type === 'compact' && rest.sections && !rest.fields) {
+    migrated.fields = deriveCompactFields(rest);
+    changes.push('compact: derived fields[] from sections[] rows/columns');
+  }
+
+  return { json: migrated, schemaVersion: 2, changes };
+}