@modulify/validator 0.2.1 → 0.3.1

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'>
 })
 ```
 

package/docs/en/09-migration.md

@@ -0,0 +1,75 @@
+# Migrating From 0.2.1
+
+[Documentation index](./00-index.md)  
+[Russian translation](../ru/09-migration.md)
+
+This guide describes the unreleased changes after `0.2.1`.
+
+## Object-Level Refinements
+
+`shape(...).refine(...)` is async-first even when its callback returns a plain value.
+Use `shape(...).refine.sync(...)` for rules used by `validate.sync(...)`,
+`matches.sync(...)`, or `shape.check(...)`.
+
+```typescript
+const profile = shape({ password: isString, confirmation: isString })
+  .refine.sync(value => value.password === value.confirmation ? null : {
+    code: 'profile.password.mismatch',
+  })
+```
+
+Use `.refine(...)` with `await validate(...)` for asynchronous rules.
+
+## Staged Assertions
+
+Guard assertions establish a domain; refinements check properties inside it:
+
+```typescript
+validate.sync('name', [isString, hasLength({ min: 3 })])
+validate.sync(4, [isInteger, multipleOf(2)])
+```
+
+Replace standalone refinements such as `validate.sync(value, hasLength(...))`
+with a compatible guard followed by the refinement. Incompatible combinations,
+such as `[isNumber, hasLength(...)]`, are rejected by TypeScript.
+
+Structural validators reset the assertion stage. To refine the outer array after
+checking its elements, use `[each(isString), isDefined, hasLength({ min: 2 })]`.
+
+## Public Type Names
+
+The old names have no compatibility aliases. Update imports and annotations:
+
+| Old name | Current name |
+| --- | --- |
+| `ValidationTuple` | `ValidationResult` |
+| `InferMaybeManyViolations` | `InferViolations` |
+| `ObjectDescriptor` | `ShapeDescriptor` |
+| `InferObjectDescriptor` | `InferShape` |
+| `PartialObjectDescriptor` | `PartialShapeDescriptor` |
+| `MergeObjectDescriptors` | `MergeShapeDescriptors` |
+| `ObjectShapeFieldSelector` | `ShapeFieldSelector` |
+| `ObjectShapeRefinement` / `ObjectShapeAsyncRefinement` | `ShapeRefinement` |
+| `ObjectShapeRefinementSync` / `ObjectShapeSyncRefinement` | `SyncShapeRefinement` |
+| `ObjectShapeRefinementIssue` | `ShapeRefinementViolationInput` |
+| `ObjectShapeRefineMethod` | `ShapeRefineMethod` |
+| `ObjectShapeRefineMethodSync` | `ShapeRefineMethodSync` |
+| `DescribeMaybeMany` | `DescribeConstraints` |
+| `DescribeObjectDescriptor` | `DescribeShapeDescriptor` |
+| `AssertionDescriptorConstraint` | `AssertionConstraintDescriptor` |
+| `ConstraintDescriptorBase` | `BaseConstraintDescriptor` |
+| `ValidatorDescriptor` | `OpaqueValidatorDescriptor` |
+| `GenericObjectShapeRuleDescriptor` | `SyncObjectShapeRuleDescriptor` |
+
+## Optional Predicate Fields
+
+`isShape({ name: [isString, false] })` permits an absent `name`, but rejects
+`{ name: 2 }` and `{ name: undefined }`. To allow explicit `undefined`, use
+`[Or(isString, isUndefined), false]`. Required fields must be present even when
+their predicate accepts `undefined`.
+
+## Package Consumers
+
+The public root and subpath exports support ESM, CommonJS, and strict TypeScript
+with NodeNext or Bundler resolution. Import from package entrypoints rather than
+internal files in `dist/`.

package/docs/ru/00-index.md

@@ -10,6 +10,8 @@
 - [Справка для AI](./07-ai-reference.md) - Краткое описание контракта для AI agents, инструментов и быстрого поиска стабильной семантики библиотеки.
 - [Типы кодов нарушений](./08-violation-code-types.md) - Подробное руководство по `ViolationCodeRegistry`, `ViolationCode`, сохранению literal-кодов в descriptors и внешнему расширению реестра.
 
+- [Миграция с 0.2.1](./09-migration.md) - Breaking changes, переименованные типы и обновлённые контракты валидации.
+
 ## Переводы
 
 - [English](../en/00-index.md)

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

@@ -49,6 +49,8 @@ Shape по-прежнему остаётся validator-ом. Дополните
 - массив constraint-ов, которые выполняются последовательно;
 - другой structural validator вроде `shape(...)`, `each(...)`, `tuple(...)`, `record(...)`, `union(...)` или `discriminatedUnion(...)`.
 
+Для массивов assertions эта последовательность теперь stage-aware: сначала guard assertions задают домен поля, а refinement assertions обязаны быть совместимы с этим доменом.
+
 Поэтому object validation остаётся согласованной с остальной библиотекой:
 
 - field-level checks переиспользуют те же assertions и combinators;
@@ -79,6 +81,11 @@ Runtime behavior:
 - вложенные violations возвращаются на пути поля;
 - unknown keys по умолчанию разрешены.
 
+Type-level behavior:
+
+- `[isString, hasLength({ min: 8 })]` типизируется корректно;
+- `[isNumber, hasLength({ min: 8 })]` TypeScript отсекает ещё до runtime.
+
 ## Неизвестные ключи
 
 У shape есть два режима работы с неизвестными ключами:
@@ -190,13 +197,36 @@ Shapes позволяют выражать cross-field invariants без вне
 
 ### `refine(...)`
 
-`refine(...)` добавляет синхронное object-level rule, которое запускается только после того, как базовая shape уже успешно провалидировалась как объект.
+`refine(...)` добавляет async-first object-level rule, которое запускается только после того, как базовая shape уже успешно провалидировалась как объект.
+
+```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(...)` специально остаётся тонким:
+
+- он принимает sync- и async-callbacks;
+- при успехе возвращает `[]`, `null` или `undefined`;
+- при ошибке возвращает один issue или массив issue;
+- `path` задаётся относительно текущей shape и по умолчанию равен `[]`;
+- `value` необязателен и по умолчанию берётся из значения объекта по этому относительному пути;
+- `code` остаётся machine-readable.
+
+Если нужен явно sync-safe object rule для `validate.sync(...)`, используйте `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(...)` специально остаётся тонким:
-
-- он только sync;
-- при успехе возвращает `[]`, `null` или `undefined`;
-- при ошибке возвращает один issue или массив issue;
-- `path` задаётся относительно текущей shape и по умолчанию равен `[]`;
-- `value` необязателен и по умолчанию берётся из значения объекта по этому относительному пути;
-- `code` остаётся machine-readable.
+`validate.sync(...)`, `matches.sync(...)` и `shape.check(...)` выбрасывают явную ошибку, если встречают async-callback в `refine(...)`.
 
 Сгенерированные violations используют:
 
@@ -243,6 +266,8 @@ const registration = shape({
 
 Позже это попадает в `describe(...)` в массив `rules`.
 
+Rules, зарегистрированные через async-first `refine(...)`, получают в этом массиве признак `async: true`.
+
 ### `fieldsMatch(...)`
 
 `fieldsMatch(...)` — небольшой helper для частого случая с полем подтверждения.

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

@@ -182,7 +182,8 @@ const descriptor = describe(shape({
 Built-in примеры:
 
 - `fieldsMatch(...)` создаёт компактный `fieldsMatch` rule descriptor;
-- `refine(...)` может принимать собственный компактный rule descriptor object.
+- `refine(...)` может принимать собственный компактный rule descriptor object;
+- async-first rules из `refine(...)` помечаются через `async: true`.
 
 Так публичное descriptor tree остаётся стабильным и достаточно сериализуемым для tooling, при этом библиотека не пытается сериализовать произвольные callbacks.
 

package/docs/ru/03-violations.md

@@ -120,7 +120,7 @@ const violation: Violation = {
 `validate(...)` и `validate.sync(...)` возвращают:
 
 ```typescript
-type ValidationTuple<T> =
+type ValidationResult<T> =
   | [ok: true, validated: T, violations: []]
   | [ok: false, validated: unknown, violations: Violation[]]
 ```

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

@@ -69,6 +69,9 @@ Exporter покрывает built-in descriptor set, который уже уч
 
 - `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'` и `format: 'email'`
@@ -202,6 +205,8 @@ Strict режим полезен, когда silent fallback был бы вво
 
 Exporter фиксирует эти границы явно и не пытается гадать.
 
+`isValidDate`, `isError`, `isRegExp` и `isPromiseLike` описывают runtime-значения без точного представления в JSON Schema. Strict mode бросает `JsonSchemaExportError`, а best-effort mode выдаёт узел без ограничений. Числа JSON конечны, поэтому для `isFiniteNumber` дополнительный schema keyword не нужен.
+
 ## Связь с `describe(...)`
 
 `toJsonSchema(...)` находится downstream от `describe(...)`.

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

@@ -19,6 +19,8 @@ Root package экспортирует:
 - `validate`
 - `validate.sync`
 - `matches.sync`
+- `Guard`
+- `Refinement`
 - `meta`
 - `describe`
 - `custom`
@@ -33,8 +35,9 @@ Root package экспортирует:
 
 Root package включает:
 
-- низкоуровневое создание assertions через `assert(...)`
-- built-in assertions вроде `isString`, `isNumber`, `isBoolean`, `isNull`, `isEmail`, `hasLength(...)`, `oneOf(...)`
+- низкоуровневое создание assertions через `assert(...)` и `refine(...)`
+- built-in guard assertions вроде `isString`, `isNumber`, `isBoolean`, `isNull`, `isEmail`, `oneOf(...)`
+- built-in refinement assertions вроде `hasLength(...)`, `hasSize(...)`, `hasPattern(...)`, `startsWith(...)`, `hasValue(...)`, `multipleOf(...)`
 - structural combinators вроде `shape(...)`, `each(...)`, `tuple(...)`, `record(...)`
 - wrappers вроде `optional(...)`, `nullable(...)`, `nullish(...)`
 - branching combinators вроде `union(...)` и `discriminatedUnion(...)`
@@ -42,6 +45,27 @@ Root package включает:
 
 Это основной runtime-facing API surface библиотеки.
 
+Последовательные массивы assertions теперь stage-aware: совместимый кортеж вроде `[isString, hasLength({ min: 3 })]` поддерживается напрямую, а несовместимые комбинации отсекаются типовой системой.
+Refinement assertions в этой модели являются staged-helper'ами, поэтому `validate(...)` и `matches.sync(...)` ожидают их после совместимого guard-а, а не в одиночку.
+
+Структурные validators вроде `each(...)` сбрасывают assertion stage. Перед следующим refinement нужен новый совместимый guard, например `[each(isString), isDefined, hasLength({ min: 2 })]`.
+
+### Встроенные проверки значений
+
+Эти проверки доступны как assertions из root и `./assertions`, а как boolean type guards — из `./predicates`.
+
+| Проверка | Допустимые значения | Код нарушения |
+| --- | --- | --- |
+| `isFiniteNumber` | Числа без `NaN` и бесконечностей | `number.finite` |
+| `isInteger` | Целые числа | `number.integer` |
+| `isSafeInteger` | Целые числа в безопасном диапазоне JavaScript | `number.safe-integer` |
+| `isValidDate` | Экземпляры `Date` с корректным timestamp | `date.valid` |
+| `isError` | Экземпляры `Error`, включая подклассы | `type.error` |
+| `isRegExp` | Экземпляры `RegExp` | `type.regexp` |
+| `isPromiseLike` | Объекты или функции с вызываемым свойством `then` | `type.promise-like` |
+
+`isNumber` по-прежнему принимает бесконечности, а `isDate` — невалидные экземпляры `Date`. Для их отклонения используйте более строгие проверки. `isPromiseLike` проверяет наличие вызываемого `then`, не вызывая его и не проверяя тип результата.
+
 ## Метаданные и интроспекция
 
 Тот же root package также включает:
@@ -67,7 +91,7 @@ Root package также содержит:
 `validate(...)` и `validate.sync(...)` возвращают:
 
 ```typescript
-type ValidationTuple<T> =
+type ValidationResult<T> =
   | [ok: true, validated: T, violations: []]
   | [ok: false, validated: unknown, violations: Violation[]]
 ```
@@ -77,6 +101,8 @@ type ValidationTuple<T> =
 - `ok` показывает, прошла ли валидация;
 - `validated` становится строго типизированным только в успешной ветке;
 - `violations` пуст при успехе и содержит структурированные ошибки при неуспехе.
+- `validate(...)` остаётся основным async-first entrypoint;
+- `validate.sync(...)` явно выбрасывает ошибку при async validators и async object-level rules из `shape(...).refine(...)`.
 
 ## Subpath predicates
 
@@ -97,6 +123,12 @@ Predicates доступны из:
 
 Используйте этот subpath, когда нужны guard-style runtime checks без более высокого validation layer.
 
+В `isShape({ name: [isString, false] })` optional-поле может отсутствовать,
+но присутствующее значение всегда проверяется предикатом. Это относится и к
+явному `undefined`: чтобы разрешить его, используйте `Or(isString, isUndefined)`.
+Shorthand `name: isString` и кортеж `[isString, true]` задают обязательное поле.
+Наличие поля проверяется через `in`, включая свойства из цепочки прототипов.
+
 ## Subpath экспорта JSON Schema
 
 JSON Schema export доступен из:

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

@@ -14,7 +14,7 @@
 Быстрое правило выбора:
 
 - используйте `@modulify/validator/predicates`, когда нужны только runtime checks и type guards;
-- используйте built-in assertions вроде `isString`, `isDefined`, `hasLength(...)`, `oneOf(...)`, когда нужны машиночитаемые ошибки;
+- используйте built-in guard/refinement assertions вроде `isString`, `isDefined`, `hasLength(...)`, `oneOf(...)`, когда нужны машиночитаемые ошибки;
 - используйте combinators вроде `shape(...)`, `each(...)`, `tuple(...)`, `record(...)`, `union(...)`, `discriminatedUnion(...)`, когда валидация становится структурной;
 - используйте `meta(...)` и `describe(...)`, когда другой слой нуждается в стабильных машиночитаемых descriptors;
 - используйте `toJsonSchema(...)` только тогда, когда нужно представление для interoperability или экспорта, а не источник runtime truth.
@@ -44,6 +44,7 @@ const [ok, validated, violations] = validate.sync(input, createUser)
 
 - используйте `.strict()` для request payload, если неизвестные ключи должны отклоняться;
 - держите leaf checks маленькими и хорошо сочетаемыми друг с другом;
+- если используете массив assertions, начинайте его с совместимого guard-а вроде `isString` перед строковыми refinement-проверками вроде `hasLength(...)`;
 - используйте элемент кортежа `validated` внутри успешной ветки;
 - используйте `violations` как структурированные данные для ответов API, логов или сопоставления с UI.
 

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

@@ -43,7 +43,7 @@ Violations — это прежде всего структурированные
 ## Контракт результата валидации
 
 ```typescript
-type ValidationTuple<T> =
+type ValidationResult<T> =
   | [ok: true, validated: T, violations: []]
   | [ok: false, validated: unknown, violations: Violation[]]
 ```
@@ -53,7 +53,8 @@ type ValidationTuple<T> =
 - `validate(...)` сужает `validated` в успешной ветке;
 - `validate(...)` не сужает исходную входную переменную;
 - `matches.sync(...)` — это API для сужения исходной переменной;
-- `violations` при успехе всегда пуст.
+- `violations` при успехе всегда пуст;
+- `validate(...)` — async-first API, а `validate.sync(...)` и `matches.sync(...)` остаются специализированными sync API.
 
 ## Семантика wrappers
 
@@ -90,6 +91,8 @@ type ValidationTuple<T> =
 
 - structural derivations намеренно сбрасывают object-level rules;
 - mode switches намеренно сохраняют object-level rules.
+- `.refine(...)` — async-first и может возвращать promise;
+- `.refine.sync(...)` — явно sync-safe API для object-level rules.
 
 ## Контракт violations
 

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

@@ -58,6 +58,32 @@ const lengthDescriptor = describe(hasLength({ min: 3 }))
 
 Это удобно для адаптеров и tooling-кода, который читает descriptors и хочет ветвиться по коду без ручных cast.
 
+Та же точность теперь протекает и в `validate(...)` для параметризованных built-in assertions.
+
+```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]
+    }
+  })
+}
+```
+
+Для staged-вызовов вроде `[isString, hasLength({ min: 3 })]` невозможные ветки, например `'length.max'` или `'length.range'`, больше не попадают в union violations, а unsupported-type остаётся только на стороне descriptor-а и не протекает в staged-валидацию.
+
 ## Зачем нужен глобальный реестр
 
 Точные literals на отдельных значениях полезны для локальной интроспекции.
@@ -158,7 +184,7 @@ const isAvailableEmail = assert(
 Та же идея работает и для 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'>
 })
 ```
 

package/docs/ru/09-migration.md

@@ -0,0 +1,76 @@
+# Миграция с 0.2.1
+
+[Индекс документации](./00-index.md)  
+[English](../en/09-migration.md)
+
+Здесь описаны ещё не выпущенные изменения после `0.2.1`.
+
+## Правила уровня объекта
+
+`shape(...).refine(...)` стал async-first, даже если callback возвращает обычное
+значение. Для правил, используемых через `validate.sync(...)`, `matches.sync(...)`
+или `shape.check(...)`, нужен `shape(...).refine.sync(...)`.
+
+```typescript
+const profile = shape({ password: isString, confirmation: isString })
+  .refine.sync(value => value.password === value.confirmation ? null : {
+    code: 'profile.password.mismatch',
+  })
+```
+
+Асинхронные правила `.refine(...)` используются с `await validate(...)`.
+
+## Последовательные assertions
+
+Guard задаёт область допустимых значений, refinement проверяет свойства внутри неё:
+
+```typescript
+validate.sync('name', [isString, hasLength({ min: 3 })])
+validate.sync(4, [isInteger, multipleOf(2)])
+```
+
+Замените самостоятельные refinements вроде `validate.sync(value, hasLength(...))`
+на совместимый guard и refinement после него. Несовместимые сочетания, например
+`[isNumber, hasLength(...)]`, отклоняются TypeScript.
+
+Структурные validators сбрасывают assertion stage. Для проверки длины внешнего
+массива после проверки элементов используйте
+`[each(isString), isDefined, hasLength({ min: 2 })]`.
+
+## Имена публичных типов
+
+Совместимых aliases для прежних имён нет. Обновите imports и аннотации:
+
+| Прежнее имя | Новое имя |
+| --- | --- |
+| `ValidationTuple` | `ValidationResult` |
+| `InferMaybeManyViolations` | `InferViolations` |
+| `ObjectDescriptor` | `ShapeDescriptor` |
+| `InferObjectDescriptor` | `InferShape` |
+| `PartialObjectDescriptor` | `PartialShapeDescriptor` |
+| `MergeObjectDescriptors` | `MergeShapeDescriptors` |
+| `ObjectShapeFieldSelector` | `ShapeFieldSelector` |
+| `ObjectShapeRefinement` / `ObjectShapeAsyncRefinement` | `ShapeRefinement` |
+| `ObjectShapeRefinementSync` / `ObjectShapeSyncRefinement` | `SyncShapeRefinement` |
+| `ObjectShapeRefinementIssue` | `ShapeRefinementViolationInput` |
+| `ObjectShapeRefineMethod` | `ShapeRefineMethod` |
+| `ObjectShapeRefineMethodSync` | `ShapeRefineMethodSync` |
+| `DescribeMaybeMany` | `DescribeConstraints` |
+| `DescribeObjectDescriptor` | `DescribeShapeDescriptor` |
+| `AssertionDescriptorConstraint` | `AssertionConstraintDescriptor` |
+| `ConstraintDescriptorBase` | `BaseConstraintDescriptor` |
+| `ValidatorDescriptor` | `OpaqueValidatorDescriptor` |
+| `GenericObjectShapeRuleDescriptor` | `SyncObjectShapeRuleDescriptor` |
+
+## Optional-поля в predicates
+
+`isShape({ name: [isString, false] })` разрешает отсутствие `name`, но отклоняет
+`{ name: 2 }` и `{ name: undefined }`. Для явного `undefined` используйте
+`[Or(isString, isUndefined), false]`. Обязательное поле должно присутствовать,
+даже если его предикат принимает `undefined`.
+
+## Потребители пакета
+
+Публичные root и subpath exports поддерживают ESM, CommonJS и strict TypeScript
+с разрешением модулей NodeNext или Bundler. Используйте package entrypoints,
+а не внутренние файлы `dist/`.