@structuralists/scaffolding 0.8.0 → 0.10.0

package/package.json

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

package/src/forms/CLAUDE.md

@@ -11,8 +11,9 @@ A form has three types in flight:
 
 1. **`FormType`** — what fields exist and what they could hold. Often loose
    (`{ a: string | undefined }`).
-2. **`Validations<FormType>`** — a per-field map of validator functions plus,
-   at the type level, refinement markers carried by each validator.
+2. **`Validations<FormType>`** — a per-field map of validators — a single
+   function or an ordered array of them — plus, at the type level, refinement
+   markers carried by each validator.
 3. **`SubmitType = Refine<FormType, typeof validations>`** — `FormType` with
    each field narrowed by the refinement that field's validator carries.
 
@@ -31,6 +32,28 @@ A validator is just:
 No library, no fluent builder, no schema DSL. Composition is via plain
 function composition.
 
+## What a constraints key may map to
+
+```ts
+type FieldConstraint<F> =
+  | FieldValidator<F>            // one validator
+  | readonly FieldValidator<F>[] // several, run in order, first error wins
+```
+
+The array form is the everyday way to stack validators on a field at the
+constraint site:
+
+```ts
+constraints: {
+  email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+}
+```
+
+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.
+
 ## Aggregation: `perField`
 
 ```ts
@@ -68,7 +91,7 @@ the widening failure mode all three patterns exist to avoid.
 
 ## Standard-library validators carry refinements
 
-Built-in validators (e.g. `notEmpty`, `oneOf`, `matches`) expose a phantom
+Built-in validators (e.g. `notEmpty`, `minLength`, `matches`) expose a phantom
 property whose type encodes the refinement they enforce. Sketch:
 
 ```ts
@@ -109,6 +132,32 @@ type C          = typeof constraints;             // a: notEmpty
 type SubmitType = Refine<FormType, C>;            // { a: string; b: number }
 ```
 
+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:
+
+- **Validator array** — every member runs, so the field earns the *union of
+  the members' contributions* in one `Exclude`:
+  `Exclude<F, MemberExcludes<C>>`. Each member's contribution is itself
+  per-member sound (`SoundExcludedOf`): a member that is a *union* of
+  validators (`cond ? v1 : v2` inside the array) runs only one branch, so it
+  contributes only the **intersection** of its branches' excludes — what
+  every branch guarantees. A bare (marker-less) branch guarantees nothing,
+  so a union containing one contributes `never`. The naive
+  `ExcludedOf<C[number]>` would instead distribute over such a member and
+  over-claim both branches — never apply `ExcludedOf` to array members
+  directly. `allOf` computes its composite marker with the same
+  `MemberExcludes`, so both composition forms share these semantics.
+- **Union-typed single constraint** (`cond ? notEmpty(…) : minLength(…)`) —
+  only one branch runs at runtime, so distribution yields the *union of the
+  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.
+
 ## Hook surface
 
 ```ts
@@ -119,6 +168,30 @@ useFormState({
 });
 ```
 
+## The error model
+
+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 FormErrors<T> = readonly FormError<T>[];          // isValid === (errors.length === 0)
+```
+
+Read one field's message with the typed accessor, never by hand-assembled
+keys — serialized path strings (`'drivers.0.name'`) are deliberately not
+exposed:
+
+```ts
+errorAt(errors, ['email']); // string | undefined
+```
+
+`errorAt` (useFormState/errorAt.ts) matches by exact structural step
+equality (no prefix matching); with first-error-wins validation there is at
+most one entry per path, and if collect-all ever lands the first entry stays
+the one shown. The path-addressed model is what the recursive grammar
+(errors just carry longer paths) and `getFormFieldPropsAt`'s `errorMessage`
+build on.
+
 ## Union policy — what form state may hold
 
 The path machinery is load-bearing (structured `{path, error}[]` errors and
@@ -222,10 +295,16 @@ precision end-to-end. So we wire it up before adding any consumers.
 - `useFormState/` — the hook + the value-model types (`FormValueSimple`,
   `FormValuesObject`, `FormValueList`). Hook surface: `{ values,
   onValueChanges, errors, isValid, submitAttempted, submit, Debugger }`;
-  `errors` is live-derived from current values each render (validators are
-  pure and cheap), `submitAttempted` lets UIs gate error display, and
-  `submit()` performs the one honest cast to `Refine<T, V>` — earned because
-  the validators just passed at runtime. `Debugger` is a per-instance
+  `errors` is the structured `FormErrors<T>` list (see "The error model"),
+  live-derived from current values each render (validators are pure and
+  cheap) with `isValid` its emptiness; `errorAt.ts` holds the typed lookup;
+  `submitAttempted` lets UIs gate error display; and `submit()` performs
+  the one honest *refinement* cast to `Refine<T, V>` — earned because the
+  validators just passed at runtime. The hook's error loop carries one
+  further documented widening (`failure.path as Path<T>`, same species as
+  its `Object.keys` cast): `[key]` is a valid single-key `Path<T>`, but TS
+  cannot compute `Path<T>` for an unresolved generic `T` to see the
+  correlation. `Debugger` is a per-instance
   dev-time overlay (fixed trigger, bottom-right, portaled to `<body>`) that
   opens a live `JsonTable` view of the form's internal state. Plumbing: the
   hook publishes a `FormDebugSnapshot` into a tiny `snapshotStore` after
@@ -240,9 +319,18 @@ 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 `useFormState/types.ts`.
-- `validations/` — `perField`, `Validations<T>`, `Refine<T,V>`,
-  `Refinement<>` infra. `Validations<T>` accepts bare
+- `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
+  the hook's error loop: `constraints[key]` is *assigned* to it, never cast,
+  so a grammar form the walk doesn't understand (a nested spec, an `each`)
+  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`
+  mirrors `allOf`'s part-call: honest contravariant widening of a single,
+  already-normalized validator.
 - `validators/` — the standard-library validators (`notEmpty`, `minLength`,
   `matches`, `min`) plus `allOf`, which composes validators on one field and
   carries the union of the parts' refinements. `allOf` derives its input type

package/src/forms/plan.md

@@ -15,12 +15,22 @@ TS wall can't strand finished work behind it.
    after it (watching nested state and structured errors live). ✅ *done*
    (PR #14, released 0.6.0)
 2. **Item 1 — validator arrays per key.** `ExcludedOf<C[number]>` already
-   proven inside `allOf`. ← *current*
+   proven inside `allOf`. ✅ *done* — grammar (`FieldConstraint`), distributive
+   `RefineField`, and the walk rewrite (`validations/walk.ts`, cast-free entry
+   dispatch, `PathStep[]`-addressed errors) landed together; probe ratchet
+   held (see the baseline note under the recursion budget).
 3. **Error-model swap** to `{path, error}[]` on the *flat* baseline (paths
    are single-key paths). Doesn't depend on nested constraints; hard
    prerequisite for item 6; makes phases 2–3 runtime-plumbing-free.
+   ✅ *done* — `FormError<T>`/`FormErrors<T>` (`{ path: Path<T>; error }[]`
+   in useFormState/types.ts), `isValid` derived from emptiness, and the
+   interim consumer accessor is a standalone `errorAt(errors, path)`
+   (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).
 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.
+   item 6 so the wrappers land in their final home once. ← *current*
 5. **Item 6 — field binding** (`getFormFieldPropsAt` + wrappers). Needs the
    error model and the split; `Path`/`ValueAt` already validated.
 6. **Type spike, then items 2/3/4** — the recursion risk zone. Throwaway
@@ -112,10 +122,12 @@ useFormState({
 
 ```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 validations/types.ts.
 
 type RefineField<F, C> =
   C extends Refinement<infer X>        ? Exclude<F, X>                 // single marked validator
-  : C extends readonly unknown[]       ? Exclude<F, ExcludedOf<C[number]>> // validator array: union of excludes
+  : 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
@@ -158,12 +170,29 @@ happened. Discipline for every phase below:
 - If a phase hits the wall, stop and record the ceiling in the learning map
   before reaching for tricks (interface-based lazy recursion, depth caps).
 
+Recorded baselines (`tsc --noEmit --extendedDiagnostics`), so drift is a diff
+rather than a memory. The failure signal is ~10× instantiations or
+multi-second check time:
+
+- pre-item-1 (0.8.0): check 0.78 s, 102,415 instantiations, 46,089 types
+- post-item-1 (arrays): check 0.77 s, 106,787 instantiations, 47,318 types
+  (+4.3% instantiations — the array grammar and its probes are nearly free)
+- post-item-1 soundness fix (per-member-sound `MemberExcludes` in the array
+  arm and `allOf`, plus its probes): check 0.77 s, 107,612 instantiations,
+  48,507 types (+0.8%)
+- pre-step-3 HEAD (union policy + validator arrays merged, PRs #17/#18):
+  check 0.78 s, 108,978 instantiations, 48,678 types
+- 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)
+
 ## Runtime consequences (can't be dodged)
 
 - **The validator walk becomes a tree walk.** Recursion mirrors `read()` in
   `path/path.ts`; share the traversal or keep them deliberately parallel.
 - **`FormErrors` can no longer be `Partial<Record<keyof T, string>>`.**
-  Decided: errors become a plain list of structured entries,
+  ✅ *Landed with working-order step 3* (on the flat baseline, single-key
+  paths). Decided: errors become a plain list of structured entries,
 
   ```ts
   type FormError<T> = { path: Path<T>; error: string };
@@ -178,8 +207,11 @@ happened. Discipline for every phase below:
   as an *internal* implementation detail — the concatenation scheme must be
   fully encapsulated and opaque to everything outside it.
 - **`errors` display wiring** in stories/components goes through a typed
-  accessor (e.g. `errorAt(errors, path)` / a cursor-based lookup), never
-  through hand-assembled keys.
+  accessor, never through hand-assembled keys. ✅ *Decided and landed with
+  step 3*: a standalone `errorAt(errors, path)` (useFormState/errorAt.ts) —
+  structural step-equality lookup, first entry wins. Chosen over a
+  cursor-based lookup as the smallest surface that keeps stories readable
+  on the flat grammar; item 6's `errorMessage` reuses it internally.
 
 ## Phases
 
@@ -190,10 +222,17 @@ tests, story updates where visible, probe ratchet.
 1. **Validator arrays per key.** Pure sugar over `allOf` at the constraint
    site (`allOf` remains for building reusable composite validators).
    First-error-wins per field, same as `allOf`. Excludes union via
-   `ExcludedOf<C[number]>`.
+   `MemberExcludes<C>` — per-member sound: a union-typed member
+   (`cond ? v1 : v2` inside the array) earns only the *intersection* of its
+   branches' excludes, since only one branch runs; `allOf` shares the same
+   marker computation. ✅ *done* — plus a byproduct: `RefineField`
+   distributes over a naked constraint parameter, which made union-typed
+   *single* constraints (`cond ? v1 : v2`) sound too (union of per-branch
+   refinements, pinned in `validations/types.test-d.ts`).
 2. **Nested object specs + recursive `Refine`.** The risk phase — the probe
-   ratchet matters most here. Errors become `{path, error}[]` in this phase
-   (nested fields need addresses).
+   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<...>`.

package/src/forms/useFormState/errorAt.test.ts

@@ -0,0 +1,54 @@
+import { describe, test, expect } from 'bun:test';
+import { errorAt } from './errorAt';
+import type { FormErrors } from './types';
+
+// The flat grammar only produces single-key paths today, but errorAt's
+// equality must already be exact over multi-step and numeric-step paths —
+// the recursive grammar (plan phases 2–3) reuses it unchanged.
+type Form = {
+  email: string | undefined;
+  address: { city: string | undefined };
+  tags: Array<{ label: string | undefined }>;
+};
+
+const errors: FormErrors<Form> = [
+  { path: ['email'], error: "'email' cannot be empty" },
+  { path: ['address', 'city'], error: "'city' cannot be empty" },
+  { path: ['tags', 0, 'label'], error: "'label' cannot be empty" },
+];
+
+describe('errorAt', () => {
+  test('finds a single-key path', () => {
+    expect(errorAt(errors, ['email'])).toBe("'email' cannot be empty");
+  });
+
+  test('finds a nested path by exact step equality', () => {
+    expect(errorAt(errors, ['address', 'city'])).toBe(
+      "'city' cannot be empty",
+    );
+  });
+
+  test('numeric steps participate in equality', () => {
+    expect(errorAt(errors, ['tags', 0, 'label'])).toBe(
+      "'label' cannot be empty",
+    );
+    expect(errorAt(errors, ['tags', 1, 'label'])).toBeUndefined();
+  });
+
+  test('a prefix of an error path is not a match', () => {
+    expect(errorAt(errors, ['address'])).toBeUndefined();
+    expect(errorAt(errors, ['tags'])).toBeUndefined();
+  });
+
+  test('returns undefined when the list has no entry for the path', () => {
+    expect(errorAt([], ['email'])).toBeUndefined();
+  });
+
+  test('first entry wins when a path has several errors', () => {
+    const duplicated: FormErrors<Form> = [
+      { path: ['email'], error: 'first' },
+      { path: ['email'], error: 'second' },
+    ];
+    expect(errorAt(duplicated, ['email'])).toBe('first');
+  });
+});

package/src/forms/useFormState/errorAt.ts

@@ -0,0 +1,27 @@
+import type { Path, PathStep } from '../path/types';
+import type { FormErrors, FormValuesObject } from './types';
+
+// Typed lookup into the structured `{ path, error }[]` error list — the
+// sanctioned way to read one field's error. Path equality is structural:
+// same steps, same order, no prefix matching. With first-error-wins
+// validation there is at most one entry per path today; should collect-all
+// ever land, the first entry stays the one shown.
+export const errorAt = <T extends FormValuesObject>(
+  errors: FormErrors<T>,
+  path: Path<T>,
+): string | undefined => {
+  // Path<T> is always a PathStep tuple; the conditional type just can't
+  // prove it for an unresolved T. Same honest widening as `Cursor.at`.
+  const steps = path as readonly PathStep[];
+
+  const match = errors.find((candidate) => {
+    const candidateSteps = candidate.path as readonly PathStep[];
+
+    return (
+      candidateSteps.length === steps.length &&
+      candidateSteps.every((step, index) => step === steps[index])
+    );
+  });
+
+  return match?.error;
+};

package/src/forms/useFormState/types.ts

@@ -1,6 +1,7 @@
-// Type-only import; FormDebugger.tsx imports value types from this file in
-// turn, but the cycle never exists at runtime.
+// Type-only imports; FormDebugger.tsx and path/types.ts import value types
+// from this file in turn, but the cycles never exist at runtime.
 import type { FormDebuggerComponent } from './FormDebugger';
+import type { Path } from '../path/types';
 
 export type FormValueSimple = string | number | bigint | boolean | string[] | Set<string> | undefined | null;
 
@@ -76,9 +77,18 @@ export type UnionPolicyCheck<T> = HasDisallowedUnion<T> extends true
     }
   : unknown;
 
-export type FormErrors<T extends FormValuesObject> = Partial<
-  Record<keyof T, string>
->;
+// Structured error model: one entry per failing constrained node, addressed
+// by a typed path (single-key paths on the flat grammar; deeper addresses
+// arrive with the recursive grammar). Deliberately a plain list — at form
+// scale a linear scan is fine, and serialized string keys ('drivers.0.name')
+// are never exposed. Read a field's error with `errorAt` (./errorAt.ts),
+// never by hand-assembled keys.
+export type FormError<T extends FormValuesObject> = {
+  readonly path: Path<T>;
+  readonly error: string;
+};
+
+export type FormErrors<T extends FormValuesObject> = readonly FormError<T>[];
 
 // What the hook publishes to its Debugger after every commit. Snapshots are
 // replaced whole (never mutated) so `useSyncExternalStore` consumers can

package/src/forms/useFormState/useFormState.stories.tsx

@@ -2,7 +2,9 @@ import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { expect, userEvent, within } from 'storybook/test';
 import { useFormState } from './useFormState';
-import { allOf, matches, minLength, notEmpty } from '../validators/validators';
+import { errorAt } from './errorAt';
+import type { FormErrors } from './types';
+import { matches, minLength, notEmpty } from '../validators/validators';
 import { Field } from '../../components/Forms/Field';
 import { Input } from '../../components/Forms/Input';
 import { Button } from '../../components/Forms/Button';
@@ -53,14 +55,20 @@ const SignupDemo = () => {
         inviteCode: undefined,
       } as SignupFormValues,
       constraints: {
-        email: allOf(notEmpty('email'), matches('email', /@/, 'a valid email')),
-        displayName: allOf(notEmpty('displayName'), minLength('displayName', 3)),
+        // Multiple validators per key: an array, run in order, first error
+        // wins. (`allOf` still exists for building reusable composites.)
+        email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+        displayName: [notEmpty('displayName'), minLength('displayName', 3)],
         role: notEmpty('role'),
       },
       onSubmit: (vals) => setSubmitted(vals),
     });
 
-  const shownErrors = submitAttempted ? errors : {};
+  // errors is a structured `{ path, error }[]` list; a field's message is
+  // read with the typed `errorAt` accessor, never a hand-assembled key.
+  const shownErrors: FormErrors<SignupFormValues> = submitAttempted
+    ? errors
+    : [];
 
   return (
     <form
@@ -70,7 +78,11 @@ const SignupDemo = () => {
         submit();
       }}
     >
-      <Field label="Email" error={shownErrors.email} htmlFor="signup-email">
+      <Field
+        label="Email"
+        error={errorAt(shownErrors, ['email'])}
+        htmlFor="signup-email"
+      >
         <Input
           id="signup-email"
           type="email"
@@ -86,7 +98,7 @@ const SignupDemo = () => {
       <Field
         label="Display name"
         hint="At least 3 characters"
-        error={shownErrors.displayName}
+        error={errorAt(shownErrors, ['displayName'])}
         htmlFor="signup-display-name"
       >
         <Input
@@ -99,7 +111,7 @@ const SignupDemo = () => {
         />
       </Field>
 
-      <Field label="Role" error={shownErrors.role}>
+      <Field label="Role" error={errorAt(shownErrors, ['role'])}>
         <SingleSelect
           options={ROLE_OPTIONS}
           value={values.role}
@@ -124,7 +136,7 @@ const SignupDemo = () => {
         <Button type="submit" variant="primary">
           Sign up
         </Button>
-        {submitAttempted && Object.keys(errors).length > 0 && (
+        {submitAttempted && errors.length > 0 && (
           <span style={{ color: 'var(--ui-danger, #c33)', fontSize: 13 }}>
             Fix the highlighted fields
           </span>
@@ -154,8 +166,9 @@ export const SignupForm: Story = {
       <SignupDemo />
     </div>
   ),
-  // Walks the headline flow: errors gated on submit, allOf first-error
-  // progression, live clearing, and the narrowed payload reaching onSubmit.
+  // Walks the headline flow: errors gated on submit, validator-array
+  // first-error progression, live clearing, and the narrowed payload
+  // reaching onSubmit.
   play: async ({ canvasElement }) => {
     const canvas = within(canvasElement);
     const body = within(canvasElement.ownerDocument.body);
@@ -173,7 +186,7 @@ export const SignupForm: Story = {
     ).toBeInTheDocument();
     await expect(canvas.getByText("'role' cannot be empty")).toBeInTheDocument();
 
-    // allOf progression: notEmpty now passes, matches takes over.
+    // Array progression: notEmpty now passes, matches takes over.
     await userEvent.type(canvas.getByLabelText(/^Email/), 'not-an-email');
     await expect(
       canvas.getByText("'email' must be a valid email"),
@@ -197,7 +210,7 @@ const LiveValidityDemo = () => {
   const { values, onValueChanges, errors, isValid } = useFormState({
     initialValues: { nickname: undefined } as { nickname: string | undefined },
     constraints: {
-      nickname: allOf(notEmpty('nickname'), minLength('nickname', 3)),
+      nickname: [notEmpty('nickname'), minLength('nickname', 3)],
     },
   });
 
@@ -206,7 +219,7 @@ const LiveValidityDemo = () => {
       <Field
         label="Nickname"
         hint="Errors here are live — not gated on a submit attempt"
-        error={errors.nickname}
+        error={errorAt(errors, ['nickname'])}
         htmlFor="live-nickname"
       >
         <Input
@@ -266,12 +279,14 @@ const DebuggerDemo = () => {
         tags: [],
       } as DebuggerDemoValues,
       constraints: {
-        email: allOf(notEmpty('email'), matches('email', /@/, 'a valid email')),
+        email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
         nickname: notEmpty('nickname'),
       },
     });
 
-  const shownErrors = submitAttempted ? errors : {};
+  const shownErrors: FormErrors<DebuggerDemoValues> = submitAttempted
+    ? errors
+    : [];
 
   return (
     <form
@@ -281,7 +296,11 @@ const DebuggerDemo = () => {
         submit();
       }}
     >
-      <Field label="Email" error={shownErrors.email} htmlFor="debug-email">
+      <Field
+        label="Email"
+        error={errorAt(shownErrors, ['email'])}
+        htmlFor="debug-email"
+      >
         <Input
           id="debug-email"
           type="email"
@@ -294,7 +313,11 @@ const DebuggerDemo = () => {
         />
       </Field>
 
-      <Field label="Nickname" error={shownErrors.nickname} htmlFor="debug-nickname">
+      <Field
+        label="Nickname"
+        error={errorAt(shownErrors, ['nickname'])}
+        htmlFor="debug-nickname"
+      >
         <Input
           id="debug-nickname"
           value={values.nickname ?? ''}

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

@@ -1,6 +1,8 @@
 import { describe, it, expectTypeOf } from 'vitest';
 import { useFormState } from './useFormState';
+import { errorAt } from './errorAt';
 import { allOf, matches, min, minLength, notEmpty } from '../validators/validators';
+import type { FormErrors } from './types';
 import type { Refine, Validations } from '../validations/types';
 import type { Path, ValueAt } from '../path/types';
 
@@ -34,6 +36,18 @@ describe('useFormState onSubmit narrowing — inline constraints', () => {
     });
   });
 
+  it('narrows via an inline validator array with no call-site ceremony', () => {
+    useFormState({
+      initialValues: { a: undefined as string | undefined, b: 0 },
+      constraints: {
+        a: [notEmpty('a'), minLength('a', 3)],
+      },
+      onSubmit: (values) => {
+        expectTypeOf(values).toEqualTypeOf<{ a: string; b: number }>();
+      },
+    });
+  });
+
   it('bare inline validator functions narrow nothing', () => {
     useFormState({
       initialValues: { a: undefined as string | undefined },
@@ -303,22 +317,42 @@ describe('useFormState narrowing at realistic scale', () => {
       initialValues: {} as InsuranceQuoteForm,
       constraints: {
         firstName: notEmpty('firstName'),
-        lastName: notEmpty('lastName'),
-        email: allOf(notEmpty('email'), matches('email', /@/, 'a valid email')),
+        // Single-element array: refines exactly like the bare validator.
+        lastName: [notEmpty('lastName')],
+        // Validator array inline — the everyday composition site. Mixed
+        // markers: notEmpty refines, matches contributes never.
+        email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
         phone: matches('phone', /^[\d\s()+-]+$/, 'a phone number'),
-        dateOfBirth: notEmpty('dateOfBirth'),
+        // allOf remains the tool for reusable composites; keep it probed at
+        // scale alongside the array sugar.
+        dateOfBirth: allOf(
+          notEmpty('dateOfBirth'),
+          matches('dateOfBirth', /^\d{4}-\d{2}-\d{2}$/, 'an ISO date'),
+        ),
         yearsEmployed: min('yearsEmployed', 0),
         annualIncomeUsd: min('annualIncomeUsd', 0),
-        coverageType: notEmpty('coverageType'),
+        // A bare arrow inside an array: contextually typed by the field, and
+        // it must not dilute the marked member's refinement.
+        coverageType: [
+          notEmpty('coverageType'),
+          (val) => {
+            expectTypeOf(val).toEqualTypeOf<string | undefined>();
+            return null;
+          },
+        ],
         startDate: notEmpty('startDate'),
         referralSource: notEmpty('referralSource'),
-        notes: minLength('notes', 10),
+        // Array of non-refining validators only.
+        notes: [minLength('notes', 10), matches('notes', /\S/, 'not blank')],
         agreedToTerms: notEmpty('agreedToTerms'),
       },
       onSubmit: (values) => {
         // Refined: notEmpty strips null/undefined/'' from the union.
         expectTypeOf(values.firstName).toEqualTypeOf<string>();
+        expectTypeOf(values.lastName).toEqualTypeOf<string>();
         expectTypeOf(values.email).toEqualTypeOf<string>();
+        expectTypeOf(values.dateOfBirth).toEqualTypeOf<string>();
+        expectTypeOf(values.coverageType).toEqualTypeOf<string>();
         expectTypeOf(values.referralSource).toEqualTypeOf<string>();
         expectTypeOf(values.agreedToTerms).toEqualTypeOf<boolean>();
         // Constrained but non-refining validators leave the type alone.
@@ -337,6 +371,19 @@ describe('useFormState narrowing at realistic scale', () => {
     });
   });
 
+  it('rejects a wrong-input validator inside an array, at scale', () => {
+    useFormState({
+      initialValues: {} as InsuranceQuoteForm,
+      constraints: {
+        yearsEmployed: [
+          min('yearsEmployed', 0),
+          // @ts-expect-error minLength validates strings; the field is number | null
+          minLength('yearsEmployed', 3),
+        ],
+      },
+    });
+  });
+
   it('Path<T> still expands on the realistic form type', () => {
     // Path is the most recursion-prone type in forms/ — its union grows with
     // every key at every depth. Probe it with deep representative paths
@@ -355,6 +402,29 @@ describe('useFormState narrowing at realistic scale', () => {
     >().toEqualTypeOf<boolean | undefined>();
   });
 
+  it('errors are the structured {path, error}[] list, looked up via errorAt', () => {
+    const form = useFormState({ initialValues: {} as InsuranceQuoteForm });
+    expectTypeOf(form.errors).toEqualTypeOf<FormErrors<InsuranceQuoteForm>>();
+
+    // FormError paths are Path<T>-typed, so entries at any depth are legal
+    // values already — the recursive grammar reuses this model unchanged.
+    const errors: FormErrors<InsuranceQuoteForm> = [
+      { path: ['email'], error: 'x' },
+      { path: ['homeAddress', 'city'], error: 'x' },
+      { path: ['drivers', 0, 'incidents', 1, 'date'], error: 'x' },
+    ];
+
+    expectTypeOf(errorAt(errors, ['email'])).toEqualTypeOf<
+      string | undefined
+    >();
+    errorAt(errors, ['vehicles', 2, 'garagingAddress', 'postalCode']);
+
+    // @ts-expect-error 'emial' is not a field of the form
+    errorAt(errors, ['emial']);
+    // @ts-expect-error no paths exist below a scalar leaf
+    errorAt(errors, ['email', 'domain']);
+  });
+
   it('paths through optional sections and nullable lists resolve, at scale', () => {
     // The latent hole this pins: Path admitted these paths all along, but
     // ValueAt resolved them to `never` because `keyof (Obj | undefined)` is

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

@@ -1,6 +1,7 @@
 import { describe, test, expect, mock } from 'bun:test';
 import { act, renderHook } from '@testing-library/react';
 import { useFormState } from './useFormState';
+import { errorAt } from './errorAt';
 import { allOf, matches, notEmpty } from '../validators/validators';
 
 type SignupForm = {
@@ -39,13 +40,21 @@ describe('useFormState', () => {
         constraints: { email: notEmpty('email') },
       }),
     );
-    expect(result.current.errors.email).toBe("'email' cannot be empty");
+    // The full structured shape: one entry per failing field, addressed by
+    // a typed path (single-key on the flat grammar).
+    expect(result.current.errors).toEqual([
+      { path: ['email'], error: "'email' cannot be empty" },
+    ]);
+    expect(errorAt(result.current.errors, ['email'])).toBe(
+      "'email' cannot be empty",
+    );
     expect(result.current.isValid).toBe(false);
 
     act(() => {
       result.current.onValueChanges((prev) => ({ ...prev, email: 'a@b.co' }));
     });
-    expect(result.current.errors.email).toBeUndefined();
+    expect(errorAt(result.current.errors, ['email'])).toBeUndefined();
+    expect(result.current.errors).toEqual([]);
     expect(result.current.isValid).toBe(true);
   });
 
@@ -56,13 +65,13 @@ describe('useFormState', () => {
         constraints: { email: notEmpty('email') },
       }),
     );
-    expect(result.current.errors.nickname).toBeUndefined();
+    expect(errorAt(result.current.errors, ['nickname'])).toBeUndefined();
   });
 
   test('a form without constraints is always valid', () => {
     const { result } = renderHook(() => useFormState({ initialValues }));
     expect(result.current.isValid).toBe(true);
-    expect(result.current.errors).toEqual({});
+    expect(result.current.errors).toEqual([]);
   });
 
   test('submit on an invalid form marks the attempt and skips onSubmit', () => {
@@ -108,6 +117,59 @@ describe('useFormState', () => {
     });
   });
 
+  test('a validator array runs in order with first-error-wins per field', () => {
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: {
+          email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+        },
+      }),
+    );
+    // Both validators would fail on undefined-adjacent input paths; the
+    // FIRST one's message surfaces.
+    expect(errorAt(result.current.errors, ['email'])).toBe(
+      "'email' cannot be empty",
+    );
+
+    act(() => {
+      result.current.onValueChanges((prev) => ({ ...prev, email: 'nope' }));
+    });
+    expect(errorAt(result.current.errors, ['email'])).toBe(
+      "'email' must be a valid email",
+    );
+
+    act(() => {
+      result.current.onValueChanges((prev) => ({ ...prev, email: 'a@b.co' }));
+    });
+    expect(errorAt(result.current.errors, ['email'])).toBeUndefined();
+    expect(result.current.isValid).toBe(true);
+  });
+
+  test('a valid form with array constraints submits the current values', () => {
+    const onSubmit = mock(() => {});
+    const { result } = renderHook(() =>
+      useFormState({
+        initialValues,
+        constraints: {
+          email: [notEmpty('email'), matches('email', /@/, 'a valid email')],
+        },
+        onSubmit,
+      }),
+    );
+
+    act(() => {
+      result.current.onValueChanges({ email: 'a@b.co', nickname: undefined });
+    });
+    act(() => {
+      result.current.submit();
+    });
+    expect(onSubmit).toHaveBeenCalledWith({
+      email: 'a@b.co',
+      nickname: undefined,
+    });
+  });
+
   test('a boolean field can be set, validated, and submitted', () => {
     const onSubmit = mock(() => {});
     const { result } = renderHook(() =>
@@ -123,7 +185,9 @@ describe('useFormState', () => {
       }),
     );
     expect(result.current.values.agreed).toBe(false);
-    expect(result.current.errors.agreed).toBe('you must agree to the terms');
+    expect(errorAt(result.current.errors, ['agreed'])).toBe(
+      'you must agree to the terms',
+    );
     expect(result.current.isValid).toBe(false);
 
     act(() => {
@@ -134,7 +198,7 @@ describe('useFormState', () => {
     act(() => {
       result.current.onValueChanges((prev) => ({ ...prev, agreed: true }));
     });
-    expect(result.current.errors.agreed).toBeUndefined();
+    expect(errorAt(result.current.errors, ['agreed'])).toBeUndefined();
     expect(result.current.isValid).toBe(true);
 
     act(() => {
@@ -144,6 +208,17 @@ describe('useFormState', () => {
     expect(onSubmit).toHaveBeenCalledWith({ email: 'a@b.co', agreed: true });
   });
 
+  test('a null constraint entry (possible from untyped JS) is skipped', () => {
+    const constraints = {
+      email: null,
+    } as unknown as { email: (val: string | undefined) => string | null };
+    const { result } = renderHook(() =>
+      useFormState({ initialValues, constraints }),
+    );
+    expect(result.current.errors).toEqual([]);
+    expect(result.current.isValid).toBe(true);
+  });
+
   test('a failed submit followed by a fix allows the next submit through', () => {
     const onSubmit = mock(() => {});
     const { result } = renderHook(() =>

package/src/forms/useFormState/useFormState.ts

@@ -5,12 +5,15 @@ import { createSnapshotStore } from './snapshotStore';
 import type { SnapshotStore } from './snapshotStore';
 import type {
   FormDebugSnapshot,
-  FormErrors,
+  FormError,
   FormHelpers,
   FormValuesObject,
   UnionPolicyCheck,
 } from './types';
+import type { Path } from '../path/types';
 import type { Refine, Validations } from '../validations/types';
+import { validateEntry } from '../validations/walk';
+import type { FlatConstraintEntry } from '../validations/walk';
 
 // `const V` freezes the inferred type of an inline `constraints` object —
 // each validator's precise type and Refinement marker survive without any
@@ -41,20 +44,25 @@ export const useFormState = <
   const [values, onValueChanges] = useState<T>(initialValues);
   const [submitAttempted, setSubmitAttempted] = useState(false);
 
-  const errors: FormErrors<T> = {};
+  const errors: FormError<T>[] = [];
   if (constraints) {
     for (const key of Object.keys(constraints) as (keyof T & string)[]) {
-      // Field type and validator input are correlated per key, but TS can't
-      // track that through the union of keys — widen the input to unknown.
-      const validator = constraints[key] as
-        | ((val: unknown) => string | null)
-        | undefined;
-      const error = validator?.(values[key]);
-      if (error != null) errors[key] = error;
+      // 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];
+      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 });
     }
   }
 
-  const isValid = Object.keys(errors).length === 0;
+  const isValid = errors.length === 0;
 
   // Debugger plumbing: one store + one component per hook instance, created
   // lazily on first render. The component's identity must be stable across

package/src/forms/validations/perField.ts

@@ -5,7 +5,10 @@
 // `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>,
+  const V extends Record<
+    string,
+    ((val: never) => string | null) | readonly ((val: never) => string | null)[]
+  >,
 >(
   validations: V,
 ): V => validations;

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

@@ -97,3 +97,128 @@ describe('Refine<T, V>', () => {
     expectTypeOf<Result>().toEqualTypeOf<FormType>();
   });
 });
+
+describe('Refine<T, V> — validator arrays', () => {
+  it('a validator array narrows by the union of its members’ excludes', () => {
+    // All members run (first-error-wins only stops on failure, and failure
+    // blocks submit), so every member's narrowing is earned — union of
+    // excludes over C[number], one Exclude. Same semantics as allOf.
+    const constraints = {
+      a: [notEmpty('a'), minLength('a', 3), matches('a', /^\S+$/, 'no spaces')],
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result['a']>().toEqualTypeOf<string>();
+  });
+
+  it('an array of bare validators narrows nothing', () => {
+    const constraints = {
+      a: [
+        (val: string | undefined) => (val ? null : 'required'),
+        (val: string | undefined) => (val && val.length > 2 ? null : 'short'),
+      ],
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<FormType>();
+  });
+
+  it('bare members ride along beside marked ones without diluting them', () => {
+    const constraints = {
+      a: [notEmpty('a'), (val: string | undefined) => (val === 'x' ? 'no x' : null)],
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    // The bare member contributes `never` to the excludes union.
+    expectTypeOf<Result['a']>().toEqualTypeOf<string>();
+  });
+
+  it('an empty validator array leaves the field unchanged', () => {
+    const constraints = { a: [] } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<FormType>();
+  });
+
+  it('preserves array-member precision through perField', () => {
+    const constraints = perField({
+      a: [notEmpty('a'), minLength('a', 3)],
+      c: notEmpty('c'),
+    }) satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result>().toEqualTypeOf<{
+      a: string;
+      b: number;
+      c: string;
+    }>();
+  });
+});
+
+describe('Refine<T, V> — union-typed members inside arrays', () => {
+  it('a conditionally-picked member claims only what every branch guarantees', () => {
+    // Only ONE branch of the member runs at runtime. minLength narrows
+    // nothing, so the member earns (null | undefined | '') & never = never —
+    // the field must NOT refine to `string`.
+    const cond = Math.random() > 0.5;
+    const constraints = {
+      a: [cond ? notEmpty('a') : minLength('a', 3)],
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result['a']>().toEqualTypeOf<string | undefined>();
+  });
+
+  it('earns the intersection of the branches’ excludes, not the union', () => {
+    // (undefined | '') & (null | '') = '' — `undefined` must survive because
+    // the second branch never rules it out. The unsound union-of-branches
+    // reading would have claimed `string`.
+    const cond = Math.random() > 0.5;
+    const branchA = {} as Validator<string | undefined, undefined | ''>;
+    const branchB = {} as Validator<string | undefined, null | ''>;
+    const constraints = {
+      a: [cond ? branchA : branchB],
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result['a']>().toEqualTypeOf<string | undefined>();
+  });
+
+  it('a union-typed member does not dilute solid members beside it', () => {
+    const cond = Math.random() > 0.5;
+    const constraints = {
+      a: [cond ? notEmpty('a') : minLength('a', 3), notEmpty('a')],
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result['a']>().toEqualTypeOf<string>();
+  });
+
+  it('allOf: a union-typed part claims only what every branch guarantees', () => {
+    const cond = Math.random() > 0.5;
+    const constraints = {
+      a: allOf(cond ? notEmpty('a') : minLength('a', 3)),
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result['a']>().toEqualTypeOf<string | undefined>();
+  });
+});
+
+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
+    // the per-branch refinements — RefineField distributes over the naked
+    // constraint union to produce exactly that. (Contrast with arrays above,
+    // where every member runs and the excludes union in a single Exclude.)
+    // Here the minLength branch never rules out undefined, so undefined
+    // must survive in the submit type.
+    const cond = Math.random() > 0.5;
+    const constraints = {
+      a: cond ? notEmpty('a') : minLength('a', 3),
+    } as const satisfies Validations<FormType>;
+
+    type Result = Refine<FormType, typeof constraints>;
+    expectTypeOf<Result['a']>().toEqualTypeOf<string | undefined>();
+  });
+});

package/src/forms/validations/types.ts

@@ -16,23 +16,87 @@ export type Refinement<Excluded = never> = {
 export type Validator<Input, Excluded = never> =
   ((val: Input) => string | null) & Refinement<Excluded>;
 
-// The constraint for a per-field validation map. Deliberately does NOT demand
-// the `Refinement` marker: a bare `(val) => string | null` is a legal
-// constraint that narrows nothing. Markers on standard-library validators
-// ride along in the *inferred* type of a concrete constraints object and are
-// recovered structurally by `Refine<>`.
+// A single field validator. Deliberately does NOT demand the `Refinement`
+// marker: a bare `(val) => string | null` is a legal constraint that narrows
+// nothing. Markers on standard-library validators ride along in the
+// *inferred* type of a concrete constraints object and are recovered
+// structurally by `Refine<>`.
+export type FieldValidator<F> = (val: F) => string | null;
+
+// What a constraints key may map to — phase 1 of the target grammar (see
+// plan.md): the leaf forms only. A single validator, or an ordered list of
+// validators run first-error-wins (sugar over `allOf` at the constraint
+// site; `allOf` remains for building reusable composite validators). The
+// structural forms (nested `Validations`, list `each`) arrive in phases 2–3.
+export type FieldConstraint<F> =
+  | FieldValidator<F>
+  | readonly FieldValidator<F>[];
+
+// The constraint for a per-field validation map.
 export type Validations<T extends FormValuesObject> = {
-  readonly [K in keyof T]?: (val: T[K]) => string | null;
+  readonly [K in keyof T]?: FieldConstraint<T[K]>;
 };
 
-// Applies each field's validator marker to the form type: the submit-time
-// type. Fields whose validator carries `Refinement<X>` become
-// `Exclude<T[K], X>`; unconstrained fields and bare (marker-less) validators
+// Extracts a validator's refinement marker; bare functions contribute
+// `never`. Distributes over a union-typed validator, yielding the union of
+// the branches' excludes — which is why it must NOT be applied to array
+// members directly (see `SoundExcludedOf`).
+export type ExcludedOf<C> = C extends Refinement<infer Excluded>
+  ? Excluded
+  : never;
+
+type UnionToIntersection<U> = (
+  U extends unknown ? (arg: U) => void : never
+) extends (arg: infer I) => void
+  ? I
+  : never;
+
+// What one composed validator (an array member, an `allOf` part) is
+// GUARANTEED to exclude. A member that is itself a *union* of validators
+// (`cond ? v1 : v2`) runs only one branch at runtime, so it may only claim
+// the INTERSECTION of its branches' excludes — what every branch guarantees.
+// Each branch's excludes are boxed in a one-tuple before intersecting so a
+// single validator's own union marker (e.g. notEmpty's
+// `null | undefined | ''`) is not collapsed by the intersection; indexing
+// `[0]` afterwards unboxes (the constrained `infer` keeps the index legal
+// for the checker; inferring the element via `[infer E]` would be wrong —
+// inference from an intersection picks one constituent, not the
+// intersection). A bare-function branch contributes `never`, so a union
+// containing one guarantees nothing — its intersection is `never`.
+type SoundExcludedOf<M> = UnionToIntersection<
+  M extends unknown ? readonly [ExcludedOf<M>] : never
+> extends infer Boxed extends readonly [unknown]
+  ? Boxed[0]
+  : never;
+
+// The excludes earned by a list of validators that ALL run: the union across
+// members, each member contributing only its per-member-sound excludes.
+export type MemberExcludes<C extends readonly unknown[]> = {
+  [I in keyof C]: SoundExcludedOf<C[I]>;
+}[number];
+
+// One field's refinement. `C` is a naked type parameter, so a *union* of
+// constraint types distributes: `RefineField<F, A | B>` is
+// `RefineField<F, A> | RefineField<F, B>`. That distribution is load-bearing
+// for soundness — a conditionally-picked validator (`cond ? v1 : v2`) only
+// runs ONE branch at runtime, so the field may only narrow to the union of
+// the per-branch results, which is exactly what distribution produces. A
+// validator *array* is the opposite regime: every member runs, so the union
+// ACROSS members is earned in a single `Exclude` — but each member's own
+// contribution is per-member sound (`MemberExcludes`): a union-typed member
+// claims only the intersection of its branches' excludes. Branch order
+// matters once the grammar grows structural forms (validator functions are
+// objects) — `Refinement` stays first.
+type RefineField<F, C> = C extends Refinement<infer Excluded>
+  ? Exclude<F, Excluded>
+  : C extends readonly unknown[]
+    ? Exclude<F, MemberExcludes<C>>
+    : F;
+
+// Applies each field's constraint to the form type: the submit-time type.
+// Singles narrow by their marker, arrays by the union of their members'
+// sound excludes; unconstrained fields and bare (marker-less) validators
 // pass through unchanged. Shallow by design — one mapped type, no recursion.
 export type Refine<T extends FormValuesObject, V extends Validations<T>> = {
-  [K in keyof T]: K extends keyof V
-    ? V[K] extends Refinement<infer Excluded>
-      ? Exclude<T[K], Excluded>
-      : T[K]
-    : T[K];
+  [K in keyof T]: K extends keyof V ? RefineField<T[K], V[K]> : T[K];
 };

package/src/forms/validations/walk.test.ts

@@ -0,0 +1,75 @@
+import { describe, test, expect, mock } from 'bun:test';
+import { validateEntry } from './walk';
+
+const pass = () => null;
+const fail = (message: string) => () => message;
+
+describe('validateEntry — single validator', () => {
+  test('a passing validator yields no error', () => {
+    expect(validateEntry(pass, 'anything', ['a'])).toBeNull();
+  });
+
+  test('a failing validator yields its message at the given path', () => {
+    expect(validateEntry(fail('nope'), 'anything', ['a'])).toEqual({
+      path: ['a'],
+      error: 'nope',
+    });
+  });
+
+  test('the validator receives the field value', () => {
+    const spy = mock((val: string) => (val === 'x' ? null : 'expected x'));
+    expect(validateEntry(spy, 'x', ['a'])).toBeNull();
+    expect(spy).toHaveBeenCalledWith('x');
+  });
+});
+
+describe('validateEntry — validator arrays', () => {
+  test('all passing yields no error', () => {
+    expect(validateEntry([pass, pass, pass], 'v', ['a'])).toBeNull();
+  });
+
+  test('validators run in array order and the first error wins', () => {
+    const result = validateEntry(
+      [pass, fail('second'), fail('third')],
+      'v',
+      ['a'],
+    );
+    expect(result).toEqual({ path: ['a'], error: 'second' });
+  });
+
+  test('validators after the first failure are not called', () => {
+    const after = mock(() => 'never reached');
+    validateEntry([fail('boom'), after], 'v', ['a']);
+    expect(after).not.toHaveBeenCalled();
+  });
+
+  test('every validator before the failure sees the value', () => {
+    const first = mock(() => null);
+    const second = mock(() => null);
+    expect(validateEntry([first, second], 42, ['n'])).toBeNull();
+    expect(first).toHaveBeenCalledWith(42);
+    expect(second).toHaveBeenCalledWith(42);
+  });
+
+  test('an empty array passes', () => {
+    expect(validateEntry([], undefined, ['a'])).toBeNull();
+  });
+});
+
+describe('validateEntry — path accumulation', () => {
+  test('the error carries the path it was given, verbatim', () => {
+    // Phase 1 paths are single-key; the signature already speaks PathStep[]
+    // so the phases-2/3 {path, error}[] model needs no walk rewrite.
+    const result = validateEntry(fail('bad date'), undefined, [
+      'drivers',
+      3,
+      'incidents',
+      0,
+      'date',
+    ]);
+    expect(result).toEqual({
+      path: ['drivers', 3, 'incidents', 0, 'date'],
+      error: 'bad date',
+    });
+  });
+});

package/src/forms/validations/walk.ts

@@ -0,0 +1,52 @@
+import type { PathStep } from '../path/types';
+
+// The runtime walk over a constraints object, kept separate from the hook so
+// its semantics are unit-testable without React. Phase 1 grammar is flat —
+// every path has exactly one step — but errors already carry a `PathStep[]`
+// address, which the hook's structured `{path, error}[]` error model
+// (`FormErrors<T>`) consumes directly; the recursive grammar of plan phases
+// 2–3 just hands the walk longer paths, no second rewrite.
+
+export type ValidationError = {
+  readonly path: readonly PathStep[];
+  readonly error: string;
+};
+
+// The walk's receiving type for one validator. `never` is the one parameter
+// type every field validator is assignable to (contravariance) — the walk
+// cannot correlate a validator's input with its field's value type, so it
+// accepts them all and re-widens at the single call site below.
+type AnyFieldValidator = (val: never) => string | null;
+
+// The walk's view of one entry in a `Validations<T>` object. This type is
+// what lets the compiler police the walk's assumptions: the hook assigns
+// `constraints[key]` to it WITHOUT a cast, so when the grammar grows a form
+// that is neither a function nor an array of them (nested spec, list `each`),
+// that assignment stops compiling and the walk must learn the new form —
+// instead of a stale walk misinterpreting it at runtime.
+export type FlatConstraintEntry =
+  | AnyFieldValidator
+  | readonly AnyFieldValidator[];
+
+// Runs one constraint entry against the field value found at `path`.
+// Semantics for arrays (identical to `allOf`): validators run in array
+// order, first error wins — later validators are not called once one fails.
+// An empty array passes, mirroring its refinement (`Exclude<F, never>`).
+export const validateEntry = (
+  entry: FlatConstraintEntry,
+  value: unknown,
+  path: readonly PathStep[],
+): ValidationError | null => {
+  const validators = typeof entry === 'function' ? [entry] : entry;
+
+  for (const validator of validators) {
+    // Safe: the constraints object was type-checked against the form type
+    // where it was built, so this validator accepts the value at `path`; the
+    // walk just can't see that correlation. Same honest contravariant
+    // widening as `allOf`'s part-call.
+    const error = (validator as (val: unknown) => string | null)(value);
+    if (error != null) return { path, error };
+  }
+
+  return null;
+};

package/src/forms/validators/validators.ts

@@ -1,4 +1,4 @@
-import type { Refinement, Validator } from '../validations/types';
+import type { MemberExcludes, Refinement, Validator } from '../validations/types';
 
 // Standard-library validators. Each one declares its refinement explicitly —
 // `Validator<Input, Excluded>` — even when it narrows nothing (`never`).
@@ -60,8 +60,6 @@ export const min = (
     {} as Refinement,
   );
 
-type ExcludedOf<V> = V extends Refinement<infer Excluded> ? Excluded : never;
-
 // The composed input is the *intersection* of the parts' inputs: a value the
 // composite accepts must be acceptable to every part. Inferring `I` from the
 // union of function types puts it in contravariant position, which is what
@@ -75,13 +73,15 @@ type InputOf<Validators extends readonly ((val: never) => string | null)[]> =
 
 // Composes validators on one field: first error wins. The refinement is the
 // union of the parts' refinements — running all of them earns all of their
-// narrowings. `const Validators` keeps each member's precise type so
-// `ExcludedOf` can extract markers; bare functions contribute `never`.
+// narrowings, with each part contributing only its per-member-sound excludes
+// (`MemberExcludes`: a union-typed part earns just the intersection of its
+// branches). `const Validators` keeps each member's precise type so the
+// markers survive extraction; bare functions contribute `never`.
 export const allOf = <
   const Validators extends readonly ((val: never) => string | null)[],
 >(
   ...validators: Validators
-): Validator<InputOf<Validators>, ExcludedOf<Validators[number]>> =>
+): Validator<InputOf<Validators>, MemberExcludes<Validators>> =>
   Object.assign(
     (val: InputOf<Validators>) => {
       for (const validator of validators) {
@@ -91,5 +91,5 @@ export const allOf = <
       }
       return null;
     },
-    {} as Refinement<ExcludedOf<Validators[number]>>,
+    {} as Refinement<MemberExcludes<Validators>>,
   );