@structuralists/scaffolding 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structuralists/scaffolding",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "main": "./index.ts",
   "types": "./index.ts",
   "exports": {

package/src/components/Json/JsonTable/JsonLeafNode.tsx

@@ -1,36 +1,39 @@
-import { Text } from '../../Content/Text';
+import styles from './styles.module.css';
 
 export type JsonLeafNodeProps = {
   value: unknown;
-  /** When true, render `null` / `undefined` via Text with the monospace font.
-   *  JsonTable sets this on recursive calls so leaves inside a table inherit
-   *  the same font as the surrounding monospace cells (Text otherwise sets
-   *  its own font-family and would break the inheritance). */
-  isMono?: boolean;
 };
 
 /**
- * Renders one value as a leaf — text only, no JSON tree viewer. Handles
- * the primitives React can't render directly (boolean, null, undefined)
- * and lets strings/numbers flow through as JSX children. Anything else
- * (objects, arrays, Dates, Maps, …) currently falls through to `{value}`
- * — that will throw at render time for non-renderable types and is the
- * placeholder until JsonTable grows specialized renderers for them.
+ * Renders one value as a leaf — text only, no JSON tree viewer. Each
+ * primitive type gets a color class so the value reads like Chrome's
+ * inspector: strings in orange (with quotes), numbers in blue, booleans
+ * in purple, `null`/`undefined` in pink. Anything else (objects, arrays,
+ * Dates, Maps, …) currently falls through to `{value}` — that will throw
+ * at render time for non-renderable types and is the placeholder until
+ * JsonTable grows specialized renderers for them.
  */
 export const JsonLeafNode = (props: JsonLeafNodeProps) => {
-  const { value, isMono } = props;
-  const size = isMono ? 'small' : undefined;
+  const { value } = props;
 
   if (value === null) {
-    return <Text isMuted isMono={isMono} size={size}>null</Text>;
+    return <span className={styles.nil}>null</span>;
   }
 
   if (value === undefined) {
-    return <Text isMuted isMono={isMono} size={size}>undefined</Text>;
+    return <span className={styles.nil}>undefined</span>;
   }
 
   if (typeof value === 'boolean') {
-    return <>{String(value)}</>;
+    return <span className={styles.boolean}>{String(value)}</span>;
+  }
+
+  if (typeof value === 'string') {
+    return <span className={styles.string}>{JSON.stringify(value)}</span>;
+  }
+
+  if (typeof value === 'number') {
+    return <span className={styles.number}>{value}</span>;
   }
 
   return <>{value}</>;

package/src/components/Json/JsonTable/JsonTable.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, within } from 'storybook/test';
 import { JsonTable } from './index';
 
 const meta: Meta<typeof JsonTable> = {
@@ -50,3 +51,89 @@ export const PrimitivesAtTopLevel: Story = {
     </div>
   ),
 };
+
+export const ValueColors: Story = {
+  name: 'Value colors per primitive type',
+  render: () => (
+    <JsonTable
+      title="Primitive value colors"
+      value={{
+        aString: 'hello world',
+        anEmptyString: '',
+        aQuotedString: 'say "hi"',
+        aMultilineString: 'line one\nline two',
+        aNumber: 12345,
+        aFloat: 3.14159,
+        aTrue: true,
+        aFalse: false,
+        aNull: null,
+        anUndefined: undefined,
+      }}
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText('"hello world"')).toBeInTheDocument();
+    await expect(canvas.getByText('"say \\"hi\\""')).toBeInTheDocument();
+    await expect(canvas.getByText('"line one\\nline two"')).toBeInTheDocument();
+  },
+};
+
+const deepSample = {
+  id: 'org_8821',
+  name: 'Northwind Logistics',
+  region: 'us-west-2',
+  active: true,
+  founded: 2014,
+  headquarters: {
+    address: {
+      street: '120 Pier Ave',
+      city: 'Seattle',
+      state: 'WA',
+      zip: '98101',
+      coords: { lat: 47.6062, lng: -122.3321 },
+    },
+    capacity: 240,
+    isLeased: false,
+  },
+  teams: [
+    {
+      id: 'team_platform',
+      name: 'Platform',
+      headcount: 12,
+      lead: { id: 'usr_1042', name: 'Alice Park', email: 'alice@northwind.io' },
+      members: [
+        { id: 'usr_1042', name: 'Alice Park', role: 'lead', onCall: true },
+        { id: 'usr_1109', name: 'Ben Ortiz', role: 'engineer', onCall: false },
+        { id: 'usr_1188', name: 'Chen Wu', role: 'engineer', onCall: false },
+      ],
+      tags: ['core', 'oncall', 'sre'],
+    },
+    {
+      id: 'team_data',
+      name: 'Data',
+      headcount: 7,
+      lead: { id: 'usr_1301', name: 'Dana Reyes', email: 'dana@northwind.io' },
+      members: [
+        { id: 'usr_1301', name: 'Dana Reyes', role: 'lead', onCall: false },
+        { id: 'usr_1422', name: 'Evan Liu', role: 'analyst', onCall: false },
+      ],
+      tags: ['analytics', 'etl'],
+    },
+  ],
+  integrations: [
+    { kind: 'slack', enabled: true, channel: '#alerts', retries: 3 },
+    { kind: 'pagerduty', enabled: true, escalation: { primary: 'usr_1042', secondary: null } },
+    { kind: 'jira', enabled: false, project: null },
+  ],
+  flags: {
+    betaFeatures: ['new-dashboard', 'inline-edit'],
+    rateLimits: { rpm: 600, burst: 1200, throttleAfter: null },
+  },
+  notes: undefined,
+};
+
+export const DeepNested: Story = {
+  name: 'Deeply nested (objects + arrays)',
+  render: () => <JsonTable value={deepSample} title="Organization" />,
+};

package/src/components/Json/JsonTable/index.tsx

@@ -13,8 +13,13 @@ import styles from './styles.module.css';
 export const JsonTable = (props: JsonTableProps) => {
   const { value, title, isNested } = props;
 
-  if (isPlainObject(value)) {
-    const entries = Object.entries(value);
+  const isObject = isPlainObject(value);
+  const isArray = Array.isArray(value);
+
+  if (isObject || isArray) {
+    const entries: [string, unknown][] = isArray
+      ? value.map((item, i) => [String(i), item])
+      : Object.entries(value as Record<string, unknown>);
 
     const headerRow = title ? (
       <QuickTableHeaderRow>
@@ -26,12 +31,14 @@ export const JsonTable = (props: JsonTableProps) => {
       <QuickTable headerRow={headerRow} hasColumnDividers hasOuterBorder={!isNested}>
         {entries.map((entry) => {
           const [key, child] = entry;
-          const childIsObject = isPlainObject(child);
+          const childIsContainer = isPlainObject(child) || Array.isArray(child);
 
           return (
             <QuickTableRow key={key}>
-              <QuickTableCell width={1}>{key}</QuickTableCell>
-              <QuickTableCell hasPadding={!childIsObject}>
+              <QuickTableCell width={1}>
+                <span className={styles.key}>{key}</span>
+              </QuickTableCell>
+              <QuickTableCell hasPadding={!childIsContainer}>
                 <JsonTable value={child} title={key} isNested />
               </QuickTableCell>
             </QuickTableRow>
@@ -43,7 +50,7 @@ export const JsonTable = (props: JsonTableProps) => {
     return isNested ? table : <div className={styles.root}>{table}</div>;
   }
 
-  return <JsonLeafNode value={value} isMono={isNested} />;
+  return <JsonLeafNode value={value} />;
 };
 
 export type { JsonTableProps };

package/src/components/Json/JsonTable/styles.module.css

@@ -5,3 +5,23 @@
 .root thead tr {
   border-bottom-color: var(--ui-border-subtle);
 }
+
+.key {
+  color: var(--ui-json-key);
+}
+
+.string {
+  color: var(--ui-json-string);
+}
+
+.number {
+  color: var(--ui-json-number);
+}
+
+.boolean {
+  color: var(--ui-json-boolean);
+}
+
+.nil {
+  color: var(--ui-json-nil);
+}

package/src/components/Json/JsonTable/types.ts

@@ -12,11 +12,9 @@ export type JsonTableProps = {
    *  labeled table. */
   title?: ReactNode;
   /** @internal Set by JsonTable on every recursive call (i.e. when rendering
-   *  a child entry of a parent table). Two effects: (1) on a nested object,
+   *  a child entry of a parent table). On a nested object or array,
    *  suppresses the outer border so the inner table sits flush inside its
-   *  parent cell — whose padding is also dropped at the parent level; (2) on
-   *  a primitive leaf, signals JsonLeafNode to render `null` / `undefined`
-   *  via Text with the monospace font so they inherit the surrounding font
-   *  set by the JsonTable root. Not intended for external callers. */
+   *  parent cell — whose padding is also dropped at the parent level. Not
+   *  intended for external callers. */
   isNested?: boolean;
 };

package/src/forms/CLAUDE.md

@@ -50,25 +50,67 @@ function composition.
 
 ## What a constraints key may map to
 
+The grammar is recursive. What a key admits is directed by the *field's*
+type, never guessed from the constraint's shape:
+
 ```ts
 type FieldConstraint<F> =
+  // leaf forms — legal for ANY field type, structural fields included
   | FieldValidator<F>            // one validator
   | readonly FieldValidator<F>[] // several, run in order, first error wins
+  // structural forms — only where the field type permits
+  | (F extends FormValuesObject ? Validations<F> : never)  // nested spec
+  | (F extends FormValueList ? ListConstraint<F[number]> : never); // { each: … }
 ```
 
 The array form is the everyday way to stack validators on a field at the
-constraint site:
+constraint site; a nested spec addresses the fields of an object section;
+`each` applies a spec to every element of a list. All compose freely:
 
 ```ts
 constraints: {
   email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+  homeAddress: {
+    city: notEmpty('city'),
+    postalCode: [notEmpty('postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+  },
+  drivers: {
+    each: {
+      name: notEmpty('name'),
+      incidents: { each: { date: notEmpty('date') } },
+    },
+  },
 }
 ```
 
-Semantics are identical to `allOf` (which remains the tool for building
-*reusable, named* composite validators): validators run in array order,
-the first error is the field's error, and later validators don't run once
-one fails. An empty array passes and narrows nothing.
+Array semantics are identical to `allOf` (which remains the tool for
+building *reusable, named* composite validators): validators run in array
+order, the first error is the field's error, and later validators don't run
+once one fails. An empty array passes and narrows nothing.
+
+Grammar doctrine, in force at the type level and in the runtime walk:
+
+- **Disambiguation is by the value model.** An object field that owns a key
+  literally named `each` still takes a nested spec — for an object-typed
+  field only the `Validations<F>` arm is live, for a list-typed field only
+  `ListConstraint`. Both `RefineField` and the walk interrogate the
+  field/value before the constraint's shape.
+- **Leaf forms stay legal on structural fields.** A bare validator on an
+  object field is a whole-section validator (`mailingAddress:
+  notEmpty(…)` is how "required section" is expressed); a validator array
+  on a list field validates the list as a value. Leaf and structural forms
+  are mutually exclusive per key (recorded open decision — a future `self`
+  slot).
+- **A nested spec on an absent (null/undefined) section validates
+  nothing**, at the type level (only the present branch refines;
+  nullability survives around the refined interior) and at runtime (the
+  walk skips — nothing to walk). Same for `each` over a null list.
+- **`F` stays naked in the structural arms.** Nullable sections/lists work
+  purely by distribution; wrapping the checked type in `NonNullable` breaks
+  it and blows the recursion stack (TS2589).
+- **Runtime status of `each`:** type-level only until plan phase 3. An
+  `each` constraint on a present list makes the walk THROW a clear error
+  instead of silently not validating.
 
 ## Aggregation: `perField`
 
@@ -79,7 +121,11 @@ const constraints = perField({
 ```
 
 `perField` is the entry point that produces a `Validations<FormType>`-shaped
-value while preserving the precise types of each individual validator.
+value while preserving the precise types of each individual validator. It
+currently admits only the leaf forms (a validator or validator array per
+key) — extending it to pre-built nested/`each` specs is plan phase 4
+(composition hardening); until then, write structural constraints inline in
+the `useFormState` call.
 
 ### The precision-preserving ceremony, by call-site shape
 
@@ -137,10 +183,11 @@ unreliable in some intersections.
 
 ## `Refine<FormType, typeof constraints>`
 
-Walks the constraints object, reads each field's validator's
-`__excludes` marker, applies `Exclude<FormType[K], __excludes>`. Fields
-without a constraint pass through unchanged. The result is the type
-handed to `onSubmit`.
+Walks the constraints object recursively, mirroring the grammar: leaves
+apply `Exclude<FormType[K], __excludes>` from their validators' markers,
+nested specs recurse into the section, `each` specs refine the element type
+and flow it through `Array<...>`. Fields without a constraint pass through
+unchanged, at every level. The result is the type handed to `onSubmit`.
 
 ```ts
 type FormType   = { a: string | undefined; b: number };
@@ -148,6 +195,18 @@ type C          = typeof constraints;             // a: notEmpty
 type SubmitType = Refine<FormType, C>;            // { a: string; b: number }
 ```
 
+`Refine` opens with an identity gate — `Validations<T> extends V ? T :
+RefineObject<T, V>` — and the gate is load-bearing, not an optimization:
+with constraints omitted the hook's default `V = Validations<T>` would
+distribute `FieldConstraint<F> | undefined` through the walk at every key
+and hand back unions of structurally-identical mapped *copies* of every
+section — assignable to `T` but not identity-equal (mangled hover types;
+the "without constraints, onSubmit receives the unrefined form type" probe
+fails). Any concrete constraints literal is strictly narrower than
+`Validations<T>`, so the gate stays open and the real walk runs. Nested
+occurrences don't need their own gate: a concrete literal's `keyof V` holds
+only the keys actually written, so uncovered fields take `T[K]` verbatim.
+
 Per-field dispatch lives in `RefineField<F, C>`, whose constraint parameter
 is deliberately **naked** so unions of constraint types distribute. Two
 regimes of "multiple markers per field" follow from that, both sound:
@@ -169,10 +228,17 @@ regimes of "multiple markers per field" follow from that, both sound:
   per-branch refinements* (`Exclude<F, A> | Exclude<F, B>`), never a
   narrowing the running branch didn't earn.
 
-Branch order inside `RefineField`: the `Refinement` check must stay ahead of
-the array check and any future structural (object) check — validator
-functions are objects, and a marked validator must not fall into a
-structural arm.
+Both regimes survive recursion verbatim — the same soundness holds for
+union-typed constraints inside nested and `each` specs (probed at depth in
+`useFormState.test-d.ts`).
+
+Branch order inside `RefineField`: `Refinement` first — validator functions
+are objects, and a marked validator must not fall into a structural arm —
+then arrays, then the structural arms, which interrogate the FIELD type
+before the constraint's shape (`F extends FormValueList` is asked before
+looking for an `each` key, so an object field literally named `each`
+refines as a nested spec). A bare marker-less validator on a structural
+field lands in `RefineObject` with an empty `keyof C` — an identity map.
 
 ## Hook surface
 
@@ -189,10 +255,15 @@ useFormState({
 Validation failures surface as a structured list, not a keyed record:
 
 ```ts
-type FormError<T>  = { path: Path<T>; error: string }; // single-key paths on the flat grammar
+type FormError<T>  = { path: Path<T>; error: string }; // one entry per failing constrained node
 type FormErrors<T> = readonly FormError<T>[];          // isValid === (errors.length === 0)
 ```
 
+Paths are as deep as the failing node: a root leaf contributes `['email']`,
+a nested-spec leaf `['homeAddress', 'postalCode']`. Sibling nodes fail
+independently — first-error-wins applies *within* one validator array, not
+across fields.
+
 Read one field's message with the typed accessor, never by hand-assembled
 keys — serialized path strings (`'drivers.0.name'`) are deliberately not
 exposed:
@@ -390,9 +461,11 @@ precision end-to-end. So we wire it up before adding any consumers.
     cheap); `isValid` is its emptiness, derived inline in the hook. Its
     loop delegates per-entry semantics to `state/validations/walk.ts` and
     carries two documented honest widenings: the `Object.keys` cast, and
-    `failure.path as Path<T>` — `[key]` is a valid single-key `Path<T>`,
-    but TS cannot compute `Path<T>` for an unresolved generic `T` to see
-    the correlation. It also hosts the cast-free `FlatConstraintEntry`
+    `failure.path as Path<T>` — the walk extends the `[key]` seed only
+    along keys of specs type-checked against `T`'s subtree, so every
+    returned path is a valid `Path<T>`, but TS cannot compute `Path<T>`
+    for an unresolved generic `T` to see the correlation. It also hosts
+    the cast-free `ConstraintEntry`
     assignment that polices grammar growth (see the `state/validations/` bullet).
   - `errorAt.ts` — the typed error lookup.
   - `useFieldBinding.ts` — field binding: owns the touched list and builds
@@ -417,8 +490,8 @@ precision end-to-end. So we wire it up before adding any consumers.
     bottom-right, portaled to `<body>`) that opens a live `JsonTable` view
     of the form's internal state. Only an *open* debugger window
     subscribes (`useSyncExternalStore`), so an unused Debugger costs
-    ~nothing. `inspectable.ts` converts arrays/Sets to shapes `JsonTable`
-    can render.
+    ~nothing. `inspectable.ts` converts Sets to string leaves `JsonTable`
+    can render (objects and arrays it renders natively).
 - `state/path/` — typed cursor (`Path<T>`, `ValueAt<T,P>`, `Cursor<T>`,
   `read()`), plus `write()` (the immutable-update mirror of `read()` behind
   granular field writes) and `pathsEqual` (the one definition of structural
@@ -427,14 +500,19 @@ precision end-to-end. So we wire it up before adding any consumers.
   Union handling is governed by the "Union policy" section above; the
   policy's type-level guts (`IsDisallowedFormUnion`, `UnionPolicyCheck`,
   `DisallowedFormUnion`) live with the value model in `state/useFormState/types.ts`.
-- `state/validations/` — `perField`, `Validations<T>` / `FieldConstraint<F>`,
-  `Refine<T,V>`, `Refinement<>` infra, plus `walk.ts`, the runtime walk the
-  hook delegates to (`validateEntry`). `Validations<T>` accepts bare
-  `(val) => string | null` functions too — they simply narrow nothing.
-  The walk's entry type (`FlatConstraintEntry`) is how the compiler polices
+- `state/validations/` — `perField`, the recursive grammar
+  (`Validations<T>` / `FieldConstraint<F>` / `ListConstraint<E>`),
+  `Refine<T,V>`, `Refinement<>` infra, plus `walk.ts`, the recursive runtime
+  walk the hook delegates to (`validateEntry` — returns every failure in the
+  entry's subtree, addresses accumulated as `PathStep[]`s). `Validations<T>`
+  accepts bare `(val) => string | null` functions too — they simply narrow
+  nothing. The walk disambiguates a structural spec against the VALUE at
+  the path (array ⇒ `{ each }`, which throws until phase 3; object ⇒
+  nested spec; absent ⇒ skip), never against the constraint's shape.
+  The walk's entry type (`ConstraintEntry`) is how the compiler polices
   the error loop in `state/useFormState/deriveErrors.ts`: `constraints[key]` is
   *assigned* to it, never cast,
-  so a grammar form the walk doesn't understand (a nested spec, an `each`)
+  so a grammar form the walk doesn't understand (a future `self` slot, say)
   is a compile error at the assignment — a cast there would silently accept
   new grammar and misinterpret it at runtime (e.g. call an array as a
   function). Keep it cast-free. The one widening cast inside `validateEntry`

package/src/forms/plan.md

@@ -28,7 +28,8 @@ 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>/`,
@@ -45,6 +46,17 @@ TS wall can't strand finished work behind it.
    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
 
@@ -126,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.
@@ -200,11 +237,39 @@ multi-second check time:
   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,
@@ -244,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.