@structuralists/scaffolding 0.10.2 → 0.12.0

package/src/forms/plan.md

@@ -28,17 +28,35 @@ TS wall can't strand finished work behind it.
    (state/useFormState/errorAt.ts) — the smallest surface that keeps stories
    readable; item 6 folds the same lookup into `getFormFieldPropsAt`'s
    `errorMessage`. The Debugger needed no change (`toInspectable`
-   index-keys arrays).
+   index-keyed arrays at the time; it now passes them through, since
+   `JsonTable` renders arrays natively).
 4. **Item 5 — elements/state split.** Pure churn, no type risk; do it before
    item 6 so the wrappers land in their final home once. ✅ *done* — one
    `src/forms/` umbrella: elements in `src/forms/elements/<Component>/`,
    the state layer in `src/forms/state/{useFormState,validations,validators,path}/`.
 5. **Item 6 — field binding** (`getFormFieldPropsAt` + wrappers). Needs the
-   error model and the split; `Path`/`ValueAt` already validated. ← *current*
-6. **Type spike, then items 2/3/4** — the recursion risk zone. Throwaway
-   `.test-d.ts` of the full grammar at `InsuranceQuoteForm` scale *before*
+   error model and the split; `Path`/`ValueAt` already validated. ✅ *done* —
+   `getFormFieldPropsAt` on the hook result (value / typed onChange /
+   policy-aware errorMessage / onBlur), `write()` as the immutable mirror of
+   `read()` in `state/path/path.ts`, touched tracking as real state, and the
+   wrapper-style element shorthands prototyped (`state/bindings/`:
+   `TextInputForForm`, `SingleSelectForForm`). Probe ratchet held (see the
+   baseline note under the recursion budget).
+6. **Type spike, then items 2/3/4** — the recursion risk zone. ← *current*
+   Throwaway `.test-d.ts` of the full grammar at `InsuranceQuoteForm` scale *before*
    any runtime work; three outcomes (works / slow / intractable) each with a
    known response. Worst case, everything above still shipped.
+   - **Spike: ✅ done — verdict WORKS, decisively.** The full recursive
+     grammar (nested specs, `each`, arrays at every level, recursive
+     `Refine`) plus a stress tier (~110-leaf form, 12-level object ladder,
+     4-deep `each` ladder) cost **1.31× instantiations, check time flat** —
+     nowhere near the ~10×/multi-second failure thresholds. No depth caps,
+     lazy-recursion or boxing tricks needed. Two binding grammar
+     adjustments came out of it, both folded into the sketches below:
+     value-model-first branch order in `RefineField`, and the `Refine`
+     identity gate for the default-`V` case.
+   - **Phase 2 (nested object specs + recursive `Refine`): ✅ done** — see
+     "Phases" below.
 
 ## Goal
 
@@ -120,30 +138,55 @@ useFormState({
 
 ## Refinement through the grammar
 
-`Refine` becomes recursive, mirroring the grammar. Sketch:
+`Refine` is recursive, mirroring the grammar. As shipped (phase 2, with both
+type-spike adjustments):
 
 ```ts
-type ExcludedOf<V> = V extends Refinement<infer X> ? X : never;
 // MemberExcludes<C>: the per-member-sound union of a validator tuple's
 // excludes — it and SoundExcludedOf landed with phase 1 in state/validations/types.ts.
 
-type RefineField<F, C> =
-  C extends Refinement<infer X>        ? Exclude<F, X>                 // single marked validator
-  : C extends readonly unknown[]       ? Exclude<F, MemberExcludes<C>> // validator array: union of per-member-sound excludes
-  : C extends { readonly each: infer E } ? F extends FormValueList
-      ? Array<RefineObject<F[number], E>> : F                          // per-element
-  : C extends object                   ? F extends FormValuesObject
-      ? RefineObject<F, C> : F                                         // nested spec
-  : F;                                                                 // bare fn / no marker
+type RefineField<F, C> = C extends Refinement<infer Excluded>
+  ? Exclude<F, Excluded>                    // single marked validator
+  : C extends readonly unknown[]
+    ? Exclude<F, MemberExcludes<C>>         // validator array: union of per-member-sound excludes
+    : C extends object                      // structural: interrogate F (the value model) FIRST
+      ? F extends FormValueList
+        ? C extends { readonly each: infer E }
+          ? Array<RefineObject<F[number], E>>  // per-element
+          : F
+        : F extends FormValuesObject
+          ? RefineObject<F, C>              // nested spec
+          : F
+      : F;                                  // bare fn / no marker
 
 type RefineObject<T, V> = { [K in keyof T]: K extends keyof V ? RefineField<T[K], V[K]> : T[K] };
+
+// The identity gate — NOT optional (spike adjustment 2): with constraints
+// omitted, the default V = Validations<T> would distribute through the walk
+// and hand back unions of structurally-identical mapped copies of every
+// section — assignable to T but not identity-equal (mangled hover types,
+// fails toEqualTypeOf). Validations<T> extends V exactly when V is the
+// default (or empty/fully-widened — no markers survive anyway).
+type Refine<T extends FormValuesObject, V extends Validations<T>> =
+  Validations<T> extends V ? T : RefineObject<T, V>;
 ```
 
-Branch-order constraints discovered in the baseline, which this sketch bakes
-in:
+Branch-order constraints baked in (baseline + spike):
 
 - **Check `Refinement` before `object`** — validator functions are objects.
-- **A bare function** (no marker) falls to the final `F` arm — narrows nothing.
+- **The structural arms branch on the value model (`F`) before the
+  constraint's shape** (spike adjustment 1): asking `C extends { each }`
+  first would strand an object field that legitimately owns a key named
+  `each` — its nested spec would match the `each` arm, fail the list test,
+  and fall back unrefined. Pinned by the `audit` disambiguation probe in
+  `useFormState.test-d.ts`.
+- **A bare function** (no marker) falls through: on a scalar field to the
+  final `F` arm; on a structural field into `RefineObject<F, C>` with
+  `keyof C` empty — an identity map, structurally unchanged, as a
+  whole-value validator should be.
+- Nested occurrences need no identity gate: a concrete literal `V` has only
+  the keys actually written, so uncovered fields take the `T[K]` arm
+  verbatim at every level.
 - The runtime cast in `submit()` stays the same single honest cast: valid ⇒
   every constrained node passed, at every depth, which is what the recursive
   `Refine` now encodes.
@@ -187,11 +230,46 @@ multi-second check time:
 - post-step-3 (error-model swap: `Path<T>`-typed `FormError`, `errorAt`,
   plus probes): check 0.79 s, 113,724 instantiations, 52,294 types
   (+4.4% instantiations over pre-step-3 HEAD)
+- post-item-5 split (0.10.1): check 0.81 s, 112,981 instantiations,
+  52,504 types
+- post-item-6 (field binding: `getFormFieldPropsAt`, `FieldBinding`
+  wrappers, plus deep-path probes at `InsuranceQuoteForm` scale): check
+  0.82 s, 125,022 instantiations, 54,959 types (+10.7% instantiations over
+  post-item-5 — the `ValueAt` instantiations at each binding call site are
+  real but cheap; check time flat)
+- type spike (full recursive grammar, chunky + stress probes, throwaway
+  worktree — not merged): 163,262 instantiations / 65,036 types / 0.86s
+  check — 1.31× post-item-6; verdict works, no mitigation tricks required.
+  The real phases should land well under that: the spike carried a stress
+  tier (~110-leaf mega form with a large spec inlined twice, 12-level
+  object ladder, 4-deep `each` ladder) the phases don't.
+- post-phase-2 (recursive grammar + recursive `Refine` with identity gate,
+  ported chunky/boundary/negative probe suite, recursive walk): check
+  0.87 s, 133,956 instantiations, 57,762 types (+7.1% instantiations over
+  post-item-6; matches the spike's equivalent non-stress milestone at
+  134,441 almost exactly)
 
 ## Runtime consequences (can't be dodged)
 
-- **The validator walk becomes a tree walk.** Recursion mirrors `read()` in
-  `state/path/path.ts`; share the traversal or keep them deliberately parallel.
+- **The validator walk becomes a tree walk.** ✅ *Landed with phase 2*
+  (`validateEntry` in `state/validations/walk.ts` recurses, accumulating the
+  `PathStep[]` address; deliberately parallel to `read()`, not shared —
+  the walk descends a *constraints* tree, `read()` a *path*). Interpretation
+  of a structural spec is directed by the VALUE at the path, mirroring the
+  type level (see "Disambiguation").
+- **Absent sections: a nested spec on an absent/null section is skipped.**
+  *Decided with the type spike.* The type level commits to this implicitly —
+  `F` distributes naked through the structural grammar arms, so a spec on
+  `UsAddress | undefined` refines only the present branch and the
+  nullability survives around the refined interior — and the runtime walk
+  mirrors it: nothing to walk when the section is absent (same for `each`
+  over a null list). A **required section** is expressed as a *leaf*
+  validator on the section field (`mailingAddress: notEmpty(…)`), which
+  stays legal on structural fields — with the recorded caveat that leaf and
+  structural forms are mutually exclusive per key (the "whole-value +
+  structural constraints on the same key" open decision below). Never
+  "help" the grammar arms with `NonNullable<F>` wrappers — that breaks the
+  distribution and blows the recursion stack (TS2589).
 - **`FormErrors` can no longer be `Partial<Record<keyof T, string>>`.**
   ✅ *Landed with working-order step 3* (on the flat baseline, single-key
   paths). Decided: errors become a plain list of structured entries,
@@ -231,13 +309,29 @@ tests, story updates where visible, probe ratchet.
    distributes over a naked constraint parameter, which made union-typed
    *single* constraints (`cond ? v1 : v2`) sound too (union of per-branch
    refinements, pinned in `state/validations/types.test-d.ts`).
-2. **Nested object specs + recursive `Refine`.** The risk phase — the probe
-   ratchet matters most here. (The `{path, error}[]` error model already
-   landed in working-order step 3 — nested errors just carry longer paths;
-   no error plumbing changes in this phase.)
-3. **List `each` specs.** Runtime walks every element; error paths carry the
-   numeric step (`['drivers', 3, 'name']`). Refined element type flows
-   through `Array<...>`.
+2. **Nested object specs + recursive `Refine`.** The risk phase — de-risked
+   by the type spike. ✅ *done* — full recursive grammar
+   (`FieldConstraint`/`ListConstraint`/`Validations` in
+   state/validations/types.ts) and recursive `Refine` with both spike
+   adjustments (value-model-first `RefineField` branch order; the identity
+   gate); recursive `validateEntry` walk with absent-section skip; the
+   spike's chunky/boundary/soundness/negative probe suite ported into
+   `useFormState.test-d.ts` (the error model needed no change, as
+   predicted — nested errors just carry longer paths). **The `each` TYPE
+   arm landed here too** (the spike proved the grammar whole, and carving
+   it out of `RefineField` would have been artificial), but the runtime
+   walk for it is phase 3 — until then an `each` constraint on a present
+   list THROWS from the walk (pinned in walk.test.ts) rather than silently
+   not validating; on a null list it skips, which already matches phase-3
+   semantics.
+3. **List `each` specs — runtime.** The walk visits every element; error
+   paths carry the numeric step (`['drivers', 3, 'name']`), replacing the
+   phase-2 throw. (The type level — refined element flowing through
+   `Array<...>` — already landed with phase 2.) Two probes the spike says
+   to keep pinned are already in the phase-2 suite: the `audit`-style
+   "object field literally named `each`" disambiguation probe, and the
+   `each: <bare validator>` negative (rejected by TypeScript's weak-type
+   check — an obscure checker rule worth a canary).
 4. **Composition hardening.** Deep mixed fixtures (list-in-object-in-list),
    `perField` still the entry point for pre-built specs, docs
    (forms/CLAUDE.md) updated to the new grammar.
@@ -275,7 +369,29 @@ Blast radius that was handled when this landed:
   Debugger is a designated bridge layer). Explicitly allowed for in the new
   boundaries rules.
 
-## 6. Field binding: `getFormFieldPropsAt(path)` + element shorthands
+## 6. Field binding: `getFormFieldPropsAt(path)` + element shorthands ✅ done
+
+Landed as specced below; deltas and decisions:
+
+- `write()` in `state/path/path.ts` is the immutable-update mirror of
+  `read()` — clones only the spine, dead-step semantics mirror read()
+  returning undefined (writing through an absent section is an
+  identity-preserving no-op; materialize the section first).
+- Touched is real state (`useFieldBinding`), a `Path<T>[]` compared with
+  `pathsEqual` — the same structural representation as `FormErrors`. It
+  also shows up in the Debugger snapshot.
+- The error-display policy (touched-or-submitAttempted) lives inside
+  `errorMessage`, nowhere else — see "Field binding" in forms/CLAUDE.md.
+- **Element-shorthand style: the wrapper style is the prototype**
+  (`TextInputForForm`, `SingleSelectForForm` in `src/forms/state/bindings/`,
+  the second sanctioned state→elements bridge after the Debugger). The
+  wrappers declare what they display/emit via `FieldBinding<Display, Emit>`
+  and plain structural assignability rejects wrong-shaped bindings — no
+  generics at the use site. Union-typed props on the elements themselves
+  remain the fallback if the parallel component set gets heavy; judge after
+  the wrapper set grows past these two.
+
+Original spec follows.
 
 Today every field is wired by hand in JSX: read `values.x`, spread-update via
 `onValueChanges`, look up the error, gate it on `submitAttempted`. That's
@@ -427,8 +543,9 @@ Possibly a hybrid: identity-matching as the default heuristic, owned ops as
 the guaranteed path. **Research topic for when we get here** — record
 findings in the learning map before committing to either.
 
-Sequencing: visited tracking lands with item 6 (its `onBlur` is the write
-path). Keys + array-sync matter from phase 3 (list `each` specs) onward —
+Sequencing: visited tracking ✅ *landed with item 6* (its `onBlur` is the
+write path; `touched: Path<T>[]` in `useFieldBinding`, structural equality
+via `pathsEqual`). Keys + array-sync matter from phase 3 (list `each` specs) onward —
 error paths and per-element meta both need element identity once lists are
 editable.
 

package/src/forms/state/bindings/SingleSelectForForm.tsx

@@ -0,0 +1,45 @@
+import { Field } from '../../elements/Field';
+import { SingleSelect } from '../../elements/Select';
+import type { SelectOption, SelectSize } from '../../elements/Select';
+import type { FieldBinding } from '../useFormState/types';
+
+export type SingleSelectForFormProps<T extends string> = {
+  // Displays T|null|undefined, emits T — a FormFieldProps<V> fits when the
+  // path's value type sits between them, so the options' literal union and
+  // the field's type must line up or the binding fails to compile.
+  formFieldProps: FieldBinding<T | null | undefined, T>;
+  options: SelectOption<T>[];
+  label: string;
+  hint?: string;
+  placeholder?: string;
+  size?: SelectSize;
+  isDisabled?: boolean;
+};
+
+// The form-aware flavor of the single select. A select has no meaningful
+// blur moment — committing an option IS the completed interaction — so the
+// commit marks the field touched alongside the write.
+export const SingleSelectForForm = <T extends string>(
+  props: SingleSelectForFormProps<T>,
+) => {
+  const { formFieldProps, options, label, hint, placeholder, size, isDisabled } =
+    props;
+  const { value, onChange, errorMessage, onBlur } = formFieldProps;
+
+  return (
+    <Field label={label} hint={hint} error={errorMessage}>
+      <SingleSelect
+        options={options}
+        value={value ?? null}
+        onChange={(next) => {
+          onChange(next);
+          onBlur();
+        }}
+        size={size}
+        isDisabled={isDisabled}
+        placeholder={placeholder}
+        ariaLabel={label}
+      />
+    </Field>
+  );
+};

package/src/forms/state/bindings/TextInputForForm.tsx

@@ -0,0 +1,45 @@
+import { Field } from '../../elements/Field';
+import { Input } from '../../elements/Input';
+import type { InputProps } from '../../elements/Input';
+import type { FieldBinding } from '../useFormState/types';
+
+export type TextInputForFormProps = {
+  // The bundle from `getFormFieldPropsAt(path)`. The binding shape declares
+  // what this element can do — display string-ish, emit string — so a
+  // FormFieldProps<V> only fits when V is a text-shaped field
+  // (string / string|null / string|undefined / both). A number- or
+  // boolean-typed path is a compile error right here.
+  formFieldProps: FieldBinding<string | null | undefined, string>;
+  label: string;
+  hint?: string;
+  placeholder?: string;
+  id?: string;
+  type?: InputProps['type'];
+  size?: InputProps['size'];
+  disabled?: boolean;
+};
+
+// The form-aware flavor of the text input: one prop wires value, change,
+// error display, and touched tracking. Composes Field (label/hint/error
+// presentation) around Input; the error-display policy already happened
+// inside `errorMessage` — this component just renders what it's given.
+export const TextInputForForm = (props: TextInputForFormProps) => {
+  const { formFieldProps, label, hint, placeholder, id, type, size, disabled } =
+    props;
+  const { value, onChange, errorMessage, onBlur } = formFieldProps;
+
+  return (
+    <Field label={label} hint={hint} error={errorMessage} htmlFor={id}>
+      <Input
+        id={id}
+        type={type}
+        size={size}
+        value={value ?? ''}
+        onChange={(e) => onChange(e.target.value)}
+        onBlur={onBlur}
+        placeholder={placeholder}
+        disabled={disabled}
+      />
+    </Field>
+  );
+};

package/src/forms/state/path/path.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from 'bun:test';
-import { path, read } from './path';
+import { path, pathsEqual, read, write } from './path';
 
 // These tests pin read()'s runtime semantics to exactly what the type level
 // (ValueAt) promises — see the union-semantics comments in ./types.ts and
@@ -95,6 +95,65 @@ describe('read step failures', () => {
     ).toBeUndefined();
   });
 
+  test('write replaces the value at a deep path without mutating the original', () => {
+    const next = write(filled, ['address', 'city'], 'Paris') as Form;
+
+    expect(next.address?.city).toBe('Paris');
+    expect(filled.address?.city).toBe('London');
+  });
+
+  test('write clones only the spine — untouched siblings keep their identity', () => {
+    const next = write(filled, ['a', 'b', 'c'], 'deeper') as Form;
+
+    // The spine to the written leaf is new at every level …
+    expect(next).not.toBe(filled);
+    expect(next.a).not.toBe(filled.a);
+    expect(next.a?.b).not.toBe(filled.a?.b);
+    // … while every branch off the spine is the same object.
+    expect(next.address).toBe(filled.address);
+    expect(next.entries).toBe(filled.entries);
+  });
+
+  test('write into a list element clones the array and that element only', () => {
+    const twoEntries: Form = {
+      ...filled,
+      entries: [
+        { title: 'first', qty: 1 },
+        { title: 'second', qty: 2 },
+      ],
+    };
+    const next = write(twoEntries, ['entries', 1, 'qty'], 5) as Form;
+
+    expect(next.entries?.[1]).toEqual({ title: 'second', qty: 5 });
+    expect(next.entries).not.toBe(twoEntries.entries);
+    expect(next.entries?.[0]).toBe(twoEntries.entries?.[0]);
+    expect(twoEntries.entries?.[1].qty).toBe(2);
+  });
+
+  test('write with an empty path replaces the root', () => {
+    expect(write(filled, [], { name: 'Eve' })).toEqual({ name: 'Eve' });
+  });
+
+  test('write through a dead ancestor is an identity-preserving no-op', () => {
+    // Mirrors read() returning undefined for a dead step: you cannot edit a
+    // field of an absent section — materialize the section first.
+    expect(write(empty, ['address', 'city'], 'Paris')).toBe(empty);
+    expect(write(empty, ['entries', 0, 'title'], 'x')).toBe(empty);
+  });
+
+  test('write on a shape mismatch or out-of-bounds index is a no-op', () => {
+    // Numeric step on a non-array, key step on a scalar, index past the end
+    // (appending is list manipulation, not a path write).
+    expect(write(filled, ['name', 'length'], 3)).toBe(filled);
+    expect(write(filled, ['entries', 5, 'title'], 'x')).toBe(filled);
+    const list = [1, 2];
+    expect(write(list, ['key'], 'x')).toBe(list);
+  });
+
+  test('writing the value already present is an identity-preserving no-op', () => {
+    expect(write(filled, ['address', 'city'], 'London')).toBe(filled);
+  });
+
   test('rejecting narrow predicate returns undefined; accepting one passes through', () => {
     const isString = (val: unknown): val is string => typeof val === 'string';
     const narrowed = path<Form>()
@@ -110,3 +169,14 @@ describe('read step failures', () => {
     expect(read(filled, rejecting)).toBeUndefined();
   });
 });
+
+describe('pathsEqual', () => {
+  test('structural equality over steps — same steps equal, no prefix matching', () => {
+    expect(pathsEqual(['a', 0, 'b'], ['a', 0, 'b'])).toBe(true);
+    expect(pathsEqual([], [])).toBe(true);
+    expect(pathsEqual(['a'], ['a', 'b'])).toBe(false);
+    expect(pathsEqual(['a', 0], ['a', 1])).toBe(false);
+    // A numeric step never equals its string spelling.
+    expect(pathsEqual(['a', 0], ['a', '0'])).toBe(false);
+  });
+});

package/src/forms/state/path/path.ts

@@ -22,6 +22,15 @@ const makeCursor = <T>(steps: readonly CursorStep[]): Cursor<T> => ({
 
 export const path = <T>(): Cursor<T> => makeCursor<T>([]);
 
+// Structural path equality: same steps, same order, no prefix matching.
+// The one sanctioned way to compare paths — `errorAt` and touched tracking
+// both build on it, so "do these address the same field?" has exactly one
+// definition.
+export const pathsEqual = (
+  a: readonly PathStep[],
+  b: readonly PathStep[],
+): boolean => a.length === b.length && a.every((step, index) => step === b[index]);
+
 // Walk steps against a value. Returns undefined if any step fails — a dead
 // value (null or undefined) encountered mid-path, missing key, out-of-bounds
 // index, or a narrow predicate that rejects the current value. Always
@@ -51,3 +60,44 @@ export const read = (root: unknown, steps: readonly CursorStep[]): unknown => {
 
   return cursor;
 };
+
+// The immutable-update mirror of read(): returns a new root with `value`
+// placed at `steps`, cloning only the containers along the path — untouched
+// siblings keep their identity. Key-only steps (a `Path<T>` value), not
+// CursorStep — there is no meaningful way to write "through" a narrow
+// predicate.
+//
+// Dead-step semantics mirror read() returning undefined: a step that hits a
+// null/undefined container, a shape mismatch (key step on a non-object,
+// numeric step on a non-array), or an out-of-bounds index makes the whole
+// write a no-op that returns `root` by identity — you can't edit a field of
+// an absent section; materialize the section first. (Appending/splicing is
+// list-manipulation territory, deliberately not a path write.) Writing a
+// value that is already there (Object.is) is also an identity-preserving
+// no-op, so state setters can bail out of re-rendering.
+export const write = (
+  root: unknown,
+  steps: readonly PathStep[],
+  value: unknown,
+): unknown => {
+  if (steps.length === 0) return value;
+  const [head, ...rest] = steps;
+
+  if (typeof head === 'number') {
+    if (!Array.isArray(root)) return root;
+    if (head < 0 || head >= root.length) return root;
+    const child = write(root[head], rest, value);
+    if (Object.is(child, root[head])) return root;
+    const clone = root.slice();
+    clone[head] = child;
+    return clone;
+  }
+
+  if (root === null || typeof root !== 'object' || Array.isArray(root)) {
+    return root;
+  }
+  const record = root as Record<string, unknown>;
+  const child = write(record[head], rest, value);
+  if (Object.is(child, record[head])) return root;
+  return { ...record, [head]: child };
+};

package/src/forms/state/useFormState/FormDebugger.test.tsx

@@ -44,7 +44,8 @@ describe('FormDebugger', () => {
 
     expect(screen.getByText('isValid')).toBeTruthy();
     expect(screen.getByText('submitAttempted')).toBeTruthy();
-    expect(screen.getByText("'nickname' cannot be empty")).toBeTruthy();
+    // String leaves render with surrounding quotes (Chrome-inspector style).
+    expect(screen.getByText('"\'nickname\' cannot be empty"')).toBeTruthy();
   });
 
   test('the open window live-updates as the form changes', () => {
@@ -57,8 +58,8 @@ describe('FormDebugger', () => {
 
     // The window survived the form re-render (stable component identity —
     // a remount would have reset it to closed) and shows the new state.
-    expect(screen.getByText('will')).toBeTruthy();
-    expect(screen.queryByText("'nickname' cannot be empty")).toBeNull();
+    expect(screen.getByText('"will"')).toBeTruthy();
+    expect(screen.queryByText('"\'nickname\' cannot be empty"')).toBeNull();
   });
 
   test('clicking the trigger again closes the window', () => {

package/src/forms/state/useFormState/FormDebugger.tsx

@@ -43,6 +43,7 @@ export const createFormDebugger = <T extends FormValuesObject>(
             submitAttempted: snapshot.submitAttempted,
             values: snapshot.values,
             errors: snapshot.errors,
+            touched: snapshot.touched,
           })}
         />
       </div>

package/src/forms/state/useFormState/deriveErrors.test.ts

@@ -74,3 +74,97 @@ describe('deriveFormErrors', () => {
     expect(deriveFormErrors(emptyForm, constraints)).toEqual([]);
   });
 });
+
+// The recursive grammar: nested object specs walk the value tree and
+// address failures with real multi-step paths. (List `each` specs are
+// type-level only until plan phase 3 — the walk throws on one; pinned in
+// walk.test.ts.)
+
+type ProfileForm = {
+  email: string | undefined;
+  homeAddress: {
+    city: string | undefined;
+    postalCode: string | undefined;
+  };
+  mailingAddress: { city: string | undefined } | undefined;
+};
+
+const emptyProfile: ProfileForm = {
+  email: undefined,
+  homeAddress: { city: undefined, postalCode: undefined },
+  mailingAddress: undefined,
+};
+
+describe('deriveFormErrors — nested object specs', () => {
+  test('a failing nested leaf contributes an entry addressed by its full path', () => {
+    const errors = deriveFormErrors(emptyProfile, {
+      homeAddress: { city: notEmpty('city') },
+    });
+    expect(errors).toEqual([
+      { path: ['homeAddress', 'city'], error: "'city' cannot be empty" },
+    ]);
+  });
+
+  test('sibling fields fail independently — one entry per failing node', () => {
+    const errors = deriveFormErrors(emptyProfile, {
+      email: notEmpty('email'),
+      homeAddress: {
+        city: notEmpty('city'),
+        postalCode: notEmpty('postalCode'),
+      },
+    });
+    expect(errors).toEqual([
+      { path: ['email'], error: "'email' cannot be empty" },
+      { path: ['homeAddress', 'city'], error: "'city' cannot be empty" },
+      {
+        path: ['homeAddress', 'postalCode'],
+        error: "'postalCode' cannot be empty",
+      },
+    ]);
+  });
+
+  test('passing nested leaves contribute nothing', () => {
+    const errors = deriveFormErrors(
+      {
+        ...emptyProfile,
+        homeAddress: { city: 'SF', postalCode: '94110' },
+      },
+      {
+        homeAddress: {
+          city: notEmpty('city'),
+          postalCode: [notEmpty('postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+        },
+      },
+    );
+    expect(errors).toEqual([]);
+  });
+
+  test('a nested spec on an absent section is skipped', () => {
+    // Decided with the phase-2 type spike: the honest runtime mirror of the
+    // type level (which refines only the present branch of a nullable
+    // section) is to validate nothing when the section is absent.
+    const errors = deriveFormErrors(emptyProfile, {
+      mailingAddress: { city: notEmpty('city') },
+    });
+    expect(errors).toEqual([]);
+  });
+
+  test('the same nested spec fires once the section is present', () => {
+    const errors = deriveFormErrors(
+      { ...emptyProfile, mailingAddress: { city: undefined } },
+      { mailingAddress: { city: notEmpty('city') } },
+    );
+    expect(errors).toEqual([
+      { path: ['mailingAddress', 'city'], error: "'city' cannot be empty" },
+    ]);
+  });
+
+  test('a required section is a leaf validator on the section field', () => {
+    const errors = deriveFormErrors(emptyProfile, {
+      mailingAddress: notEmpty('mailingAddress'),
+    });
+    expect(errors).toEqual([
+      { path: ['mailingAddress'], error: "'mailingAddress' cannot be empty" },
+    ]);
+  });
+});

package/src/forms/state/useFormState/deriveErrors.ts

@@ -1,7 +1,7 @@
 import type { Path } from '../path/types';
 import type { Validations } from '../validations/types';
 import { validateEntry } from '../validations/walk';
-import type { FlatConstraintEntry } from '../validations/walk';
+import type { ConstraintEntry } from '../validations/walk';
 import type { FormError, FormValuesObject } from './types';
 
 // The pure half of the hook's error model: current values + constraints in,
@@ -19,16 +19,16 @@ export const deriveFormErrors = <T extends FormValuesObject>(
   for (const key of Object.keys(constraints) as (keyof T & string)[]) {
     // No cast: if the grammar grows a constraint form the walk doesn't
     // understand, this assignment is the compile error that says so.
-    const entry: FlatConstraintEntry | undefined = constraints[key];
+    const entry: ConstraintEntry | undefined = constraints[key];
     if (entry == null) continue;
-    const failure = validateEntry(entry, values[key], [key]);
-    if (failure == null) continue;
-    // The walk returns the address it was handed, and `[key]` — a key of
-    // a constraints object type-checked against T — is a valid single-key
-    // Path<T>. TS can't compute Path<T> for an unresolved generic T, so
-    // the correlation needs the same honest widening as the keys cast
-    // above.
-    errors.push({ path: failure.path as Path<T>, error: failure.error });
+    for (const failure of validateEntry(entry, values[key], [key])) {
+      // The walk extends the address it was handed only along keys of specs
+      // type-checked against T's subtree, so every returned path is a valid
+      // Path<T>. TS can't compute Path<T> for an unresolved generic T to
+      // see the correlation, so it needs the same honest widening as the
+      // keys cast above.
+      errors.push({ path: failure.path as Path<T>, error: failure.error });
+    }
   }
 
   return errors;