@modulify/validator 0.2.0 → 0.3.0

package/types/index.d.ts

@@ -27,6 +27,9 @@ export type Checker<T, A extends readonly unknown[] = readonly unknown[]> = (val
 /** Extracts a derived value from the original input before a checker runs. */
 export type Extractor<T, V> = (value: T) => V
 
+/** Public stage marker for assertion pipelines. */
+export type AssertionStage = 'guard' | 'refinement'
+
 /** Origin layer that produced a violation. */
 export type ViolationKind = 'assertion' | 'validator' | 'runtime'
 
@@ -63,23 +66,27 @@ type ResolveViolationSubjectArgs<COrT extends string | readonly unknown[], C ext
  * `declare module '@modulify/validator' { interface ViolationCodeRegistry { 'legacy.code': never } }`
  */
 export interface ViolationCodeRegistry {
+  'date.valid': ViolationCodeEntry<'assertion', 'isValidDate', readonly []>;
   'length.exact': ViolationCodeEntry<'assertion', 'hasLength', readonly [exact: number]>;
   'length.max': ViolationCodeEntry<'assertion', 'hasLength', readonly [max: number]>;
   'length.min': ViolationCodeEntry<'assertion', 'hasLength', readonly [min: number]>;
   'length.range': ViolationCodeEntry<'assertion', 'hasLength', readonly [range: readonly [number, number]]>;
   'length.unsupported-type': ViolationCodeEntry<'assertion', 'hasLength', readonly []>;
   'number.exact': ViolationCodeEntry<'assertion', 'hasValue', readonly [exact: number]>;
+  'number.finite': ViolationCodeEntry<'assertion', 'isFiniteNumber', readonly []>;
+  'number.integer': ViolationCodeEntry<'assertion', 'isInteger', readonly []>;
   'number.max': ViolationCodeEntry<'assertion', 'hasValue', readonly [max: number]>;
   'number.min': ViolationCodeEntry<'assertion', 'hasValue', readonly [min: number]>;
   'number.multiple-of': ViolationCodeEntry<'assertion', 'multipleOf', readonly [step: number]>;
   'number.nan': ViolationCodeEntry<'assertion', 'isNaN', readonly []>;
   'number.range': ViolationCodeEntry<'assertion', 'hasValue', readonly [range: readonly [number, number]]>;
+  'number.safe-integer': ViolationCodeEntry<'assertion', 'isSafeInteger', readonly []>;
   'number.unsupported-type': ViolationCodeEntry<'assertion', 'hasValue' | 'multipleOf', readonly []>;
   'runtime.rejection': ViolationCodeEntry<'runtime', 'validate', readonly [reason: unknown]>;
   'shape.fields.mismatch': ViolationCodeEntry<
     'validator',
     'shape',
-    readonly [selectors: readonly [ObjectShapeFieldSelector, ObjectShapeFieldSelector]]
+    readonly [selectors: readonly [ShapeFieldSelector, ShapeFieldSelector]]
   >;
   'shape.unknown-key': ViolationCodeEntry<'validator', 'shape', readonly []>;
   'size.exact': ViolationCodeEntry<'assertion', 'hasSize', readonly [exact: number]>;
@@ -102,12 +109,15 @@ export interface ViolationCodeRegistry {
   'type.blob': ViolationCodeEntry<'assertion', 'isBlob', readonly []>;
   'type.boolean': ViolationCodeEntry<'assertion', 'isBoolean', readonly []>;
   'type.date': ViolationCodeEntry<'assertion', 'isDate', readonly []>;
+  'type.error': ViolationCodeEntry<'assertion', 'isError', readonly []>;
   'type.file': ViolationCodeEntry<'assertion', 'isFile', readonly []>;
   'type.function': ViolationCodeEntry<'assertion', 'isFunction', readonly []>;
   'type.map': ViolationCodeEntry<'assertion', 'isMap', readonly []>;
   'type.null': ViolationCodeEntry<'assertion', 'isNull', readonly []>;
   'type.number': ViolationCodeEntry<'assertion', 'isNumber', readonly []>;
+  'type.promise-like': ViolationCodeEntry<'assertion', 'isPromiseLike', readonly []>;
   'type.record': ViolationCodeEntry<'validator', 'shape' | 'discriminatedUnion' | 'record', readonly []>;
+  'type.regexp': ViolationCodeEntry<'assertion', 'isRegExp', readonly []>;
   'type.set': ViolationCodeEntry<'assertion', 'isSet', readonly []>;
   'type.string': ViolationCodeEntry<'assertion', 'isString', readonly []>;
   'type.symbol': ViolationCodeEntry<'assertion', 'isSymbol', readonly []>;
@@ -225,7 +235,7 @@ export declare const collection: <V extends Violation>(violations: readonly V[])
 export type ConstraintMetadata = Readonly<Record<string, unknown>>
 
 /** Public descriptor entry for additional assertion-level checks. */
-export interface AssertionDescriptorConstraint<
+export interface AssertionConstraintDescriptor<
   C extends string = string,
   A extends readonly unknown[] = readonly unknown[],
 > {
@@ -234,7 +244,7 @@ export interface AssertionDescriptorConstraint<
 }
 
 /** Shared descriptor shape returned by `describe(...)`. */
-export interface ConstraintDescriptorBase<K extends string = string> {
+export interface BaseConstraintDescriptor<K extends string = string> {
   readonly kind: K;
   readonly metadata?: ConstraintMetadata
 }
@@ -243,8 +253,8 @@ export interface ConstraintDescriptorBase<K extends string = string> {
 export interface AssertionDescriptor<
   C extends string = string,
   A extends readonly unknown[] = readonly unknown[],
-  T extends readonly AssertionDescriptorConstraint[] = readonly AssertionDescriptorConstraint[],
-> extends ConstraintDescriptorBase<'assertion'> {
+  T extends readonly AssertionConstraintDescriptor[] = readonly AssertionConstraintDescriptor[],
+> extends BaseConstraintDescriptor<'assertion'> {
   readonly name: string;
   readonly bail: boolean;
   readonly code: C;
@@ -253,17 +263,17 @@ export interface AssertionDescriptor<
 }
 
 /** Generic fallback descriptor for custom validators without structural instrumentation. */
-export type ValidatorDescriptor = ConstraintDescriptorBase<'validator'>
+export type OpaqueValidatorDescriptor = BaseConstraintDescriptor<'validator'>
 
 /** Public extension descriptor for custom validators that expose their own `describe()` contract. */
-export interface CustomConstraintDescriptor<K extends string = string> extends ConstraintDescriptorBase<K> {
+export interface CustomConstraintDescriptor<K extends string = string> extends BaseConstraintDescriptor<K> {
   readonly [key: string]: unknown
 }
 
 /** Descriptor for sequential arrays of constraints used in a single slot. */
 export interface AllOfConstraintDescriptor<
   T extends readonly unknown[] = readonly ConstraintDescriptor[],
-> extends ConstraintDescriptorBase<'allOf'> {
+> extends BaseConstraintDescriptor<'allOf'> {
   readonly constraints: T
 }
 
@@ -271,42 +281,42 @@ export interface AllOfConstraintDescriptor<
 export interface WrapperConstraintDescriptor<
   K extends 'optional' | 'nullable' | 'nullish' = 'optional' | 'nullable' | 'nullish',
   C = ConstraintDescriptor,
-> extends ConstraintDescriptorBase<K> {
+> extends BaseConstraintDescriptor<K> {
   readonly child: C
 }
 
 /** Descriptor for `each(...)`. */
 export interface EachConstraintDescriptor<
   C = ConstraintDescriptor,
-> extends ConstraintDescriptorBase<'each'> {
+> extends BaseConstraintDescriptor<'each'> {
   readonly item: C
 }
 
 /** Descriptor for `tuple(...)`. */
 export interface TupleConstraintDescriptor<
   T extends readonly unknown[] = readonly ConstraintDescriptor[],
-> extends ConstraintDescriptorBase<'tuple'> {
+> extends BaseConstraintDescriptor<'tuple'> {
   readonly items: T
 }
 
 /** Descriptor for `union(...)`. */
 export interface UnionConstraintDescriptor<
   T extends readonly unknown[] = readonly ConstraintDescriptor[],
-> extends ConstraintDescriptorBase<'union'> {
+> extends BaseConstraintDescriptor<'union'> {
   readonly branches: T
 }
 
 /** Descriptor for `record(...)`. */
 export interface RecordConstraintDescriptor<
   C = ConstraintDescriptor,
-> extends ConstraintDescriptorBase<'record'> {
+> extends BaseConstraintDescriptor<'record'> {
   readonly values: C
 }
 
 /** Descriptor for `discriminatedUnion(...)`. */
 export interface DiscriminatedUnionConstraintDescriptor<
   V = Readonly<Record<PropertyKey, ConstraintDescriptor>>,
-> extends ConstraintDescriptorBase<'discriminatedUnion'> {
+> extends BaseConstraintDescriptor<'discriminatedUnion'> {
   readonly key: PropertyKey;
   readonly variants: V
 }
@@ -317,29 +327,37 @@ export interface ObjectShapeRuleDescriptorBase<K extends string = string> {
   readonly metadata?: ConstraintMetadata
 }
 
-/** Generic compact descriptor for sync object-level rules added via `.refine(...)`. */
-export type GenericObjectShapeRuleDescriptor<
+/** Generic compact descriptor for sync-safe object-level rules. */
+export type SyncObjectShapeRuleDescriptor<
   K extends string = 'refine',
 > = ObjectShapeRuleDescriptorBase<K>
 
+/** Compact descriptor for object-level rules registered through the async-first `.refine(...)` API. */
+export interface AsyncObjectShapeRuleDescriptor<
+  K extends string = 'refine',
+> extends ObjectShapeRuleDescriptorBase<K> {
+  readonly async: true
+}
+
 /** Descriptor for the built-in `.fieldsMatch(...)` helper. */
 export interface FieldsMatchObjectShapeRuleDescriptor<
-  Left extends ObjectShapeFieldSelector = ObjectShapeFieldSelector,
-  Right extends ObjectShapeFieldSelector = ObjectShapeFieldSelector,
+  Left extends ShapeFieldSelector = ShapeFieldSelector,
+  Right extends ShapeFieldSelector = ShapeFieldSelector,
 > extends ObjectShapeRuleDescriptorBase<'fieldsMatch'> {
   readonly selectors: readonly [Left, Right]
 }
 
 /** Machine-readable summary of object-level rules registered on a shape. */
 export type ObjectShapeRuleDescriptor =
-  | GenericObjectShapeRuleDescriptor<string>
+  | SyncObjectShapeRuleDescriptor<string>
+  | AsyncObjectShapeRuleDescriptor<string>
   | FieldsMatchObjectShapeRuleDescriptor
 
 /** Descriptor for `shape(...)`. */
 export interface ShapeConstraintDescriptor<
   F = Readonly<Record<PropertyKey, ConstraintDescriptor>>,
   R extends readonly ObjectShapeRuleDescriptor[] = readonly ObjectShapeRuleDescriptor[],
-> extends ConstraintDescriptorBase<'shape'> {
+> extends BaseConstraintDescriptor<'shape'> {
   readonly unknownKeys: UnknownKeysMode;
   readonly fields: F;
   readonly rules: R
@@ -349,7 +367,7 @@ export interface ShapeConstraintDescriptor<
 export type BuiltInConstraintDescriptor =
   | AssertionDescriptor
   | AllOfConstraintDescriptor
-  | ValidatorDescriptor
+  | OpaqueValidatorDescriptor
   | WrapperConstraintDescriptor
   | EachConstraintDescriptor
   | TupleConstraintDescriptor
@@ -368,9 +386,13 @@ export type ConstraintDescriptor = BuiltInConstraintDescriptor | CustomConstrain
  * `type LengthConstraint = AssertionConstraint<string, number, [min: number], 'length.min'>`
  */
 export type AssertionConstraint<
-  T = unknown,
-  V = unknown,
-  A extends readonly unknown[] = readonly unknown[],
+  // Defaults erase heterogeneous checker signatures; concrete tuples retain their types.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  T = any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  V = any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  A extends readonly unknown[] = any[],
   C extends string = string
 > = readonly [
   Extractor<T, V>,
@@ -381,13 +403,13 @@ export type AssertionConstraint<
 
 /** Maps an assertion checker tuple into its public descriptor entry. */
 export type DescribeAssertionConstraint<C extends AssertionConstraint> =
-  C extends AssertionConstraint<unknown, unknown, infer A, infer Code>
-    ? AssertionDescriptorConstraint<Code, A>
+  C extends readonly [unknown, unknown, infer Code extends string, ...infer A]
+    ? AssertionConstraintDescriptor<Code, A>
     : never
 
 /** Maps an assertion checker tuple into the violation subject it can produce. */
 export type AssertionConstraintSubject<C extends AssertionConstraint, N extends string = string> =
-  C extends AssertionConstraint<unknown, unknown, infer A, infer Code>
+  C extends readonly [unknown, unknown, infer Code extends string, ...infer A]
     ? {
         kind: 'assertion';
         name: N;
@@ -403,6 +425,8 @@ export type DescribeAssertionConstraintTuple<T extends readonly AssertionConstra
     : never
 } & ReadonlyArray<DescribeAssertionConstraint<T[number]>>
 
+declare const assertionStageBrand: unique symbol
+
 /**
  * Leaf-level validator that checks a single value and either succeeds with `null`
  * or returns a structured violation.
@@ -415,20 +439,42 @@ export type Assertion<
   Code extends string = string,
   A extends readonly unknown[] = readonly unknown[],
   Name extends string = string,
+  Stage extends AssertionStage = AssertionStage,
 > = ((value: unknown) => MaybePromise<Omit<Violation<
-  {
-    kind: 'assertion';
-    name: Name;
-    code: Code;
-    args: A;
-  } | AssertionConstraintSubject<C[number], Name>
+  Stage extends 'refinement'
+    ? AssertionConstraintSubject<C[number], Name>
+    : {
+        kind: 'assertion';
+        name: Name;
+        code: Code;
+        args: A;
+      } | AssertionConstraintSubject<C[number], Name>
 >, 'path'> | null>) & {
   readonly name: Name;
   readonly bail: boolean;
   readonly constraints: C;
   readonly check: Predicate<T>;
+  readonly [assertionStageBrand]: Stage;
 }
 
+/** Assertion stage that establishes the base domain for subsequent checks. */
+export type Guard<
+  T = unknown,
+  C extends readonly AssertionConstraint[] = readonly AssertionConstraint[],
+  Code extends string = string,
+  A extends readonly unknown[] = readonly unknown[],
+  Name extends string = string,
+> = Assertion<T, C, Code, A, Name, 'guard'>
+
+/** Assertion stage that validates properties inside an already established domain. */
+export type Refinement<
+  T = unknown,
+  C extends readonly AssertionConstraint[] = readonly AssertionConstraint[],
+  Code extends string = string,
+  A extends readonly unknown[] = readonly unknown[],
+  Name extends string = string,
+> = Assertion<T, C, Code, A, Name, 'refinement'>
+
 /**
  * Any reusable validation unit: either a leaf `Assertion` or a composed `Validator`.
  *
@@ -437,14 +483,77 @@ export type Assertion<
  */
 export type Constraint<T = unknown> = Assertion<T> | Validator<T>
 
+type ConstraintSequenceState<
+  Value,
+  Ready extends boolean,
+> = {
+  value: Value;
+  ready: Ready;
+}
+
+type ApplyConstraintStep<
+  State extends ConstraintSequenceState<unknown, boolean>,
+  Step extends Constraint,
+> =
+  [Step] extends [Refinement<infer Input, readonly AssertionConstraint[], string, readonly unknown[], string>]
+    ? State['ready'] extends true
+      ? [State['value']] extends [Input]
+        ? ConstraintSequenceState<State['value'], true>
+        : never
+      : never
+    : Step extends Validator<infer Output>
+      ? ConstraintSequenceState<State['value'] & Output, false>
+      : Step extends Assertion<infer Output>
+        ? ConstraintSequenceState<State['value'] & Output, true>
+        : never
+
+type CompatibleConstraintTupleState<
+  T extends readonly Constraint[],
+  State extends ConstraintSequenceState<unknown, boolean> = ConstraintSequenceState<unknown, false>,
+> =
+  T extends readonly [infer First extends Constraint, ...infer Rest extends readonly Constraint[]]
+    ? ApplyConstraintStep<State, First> extends infer Next
+      ? [Next] extends [never]
+        ? never
+        : Next extends ConstraintSequenceState<unknown, boolean>
+          ? CompatibleConstraintTupleState<Rest, Next>
+          : never
+      : never
+    : State
+
+/** Tuple of sequential constraints with stage-aware assertion compatibility checks. */
+export type CompatibleConstraintTuple<T extends readonly Constraint[] = readonly Constraint[]> =
+  number extends T['length']
+    ? T
+    : T extends readonly [Constraint, ...Constraint[]]
+    ? CompatibleConstraintTupleState<T> extends never
+      ? never
+      : T
+    : T
+
+/** One-or-many constraint input after applying staged assertion compatibility checks. */
+export type CompatibleConstraints<C> =
+  C extends readonly Constraint[]
+    ? CompatibleConstraintTuple<C>
+    : C extends Refinement<unknown, readonly AssertionConstraint[], string, readonly unknown[], string>
+      ? never
+      : C extends Constraint
+      ? C
+      : never
+
 /** Extracts the validated TypeScript type from a single constraint. */
 export type InferConstraint<C> =
-  C extends Assertion<infer T, readonly AssertionConstraint[], string, readonly unknown[], string>
+  C extends Assertion<infer T, readonly AssertionConstraint[], string, readonly unknown[], string, AssertionStage>
     ? T
     : C extends Validator<infer T>
       ? T
       : never
 
+type InferConstraintIntersection<C> =
+  (C extends unknown ? (value: InferConstraint<C>) => void : never) extends (value: infer Output) => void
+    ? Output
+    : never
+
 /**
  * Extracts the validated TypeScript type from one or many constraints.
  *
@@ -460,22 +569,28 @@ export type InferConstraints<C> =
   C extends readonly []
     ? unknown
     : C extends readonly unknown[]
-      ? UnionToIntersection<InferConstraint<C[number]>>
+      ? number extends C['length']
+        ? InferConstraintIntersection<C[number]>
+        : Intersect<{ [K in keyof C]: InferConstraint<C[K]> }>
       : InferConstraint<C>
 
 /** Internal async runner signature used by composed validators. */
-export type Validate = (
+export type Validate = (( 
   value: unknown,
-  constraints: MaybeMany<Constraint>,
+  constraints: CompatibleConstraints<MaybeMany<Constraint>>,
   path?: PropertyKey[]
-) => Promise<Violation[]>
+) => Promise<Violation[]>) & {
+  readonly sync?: false
+}
 
 /** Internal sync runner signature used by composed validators. */
-export type ValidateSync = (
+export type ValidateSync = ((
   value: unknown,
-  constraints: MaybeMany<Constraint>,
+  constraints: CompatibleConstraints<MaybeMany<Constraint>>,
   path?: PropertyKey[]
-) => Violation[]
+) => Violation[]) & {
+  readonly sync: true
+}
 
 /** Internal union of async and sync runner signatures. */
 export type ValidateLike = Validate | ValidateSync
@@ -489,18 +604,18 @@ export type Validation<F extends ValidateLike> = F extends Validate
 export type UnknownKeysMode = 'passthrough' | 'strict'
 
 /** Field selector accepted by shape helpers that can point to the current level or a nested path. */
-export type ObjectShapeFieldSelector = PropertyKey | readonly PropertyKey[]
+export type ShapeFieldSelector = PropertyKey | readonly PropertyKey[]
 
-type ResolveObjectShapeRefinementIssueCode<COrA extends string | readonly unknown[]> = COrA extends string ? COrA : string
-type ResolveObjectShapeRefinementIssueArgs<COrA extends string | readonly unknown[], C extends string> = [COrA] extends [readonly unknown[]]
+type ResolveShapeRefinementViolationCode<COrA extends string | readonly unknown[]> = COrA extends string ? COrA : string
+type ResolveShapeRefinementViolationArgs<COrA extends string | readonly unknown[], C extends string> = [COrA] extends [readonly unknown[]]
   ? COrA
   : ViolationArgs<C>
 
-/** Machine-readable issue returned by an object-level shape refinement. */
-export type ObjectShapeRefinementIssue<
+/** Machine-readable violation input returned by an object-level shape refinement. */
+export type ShapeRefinementViolationInput<
   COrA extends string | readonly unknown[] = string,
-  C extends string = ResolveObjectShapeRefinementIssueCode<COrA>,
-  A extends readonly unknown[] = ResolveObjectShapeRefinementIssueArgs<COrA, C>,
+  C extends string = ResolveShapeRefinementViolationCode<COrA>,
+  A extends readonly unknown[] = ResolveShapeRefinementViolationArgs<COrA, C>,
 > = {
   path?: PropertyKey[];
   code: C;
@@ -512,18 +627,68 @@ export type ObjectShapeRefinementIssue<
   value?: unknown;
 }
 
-/** Sync object-level rule that runs after the base shape has validated successfully. */
-export type ObjectShapeRefinement<
+/** Sync-safe object-level rule that runs after the base shape has validated successfully. */
+export type SyncShapeRefinement<
   T,
-  I extends ObjectShapeRefinementIssue = ObjectShapeRefinementIssue,
+  I extends ShapeRefinementViolationInput = ShapeRefinementViolationInput,
 > = (
   value: T
 ) => MaybeMany<I | null | undefined> | null | undefined
 
+/** Async-first object-level rule that runs after the base shape has validated successfully. */
+export type ShapeRefinement<
+  T,
+  I extends ShapeRefinementViolationInput = ShapeRefinementViolationInput,
+> = (
+  value: T
+) => MaybePromise<MaybeMany<I | null | undefined> | null | undefined>
+
+type AsyncObjectShapeRuleDescriptorOf<RD extends SyncObjectShapeRuleDescriptor<string>> =
+  Omit<RD, 'async'> & AsyncObjectShapeRuleDescriptor<RD['kind']>
+
+/** Explicitly sync-safe callable helper exposed as `shape(...).refine.sync(...)`. */
+export interface ShapeRefineMethodSync<
+  D extends ShapeDescriptor = ShapeDescriptor,
+  M extends UnknownKeysMode = UnknownKeysMode,
+  R extends readonly ObjectShapeRuleDescriptor[] = readonly ObjectShapeRuleDescriptor[],
+  RI extends ShapeRefinementViolationInput = never,
+> {
+  <const I extends ShapeRefinementViolationInput = ShapeRefinementViolationInput>(
+    refinement: SyncShapeRefinement<InferShape<D>, I>
+  ): ObjectShape<D, M, [...R, SyncObjectShapeRuleDescriptor<'refine'>], RI | I>;
+  <
+    const I extends ShapeRefinementViolationInput = ShapeRefinementViolationInput,
+    const RD extends SyncObjectShapeRuleDescriptor<string> = SyncObjectShapeRuleDescriptor<'refine'>
+  >(
+    refinement: SyncShapeRefinement<InferShape<D>, I>,
+    descriptor: RD
+  ): ObjectShape<D, M, [...R, RD], RI | I>;
+}
+
+/** Async-first callable shape helper exposed as `shape(...).refine(...)`. */
+export interface ShapeRefineMethod<
+  D extends ShapeDescriptor = ShapeDescriptor,
+  M extends UnknownKeysMode = UnknownKeysMode,
+  R extends readonly ObjectShapeRuleDescriptor[] = readonly ObjectShapeRuleDescriptor[],
+  RI extends ShapeRefinementViolationInput = never,
+> {
+  <const I extends ShapeRefinementViolationInput = ShapeRefinementViolationInput>(
+    refinement: ShapeRefinement<InferShape<D>, I>
+  ): ObjectShape<D, M, [...R, AsyncObjectShapeRuleDescriptor<'refine'>], RI | I>;
+  <
+    const I extends ShapeRefinementViolationInput = ShapeRefinementViolationInput,
+    const RD extends SyncObjectShapeRuleDescriptor<string> = SyncObjectShapeRuleDescriptor<'refine'>
+  >(
+    refinement: ShapeRefinement<InferShape<D>, I>,
+    descriptor: RD
+  ): ObjectShape<D, M, [...R, AsyncObjectShapeRuleDescriptorOf<RD>], RI | I>;
+  sync: ShapeRefineMethodSync<D, M, R, RI>;
+}
+
 type KnownCodeViolation<C extends KnownViolationCode> = Violation<KnownViolationSubject<C>>
 
-type ShapeRefinementIssueSubject<I extends ObjectShapeRefinementIssue> =
-  I extends ObjectShapeRefinementIssue<string | readonly unknown[], infer C, infer A>
+type ShapeRefinementIssueSubject<I extends ShapeRefinementViolationInput> =
+  I extends ShapeRefinementViolationInput<string | readonly unknown[], infer C, infer A>
     ? C extends KnownViolationCode
       ? {
           kind: 'validator';
@@ -534,55 +699,57 @@ type ShapeRefinementIssueSubject<I extends ObjectShapeRefinementIssue> =
       : ViolationSubject<A, 'validator', C>
     : never
 
-type ShapeRefinementIssueViolation<I extends ObjectShapeRefinementIssue> =
-  I extends ObjectShapeRefinementIssue
+type ShapeRefinementIssueViolation<I extends ShapeRefinementViolationInput> =
+  I extends ShapeRefinementViolationInput
     ? Violation<ShapeRefinementIssueSubject<I>>
     : never
 
-type InferObjectDescriptorViolations<D extends ObjectDescriptor> = {
-  [K in keyof D]: InferMaybeManyViolations<D[K]>
+type InferShapeViolations<D extends ShapeDescriptor> = {
+  [K in keyof D]: InferViolations<D[K]>
 }[keyof D]
 
 /** Maps a single constraint into the union of violations it can produce. */
 export type InferConstraintViolations<C extends Constraint> =
-  C extends Assertion<unknown, infer AC, infer Code, infer Args, infer Name>
+  C extends Guard<unknown, infer AC, infer Code, infer Args, infer Name>
     ? Violation<{
         kind: 'assertion';
         name: Name;
         code: Code;
         args: Args;
       } | AssertionConstraintSubject<AC[number], Name>>
+    : C extends Refinement<unknown, infer AC, string, readonly unknown[], infer Name>
+      ? Violation<AssertionConstraintSubject<AC[number], Name>>
     : C extends ObjectShape<infer D, infer M, readonly ObjectShapeRuleDescriptor[], infer RI>
       ? KnownCodeViolation<'type.record'>
         | (M extends 'strict' ? KnownCodeViolation<'shape.unknown-key'> : never)
-        | InferObjectDescriptorViolations<D>
+        | InferShapeViolations<D>
         | ShapeRefinementIssueViolation<RI>
       : C extends OptionalValidator<infer Child>
-        ? InferMaybeManyViolations<Child>
+        ? InferViolations<Child>
         : C extends NullableValidator<infer Child>
-          ? InferMaybeManyViolations<Child>
+          ? InferViolations<Child>
           : C extends NullishValidator<infer Child>
-            ? InferMaybeManyViolations<Child>
+            ? InferViolations<Child>
             : C extends EachValidator<infer Child>
-              ? KnownCodeViolation<'type.array'> | InferMaybeManyViolations<Child>
+              ? KnownCodeViolation<'type.array'> | InferViolations<Child>
               : C extends TupleValidator<infer Items>
                 ? KnownCodeViolation<'type.array'>
                   | KnownCodeViolation<'tuple.length'>
-                  | InferMaybeManyViolations<Items[number]>
+                  | InferViolations<Items[number]>
                 : C extends UnionValidator<infer Branches>
-                  ? KnownCodeViolation<'union.no-match'> | InferMaybeManyViolations<Branches[number]>
+                  ? KnownCodeViolation<'union.no-match'> | InferViolations<Branches[number]>
                   : C extends DiscriminatedUnionValidator<PropertyKey, infer Variants>
                     ? KnownCodeViolation<'type.record'>
                       | KnownCodeViolation<'union.invalid-discriminator'>
-                      | InferMaybeManyViolations<Variants[keyof Variants]>
+                      | InferViolations<Variants[keyof Variants]>
                     : C extends RecordValidator<infer Values>
-                      ? KnownCodeViolation<'type.record'> | InferMaybeManyViolations<Values>
+                      ? KnownCodeViolation<'type.record'> | InferViolations<Values>
                       : C extends Validator
                         ? Violation
                         : never
 
 /** Maps one-or-many constraints into the union of violations they can produce. */
-export type InferMaybeManyViolations<C extends MaybeMany<Constraint>> =
+export type InferViolations<C extends MaybeMany<Constraint>> =
   C extends readonly []
     ? never
     : C extends readonly Constraint[]
@@ -598,7 +765,7 @@ export type ValidationSuccess<T> = [ok: true, validated: T, violations: []]
 export type ValidationFailure<V extends Violation = Violation> = [ok: false, validated: unknown, violations: V[]]
 
 /**
- * The result tuple returned by `validate(...)` and `validate.sync(...)`.
+ * The result returned by `validate(...)` and `validate.sync(...)`.
  *
  * Example:
  * `const [ok, validated, violations] = await validate(value, schema)`
@@ -606,10 +773,7 @@ export type ValidationFailure<V extends Violation = Violation> = [ok: false, val
  * Example:
  * `if (ok) validated.name.toUpperCase()`
  */
-export type ValidationTuple<T, V extends Violation = Violation> = ValidationSuccess<T> | ValidationFailure<V>
-
-/** Alias for `ValidationTuple<T>`. */
-export type ValidationResult<T, V extends Violation = Violation> = ValidationTuple<T, V>
+export type ValidationResult<T, V extends Violation = Violation> = ValidationSuccess<T> | ValidationFailure<V>
 
 /** Attaches read-only metadata to a constraint without changing validation semantics. */
 export declare const meta: <const C extends Constraint, const M extends ConstraintMetadata>(constraint: C, metadata: M) => C
@@ -644,22 +808,27 @@ export interface DescribedValidator<
 export declare const custom: <const V extends Validator>(validator: V) => V
 
 /** Descriptor that maps object keys to one or many constraints. */
-export type ObjectDescriptor = Record<PropertyKey, MaybeMany<Constraint>>
+export type ShapeDescriptor = Record<PropertyKey, MaybeMany<Constraint>>
+
+/** Shape descriptor with stage-aware compatibility checks applied to every field slot. */
+export type CompatibleShapeDescriptor<D extends ShapeDescriptor> = {
+  [K in keyof D]: CompatibleConstraints<D[K]>
+}
 
-/** Runtime type inferred from an object descriptor. */
-export type InferObjectDescriptor<D extends ObjectDescriptor> = {
+/** Runtime type inferred from a shape descriptor. */
+export type InferShape<D extends ShapeDescriptor> = {
   [K in keyof D]: InferConstraints<D[K]>
 }
 
 /** Descriptor produced by `.partial()` where every field accepts `undefined`. */
-export type PartialObjectDescriptor<D extends ObjectDescriptor> = {
+export type PartialShapeDescriptor<D extends ShapeDescriptor> = {
   [K in keyof D]: Validator<InferConstraints<D[K]> | undefined>
 }
 
 /** Utility type for overriding descriptor keys from left to right. */
-export type MergeObjectDescriptors<
-  Left extends ObjectDescriptor,
-  Right extends ObjectDescriptor,
+export type MergeShapeDescriptors<
+  Left extends ShapeDescriptor,
+  Right extends ShapeDescriptor,
 > = Omit<Left, keyof Right> & Right
 
 /**
@@ -669,67 +838,58 @@ export type MergeObjectDescriptors<
  * `const user = shape({ name: isString }).strict()`
  */
 export interface ObjectShape<
-  D extends ObjectDescriptor = ObjectDescriptor,
+  D extends ShapeDescriptor = ShapeDescriptor,
   M extends UnknownKeysMode = 'passthrough',
   R extends readonly ObjectShapeRuleDescriptor[] = readonly ObjectShapeRuleDescriptor[],
-  RI extends ObjectShapeRefinementIssue = never,
-> extends Validator<InferObjectDescriptor<D>> {
+  RI extends ShapeRefinementViolationInput = never,
+> extends Validator<InferShape<D>> {
   readonly descriptor: D;
   readonly unknownKeys: M;
-  refine<const I extends ObjectShapeRefinementIssue = ObjectShapeRefinementIssue>(
-    refinement: ObjectShapeRefinement<InferObjectDescriptor<D>, I>
-  ): ObjectShape<D, M, [...R, GenericObjectShapeRuleDescriptor<'refine'>], RI | I>;
-  refine<
-    const I extends ObjectShapeRefinementIssue = ObjectShapeRefinementIssue,
-    const RD extends GenericObjectShapeRuleDescriptor<string> = GenericObjectShapeRuleDescriptor<'refine'>
-  >(
-    refinement: ObjectShapeRefinement<InferObjectDescriptor<D>, I>,
-    descriptor: RD
-  ): ObjectShape<D, M, [...R, RD], RI | I>;
-  fieldsMatch<const K extends readonly [ObjectShapeFieldSelector, ObjectShapeFieldSelector]>(
+  readonly refine: ShapeRefineMethod<D, M, R, RI>;
+  fieldsMatch<const K extends readonly [ShapeFieldSelector, ShapeFieldSelector]>(
     keys: K
-  ): ObjectShape<D, M, [...R, FieldsMatchObjectShapeRuleDescriptor<K[0], K[1]>], RI | ObjectShapeRefinementIssue<'shape.fields.mismatch'>>;
+  ): ObjectShape<D, M, [...R, FieldsMatchObjectShapeRuleDescriptor<K[0], K[1]>], RI | ShapeRefinementViolationInput<'shape.fields.mismatch'>>;
   strict(): ObjectShape<D, 'strict', R, RI>;
   passthrough(): ObjectShape<D, 'passthrough', R, RI>;
   pick<const K extends readonly (keyof D)[]>(keys: K): ObjectShape<Pick<D, K[number]>, M, [], never>;
   omit<const K extends readonly (keyof D)[]>(keys: K): ObjectShape<Omit<D, K[number]>, M, [], never>;
-  partial(): ObjectShape<PartialObjectDescriptor<D>, M, [], never>;
-  extend<const E extends ObjectDescriptor>(descriptor: E): ObjectShape<MergeObjectDescriptors<D, E>, M, [], never>;
-  merge<const E extends ObjectDescriptor, OM extends UnknownKeysMode, OR extends readonly ObjectShapeRuleDescriptor[]>(
-    shape: ObjectShape<E, OM, OR, ObjectShapeRefinementIssue>
-  ): ObjectShape<MergeObjectDescriptors<D, E>, M, [], never>;
+  partial(): ObjectShape<PartialShapeDescriptor<D>, M, [], never>;
+  extend<const E extends ShapeDescriptor>(descriptor: E): ObjectShape<MergeShapeDescriptors<D, E>, M, [], never>;
+  merge<const E extends ShapeDescriptor, OM extends UnknownKeysMode, OR extends readonly ObjectShapeRuleDescriptor[]>(
+    shape: ObjectShape<E, OM, OR, ShapeRefinementViolationInput>
+  ): ObjectShape<MergeShapeDescriptors<D, E>, M, [], never>;
 }
 
 /** Helper that maps a single constraint into its public `describe(...)` result. */
 export type DescribeConstraint<C extends Constraint> =
-  C extends Assertion<unknown, infer AC, infer Code, infer Args, string>
+  C extends Assertion<unknown, infer AC, infer Code, infer Args, string, AssertionStage>
     ? AssertionDescriptor<Code, Args, DescribeAssertionConstraintTuple<AC>>
-    : C extends ObjectShape<infer D, infer M, infer R, ObjectShapeRefinementIssue>
-      ? ShapeConstraintDescriptor<DescribeObjectDescriptor<D>, R> & { readonly unknownKeys: M }
+    : C extends ObjectShape<infer D, infer M, infer R, ShapeRefinementViolationInput>
+      ? ShapeConstraintDescriptor<DescribeShapeDescriptor<D>, R> & { readonly unknownKeys: M }
       : C extends OptionalValidator<infer Child>
-        ? WrapperConstraintDescriptor<'optional', DescribeMaybeMany<Child>>
+        ? WrapperConstraintDescriptor<'optional', DescribeConstraints<Child>>
         : C extends NullableValidator<infer Child>
-          ? WrapperConstraintDescriptor<'nullable', DescribeMaybeMany<Child>>
+          ? WrapperConstraintDescriptor<'nullable', DescribeConstraints<Child>>
           : C extends NullishValidator<infer Child>
-            ? WrapperConstraintDescriptor<'nullish', DescribeMaybeMany<Child>>
+            ? WrapperConstraintDescriptor<'nullish', DescribeConstraints<Child>>
             : C extends EachValidator<infer Child>
-              ? EachConstraintDescriptor<DescribeMaybeMany<Child>>
+              ? EachConstraintDescriptor<DescribeConstraints<Child>>
               : C extends TupleValidator<infer Items>
                 ? TupleConstraintDescriptor<DescribeConstraintTuple<Items>>
                 : C extends UnionValidator<infer Branches>
                   ? UnionConstraintDescriptor<DescribeConstraintTuple<Branches>>
                   : C extends DiscriminatedUnionValidator<PropertyKey, infer Variants>
-                    ? DiscriminatedUnionConstraintDescriptor<DescribeObjectDescriptor<Variants>>
+                    ? DiscriminatedUnionConstraintDescriptor<DescribeShapeDescriptor<Variants>>
                     : C extends RecordValidator<infer Values>
-                      ? RecordConstraintDescriptor<DescribeMaybeMany<Values>>
+                      ? RecordConstraintDescriptor<DescribeConstraints<Values>>
                       : C extends DescribedValidator<unknown, infer D>
                         ? D & { readonly metadata?: ConstraintMetadata }
                         : C extends Validator
-                          ? ValidatorDescriptor
+                          ? OpaqueValidatorDescriptor
                           : never
 
 /** Helper that maps a one-or-many constraint slot into its public `describe(...)` result. */
-export type DescribeMaybeMany<C extends MaybeMany<Constraint>> =
+export type DescribeConstraints<C extends MaybeMany<Constraint>> =
   C extends readonly [infer Only]
     ? Only extends Constraint
       ? DescribeConstraint<Only>
@@ -743,14 +903,14 @@ export type DescribeMaybeMany<C extends MaybeMany<Constraint>> =
           : never
 
 /** Helper that maps object descriptors into their `describe(...)` field tree. */
-export type DescribeObjectDescriptor<D extends ObjectDescriptor> = {
-  [K in keyof D]: DescribeMaybeMany<D[K]>
+export type DescribeShapeDescriptor<D extends ShapeDescriptor> = {
+  [K in keyof D]: DescribeConstraints<D[K]>
 }
 
 /** Helper that maps tuples of constraints into tuples of descriptors. */
 export type DescribeConstraintTuple<T extends readonly MaybeMany<Constraint>[]> = {
-  readonly [K in keyof T]: DescribeMaybeMany<T[K]>
-} & ReadonlyArray<DescribeMaybeMany<T[number]>>
+  readonly [K in keyof T]: DescribeConstraints<T[K]>
+} & ReadonlyArray<DescribeConstraints<T[number]>>
 
 declare const optionalValidatorBrand: unique symbol
 declare const nullableValidatorBrand: unique symbol