@structuralists/scaffolding 0.14.0 → 0.15.0

package/package.json

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

package/src/forms/CLAUDE.md

@@ -63,6 +63,14 @@ type FieldConstraint<F> =
   | (F extends FormValueList ? ListConstraint<F[number]> : never); // { each: … }
 ```
 
+Per field type, that comes out as:
+
+| Field type       | Legal constraint forms                                        |
+|------------------|---------------------------------------------------------------|
+| scalar leaf      | validator, validator array                                    |
+| object section   | validator / array (whole-section value), nested `Validations` |
+| list             | validator / array (whole-list value), `{ each: spec }`        |
+
 The array form is the everyday way to stack validators on a field at the
 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:
@@ -126,10 +134,22 @@ const constraints = perField({
 
 `perField` is the entry point that produces a `Validations<FormType>`-shaped
 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.
+admits the full recursive grammar — leaf validators and arrays, nested
+object specs, `each` specs, freely composed. Its own bound is deliberately
+*shape-only* (validators / validator arrays / objects of more of the same):
+perField never sees the form type, so it can only reject obvious garbage;
+the real check — every key a field, every validator input compatible,
+structural forms only where the field type permits — happens at the
+caller's `satisfies Validations<FormType>`. Consequence: wrong-key and
+wrong-shape errors on a perField-built spec anchor at the `satisfies`, not
+at the offending line inside the call.
+
+A pre-built spec is also a legal *nested-spec value*: a
+`perField({...}) satisfies Validations<Section>` object can sit under a
+section key (or an `each` key) of a larger constraints object — building a
+section's spec once and reusing it across sections is the intended
+composition pattern (pinned at ~110-leaf scale in
+`state/useFormState/useFormState.stress.test-d.ts`).
 
 ### The precision-preserving ceremony, by call-site shape
 
@@ -437,6 +457,38 @@ descent into a field.
   real values onto validators except as opaque type tags — anything else
   invites consumers to depend on the runtime shape.
 
+## Probe suites and the recursion budget
+
+The grammar's behavior is pinned by three type-probe tiers (enforced by
+`bun run typecheck`) plus the runtime composition fixture:
+
+- `state/validations/types.test-d.ts` — `Refine`/marker semantics at unit
+  scale: perField precision, union-member soundness, the widening failure
+  modes.
+- `state/useFormState/useFormState.test-d.ts` — the hook boundary at chunky
+  (~30-leaf `InsuranceQuoteForm`) scale: the full grammar inline, boundary
+  regimes (default `V`, literal `initialValues`, `as const satisfies`),
+  union policy, and the negative probes. Authoring gotcha: deep
+  wrong-validator-INPUT rejections (TS2322) anchor at the *outermost*
+  constraint key, so their `@ts-expect-error` sits on the parent/root key's
+  line; wrong-KEY rejections (TS2353) anchor at the leaf.
+- `state/useFormState/useFormState.stress.test-d.ts` — the stress tier
+  (~110-leaf `MegaQuoteForm` with the large spec inline twice, a 12-level
+  nested-spec ladder, a 4-deep `each` ladder, perField pre-built specs at
+  the same scale, deep `Path` bindings). If the recursion budget regresses,
+  tsc slows or fails here first.
+- `state/useFormState/useFormState.composition.test.tsx` — the same deep
+  mixed composition exercised at *runtime* through the real hook: deep error
+  paths, absent-section/null-list skips (and their materialization), deep
+  `getFormFieldPropsAt` writes, whole-value leaf validators on structural
+  fields, submit gating.
+
+Budget baselines live in plan.md's "recursion budget" section. When touching
+the type machinery, run `bunx tsc --noEmit --extendedDiagnostics` and
+compare instantiations against the latest recorded baseline — the failure
+signal is ~10× instantiations or multi-second check time, and regressions
+should be recorded there, not just noticed.
+
 ## Why we're building it this way from the start
 
 The whole carrier-type approach falls apart if it gets retrofitted onto

package/src/forms/plan.md

@@ -1,8 +1,12 @@
 # Plan: composable, recursive `Validations`
 
-Status: **in progress** — order of operations below. The baseline (flat
-`Validations<T>`, one validator per key, shallow `Refine`) is **merged to main**
-(PR #12, squashed; released as 0.5.0).
+Status: **complete** — all working-order items and phases below are done.
+The baseline (flat `Validations<T>`, one validator per key, shallow `Refine`)
+merged as PR #12 (released 0.5.0); the recursive grammar landed over phases
+1–4 (PRs #18, #24, #25, and the composition-hardening close-out). What
+remains in this file is the record: grammar doctrine, decided semantics,
+recorded budgets, and the deliberately-deferred items (per-field meta
+state / stable keys — section 8 — and the open decisions at the end).
 
 ## Order of operations
 
@@ -42,7 +46,7 @@ TS wall can't strand finished work behind it.
    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*
+6. **Type spike, then items 2/3/4** — the recursion risk zone. ✅ *done*
    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.
@@ -58,6 +62,7 @@ TS wall can't strand finished work behind it.
    - **Phase 2 (nested object specs + recursive `Refine`): ✅ done** — see
      "Phases" below.
    - **Phase 3 (list `each` runtime): ✅ done** — see "Phases" below.
+   - **Phase 4 (composition hardening): ✅ done** — see "Phases" below.
 
 ## Goal
 
@@ -254,6 +259,15 @@ multi-second check time:
   instantiations, 58,813 types (+1.8% over the pre-phase-3 HEAD at
   134,330/58,034 — mostly the story's new hook call site and deep
   `Path`/`ValueAt` bindings)
+- post-phase-4 / **final** (composition hardening: the stress tier ported
+  against the real hook — mega form with the spec inline twice, both depth
+  ladders, deep bindings — plus perField at the full grammar with its
+  probes, and the runtime composition fixture): check 0.92–0.99 s, 172,040
+  instantiations, 67,889 types (+25.8% instantiations over post-phase-3 —
+  almost entirely the deliberately-heavy stress fixtures, closely matching
+  the spike's measured stress-tier cost of ~28k; check time stays
+  sub-second, exactly as the spike's headroom predicted). This is the
+  standing baseline for future type-machinery work.
 
 ## Runtime consequences (can't be dodged)
 
@@ -343,9 +357,24 @@ tests, story updates where visible, probe ratchet.
    "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.
+4. **Composition hardening.** ✅ *done* — the closing phase. Deep mixed
+   fixtures: the type spike's stress tier ported against the REAL hook
+   (`useFormState.stress.test-d.ts` — ~110-leaf `MegaQuoteForm` with the
+   large applicant spec inline twice, 12-level nested-spec ladder, 4-deep
+   `each` ladder, deep `Path` bindings), plus a runtime composition fixture
+   through `renderHook` (`useFormState.composition.test.tsx` — deep error
+   paths at two list depths, absent-section/null-list skip *and*
+   materialization, deep `getFormFieldPropsAt` writes, whole-list leaf
+   validators, submit gating end to end). `perField` extended from
+   leaf-forms-only to the full recursive grammar: its bound is a loose
+   recursive shape (validators / arrays / objects of the same — deliberately
+   form-type-agnostic, so the real shape check stays at the caller's
+   `satisfies Validations<T>`), pinned at unit scale in
+   `validations/types.test-d.ts` and at mega scale (one pre-built applicant
+   spec reused across two sections) in the stress file. forms/CLAUDE.md
+   brought fully up to the grammar (constraint-forms-per-field-type table,
+   perField's new reach, probe-suite map). No runtime machinery changed —
+   the deep fixtures flushed out no correctness fixes.
 
 ## 5. Split forms into 'form elements' and 'form state' ✅ done
 

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

@@ -0,0 +1,342 @@
+import { describe, test, expect, mock } from 'bun:test';
+import { act, renderHook } from '@testing-library/react';
+import { useFormState } from './useFormState';
+import { errorAt } from './errorAt';
+import { perField } from '../validations/perField';
+import { matches, min, notEmpty } from '../validators/validators';
+import type { Validations } from '../validations/types';
+
+// The composition-hardening runtime fixture (plan phase 4): a deep mixed
+// form — lists inside objects inside lists, nested specs inside `each`
+// specs, whole-value leaf validators on structural fields, an absent
+// section and a null list — driven through the REAL useFormState at the
+// hook boundary. walk.test.ts pins each construct's semantics React-free;
+// this file pins that they hold composed, end to end, with the constraints
+// pre-built via perField (the phase-4 entry point for pre-built specs).
+
+type UsAddress = {
+  line1: string | undefined;
+  city: string | undefined;
+  postalCode: string | undefined;
+};
+
+type Incident = {
+  date: string | undefined;
+  claimAmountUsd: number | null;
+};
+
+type Driver = {
+  name: string | undefined;
+  incidents: Incident[];
+};
+
+type Vehicle = { vin: string | undefined };
+
+type Applicant = {
+  email: string | undefined;
+  homeAddress: UsAddress;
+  mailingAddress: UsAddress | undefined;
+  drivers: Driver[];
+  vehicles: Vehicle[];
+};
+
+type QuoteForm = {
+  primary: Applicant;
+  secondary: Applicant | undefined;
+  household: {
+    members: Array<{ name: string | undefined }>;
+  };
+  quotes: Array<{
+    coverageType: string | undefined;
+    riders: Array<{ code: string | undefined; amountUsd: number | null }>;
+  }>;
+  pastPolicies: Array<{ insurer: string | undefined }> | null;
+  // An object field literally named `each` — the value model, not the
+  // constraint's shape, directs interpretation.
+  audit: { each: string | undefined };
+  agreedToTerms: boolean | undefined;
+};
+
+// One applicant spec, built once via perField and reused for both applicant
+// sections — nested specs, each-in-each, arrays at depth, and a whole-list
+// leaf validator on a structural field (leaf and structural forms are
+// mutually exclusive per key: vehicles validates as a value, drivers per
+// element).
+const applicantSpec = perField({
+  email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+  homeAddress: {
+    city: notEmpty('city'),
+    postalCode: [notEmpty('postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+  },
+  mailingAddress: {
+    city: notEmpty('mailing city'),
+  },
+  drivers: {
+    each: {
+      name: notEmpty('name'),
+      incidents: {
+        each: {
+          date: notEmpty('date'),
+          claimAmountUsd: min('claimAmountUsd', 0),
+        },
+      },
+    },
+  },
+  vehicles: [(val: Vehicle[]) => (val.length > 0 ? null : 'at least one vehicle')],
+}) satisfies Validations<Applicant>;
+
+const constraints = {
+  primary: applicantSpec,
+  secondary: applicantSpec,
+  household: {
+    members: { each: { name: notEmpty('member name') } },
+  },
+  quotes: {
+    each: {
+      coverageType: notEmpty('coverageType'),
+      riders: {
+        each: { code: notEmpty('code'), amountUsd: min('amountUsd', 0) },
+      },
+    },
+  },
+  pastPolicies: {
+    each: { insurer: notEmpty('insurer') },
+  },
+  audit: { each: notEmpty('audit each') },
+  agreedToTerms: notEmpty('agreedToTerms'),
+} as const satisfies Validations<QuoteForm>;
+
+// Mostly-valid deep values with deliberate failures: an each-in-each leaf
+// and its sibling at depth 5, a member name, a rider code at list-in-
+// object-in-list depth, and the `audit.each` disambiguation field. The
+// secondary section is absent and pastPolicies is null — both fully
+// spec'd, both skipped.
+const makeValues = (): QuoteForm => ({
+  primary: {
+    email: 'ada@lovelace.dev',
+    homeAddress: { line1: '1 Main St', city: 'London', postalCode: '12345' },
+    mailingAddress: undefined,
+    drivers: [
+      { name: 'Ada', incidents: [] },
+      { name: 'Grace', incidents: [{ date: undefined, claimAmountUsd: -50 }] },
+    ],
+    vehicles: [{ vin: 'V1' }],
+  },
+  secondary: undefined,
+  household: { members: [{ name: undefined }, { name: 'Linus' }] },
+  quotes: [
+    {
+      coverageType: 'auto',
+      riders: [
+        { code: 'R1', amountUsd: 10 },
+        { code: undefined, amountUsd: null },
+      ],
+    },
+  ],
+  pastPolicies: null,
+  audit: { each: undefined },
+  agreedToTerms: true,
+});
+
+const setup = (onSubmit?: (values: QuoteForm) => void) =>
+  renderHook(() =>
+    useFormState({ initialValues: makeValues(), constraints, onSubmit }),
+  );
+
+describe('useFormState — deep mixed composition at the hook boundary', () => {
+  test('errors carry full structural paths across every grammar construct', () => {
+    const { result } = setup();
+    // The exact list: constraint-key order at each level, elements in list
+    // order, failing nodes only. Absent secondary and null pastPolicies
+    // contribute nothing despite full specs; the whole-list vehicles
+    // validator and every passing leaf contribute nothing.
+    expect(result.current.errors).toEqual([
+      {
+        path: ['primary', 'drivers', 1, 'incidents', 0, 'date'],
+        error: "'date' cannot be empty",
+      },
+      {
+        path: ['primary', 'drivers', 1, 'incidents', 0, 'claimAmountUsd'],
+        error: "'claimAmountUsd' must be at least 0",
+      },
+      {
+        path: ['household', 'members', 0, 'name'],
+        error: "'member name' cannot be empty",
+      },
+      {
+        path: ['quotes', 0, 'riders', 1, 'code'],
+        error: "'code' cannot be empty",
+      },
+      {
+        path: ['audit', 'each'],
+        error: "'audit each' cannot be empty",
+      },
+    ]);
+    expect(result.current.isValid).toBe(false);
+  });
+
+  test('errorAt resolves deep numeric paths and stays empty on skipped subtrees', () => {
+    const { result } = setup();
+    expect(
+      errorAt(result.current.errors, ['primary', 'drivers', 1, 'incidents', 0, 'date']),
+    ).toBe("'date' cannot be empty");
+    expect(errorAt(result.current.errors, ['quotes', 0, 'riders', 1, 'code'])).toBe(
+      "'code' cannot be empty",
+    );
+    // Sibling elements that passed have no entry at their own index.
+    expect(
+      errorAt(result.current.errors, ['quotes', 0, 'riders', 0, 'code']),
+    ).toBeUndefined();
+    // The absent section's constrained leaves have no entries.
+    expect(errorAt(result.current.errors, ['secondary', 'email'])).toBeUndefined();
+  });
+
+  test('a deep fix through getFormFieldPropsAt clears exactly that entry', () => {
+    const { result } = setup();
+
+    act(() => {
+      result.current
+        .getFormFieldPropsAt(['primary', 'drivers', 1, 'incidents', 0, 'date'])
+        .onChange('2026-01-01');
+    });
+
+    expect(
+      errorAt(result.current.errors, ['primary', 'drivers', 1, 'incidents', 0, 'date']),
+    ).toBeUndefined();
+    // The failing sibling leaf in the same element is untouched …
+    expect(
+      errorAt(result.current.errors, [
+        'primary',
+        'drivers',
+        1,
+        'incidents',
+        0,
+        'claimAmountUsd',
+      ]),
+    ).toBe("'claimAmountUsd' must be at least 0");
+    // … and the write only cloned the spine: the other driver keeps identity.
+    expect(result.current.values.primary.drivers[0]).toEqual({
+      name: 'Ada',
+      incidents: [],
+    });
+  });
+
+  test('a whole-list leaf validator on a structural field runs against the list value', () => {
+    const { result } = setup();
+    expect(errorAt(result.current.errors, ['primary', 'vehicles'])).toBeUndefined();
+
+    act(() => {
+      result.current.getFormFieldPropsAt(['primary', 'vehicles']).onChange([]);
+    });
+
+    expect(errorAt(result.current.errors, ['primary', 'vehicles'])).toBe(
+      'at least one vehicle',
+    );
+  });
+
+  test('materializing an absent section brings its whole spec to life', () => {
+    const { result } = setup();
+
+    act(() => {
+      result.current.onValueChanges((prev) => ({
+        ...prev,
+        secondary: {
+          email: undefined,
+          homeAddress: { line1: undefined, city: undefined, postalCode: undefined },
+          mailingAddress: undefined,
+          drivers: [{ name: undefined, incidents: [] }],
+          vehicles: [],
+        },
+      }));
+    });
+
+    expect(errorAt(result.current.errors, ['secondary', 'email'])).toBe(
+      "'email' cannot be empty",
+    );
+    expect(errorAt(result.current.errors, ['secondary', 'homeAddress', 'city'])).toBe(
+      "'city' cannot be empty",
+    );
+    expect(
+      errorAt(result.current.errors, ['secondary', 'drivers', 0, 'name']),
+    ).toBe("'name' cannot be empty");
+    expect(errorAt(result.current.errors, ['secondary', 'vehicles'])).toBe(
+      'at least one vehicle',
+    );
+    // The still-absent nested section inside the materialized one stays
+    // skipped.
+    expect(
+      errorAt(result.current.errors, ['secondary', 'mailingAddress', 'city']),
+    ).toBeUndefined();
+  });
+
+  test('a null list wakes up the same way', () => {
+    const { result } = setup();
+    expect(errorAt(result.current.errors, ['pastPolicies', 0, 'insurer'])).toBeUndefined();
+
+    act(() => {
+      result.current.onValueChanges((prev) => ({
+        ...prev,
+        pastPolicies: [{ insurer: 'Acme' }, { insurer: undefined }],
+      }));
+    });
+
+    expect(errorAt(result.current.errors, ['pastPolicies', 0, 'insurer'])).toBeUndefined();
+    expect(errorAt(result.current.errors, ['pastPolicies', 1, 'insurer'])).toBe(
+      "'insurer' cannot be empty",
+    );
+  });
+
+  test('submit is gated on the deep composition and passes the current values through', () => {
+    let submitted: QuoteForm | undefined;
+    const onSubmit = mock((values: QuoteForm) => {
+      submitted = values;
+    });
+    const { result } = setup(onSubmit);
+
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(result.current.submitAttempted).toBe(true);
+
+    // Fix every failing node, one grammar construct at a time.
+    act(() => {
+      result.current
+        .getFormFieldPropsAt(['primary', 'drivers', 1, 'incidents', 0, 'date'])
+        .onChange('2026-01-01');
+    });
+    act(() => {
+      result.current
+        .getFormFieldPropsAt(['primary', 'drivers', 1, 'incidents', 0, 'claimAmountUsd'])
+        .onChange(500);
+    });
+    act(() => {
+      result.current
+        .getFormFieldPropsAt(['household', 'members', 0, 'name'])
+        .onChange('Margaret');
+    });
+    act(() => {
+      result.current
+        .getFormFieldPropsAt(['quotes', 0, 'riders', 1, 'code'])
+        .onChange('R2');
+    });
+    act(() => {
+      result.current.getFormFieldPropsAt(['audit', 'each']).onChange('reviewed');
+    });
+
+    expect(result.current.errors).toEqual([]);
+    expect(result.current.isValid).toBe(true);
+
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(submitted?.primary.drivers[1].incidents[0]).toEqual({
+      date: '2026-01-01',
+      claimAmountUsd: 500,
+    });
+    expect(submitted?.quotes[0].riders[1].code).toBe('R2');
+    expect(submitted?.secondary).toBeUndefined();
+    expect(submitted?.pastPolicies).toBeNull();
+  });
+});

package/src/forms/state/useFormState/useFormState.stress.test-d.ts

@@ -0,0 +1,451 @@
+import { describe, it, expectTypeOf } from 'vitest';
+import { useFormState } from './useFormState';
+import { perField } from '../validations/perField';
+import { matches, min, minLength, notEmpty } from '../validators/validators';
+import type { FormFieldProps } from './types';
+import type { Refine, Validations } from '../validations/types';
+
+// ---------------------------------------------------------------------------
+// The stress tier (plan phase 4, composition hardening) — the phase-2 type
+// spike's stress fixtures, pinned against the REAL hook. Where
+// useFormState.test-d.ts probes the grammar at chunky (~30-leaf) scale, this
+// file pushes past it to hold the measured headroom: a ~110-leaf form at 5–6
+// levels with the large applicant spec written inline twice, the same spec
+// pre-built ONCE via perField and reused for both applicant sections (the
+// pre-built entry point at realistic scale), a 12-level nested-object spec
+// ladder, a 4-deep list-in-list `each` ladder, and deep Path bindings on the
+// mega form. If the recursion budget regresses, tsc slows or fails here
+// first — watch the instantiation count in the plan's recursion-budget
+// section, not just success.
+// ---------------------------------------------------------------------------
+
+type UsAddress = {
+  line1: string | undefined;
+  line2: string | undefined;
+  city: string | undefined;
+  state: string | undefined;
+  postalCode: string | undefined;
+};
+
+type Incident = {
+  date: string | undefined;
+  kind: string | undefined;
+  claimAmountUsd: number | null;
+};
+
+type Driver = {
+  name: string | undefined;
+  licenseNumber: string | undefined;
+  licenseState: string | undefined;
+  incidents: Incident[];
+};
+
+type Vehicle = {
+  vin: string | undefined;
+  year: number | undefined;
+  make: string | undefined;
+  model: string | undefined;
+  primaryDriverName: string | undefined;
+  garagingAddress: UsAddress;
+};
+
+type Applicant = {
+  firstName: string | undefined;
+  lastName: string | undefined;
+  email: string | undefined;
+  phone: string | undefined;
+  dateOfBirth: string | undefined;
+  employer: string | null;
+  jobTitle: string | null;
+  yearsEmployed: number | null;
+  annualIncomeUsd: number | null;
+  homeAddress: UsAddress;
+  mailingAddress: UsAddress | undefined;
+  drivers: Driver[];
+  vehicles: Vehicle[];
+};
+
+type MegaQuoteForm = {
+  primary: Applicant;
+  secondary: Applicant | undefined;
+  household: {
+    address: UsAddress;
+    members: Array<{
+      name: string | undefined;
+      relation: string | undefined;
+      dateOfBirth: string | undefined;
+    }>;
+  };
+  quotes: Array<{
+    coverageType: string | undefined;
+    deductibleUsd: number | undefined;
+    startDate: string | undefined;
+    riders: Array<{
+      code: string | undefined;
+      amountUsd: number | null;
+    }>;
+  }>;
+  referralSource: string | null;
+  notes: string | undefined;
+  agreedToTerms: boolean | undefined;
+  paperlessBilling: boolean;
+};
+
+describe('useFormState stress: ~110-leaf form, large inline spec written twice', () => {
+  it('composes and refines with the applicant spec duplicated inline', () => {
+    useFormState({
+      initialValues: {} as MegaQuoteForm,
+      constraints: {
+        primary: {
+          firstName: notEmpty('firstName'),
+          lastName: [notEmpty('lastName')],
+          email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+          phone: matches('phone', /^[\d\s()+-]+$/, 'a phone number'),
+          dateOfBirth: notEmpty('dateOfBirth'),
+          yearsEmployed: min('yearsEmployed', 0),
+          annualIncomeUsd: min('annualIncomeUsd', 0),
+          homeAddress: {
+            line1: notEmpty('line1'),
+            city: notEmpty('city'),
+            postalCode: [notEmpty('postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+          },
+          mailingAddress: {
+            city: notEmpty('mailing city'),
+          },
+          drivers: {
+            each: {
+              name: notEmpty('name'),
+              licenseNumber: [notEmpty('licenseNumber'), minLength('licenseNumber', 5)],
+              incidents: {
+                each: {
+                  date: notEmpty('date'),
+                  claimAmountUsd: min('claimAmountUsd', 0),
+                },
+              },
+            },
+          },
+          vehicles: {
+            each: {
+              vin: [notEmpty('vin')],
+              year: min('year', 1900),
+              garagingAddress: {
+                line1: notEmpty('garaging line1'),
+                postalCode: [notEmpty('garaging postalCode')],
+              },
+            },
+          },
+        },
+        // The same large spec again, on the nullable secondary applicant —
+        // simulates a real page where big sections each get full specs.
+        secondary: {
+          firstName: notEmpty('firstName'),
+          lastName: [notEmpty('lastName')],
+          email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+          phone: matches('phone', /^[\d\s()+-]+$/, 'a phone number'),
+          dateOfBirth: notEmpty('dateOfBirth'),
+          yearsEmployed: min('yearsEmployed', 0),
+          annualIncomeUsd: min('annualIncomeUsd', 0),
+          homeAddress: {
+            line1: notEmpty('line1'),
+            city: notEmpty('city'),
+            postalCode: [notEmpty('postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+          },
+          mailingAddress: {
+            city: notEmpty('mailing city'),
+          },
+          drivers: {
+            each: {
+              name: notEmpty('name'),
+              licenseNumber: [notEmpty('licenseNumber'), minLength('licenseNumber', 5)],
+              incidents: {
+                each: {
+                  date: notEmpty('date'),
+                  claimAmountUsd: min('claimAmountUsd', 0),
+                },
+              },
+            },
+          },
+          vehicles: {
+            each: {
+              vin: [notEmpty('vin')],
+              year: min('year', 1900),
+              garagingAddress: {
+                line1: notEmpty('garaging line1'),
+                postalCode: [notEmpty('garaging postalCode')],
+              },
+            },
+          },
+        },
+        household: {
+          address: {
+            city: notEmpty('household city'),
+          },
+          members: {
+            each: {
+              name: notEmpty('member name'),
+              dateOfBirth: notEmpty('member dateOfBirth'),
+            },
+          },
+        },
+        quotes: {
+          each: {
+            coverageType: notEmpty('coverageType'),
+            deductibleUsd: min('deductibleUsd', 0),
+            startDate: notEmpty('startDate'),
+            riders: {
+              each: {
+                code: notEmpty('code'),
+                amountUsd: min('amountUsd', 0),
+              },
+            },
+          },
+        },
+        referralSource: notEmpty('referralSource'),
+        agreedToTerms: notEmpty('agreedToTerms'),
+      },
+      onSubmit: (values) => {
+        // Depth 5–6 refinements on both applicant sections.
+        expectTypeOf(values.primary.email).toEqualTypeOf<string>();
+        expectTypeOf(values.primary.homeAddress.postalCode).toEqualTypeOf<string>();
+        expectTypeOf(values.primary.drivers[0].incidents[0].date).toEqualTypeOf<string>();
+        expectTypeOf(values.primary.vehicles[0].garagingAddress.line1).toEqualTypeOf<string>();
+        expectTypeOf(values.primary.drivers[0].licenseState).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.secondary?.homeAddress.city).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.secondary?.drivers[0].incidents[0].date).toEqualTypeOf<
+          string | undefined
+        >();
+        expectTypeOf(values.household.members[0].name).toEqualTypeOf<string>();
+        expectTypeOf(values.quotes[0].riders[0].code).toEqualTypeOf<string>();
+        expectTypeOf(values.quotes[0].riders[0].amountUsd).toEqualTypeOf<number | null>();
+        expectTypeOf(values.agreedToTerms).toEqualTypeOf<boolean>();
+        expectTypeOf(values.paperlessBilling).toEqualTypeOf<boolean>();
+      },
+    });
+  });
+
+  it('Path machinery holds at mega scale: deep bindings on the hook result', () => {
+    const form = useFormState({ initialValues: {} as MegaQuoteForm });
+
+    expectTypeOf(
+      form.getFormFieldPropsAt(['primary', 'drivers', 0, 'incidents', 0, 'date']),
+    ).toEqualTypeOf<FormFieldProps<string | undefined>>();
+    expectTypeOf(
+      form.getFormFieldPropsAt(['secondary', 'vehicles', 0, 'garagingAddress', 'postalCode']),
+    ).toEqualTypeOf<FormFieldProps<string | undefined>>();
+    expectTypeOf(
+      form.getFormFieldPropsAt(['quotes', 0, 'riders', 0, 'amountUsd']),
+    ).toEqualTypeOf<FormFieldProps<number | null>>();
+    expectTypeOf(
+      form.getFormFieldPropsAt(['household', 'members', 0, 'relation']),
+    ).toEqualTypeOf<FormFieldProps<string | undefined>>();
+
+    // @ts-expect-error 'drvers' is not a field of the primary applicant
+    form.getFormFieldPropsAt(['primary', 'drvers', 0, 'name']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// perField at realistic scale (plan phase 4): the pre-built entry point on
+// the full recursive grammar — one applicant spec built once, reused for
+// both applicant sections, mixing each-in-each, nested-in-each, and a
+// whole-list leaf validator on a structural field. Before this phase,
+// perField was only ever exercised on a 3-key flat form.
+// ---------------------------------------------------------------------------
+
+describe('useFormState stress: perField pre-built specs at mega scale', () => {
+  it('preserves markers through a perField applicant spec reused across sections', () => {
+    const applicantSpec = perField({
+      firstName: notEmpty('firstName'),
+      email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+      yearsEmployed: min('yearsEmployed', 0),
+      homeAddress: {
+        city: notEmpty('city'),
+        postalCode: [notEmpty('postalCode'), matches('postalCode', /^\d{5}$/, '5 digits')],
+      },
+      mailingAddress: {
+        city: notEmpty('mailing city'),
+      },
+      drivers: {
+        each: {
+          name: notEmpty('name'),
+          licenseNumber: [notEmpty('licenseNumber'), minLength('licenseNumber', 5)],
+          incidents: {
+            each: {
+              date: notEmpty('date'),
+              claimAmountUsd: min('claimAmountUsd', 0),
+            },
+          },
+        },
+      },
+      // Whole-list leaf validator on a structural field: leaf and structural
+      // forms are mutually exclusive per key, so vehicles takes the
+      // list-as-a-value form while drivers takes `each`.
+      vehicles: [
+        (val: Vehicle[]) => (val.length > 0 ? null : 'at least one vehicle'),
+      ],
+    }) satisfies Validations<Applicant>;
+
+    const constraints = {
+      primary: applicantSpec,
+      secondary: applicantSpec,
+      household: {
+        members: {
+          each: { name: notEmpty('member name') },
+        },
+      },
+      agreedToTerms: notEmpty('agreedToTerms'),
+    } as const satisfies Validations<MegaQuoteForm>;
+
+    // Direct Refine application on the composed pre-built object.
+    type Submit = Refine<MegaQuoteForm, typeof constraints>;
+    expectTypeOf<Submit['primary']['email']>().toEqualTypeOf<string>();
+    expectTypeOf<Submit['primary']['homeAddress']['postalCode']>().toEqualTypeOf<string>();
+    expectTypeOf<
+      Submit['primary']['drivers'][number]['incidents'][number]['date']
+    >().toEqualTypeOf<string>();
+    expectTypeOf<Submit['primary']['vehicles']>().toEqualTypeOf<Vehicle[]>();
+    expectTypeOf<Submit['secondary']>().toEqualTypeOf<
+      Refine<Applicant, typeof applicantSpec> | undefined
+    >();
+    expectTypeOf<Submit['household']['members'][number]['name']>().toEqualTypeOf<string>();
+    expectTypeOf<Submit['quotes']>().toEqualTypeOf<MegaQuoteForm['quotes']>();
+
+    // And through the hook boundary.
+    useFormState({
+      initialValues: {} as MegaQuoteForm,
+      constraints,
+      onSubmit: (values) => {
+        expectTypeOf(values.primary.drivers[0].incidents[0].date).toEqualTypeOf<string>();
+        expectTypeOf(values.secondary?.homeAddress.city).toEqualTypeOf<string | undefined>();
+        expectTypeOf(values.agreedToTerms).toEqualTypeOf<boolean>();
+        expectTypeOf(values.paperlessBilling).toEqualTypeOf<boolean>();
+      },
+    });
+  });
+});
+
+// --- Object-depth ladder: specs 12 levels deep --------------------------------
+
+type L12 = { leaf: string | undefined; tag: string | undefined };
+type L11 = { next: L12; tag: string | undefined };
+type L10 = { next: L11; tag: string | undefined };
+type L9 = { next: L10; tag: string | undefined };
+type L8 = { next: L9; tag: string | undefined };
+type L7 = { next: L8; tag: string | undefined };
+type L6 = { next: L7; tag: string | undefined };
+type L5 = { next: L6; tag: string | undefined };
+type L4 = { next: L5; tag: string | undefined };
+type L3 = { next: L4; tag: string | undefined };
+type L2 = { next: L3; tag: string | undefined };
+type L1 = { next: L2; tag: string | undefined };
+type DeepObjectForm = { root: L1 };
+
+describe('useFormState stress: 12-level nested-object spec ladder', () => {
+  it('refines a leaf 13 levels down, with a validator at every level', () => {
+    useFormState({
+      initialValues: {} as DeepObjectForm,
+      constraints: {
+        root: {
+          tag: notEmpty('t1'),
+          next: {
+            tag: notEmpty('t2'),
+            next: {
+              tag: notEmpty('t3'),
+              next: {
+                tag: notEmpty('t4'),
+                next: {
+                  tag: notEmpty('t5'),
+                  next: {
+                    tag: notEmpty('t6'),
+                    next: {
+                      tag: notEmpty('t7'),
+                      next: {
+                        tag: notEmpty('t8'),
+                        next: {
+                          tag: notEmpty('t9'),
+                          next: {
+                            tag: notEmpty('t10'),
+                            next: {
+                              tag: notEmpty('t11'),
+                              next: {
+                                tag: notEmpty('t12'),
+                                leaf: [notEmpty('leaf'), minLength('leaf', 2)],
+                              },
+                            },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      onSubmit: (values) => {
+        expectTypeOf(
+          values.root.next.next.next.next.next.next.next.next.next.next.next.leaf,
+        ).toEqualTypeOf<string>();
+        expectTypeOf(
+          values.root.next.next.next.next.next.next.next.next.next.next.next.tag,
+        ).toEqualTypeOf<string>();
+        expectTypeOf(values.root.tag).toEqualTypeOf<string>();
+      },
+    });
+  });
+});
+
+// --- List-depth ladder: `each` 4 levels deep ----------------------------------
+
+type DeepListForm = {
+  xs: Array<{
+    label: string | undefined;
+    ys: Array<{
+      label: string | undefined;
+      zs: Array<{
+        label: string | undefined;
+        ws: Array<{
+          v: string | undefined;
+          n: number | null;
+        }>;
+      }>;
+    }>;
+  }>;
+};
+
+describe('useFormState stress: 4-deep list-in-list each ladder', () => {
+  it('refines through four nested each specs', () => {
+    useFormState({
+      initialValues: {} as DeepListForm,
+      constraints: {
+        xs: {
+          each: {
+            label: notEmpty('x label'),
+            ys: {
+              each: {
+                label: notEmpty('y label'),
+                zs: {
+                  each: {
+                    label: notEmpty('z label'),
+                    ws: {
+                      each: {
+                        v: notEmpty('v'),
+                        n: min('n', 0),
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      onSubmit: (values) => {
+        expectTypeOf(values.xs[0].ys[0].zs[0].ws[0].v).toEqualTypeOf<string>();
+        expectTypeOf(values.xs[0].ys[0].zs[0].ws[0].n).toEqualTypeOf<number | null>();
+        expectTypeOf(values.xs[0].ys[0].zs[0].label).toEqualTypeOf<string>();
+      },
+    });
+  });
+});

package/src/forms/state/validations/perField.ts

@@ -1,14 +1,25 @@
+// The loose, form-type-agnostic shape of one constraint: a validator, a
+// validator array, or an object of more of the same — which covers both
+// nested specs and `{ each: … }` (an `each` value is itself a spec object).
+// `(val: never) => …` admits any validator input contravariantly. This bound
+// only rejects obvious garbage (strings, numbers, null values); the real
+// shape check — every key a field, every validator's input compatible,
+// structural forms only where the field type permits — happens at the
+// caller's `satisfies Validations<FormType>`, which is where the form type
+// first enters the picture.
+type LooseFieldConstraint =
+  | ((val: never) => string | null)
+  | readonly ((val: never) => string | null)[]
+  | { readonly [key: string]: LooseFieldConstraint };
+
 // Aggregation entry point for building a `Validations<T>`-shaped constraints
-// object. Runtime identity; the value is in the type: the `const` type
-// parameter freezes each validator's precise type (including `Refinement`
-// markers) instead of letting function types widen. Callers still apply
-// `as const satisfies Validations<FormType>` to shape-check against their
-// form type without losing that precision — see src/forms/CLAUDE.md.
-export const perField = <
-  const V extends Record<
-    string,
-    ((val: never) => string | null) | readonly ((val: never) => string | null)[]
-  >,
->(
+// object — the full recursive grammar (leaf validators and arrays, nested
+// object specs, list `each` specs, freely composed). Runtime identity; the
+// value is in the type: the `const` type parameter freezes each validator's
+// precise type (including `Refinement` markers) instead of letting function
+// types widen. Callers still apply `satisfies Validations<FormType>` to
+// shape-check against their form type without losing that precision — see
+// src/forms/CLAUDE.md.
+export const perField = <const V extends Record<string, LooseFieldConstraint>>(
   validations: V,
 ): V => validations;

package/src/forms/state/validations/types.test-d.ts

@@ -205,6 +205,114 @@ describe('Refine<T, V> — union-typed members inside arrays', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// perField at the recursive grammar (plan phase 4): the pre-built-spec entry
+// point admits the full grammar — nested object specs, list `each` specs,
+// arrays at every level — and preserves refinement markers through all of it.
+// perField's own bound is shape-only (validators / arrays / objects of the
+// same); the form-type shape check happens at `satisfies Validations<T>`.
+// ---------------------------------------------------------------------------
+
+type NestedFormType = {
+  email: string | undefined;
+  homeAddress: {
+    city: string | undefined;
+    postalCode: string | undefined;
+  };
+  mailingAddress: { city: string | undefined } | undefined;
+  drivers: Array<{
+    name: string | undefined;
+    incidents: Array<{ date: string | undefined }>;
+  }>;
+};
+
+describe('perField — recursive grammar', () => {
+  it('preserves markers through nested specs and each-in-each specs', () => {
+    const constraints = perField({
+      email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+      homeAddress: {
+        city: notEmpty('city'),
+        postalCode: [notEmpty('postalCode'), minLength('postalCode', 5)],
+      },
+      mailingAddress: {
+        city: notEmpty('mailing city'),
+      },
+      drivers: {
+        each: {
+          name: notEmpty('name'),
+          incidents: { each: { date: notEmpty('date') } },
+        },
+      },
+    }) satisfies Validations<NestedFormType>;
+
+    type Result = Refine<NestedFormType, typeof constraints>;
+    expectTypeOf<Result['email']>().toEqualTypeOf<string>();
+    expectTypeOf<Result['homeAddress']['city']>().toEqualTypeOf<string>();
+    expectTypeOf<Result['homeAddress']['postalCode']>().toEqualTypeOf<string>();
+    // Nullability survives around the refined interior of a nullable section.
+    expectTypeOf<Result['mailingAddress']>().toEqualTypeOf<
+      { city: string } | undefined
+    >();
+    expectTypeOf<Result['drivers'][number]['name']>().toEqualTypeOf<string>();
+    expectTypeOf<
+      Result['drivers'][number]['incidents'][number]['date']
+    >().toEqualTypeOf<string>();
+  });
+
+  it('a pre-built section spec composes as a nested-spec value', () => {
+    // Building one section's spec via perField and placing it under the
+    // section key in a larger constraints object — the reuse shape phase 4
+    // exists to keep working.
+    const addressSpec = perField({
+      city: notEmpty('city'),
+    }) satisfies Validations<NestedFormType['homeAddress']>;
+
+    const constraints = {
+      homeAddress: addressSpec,
+      mailingAddress: addressSpec,
+    } as const satisfies Validations<NestedFormType>;
+
+    type Result = Refine<NestedFormType, typeof constraints>;
+    expectTypeOf<Result['homeAddress']['city']>().toEqualTypeOf<string>();
+    expectTypeOf<Result['homeAddress']['postalCode']>().toEqualTypeOf<
+      string | undefined
+    >();
+    expectTypeOf<Result['mailingAddress']>().toEqualTypeOf<
+      { city: string } | undefined
+    >();
+  });
+
+  it('rejects non-constraint values at the perField call itself', () => {
+    perField({
+      // @ts-expect-error a string is not a validator, array, or spec
+      email: 'not a validator',
+    });
+    perField({
+      // @ts-expect-error garbage stays rejected at depth (the TS2322
+      // anchors at the parent key, same as deep validator-input mismatches)
+      homeAddress: {
+        city: 42,
+      },
+    });
+  });
+
+  it('form-type shape errors surface at the satisfies check', () => {
+    // perField is form-type-agnostic, so a wrong key passes its bound and
+    // is caught where the form type first appears.
+    const wrongKey = perField({
+      homeAddress: { cityy: notEmpty('cityy') },
+    });
+    // @ts-expect-error 'cityy' is not a field of homeAddress
+    wrongKey satisfies Validations<NestedFormType>;
+
+    const eachOnObject = perField({
+      homeAddress: { each: { city: notEmpty('city') } },
+    });
+    // @ts-expect-error an `each` spec is not legal on an object field
+    eachOnObject satisfies Validations<NestedFormType>;
+  });
+});
+
 describe('Refine<T, V> — union-typed single constraints (conditional pick)', () => {
   it('narrows a conditionally-picked validator to the union of branch results', () => {
     // Only ONE branch runs at runtime, so the sound result is the UNION of