@modulify/validator 0.2.0 → 0.3.0

package/dist/types/json-schema.d.cts

@@ -0,0 +1,75 @@
+import type {
+  Constraint,
+  ConstraintDescriptor,
+  MaybeMany,
+} from './index.cjs'
+
+/** JSON Schema primitive `type` values used by `toJsonSchema(...)`. */
+export type JsonSchemaTypeName =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  | 'null'
+
+/** Minimal JSON Schema object shape emitted by the built-in exporter. */
+export interface JsonSchema {
+  readonly $schema?: string;
+  readonly $id?: string;
+  readonly $comment?: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly format?: string;
+  readonly default?: unknown;
+  readonly examples?: readonly unknown[];
+  readonly deprecated?: boolean;
+  readonly readOnly?: boolean;
+  readonly writeOnly?: boolean;
+  readonly type?: JsonSchemaTypeName | readonly JsonSchemaTypeName[];
+  readonly const?: unknown;
+  readonly enum?: readonly unknown[];
+  readonly allOf?: readonly JsonSchema[];
+  readonly anyOf?: readonly JsonSchema[];
+  readonly oneOf?: readonly JsonSchema[];
+  readonly properties?: Readonly<Record<string, JsonSchema>>;
+  readonly required?: readonly string[];
+  readonly additionalProperties?: boolean | JsonSchema;
+  readonly items?: JsonSchema;
+  readonly prefixItems?: readonly JsonSchema[];
+  readonly minItems?: number;
+  readonly maxItems?: number;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  readonly pattern?: string;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly multipleOf?: number;
+}
+
+/** Controls how `toJsonSchema(...)` handles constraints that cannot be represented faithfully. */
+export type JsonSchemaExportMode = 'bestEffort' | 'strict'
+
+/** Options for the JSON Schema exporter. */
+export interface ToJsonSchemaOptions {
+  readonly mode?: JsonSchemaExportMode
+}
+
+/** Error thrown by `toJsonSchema(...)` in strict mode when a node cannot be exported faithfully. */
+export declare class JsonSchemaExportError extends Error {
+  constructor(message: string, options: {
+    descriptor: ConstraintDescriptor
+    reason: string
+    path?: readonly PropertyKey[]
+  })
+  readonly descriptor: ConstraintDescriptor
+  readonly reason: string
+  readonly path: readonly PropertyKey[]
+}
+
+/** Derives a JSON Schema object from one or many public constraint descriptors. */
+export declare const toJsonSchema: <const C extends MaybeMany<Constraint>>(
+  constraints: C,
+  options?: ToJsonSchemaOptions
+) => JsonSchema

package/dist/types/json-schema.d.mts

@@ -0,0 +1,75 @@
+import type {
+  Constraint,
+  ConstraintDescriptor,
+  MaybeMany,
+} from './index.mjs'
+
+/** JSON Schema primitive `type` values used by `toJsonSchema(...)`. */
+export type JsonSchemaTypeName =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  | 'null'
+
+/** Minimal JSON Schema object shape emitted by the built-in exporter. */
+export interface JsonSchema {
+  readonly $schema?: string;
+  readonly $id?: string;
+  readonly $comment?: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly format?: string;
+  readonly default?: unknown;
+  readonly examples?: readonly unknown[];
+  readonly deprecated?: boolean;
+  readonly readOnly?: boolean;
+  readonly writeOnly?: boolean;
+  readonly type?: JsonSchemaTypeName | readonly JsonSchemaTypeName[];
+  readonly const?: unknown;
+  readonly enum?: readonly unknown[];
+  readonly allOf?: readonly JsonSchema[];
+  readonly anyOf?: readonly JsonSchema[];
+  readonly oneOf?: readonly JsonSchema[];
+  readonly properties?: Readonly<Record<string, JsonSchema>>;
+  readonly required?: readonly string[];
+  readonly additionalProperties?: boolean | JsonSchema;
+  readonly items?: JsonSchema;
+  readonly prefixItems?: readonly JsonSchema[];
+  readonly minItems?: number;
+  readonly maxItems?: number;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  readonly pattern?: string;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly multipleOf?: number;
+}
+
+/** Controls how `toJsonSchema(...)` handles constraints that cannot be represented faithfully. */
+export type JsonSchemaExportMode = 'bestEffort' | 'strict'
+
+/** Options for the JSON Schema exporter. */
+export interface ToJsonSchemaOptions {
+  readonly mode?: JsonSchemaExportMode
+}
+
+/** Error thrown by `toJsonSchema(...)` in strict mode when a node cannot be exported faithfully. */
+export declare class JsonSchemaExportError extends Error {
+  constructor(message: string, options: {
+    descriptor: ConstraintDescriptor
+    reason: string
+    path?: readonly PropertyKey[]
+  })
+  readonly descriptor: ConstraintDescriptor
+  readonly reason: string
+  readonly path: readonly PropertyKey[]
+}
+
+/** Derives a JSON Schema object from one or many public constraint descriptors. */
+export declare const toJsonSchema: <const C extends MaybeMany<Constraint>>(
+  constraints: C,
+  options?: ToJsonSchemaOptions
+) => JsonSchema

package/dist/types/json-schema.d.ts

@@ -0,0 +1,75 @@
+import type {
+  Constraint,
+  ConstraintDescriptor,
+  MaybeMany,
+} from './index.js'
+
+/** JSON Schema primitive `type` values used by `toJsonSchema(...)`. */
+export type JsonSchemaTypeName =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  | 'null'
+
+/** Minimal JSON Schema object shape emitted by the built-in exporter. */
+export interface JsonSchema {
+  readonly $schema?: string;
+  readonly $id?: string;
+  readonly $comment?: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly format?: string;
+  readonly default?: unknown;
+  readonly examples?: readonly unknown[];
+  readonly deprecated?: boolean;
+  readonly readOnly?: boolean;
+  readonly writeOnly?: boolean;
+  readonly type?: JsonSchemaTypeName | readonly JsonSchemaTypeName[];
+  readonly const?: unknown;
+  readonly enum?: readonly unknown[];
+  readonly allOf?: readonly JsonSchema[];
+  readonly anyOf?: readonly JsonSchema[];
+  readonly oneOf?: readonly JsonSchema[];
+  readonly properties?: Readonly<Record<string, JsonSchema>>;
+  readonly required?: readonly string[];
+  readonly additionalProperties?: boolean | JsonSchema;
+  readonly items?: JsonSchema;
+  readonly prefixItems?: readonly JsonSchema[];
+  readonly minItems?: number;
+  readonly maxItems?: number;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  readonly pattern?: string;
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly multipleOf?: number;
+}
+
+/** Controls how `toJsonSchema(...)` handles constraints that cannot be represented faithfully. */
+export type JsonSchemaExportMode = 'bestEffort' | 'strict'
+
+/** Options for the JSON Schema exporter. */
+export interface ToJsonSchemaOptions {
+  readonly mode?: JsonSchemaExportMode
+}
+
+/** Error thrown by `toJsonSchema(...)` in strict mode when a node cannot be exported faithfully. */
+export declare class JsonSchemaExportError extends Error {
+  constructor(message: string, options: {
+    descriptor: ConstraintDescriptor
+    reason: string
+    path?: readonly PropertyKey[]
+  })
+  readonly descriptor: ConstraintDescriptor
+  readonly reason: string
+  readonly path: readonly PropertyKey[]
+}
+
+/** Derives a JSON Schema object from one or many public constraint descriptors. */
+export declare const toJsonSchema: <const C extends MaybeMany<Constraint>>(
+  constraints: C,
+  options?: ToJsonSchemaOptions
+) => JsonSchema

package/dist/violations.d.cts

@@ -0,0 +1,29 @@
+import { Violation } from './types/index.cjs';
+type ViolationPath = readonly PropertyKey[];
+type ViolationTreeState<V extends Violation = Violation> = {
+    readonly path: ViolationPath;
+    readonly self: V[];
+    readonly subtree: V[];
+    readonly children: Map<PropertyKey, ViolationTreeState<V>>;
+};
+declare class TreeNode<V extends Violation = Violation> {
+    readonly path: readonly PropertyKey[];
+    readonly self: ViolationCollection<V>;
+    readonly subtree: ViolationCollection<V>;
+    readonly children: ReadonlyMap<PropertyKey, TreeNode<V>>;
+    constructor(state: ViolationTreeState<V>);
+    at(path: readonly PropertyKey[]): TreeNode<V> | undefined;
+}
+export declare class ViolationCollection<V extends Violation = Violation> implements Iterable<V> {
+    readonly size: number;
+    private readonly violations;
+    constructor(violations: readonly V[]);
+    [Symbol.iterator](): Iterator<V>;
+    forEach(callback: (violation: V, index: number, collection: ViolationCollection<V>) => void): void;
+    map<T>(callback: (violation: V, index: number, collection: ViolationCollection<V>) => T): T[];
+    at(path: readonly PropertyKey[]): ViolationCollection<V>;
+    tree(): TreeNode<V>;
+}
+export type ViolationTreeNode<V extends Violation = Violation> = TreeNode<V>;
+export declare const collection: <V extends Violation>(violations: readonly V[]) => ViolationCollection<V>;
+export {};

package/dist/violations.d.mts

@@ -0,0 +1,29 @@
+import { Violation } from './types/index.mjs';
+type ViolationPath = readonly PropertyKey[];
+type ViolationTreeState<V extends Violation = Violation> = {
+    readonly path: ViolationPath;
+    readonly self: V[];
+    readonly subtree: V[];
+    readonly children: Map<PropertyKey, ViolationTreeState<V>>;
+};
+declare class TreeNode<V extends Violation = Violation> {
+    readonly path: readonly PropertyKey[];
+    readonly self: ViolationCollection<V>;
+    readonly subtree: ViolationCollection<V>;
+    readonly children: ReadonlyMap<PropertyKey, TreeNode<V>>;
+    constructor(state: ViolationTreeState<V>);
+    at(path: readonly PropertyKey[]): TreeNode<V> | undefined;
+}
+export declare class ViolationCollection<V extends Violation = Violation> implements Iterable<V> {
+    readonly size: number;
+    private readonly violations;
+    constructor(violations: readonly V[]);
+    [Symbol.iterator](): Iterator<V>;
+    forEach(callback: (violation: V, index: number, collection: ViolationCollection<V>) => void): void;
+    map<T>(callback: (violation: V, index: number, collection: ViolationCollection<V>) => T): T[];
+    at(path: readonly PropertyKey[]): ViolationCollection<V>;
+    tree(): TreeNode<V>;
+}
+export type ViolationTreeNode<V extends Violation = Violation> = TreeNode<V>;
+export declare const collection: <V extends Violation>(violations: readonly V[]) => ViolationCollection<V>;
+export {};

package/dist/violations.d.ts

@@ -1,4 +1,4 @@
-import { Violation } from '../types';
+import { Violation } from './types/index.js';
 type ViolationPath = readonly PropertyKey[];
 type ViolationTreeState<V extends Violation = Violation> = {
     readonly path: ViolationPath;

package/docs/RELEASING.md

@@ -0,0 +1,66 @@
+# Releasing @modulify/validator
+
+Use Node.js 22.14+ or 24+ and the Yarn version pinned in `package.json`.
+Install dependencies with `yarn install --immutable`.
+
+The repository uses `@modulify/conventional-release` to calculate the version,
+update `package.json` and `CHANGELOG.md`, and create a release commit with an
+annotated `v<version>` tag. npm publication and GitHub Releases belong to CI.
+
+Preview a release without changing files, commits, or tags:
+
+```sh
+yarn release:dry
+yarn release:dry --prerelease rc
+yarn release:dry --release-as minor
+```
+
+Automatic version recommendations below 1.0 follow pre-major semantics:
+breaking changes advance the minor version; features and fixes advance the patch.
+Explicit `--release-as major` produces 1.0.0. Release configuration lives in
+`release.config.mjs`; dependencies are installed before releasing, so the version
+bump does not rerun installation or update the lockfile.
+
+## GitHub Actions
+
+Start the `Release` workflow manually:
+
+- `release`: `auto`, `patch`, `minor`, or `major`;
+- `prerelease`: `none`, `alpha`, `beta`, or `rc`;
+- `npm_tag`: `auto` selects `latest` for stable releases and the prerelease channel
+  otherwise; an explicit dist-tag can override it.
+
+Stable releases run only from `main`. Prereleases may run from other branches,
+but cannot publish to `latest`. Releases are serialized across branches.
+
+CI runs lint, strict type checks, runtime and type tests, and packed consumer
+checks before creating the release. It atomically pushes the release commit and
+its tag. A separate job checks out that exact tag, repeats the checks, builds the
+package, and publishes through npm OIDC. A GitHub Release is created after npm
+publication succeeds; prereleases are marked accordingly.
+
+If publication or GitHub Release creation fails after the tag was pushed, use
+GitHub Actions **Re-run failed jobs** on the original run. Publication checks the
+registry for the exact version and skips a version already published. Registry
+lookup errors stop the job. Starting a new workflow run prepares another release.
+
+## npm Trusted Publisher
+
+The package already has this trusted publisher configured (verified 2026-09-26):
+
+| Field | Value |
+| --- | --- |
+| Provider | GitHub Actions |
+| Organization | `modulify` |
+| Repository | `validator` |
+| Workflow filename | `release.yml` |
+| Allowed actions | `npm publish`, `npm stage publish` |
+
+Keep the workflow filename aligned with this package-level configuration.
+The publishing job uses a GitHub-hosted runner, Node.js 24, npm 11.5.1 or newer,
+and `id-token: write`. No `NPM_TOKEN` or `NODE_AUTH_TOKEN` secret is used for
+publication. npm generates provenance automatically for this public package
+and repository. See [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/).
+
+A local authenticated npm session is separate from CI OIDC. Release previews
+and repository-local versioning do not require npm authentication.

package/docs/en/00-index.md

@@ -9,6 +9,8 @@
 - [AI Reference](./07-ai-reference.md) - Compact contract summary for AI agents, tooling, and quick lookup of stable library semantics.
 - [Violation Code Types](./08-violation-code-types.md) - Detailed guide to `ViolationCodeRegistry`, `ViolationCode`, literal code preservation in descriptors, and external registry augmentation.
 
+- [Migration From 0.2.1](./09-migration.md) - Breaking changes, renamed types, and updated validation contracts.
+
 ## Translations
 
 - [Russian](../ru/00-index.md)

package/docs/en/01-shape-api.md

@@ -49,6 +49,8 @@ Each field in the descriptor may contain:
 - an array of constraints that run sequentially;
 - another structural validator such as `shape(...)`, `each(...)`, `tuple(...)`, `record(...)`, `union(...)`, or `discriminatedUnion(...)`.
 
+For assertion arrays, sequencing is stage-aware: guard assertions establish the field domain first, and refinement assertions must be compatible with that domain.
+
 That means object validation stays aligned with the rest of the library:
 
 - field-level checks reuse the same assertions and combinators;
@@ -79,6 +81,11 @@ Runtime behavior:
 - nested violations are reported on the field path;
 - unknown keys are allowed by default.
 
+Type-level behavior:
+
+- `[isString, hasLength({ min: 8 })]` is valid;
+- `[isNumber, hasLength({ min: 8 })]` is rejected by TypeScript before runtime.
+
 ## Unknown Keys
 
 Shapes have two unknown-key modes:
@@ -190,13 +197,36 @@ Shapes can express cross-field invariants without introducing a second schema la
 
 ### `refine(...)`
 
-`refine(...)` adds a synchronous object-level rule that runs only after the base shape has already validated successfully as an object.
+`refine(...)` adds an async-first object-level rule that runs only after the base shape has already validated successfully as an object.
+
+```typescript
+const registration = shape({
+  email: isString,
+}).refine(async value => {
+  const taken = await users.has(value.email)
+
+  return taken
+    ? [{ path: ['email'], code: 'user.email.taken' }]
+    : []
+})
+```
+
+`refine(...)` is intentionally thin:
+
+- it accepts sync or async callbacks;
+- it returns `[]`, `null`, or `undefined` when the rule passes;
+- it returns one issue or an array of issues when it fails;
+- `path` is relative to the current shape and defaults to `[]`;
+- `value` is optional and defaults to the object value at that relative path;
+- `code` stays machine-readable.
+
+If you need an explicitly sync-safe object rule for `validate.sync(...)`, use `refine.sync(...)`:
 
 ```typescript
 const registration = shape({
   password: isString,
   confirmPassword: isString,
-}).refine(value => {
+}).refine.sync(value => {
   return value.password === value.confirmPassword
     ? []
     : [{
@@ -207,14 +237,7 @@ const registration = shape({
 })
 ```
 
-`refine(...)` is intentionally thin:
-
-- it is sync-only;
-- it returns `[]`, `null`, or `undefined` when the rule passes;
-- it returns one issue or an array of issues when it fails;
-- `path` is relative to the current shape and defaults to `[]`;
-- `value` is optional and defaults to the object value at that relative path;
-- `code` stays machine-readable.
+`validate.sync(...)`, `matches.sync(...)`, and `shape.check(...)` throw explicitly if they encounter an async `refine(...)` callback.
 
 Produced violations use:
 
@@ -243,6 +266,8 @@ const registration = shape({
 
 This shows up later in `describe(...)` under the shape `rules` array.
 
+Rules registered through async-first `refine(...)` are marked with `async: true` in that descriptor array.
+
 ### `fieldsMatch(...)`
 
 `fieldsMatch(...)` is a small helper for the common confirmation-field case.

package/docs/en/02-metadata-and-introspection.md

@@ -182,7 +182,8 @@ Instead, shapes keep lightweight rule descriptors in `rules`.
 Built-in examples:
 
 - `fieldsMatch(...)` produces a compact `fieldsMatch` rule descriptor;
-- `refine(...)` can accept a custom compact rule descriptor object.
+- `refine(...)` can accept a custom compact rule descriptor object;
+- async-first `refine(...)` rules are marked with `async: true`.
 
 This keeps the public descriptor tree stable and serializable enough for tooling, while avoiding the impossible task of serializing arbitrary callbacks.
 

package/docs/en/03-violations.md

@@ -120,7 +120,7 @@ This is one of the reasons the library can stay adapter-friendly without stringi
 `validate(...)` and `validate.sync(...)` return:
 
 ```typescript
-type ValidationTuple<T> =
+type ValidationResult<T> =
   | [ok: true, validated: T, violations: []]
   | [ok: false, validated: unknown, violations: Violation[]]
 ```

package/docs/en/04-json-schema-export.md

@@ -69,6 +69,9 @@ Supported practical mappings include:
 
 - `isString` -> `type: 'string'`
 - `isNumber` -> `type: 'number'`
+- `isFiniteNumber` -> `type: 'number'`
+- `isInteger` -> `type: 'integer'`
+- `isSafeInteger` -> `type: 'integer'`, `minimum: Number.MIN_SAFE_INTEGER`, `maximum: Number.MAX_SAFE_INTEGER`
 - `isBoolean` -> `type: 'boolean'`
 - `isNull` -> `type: 'null'`
 - `isEmail` -> `type: 'string'` plus `format: 'email'`
@@ -202,6 +205,8 @@ Important examples:
 
 The exporter keeps these boundaries explicit instead of guessing.
 
+`isValidDate`, `isError`, `isRegExp`, and `isPromiseLike` describe runtime values without a faithful JSON Schema representation. Strict mode throws `JsonSchemaExportError`; best-effort mode emits an unconstrained node. JSON numeric values are finite, so `isFiniteNumber` needs no additional schema keyword.
+
 ## Relationship To `describe(...)`
 
 `toJsonSchema(...)` is downstream from `describe(...)`.

package/docs/en/05-public-api.md

@@ -19,6 +19,8 @@ The root package exports:
 - `validate`
 - `validate.sync`
 - `matches.sync`
+- `Guard`
+- `Refinement`
 - `meta`
 - `describe`
 - `custom`
@@ -33,8 +35,9 @@ Use the root package when you need the main validation API, composed validators,
 
 The root package includes:
 
-- low-level assertion construction through `assert(...)`
-- built-in assertions such as `isString`, `isNumber`, `isBoolean`, `isNull`, `isEmail`, `hasLength(...)`, `oneOf(...)`
+- low-level assertion construction through `assert(...)` and `refine(...)`
+- built-in guard assertions such as `isString`, `isNumber`, `isBoolean`, `isNull`, `isEmail`, `oneOf(...)`
+- built-in refinement assertions such as `hasLength(...)`, `hasSize(...)`, `hasPattern(...)`, `startsWith(...)`, `hasValue(...)`, `multipleOf(...)`
 - structural combinators such as `shape(...)`, `each(...)`, `tuple(...)`, `record(...)`
 - wrapper combinators such as `optional(...)`, `nullable(...)`, `nullish(...)`
 - branching combinators such as `union(...)` and `discriminatedUnion(...)`
@@ -42,6 +45,27 @@ The root package includes:
 
 This is the main runtime-facing API surface of the library.
 
+Sequential assertion arrays are stage-aware: a compatible tuple such as `[isString, hasLength({ min: 3 })]` is supported directly, while incompatible combinations are rejected by the type system.
+Refinement assertions are staged helpers, so `validate(...)` and `matches.sync(...)` expect them to appear after a compatible guard instead of being passed on their own.
+
+Structural validators such as `each(...)` reset the assertion stage. Use a new compatible guard before subsequent refinements, for example `[each(isString), isDefined, hasLength({ min: 2 })]`.
+
+### Built-in value guards
+
+These checks are available as assertions from the root and `./assertions`, and as boolean type guards from `./predicates`.
+
+| Check | Accepted values | Violation code |
+| --- | --- | --- |
+| `isFiniteNumber` | Numbers excluding `NaN` and infinities | `number.finite` |
+| `isInteger` | Integer numbers | `number.integer` |
+| `isSafeInteger` | Integers within JavaScript's safe integer bounds | `number.safe-integer` |
+| `isValidDate` | `Date` instances with a valid timestamp | `date.valid` |
+| `isError` | `Error` instances, including subclasses | `type.error` |
+| `isRegExp` | `RegExp` instances | `type.regexp` |
+| `isPromiseLike` | Objects or functions with a callable `then` property | `type.promise-like` |
+
+`isNumber` still accepts infinities; `isDate` still accepts invalid `Date` instances. Use the stricter checks when those values must be rejected. `isPromiseLike` checks the presence of a callable `then`, without executing it or inspecting the resolved value.
+
 ## Metadata And Introspection
 
 The same root package also includes:
@@ -67,7 +91,7 @@ These are the main utilities for post-processing machine-readable validation fai
 `validate(...)` and `validate.sync(...)` return:
 
 ```typescript
-type ValidationTuple<T> =
+type ValidationResult<T> =
   | [ok: true, validated: T, violations: []]
   | [ok: false, validated: unknown, violations: Violation[]]
 ```
@@ -77,6 +101,8 @@ Practical meaning:
 - `ok` tells whether validation succeeded;
 - `validated` becomes strongly typed only in the success branch;
 - `violations` is empty on success and contains structured failures on error.
+- `validate(...)` is the default async-first entrypoint;
+- `validate.sync(...)` throws explicitly when it encounters async validators or async object-level `shape(...).refine(...)` rules.
 
 ## Predicates Subpath
 
@@ -97,6 +123,12 @@ This subpath contains reusable runtime/type-guard helpers and predicate combinat
 
 Use this subpath when you want guard-style runtime checks without pulling in the higher-level validation layer.
 
+In `isShape({ name: [isString, false] })`, an optional field may be absent,
+but a present value is always checked by its predicate. This includes explicit
+`undefined`: use `Or(isString, isUndefined)` to allow it.
+The shorthand `name: isString` and the tuple `[isString, true]` define required fields.
+Field presence is checked with `in`, including properties in the prototype chain.
+
 ## JSON Schema Export Subpath
 
 JSON Schema export is available from:

package/docs/en/06-common-recipes.md

@@ -14,7 +14,7 @@ It is intentionally recipe-oriented. Use it when you already understand the proj
 Use this quick rule of thumb:
 
 - use `@modulify/validator/predicates` when you only need runtime checks and type guards;
-- use built-in assertions such as `isString`, `isDefined`, `hasLength(...)`, `oneOf(...)` when you want machine-readable failures;
+- use built-in guard/refinement assertions such as `isString`, `isDefined`, `hasLength(...)`, `oneOf(...)` when you want machine-readable failures;
 - use combinators such as `shape(...)`, `each(...)`, `tuple(...)`, `record(...)`, `union(...)`, `discriminatedUnion(...)` when validation becomes structural;
 - use `meta(...)` and `describe(...)` when another layer needs stable machine-readable descriptors;
 - use `toJsonSchema(...)` only when you need an interoperability/export view, not as the source of runtime truth.
@@ -44,6 +44,7 @@ Practical pattern:
 
 - use `.strict()` for request payloads when unknown keys should be rejected;
 - keep leaf checks small and composable;
+- when you use an assertion array, start with a compatible guard such as `isString` before string refinements like `hasLength(...)`;
 - use the `validated` tuple item inside the success branch;
 - use `violations` as structured data for API responses, logs, or UI mapping.
 

package/docs/en/07-ai-reference.md

@@ -43,7 +43,7 @@ Use `@modulify/validator/json-schema` for:
 ## Validation Result Contract
 
 ```typescript
-type ValidationTuple<T> =
+type ValidationResult<T> =
   | [ok: true, validated: T, violations: []]
   | [ok: false, validated: unknown, violations: Violation[]]
 ```
@@ -53,7 +53,8 @@ Important consequences:
 - `validate(...)` narrows the `validated` tuple item in the success branch;
 - `validate(...)` does not narrow the original input variable;
 - `matches.sync(...)` is the API that narrows the original variable;
-- `violations` is always empty on success.
+- `violations` is always empty on success;
+- `validate(...)` is async-first, while `validate.sync(...)` and `matches.sync(...)` are specialized sync APIs.
 
 ## Wrapper Semantics
 
@@ -90,6 +91,8 @@ Important rule:
 
 - structural derivations intentionally drop object-level rules;
 - mode switches intentionally keep object-level rules.
+- `.refine(...)` is async-first and may return a promise;
+- `.refine.sync(...)` is the explicitly sync-safe object-level rule API.
 
 ## Violations Contract
 

package/docs/en/08-violation-code-types.md

@@ -58,6 +58,32 @@ In TypeScript this means:
 
 This is useful when adapters inspect descriptors and want code-aware branching without hand-written casts.
 
+The same precision now flows into `validate(...)` for parameterized built-ins.
+
+```typescript
+import {
+  collection,
+  hasLength,
+  isString,
+  validate,
+} from '@modulify/validator'
+
+const [ok, , violations] = validate.sync('ab', [isString, hasLength({ min: 3 })])
+
+if (!ok) {
+  collection(violations).map(violation => {
+    switch (violation.violates.code) {
+      case 'type.string':
+        return violation.violates.name
+      case 'length.min':
+        return violation.violates.args[0]
+    }
+  })
+}
+```
+
+For staged calls like `[isString, hasLength({ min: 3 })]`, impossible branches such as `'length.max'` or `'length.range'` are no longer carried into the violation union, and the unsupported-type branch stays on the descriptor side instead of leaking into staged validation.
+
 ## What The Global Registry Solves
 
 Exact literals on individual values are good for local introspection.
@@ -158,7 +184,7 @@ This part does not depend on the global union extraction. The literal is preserv
 The same idea applies to object-level refinement issues.
 
 ```typescript
-import type { ObjectShapeRefinementIssue } from '@modulify/validator'
+import type { ShapeRefinementViolationInput } from '@modulify/validator'
 import {
   isEmail,
   isString,
@@ -180,7 +206,7 @@ const signUpForm = shape({
     path: ['confirmation', 'password'],
     code: 'profile.password.mismatch',
     args: [],
-  }] satisfies ObjectShapeRefinementIssue<'profile.password.mismatch'>
+  }] satisfies ShapeRefinementViolationInput<'profile.password.mismatch'>
 })
 ```