@structuralists/scaffolding 0.7.0 → 0.9.0

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.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 },
@@ -133,6 +145,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 +260,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;
@@ -195,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.
@@ -220,6 +360,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']
         >();
@@ -228,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
@@ -245,4 +399,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.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

@@ -8,18 +8,29 @@ import type {
   FormErrors,
   FormHelpers,
   FormValuesObject,
+  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
 // `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,
@@ -35,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>();
+  });
+});