@structuralists/scaffolding 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structuralists/scaffolding",
-  "version": "0.8.0",
+  "version": "0.9.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
@@ -240,9 +289,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,10 +15,14 @@ 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.
+   ← *current*
 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.
 5. **Item 6 — field binding** (`getFormFieldPropsAt` + wrappers). Needs the
@@ -112,10 +116,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,6 +164,17 @@ 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%)
+
 ## Runtime consequences (can't be dodged)
 
 - **The validator walk becomes a tree walk.** Recursion mirrors `read()` in
@@ -190,7 +207,13 @@ 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).

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

@@ -2,7 +2,7 @@ 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 { 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,8 +53,10 @@ 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),
@@ -154,8 +156,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 +176,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 +200,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)],
     },
   });
 
@@ -266,7 +269,7 @@ 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'),
       },
     });

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

@@ -34,6 +34,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 +315,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 +369,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

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

@@ -108,6 +108,55 @@ 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(result.current.errors.email).toBe("'email' cannot be empty");
+
+    act(() => {
+      result.current.onValueChanges((prev) => ({ ...prev, email: 'nope' }));
+    });
+    expect(result.current.errors.email).toBe("'email' must be a valid email");
+
+    act(() => {
+      result.current.onValueChanges((prev) => ({ ...prev, email: 'a@b.co' }));
+    });
+    expect(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(() =>
@@ -144,6 +193,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

@@ -11,6 +11,8 @@ import type {
   UnionPolicyCheck,
 } from './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
@@ -44,13 +46,12 @@ export const useFormState = <
   const errors: FormErrors<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) errors[key] = failure.error;
     }
   }
 

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,51 @@
+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 so the `{path, error}[]` error model of plan phases 2–3 falls out
+// of this structure instead of forcing a 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>>,
   );