@reformer/core 11.0.0-beta.1 → 11.0.0-beta.10

package/docs/llms/29-async-preload.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Загрузка формы данными с сервера под M1: (1) **initial values** в `createModel(...)`; (2)
+Загрузка формы данными с сервера: (1) **initial values** в `createModel(...)` / `createForm({ initial })`; (2)
 **`model.set` / `model.patch`** для загрузки/обновления значений; (3) **external React-hook**
 для full-blown async preload (параллельный fetch заявки + справочников, обработка ошибок,
 race-guard через deps). Динамические `componentProps` (опции селектов) обновляются через
@@ -14,7 +14,8 @@ race-guard через deps). Динамические `componentProps` (опци
 ```typescript
 // Модель:
 model.set(value: T): void;            // полная установка значений (load полного DTO). Не меняет initial.
-model.patch(value: Partial<T>): void; // частичное слияние (только переданные ключи). Не меняет initial.
+                                      // DTO без части ключей: поля остаются прежними, в dev — предупреждение.
+model.patch(value: DeepPartial<T>): void; // частичное слияние (только переданные ключи, на любой глубине групп; undefined — «не трогать»). Не меняет initial.
 model.reset(): void;                  // вернуть к initial-снимку
 model.captureInitial(): void;         // сделать текущие значения новым initial-снимком
 
@@ -30,28 +31,38 @@ Initial values задаются в `createModel(initial)`; `reset()` возвр
 ### Initial values в модели
 
 ```typescript
-import { createModel, createForm } from '@reformer/core';
-import { Input, Select } from '@reformer/ui-kit';
+import { createModel, createFormFromModel, type FormSchemaNode } from '@reformer/core';
+import { Input, SelectAsync, CheckboxWithLabel } from '@reformer/ui-kit';
 
-type ProfileForm = { username: string; language: 'ru' | 'en'; marketing: boolean };
+interface ProfileForm {
+  username: string;
+  language: 'ru' | 'en';
+  marketing: boolean;
+}
 
 const model = createModel<ProfileForm>({ username: '', language: 'ru', marketing: true });
-const schema = {
-  username: { value: model.$.username, component: Input, componentProps: { label: 'Username' } },
-  language: {
-    value: model.$.language,
-    component: Select,
-    componentProps: {
-      label: 'Язык',
-      options: [
-        { value: 'ru', label: 'Русский' },
-        { value: 'en', label: 'English' },
-      ],
+const schema: FormSchemaNode = {
+  children: [
+    { model: model.$.username, component: Input, componentProps: { label: 'Username' } },
+    {
+      model: model.$.language,
+      component: SelectAsync,
+      componentProps: {
+        label: 'Язык',
+        options: [
+          { value: 'ru', label: 'Русский' },
+          { value: 'en', label: 'English' },
+        ],
+      },
+    },
+    {
+      model: model.$.marketing,
+      component: CheckboxWithLabel,
+      componentProps: { label: 'Рассылка' },
     },
-  },
-  marketing: { value: model.$.marketing, component: Input, componentProps: { type: 'checkbox' } },
+  ],
 };
-const form = createForm({ model, schema });
+const form = createFormFromModel({ model, schema });
 // model.get() === { username: '', language: 'ru', marketing: true }
 // после правок: model.reset() возвращает к этим значениям
 ```
@@ -60,13 +71,13 @@ const form = createForm({ model, schema });
 
 ```tsx
 import { useEffect, useState } from 'react';
-import type { FormModel, FormProxy } from '@reformer/core';
+import type { FormModel, FormGroup } from '@reformer/core';
 
 interface LoadingState { isLoading: boolean; error: string | null }
 
 export function useLoadCreditApplication(
   model: FormModel<CreditApplicationForm>,
-  form: FormProxy<CreditApplicationForm>,
+  form: FormGroup<CreditApplicationForm>,
   applicationId: string | null
 ): LoadingState {
   const [state, setState] = useState<LoadingState>({ isLoading: !!applicationId, error: null });
@@ -102,7 +113,7 @@ export function useLoadCreditApplication(
     })();
 
     return () => { cancelled = true; };
-  }, [applicationId]); // model/form стабильны (создан через useMemo)
+  }, [applicationId]); // model/form стабильны (сборка через useFormBundle)
 
   return state;
 }
@@ -137,16 +148,13 @@ export const addressBehavior = defineFormBehavior<AddressForm>(({ model, form })
 ```typescript
 // ❌ model/form пересоздаются на каждый рендер → preload запускается каждый раз
 function MyForm() {
-  const model = createModel<T>(initial);   // КАЖДЫЙ рендер!
-  const form = createForm({ model, schema });
+  const bundle = createForm<T>({ initial, schema }); // КАЖДЫЙ рендер!
 }
 
-// ✅ Стабильные ссылки через useMemo
+// ✅ Стабильная сборка: useFormBundle вызывает фабрику ровно один раз (useMemo React вправе
+// сбросить и пересобрать форму, потеряв введённое)
 function MyForm() {
-  const { model, form } = useMemo(() => {
-    const m = createModel<T>(initial);
-    return { model: m, form: createForm({ model: m, schema: buildSchema(m) }) };
-  }, []);
+  const { model, form } = useFormBundle(() => createForm<T>({ initial, schema }));
 }
 ```
 
@@ -174,8 +182,10 @@ useEffect(() => {
 
 ## Troubleshooting
 
-**Q: После `set`/`patch` не показываются ошибки.**
-A: `set`/`patch` не запускают валидацию. После загрузки вызови `await validateModel(model, schema)` (внешний раннер из `@reformer/core/validation`).
+**Q: После `set`/`patch` не показываются замечания.**
+A: `set`/`patch` не запускают валидацию (кроме живой стратегии `change`). После загрузки вызови
+`await bundle.validate()`; без сборки — `await validateModel(model, schema)` из
+`@reformer/core/validation`.
 
 **Q: Опции в `<Select>` не появляются после `updateComponentProps`.**
 A: (1) Оберни вызов в `queueMicrotask`; (2) убедись, что компонент подписан через `useFormControl`;

package/docs/llms/30-type-safety-recipes.md

@@ -1,12 +1,14 @@
 ## 30. TYPE-SAFETY RECIPES
 
-Идиоматичные паттерны, которые держат сгенерированный код без `any` и `as`-кастов под M1.
+Идиоматичные паттерны, которые держат сгенерированный код без `any` и `as`-кастов.
 
 ### Recipe 1 — Imports (root cause prevention)
 
-- Модель/форма/хуки/типы/**примитивы behaviors** — из `@reformer/core`.
+- Модель/форма/типы — из `@reformer/core`; хуки — из `@reformer/core/react`; примитивы над
+  сигналами — из `@reformer/core/model`.
 - Схема валидации (операторы + раннер `validateModel`) — из `@reformer/core/validation`.
 - Чистые фабрики валидаторов — из `@reformer/core/validators`.
+- Словарь текстов замечаний (`defineIssueMessages`) — из `@reformer/core/i18n`.
 - Декларативный DSL (`defineFormBehavior` + операторы) — из `@reformer/core/behaviors`.
 
 ```typescript
@@ -14,13 +16,13 @@ import {
   createModel,
   createForm,
   type FormModel,
-  type FormProxy,
-  type ModelSignals,
+  type FormGroup,
+  type FormSchemaNode,
 } from '@reformer/core';
+import { useFormBundle, useFormControl } from '@reformer/core/react';
 import {
-  defineValidationSchema,
+  defineValidation,
   validate,
-  cross,
   validateModel,
   type Rule,
 } from '@reformer/core/validation';
@@ -28,65 +30,96 @@ import { required, min, max, email } from '@reformer/core/validators';
 import { defineFormBehavior, compute, enableWhen, onChange } from '@reformer/core/behaviors';
 ```
 
-> **watchField — из `@reformer/core`** (примитив), НЕ из `@reformer/core/behaviors` (там `onChange`).
+> **watchField — из `@reformer/core/model`** (примитив), НЕ из `@reformer/core/behaviors` (там `onChange`)
+> и не из корня `@reformer/core`.
 
-### Recipe 2 — Form-shape types as `type`, not `interface`
+### Recipe 2 — Form-shape types: `interface` или `type`
 
-`Record<string, FormValue>` требует index signature. У `interface` её нет неявно; у `type` —
-структурно. Объявляй через `type`-alias всё, что попадает в `FormProxy<T>`/`ArrayNode<T>`:
-корневую форму, вложенные группы, типы элементов массива.
+Оба варианта работают одинаково. Ограничения `Record<string, …>` у `createModel<T>`,
+`createForm<T>`, `FormGroup<T>` и `FormArray<T>` нет (`createModel` и `createForm` требуют только
+`T extends object`). Вид ноды поля `FormFields<T>` выводит по виду значения: обычный объект —
+`FormGroup`, массив объектов — `FormArray`, остальное (примитив, массив примитивов, `Date`, `File`)
+— `FormControl`. Index signature здесь не участвует, поэтому `interface` распознаётся так же, как
+`type`. Эталонная форма объявлена через `interface`.
 
 ```typescript
-export type PropertyItem = {
+export interface PropertyItem {
   type: 'apartment' | 'house' | 'car';
   description: string;
   estimatedValue: number;
-};
+}
 
-export type CreditApplicationForm = {
+export interface CreditApplication {
   loanAmount: number | null;
-  properties: PropertyItem[];
+  properties: PropertyItem[]; // form.properties — FormArray<PropertyItem>
+  address: Address; // form.address — FormGroup<Address>
+  tags: string[]; // form.tags — FormControl<string[]>
   // ...
-};
+}
+
+// вычисляемые поля — отдельным типом; форма — пересечение
+export interface CreditApplicationDerived {
+  monthlyPayment: number;
+}
+export type CreditApplicationForm = CreditApplication & CreditApplicationDerived;
 ```
 
-### Recipe 3 — Схема привязана к сигналам модели
+Оговорка только для своих обобщённых хелперов: `interface` не присваивается
+`Record<string, unknown>` (неявной index signature у него нет). Ограничение пиши через
+`T extends object`:
 
-`value` поля — это сигнал модели (`model.$.field`), а не литерал. Тип поля выводится из сигнала.
-Layout-схема БЕЗ валидаторов — правила живут в отдельной validation-схеме.
+```typescript
+// ❌ interface-форму этот хелпер не примет
+function snapshot<T extends Record<string, unknown>>(form: FormGroup<T>): T { return form.getValue(); }
+
+// ✅
+function snapshot<T extends object>(form: FormGroup<T>): T { return form.getValue(); }
+```
+
+### Recipe 3 — Схема привязана к ручкам модели
+
+Привязка узла — ручка модели (`model: model.$.field`), а не литерал. Тип узла `FormSchemaNode`
+закрыт: вид узла (поле, массив под-форм, подформа) сверяется с тем, чем является привязка, а
+опечатка в ключе не компилируется. Правил в схеме нет — они живут в отдельной схеме валидации.
 
 ```typescript
-const model = createModel<CreditApplicationForm>(initial);
-
-const schema = {
-  loanAmount: { value: model.$.loanAmount, component: Input },
-  // вложенная группа — builder, принимающий ModelSignals<Sub>
-  personalData: personalDataNodes(model.$.personalData),
-  // массив — { array, item }
-  properties: { array: model.properties, item: propertyItem },
-};
+const creditSchema = (model: FormModel<CreditApplicationForm>): FormSchemaNode => ({
+  children: [
+    { model: model.$.loanAmount, component: InputNumber },
+    // вложенная группа — подформа: билдер получает под-модель FormModel<PersonalData>
+    { model: model.$.personalData, part: personalData },
+    // массив под-форм — { model, item }: билдер получает под-модель строки
+    { model: model.$.properties, component: FieldArray, item: propertyRow },
+  ],
+});
+
+// правила — отдельно; тип правила сверяется с типом поля
+const LOAN_AMOUNT_RULES: Rule<number | null>[] = [required(), min(50000)];
 
-// правила — отдельно; типы полей выводятся из сигналов
-const validation = defineValidationSchema<CreditApplicationForm>(({ model }) => {
-  validate(model.$.loanAmount, [required(), min(50000)]);
+const validation = defineValidation<CreditApplicationForm>(({ model }) => {
+  validate(model.$.loanAmount, LOAN_AMOUNT_RULES);
 });
 ```
 
-### Recipe 4 — Cross-field валидаторы: `cross` над типизированным снапшотом
+### Recipe 4 — Cross-field валидаторы: `cross` над типизированным снимком
 
-Правило — обычная функция `(f: Root) => ValidationError | null` над снапшотом `model.get()`.
-Соседние поля читаются без `as`; ошибка вешается на поле-носитель `sig`:
+Правило — обычная функция `(snapshot: T) => ValidationIssue | null`. Оператор `cross` берётся из
+аргумента схемы: тип снимка выведен из схемы, соседние поля читаются без `as`, ошибка вешается на
+поле-носитель:
 
 ```typescript
-import type { ValidationError } from '@reformer/core';
+import type { ValidationIssue } from '@reformer/core';
 
-const initialPaymentVsProperty = (f: CreditApplicationForm): ValidationError | null =>
-  f.initialPayment && f.propertyValue && f.initialPayment > f.propertyValue
-    ? { code: 'tooHigh', message: 'Взнос не может превышать стоимость' }
+const initialPaymentVsProperty = (application: CreditApplicationForm): ValidationIssue | null =>
+  application.initialPayment &&
+  application.propertyValue &&
+  application.initialPayment > application.propertyValue
+    ? { code: 'initialPaymentTooHigh' } // текст — в словаре формы (defineIssueMessages)
     : null;
 
-// внутри defineValidationSchema<CreditApplicationForm>(({ model }) => { ... }):
-cross(model.$.initialPayment, initialPaymentVsProperty);
+const loanRules = defineValidation<CreditApplicationForm>(({ model, cross }) => {
+  cross(model.$.initialPayment, initialPaymentVsProperty);
+});
 ```
 
 ### Recipe 5 — `compute` читает модель напрямую (без аннотаций)
@@ -112,27 +145,32 @@ compute(model.$.fullName, () =>
 пустые значения — guard `if (value != null)` не нужен.
 
 ```typescript
-export type CreditForm = {
-  loanAmount: number | null;   // min(model.$.loanAmount, 50000) — ок
+export interface CreditForm {
+  loanAmount: number | null;   // validate(model.$.loanAmount, [min(50000)]) — ок
   loanPurpose: string | null;  // minLength — ок
   birthDate: string | null;    // minAge — ок
-};
+}
 ```
 
 ### Recipe 7 — Нода поля для кастомных компонентов
 
-`useFormControl(control)` типизируется по `FieldNode<T>`. В props компонента используй `FieldNode<T>`:
+`useFormControl(control)` типизируется по `FormControl<T>`. В props компонента используй `FormControl<T>`:
 
 ```typescript
-import type { FieldNode } from '@reformer/core';
+import type { FormControl } from '@reformer/core';
+import { useFormControl } from '@reformer/core/react';
 
-type MyFieldProps<T> = { control: FieldNode<T> };
+type MyFieldProps<T> = { control: FormControl<T> };
 function MyField<T>({ control }: MyFieldProps<T>) {
-  const { value, errors, disabled } = useFormControl(control);
+  const { value, issues, disabled } = useFormControl(control);
   // ...
 }
 ```
 
+Для массива под-форм — `FormArray<Item>` (`useFormControl` отдаёт `ArrayControlState`), для группы —
+`FormGroup<Group>`. Вид неизвестной ноды сужают гарды `isFormControl` / `isFormGroup` /
+`isFormArray`.
+
 ### Recipe 8 — Вынос правил в именованные функции
 
 Field-правила — именованные `Rule<T>`, validation-схема остаётся плоской:
@@ -143,17 +181,33 @@ import type { Rule } from '@reformer/core/validation';
 const validateAdultAge: Rule<string | null> = (value) => {
   if (!value) return null;
   const age = new Date().getFullYear() - new Date(value).getFullYear();
-  return age < 18 ? { code: 'tooYoung', message: 'Минимум 18 лет' } : null;
+  return age < 18 ? { code: 'birthDate.adult', params: { minAge: 18 } } : null;
 };
 
-// внутри defineValidationSchema<MyForm>(({ model }) => { ... }):
+// внутри defineValidation<MyForm>(({ model }) => { ... }):
 validate(model.$.birthDate, [validateAdultAge]);
 ```
 
+### Recipe 9 — Результаты уровня формы — сужение по `status`
+
+`bundle.validate()`, `bundle.submission.submit(handler)` и `flow.next()` отвечают
+дискриминированными объединениями: поле результата доступно после проверки `status`, без `as`.
+
+```typescript
+const outcome = await bundle.submission.submit(api.send); // SubmitResult<Awaited<ReturnType<typeof api.send>>>
+if (outcome.status === 'submitted') use(outcome.result);
+else if (outcome.status === 'failed') report(outcome.error);
+else showIssues(outcome.validation.issues); // 'invalid' | 'error' | 'cancelled'
+
+const transition = await bundle.flow!.next(); // FlowTransition
+if (transition.status === 'stayed') console.log(transition.reason); // 'invalid' | 'error' | …
+```
+
 ### Anti-patterns to avoid
 
 - `import { computeFrom } from '@reformer/core/behaviors'` для примитива, вызываемого вне
-  `defineFormBehavior` → примитив живёт в `@reformer/core` (возвращает cleanup).
-- `interface MyForm { ... }` для form-shape → см. Recipe 2.
+  `defineFormBehavior` → примитив живёт в `@reformer/core/model` (возвращает cleanup).
+- `T extends Record<string, unknown>` в своих хелперах формы → `T extends object` (Recipe 2).
 - `as`-касты значений полей внутри `compute` → читай `model.field` напрямую (Recipe 5).
 - строковые пути / `(form) => ...` в behaviors → это удалённый API, используй сигналы (`model.$.x`).
+- `node instanceof …` → ноды — интерфейсы; гарды `isFormControl` / `isFormGroup` / `isFormArray`.

package/docs/llms/31-async-validator-debounce.md

@@ -1,62 +1,110 @@
 ## 31. ASYNC VALIDATOR
 
 Для проверок типа «уникальность email», «валидация ИНН через API», «проверка адреса» —
-async-правило это `AsyncRule<T>` = `(value, { signal }) => Promise<ValidationError | null>`.
+async-правило это `AsyncRule<T>` = `(value, { signal }) => Promise<ValidationIssue | null>`.
 Оно регистрируется оператором `validateAsync(sig, [asyncRules])` внутри схемы валидации
-(`@reformer/core/validation`) и исполняется внешним раннером `validateModel` (async-правила
-прогоняются параллельно через `Promise.all`, раннер их дожидается).
+(`@reformer/core/validation`) и исполняется прогоном — уровнем формы (`bundle.validate()`,
+`bundle.submission.submit(handler)`, `flow.next()`) либо раннером `validateModel`. Async-правила
+прогоняются параллельно через `Promise.all`, прогон их дожидается.
 
-Слои разделены: layout (`createForm`-схема / JSON) НЕ несёт валидаторов — правила живут в
-отдельной функции-схеме `defineValidationSchema<T>(({ model }) => …)`.
+Слои разделены: схема формы (билдер `createForm` / JSON) правил НЕ несёт — они живут в
+отдельной функции-схеме `defineValidation<T>(({ model }) => …)`.
+
+**Сбой async-правила блокирует.** Если правило отклонило промис (сеть, исключение), прогон получает
+статус `error`, а поле — замечание `{ code: 'ruleFailed' }` («Не удалось проверить поле. Повторите
+попытку»): форму, которую не удалось проверить, прогон валидной не считает.
 
 ```ts
-import { createModel } from '@reformer/core';
+import { createForm, createModel } from '@reformer/core';
 import {
   validate,
   validateAsync,
-  defineValidationSchema,
+  defineValidation,
   validateModel,
   type AsyncRule,
 } from '@reformer/core/validation';
 import { required, email } from '@reformer/core/validators';
 
-// async-правило: (value, { signal }) => Promise<ValidationError | null>.
+// async-правило: (value, { signal }) => Promise<ValidationIssue | null>.
 // `signal` — AbortSignal устаревшего прогона: прокинь его в fetch, чтобы отменить in-flight.
 const checkEmailUnique: AsyncRule<string> = async (value, { signal }) => {
   if (!value) return null; // пусто = валидно (sync `required` отдельно)
-  try {
-    const res = await fetch(`/api/check-email?email=${encodeURIComponent(value)}`, { signal });
-    const { available } = (await res.json()) as { available: boolean };
-    return available ? null : { code: 'email-taken', message: 'Email уже зарегистрирован' };
-  } catch {
-    return null; // сетевой сбой/отмена НЕ блокирует submit — возвращаем null, а не ошибку
-  }
+  // try/catch не нужен: отклонённый запрос раннер запишет сбоем правила (статус `error`,
+  // ошибка `ruleFailed` на поле), а отмену устаревшего прогона отличит сам по `signal`.
+  const res = await fetch(`/api/check-email?email=${encodeURIComponent(value)}`, { signal });
+  const { available } = (await res.json()) as { available: boolean };
+  return available ? null : { code: 'email.taken' }; // текст кода — в словаре формы
 };
 
-const model = createModel<{ email: string }>({ email: '' });
-
 // Схема — обычная функция над моделью; sync и async — разными операторами на одном сигнале.
-const schema = defineValidationSchema<{ email: string }>(({ model }) => {
+const schema = defineValidation<{ email: string }>(({ model }) => {
   validate(model.$.email, [required(), email()]); // sync-фабрики
   validateAsync(model.$.email, [checkEmailUnique]); // async-правило
 });
 
-// Прогон по требованию (submit / шаг):
+// В сборке — прогон уровнем формы:
+const signup = createForm<{ email: string }>({ initial: { email: '' }, validation: schema });
+const outcome = await signup.submission.submit(api.signup); // обработчик — только при valid
+
+// Без сборки — раннер:
+const model = createModel<{ email: string }>({ email: '' });
 const ok = await validateModel(model, schema); // Promise<boolean>
 ```
 
 ### Как это исполняется
 
-1. `validateModel(model, schema)` открывает ambient-окно и **синхронно** прогоняет схему:
+1. Прогон (`bundle.validate()` / `validateModel(model, schema)`) открывает ambient-окно и
+   **синхронно** прогоняет схему:
    `validate`/`validateAsync`/`cross` регистрируют правила своих полей.
 2. Sync-правила выполняются сразу; async-правила из `validateAsync` собираются и после закрытия
    ambient-окна дожидаются параллельно (`Promise.all`) с прокинутым `AbortSignal`.
-3. Ошибки роутятся в ноды формы (`getNodeForSignal(sig).setErrors(...)`), UI подсвечивает поле;
-   поля, ставшие валидными, гасятся (`setErrors([])`).
-4. Возвращает `Promise<boolean>` — `true`, если нет блокирующих ошибок (`severity:'warning'`
-   не блокирует). Устаревший (отменённый) прогон возвращает `false` — ему нельзя доверять для submit.
+3. Пока async-правила поля не завершились, его нода в состоянии `pending`
+   (`form.email.pending.value`, `useFormControl(form.email).pending`).
+4. Замечания разносятся по нодам формы, UI подсвечивает поле; поля, ставшие валидными, гасятся.
+   Отклонённое правило даёт на своём поле замечание `ruleFailed`.
+5. Итог — `ValidationResult` со статусом (`bundle.validate()`, `runValidation`) либо `boolean`
+   (`validateModel`: `true` только при `valid`; `severity:'warning'` не блокирует). Замечания
+   (`invalid`), сбой правила (`error`) и устаревший отменённый прогон (`cancelled`) — не `valid`.
 
-Синхронного варианта у нового контракта нет: раннер один — `validateModel`, и он всегда `async`.
+Синхронного варианта у контракта нет: прогон всегда `async`.
+
+### Результат прогона и сбой правила
+
+Когда нужно отличить «в форме замечания» от «проверить не удалось», бери полный результат —
+`bundle.validate()` / `bundle.validateStep(id)` сборки, а для отправки — статус `SubmitResult`:
+
+```ts
+const outcome = await bundle.submission.submit(api.send);
+if (outcome.status === 'error') {
+  // outcome.validation.failures: [{ handle, error }] — какое правило и почему не вернуло результат
+  showToast('Не удалось проверить форму. Повторите попытку');
+}
+```
+
+Без сборки — `runValidation(model, schema)` (только сбор) и `applyValidationResult`:
+
+```ts
+import { applyValidationResult, runValidation } from '@reformer/core/validation';
+
+const result = await runValidation(model, schema); // только сбор: ни замечаний, ни pending на нодах
+if (result.status === 'cancelled') return; // вытеснен более новым прогоном — не разносится
+applyValidationResult(result, { touch: true }); // замечания (и ruleFailed) — на поля
+if (result.status === 'valid') await send(model.get());
+```
+
+Если сбой сети НЕ должен блокировать отправку (проверка необязательна), перехвати его в самом
+правиле и верни `null` — это явное решение автора правила, а не поведение по умолчанию:
+
+```ts
+const softCheck: AsyncRule<string> = async (value, { signal }) => {
+  try {
+    const res = await fetch(`/api/check?value=${encodeURIComponent(value)}`, { signal });
+    return (await res.json()).ok ? null : { code: 'rejected' };
+  } catch {
+    return null; // осознанно: недоступность сервиса проверку не проваливает
+  }
+};
+```
 
 ### Sync и async — два оператора
 
@@ -72,37 +120,32 @@ validateAsync(model.$.inn, [checkInnInRegistry]); // обращение к API
 
 ### UI integration
 
-`validateModel(...)` возвращает `Promise<boolean>` — индикатор проверки держи вокруг этого
-`await`. Раннер схемы **не** выставляет per-field `pending` на ноде (он роутит только ошибки через
-`setErrors`), поэтому спиннер async-валидации — это собственный флаг (обычно form-level, как
-`ui.pending` в submit-флоу, или локальный state компонента):
+Пока идут async-правила поля, раннер держит его ноду в `pending` — индикатор проверки поля
+берётся из состояния ноды, свой флаг не нужен:
 
 ```tsx
-const [checking, setChecking] = useState(false);
+const { issues, pending, shouldShowIssues } = useFormControl(form.email);
+const message = useIssueMessage(formMessages); // @reformer/core/react
 
-const runValidation = async (): Promise<boolean> => {
-  setChecking(true);
-  try {
-    return await validateModel(model, schema);
-  } finally {
-    setChecking(false);
-  }
-};
-
-return checking ? <Spinner /> : errors.length ? <Error errors={errors} /> : null;
+return pending ? <Spinner /> : shouldShowIssues ? <Error text={message(issues[0])} /> : null;
 ```
 
+Индикатор прогона всей формы — сигнал `bundle.validating` сборки (`createForm`): он истинен,
+пока идёт полный прогон либо прогон шага; `bundle.submission.submitting` — пока работает обработчик
+отправки.
+
 ### Debounce и отмена
 
-- **Отмена устаревших — раннером, бесплатно.** Быстрый повторный `validateModel(model, schema)`
-  той же пары `(model, schema)` отменяет предыдущий in-flight прогон через `AbortController`;
-  его `AbortSignal` прокинут в `validateAsync`-правила, поэтому `fetch(url, { signal })` рвётся
-  сам. Ручной debounce для КОРРЕКТНОСТИ не нужен — держи схему стабильным `const`
-  (`defineValidationSchema`), иначе отмена не сматчит прогоны по идентичности.
-- Валидация запускается on-demand (submit / шаг / через `revalidateWhen`), а не на каждый
-  keystroke — отдельный `debounce` в правиле обычно не нужен.
-- Если нужно дебаунсить дорогой async-валидатор относительно частых изменений — триггерь прогон
-  из поведения через `onChange`, который даёт debounce из коробки:
+- **Отмена устаревших — бесплатно.** Быстрый повторный прогон той же пары `(model, schema)`
+  отменяет предыдущий in-flight прогон через `AbortController`; его `AbortSignal` прокинут в
+  `validateAsync`-правила, поэтому `fetch(url, { signal })` рвётся сам. Ручной debounce для
+  КОРРЕКТНОСТИ не нужен — держи схему стабильным `const` (`defineValidation`), иначе отмена не
+  сматчит прогоны по идентичности.
+- Валидация запускается on-demand (submit / шаг / через `revalidateWhen`) либо живой стратегией
+  сборки — `validation: { rules, strategy: 'change', debounce: 300 }` (см. `33-validation-strategy.md`):
+  у живой фазы debounce встроен.
+- Если нужно дебаунсить дорогой async-валидатор относительно частых изменений одного поля — триггерь
+  прогон из поведения через `onChange`, который даёт debounce из коробки:
 
   ```ts
   import { defineFormBehavior, onChange } from '@reformer/core/behaviors';
@@ -114,16 +157,16 @@ return checking ? <Spinner /> : errors.length ? <Error errors={errors} /> : null
   ```
 
   Либо оборачивай в свой debounce колбэк `revalidateWhen([...], () => void validateModel(...))`.
-- **Async cross-field** — инлайн `validateAsync`-правило, замыкающее `model` и читающее снапшот
-  соседей `model.get()` до первого `await` (у `AsyncRule` нет `root`, только `value` + `signal`;
-  `cross(...)` — синхронный):
+- **Async cross-field** — инлайн `validateAsync`-правило, замыкающее `model` и читающее снимок
+  соседей `model.get()` до первого `await` (`AsyncRule` получает только `value` и `signal`;
+  `cross` — синхронный):
 
   ```ts
   validateAsync(model.$.email, [
     async (email, { signal }) => {
       const { username } = model.get(); // снапшот соседних полей до await
       const res = await fetch(`/api/check?email=${email}&user=${username}`, { signal });
-      return (await res.json()).ok ? null : { code: 'conflict', message: 'Пара занята' };
+      return (await res.json()).ok ? null : { code: 'conflict' };
     },
   ]);
   ```