@pilotiq/pilotiq 0.1.0

package/src/elements/dispatchForm.ts

@@ -0,0 +1,1855 @@
+import { Element } from '../schema/Element.js'
+import { Field, type AfterStateUpdatedContext } from '../fields/Field.js'
+import { RepeaterField, isRepeaterField } from '../fields/RepeaterField.js'
+import type { RepeaterRelationshipConfig } from '../fields/RepeaterField.js'
+import { BuilderField, isBuilderField } from '../fields/BuilderField.js'
+import type { BuilderRelationshipConfig } from '../fields/BuilderField.js'
+import { Form, type FormContext } from './Form.js'
+import { validateSchema, type ValidationErrors } from '../validation/index.js'
+import { resolveSavedNotification, type NotificationMeta } from '../notifications/index.js'
+import {
+  getParentRelationDescriptor,
+  getMorphRelationDescriptor,
+  getM2MRelationDescriptor,
+  computeMorphPayload,
+  getPrimaryKey,
+  resolveRelatedQuery,
+  type ModelLike,
+  type MorphRelationDescriptor,
+} from '../orm/modelDefaults.js'
+import { resolveM2MAccessor } from '../orm/m2mAccessor.js'
+
+export interface DispatchSuccess<R> {
+  ok:            true
+  record:        R
+  redirect:      string | undefined
+  /**
+   * Resolved success notifications to flash to the client. Empty when the
+   * form has `disableSavedNotification()` or no spec configured. Currently
+   * only delivered through the JSON action-modal path; the form-post 303
+   * path drops them until a flash mechanism lands.
+   */
+  notifications: NotificationMeta[]
+}
+
+export interface DispatchFailure {
+  ok:     false
+  errors: ValidationErrors
+}
+
+export type DispatchResult<R> = DispatchSuccess<R> | DispatchFailure
+
+/**
+ * Run the full form submit lifecycle on a `Form` element. Mode is inferred
+ * from `ctx.record`: undefined → create, set → update. Mode-specific hooks
+ * fire after their generic counterparts so cross-cutting logic (auth
+ * stamping, audit fields) lives above mode-specific business rules.
+ *
+ * Order:
+ *
+ *   validateSchema
+ *     → form-level validators
+ *     → mutateData (both modes)
+ *     → mutateDataBeforeCreate / mutateDataBeforeUpdate
+ *     → beforeSave (both modes)
+ *     → beforeCreate / beforeUpdate
+ *     → handleCreate || handleUpdate || save     ← persistence
+ *     → afterCreate / afterUpdate
+ *     → afterSave (both modes)
+ *     → redirectAfterSave
+ *
+ * Validation failures short-circuit and return `{ ok: false, errors }`. On
+ * success the result includes the saved record and the resolved redirect URL
+ * (when `redirectAfterSave` is configured).
+ *
+ * Form-level validator errors are keyed under `_form` so the renderer can
+ * surface them as a top-of-form banner without colliding with field names.
+ */
+export async function dispatchFormSubmit<R = unknown>(
+  form: Form<R>,
+  body:  Record<string, unknown>,
+  ctx:   FormContext<R>,
+): Promise<DispatchResult<R>> {
+  const children = form.getChildren() ?? []
+  const isCreate = ctx.record === undefined
+
+  const fieldErrors = await validateSchema(children as Element[], body, ctx.record)
+
+  const formValidatorErrors: string[] = []
+  for (const v of form.getFormValidators()) {
+    const msg = await v(body, { values: body, ...(ctx.record !== undefined ? { record: ctx.record } : {}) })
+    if (msg) formValidatorErrors.push(msg)
+  }
+
+  const errors: ValidationErrors = { ...fieldErrors }
+  if (formValidatorErrors.length > 0) {
+    errors['_form'] = formValidatorErrors
+  }
+
+  if (Object.keys(errors).length > 0) {
+    return { ok: false, errors }
+  }
+
+  let data: Record<string, unknown> = coerceFormValues(children as Element[], body)
+  // Flatten `simple()` Repeaters from the wrapped `[{name: v}]` pipeline
+  // shape to the user-declared `[v]` storage shape before any user-side
+  // transform runs. Non-simple repeaters are untouched.
+  data = unwrapSimpleRepeaters(children as Element[], data)
+
+  // Pull relationship-backed Repeater values OUT of `data` so the
+  // parent's save handler doesn't try to write them as a JSON column.
+  // The deferral list holds the rows + the field reference; we run
+  // the create/update/delete diff against the relation AFTER the
+  // parent save returns (so we have a parent PK in create mode).
+  const relationshipDeferrals = extractRelationshipRepeaters(children as Element[], data)
+  // Same trick for Builders. Heterogeneous-row sibling — each row is a
+  // `{ __id?, type, data }` envelope persisted as a child carrying a
+  // discriminator column + a JSON payload column.
+  const builderRelationshipDeferrals = extractRelationshipBuilders(children as Element[], data)
+
+  const mutate = form.getMutateData()
+  if (mutate) data = await mutate(data, { ...ctx, values: data })
+
+  const modeMutate = isCreate ? form.getMutateDataBeforeCreate() : form.getMutateDataBeforeUpdate()
+  if (modeMutate) data = await modeMutate(data, { ...ctx, values: data })
+
+  const before = form.getBeforeSave()
+  if (before) await before(data, { ...ctx, values: data })
+
+  const modeBefore = isCreate ? form.getBeforeCreate() : form.getBeforeUpdate()
+  if (modeBefore) await modeBefore(data, { ...ctx, values: data })
+
+  const persist = (isCreate ? form.getHandleCreate() : form.getHandleUpdate()) ?? form.getSave()
+  if (!persist) {
+    throw new Error(
+      '[Pilotiq] Form has no save() handler. Configure Form.save() (or handleCreate/handleUpdate) on the page schema, or override Resource.pages() with a Page that supplies one.',
+    )
+  }
+  const record = await persist(data, { ...ctx, values: data })
+
+  // Persist the relationship-backed Repeater diffs against the saved
+  // parent. Runs BEFORE `afterCreate / afterUpdate` so user hooks can
+  // observe the fully-saved tree (parent + children).
+  if (relationshipDeferrals.length > 0 || builderRelationshipDeferrals.length > 0) {
+    const parentModel = (ctx as { parentModel?: ModelLike }).parentModel
+    if (!parentModel) {
+      throw new Error(
+        '[Pilotiq] Repeater/Builder.relationship: form has relationship-backed rows but no parentModel on the FormContext. ' +
+        'Routes that submit forms with relationship-backed Repeaters/Builders must set ctx.parentModel = R.model.',
+      )
+    }
+    for (const deferral of relationshipDeferrals) {
+      await persistRelationshipRows(record, deferral, parentModel)
+    }
+    for (const deferral of builderRelationshipDeferrals) {
+      await persistRelationshipBuilderRows(record, deferral, parentModel)
+    }
+  }
+
+  const modeAfter = isCreate ? form.getAfterCreate() : form.getAfterUpdate()
+  if (modeAfter) await modeAfter(record, { ...ctx, record, values: data })
+
+  const after = form.getAfterSave()
+  if (after) await after(record, { ...ctx, record, values: data })
+
+  const redirectFn = form.getRedirectAfterSave()
+  const redirect = redirectFn ? redirectFn(record, { ...ctx, record, values: data }) : undefined
+
+  const notification = resolveSavedNotification(
+    form,
+    isCreate ? 'create' : 'update',
+    record,
+    { ...ctx, record, values: data },
+  )
+  const notifications = notification ? [notification] : []
+
+  return { ok: true, record, redirect, notifications }
+}
+
+/**
+ * Coerce raw form-body strings into the runtime types each field expects:
+ * booleans for toggles, numbers for number inputs, Dates for dates. The
+ * browser submits everything as a string by default, but ORM layers (Prisma,
+ * etc.) expect actual booleans/numbers/Dates. Runs after validation so
+ * validators still see the raw submitted text.
+ *
+ * Empty / missing values are normalized:
+ *   - `toggle`  → `false` when missing or 'false'/empty; `true` otherwise.
+ *   - `number`  → `null` when empty; otherwise `Number(v)` (NaN passes through).
+ *   - `date`    → `null` when empty; otherwise a `Date` parsed from the string.
+ *
+ * Other field types are passed through untouched.
+ */
+export function coerceFormValues(
+  elements: Element[],
+  body:     Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...body }
+
+  // Plan #14 — Repeater pass. Run BEFORE the regular field coercion so
+  // each row's body is coerced against the inner schema (recursive
+  // `coerceFormValues` call), not against the parent form. Two body
+  // shapes supported: array-valued JSON (`out[name]` already an array)
+  // and flat-keyed form bodies (`name.0.childName=…`). Flat-shape keys
+  // are removed from `out` after the Repeater value is composed so they
+  // don't leak into the persisted record.
+  walkRepeatersTopLevel(elements, repeater => {
+    if (repeater.isDehydrated() === false) {
+      delete out[repeater.name]
+      return
+    }
+    out[repeater.name] = coerceRepeaterValue(repeater, out)
+    const prefix = `${repeater.name}.`
+    for (const key of Object.keys(out)) {
+      if (key.startsWith(prefix)) delete out[key]
+    }
+  })
+
+  // Plan #14 follow-up — Builder pass. Same disposition as Repeater
+  // (run BEFORE the generic field walker so per-row inner-schema
+  // coercion uses the row's own body, not the parent form's), but each
+  // row's coercion is dispatched against the block matching the row's
+  // `type` discriminator. Rows whose `type` doesn't match a registered
+  // block have their `data` body passed through verbatim — better to
+  // round-trip than to silently drop unknown content.
+  walkBuildersTopLevel(elements, builder => {
+    if (builder.isDehydrated() === false) {
+      delete out[builder.name]
+      return
+    }
+    out[builder.name] = coerceBuilderValue(builder, out)
+    const prefix = `${builder.name}.`
+    for (const key of Object.keys(out)) {
+      if (key.startsWith(prefix)) delete out[key]
+    }
+  })
+
+  walkFields(elements, field => {
+    const name = field.name
+
+    // Plan #6 — `dehydrated(false)` fields are decorative / computed;
+    // their value never enters the persisted record. Drop the body key
+    // before any coercion or validation runs so downstream code can't
+    // see it.
+    if (field.isDehydrated() === false) {
+      delete out[name]
+      return
+    }
+
+    const raw  = out[name]
+    switch (field.fieldType) {
+      case 'toggle':
+      case 'checkbox': {
+        if (raw === undefined || raw === null || raw === '' || raw === 'false' || raw === '0' || raw === false) {
+          out[name] = false
+        } else {
+          out[name] = true
+        }
+        break
+      }
+      case 'number':
+      case 'slider': {
+        if (raw === undefined || raw === null || raw === '') {
+          out[name] = null
+        } else if (typeof raw === 'string') {
+          out[name] = Number(raw)
+        }
+        break
+      }
+      case 'date':
+      case 'dateTime': {
+        // Both 'date' and 'dateTime' accept ISO strings and
+        // YYYY-MM-DD(THH:mm) shapes — `new Date()` handles both.
+        if (raw === undefined || raw === null || raw === '') {
+          out[name] = null
+        } else if (typeof raw === 'string') {
+          out[name] = new Date(raw)
+        }
+        break
+      }
+      case 'checkboxList': {
+        // HTML form bodies post checkbox-lists as either an array (when
+        // multiple boxes are checked) or a single string (one checked) or
+        // undefined (none). Normalize all three to `string[]`.
+        if (raw === undefined || raw === null) {
+          out[name] = []
+        } else if (Array.isArray(raw)) {
+          out[name] = raw.map(v => String(v))
+        } else {
+          out[name] = [String(raw)]
+        }
+        break
+      }
+      case 'tagsInput': {
+        // Client serializes the chip set as a JSON-encoded string in a
+        // single hidden input. Parse back into `string[]`. Already-array
+        // values pass through (e.g. when a `live()` partial-resolve has
+        // already shipped structured data, or when a server-side default
+        // landed pre-coerce). Empty / null / unparseable → `[]`.
+        if (raw === undefined || raw === null || raw === '') {
+          out[name] = []
+        } else if (Array.isArray(raw)) {
+          out[name] = raw.map(v => String(v))
+        } else if (typeof raw === 'string') {
+          try {
+            const parsed = JSON.parse(raw)
+            if (Array.isArray(parsed)) {
+              out[name] = parsed.map(v => String(v))
+            } else {
+              out[name] = []
+            }
+          } catch {
+            out[name] = []
+          }
+        } else {
+          out[name] = []
+        }
+        break
+      }
+      case 'color': {
+        // Empty string → null so DB nullable columns accept it. Otherwise
+        // pass the hex string through verbatim.
+        if (raw === undefined || raw === null || raw === '') {
+          out[name] = null
+        }
+        break
+      }
+      case 'fileUpload': {
+        // The browser already turned uploaded files into URLs via the
+        // `_uploads` route; what arrives here is either a string, a
+        // string[] (multi-mode), or a JSON-encoded array (when the
+        // client serialized through a hidden input). Normalize to the
+        // declared shape: array bodies → string[], string body → string.
+        if (raw === undefined || raw === null || raw === '') {
+          out[name] = null
+        } else if (Array.isArray(raw)) {
+          out[name] = raw.map(v => String(v))
+        } else if (typeof raw === 'string') {
+          // Try JSON-decode for multi-file fields encoded as JSON; otherwise pass through.
+          if (raw.startsWith('[')) {
+            try {
+              const parsed = JSON.parse(raw)
+              if (Array.isArray(parsed)) { out[name] = parsed.map(v => String(v)); break }
+            } catch { /* fall through */ }
+          }
+          out[name] = raw
+        }
+        break
+      }
+      case 'keyValue': {
+        // Client serializes the row map as a JSON string in a hidden
+        // input. Parse back into a Record<string,string>; filter empty
+        // rows (`{ "": "" }`) before yielding so the persisted record
+        // doesn't carry placeholder noise. Already-object values pass
+        // through (e.g. when the `live()` partial-resolve already shipped
+        // structured data).
+        let parsed: Record<string, string> = {}
+        if (raw === undefined || raw === null || raw === '') {
+          parsed = {}
+        } else if (typeof raw === 'string') {
+          try {
+            const obj = JSON.parse(raw)
+            if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+              for (const [k, v] of Object.entries(obj)) {
+                parsed[String(k)] = v == null ? '' : String(v)
+              }
+            }
+          } catch { parsed = {} }
+        } else if (typeof raw === 'object' && !Array.isArray(raw)) {
+          for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+            parsed[String(k)] = v == null ? '' : String(v)
+          }
+        }
+        const filtered: Record<string, string> = {}
+        for (const [k, v] of Object.entries(parsed)) {
+          if (k === '' && v === '') continue
+          filtered[k] = v
+        }
+        out[name] = filtered
+        break
+      }
+      case 'richtext': {
+        // Editor posts the document as a JSON-encoded string via a hidden
+        // input. Prisma's Json column wants a real object, so parse here.
+        // Empty / unparseable → null so the column accepts it.
+        if (raw === undefined || raw === null || raw === '') {
+          out[name] = null
+        } else if (typeof raw === 'string') {
+          try { out[name] = JSON.parse(raw) }
+          catch { out[name] = null }
+        }
+        break
+      }
+      default:
+        // text/textarea/email/select/slug — leave as string.
+        break
+    }
+  })
+  return out
+}
+
+function walkFields(elements: Element[], visit: (f: Field) => void): void {
+  for (const el of elements) {
+    if (el instanceof Field) {
+      visit(el)
+      // Plan #14 — don't recurse into Repeater / Builder children. Their
+      // inner schemas belong to row bodies, not the parent form's body,
+      // so the parent walker would coerce siblings against the wrong
+      // values map. The dedicated Repeater + Builder passes in
+      // `coerceFormValues` recurse into rows with the proper per-row body.
+      if (el instanceof RepeaterField) continue
+      if (el instanceof BuilderField)  continue
+    }
+    const children = el.getChildren()
+    if (children && children.length > 0) walkFields(children as Element[], visit)
+  }
+}
+
+/**
+ * Walk an element tree and visit every top-level Repeater — i.e., every
+ * `RepeaterField` that isn't itself nested inside another Repeater. Inner
+ * Repeaters are handled recursively when the outer Repeater coerces its
+ * row bodies against the inner schema (which then enters this walker
+ * again from `coerceFormValues`).
+ */
+function walkRepeatersTopLevel(
+  elements: Element[],
+  visit:    (f: RepeaterField) => void,
+): void {
+  for (const el of elements) {
+    if (el instanceof RepeaterField) {
+      visit(el)
+      continue
+    }
+    // Builder boundaries are also opaque — its inner schemas live per-row
+    // and never need to be visited by the Repeater pass.
+    if (el instanceof BuilderField) continue
+    const children = el.getChildren()
+    if (children && children.length > 0) walkRepeatersTopLevel(children as Element[], visit)
+  }
+}
+
+/**
+ * Walk an Element tree and visit every top-level Builder — i.e., every
+ * `BuilderField` that isn't itself nested inside a Repeater or another
+ * Builder. Inner Builders are reached recursively when the outer
+ * array-row field coerces its row bodies (which then re-enters this
+ * walker via `coerceFormValues`).
+ */
+function walkBuildersTopLevel(
+  elements: Element[],
+  visit:    (f: BuilderField) => void,
+): void {
+  for (const el of elements) {
+    if (el instanceof BuilderField) {
+      visit(el)
+      continue
+    }
+    if (el instanceof RepeaterField) continue
+    const children = el.getChildren()
+    if (children && children.length > 0) walkBuildersTopLevel(children as Element[], visit)
+  }
+}
+
+/**
+ * Build the coerced array value for a single Builder field from the
+ * parent form body. Two body shapes are supported:
+ *
+ * 1. **JSON-shape** — `body[name]` is `unknown[]`. Each entry should be
+ *    an object with shape `{ __id?, type, data?: {…} }`. Non-object
+ *    entries coerce to a sentinel empty row; missing / non-string `type`
+ *    rounds to `''` (resolver flags as `unknownType`).
+ * 2. **Flat-shape** — body has keys like `${name}.${i}.type`,
+ *    `${name}.${i}.__id`, `${name}.${i}.data.${childName}`. Indices are
+ *    grouped, gaps filled with empty rows, and the per-block schema
+ *    drives coercion of `data.*` keys.
+ *
+ * Trailing rows whose `data` body is empty are trimmed (matching
+ * Repeater's posture). The row's `__id` and `type` alone don't keep a
+ * row alive — same trim semantics.
+ */
+function coerceBuilderValue(
+  field: BuilderField,
+  body:  Record<string, unknown>,
+): Array<Record<string, unknown>> {
+  const fieldName = field.name
+  const raw       = body[fieldName]
+
+  type RawRow = { __id?: string; type: string; data: Record<string, unknown> }
+  let rows: RawRow[] = []
+
+  if (Array.isArray(raw)) {
+    rows = raw.map(coerceBuilderRowEntry)
+  } else {
+    const prefix  = `${fieldName}.`
+    const grouped = new Map<number, RawRow>()
+    let maxIdx = -1
+    for (const key of Object.keys(body)) {
+      if (!key.startsWith(prefix)) continue
+      const rest = key.slice(prefix.length)
+      const dot  = rest.indexOf('.')
+      if (dot < 0) continue
+      const idxStr = rest.slice(0, dot)
+      const tail   = rest.slice(dot + 1)
+      const idx    = Number(idxStr)
+      if (!Number.isInteger(idx) || idx < 0) continue
+      if (idx > maxIdx) maxIdx = idx
+      let row = grouped.get(idx)
+      if (!row) { row = { type: '', data: {} }; grouped.set(idx, row) }
+      const value = body[key]
+      if (tail === '__id') {
+        if (typeof value === 'string') row.__id = value
+      } else if (tail === 'type') {
+        if (typeof value === 'string') row.type = value
+      } else if (tail.startsWith('data.')) {
+        row.data[tail.slice('data.'.length)] = value
+      } else if (tail === 'data') {
+        // Whole `data` body posted as a single value (rare — typically
+        // a stringified JSON blob from a hidden input). Best-effort parse.
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+          row.data = { ...(value as Record<string, unknown>) }
+        } else if (typeof value === 'string' && value !== '') {
+          try {
+            const parsed = JSON.parse(value)
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+              row.data = parsed as Record<string, unknown>
+            }
+          } catch { /* leave row.data alone */ }
+        }
+      }
+    }
+    if (maxIdx >= 0) {
+      rows = Array.from({ length: maxIdx + 1 }, (_, i) => grouped.get(i) ?? { type: '', data: {} })
+    }
+  }
+
+  // Trim trailing empty rows (matches Repeater). A row counts as empty
+  // when its `data` body has no values beyond round-tripped sentinels.
+  // Note we don't gate on `type` — a freshly-picked block with no fields
+  // typed in is still "untouched" for the purposes of submit-trim.
+  while (rows.length > 0 && isBuilderRowEmpty(rows[rows.length - 1]!)) {
+    rows.pop()
+  }
+
+  return rows.map(row => {
+    const block = field.getBlock(row.type)
+    let coercedData: Record<string, unknown>
+    if (block) {
+      coercedData = coerceFormValues(block.getSchema(), row.data)
+    } else {
+      // Unknown block type — pass `data` through verbatim so a stale
+      // record with a since-removed block type doesn't lose its
+      // contents on the next save. Validation will surface the issue.
+      coercedData = { ...row.data }
+    }
+    const out: Record<string, unknown> = { type: row.type, data: coercedData }
+    if (typeof row.__id === 'string') out['__id'] = row.__id
+    return out
+  })
+}
+
+function coerceBuilderRowEntry(raw: unknown): { __id?: string; type: string; data: Record<string, unknown> } {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { type: '', data: {} }
+  }
+  const r = raw as Record<string, unknown>
+  const type = typeof r['type'] === 'string' ? (r['type'] as string) : ''
+  const dataRaw = r['data']
+  const data: Record<string, unknown> = (dataRaw && typeof dataRaw === 'object' && !Array.isArray(dataRaw))
+    ? { ...(dataRaw as Record<string, unknown>) }
+    : {}
+  const out: { __id?: string; type: string; data: Record<string, unknown> } = { type, data }
+  if (typeof r['__id'] === 'string') out.__id = r['__id'] as string
+  return out
+}
+
+function isBuilderRowEmpty(row: { type: string; data: Record<string, unknown> }): boolean {
+  for (const [k, v] of Object.entries(row.data)) {
+    if (v === undefined || v === null || v === '') continue
+    void k
+    return false
+  }
+  return true
+}
+
+/**
+ * Build the coerced array value for a single Repeater field from the
+ * parent form body. Two body shapes are supported:
+ *
+ * 1. **JSON-shape** — `body[name]` is an `unknown[]`. Each element should
+ *    be an object; non-object entries coerce to `{}`. This is the SPA
+ *    `fetch+JSON` path (the default since `feedback_action_dispatch_fetch_vs_303.md`).
+ * 2. **Flat-shape** — body has keys like `${name}.${i}.${childName}`.
+ *    The browser submits these for `application/x-www-form-urlencoded`
+ *    bodies when the form-post 303 fallback path is used. Indices are
+ *    grouped, gaps are filled with `{}`, and the resulting per-row
+ *    bodies feed into the recursive coercion call.
+ *
+ * Empty trailing rows (no entered values, only `__id` carrying through
+ * from the previous render) are trimmed before the coerced array is
+ * returned.
+ */
+function coerceRepeaterValue(
+  field: RepeaterField,
+  body:  Record<string, unknown>,
+): Array<Record<string, unknown>> {
+  const inner     = field.getInnerSchema()
+  const fieldName = field.name
+  const raw       = body[fieldName]
+  const simpleInner = field.getSimpleInnerField()
+
+  let rowBodies: Array<Record<string, unknown>> = []
+  if (Array.isArray(raw)) {
+    rowBodies = raw.map(r => simpleInner ? coerceSimpleEntry(r, simpleInner.name) : coerceRowEntry(r))
+  } else {
+    const prefix = `${fieldName}.`
+    const grouped = new Map<number, Record<string, unknown>>()
+    let maxIdx = -1
+    for (const key of Object.keys(body)) {
+      if (!key.startsWith(prefix)) continue
+      const rest = key.slice(prefix.length)
+      const dot = rest.indexOf('.')
+      if (dot < 0) continue
+      const idxStr = rest.slice(0, dot)
+      const childKey = rest.slice(dot + 1)
+      const idx = Number(idxStr)
+      if (!Number.isInteger(idx) || idx < 0) continue
+      if (idx > maxIdx) maxIdx = idx
+      let row = grouped.get(idx)
+      if (!row) { row = {}; grouped.set(idx, row) }
+      row[childKey] = body[key]
+    }
+    if (maxIdx >= 0) {
+      rowBodies = Array.from({ length: maxIdx + 1 }, (_, i) => grouped.get(i) ?? {})
+    }
+  }
+
+  // Trim trailing rows where the user didn't enter anything beyond the
+  // round-tripped `__id`. We trim BEFORE coercion so default fills (e.g.
+  // toggle → false, number → null) don't disguise an untouched row as a
+  // touched one. Only trailing emptiness — gaps in the middle survive.
+  while (rowBodies.length > 0 && isRawRowEmpty(rowBodies[rowBodies.length - 1]!)) {
+    rowBodies.pop()
+  }
+
+  return rowBodies.map(rowBody => {
+    const coerced = coerceFormValues(inner, rowBody)
+    if (typeof rowBody['__id'] === 'string') coerced['__id'] = rowBody['__id']
+    return coerced
+  })
+}
+
+function coerceRowEntry(raw: unknown): Record<string, unknown> {
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    return { ...(raw as Record<string, unknown>) }
+  }
+  return {}
+}
+
+/**
+ * Variant of `coerceRowEntry` for `Repeater.simple(field)`. Wraps a
+ * primitive entry under the inner field's name so the rest of the
+ * coerce pipeline keeps using `{ <innerName>: v }` row shape. Object
+ * entries pass through. The unwrap (back to `[v]`) happens once at the
+ * top of `dispatchFormSubmit` via `unwrapSimpleRepeaters`.
+ */
+function coerceSimpleEntry(raw: unknown, innerName: string): Record<string, unknown> {
+  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+    return { ...(raw as Record<string, unknown>) }
+  }
+  if (raw === undefined) return {}
+  return { [innerName]: raw }
+}
+
+/**
+ * After `coerceFormValues` has produced wrapped `[{<innerName>: v}]`
+ * rows for every Repeater in the schema, flatten the `simple()` ones
+ * back to `[v, v, …]` for storage. Non-simple repeaters are left alone.
+ *
+ * Runs before `mutateData` / `save` so user-facing data already uses
+ * the storage shape they declared via `.simple(field)` — they don't
+ * have to remember the internal wrapping at the save site.
+ *
+ * Tolerates already-flat input (e.g. when a `dehydrated(false)` upstream
+ * has dropped wrapping, or when the user manually fed a flat array
+ * through `withValues`) by re-emitting verbatim.
+ */
+export function unwrapSimpleRepeaters(
+  elements: Element[],
+  values:   Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...values }
+  walkRepeatersTopLevel(elements, repeater => {
+    const innerName = repeater.getSimpleInnerField()?.name
+    if (!innerName) return
+    const rows = out[repeater.name]
+    if (!Array.isArray(rows)) return
+    out[repeater.name] = rows.map(row => {
+      if (row && typeof row === 'object' && !Array.isArray(row)) {
+        return (row as Record<string, unknown>)[innerName]
+      }
+      return row
+    })
+  })
+  return out
+}
+
+function isRawRowEmpty(rowBody: Record<string, unknown>): boolean {
+  for (const [k, v] of Object.entries(rowBody)) {
+    if (k === '__id') continue
+    if (v === undefined || v === null || v === '') continue
+    return false
+  }
+  return true
+}
+
+/**
+ * Walk an Element tree and return every `Form` instance, in document order.
+ * Used by route handlers to locate the form being submitted on a page that
+ * may declare more than one.
+ *
+ * Uses a structural `getType() === 'form'` check rather than `instanceof
+ * Form`. Vite's SSR module cache can load the package through two
+ * different module paths during a single dev session — the path used by
+ * the rudder SSR route and the path used by Vike's `+data` hook for SPA
+ * navigations end up importing different `Form` classes, so `instanceof`
+ * silently returns false and the form goes "missing" on SPA nav while
+ * SSR keeps working. The structural check is robust to that and matches
+ * the convention used elsewhere in the codebase (see Filter, Column,
+ * Action — all keyed on the serialized type, not class identity).
+ */
+export function findForms(elements: ReadonlyArray<Element>): Form[] {
+  const forms: Form[] = []
+  const walk = (els: ReadonlyArray<Element>): void => {
+    for (const el of els) {
+      if (el.getType() === 'form') forms.push(el as Form)
+      // Plan #14 — don't dive into Repeater / Builder children. Forms
+      // inside an array-row field don't have row context for dispatch,
+      // so finding them at the parent level would mis-route submissions.
+      // Use structural checks (not `instanceof`) per the Vite SSR module
+      // duplication note above.
+      if (isRepeaterField(el)) continue
+      if (isBuilderField(el))  continue
+      const children = el.getChildren()
+      if (children && children.length > 0) walk(children)
+    }
+  }
+  walk(elements)
+  return forms
+}
+
+/**
+ * Plan #8 — locate the children of a Wizard step at the given index inside
+ * the form's tree. Returns `undefined` when the form has no Wizard
+ * descendant or the step index is out of range. Step children are returned
+ * as a fresh Element[] so callers can pass them straight to
+ * `validateSchema`. Walks structurally (`getType() === 'wizard'/'step'`)
+ * to stay robust to Vite SSR module-cache duplication.
+ */
+export function findWizardStepFields(
+  formChildren: ReadonlyArray<Element>,
+  stepIndex:    number,
+): Element[] | undefined {
+  let wizard: Element | undefined
+  const walk = (els: ReadonlyArray<Element>): void => {
+    for (const el of els) {
+      if (el.getType() === 'wizard') { wizard = el; return }
+      const children = el.getChildren()
+      if (children && children.length > 0) walk(children)
+      if (wizard) return
+    }
+  }
+  walk(formChildren)
+  if (!wizard) return undefined
+  const steps = (wizard.getChildren() ?? []).filter(c => c.getType() === 'step')
+  const step = steps[stepIndex]
+  if (!step) return undefined
+  return step.getChildren() ?? []
+}
+
+/**
+ * Pick the `Form` matching the submitted `_formId`, or fall back to the
+ * first form on the page when no id was sent OR the submitted id misses.
+ *
+ * Use this on **legacy form-submit paths** (POST create / edit / global-edit
+ * / custom-page) where a single page may host multiple forms and the
+ * fallback to "first form" is a back-compat affordance for submissions that
+ * predate the `_formId` hidden input.
+ *
+ * Do NOT use this on partial-resolve paths (Plan #5 form-state, Plan #8
+ * wizard step-validate) — those must hard-fail on a mismatched id so the
+ * client gets a 404 instead of silently writing the wrong form's state.
+ * Use `selectFormById` there.
+ */
+export function selectForm(forms: ReadonlyArray<Form>, submittedId: unknown): Form | undefined {
+  if (typeof submittedId === 'string') {
+    const match = forms.find(f => f.getFormId() === submittedId)
+    if (match) return match
+  }
+  return forms[0]
+}
+
+/**
+ * ID-match counterpart to `selectForm`, used by partial-resolve endpoints
+ * (Plan #5 form-state, Plan #8 wizard step-validate).
+ *
+ * - If `id` matches a form, return it.
+ * - If there's no match AND the page has exactly one form, return that
+ *   form. This is safe — there's no ambiguity about which form the POST
+ *   meant — and it removes the auto-counter desync footgun: the GET
+ *   render and the partial-resolve POST run through `Form.make()` in
+ *   different requests, so the process-global formId counter ticks
+ *   forward and a strict match would 404. See
+ *   `feedback_pilotiq_live_forms_pin_formid.md`.
+ * - Otherwise return `undefined`. Multi-form pages with a missing/wrong
+ *   id must hard-fail so the client surfaces a 404 instead of writing
+ *   the wrong form's state.
+ *
+ * Pages with multiple reactive forms still need to pin a stable
+ * `Form.make().formId(...)` to disambiguate.
+ */
+export function selectFormById(forms: ReadonlyArray<Form>, id: string): Form | undefined {
+  const match = forms.find(f => f.getFormId() === id)
+  if (match) return match
+  if (forms.length === 1) return forms[0]
+  return undefined
+}
+
+// ─── Plan #5: applyStateUpdate ────────────────────────────
+
+export interface StateUpdateContext<R = unknown> {
+  record?: R
+  user?:   unknown
+  request?: unknown
+}
+
+export interface StateUpdateResult {
+  /**
+   * Updated values map after coercing the changed field and running
+   * its `afterStateUpdated` hook. The same object the client should
+   * rebind to its inputs on the next render.
+   */
+  values: Record<string, unknown>
+  /**
+   * Field names whose value was written via `$set` during this resolve.
+   * Includes the changed field itself. The client uses this to decide
+   * which inputs to update without disrupting focus on others.
+   */
+  dirty:  string[]
+}
+
+/**
+ * Apply a partial-resolve update from the client. Coerces the changed
+ * field's value (other fields keep whatever the client sent), runs the
+ * field's `afterStateUpdated` hook with bound `$get / $set` helpers,
+ * and returns the updated values + names of fields whose values were
+ * mutated. The caller (the partial-resolve route handler) feeds the
+ * resulting values into `resolveSchema` to produce a fresh form meta.
+ *
+ * Returns `null` when the changed field name doesn't correspond to a
+ * field on the form — the route handler turns this into a 404.
+ *
+ * Plan #14 — `changed` may be a dotted path into a Repeater row
+ * (`items.2.quantity` or, for nested Repeaters, `items.0.modifiers.1.name`).
+ * The dotted form routes through `applyRepeaterStateUpdate` which scopes
+ * `$get / $set` to the innermost row by default; cross-row reads / writes
+ * go through the parent `$get / $set` using a full dotted path.
+ */
+export async function applyStateUpdate<R = unknown>(
+  form:    Form<R>,
+  values:  Record<string, unknown>,
+  changed: string,
+  ctx:     StateUpdateContext<R> = {},
+): Promise<StateUpdateResult | null> {
+  const children = (form.getChildren() ?? []) as Element[]
+
+  if (changed.includes('.')) {
+    // Plan #14 — dotted paths route to the array-row field that owns
+    // the path's first segment. Builder paths look like `name.<i>.data.<leaf>`
+    // (the literal `data` segment is the giveaway); Repeater paths look
+    // like `name.<i>.<leaf>`. Inspect the first segment's field on the
+    // schema to dispatch.
+    const head = changed.split('.', 1)[0]!
+    const headField = findFieldDirect(children, head)
+    if (headField instanceof BuilderField) {
+      return applyBuilderStateUpdate(headField, values, changed, ctx)
+    }
+    return applyRepeaterStateUpdate(children, values, changed, ctx)
+  }
+
+  const target = findFieldByName(children, changed)
+  if (!target) return null
+
+  // Coerce the changed field only — other fields may have been mid-edit
+  // on the client and we don't want to clobber their in-flight state.
+  const coerced = { ...values }
+  const subset: Record<string, unknown> = { [changed]: values[changed] }
+  const after  = coerceFormValues([target], subset)
+  coerced[changed] = after[changed]
+
+  const dirty = new Set<string>([changed])
+
+  const hook = target.getAfterStateUpdated()
+  if (hook) {
+    const $get = (name: string): unknown => coerced[name]
+    const $set = (name: string, v: unknown): void => {
+      coerced[name] = v
+      dirty.add(name)
+    }
+    const hookCtx: AfterStateUpdatedContext = {
+      $get,
+      $set,
+      values: coerced,
+      ...(ctx.record  !== undefined ? { record:  ctx.record  } : {}),
+      ...(ctx.user    !== undefined ? { user:    ctx.user    } : {}),
+      ...(ctx.request !== undefined ? { request: ctx.request } : {}),
+    }
+    await hook(coerced[changed], hookCtx)
+  }
+
+  return { values: coerced, dirty: Array.from(dirty) }
+}
+
+function findFieldByName(elements: Element[], name: string): Field | undefined {
+  for (const el of elements) {
+    if (el instanceof Field && el.name === name) return el
+    // Plan #14 — don't dive into Repeater / Builder inner schemas when
+    // looking for a top-level field; row-local fields are addressed via
+    // dotted paths through `applyRepeaterStateUpdate` /
+    // `applyBuilderStateUpdate`.
+    if (el instanceof RepeaterField) continue
+    if (el instanceof BuilderField)  continue
+    const children = el.getChildren()
+    if (children && children.length > 0) {
+      const hit = findFieldByName(children as Element[], name)
+      if (hit) return hit
+    }
+  }
+  return undefined
+}
+
+/**
+ * Plan #14 — resolve a dotted-path live-update into a Repeater row.
+ *
+ * `changed` looks like `items.2.quantity` (one level) or
+ * `items.0.modifiers.1.name` (nested). Segments alternate field-name and
+ * row-index. The leaf must be a real Field inside the innermost
+ * Repeater's inner schema. Returns `null` (→ 404) when the path doesn't
+ * resolve.
+ *
+ * Mutates a shallow-cloned `values` so the caller gets a fresh map and
+ * the input isn't aliased. Row arrays + row maps along the path are
+ * cloned to avoid mutating shared state in the input.
+ */
+async function applyRepeaterStateUpdate<R>(
+  children: Element[],
+  values:   Record<string, unknown>,
+  changed:  string,
+  ctx:      StateUpdateContext<R>,
+): Promise<StateUpdateResult | null> {
+  const resolved = resolveRepeaterPath(children, changed)
+  if (!resolved) return null
+  const { field, rowPath } = resolved
+
+  const coerced = { ...values }
+
+  // Clone path-traversed arrays + row maps so we can mutate them without
+  // touching the caller's input. Final row map is the innermost row.
+  let rowMap = ensureRowAtPath(coerced, rowPath)
+
+  // Coerce only the leaf field's value — read raw value from the existing
+  // row map, then run it through `coerceFormValues` against the leaf field
+  // alone, and write the coerced value back.
+  const rawAtPath = rowMap[field.name]
+  const coercedSubset = coerceFormValues([field], { [field.name]: rawAtPath })
+  rowMap[field.name] = coercedSubset[field.name]
+
+  const dirty = new Set<string>([changed])
+
+  const hook = field.getAfterStateUpdated()
+  if (hook) {
+    const innermost = rowPath[rowPath.length - 1]!
+    const rowPrefix = rowPath.map(r => `${r.repeater.name}.${r.index}`).join('.')
+
+    const $get = (name: string): unknown => {
+      if (name.includes('.')) return readDottedPath(coerced, name)
+      return rowMap[name]
+    }
+    const $set = (name: string, v: unknown): void => {
+      if (name.includes('.')) {
+        writeDottedPath(coerced, name, v)
+        dirty.add(name)
+        return
+      }
+      rowMap[name] = v
+      dirty.add(`${rowPrefix}.${name}`)
+    }
+
+    const row = {
+      index: innermost.index,
+      $get:  (name: string): unknown => rowMap[name],
+      $set:  (name: string, v: unknown): void => {
+        rowMap[name] = v
+        dirty.add(`${rowPrefix}.${name}`)
+      },
+    }
+
+    const hookCtx: AfterStateUpdatedContext = {
+      $get,
+      $set,
+      values: coerced,
+      row,
+      ...(ctx.record  !== undefined ? { record:  ctx.record  } : {}),
+      ...(ctx.user    !== undefined ? { user:    ctx.user    } : {}),
+      ...(ctx.request !== undefined ? { request: ctx.request } : {}),
+    }
+
+    await hook(rowMap[field.name], hookCtx)
+  }
+
+  return { values: coerced, dirty: Array.from(dirty) }
+}
+
+interface ResolvedPath {
+  field:   Field
+  rowPath: Array<{ repeater: RepeaterField; index: number }>
+}
+
+/**
+ * Walk a dotted path against an Element tree. Segments alternate
+ * field-name and row-index. Returns the leaf Field plus the chain of
+ * (Repeater, index) hops needed to reach it.
+ */
+function resolveRepeaterPath(elements: Element[], path: string): ResolvedPath | null {
+  const segments = path.split('.')
+  const rowPath: Array<{ repeater: RepeaterField; index: number }> = []
+
+  let currentElements = elements
+  let i = 0
+  while (i < segments.length) {
+    const seg = segments[i]!
+    const field = findFieldDirect(currentElements, seg)
+    if (!field) return null
+
+    if (i === segments.length - 1) {
+      return { field, rowPath }
+    }
+
+    if (!(field instanceof RepeaterField)) return null
+    const idxStr = segments[i + 1]
+    if (idxStr === undefined) return null
+    const idx = Number(idxStr)
+    if (!Number.isInteger(idx) || idx < 0) return null
+
+    rowPath.push({ repeater: field, index: idx })
+    currentElements = field.getInnerSchema()
+    i += 2
+  }
+
+  return null
+}
+
+/**
+ * Find a top-level field by name inside an element tree, walking through
+ * non-Repeater containers but stopping at Repeater boundaries (those need
+ * a dotted path to address inner fields).
+ */
+function findFieldDirect(elements: Element[], name: string): Field | undefined {
+  for (const el of elements) {
+    if (el instanceof Field && el.name === name) return el
+    if (el instanceof RepeaterField) continue
+    const children = el.getChildren()
+    if (children && children.length > 0) {
+      const hit = findFieldDirect(children as Element[], name)
+      if (hit) return hit
+    }
+  }
+  return undefined
+}
+
+/**
+ * Walk + clone the row arrays/maps along `rowPath`, ensuring each row
+ * exists, then return the innermost row map. Mutations on the returned
+ * object propagate up to `coerced` because we replace each step's
+ * container with a fresh clone in the parent.
+ */
+function ensureRowAtPath(
+  coerced: Record<string, unknown>,
+  rowPath: Array<{ repeater: RepeaterField; index: number }>,
+): Record<string, unknown> {
+  let parent: Record<string, unknown> | unknown[] = coerced
+  for (const { repeater, index } of rowPath) {
+    const arrName = repeater.name
+    let arr: unknown[]
+    if (Array.isArray(parent)) {
+      // Should never happen at the outer iteration (parent starts as
+      // `coerced`, an object); guard anyway.
+      arr = (parent as unknown[]).slice()
+    } else {
+      const existing = (parent as Record<string, unknown>)[arrName]
+      arr = Array.isArray(existing) ? existing.slice() : []
+      ;(parent as Record<string, unknown>)[arrName] = arr
+    }
+    while (arr.length <= index) arr.push({})
+    const existingRow = arr[index]
+    const row: Record<string, unknown> = (existingRow && typeof existingRow === 'object' && !Array.isArray(existingRow))
+      ? { ...(existingRow as Record<string, unknown>) }
+      : {}
+    arr[index] = row
+    parent = row
+  }
+  return parent as Record<string, unknown>
+}
+
+function readDottedPath(values: Record<string, unknown>, path: string): unknown {
+  const segments = path.split('.')
+  let cur: unknown = values
+  for (const seg of segments) {
+    if (cur === null || cur === undefined) return undefined
+    if (Array.isArray(cur)) {
+      const idx = Number(seg)
+      if (!Number.isInteger(idx)) return undefined
+      cur = cur[idx]
+    } else if (typeof cur === 'object') {
+      cur = (cur as Record<string, unknown>)[seg]
+    } else {
+      return undefined
+    }
+  }
+  return cur
+}
+
+function writeDottedPath(values: Record<string, unknown>, path: string, value: unknown): void {
+  const segments = path.split('.')
+  let cur: Record<string, unknown> | unknown[] = values
+  for (let i = 0; i < segments.length - 1; i++) {
+    const seg = segments[i]!
+    const nextSeg = segments[i + 1]!
+    const childIsIndex = /^\d+$/.test(nextSeg)
+    if (Array.isArray(cur)) {
+      const idx = Number(seg)
+      if (!Number.isInteger(idx)) return
+      while (cur.length <= idx) cur.push(childIsIndex ? [] : {})
+      let next = cur[idx]
+      if (next === undefined || next === null) {
+        next = childIsIndex ? [] : {}
+        cur[idx] = next
+      }
+      cur = next as Record<string, unknown> | unknown[]
+    } else {
+      let next = (cur as Record<string, unknown>)[seg]
+      if (next === undefined || next === null) {
+        next = childIsIndex ? [] : {}
+        ;(cur as Record<string, unknown>)[seg] = next
+      }
+      cur = next as Record<string, unknown> | unknown[]
+    }
+  }
+  const last = segments[segments.length - 1]!
+  if (Array.isArray(cur)) {
+    const idx = Number(last)
+    if (!Number.isInteger(idx)) return
+    cur[idx] = value
+  } else {
+    (cur as Record<string, unknown>)[last] = value
+  }
+}
+
+// ─── Plan #14 follow-up: Builder partial-resolve ─────────
+
+/**
+ * Resolve a dotted-path live-update into a Builder row.
+ *
+ * Path shape: `<name>.<i>.data.<leaf>`. The literal `data` segment
+ * separates the row's envelope (`__id`, `type`) from the block-scoped
+ * inner field. The row's block schema is selected from the values map
+ * via `values[name][i].type` — Builder rows are heterogeneous, so the
+ * schema can't be derived from the field alone.
+ *
+ * Nested array-row fields inside a block (Repeater-in-Builder, etc.)
+ * aren't supported in v1 — same posture as nested Repeater leaf depth
+ * past one level. Returns `null` (→ 404) on any unsupported shape.
+ *
+ * Mutates a shallow-cloned `values` so the caller gets a fresh map; the
+ * row array + row map + `data` map along the path are cloned to avoid
+ * aliasing the input.
+ */
+async function applyBuilderStateUpdate<R>(
+  field:    BuilderField,
+  values:   Record<string, unknown>,
+  changed:  string,
+  ctx:      StateUpdateContext<R>,
+): Promise<StateUpdateResult | null> {
+  const segments = changed.split('.')
+  // Expected: name (already matched by caller), <i>, 'data', <leaf>...
+  if (segments.length < 4) return null
+  const name    = segments[0]!
+  if (name !== field.name) return null
+  const idxStr  = segments[1]!
+  const idx     = Number(idxStr)
+  if (!Number.isInteger(idx) || idx < 0) return null
+  if (segments[2] !== 'data') return null
+  const leafName = segments[3]!
+  // Nested-array path past `data.<leaf>` not supported in v1.
+  if (segments.length > 4) return null
+
+  // Look up the row's block from the submitted values.
+  const arrRaw = values[name]
+  if (!Array.isArray(arrRaw)) return null
+  const rowRaw = arrRaw[idx]
+  if (!rowRaw || typeof rowRaw !== 'object' || Array.isArray(rowRaw)) return null
+  const blockName = (rowRaw as Record<string, unknown>)['type']
+  if (typeof blockName !== 'string' || blockName === '') return null
+  const block = field.getBlock(blockName)
+  if (!block) return null
+
+  // Locate the leaf field inside the block's schema.
+  const leafField = findFieldDirect(block.getSchema(), leafName)
+  if (!leafField) return null
+
+  // Clone path-traversed containers.
+  const coerced = { ...values }
+  const arrClone = (coerced[name] as unknown[]).slice()
+  coerced[name] = arrClone
+  const rowSrc = arrClone[idx] as Record<string, unknown>
+  const rowClone: Record<string, unknown> = { ...rowSrc }
+  arrClone[idx] = rowClone
+  const dataSrc = rowClone['data']
+  const dataClone: Record<string, unknown> = (dataSrc && typeof dataSrc === 'object' && !Array.isArray(dataSrc))
+    ? { ...(dataSrc as Record<string, unknown>) }
+    : {}
+  rowClone['data'] = dataClone
+
+  // Coerce the leaf field's value only.
+  const rawLeaf      = dataClone[leafName]
+  const coercedSubset = coerceFormValues([leafField], { [leafName]: rawLeaf })
+  dataClone[leafName] = coercedSubset[leafName]
+
+  const dirty = new Set<string>([changed])
+
+  const hook = leafField.getAfterStateUpdated()
+  if (hook) {
+    const rowPrefix = `${name}.${idx}.data`
+
+    const $get = (n: string): unknown => {
+      if (n.includes('.')) return readDottedPath(coerced, n)
+      return dataClone[n]
+    }
+    const $set = (n: string, v: unknown): void => {
+      if (n.includes('.')) {
+        writeDottedPath(coerced, n, v)
+        dirty.add(n)
+        return
+      }
+      dataClone[n] = v
+      dirty.add(`${rowPrefix}.${n}`)
+    }
+
+    const row = {
+      index:     idx,
+      blockType: block.name,
+      $get:      (n: string): unknown => dataClone[n],
+      $set:      (n: string, v: unknown): void => {
+        dataClone[n] = v
+        dirty.add(`${rowPrefix}.${n}`)
+      },
+    }
+
+    const hookCtx: AfterStateUpdatedContext = {
+      $get,
+      $set,
+      values: coerced,
+      row,
+      ...(ctx.record  !== undefined ? { record:  ctx.record  } : {}),
+      ...(ctx.user    !== undefined ? { user:    ctx.user    } : {}),
+      ...(ctx.request !== undefined ? { request: ctx.request } : {}),
+    }
+
+    await hook(dataClone[leafName], hookCtx)
+  }
+
+  return { values: coerced, dirty: Array.from(dirty) }
+}
+
+// ─── Repeater.relationship — extraction + persistence ────────
+
+interface RelationshipDeferral {
+  field: RepeaterField
+  rows:  Array<Record<string, unknown>>
+  cfg:   RepeaterRelationshipConfig
+}
+
+/**
+ * Walk the form's top-level Repeaters and extract values for any that
+ * have a `relationship(...)` config. Returns the deferral list and
+ * mutates `data` in place by deleting each extracted key — the parent's
+ * save handler doesn't need to see those values (they aren't real
+ * columns on the parent).
+ *
+ * Inner / nested Repeaters aren't supported in v1; we only walk the top
+ * level (consistent with the existing `walkRepeatersTopLevel` helper)
+ * so a relationship-backed Repeater nested inside a JSON-backed
+ * Repeater silently falls back to JSON storage. Documented as a
+ * v1 limitation in `docs/plans/repeater-relationship.md`.
+ */
+export function extractRelationshipRepeaters(
+  elements: Element[],
+  data:     Record<string, unknown>,
+): RelationshipDeferral[] {
+  const out: RelationshipDeferral[] = []
+  walkRepeatersTopLevel(elements, repeater => {
+    const cfg = repeater.getRelationship()
+    if (!cfg) return
+    const value = data[repeater.name]
+    delete data[repeater.name]
+    if (!Array.isArray(value)) return
+    out.push({
+      field: repeater,
+      rows:  value as Array<Record<string, unknown>>,
+      cfg,
+    })
+  })
+  return out
+}
+
+/**
+ * Resolved attachment shape for a relationship-backed Repeater. Five
+ * variants reflect the persisted-relation kinds we know how to write
+ * back from a Repeater submit:
+ *
+ *   - `hasMany`        — single FK column on the child.
+ *   - `morphMany`      — polymorphic owner side; `<morphName>Id` +
+ *                        `<morphName>Type` stamped on the child.
+ *                        `morphOne` collapses into this kind (storage
+ *                        shape is identical; "one row" is enforced
+ *                        upstream).
+ *   - `belongsToMany`  — pivot-table M2M; the child has no parent
+ *                        attachment column, so create + attach goes
+ *                        through `parent[rel]().attach([childPk])` and
+ *                        delete-from-row goes through `.detach([pk])`.
+ *   - `morphToMany`    — polymorphic pivot M2M; pivot row carries
+ *                        `<morphName>Type` + the parent's PK, written
+ *                        transparently by the accessor.
+ *   - `morphedByMany`  — inverse polymorphic pivot. Same accessor
+ *                        surface.
+ *
+ * The three M2M variants carry only the relation name — the persist
+ * pipeline reaches the accessor via `resolveM2MAccessor(parent, relation)`.
+ */
+type RepeaterChildAttachment =
+  | { kind: 'hasMany';        model: ModelLike; foreignKey: string }
+  | { kind: 'morphMany';      model: ModelLike; morph:      MorphRelationDescriptor }
+  | { kind: 'belongsToMany';  model: ModelLike; relation:   string }
+  | { kind: 'morphToMany';    model: ModelLike; relation:   string }
+  | { kind: 'morphedByMany';  model: ModelLike; relation:   string }
+
+/**
+ * Resolve the child model + parent-attachment shape for a
+ * relationship-backed Repeater. Five supported modes:
+ *
+ *   - `hasMany`         — single foreign key on the child.
+ *   - `morphMany` / `morphOne` — polymorphic owner side.
+ *   - `belongsToMany`   — pivot-table M2M.
+ *   - `morphToMany` / `morphedByMany` — polymorphic pivot M2M.
+ *
+ * Detection order: M2M descriptor (covers all three M2M variants) →
+ * morph descriptor (morphMany / morphOne) → hasMany. The order matters
+ * because `getParentRelationDescriptor` accepts entries with
+ * `foreignKey: string` even if the type is M2M, so checking M2M first
+ * keeps mis-shaped entries from falling through to the hasMany branch.
+ *
+ * `cfg.orderColumn` is rejected under M2M because pivot-side ordering
+ * needs ORM `orderByPivot` which v1 doesn't expose. Throwing here
+ * beats silently writing into a non-existent column on the related
+ * model.
+ *
+ * Throws a clear configuration error when the relation type isn't one
+ * of the five, or when descriptor lookup fails entirely.
+ */
+function resolveChildAndAttachment(
+  parentModel: ModelLike,
+  cfg:         RepeaterRelationshipConfig,
+): RepeaterChildAttachment {
+  const m2mDescriptor = getM2MRelationDescriptor(parentModel, cfg.name)
+  if (m2mDescriptor) {
+    if (cfg.orderColumn !== undefined) {
+      throw new Error(
+        `[Pilotiq] Repeater.relationship("${cfg.name}"): orderColumn() is not supported under ` +
+        `'${m2mDescriptor.type}' v1. Pivot-side ordering needs ORM \`orderByPivot\` which is deferred.`,
+      )
+    }
+    const model = cfg.model ?? m2mDescriptor.model()
+    if (!model) {
+      throw new Error(
+        `[Pilotiq] Repeater.relationship("${cfg.name}"): could not resolve the related model. ` +
+        `Pass it explicitly via .relationship({ name, model: RelatedModel }) or declare ` +
+        `the relation's \`model\` thunk on the parent model's static relations map.`,
+      )
+    }
+    return { kind: m2mDescriptor.type, model, relation: cfg.name }
+  }
+
+  const parentDescriptor = getParentRelationDescriptor(parentModel, cfg.name)
+  const morphDescriptor  = getMorphRelationDescriptor(parentModel, cfg.name)
+  const type             = parentDescriptor?.type
+                        ?? (morphDescriptor ? 'morphMany' : 'hasMany')
+
+  if (type === 'morphMany' || type === 'morphOne') {
+    const model = cfg.model ?? morphDescriptor?.model?.()
+    if (!model) {
+      throw new Error(
+        `[Pilotiq] Repeater.relationship("${cfg.name}"): could not resolve the child model. ` +
+        `Pass it explicitly via .relationship({ name, model: ChildModel }) or declare ` +
+        `the relation's \`model\` thunk on the parent model's static relations map.`,
+      )
+    }
+    if (!morphDescriptor) {
+      throw new Error(
+        `[Pilotiq] Repeater.relationship("${cfg.name}"): polymorphic relation entry is missing \`morphName\`. ` +
+        `Set \`relations.${cfg.name} = { type: 'morphMany', morphName: '<name>', model: () => ChildModel }\` on the parent.`,
+      )
+    }
+    return { kind: 'morphMany', model, morph: morphDescriptor }
+  }
+
+  const model      = cfg.model ?? parentDescriptor?.model()
+  const foreignKey = cfg.foreignKey ?? parentDescriptor?.foreignKey
+
+  if (!model) {
+    throw new Error(
+      `[Pilotiq] Repeater.relationship("${cfg.name}"): could not resolve the child model. ` +
+      `Pass it explicitly via .relationship({ name, model: ChildModel }) or declare ` +
+      `the relation on the parent model's static relations map.`,
+    )
+  }
+  if (!foreignKey) {
+    throw new Error(
+      `[Pilotiq] Repeater.relationship("${cfg.name}"): could not resolve the foreign-key column. ` +
+      `Pass it explicitly via .relationship({ name, foreignKey: 'parentId' }) or declare ` +
+      `it on the parent model's static relations map.`,
+    )
+  }
+  if (type !== 'hasMany') {
+    throw new Error(
+      `[Pilotiq] Repeater.relationship("${cfg.name}"): unsupported relation type '${type}'. ` +
+      `Supported: hasMany, morphMany, morphOne, belongsToMany, morphToMany, morphedByMany.`,
+    )
+  }
+
+  return { kind: 'hasMany', model, foreignKey }
+}
+
+/**
+ * Diff submitted rows against the existing related rows and apply
+ * create / update / delete operations through the child model.
+ *
+ * Identity:
+ *   - Submitted row with `__id` matching an existing PK → update.
+ *   - Submitted row without `__id` (or with one not in the existing
+ *     set) → create. The FK is stamped onto the create payload.
+ *   - Existing PK not present in any submitted `__id` → delete.
+ *
+ * Order:
+ *   - When `cfg.orderColumn` is set, every create / update payload
+ *     stamps it with the row's 0-based index.
+ *
+ * Errors propagate. v1 isn't transactional — partial failure leaves
+ * the parent saved and some children unchanged. See plan doc for the
+ * follow-up.
+ */
+async function persistRelationshipRows(
+  parent:      unknown,
+  deferral:    RelationshipDeferral,
+  parentModel: ModelLike,
+): Promise<void> {
+  const { rows, cfg, field } = deferral
+  const attachment  = resolveChildAndAttachment(parentModel, cfg)
+  const { model }   = attachment
+  const pk          = getPrimaryKey(model)
+  const orderColumn = cfg.orderColumn
+  const parentPk    = (parent as Record<string, unknown> | undefined)?.[getPrimaryKey(parentModel)]
+  if (parentPk === undefined || parentPk === null) {
+    throw new Error(
+      `[Pilotiq] Repeater.relationship("${cfg.name}"): parent record has no primary key after save. ` +
+      `Form.save() / handleCreate() must return a record with a primary key set.`,
+    )
+  }
+
+  // Compute the morph stamp once — `computeMorphPayload` is pure.
+  const morphStamp = attachment.kind === 'morphMany'
+    ? computeMorphPayload(parent, attachment.morph)
+    : undefined
+
+  // Resolve the M2M pivot-mutation accessor once — fails closed with a
+  // clear error if the parent doesn't expose `parent[rel]()` or a
+  // legacy `parent.related(rel)` shape returning attach/detach.
+  const isM2M = attachment.kind === 'belongsToMany'
+             || attachment.kind === 'morphToMany'
+             || attachment.kind === 'morphedByMany'
+  const m2mAccessor = isM2M
+    ? resolveM2MAccessor(parent, (attachment as { relation: string }).relation)
+    : undefined
+  if (isM2M && !m2mAccessor) {
+    throw new Error(
+      `[Pilotiq] Repeater.relationship("${cfg.name}"): could not resolve the pivot-mutation accessor on the parent record. ` +
+      `Expected \`parent.${cfg.name}()\` to return \`{ attach, detach, sync }\` (rudder ORM convention). ` +
+      `Make sure the parent model declares the relation under \`static relations\` and that the prototype method is installed.`,
+    )
+  }
+
+  const existing = await loadRelationRows(parentModel, parent, cfg.name)
+  const existingByPk = new Map<string, Record<string, unknown>>()
+  for (const row of existing) {
+    const key = String((row as Record<string, unknown>)[pk])
+    existingByPk.set(key, row as Record<string, unknown>)
+  }
+
+  const keptPks = new Set<string>()
+
+  // M2M-only: the user may have declared `pivotColumns([…])`. Those
+  // names live on the pivot table, NOT the child model — split them
+  // out before each create / update so the child writes never see
+  // them and the pivot writes only see them.
+  const pivotColumnSet = (isM2M && cfg.pivotColumns && cfg.pivotColumns.length > 0)
+    ? new Set(cfg.pivotColumns)
+    : undefined
+
+  for (let idx = 0; idx < rows.length; idx++) {
+    const submitted = rows[idx] ?? {}
+    const submittedId = typeof submitted['__id'] === 'string' ? submitted['__id'] : undefined
+    const isUpdate = submittedId !== undefined && existingByPk.has(submittedId)
+
+    // Strip framework keys before constructing the payload — the
+    // child model never sees `__id`, and the parent attachment cols
+    // are stamped explicitly below so user-supplied values are
+    // ignored (FK / morph cols can't be retargeted; order is
+    // canonical from row index).
+    const payload: Record<string, unknown> = {}
+    const pivotPayload: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(submitted)) {
+      if (k === '__id') continue
+      if (pivotColumnSet?.has(k)) {
+        pivotPayload[k] = v
+      } else {
+        payload[k] = v
+      }
+    }
+    if (orderColumn !== undefined) payload[orderColumn] = idx
+    const hasPivotPayload = pivotColumnSet !== undefined
+      && Object.keys(pivotPayload).length > 0
+
+    if (isUpdate) {
+      // Don't overwrite the parent attachment on update — for hasMany
+      // the FK is already correct; for morphMany the `<morphName>Id`
+      // + `<morphName>Type` cols are too. Defense against a tampered
+      // client trying to re-link the child to a different (poly)
+      // parent. M2M variants have no parent-attachment column on the
+      // child to strip — pivot lives on its own table.
+      if (attachment.kind === 'hasMany') {
+        delete payload[attachment.foreignKey]
+      } else if (attachment.kind === 'morphMany') {
+        for (const k of Object.keys(morphStamp!)) delete payload[k]
+      }
+      // For M2M without pivot extras the row still benefits from a
+      // child-row update (user may have edited the child's own
+      // columns through the Repeater). Skip the child write only
+      // when the payload would be empty (M2M + pivot-only edits).
+      if (Object.keys(payload).length > 0) {
+        await model.update(submittedId!, payload)
+      }
+      if (hasPivotPayload) {
+        if (typeof m2mAccessor!.updatePivot !== 'function') {
+          throw new Error(
+            `[Pilotiq] Repeater.relationship("${cfg.name}").pivotColumns(...) requires a rudder ORM with \`updatePivot\` ` +
+            `on the M2M accessor (shipped via \`feat(orm): pivot-extras read/update\`). ` +
+            `Upgrade @rudderjs/orm or drop the pivotColumns call.`,
+          )
+        }
+        await m2mAccessor!.updatePivot(submittedId!, pivotPayload)
+      }
+      keptPks.add(submittedId!)
+    } else {
+      if (attachment.kind === 'hasMany') {
+        payload[attachment.foreignKey] = parentPk
+        await model.create(payload)
+      } else if (attachment.kind === 'morphMany') {
+        Object.assign(payload, morphStamp)
+        await model.create(payload)
+      } else {
+        // M2M: create the related record first, then attach via the
+        // pivot accessor. The accessor handles polymorphic stamping
+        // (`<morphName>Type`) transparently for morphToMany /
+        // morphedByMany. When `pivotColumns` is set the per-id
+        // attach map ferries pivot extras into the new pivot row.
+        const created = await model.create(payload)
+        const newPk   = (created as Record<string, unknown> | null | undefined)?.[pk]
+        if (newPk === undefined || newPk === null) {
+          throw new Error(
+            `[Pilotiq] Repeater.relationship("${cfg.name}"): newly created related record has no primary key — ` +
+            `cannot attach pivot row. Check that \`${(model as { name?: string }).name ?? 'related model'}.create()\` ` +
+            `returns a record with the primary key set.`,
+          )
+        }
+        if (hasPivotPayload) {
+          await m2mAccessor!.attach!({ [String(newPk)]: pivotPayload })
+        } else {
+          await m2mAccessor!.attach!([newPk as string | number])
+        }
+      }
+    }
+    void field
+  }
+
+  for (const [pkVal, _row] of existingByPk) {
+    if (keptPks.has(pkVal)) continue
+    if (isM2M) {
+      // Detach the pivot link only — the related record may still be
+      // attached to other parents. `cascadeDelete` opt-in is a Tier-2
+      // follow-up.
+      await m2mAccessor!.detach!([pkVal])
+    } else {
+      await model.delete(pkVal)
+    }
+    void _row
+  }
+}
+
+/**
+ * Read all rows from `parent.related(name)`. Used both by the load-
+ * side fill (in pageData) and the save-side diff (above). Caps at
+ * 10k — admin Repeaters should never get that large; if they do we'll
+ * add explicit pagination.
+ */
+export async function loadRelationRows(
+  parentModel:  ModelLike,
+  parent:       unknown,
+  name:         string,
+  pivotColumns?: readonly string[],
+): Promise<unknown[]> {
+  let q = resolveRelatedQuery(parentModel, parent, name)
+  if (pivotColumns && pivotColumns.length > 0 && typeof q.withPivot === 'function') {
+    q = q.withPivot(...pivotColumns)
+  }
+  const result = await q.paginate(1, 10000)
+  return result.data
+}
+
+// ─── Builder.relationship — extraction + persistence ─────────
+
+interface BuilderRelationshipDeferral {
+  field: BuilderField
+  rows:  Array<Record<string, unknown>>
+  cfg:   BuilderRelationshipConfig
+}
+
+/**
+ * Walk the form's top-level Builders and extract values for any that have
+ * a `relationship(...)` config. Same shape + posture as
+ * `extractRelationshipRepeaters`; mutates `data` in place by deleting each
+ * extracted key. Heterogeneous-row sibling — each row is a
+ * `{ __id?, type, data: {…} }` envelope after `coerceBuilderValue`.
+ */
+export function extractRelationshipBuilders(
+  elements: Element[],
+  data:     Record<string, unknown>,
+): BuilderRelationshipDeferral[] {
+  const out: BuilderRelationshipDeferral[] = []
+  walkBuildersTopLevel(elements, builder => {
+    const cfg = builder.getRelationship()
+    if (!cfg) return
+    const value = data[builder.name]
+    delete data[builder.name]
+    if (!Array.isArray(value)) return
+    out.push({
+      field: builder,
+      rows:  value as Array<Record<string, unknown>>,
+      cfg,
+    })
+  })
+  return out
+}
+
+/**
+ * Resolved attachment shape for a relationship-backed Builder. v1 of
+ * Builder.relationship handled `hasMany` only; the morphMany variant
+ * stamps `<morphName>Id` + `<morphName>Type` on every create instead of
+ * a single FK column. The two branches share the load path
+ * (`parent.related(name)` already filters morph cols) but differ in the
+ * persist payload.
+ */
+type BuilderChildAttachment =
+  | { kind: 'hasMany';   model: ModelLike; foreignKey: string }
+  | { kind: 'morphMany'; model: ModelLike; morph:      MorphRelationDescriptor }
+
+/**
+ * Resolve the child model + parent-attachment shape for a
+ * relationship-backed Builder. Two supported modes:
+ *
+ *   - `hasMany`   — single foreign key on the child. Falls back to
+ *                   `cfg.model` / `cfg.foreignKey` overrides when the
+ *                   parent's `static relations[name]` doesn't expose them.
+ *   - `morphMany` — polymorphic owner side. Reads the morph descriptor
+ *                   off the parent's `static relations[name]` (no
+ *                   override path — the discriminator + id columns are
+ *                   driven entirely by `morphName`). `morphOne` collapses
+ *                   into the same branch (the storage shape is identical;
+ *                   "one row" is enforced upstream by the schema).
+ *
+ * Throws a clear configuration error when the relation type isn't one of
+ * those two, or when the descriptor lookup fails entirely.
+ */
+function resolveBuilderChildAndAttachment(
+  parentModel: ModelLike,
+  cfg:         BuilderRelationshipConfig,
+): BuilderChildAttachment {
+  // Detect M2M first — a `belongsToMany` / `morphToMany` /
+  // `morphedByMany` entry has no `foreignKey`, so it would silently
+  // fall through to the hasMany branch below and surface a less-useful
+  // "could not resolve foreign-key" error. Builder rows
+  // (`{ type, data }`) don't compose with M2M pivot semantics, so this
+  // is the surface where we point users at Repeater.relationship.
+  const m2mDescriptor = getM2MRelationDescriptor(parentModel, cfg.name)
+  if (m2mDescriptor) {
+    throw new Error(
+      `[Pilotiq] Builder.relationship("${cfg.name}"): unsupported relation type '${m2mDescriptor.type}'. ` +
+      `Only 'hasMany' and 'morphMany' / 'morphOne' are supported on Builder.relationship in v1. ` +
+      `belongsToMany / morphToMany / morphedByMany are not supported — the heterogeneous {type, data} ` +
+      `envelope doesn't compose cleanly with M2M pivot semantics. Use a hasMany or morphMany relation, ` +
+      `or use Repeater.relationship if your rows are homogeneous.`,
+    )
+  }
+
+  const parentDescriptor = getParentRelationDescriptor(parentModel, cfg.name)
+  const morphDescriptor  = getMorphRelationDescriptor(parentModel, cfg.name)
+  const type             = parentDescriptor?.type
+                        ?? (morphDescriptor ? 'morphMany' : 'hasMany')
+
+  if (type === 'morphMany' || type === 'morphOne') {
+    const model = cfg.model ?? morphDescriptor?.model?.()
+    if (!model) {
+      throw new Error(
+        `[Pilotiq] Builder.relationship("${cfg.name}"): could not resolve the child model. ` +
+        `Pass it explicitly via .relationship({ name, model: ChildModel }) or declare ` +
+        `the relation's \`model\` thunk on the parent model's static relations map.`,
+      )
+    }
+    if (!morphDescriptor) {
+      throw new Error(
+        `[Pilotiq] Builder.relationship("${cfg.name}"): polymorphic relation entry is missing \`morphName\`. ` +
+        `Set \`relations.${cfg.name} = { type: 'morphMany', morphName: '<name>', model: () => ChildModel }\` on the parent.`,
+      )
+    }
+    return { kind: 'morphMany', model, morph: morphDescriptor }
+  }
+
+  const model      = cfg.model ?? parentDescriptor?.model()
+  const foreignKey = cfg.foreignKey ?? parentDescriptor?.foreignKey
+
+  if (!model) {
+    throw new Error(
+      `[Pilotiq] Builder.relationship("${cfg.name}"): could not resolve the child model. ` +
+      `Pass it explicitly via .relationship({ name, model: ChildModel }) or declare ` +
+      `the relation on the parent model's static relations map.`,
+    )
+  }
+  if (!foreignKey) {
+    throw new Error(
+      `[Pilotiq] Builder.relationship("${cfg.name}"): could not resolve the foreign-key column. ` +
+      `Pass it explicitly via .relationship({ name, foreignKey: 'parentId' }) or declare ` +
+      `it on the parent model's static relations map.`,
+    )
+  }
+  if (type !== 'hasMany') {
+    throw new Error(
+      `[Pilotiq] Builder.relationship("${cfg.name}"): unsupported relation type '${type}'. ` +
+      `Only 'hasMany' and 'morphMany' / 'morphOne' are supported on Builder.relationship in v1. ` +
+      `belongsToMany / morphToMany / morphedByMany are not supported — the heterogeneous {type, data} ` +
+      `envelope doesn't compose cleanly with M2M pivot semantics. Use a hasMany or morphMany relation, ` +
+      `or use Repeater.relationship if your rows are homogeneous.`,
+    )
+  }
+
+  return { kind: 'hasMany', model, foreignKey }
+}
+
+/**
+ * Diff submitted Builder rows against the existing related rows and apply
+ * create / update / delete operations through the child model. Same
+ * identity rules as the Repeater pair — `__id` matches an existing PK →
+ * update, missing → create, existing PK absent from submitted set →
+ * delete. Each row writes its `type` discriminator + JSON `data` payload
+ * to the configured columns.
+ */
+async function persistRelationshipBuilderRows(
+  parent:      unknown,
+  deferral:    BuilderRelationshipDeferral,
+  parentModel: ModelLike,
+): Promise<void> {
+  const { rows, cfg } = deferral
+  const attachment  = resolveBuilderChildAndAttachment(parentModel, cfg)
+  const { model }   = attachment
+  const pk          = getPrimaryKey(model)
+  const typeColumn  = cfg.typeColumn ?? 'type'
+  const dataColumn  = cfg.dataColumn ?? 'data'
+  const orderColumn = cfg.orderColumn
+  const parentPk    = (parent as Record<string, unknown> | undefined)?.[getPrimaryKey(parentModel)]
+  if (parentPk === undefined || parentPk === null) {
+    throw new Error(
+      `[Pilotiq] Builder.relationship("${cfg.name}"): parent record has no primary key after save. ` +
+      `Form.save() / handleCreate() must return a record with a primary key set.`,
+    )
+  }
+
+  // Compute the morph stamp once — `computeMorphPayload` is pure.
+  const morphStamp = attachment.kind === 'morphMany'
+    ? computeMorphPayload(parent, attachment.morph)
+    : undefined
+
+  const existing = await loadRelationRows(parentModel, parent, cfg.name)
+  const existingByPk = new Map<string, Record<string, unknown>>()
+  for (const row of existing) {
+    const key = String((row as Record<string, unknown>)[pk])
+    existingByPk.set(key, row as Record<string, unknown>)
+  }
+
+  const keptPks = new Set<string>()
+
+  for (let idx = 0; idx < rows.length; idx++) {
+    const submitted   = rows[idx] ?? {}
+    const submittedId = typeof submitted['__id'] === 'string' ? submitted['__id'] : undefined
+    const isUpdate    = submittedId !== undefined && existingByPk.has(submittedId)
+
+    const blockType = typeof submitted['type'] === 'string' ? submitted['type'] : ''
+    const blockData = (submitted['data'] && typeof submitted['data'] === 'object')
+      ? submitted['data']
+      : {}
+
+    const payload: Record<string, unknown> = {
+      [typeColumn]: blockType,
+      [dataColumn]: blockData,
+    }
+    if (orderColumn !== undefined) payload[orderColumn] = idx
+
+    if (isUpdate) {
+      // Don't overwrite the parent attachment on update — for hasMany the
+      // FK is already correct; for morphMany the `<morphName>Id` +
+      // `<morphName>Type` cols are too. Defense against a tampered
+      // client trying to re-link the child to a different polymorphic
+      // parent.
+      await model.update(submittedId!, payload)
+      keptPks.add(submittedId!)
+    } else {
+      if (attachment.kind === 'hasMany') {
+        payload[attachment.foreignKey] = parentPk
+      } else {
+        Object.assign(payload, morphStamp)
+      }
+      await model.create(payload)
+    }
+  }
+
+  for (const [pkVal] of existingByPk) {
+    if (keptPks.has(pkVal)) continue
+    await model.delete(pkVal)
+  }
+}