letopis 1.4.2 → 3.0.0

package/dist/typed.d.ts

@@ -1,35 +1,171 @@
 /**
- * Типы цепочек по моделям (план, этап 3, п. 9): `connect({ models })` даёт типы шагов по именам и
- * алиасам классов, типы строк ответа и фильтров. Допустимость переходов проверяется во время
- * выполнения, как в 0.21. Модель описана структурно (ModelLike), чтобы основная точка входа не
- * зависела от Zod: модели letopis/model ей соответствуют.
+ * Строгие типы цепочек по моделям (план 2.0, этап 4, п. 1; типы шагов, строк и фильтров — план 1.0, этап 3, п. 9).
+ * `connect({ models })` — модели letopis/model — или `connect<Models>()` — объявления `letopis types` (generateTypes,
+ * sync.ts) — дают TypedDb без индексных сигнатур:
+ * - шаг от корня — только известный класс или алиас: моделей подключения и системных (встроенный набор SystemModels);
+ * - переходы цепочки выводятся из концов, как в resolveHop (lib/src/sql.ts): от класса C — роли его семейства (C и
+ *   потомков) и классы, связанные с семейством C концом в любую сторону (роль, имя которой совпало с именем класса,
+ *   во время выполнения — шаг класса, так же и здесь);
+ * - слоты — только роли класса C: `set(id | строка | цепочка)`, `add` и `remove` — у множественного конца, `unset` —
+ *   у необязательного;
+ * - поля фильтров, `or()` и агрегатов `sum`, `avg`, `min`, `max`, `countBy` — поля класса.
+ * Чего типы не знают: возврат к узлу связи из пути (pivot) от класса, с которым связь не связана концом, и роль чужого
+ * класса шагом. Это и имена, известные только во время выполнения, — через loose(db) (index.ts): проверки во время
+ * выполнения те же. db.as(), db.begin(), db.batch() и entity() отдают цепочки без строгих типов (Db, Batch, Chain).
+ * Модель описана структурно (ModelLike), поэтому основная точка входа не зависит от Zod.
  */
-import type { ChainCore, StepFn } from './chain.js';
-import type { Cursor, Op, Path, Row, Scalar } from './types.js';
-import type { IncMarker } from './write.js';
-/** То, что цепочкам нужно от модели: имя, алиас и выведенные типы данных и концов. */
-export interface ModelLike<N extends string = string, D = unknown, L = unknown, A extends string = string> {
+import type { ChainCore, ChainRef } from './chain.js';
+import type { Cursor, Op, OP, Path, Row, Scalar } from './types.js';
+import type { DeleteOptions, IncMarker, RestoreOptions } from './write.js';
+/**
+ * То, что цепочкам нужно от модели: имя, алиас и типы для вывода — данные строки, концы строки, концы класса (роль →
+ * `{ targets: имена классов целей; many; required }`) и имена класса и его предков. Модели letopis/model и объявления
+ * `letopis types` ему соответствуют.
+ */
+export interface ModelLike<N extends string = string, D = unknown, L = unknown, A extends string = string, E = unknown, P extends string = never> {
     readonly name: N;
     readonly alias?: A;
     readonly __types?: {
         data: D;
         links: L;
+        ends?: E;
+        ancestors?: P;
     };
 }
-export type AnyModelLike = ModelLike<string, any, any, any>;
-type DataOf<C> = C extends ModelLike<string, infer D, unknown, string> ? (D extends Record<string, unknown> ? D : Record<string, unknown>) : Record<string, unknown>;
-type LinksOf<C> = C extends ModelLike<string, unknown, infer L, string> ? (L extends Record<string, unknown> ? L : Record<string, string>) : Record<string, string>;
+export type AnyModelLike = ModelLike<string, any, any, any, any, any>;
+/** Обязательный одиночный конец на класс T (системные классы). */
+type One<T extends string> = {
+    targets: T;
+    many: false;
+    required: true;
+};
+type NoKeys = Record<never, never>;
+/**
+ * Встроенный набор моделей системных классов (lib/sql/95-seed.system.sql): шаги Class, Account, member, Resource, rule
+ * есть у любого TypedDb. Модель с тем же именем в `models` (например, из `letopis types --system`) — вместо встроенной.
+ */
+export type SystemModels = readonly [
+    ModelLike<'Class', {
+        name: string;
+    }, NoKeys, never, NoKeys>,
+    ModelLike<'Account', {
+        name: string;
+        enabled?: boolean;
+        categories?: string[];
+    }, NoKeys, never, NoKeys>,
+    ModelLike<'member', {
+        roles?: string[];
+    }, {
+        User: string;
+        Tenant: string;
+    }, never, {
+        User: One<'Account'>;
+        Tenant: One<'Account'>;
+    }>,
+    ModelLike<'Resource', {
+        alias: string;
+        category: 'ACCOUNT' | 'API' | 'READ' | 'WRITE' | 'DELETE';
+        pattern?: {
+            categories?: string;
+            roles?: string;
+            endpoint?: string;
+            class?: string;
+        };
+        description?: string;
+    }, NoKeys, never, NoKeys>,
+    ModelLike<'rule', {
+        permission: 'allow' | 'deny';
+        weight?: number;
+        enabled?: boolean;
+        code?: number;
+        message?: string;
+        description?: string;
+    }, {
+        Group: string;
+        Object: string;
+    }, never, {
+        Group: One<'Resource'>;
+        Object: One<'Resource'>;
+    }>
+];
+type NameOf<K> = K extends {
+    readonly name: infer N extends string;
+} ? N : never;
+/** Алиас модели; нет алиаса (или он не литерал) — never. */
+type AliasOf<K> = K extends {
+    readonly alias?: infer A;
+} ? (A extends string ? (string extends A ? never : A) : never) : never;
+/** Имена, которыми модель вызывается шагом: имя и алиас. */
+type StepNames<K> = NameOf<K> | AliasOf<K>;
+type TypesOf<K> = K extends {
+    readonly __types?: infer T;
+} ? NonNullable<T> : NoKeys;
+/** Данные строки класса C (интерфейсы `letopis types` — тоже: индексная сигнатура не требуется). */
+type DataOf<C> = C extends unknown ? (TypesOf<C> extends {
+    data: infer D;
+} ? (D extends object ? D : Record<string, unknown>) : Record<string, unknown>) : never;
+type LinksOf<C> = C extends unknown ? (TypesOf<C> extends {
+    links: infer L;
+} ? (L extends object ? L : Record<string, string>) : Record<string, string>) : never;
+/** Концы класса C: роль → { targets, many, required }; модель без них — без концов. */
+type EndsOf<C> = C extends unknown ? (TypesOf<C> extends {
+    ends?: infer E;
+} ? EndsOrNone<NonNullable<E>> : NoKeys) : never;
+type EndsOrNone<E> = [E] extends [object] ? E : NoKeys;
+/** Имя класса и его предков (ancestors реестра). */
+type AncestorsOf<K> = K extends unknown ? NameOf<K> | (TypesOf<K> extends {
+    ancestors?: infer P;
+} ? Extract<P, string> : never) : never;
+type EndTargets<S> = S extends {
+    targets: infer T;
+} ? Extract<T, string> : never;
+/** Классы целей всех концов модели. */
+type TargetsOf<K> = K extends unknown ? {
+    [R in keyof EndsOf<K>]: EndTargets<EndsOf<K>[R]>;
+}[keyof EndsOf<K>] : never;
+/** Роли модели. */
+type RolesOf<K> = K extends unknown ? Extract<keyof EndsOf<K>, string> : never;
+/** Модели подключения и встроенные системные (своя модель системного класса — вместо встроенной). */
+type AllOf<M extends readonly AnyModelLike[]> = M[number] | Exclude<SystemModels[number], {
+    readonly name: NameOf<M[number]>;
+}>;
+/** Семейство класса C: сам класс и потомки (reg.family). */
+type FamilyOf<C, All> = C extends unknown ? C | DescendantsOf<NameOf<C>, All> : never;
+type DescendantsOf<N, All> = All extends unknown ? (N extends AncestorsOf<All> ? All : never) : never;
+type FamTargets<C, All> = TargetsOf<FamilyOf<C, All>>;
+type FamAncestors<C, All> = AncestorsOf<FamilyOf<C, All>>;
+/**
+ * Связаны ли классы C и X концом: роль семейства C принимает класс семейства X (вперёд) или роль семейства X — класс
+ * семейства C (назад); конец принимает класс и его потомков (accepts).
+ */
+type Linked<C, X, All> = [FamTargets<C, All> & FamAncestors<X, All>] extends [never] ? ([FamTargets<X, All> & FamAncestors<C, All>] extends [never] ? false : true) : true;
+/** Классы, в которые ведёт шаг от C. */
+type HopClasses<C, All> = HopClassesOf<C, All, All>;
+type HopClassesOf<C, X, All> = X extends unknown ? (Linked<C, X, All> extends true ? X : never) : never;
+/** Модель по имени или алиасу шага. */
+type ByStepName<P, U> = U extends unknown ? (P extends StepNames<U> ? U : never) : never;
+/** Классы целей роли R: имя роли однозначно во всей схеме (проверяет база). */
+type RoleTargets<R, All> = All extends unknown ? (R extends RolesOf<All> ? EndTargets<EndsOf<All>[R & keyof EndsOf<All>]> : never) : never;
+/** Модели классов T; класса нет среди моделей — только имя (строки без типов данных). */
+type ModelsNamed<T, All> = (All extends unknown ? (NameOf<All> extends T ? All : never) : never) | BareOf<Exclude<T, NameOf<All>>>;
+type BareOf<T> = T extends string ? {
+    readonly name: T;
+} : never;
+/**
+ * Анонимный тип объекта вместо интерфейса: у интерфейса (`<Класс>Data` из `letopis types`) нет неявной индексной
+ * сигнатуры, и без этого его строка не подошла бы туда, где ждут `Row` (`entity()`, `cursorOf()`).
+ */
+type Plain<T> = {
+    [K in keyof T]: T[K];
+};
 /** Строка ответа класса C. */
-export type RowOf<C> = Row<DataOf<C>, LinksOf<C>>;
+export type RowOf<C> = C extends unknown ? Row<Plain<DataOf<C>>, Plain<LinksOf<C>>> : never;
 /** Фильтр по значению поля: равенство, оператор, вложенный объект любой глубины. */
 export type FieldFilterOf<T> = Op | (T extends readonly unknown[] ? T : T extends Record<string, unknown> ? {
     [P in keyof T]?: FieldFilterOf<T[P]>;
 } : T extends Scalar ? T | null : never);
-/** Фильтр шага класса C: id, список id, строка ответа, or(…) или объект полей и ролей. */
-export type FilterOf<C> = string | string[] | Op | {
-    id: string;
-    class: string;
-} | ({
+/** Фильтр-объект класса C: поля данных, роли концов и id. */
+type ObjectFilterOf<C> = C extends unknown ? {
     [P in keyof DataOf<C>]?: FieldFilterOf<DataOf<C>[P]>;
 } & {
     [R in keyof LinksOf<C>]?: string | {
@@ -37,26 +173,98 @@ export type FilterOf<C> = string | string[] | Op | {
     } | null;
 } & {
     id?: string | string[];
-});
-/** Шаги по именам и алиасам моделей M. */
-export type StepsOf<M extends readonly AnyModelLike[]> = {
-    [K in M[number] as K['name']]: (filter?: FilterOf<K>) => TypedChain<K, M>;
+} : never;
+/**
+ * Результат `or(…)` (index.ts): оператор `or` и фильтры, которыми он типизирован; `F` — только для типов. В шаге класса C
+ * фильтры внутри `or()` — фильтры-объекты класса C.
+ */
+export type OrOp<F = Record<string, unknown>> = Op & {
+    readonly [K in typeof OP]: 'or';
 } & {
-    [K in M[number] as K extends ModelLike<string, unknown, unknown, infer A> ? (string extends A ? never : A) : never]: (filter?: FilterOf<K>) => TypedChain<K, M>;
+    readonly __filters?: F;
 };
+/** Фильтр шага класса C: id, список id, строка ответа, or(…) из фильтров класса или объект полей и ролей. */
+export type FilterOf<C> = string | string[] | {
+    id: string;
+    class: string;
+} | OrOp<ObjectFilterOf<C>> | ObjectFilterOf<C>;
 /** Патч update: поля любой глубины необязательны; inc() — только у числовых полей (§2.5). */
 export type PatchOf<T> = {
     [P in keyof T]?: T[P] extends number | undefined ? T[P] | IncMarker : T[P] extends readonly unknown[] | undefined ? T[P] : T[P] extends Record<string, unknown> | undefined ? PatchOf<NonNullable<T[P]>> : T[P];
 };
-type Retyped = 'paths' | 'rows' | 'first' | 'versions' | 'limit' | 'offset' | 'sort' | 'asOf' | 'after' | 'withDeleted' | 'deep' | 'exact' | 'alias' | 'tags' | 'owner' | 'create' | 'update' | 'upsert' | 'delete' | 'anonymize' | 'reclass' | 'forUpdate' | 'restore' | 'purge' | 'rekey' | 'cache';
-/** Цепочка с текущим классом C: терминалы отдают RowOf<C>, шаги — по моделям M; роли и прочие классы — без типов. */
+/** Счётчик глубины путей полей. */
+type Depth = [never, 0, 1, 2, 3, 4, 5];
+/** Пути полей данных через точку — без элементов массивов. */
+type FieldPaths<T, D extends number = 6> = [D] extends [never] ? never : T extends readonly unknown[] ? never : T extends object ? {
+    [K in keyof T & string]-?: K | `${K}.${FieldPaths<NonNullable<T[K]>, Depth[D]>}`;
+}[keyof T & string] : never;
+/** Пути числовых полей (и полей без типа). */
+type NumberPaths<T, D extends number = 6> = [D] extends [never] ? never : T extends readonly unknown[] ? never : T extends object ? {
+    [K in keyof T & string]-?: (unknown extends T[K] ? K : NonNullable<T[K]> extends number ? K : never) | `${K}.${NumberPaths<NonNullable<T[K]>, Depth[D]>}`;
+}[keyof T & string] : never;
+/** Поле агрегата класса C: `'data.<путь>'`. */
+type DataField<C> = `data.${FieldPaths<DataOf<C>>}`;
+/** Числовое поле агрегата класса C (sum, avg). */
+type NumberField<C> = `data.${NumberPaths<DataOf<C>>}`;
+/** Шаг класса C: фильтр класса и цепочка с ним. */
+type StepFnOf<C, M extends readonly AnyModelLike[]> = (filter?: FilterOf<C>) => TypedChain<C, M>;
+/** Шаги корня: имена и алиасы моделей подключения и системных классов. */
+export type StepsOf<M extends readonly AnyModelLike[]> = {
+    [K in AllOf<M> as NameOf<K>]: StepFnOf<K, M>;
+} & {
+    [K in AllOf<M> as AliasOf<K>]: StepFnOf<K, M>;
+};
+/** Значение слота одиночного конца: id, строка ответа или цепочка. */
+type SlotOne = string | {
+    readonly id: string;
+} | ChainRef;
+/** Значение слота множественного конца: ещё и список id или строк. */
+type SlotMany = SlotOne | readonly (string | {
+    readonly id: string;
+})[];
+/** Слоты роли с концом S записываемой строки класса C. */
+type SlotFns<S, C, M extends readonly AnyModelLike[]> = {
+    set(value: S extends {
+        many: true;
+    } ? SlotMany : SlotOne): TypedChain<C, M>;
+} & (S extends {
+    many: false;
+} ? unknown : {
+    add(value: SlotMany): TypedChain<C, M>;
+    remove(value: SlotMany): TypedChain<C, M>;
+}) & (S extends {
+    required: true;
+} ? unknown : {
+    unset(): TypedChain<C, M>;
+});
+/** Шаг от C по имени P: класс или алиас, связанный с C, или роль семейства C (имя роли, совпавшее с классом, — шаг класса). */
+type HopStep<C, P, M extends readonly AnyModelLike[], All> = P extends StepNames<All> ? ([ByStepName<P, HopClasses<C, All>>] extends [never] ? unknown : StepFnOf<ByStepName<P, HopClasses<C, All>>, M>) : P extends RolesOf<FamilyOf<C, All>> ? StepFnOf<ModelsNamed<RoleTargets<P, All>, All>, M> : unknown;
+/** Слоты имени P: только роль самого класса C. */
+type HopSlots<C, P, M extends readonly AnyModelLike[]> = P extends keyof EndsOf<C> ? SlotFns<EndsOf<C>[P], C, M> : unknown;
+/** Свойства-шаги цепочки класса C. */
+type HopsOf<C, M extends readonly AnyModelLike[], All = AllOf<M>> = {
+    [P in StepNames<HopClasses<C, All>> | Exclude<RolesOf<FamilyOf<C, All>>, StepNames<All>> | Extract<keyof EndsOf<C>, string>]: HopStep<C, P, M, All> & HopSlots<C, P, M>;
+};
+type Retyped = 'paths' | 'rows' | 'first' | 'versions' | 'limit' | 'offset' | 'sort' | 'asOf' | 'after' | 'withDeleted' | 'deep' | 'exact' | 'alias' | 'tags' | 'owner' | 'create' | 'update' | 'upsert' | 'delete' | 'forUpdate' | 'restore' | 'cache' | 'sum' | 'avg' | 'min' | 'max' | 'countBy';
+/**
+ * Цепочка с текущим классом C (у шага-роли с несколькими целями — их союз): терминалы отдают RowOf<C>, шаги — переходы
+ * из концов, слоты — роли C, агрегаты — поля C.
+ */
 export type TypedChain<C, M extends readonly AnyModelLike[]> = Omit<ChainCore, Retyped> & {
     paths(): Promise<Path[]>;
     rows(): Promise<RowOf<C>[]>;
     first(): Promise<RowOf<C> | null>;
-    versions(opts?: {
-        follow?: boolean;
-    }): Promise<RowOf<C>[]>;
+    versions(): Promise<RowOf<C>[]>;
+    /** Сумма числового поля `'data.<путь>'` класса; нет ни одного значения — `null`. */
+    sum(field: NumberField<C>): Promise<number | null>;
+    /** Среднее числового поля `'data.<путь>'` класса; нет ни одного значения — `null`. */
+    avg(field: NumberField<C>): Promise<number | null>;
+    /** Наименьшее значение поля `'data.<путь>'` класса. */
+    min(field: DataField<C>): Promise<unknown>;
+    /** Наибольшее значение поля `'data.<путь>'` класса. */
+    max(field: DataField<C>): Promise<unknown>;
+    /** Сколько объектов с каждым значением поля `'data.<путь>'` класса. */
+    countBy(field: DataField<C>): Promise<Record<string, number>>;
     limit(n: number): TypedChain<C, M>;
     offset(n: number): TypedChain<C, M>;
     sort(field: 'at' | 'rev' | 'id' | `data.${string}`, dir?: 'asc' | 'desc' | boolean): TypedChain<C, M>;
@@ -73,40 +281,31 @@ export type TypedChain<C, M extends readonly AnyModelLike[]> = Omit<ChainCore, R
     create(data: Partial<DataOf<C>>, opts?: {
         reason?: string;
     }): TypedChain<C, M>;
+    /** Без фильтра, id, `tags()`, `owner()` и `limit()` у шагов — `invalid_query`; правка всех строк — `{ all: true }`. */
     update(patch?: PatchOf<DataOf<C>>, opts?: {
         rev?: number;
+        all?: boolean;
         reason?: string;
     }): TypedChain<C, M>;
     upsert(data: Partial<DataOf<C>>, opts?: {
         reason?: string;
     }): TypedChain<C, M>;
-    delete(opts?: {
-        confirm?: boolean;
-        reason?: string;
-    }): TypedChain<C, M>;
-    anonymize(fields: (keyof DataOf<C> & string)[], opts?: {
-        reason?: string;
-    }): TypedChain<C, M>;
-    reclass(cls: string, data?: Record<string, unknown>, opts?: {
-        reason?: string;
-    }): TypedChain<unknown, M>;
+    /**
+     * Без опций — превью. `{ confirm: true, expect: превью }` — удалить ровно показанное (цели сужены фильтром, id, `tags()`,
+     * `owner()` или `limit()`); `{ confirm: true }` без `expect` — `invalid_query` (`write.confirm_without_expect`);
+     * осознанно удалить текущий состав без сверки — `{ confirm: true, all: true }`.
+     */
+    delete(opts?: DeleteOptions): TypedChain<C, M>;
     forUpdate(): TypedChain<C, M>;
-    restore(opts?: {
-        reason?: string;
-    }): TypedChain<C, M>;
-    purge(opts?: {
-        confirm?: boolean;
-        reason?: string;
-    }): TypedChain<C, M>;
-    rekey(patch: Partial<DataOf<C>> & Partial<Record<keyof LinksOf<C>, string | {
-        id: string;
-    }>>, opts?: {
-        reason?: string;
-    }): TypedChain<C, M>;
+    /**
+     * `{ expect }` — надгробия `{ id, rev }`: восстановить ровно то, что ушло удалением; расхождение — отказ по смыслу
+     * (`write.restore_already`, `write.restore_id_taken`, `write.restore_stale`). `{ expect, partial: true }` — что можно, а
+     * остальное — строки `$action: 'skip'` с причиной `$why`. Без `expect` — `invalid_query` (`write.restore_without_expect`);
+     * осознанно вернуть все удалённые цели шага без сверки — `{ all: true }`.
+     */
+    restore(opts: RestoreOptions): TypedChain<C, M>;
     cache(opts?: {
         ttl?: number;
     }): TypedChain<C, M>;
-} & StepsOf<M> & {
-    [step: string]: StepFn;
-};
+} & HopsOf<C, M>;
 export {};

package/dist/types.d.ts

@@ -3,35 +3,41 @@
  */
 /**
  * Ревизия схемы, которую знает эта версия пакета, — номер версии SQL-части letopis (таблиц и функций в схеме установки).
- * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии `up()` обновляет только с `upgrade: true`,
- * а `connect()` о ней предупреждает.
+ * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии 2.x `up()` обновляет только с
+ * `upgrade: true`, а `connect()` о ней предупреждает.
  */
-export declare const DDL_REVISION = 7;
+export declare const DDL_REVISION = 11;
+/**
+ * Префикс версии в имени схемы `v<N>.<имя>`: `up({ schema: 'salon' })` и `connect({ schema: 'salon' })` дописывают его к
+ * имени без точки — `v2.salon`.
+ */
+export declare const SCHEMA_VERSION = "v2";
 /**
  * Классы, строки которых меняют права и схему: их запись повышает счётчик прав (загрузчик), а сигнал
  * сбрасывает весь кэш результатов и пропуска прав. Тот же список — в триггерах базы (60-write.sql).
  */
 export declare const ACL_CLASS_NAMES: readonly string[];
 /**
- * Имена методов цепочки: модификаторы, терминалы, глаголы записи и слоты концов, а также `then` и снятые методы прежних
- * версий. После шага цепочки эти имена библиотека не ищет среди классов; все они входят в `RESERVED_CLASS_NAMES`.
+ * Имена методов цепочки: модификаторы, терминалы, глаголы записи и слоты концов, а также `then`. После шага цепочки эти
+ * имена библиотека не ищет среди классов; все они входят в `RESERVED_CLASS_NAMES`.
  */
-export declare const CHAIN_METHODS: readonly ["then", "entity", "paths", "rows", "first", "ids", "count", "limit", "offset", "sort", "asOf", "withDeleted", "deep", "exact", "sum", "avg", "min", "max", "countBy", "after", "versions", "create", "update", "upsert", "set", "unset", "add", "remove", "delete", "anonymize", "reclass", "restore", "purge", "alias", "tags", "owner", "forUpdate", "cache", "rekey", "run", "execute", "account", "diff", "blame"];
+export declare const CHAIN_METHODS: readonly ["then", "entity", "paths", "rows", "first", "ids", "count", "limit", "offset", "sort", "asOf", "withDeleted", "deep", "exact", "sum", "avg", "min", "max", "countBy", "after", "versions", "create", "update", "upsert", "set", "unset", "add", "remove", "delete", "restore", "alias", "tags", "owner", "forUpdate", "cache"];
 /** Свойства корня db (и транзакции db.begin()). */
-export declare const DB_METHODS: readonly ["as", "begin", "commit", "rollback", "lock", "batch", "watch", "close", "registry", "sql", "load", "verify", "maintain", "reset", "describe", "auth", "acl", "idOf", "refresh", "transaction", "flushSignals", "schema", "token", "tenant", "reloadSchema", "accounts", "credentials", "resources", "rules", "compact", "trimHistory", "rekeyClass", "cache", "projector", "rebuildAggregates"];
+export declare const DB_METHODS: readonly ["as", "begin", "commit", "rollback", "lock", "batch", "watch", "close", "registry", "sql", "load", "maintain", "auth", "acl", "idOf", "refresh", "transaction", "flushSignals", "schema", "token", "tenant", "cache"];
 /** Свойства батча db.batch(name). */
-export declare const BATCH_METHODS: readonly ["discard", "size"];
+export declare const BATCH_METHODS: readonly ["run", "discard", "size"];
 /**
  * Имена методов цепочки, корня `db` и батча. Там, где имя занято методом, библиотека не ищет его среди классов, и шаг с
- * таким именем до класса не дойдёт; класс-связь (`link`) с таким именем база не создаст (`invalid_class`). Не давайте
- * классам эти имена.
+ * таким именем до класса не дойдёт. Хаб с таким именем отклоняют `hub()`, `syncModels` и база, связь (`link`) — база
+ * (`invalid_class`; план 2.0, этап 4, п. 2); хаб, заведённый мимо проверки базы, `up()` оставляет и называет в
+ * предупреждении.
  */
 export declare const RESERVED_CLASS_NAMES: readonly string[];
 /** Строка ответа: текущая версия (или версия журнала для asOf, versions, withDeleted). */
 export interface Row<D = Record<string, unknown>, L = Record<string, string | string[]>> {
     id: string;
     class: string;
-    /** Номер версии — для update(patch, { rev }) (этап 4). */
+    /** Номер версии — для update(patch, { rev }). */
     rev: number;
     tenant: string;
     owner: string;
@@ -42,23 +48,25 @@ export interface Row<D = Record<string, unknown>, L = Record<string, string | st
     at: string;
     author: string;
     agent?: string;
-    /** Вид операции версии: create, update, delete, reclass, … */
+    /** Вид операции версии: create, update, delete, restore, … */
     op: string;
     reason?: string;
-    /** Связь со старым или новым id при reclass и rekey. */
-    moved?: string;
     /** Надгробие: удалённая сущность (withDeleted) или версия удаления (versions). */
     $deleted?: true;
     /** Глубина узла при deep() (1 — прямой потомок); в превью удаления — уровень каскада (0 — цель). */
     $depth?: number;
-    /** Что сделал upsert (этап 4). */
+    /** Что сделал upsert. */
     $upsert?: 'created' | 'updated' | 'unchanged';
-    /** Превью удаления (delete() без confirm): удалится, снимется конец или помешает (restrict). */
-    $action?: 'delete' | 'unset' | 'restrict';
-    /** purge(): число версий в журнале (превью) или стёртых. */
-    $versions?: number;
-    /** purge({ confirm: true }): история стёрта. */
-    $purged?: true;
+    /**
+     * Превью удаления (delete() без confirm): удалится, снимется конец или помешает (restrict). В ответе
+     * `restore({ expect, partial: true })` — `skip`: цель не восстановлена, причина — `$why`.
+     */
+    $action?: 'delete' | 'unset' | 'restrict' | 'skip';
+    /**
+     * Почему цель `restore({ expect, partial: true })` не восстановлена: `restored` — её уже восстановили, `reissued` — id
+     * занял новый объект с тем же ключом, `changed` — после показанного удаления её меняли (удалили снова и т. п.).
+     */
+    $why?: 'restored' | 'reissued' | 'changed';
 }
 /** Путь paths(): узел на каждый шаг цепочки. */
 export type Path = Record<string, Row>;
@@ -107,28 +115,21 @@ export interface ChainMods {
     /** Срез «как было на момент T» (ISO). */
     asOf?: string;
     after?: Cursor;
-    /** Последний шаг включает удалённые. */
+    /**
+     * Не действует: с 2.1 `withDeleted()` — модификатор своего шага (флаг шага цепочки), а не всей выборки. Поле оставлено,
+     * чтобы тип не менялся.
+     */
     withDeleted?: boolean;
     /** Чтение с блокировкой строк последнего шага (только в db.begin()). */
     forUpdate?: boolean;
-    /** versions({ follow: true }): история и через смену id (reclass, rekey) по колонке moved. */
-    follow?: boolean;
     /** Кэш результатов (§2.12): .cache() — срок по умолчанию, .cache({ ttl }) — свой, секунды. */
     cache?: {
         ttl?: number;
     };
-    /** Параметры терминалов diff() и blame() (план 1.1, §2.1): номера версий или моменты (ISO). */
-    hist?: {
-        from?: number | string;
-        to?: number | string;
-        at?: string;
-        follow?: boolean;
-        limit?: number;
-    };
 }
 /** Событие хука onQuery: один запрос цепочки. */
 export interface QueryEvent {
-    mode: 'paths' | 'rows' | 'ids' | 'count' | 'versions' | 'agg' | 'diff' | 'blame';
+    mode: 'paths' | 'rows' | 'ids' | 'count' | 'versions' | 'agg';
     /** Классы шагов цепочки. */
     classes: string[];
     ms: number;
@@ -136,63 +137,65 @@ export interface QueryEvent {
     /** ms > slowMs. */
     slow: boolean;
 }
-/** Изменение пути: added — не было, removed — не стало, changed — другое значение. */
-export interface DiffChange {
-    /** Путь: первый сегмент — раздел строки (data, links, tags, owner, class). */
-    path: string[];
-    kind: 'added' | 'removed' | 'changed';
-    before?: unknown;
-    after?: unknown;
-}
-/** Различия объекта между двумя версиями (diff()). */
-export interface DiffResult {
-    id: string;
-    class: string | null;
-    from: {
-        rev: number;
-        at: string;
-        id?: string;
-    } | null;
-    to: {
-        rev: number;
-        at: string;
-        id?: string;
-        deleted?: true;
-    } | null;
-    changes: DiffChange[];
-}
-/** Кто и почему последним изменил лист версии (blame()). */
-export interface BlameField {
-    path: string[];
-    rev: number;
-    at: string;
-    author: string;
-    agent?: string;
-    op: string;
-    reason?: string;
-    /** Другой id (история прошла через смену id при reclass или rekey). */
-    id?: string;
-    /** false — до найденной версии история неполная: изменение могло быть раньше. */
-    exact: boolean;
-}
-/** Поля версии объекта с версиями, которые их изменили (blame()). */
-export interface BlameResult {
-    id: string;
-    class: string;
-    rev: number;
-    deleted?: true;
-    /** История просмотрена целиком и без пропусков. */
-    complete: boolean;
-    fields: BlameField[];
+/** Порог логирования: события этого уровня и выше; `'off'` — ничего. */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'off';
+/** Событие логирования (каталог событий — lib/src/messages/log.ts). Поля без значения в событии отсутствуют. */
+export interface LogEvent {
+    /** Время события, ISO 8601 (UTC). */
+    ts: string;
+    level: Exclude<LogLevel, 'off'>;
+    /** Имя события: connect, read, write, delete, error, sql и др. */
+    event: string;
+    /** Операция: терминал или глагол цепочки, метод db, auth, acl, инструмент MCP. */
+    op?: string;
+    /** Длительность операции, мс (с точностью до 0,1). */
+    ms?: number;
+    /** Арендатор сессии фасада. */
+    tenant?: string;
+    /** Аккаунт фасада: аккаунт сессии или тот, от чьего имени действует db.as(). */
+    account?: string;
+    /** Метка транзакции db.begin() или db.transaction(). */
+    tx?: string;
+    /** Цепочка в читаемом виде: `Shop({"name":"A"}).Product.limit(10).rows()`; данные записи — только именами полей. */
+    chain?: string;
+    /** Строк в ответе или затронуто. */
+    rows?: number;
+    /** Код ошибки letopis (или SQLSTATE ошибки базы) — у error. */
+    code?: string;
+    /** Ключ каталога сообщений — у error и warning. */
+    key?: string;
+    /** Текст ошибки или предупреждения. */
+    msg?: string;
+    /** Подробности события; секреты замаскированы. */
+    detail?: Record<string, unknown>;
+    /** Причина ошибки (исходная ошибка базы и т. п.) — у error. */
+    cause?: {
+        name?: string;
+        message: string;
+        code?: string;
+    };
 }
-/** diff(): «до» и «после» — номер версии или момент (ISO-строка, Date); follow — через смену id. */
-export interface DiffOptions {
-    from?: number | string | Date;
-    to?: number | string | Date;
-    follow?: boolean;
+/** Логгер-функция. */
+export type LogFn = (event: LogEvent) => unknown;
+/** Логгер-объект: pino, console и подобные — вызов `logger[уровень](событие, событие.event)`. */
+export interface LogObject {
+    debug?(event: LogEvent, msg: string): unknown;
+    info?(event: LogEvent, msg: string): unknown;
+    warn?(event: LogEvent, msg: string): unknown;
+    error?(event: LogEvent, msg: string): unknown;
+    log?(event: LogEvent, msg: string): unknown;
 }
-/** blame(): версия на момент at (по умолчанию текущая); limit — сколько версий просматривать (1000). */
-export interface BlameOptions {
-    at?: string | Date;
-    limit?: number;
+/** Логгер: функция или объект с методами уровней. */
+export type Logger = LogFn | LogObject;
+/** Опции логирования connect() и up(). */
+export interface LogOptions {
+    /**
+     * Логгер: функция `(событие) => void` или объект с методами `debug`, `info`, `warn`, `error` (pino, console). Без него
+     * и с переменной окружения `LETOPIS_LOG=<уровень>` события идут JSON-строками в stderr.
+     */
+    log?: Logger;
+    /** Порог: `'debug' | 'info' | 'warn' | 'error' | 'off'`, по умолчанию `'info'` (или уровень из `LETOPIS_LOG`). */
+    logLevel?: LogLevel;
+    /** Ещё имена полей, значения которых маскируются в событиях (пароли, токены и ключи маскируются всегда). */
+    redact?: readonly string[];
 }