@structuralists/scaffolding 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@structuralists/scaffolding",
-  "version": "0.7.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
@@ -119,8 +168,82 @@ useFormState({
 });
 ```
 
+## Union policy — what form state may hold
+
+The path machinery is load-bearing (structured `{path, error}[]` errors and
+`getFormFieldPropsAt` both build on it), so its contract is strict: **every
+path `Path<T>` admits must resolve to a correct, useful type via `ValueAt`.**
+Unions against objects and arrays sank a previous incarnation of this kind of
+form-state management; the lesson adopted here is to support the one union
+form state genuinely needs and loudly reject the rest.
+
+**Allowed — nullability on any field.** `Section | undefined`,
+`Item[] | null`, etc. are everyday form state ("not filled in yet", "not
+loaded yet"). Scalar unions (`'a' | 'b' | undefined`) are also fine — they
+are `FormValueSimple` leaves. Resolution semantics, identical at the type
+level (`ValueAt`) and runtime (`read()`):
+
+- A path that stops **at** a nullable field resolves to the field's exact
+  type — `| null` preserved.
+- A path that steps **through** a nullable ancestor picks up `| undefined` —
+  always `undefined`, never `null`, even when the ancestor's own nullability
+  is `null`, because `read()` returns `undefined` for any dead step. Chained
+  nullable ancestors contribute a single `| undefined`.
+
+**Disallowed — every other union.** After stripping `null | undefined`, a
+field must be exactly one shape. Unions of two object types (tagged or
+untagged), object-vs-list, object-vs-scalar, list-vs-list are all rejected,
+in three layers:
+
+1. **At the `useFormState` boundary**: an illegal form type makes the call
+   fail with an unsatisfiable `'ERROR: form state disallows unions of
+   objects/lists …'` property whose type names the offending keys
+   (`UnionPolicyCheck<T>` in `useFormState/types.ts`).
+2. **`Path<T>` refuses to descend** into a disallowed union — the field
+   stays addressable as a leaf (reading it yields the union, which is
+   honest), but no paths below it exist, so `.at(…)`/path literals into it
+   are compile errors.
+3. **A hand-written `ValueAt` into one** resolves to the loud
+   `DisallowedFormUnion` marker — never a quiet `never`.
+
+**Tagged/discriminated unions are deliberately deferred, not supported.**
+Reliable per-variant path semantics would require detecting the discriminant
+at the type level — fragile and expensive against the recursion budget.
+Model variants as sibling optional sections plus a scalar discriminant
+field, which the nullable-section support makes ergonomic:
+
+```ts
+// instead of:  party: { kind: 'person'; … } | { kind: 'company'; … }
+partyKind: 'person' | 'company' | undefined;
+person: { name: string | undefined } | undefined;
+company: { vat: string | undefined } | undefined;
+```
+
+Known, accepted type/runtime divergence: indexing a *present* list types the
+element without `| undefined` (standard TS array-indexing convention; we
+don't use `noUncheckedIndexedAccess`), while `read()` returns `undefined`
+out of bounds.
+
+Maintainer note: `Path<T>` must remain a distributive conditional over naked
+`T`. Wrapping the check type (e.g. `PathShapes<NonNullable<T>>`) makes the
+constraint of `P extends Path<T>` uncomputable for generic `T` and blows the
+recursion stack (TS2589) at `Cursor.at`. Nullability handling rides on that
+distribution; the union-policy gate lives in `PathBelow`, applied at each
+descent into a field.
+
 ## Caveats — known and accepted
 
+- **Generic pass-through wrappers of `useFormState` are unsupported.** A
+  hook generic over `T extends FormValuesObject` that forwards
+  `initialValues` — e.g. `<T extends FormValuesObject>(init: T) =>
+  useFormState({ initialValues: init })` — fails to compile with TS2589
+  ("Type instantiation is excessively deep"), because the boundary gate
+  `UnionPolicyCheck<T>` cannot resolve for an unresolved generic `T`. The
+  error names recursion depth, not the union policy — if you hit it in a
+  wrapper, this is why. Accepted tradeoff of the conditional-type boundary
+  gate, and congruent with intended usage: wrap the hook in a custom hook
+  that pre-applies a *concrete* form type instead — `T` then resolves
+  concretely and compiles fine.
 - **`Exclude<string, ''>` is still `string`.** The empty-string refinement
   only narrows fields whose type is a *union* containing the literal `''`.
   For plain `string`, `notEmpty` still validates at runtime, but the
@@ -163,9 +286,21 @@ precision end-to-end. So we wire it up before adding any consumers.
 - `path/` — typed cursor (`Path<T>`, `ValueAt<T,P>`, `Cursor<T>`, `read()`).
   Will be used for granular setters and for surfacing per-field
   errors/touched state. Coupled to the form value model intentionally.
-- `validations/` — `perField`, `Validations<T>`, `Refine<T,V>`,
-  `Refinement<>` infra. `Validations<T>` accepts bare
+  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>` / `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/path/path.test.ts

@@ -0,0 +1,112 @@
+import { describe, test, expect } from 'bun:test';
+import { path, read } from './path';
+
+// These tests pin read()'s runtime semantics to exactly what the type level
+// (ValueAt) promises — see the union-semantics comments in ./types.ts and
+// the "Union policy" section in src/forms/CLAUDE.md. The load-bearing rule:
+// stepping THROUGH a dead value (undefined or null) yields undefined; a path
+// that stops AT a nullable field yields the field's actual value, null
+// included.
+
+type Address = { city: string | undefined; zip: string };
+
+type Form = {
+  name: string;
+  // optional nested section
+  address: Address | undefined;
+  // nullable list
+  entries: Array<{ title: string; qty: number }> | null;
+  // chained nullables
+  a: { b: { c: string } | null } | undefined;
+};
+
+const filled: Form = {
+  name: 'Ada',
+  address: { city: 'London', zip: 'N1' },
+  entries: [{ title: 'first', qty: 1 }],
+  a: { b: { c: 'deep' } },
+};
+
+const empty: Form = {
+  name: 'Ada',
+  address: undefined,
+  entries: null,
+  a: undefined,
+};
+
+describe('read through nullable ancestors', () => {
+  test('resolves normally when the nullable ancestor is present', () => {
+    const steps = path<Form>().at(['address', 'city']).build();
+    expect(read(filled, steps)).toBe('London');
+
+    const listSteps = path<Form>().at(['entries', 0, 'title']).build();
+    expect(read(filled, listSteps)).toBe('first');
+
+    const chained = path<Form>().at(['a', 'b', 'c']).build();
+    expect(read(filled, chained)).toBe('deep');
+  });
+
+  test('returns undefined when an undefined ancestor is stepped through', () => {
+    const steps = path<Form>().at(['address', 'city']).build();
+    expect(read(empty, steps)).toBeUndefined();
+  });
+
+  test('returns undefined when a null ancestor is stepped through — null never leaks', () => {
+    const steps = path<Form>().at(['entries', 0, 'title']).build();
+    expect(read(empty, steps)).toBeUndefined();
+
+    const midNull: Form = { ...filled, a: { b: null } };
+    const chained = path<Form>().at(['a', 'b', 'c']).build();
+    expect(read(midNull, chained)).toBeUndefined();
+  });
+
+  test('a path stopping AT a nullable field returns the actual value, null included', () => {
+    // Ancestors count for the through-a-dead-value rule; the addressed field
+    // itself does not — its own value comes back as-is. This is why ValueAt
+    // preserves `| null` on the field but converts ancestor nullability to
+    // `| undefined`.
+    expect(read(empty, path<Form>().at(['entries']).build())).toBeNull();
+    expect(read(empty, path<Form>().at(['address']).build())).toBeUndefined();
+    expect(read(filled, path<Form>().at(['entries']).build())).toEqual([
+      { title: 'first', qty: 1 },
+    ]);
+  });
+});
+
+describe('read step failures', () => {
+  test('out-of-bounds list index returns undefined', () => {
+    // Known type/runtime divergence, TS-array-indexing style: ValueAt types
+    // a present list's element WITHOUT `| undefined`. Documented in
+    // src/forms/CLAUDE.md.
+    const steps = path<Form>().at(['entries', 5, 'title']).build();
+    expect(read(filled, steps)).toBeUndefined();
+  });
+
+  test('numeric step on a non-list returns undefined', () => {
+    expect(read(filled, [{ kind: 'key', key: 0 }])).toBeUndefined();
+  });
+
+  test('string step on a scalar returns undefined', () => {
+    expect(
+      read(filled, [
+        { kind: 'key', key: 'name' },
+        { kind: 'key', key: 'length' },
+      ]),
+    ).toBeUndefined();
+  });
+
+  test('rejecting narrow predicate returns undefined; accepting one passes through', () => {
+    const isString = (val: unknown): val is string => typeof val === 'string';
+    const narrowed = path<Form>()
+      .at(['name'])
+      .narrow((val): val is string => isString(val))
+      .build();
+    expect(read(filled, narrowed)).toBe('Ada');
+
+    const rejecting = [
+      { kind: 'key' as const, key: 'name' },
+      { kind: 'narrow' as const, predicate: (val: unknown) => typeof val === 'number' },
+    ];
+    expect(read(filled, rejecting)).toBeUndefined();
+  });
+});

package/src/forms/path/path.ts

@@ -22,10 +22,13 @@ const makeCursor = <T>(steps: readonly CursorStep[]): Cursor<T> => ({
 
 export const path = <T>(): Cursor<T> => makeCursor<T>([]);
 
-// Walk steps against a value. Returns undefined if any step fails — missing
-// key, out-of-bounds index, or a narrow predicate that rejects the current
-// value. Callers using the typed cursor know what shape to expect; this is
-// the runtime escape hatch that surfaces "the path didn't resolve."
+// Walk steps against a value. Returns undefined if any step fails — a dead
+// value (null or undefined) encountered mid-path, missing key, out-of-bounds
+// index, or a narrow predicate that rejects the current value. Always
+// undefined, never null, even when the dead value was null — ValueAt in
+// ./types.ts mirrors this exactly (see "Union policy" in src/forms/CLAUDE.md).
+// Callers using the typed cursor know what shape to expect; this is the
+// runtime escape hatch that surfaces "the path didn't resolve."
 export const read = (root: unknown, steps: readonly CursorStep[]): unknown => {
   let cursor: unknown = root;
 

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

@@ -28,6 +28,30 @@ type Mixed = {
   }>;
 };
 
+// Nullable ancestors — the one union form state supports. See the "Union
+// policy" section in src/forms/CLAUDE.md.
+type WithOptionalSection = {
+  name: string;
+  address: { city: string; zip: string | undefined } | undefined;
+};
+
+type WithNullableList = {
+  entries: Array<{ title: string; qty: number }> | null;
+};
+
+type WithChainedNullables = {
+  a: { b: { c: string } | null } | undefined;
+};
+
+// Disallowed unions — everything that isn't "single shape, possibly
+// null/undefined". Paths must not descend into these.
+type Tagged = { kind: 'person'; name: string } | { kind: 'company'; vat: string };
+type WithTaggedUnion = { party: Tagged };
+type WithUntaggedUnion = { thing: { a: string } | { b: number } };
+type WithObjOrList = { x: { a: string } | Array<{ a: string }> };
+type WithObjOrScalar = { y: { a: string } | string };
+type WithNullableDisallowed = { z: { a: string } | { b: number } | undefined };
+
 describe('Path<T>', () => {
   it('expands flat object keys to single-step paths', () => {
     type P = Path<FlatObj>;
@@ -76,6 +100,32 @@ describe('Path<T>', () => {
     expectTypeOf<Path<string[]>>().toEqualTypeOf<never>();
     expectTypeOf<Path<undefined>>().toEqualTypeOf<never>();
   });
+
+  it('descends into optional sections and nullable lists', () => {
+    expectTypeOf<Path<WithOptionalSection>>().toEqualTypeOf<
+      ['name'] | ['address'] | ['address', 'city'] | ['address', 'zip']
+    >();
+    expectTypeOf<Path<WithNullableList>>().toEqualTypeOf<
+      | ['entries']
+      | ['entries', number]
+      | ['entries', number, 'title']
+      | ['entries', number, 'qty']
+    >();
+    expectTypeOf<Path<WithChainedNullables>>().toEqualTypeOf<
+      ['a'] | ['a', 'b'] | ['a', 'b', 'c']
+    >();
+  });
+
+  it('refuses to descend into disallowed unions — the field is a leaf', () => {
+    // The field itself stays addressable (reading it yields the union,
+    // which is honest); paths *into* it are never generated.
+    expectTypeOf<Path<WithTaggedUnion>>().toEqualTypeOf<['party']>();
+    expectTypeOf<Path<WithUntaggedUnion>>().toEqualTypeOf<['thing']>();
+    expectTypeOf<Path<WithObjOrList>>().toEqualTypeOf<['x']>();
+    expectTypeOf<Path<WithObjOrScalar>>().toEqualTypeOf<['y']>();
+    // Nullability does not launder a disallowed union into an allowed one.
+    expectTypeOf<Path<WithNullableDisallowed>>().toEqualTypeOf<['z']>();
+  });
 });
 
 describe('ValueAt<T, P>', () => {
@@ -129,6 +179,55 @@ describe('ValueAt<T, P>', () => {
     type Bad = ValueAt<FlatObj, [number]>;
     expectTypeOf<Bad>().toEqualTypeOf<never>();
   });
+
+  it('resolves through an optional section as `V | undefined`', () => {
+    // The section itself resolves exactly …
+    expectTypeOf<ValueAt<WithOptionalSection, ['address']>>().toEqualTypeOf<
+      WithOptionalSection['address']
+    >();
+    // … a non-optional leaf below it picks up `| undefined` from the ancestor …
+    expectTypeOf<
+      ValueAt<WithOptionalSection, ['address', 'city']>
+    >().toEqualTypeOf<string | undefined>();
+    // … and an already-optional leaf stays `| undefined` (no double-counting).
+    expectTypeOf<
+      ValueAt<WithOptionalSection, ['address', 'zip']>
+    >().toEqualTypeOf<string | undefined>();
+  });
+
+  it('resolves through a nullable list as `V | undefined`, never `V | null`', () => {
+    // Dead ancestors surface as `undefined` in the resolved type even when
+    // the ancestor's own nullability is `null` — read() returns undefined
+    // for any dead step, and the types mirror read() exactly.
+    expectTypeOf<ValueAt<WithNullableList, ['entries']>>().toEqualTypeOf<
+      WithNullableList['entries']
+    >();
+    expectTypeOf<
+      ValueAt<WithNullableList, ['entries', number]>
+    >().toEqualTypeOf<{ title: string; qty: number } | undefined>();
+    expectTypeOf<
+      ValueAt<WithNullableList, ['entries', number, 'title']>
+    >().toEqualTypeOf<string | undefined>();
+  });
+
+  it('collapses chained nullable ancestors into a single `| undefined`', () => {
+    expectTypeOf<
+      ValueAt<WithChainedNullables, ['a', 'b', 'c']>
+    >().toEqualTypeOf<string | undefined>();
+  });
+
+  it('resolves a disallowed-union field itself, but never into it', () => {
+    // The field is a leaf: reading it yields the union, honestly.
+    expectTypeOf<ValueAt<WithTaggedUnion, ['party']>>().toEqualTypeOf<Tagged>();
+    // Stepping *into* it is loud — a branded error object, not a quiet
+    // `never`. (Path<T> never admits these paths; this covers hand-written
+    // ValueAt uses.)
+    type Loud = ValueAt<WithTaggedUnion, ['party', 'kind']>;
+    expectTypeOf<Loud>().not.toEqualTypeOf<never>();
+    expectTypeOf<Loud>().toHaveProperty(
+      'ERROR: form state disallows unions of objects/lists — restructure this field',
+    );
+  });
 });
 
 describe('Cursor<T>', () => {
@@ -158,6 +257,31 @@ describe('Cursor<T>', () => {
     path<NestedObj>().at(['user', 0]);
   });
 
+  it('tracks `| undefined` through nullable ancestors', () => {
+    const c = path<WithOptionalSection>().at(['address', 'city']);
+    expectTypeOf(c).toEqualTypeOf<Cursor<string | undefined>>();
+
+    const el = path<WithNullableList>().at(['entries', 0]);
+    expectTypeOf(el).toEqualTypeOf<
+      Cursor<{ title: string; qty: number } | undefined>
+    >();
+  });
+
+  it('rejects stepping into disallowed unions at the call site', () => {
+    // @ts-expect-error tagged unions are not path-addressable below the field
+    path<WithTaggedUnion>().at(['party', 'kind']);
+
+    // @ts-expect-error untagged object unions are not path-addressable below the field
+    path<WithUntaggedUnion>().at(['thing', 'a']);
+
+    // @ts-expect-error object-vs-list unions are not path-addressable below the field
+    path<WithObjOrList>().at(['x', 0]);
+
+    // the field itself remains addressable
+    const c = path<WithTaggedUnion>().at(['party']);
+    expectTypeOf(c).toEqualTypeOf<Cursor<Tagged>>();
+  });
+
   it('narrow() refines the cursor type', () => {
     const c = path<{ value: string | number }>().at(['value']);
     expectTypeOf(c).toEqualTypeOf<Cursor<string | number>>();

package/src/forms/path/types.ts

@@ -1,28 +1,71 @@
-import type { FormValuesObject, FormValueList } from '../useFormState/types';
+import type {
+  DisallowedFormUnion,
+  FormValueList,
+  FormValuesObject,
+  IsDisallowedFormUnion,
+} from '../useFormState/types';
 
 export type PathStep = string | number;
 
-export type Path<T> =
-  T extends FormValuesObject
-    ? {
-        [K in Extract<keyof T, PathStep>]: [K] | [K, ...Path<T[K]>];
-      }[Extract<keyof T, PathStep>]
-    : T extends FormValueList
-      ? [number] | [number, ...Path<T[number]>]
-      : never;
+// Union semantics (the full policy lives in src/forms/CLAUDE.md):
+// - Nullability is handled here, once, at the top: `Section | undefined` and
+//   `Item[] | null` are everyday form state, so paths descend through them
+//   as if the shape were present.
+// - Disallowed unions (object|object, object|list, object|scalar, list|list)
+//   get NO paths into them — the field stays addressable as a leaf, which is
+//   honest (reading it yields the union), but nothing below it is.
+// Path<T> must stay a distributive conditional over naked T: wrapping the
+// check type (e.g. `PathShapes<NonNullable<T>>`) makes the constraint of
+// `P extends Path<T>` uncomputable for generic T and blows the recursion
+// stack at Cursor.at (TS2589). Distribution also IS the nullability
+// handling here — the undefined/null members of a nullable section fall
+// into the final `never` arm and drop out of the union.
+export type Path<T> = T extends FormValuesObject
+  ? {
+      [K in Extract<keyof T, PathStep>]: [K] | [K, ...PathBelow<T[K]>];
+    }[Extract<keyof T, PathStep>]
+  : T extends FormValueList
+    ? [number] | [number, ...PathBelow<T[number]>]
+    : never;
 
-export type ValueAt<T, P extends readonly PathStep[]> =
-  P extends readonly [infer Head, ...infer Rest]
-    ? Rest extends readonly PathStep[]
-      ? Head extends number
-        ? T extends FormValueList
-          ? ValueAt<T[number], Rest>
-          : never
-        : Head extends keyof T
-          ? ValueAt<T[Head], Rest>
-          : never
+// The union-policy gate, applied at every descent into a field: a
+// disallowed union gets no paths below it (the spread of `never` erases the
+// longer tuple, leaving the field addressable only as a leaf). The root T
+// is a FormValuesObject — never itself a union — so gating descents gates
+// everything.
+type PathBelow<F> =
+  IsDisallowedFormUnion<NonNullable<F>> extends true ? never : Path<F>;
+
+// Resolution mirrors read() exactly: stepping THROUGH a nullable value adds
+// `| undefined` to the result — undefined even when the ancestor's own
+// nullability is `null`, because read() returns undefined for any dead step.
+// A path that stops AT a nullable field resolves to the field's exact type
+// (`| null` preserved); only ancestors count. Stepping into a disallowed
+// union resolves to the loud DisallowedFormUnion marker, never a quiet
+// `never` — though Path<T> refuses to admit such paths in the first place.
+export type ValueAt<T, P extends readonly PathStep[]> = P extends readonly [
+  infer Head extends PathStep,
+  ...infer Rest extends readonly PathStep[],
+]
+  ? [T] extends [NonNullable<T>]
+    ? ValueAtStep<T, Head, Rest>
+    : ValueAtStep<NonNullable<T>, Head, Rest> extends infer V
+      ? [V] extends [never]
+        ? never // an invalid step stays never — don't launder it into undefined
+        : V | undefined
       : never
-    : T;
+  : T;
+
+type ValueAtStep<T, Head extends PathStep, Rest extends readonly PathStep[]> =
+  IsDisallowedFormUnion<T> extends true
+    ? DisallowedFormUnion<T>
+    : Head extends number
+      ? [T] extends [FormValueList]
+        ? ValueAt<T[number], Rest>
+        : never
+      : Head extends keyof T
+        ? ValueAt<T[Head], Rest>
+        : never;
 
 export type CursorStep =
   | { kind: 'key'; key: PathStep }

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).
@@ -396,3 +419,14 @@ editable.
 
 *(Resolved: error path format. Structured `{path, error}[]` with typed
 paths — never exposed serialized-string keys. See "Runtime consequences".)*
+
+*(Resolved: unions in form state. Nullability (`Section | undefined`,
+`Item[] | null`) is fully supported by `Path`/`ValueAt`/`read()` — stepping
+through a dead ancestor resolves as `| undefined`, identically at the type
+level and at runtime. Every other union against objects/lists — including
+tagged unions, deliberately deferred — is rejected at the `useFormState`
+boundary and unaddressable below the field by `Path`. Full policy, the
+recommended variant-modeling pattern, and the `Path` distributivity
+constraint (TS2589) are in forms/CLAUDE.md, "Union policy". The error-model
+swap and `getFormFieldPropsAt` can rely on `ValueAt` being truthful for
+every admitted path.)*