@structuralists/scaffolding 0.7.0 → 0.8.0

package/package.json

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

package/src/forms/CLAUDE.md

@@ -119,8 +119,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,6 +237,9 @@ 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.
+  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
   `(val) => string | null` functions too — they simply narrow nothing.

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

@@ -396,3 +396,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.)*

package/src/forms/useFormState/types.ts

@@ -10,6 +10,72 @@ export type FormValueList = FormValuesObject[];
 
 export type FormValue = FormValuesObject | FormValueList | FormValueSimple;
 
+// --- Union policy ---------------------------------------------------------
+// After stripping null/undefined, a form value must be exactly ONE shape: a
+// simple value (scalar unions like `'a' | 'b'` count as simple), a single
+// object type, or a single list type. Everything else — object|object
+// (tagged or not), object|list, object|scalar, list|list — is disallowed in
+// form state, because the path machinery (`Path`/`ValueAt`) cannot resolve
+// through it reliably. See "Union policy" in src/forms/CLAUDE.md.
+
+type UnionToIntersection<U> = (
+  U extends unknown ? (x: U) => void : never
+) extends (x: infer I) => void
+  ? I
+  : never;
+
+type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true;
+
+// Callers strip null/undefined before asking (nullability is the one union
+// that IS allowed); the FormValueSimple check must come first so scalar
+// unions — including `boolean`, itself `true | false` — never reach IsUnion.
+export type IsDisallowedFormUnion<T> = [T] extends [FormValueSimple]
+  ? false
+  : IsUnion<T>;
+
+// Loud rejection marker: the resolved type when a hand-written ValueAt
+// steps into a disallowed union (Path<T> never admits such paths, so this
+// only surfaces from raw ValueAt uses). Deliberately not an alias of the
+// field type so nothing real is assignable to it, and never a quiet `never`.
+export type DisallowedFormUnion<F> = {
+  readonly 'ERROR: form state disallows unions of objects/lists — restructure this field': F;
+};
+
+// Does this field's subtree contain a disallowed union anywhere? The check
+// FormValueSimple first: string[]/Set<string> are simple leaves, not lists
+// to recurse into.
+type FieldHasDisallowedUnion<F> = [NonNullable<F>] extends [FormValueSimple]
+  ? false
+  : IsDisallowedFormUnion<NonNullable<F>> extends true
+    ? true
+    : [NonNullable<F>] extends [Array<infer E>]
+      ? FieldHasDisallowedUnion<E>
+      : [NonNullable<F>] extends [FormValuesObject]
+        ? HasDisallowedUnion<NonNullable<F>>
+        : false;
+
+type HasDisallowedUnion<T> = true extends {
+  [K in keyof T]: FieldHasDisallowedUnion<T[K]>;
+}[keyof T]
+  ? true
+  : false;
+
+// Top-level keys whose subtree violates the policy — shown in the boundary
+// error so the offender is named, not just detected.
+type DisallowedUnionKeys<T> = {
+  [K in keyof T]: FieldHasDisallowedUnion<T[K]> extends true ? K : never;
+}[keyof T];
+
+// The useFormState boundary gate. Intersected with the hook's Args: a legal
+// form type contributes `unknown` (a no-op); an illegal one demands an
+// unsatisfiable property whose name states the policy and whose type names
+// the offending keys. The offending-keys walk only runs on failing calls.
+export type UnionPolicyCheck<T> = HasDisallowedUnion<T> extends true
+  ? {
+      'ERROR: form state disallows unions of objects/lists — see the union policy in src/forms/CLAUDE.md': DisallowedUnionKeys<T>;
+    }
+  : unknown;
+
 export type FormErrors<T extends FormValuesObject> = Partial<
   Record<keyof T, string>
 >;

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

@@ -133,6 +133,98 @@ describe('useFormState onSubmit narrowing — pre-built constraints', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Union policy at the hook boundary (see "Union policy" in src/forms/CLAUDE.md):
+// nullability is the one union form state supports on object/list fields.
+// Everything else — tagged or untagged object unions, object|list,
+// object|scalar — is rejected at the useFormState call, naming the offending
+// keys, instead of silently producing dead types in resolved paths later.
+// ---------------------------------------------------------------------------
+
+describe('useFormState union policy at the boundary', () => {
+  it('accepts optional sections and nullable lists', () => {
+    useFormState({
+      initialValues: {
+        home: undefined as { city: string | undefined } | undefined,
+        entries: null as Array<{ title: string }> | null,
+      },
+      onSubmit: (values) => {
+        expectTypeOf(values.home).toEqualTypeOf<
+          { city: string | undefined } | undefined
+        >();
+      },
+    });
+  });
+
+  it('rejects tagged object unions', () => {
+    type Party =
+      | { kind: 'person'; name: string }
+      | { kind: 'company'; vat: string };
+
+    // @ts-expect-error tagged object unions are disallowed in form state
+    useFormState({
+      initialValues: { party: { kind: 'person', name: 'Ada' } as Party },
+    });
+  });
+
+  it('rejects untagged object unions, object|list, and object|scalar', () => {
+    // @ts-expect-error untagged object unions are disallowed in form state
+    useFormState({
+      initialValues: {
+        thing: { a: '' } as { a: string } | { b: number },
+      },
+    });
+
+    // @ts-expect-error object|list unions are disallowed in form state
+    useFormState({
+      initialValues: {
+        x: [] as Array<{ a: string }> | { a: string },
+      },
+    });
+
+    // @ts-expect-error object|scalar unions are disallowed in form state
+    useFormState({
+      initialValues: {
+        y: '' as { a: string } | string,
+      },
+    });
+  });
+
+  it('rejects disallowed unions nested below the top level', () => {
+    // @ts-expect-error the policy applies at every depth, not just root keys
+    useFormState({
+      initialValues: {
+        wrapper: {
+          inner: { a: '' } as { a: string } | { b: number },
+        },
+      },
+    });
+
+    // @ts-expect-error … including inside list elements
+    useFormState({
+      initialValues: {
+        rows: [] as Array<{ cell: { a: string } | { b: number } }>,
+      },
+    });
+
+    // @ts-expect-error … and when the list's ELEMENT type is itself a union
+    useFormState({
+      initialValues: {
+        rows: [] as Array<{ a: string } | { b: number }>,
+      },
+    });
+  });
+
+  it('nullability does not launder a disallowed union', () => {
+    // @ts-expect-error `| undefined` on top of an object union is still a union of objects
+    useFormState({
+      initialValues: {
+        z: undefined as { a: string } | { b: number } | undefined,
+      },
+    });
+  });
+});
+
 // ---------------------------------------------------------------------------
 // The recursion probe. Prior explorations of this design narrowed fine on
 // trivial examples but hit TS recursion limits on realistic form state. This
@@ -156,7 +248,23 @@ type InsuranceQuoteForm = {
   phone: string | undefined;
   dateOfBirth: string | undefined;
   homeAddress: UsAddress;
-  mailingAddress: UsAddress;
+  // Optional nested section: absent until the user opts in.
+  mailingAddress: UsAddress | undefined;
+  // Optional section with a non-optional leaf inside — the probe that pins
+  // ancestor nullability surfacing in the leaf's resolved type.
+  coApplicant:
+    | {
+        firstName: string | undefined;
+        lastName: string | undefined;
+        sharesResidence: boolean;
+      }
+    | undefined;
+  // Nullable list: null until upstream quote data loads.
+  pastPolicies: Array<{
+    insurer: string | undefined;
+    policyNumber: string | undefined;
+    activeUntil: string | null;
+  }> | null;
   employer: string | null;
   jobTitle: string | null;
   yearsEmployed: number | null;
@@ -220,6 +328,7 @@ describe('useFormState narrowing at realistic scale', () => {
         // Unconstrained fields — including all nested structure — untouched.
         expectTypeOf(values.paperlessBilling).toEqualTypeOf<boolean>();
         expectTypeOf(values.homeAddress).toEqualTypeOf<UsAddress>();
+        expectTypeOf(values.mailingAddress).toEqualTypeOf<UsAddress | undefined>();
         expectTypeOf(values.drivers).toEqualTypeOf<
           InsuranceQuoteForm['drivers']
         >();
@@ -245,4 +354,47 @@ describe('useFormState narrowing at realistic scale', () => {
       ValueAt<InsuranceQuoteForm, ['agreedToTerms']>
     >().toEqualTypeOf<boolean | undefined>();
   });
+
+  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
+    // `never`. Stepping through a nullable ancestor must instead surface as
+    // `| undefined` in the resolved type — matching read()'s runtime behavior
+    // of returning undefined when a step hits a dead value.
+    type P = Path<InsuranceQuoteForm>;
+    expectTypeOf<['mailingAddress', 'city']>().toMatchTypeOf<P>();
+    expectTypeOf<['coApplicant', 'sharesResidence']>().toMatchTypeOf<P>();
+    expectTypeOf<['pastPolicies', number, 'insurer']>().toMatchTypeOf<P>();
+
+    // Optional section: the section itself resolves exactly (no ancestor is
+    // nullable above it) …
+    expectTypeOf<
+      ValueAt<InsuranceQuoteForm, ['coApplicant']>
+    >().toEqualTypeOf<InsuranceQuoteForm['coApplicant']>();
+    // … and a non-optional leaf below it picks up `| undefined` from the
+    // ancestor.
+    expectTypeOf<
+      ValueAt<InsuranceQuoteForm, ['coApplicant', 'sharesResidence']>
+    >().toEqualTypeOf<boolean | undefined>();
+    expectTypeOf<
+      ValueAt<InsuranceQuoteForm, ['mailingAddress', 'city']>
+    >().toEqualTypeOf<string | undefined>();
+
+    // Nullable list: the list itself resolves exactly (`| null` preserved) …
+    expectTypeOf<
+      ValueAt<InsuranceQuoteForm, ['pastPolicies']>
+    >().toEqualTypeOf<InsuranceQuoteForm['pastPolicies']>();
+    // … while stepping *through* the null surfaces as `| undefined` (not
+    // `| null`) — read() returns undefined for a dead step regardless of
+    // whether the dead value was null or undefined.
+    expectTypeOf<
+      ValueAt<InsuranceQuoteForm, ['pastPolicies', number]>
+    >().toEqualTypeOf<
+      | { insurer: string | undefined; policyNumber: string | undefined; activeUntil: string | null }
+      | undefined
+    >();
+    expectTypeOf<
+      ValueAt<InsuranceQuoteForm, ['pastPolicies', number, 'activeUntil']>
+    >().toEqualTypeOf<string | null | undefined>();
+  });
 });

package/src/forms/useFormState/useFormState.ts

@@ -8,6 +8,7 @@ import type {
   FormErrors,
   FormHelpers,
   FormValuesObject,
+  UnionPolicyCheck,
 } from './types';
 import type { Refine, Validations } from '../validations/types';
 
@@ -15,11 +16,19 @@ import type { Refine, Validations } from '../validations/types';
 // each validator's precise type and Refinement marker survive without any
 // `as const` at the call site. Constraint objects built outside the call
 // still need `as const satisfies Validations<T>` (see src/forms/CLAUDE.md).
+//
+// The `UnionPolicyCheck<T>` intersection enforces the union policy (see
+// "Union policy" in src/forms/CLAUDE.md) at the hook boundary: a form type
+// containing a disallowed union fails here, naming the offending keys,
+// rather than silently producing dead types deep inside a resolved path
+// later. It must stay OUT of the `initialValues` property type — an
+// intersection target there defeats literal widening during inference
+// (`b: 0` infers as `0`, not `number`).
 type Args<T extends FormValuesObject, V extends Validations<T>> = {
   initialValues: T;
   constraints?: V;
   onSubmit?: (values: Refine<T, V>) => void;
-};
+} & UnionPolicyCheck<T>;
 
 export const useFormState = <
   T extends FormValuesObject,