letopis 2.0.0 → 3.0.1

package/dist/sql.js

@@ -20,6 +20,7 @@
 import { lerr, lmsg, similar } from './errors.js';
 import { isOp } from './ops.js';
 import { OP } from './types.js';
+import { PG_UUID_RE, UUID_RE } from './uuid.js';
 let nodeSeq = 0;
 /** Уникальная метка узла пути. */
 export const nextNodeKey = () => ++nodeSeq;
@@ -162,12 +163,33 @@ function leafOf(reg, classes, path) {
     }
     return 'jsonb';
 }
-function compileOp(path, leaf, o, p) {
+/**
+ * Тип поля у классов шага не один (потомок переопределил тип: Base.price — число, Child.price — строка; у другой цели
+ * полиморфного конца поля нет или оно другого типа): приведение к типу листа должно быть безопасным — значение, которое
+ * к нему не приводится, сравнивается и сортируется как null, а не роняет весь запрос ошибкой приведения.
+ */
+function leafMixed(reg, classes, path, leaf) {
+    return !!CAST[leaf] && classes.some((c) => reg.leafType(c.name, path) !== leaf);
+}
+/** Имя типа для pg_input_is_valid по типу листа. */
+const PG_TYPE = {
+    text: 'text', jsonb: 'jsonb', numeric: 'numeric', boolean: 'boolean', timestamptz: 'timestamptz', date: 'date', uuid: 'uuid',
+};
+/**
+ * Значение поля, приведённое к типу листа (скобки обязательны: '::' сильнее '->>'). safe — тип поля в семействе
+ * разный (leafMixed): то, что не приводится, — null.
+ */
+function castLeaf(expr, leaf, safe) {
+    const cast = CAST[leaf];
+    if (!cast)
+        return expr;
+    return safe ? `(case when pg_input_is_valid(${expr}, ${lit(PG_TYPE[leaf])}) then (${expr})${cast} end)` : `(${expr})${cast}`;
+}
+function compileOp(path, leaf, o, p, safe = false) {
     const lhs = accessor(path);
     const cast = CAST[leaf];
     const pc = PCAST[leaf];
-    // скобки обязательны: '::' сильнее '->>'
-    const L = cast ? (a) => `(${lhs(a)})${cast}` : lhs;
+    const L = cast ? (a) => castLeaf(lhs(a), leaf, safe) : lhs;
     const args = o.args;
     switch (o[OP]) {
         case 'ne':
@@ -228,10 +250,10 @@ function compileOp(path, leaf, o, p) {
             return (a) => `${lhs(a)} is null`;
         case 'not': {
             if (isOp(args[0])) {
-                const inner = compileOp(path, leaf, args[0], p);
+                const inner = compileOp(path, leaf, args[0], p, safe);
                 return (a) => `not coalesce(${inner(a)}, false)`;
             }
-            return compileOp(path, leaf, { [OP]: 'ne', args: [args[0]] }, p);
+            return compileOp(path, leaf, { [OP]: 'ne', args: [args[0]] }, p, safe);
         }
         default:
             throw lerr('query.unknown_op', { op: String(o[OP]) });
@@ -266,10 +288,22 @@ function compileTags(v, p) {
 const isPlain = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && !isOp(v);
 /** Объект-строка ответа как значение: берётся id. */
 const idOfValue = (v) => typeof v === 'string' ? v : isPlain(v) && typeof v.id === 'string' ? v.id : undefined;
+/**
+ * id фильтра шага, `{ id }` или конца — uuid, который примет приведение базы (PG_UUID_RE): иначе invalid_query до запроса,
+ * а не сырая ошибка PostgreSQL 22P02 (у null — TypeError; план 2.1, A7).
+ */
+function idCheck(v, where) {
+    if (typeof v === 'string' && PG_UUID_RE.test(v))
+        return v;
+    throw lerr('query.bad_uuid', { where, value: shown(v) });
+}
 function compileFilter(reg, classes, filter, p) {
     const out = { ends: [], frags: [] };
     if (filter === undefined)
         return out;
+    const at = `${classes[0]?.name ?? ''}(…)`;
+    if (filter === null)
+        idCheck(filter, at);
     // or(…): дизъюнкция под-фильтров — только перепроверка
     if (isOp(filter)) {
         if (filter[OP] !== 'or')
@@ -283,11 +317,11 @@ function compileFilter(reg, classes, filter, p) {
         return out;
     }
     if (typeof filter === 'string') {
-        out.ids = [filter];
+        out.ids = [idCheck(filter, at)];
         return out;
     }
     if (Array.isArray(filter)) {
-        out.ids = filter.map((x) => idOfValue(x) ?? refuse('query.id_list'));
+        out.ids = filter.map((x) => idCheck(idOfValue(x) ?? refuse('query.id_list'), at));
         return out;
     }
     const props = (classes[0]?.schema.properties ?? {});
@@ -303,7 +337,8 @@ function compileFilter(reg, classes, filter, p) {
                 continue;
             const at = [...path, k];
             if (isOp(v)) {
-                out.frags.push(compileOp(at, leafOf(reg, classes, at), v, p));
+                const t = leafOf(reg, classes, at);
+                out.frags.push(compileOp(at, t, v, p, leafMixed(reg, classes, at, t)));
                 hadOps = true;
             }
             else if (isPlain(v)) {
@@ -324,10 +359,11 @@ function compileFilter(reg, classes, filter, p) {
         if (value === undefined)
             continue;
         if (key === 'id') {
+            const w = `${classes[0]?.name ?? ''}({ id })`;
             if (typeof value === 'string')
-                out.ids = [value];
+                out.ids = [idCheck(value, w)];
             else if (Array.isArray(value))
-                out.ids = value.map((x) => idOfValue(x) ?? refuse('query.filter_id_list'));
+                out.ids = value.map((x) => idCheck(idOfValue(x) ?? refuse('query.filter_id_list'), w));
             else
                 throw lerr('query.filter_id');
             continue;
@@ -338,7 +374,7 @@ function compileFilter(reg, classes, filter, p) {
                 out.frags.push((a) => `coalesce(${a}.links->${role}, 'null'::jsonb) in ('null'::jsonb, '[]'::jsonb)`);
                 continue;
             }
-            const id = idOfValue(value) ?? refuse('query.end_value', { role: key });
+            const id = idCheck(idOfValue(value) ?? refuse('query.end_value', { role: key }), `${classes[0]?.name ?? ''}({ ${key} })`);
             out.ends.push(id);
             const ph = p.push(id);
             out.frags.push((a) => `${SCHEMA_MARK}.role_has(${a}.links, array[${role}], ${ph}::uuid)`);
@@ -347,7 +383,8 @@ function compileFilter(reg, classes, filter, p) {
         // поле данных: не описано ни в одном классе шага — invalid_query с похожими (план 2.0, этап 3, п. 3)
         checkField(classes, key, `${classes[0]?.name ?? ''}({ ${key} })`, true);
         if (isOp(value)) {
-            out.frags.push(compileOp([key], leafOf(reg, classes, [key]), value, p));
+            const t = leafOf(reg, classes, [key]);
+            out.frags.push(compileOp([key], t, value, p, leafMixed(reg, classes, [key], t)));
             continue;
         }
         if (isPlain(value)) {
@@ -379,7 +416,7 @@ function asFrags(cf, p) {
     }
     return frags;
 }
-function sortSpec(order, leaf) {
+function sortSpec(order, leaf, mixed) {
     const f = order === 'updated' ? 'at' : order;
     const col = { field: order, nullable: false };
     if (f === 'at')
@@ -391,12 +428,16 @@ function sortSpec(order, leaf) {
     if (f.startsWith('data.')) {
         const path = f.slice(5).split('.');
         const t = leaf(path);
-        return { expr: (a) => (CAST[t] ? `(${accessor(path)(a)})${CAST[t]}` : accessor(path)(a)), pcast: PCAST[t], field: order, type: t, nullable: true };
+        const safe = mixed(path, t);
+        return { expr: (a) => castLeaf(accessor(path)(a), t, safe), pcast: PCAST[t], field: order, type: t, nullable: true, safe };
     }
+    // имя поля данных без префикса (sort('code')) — подсказка «data.code?»: принять его молча нельзя — колонки at, rev, id
+    // и поле данных с тем же именем разошлись бы, а курсор cursorOf(строка, 'code') — с ними
+    if (/^[\p{L}_$][\p{L}\p{N}_$]*(\.[\p{L}\p{N}_$]+)*$/u.test(order))
+        throw lerr('query.sort_field_data', { field: order });
     throw lerr('query.sort_field', { field: order });
 }
-/** Формы значений курсора — как у форматов uuid, date и date-time валидатора (validate.ts). */
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Формы значений курсора — как у форматов uuid (UUID_RE, uuid.ts), date и date-time валидатора (validate.ts). */
 const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
 const TIME_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(\.\d{1,6})?(?:Z|[+-](\d{2}):(\d{2}))$/;
 /** Дата (и время), которую примет приведение базы ::date / ::timestamptz: форма и смысл полей. */
@@ -468,7 +509,10 @@ function cursorParams(c, sort) {
     const { v, id } = c;
     if (typeof id !== 'string' || !UUID_RE.test(id))
         throw lerr('query.cursor_id', { id: shown(id) });
-    const value = v === null && sort.nullable ? null : cursorValue(v, sort.type);
+    let value = v === null && sort.nullable ? null : cursorValue(v, sort.type);
+    // строка потомка с другим типом поля (курсор её значения) стоит среди null — как в castLeaf
+    if (value === undefined && sort.safe && v !== undefined && typeof v !== 'object')
+        value = null;
     if (value === undefined) {
         // у поля данных подходит и курсор null — своя запись, а не склейка « или null»
         throw lerr(sort.nullable ? 'query.cursor_value_nullable' : 'query.cursor_value', { value: shown(v), field: sort.field, expect: lmsg(CURSOR_EXPECT[sort.type]) });
@@ -599,7 +643,9 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
         const dataP = lazy(() => (cf.eq ? `${p.push(cf.eq)}::jsonb` : 'null'));
         const endsP = lazy(() => (cf.ends.length ? `${p.push(cf.ends)}::uuid[]` : 'null'));
         const idsP = lazy(() => (cf.ids ? `${p.push(cf.ids)}::uuid[]` : 'null'));
-        const dead = mods.withDeleted === true && i === lastNode;
+        // надгробия узла: withDeleted() этого шага (план 2.1, A9) или versions() по явным id последнего шага — история
+        // удалённого объекта (план 2.1, A10)
+        const dead = step.withDeleted === true || (mode === 'versions' && i === lastNode && cf.ids !== undefined && step.deepMax === undefined);
         const dataCond = (v) => (cf.eq ? ` and ${v}.data @> ${dataP()}` : '');
         const endsCond = (col) => (cf.ends.length ? ` and ${col} @> ${endsP()}` : '');
         /** Версии журнала: последняя версия каждого id не позже момента. */
@@ -717,15 +763,19 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
         joins.push(`join p${i} on p${i}.src = h${a}.id join n${i} h${i} on h${i}.id = p${i}.id`);
     }
     // ключи шагов в путях
+    // повтор имени — суффикс _2, _3…, свободный среди всех уже выданных ключей: алиас x_2 и второй шаг x не
+    // совпадают (x, x_2, x → x, x_2, x_3), иначе узел терялся бы в jsonb_build_object
     const keyed = [];
-    const seen = new Map();
+    const used = new Set();
     steps.forEach((s, i) => {
         if (s.pivotKey !== undefined)
             return;
         const base = s.aliasKey ?? s.name;
-        const n = (seen.get(base) ?? 0) + 1;
-        seen.set(base, n);
-        keyed.push({ key: n === 1 ? base : `${base}_${n}`, node: i });
+        let key = base;
+        for (let n = 2; used.has(key); n++)
+            key = `${base}_${n}`;
+        used.add(key);
+        keyed.push({ key, node: i });
     });
     const from = `from n0 h0${joins.length ? ' ' + joins.join(' ') : ''}`;
     const whereOf = (conds) => {
@@ -738,9 +788,10 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
     const single = tail.length === 0 && !steps.some((st) => st.pivotKey !== undefined);
     const ents = single ? `n${lastNode}` : `(select z0.* from n${lastNode} z0 where z0.id in (select h${lastNode}.id ${from}${whereOf(tail)}))`;
     const leaf = (path) => leafOf(reg, rowsNode(lastNode), path);
+    const mixed = (path, t) => leafMixed(reg, rowsNode(lastNode), path, t);
     if (mods.order?.startsWith('data.'))
         checkField(rowsNode(lastNode), topField(mods.order), `sort('${mods.order}')`, false);
-    const sort = mods.order ? sortSpec(mods.order, leaf) : undefined;
+    const sort = mods.order ? sortSpec(mods.order, leaf, mixed) : undefined;
     const dir = mods.desc ? ' desc' : '';
     /** Порядок: поле sort, id строки и разделители равных (id прочих узлов пути). */
     const orderBy = (a, more = []) => (sort ? ` order by ${[sort.expr(a), `${a}.id`, ...more].map((x) => `${x}${dir}`).join(', ')}` : '');
@@ -828,10 +879,11 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
                 text = `${withClause}select ${acc} as k, count(*)::int as n from ${ents} z group by 1 order by 2 desc, 1${limitOffset()}`;
             }
             else {
-                const cast = agg.fn === 'sum' || agg.fn === 'avg' ? '::numeric' : CAST[aggLeaf];
+                const t = agg.fn === 'sum' || agg.fn === 'avg' ? 'numeric' : aggLeaf;
                 // у boolean в PostgreSQL нет min и max; false меньше true: наименьшее — «все ли true», наибольшее — «есть ли true»
                 const fn = aggLeaf === 'boolean' && agg.fn === 'min' ? 'bool_and' : aggLeaf === 'boolean' && agg.fn === 'max' ? 'bool_or' : agg.fn;
-                text = `${withClause}select ${fn}((${acc})${cast}) as v from ${ents} z`;
+                // тип поля в семействе разный — значения, которые не приводятся к типу листа, агрегат пропускает (как null)
+                text = `${withClause}select ${fn}(${castLeaf(acc, t, aggLeaf === t && mixed(path, t))}) as v from ${ents} z`;
             }
             break;
         }

package/dist/sync.d.ts

@@ -17,7 +17,7 @@ export interface SyncResult {
     unchanged: string[];
     /** Классы системного арендатора: их меняет только установка. */
     skipped: string[];
-    /** Правила refine, которых нет в базе. */
+    /** Правила refine, которых нет в базе (преобразования Zod syncModels отклоняет — model.transform_unsupported). */
     lost: LostRule[];
 }
 export declare function syncModels(db: DbCore, models: readonly AnyModel[], opts?: {
@@ -27,10 +27,9 @@ export declare function syncModels(db: DbCore, models: readonly AnyModel[], opts
 export declare function schemaToTs(s: JsonSchema | undefined, indent?: string): string;
 /**
  * Объявления `<Класс>Data` и `<Класс>Links` для классов реестра и `<Класс>Model` — имя, алиас, концы с классами целей
- * и предки (ModelLike, typed.ts), — а в конце список `Models`: строгие типы цепочек без моделей Zod, `connect<Models>()`
- * (план 2.0, этап 4, п. 1). Классы арендатора System (системные и классы сидов пакета) — только с includeSystem
- * (`letopis types --system`); без него системные классы даёт встроенный набор SystemModels. Пометка в первой строке —
- * запись каталога model.types_header.
+ * и предки, — а в конце список `Models`: строгие типы цепочек без моделей Zod, `connect<Models>()`. Классы арендатора
+ * System (системные и классы сидов пакета) — только с includeSystem (`letopis types --system`); без него системные
+ * классы даёт встроенный набор SystemModels. Первая строка — пометка «Сгенерировано letopis types — не править руками.»
  */
 export declare function generateTypes(registry: Registry, opts?: {
     includeSystem?: boolean;

package/dist/sync.js

@@ -1,5 +1,6 @@
 import { lerr, lmsg } from './errors.js';
 import { internalsOf } from './internal.js';
+import { NOLOG, traced } from './log.js';
 import { RESERVED_CLASS_NAMES } from './types.js';
 const ROLLBACK = Symbol('sync-dry-run');
 /** Канонический JSON: ключи по алфавиту — сравнение описаний без учёта порядка ключей. */
@@ -11,6 +12,14 @@ function canon(v) {
     return JSON.stringify(v);
 }
 export async function syncModels(db, models, opts = {}) {
+    // событие sync (логирование 3.0): логгер — фасада, которым пишут классы
+    return traced(internalsOf(db)?.log ?? NOLOG, 'sync', { op: 'syncModels' }, () => syncCore(db, models, opts), (r) => ({
+        rows: r.created.length + r.updated.length,
+        detail: { applied: r.applied, models: models.length, created: r.created, updated: r.updated, unchanged: r.unchanged.length,
+            skipped: r.skipped, lost: r.lost.length },
+    }));
+}
+async function syncCore(db, models, opts) {
     // хаб с именем метода цепочки или корня db (модель собрана мимо hub()) — отказ до записи (план 2.0, этап 4, п. 2;
     // 7.10 №3); связь с таким именем отклоняет база
     for (const m of models) {
@@ -18,6 +27,13 @@ export async function syncModels(db, models, opts = {}) {
             throw lerr('model.sync_hub_name_reserved', { name: m.name });
     }
     const res = { applied: Boolean(opts.apply), created: [], updated: [], unchanged: [], skipped: [], lost: models.flatMap((m) => m.lostRules()) };
+    // преобразования Zod (.trim(), .toLowerCase(), .transform(), z.preprocess …) база и валидатор letopis не исполняют —
+    // данные записались бы как есть: отказ до записи (план 2.1, A11); refine остаётся в отчёте lost
+    const transforms = res.lost.filter((l) => l.kind !== 'refine');
+    if (transforms.length) {
+        throw lerr('model.transform_unsupported', { rules: transforms.map((l) => `${l.path} (${l.kind})`).join(', ') }, { detail: { rules: transforms } });
+    }
+    checkEndRoles(db.registry, models);
     const S = `"${db.schema.replace(/"/g, '""')}"`;
     // предок раньше потомка: потомка класса, которого ещё нет, база отклоняет. Круг родителей (модель, собранная мимо
     // hub()) так не упорядочить — отказ до записи с самим кругом (хвост ревью доработок после 1.2.0: раньше обход молча
@@ -75,6 +91,40 @@ export async function syncModels(db, models, opts = {}) {
         await db.refresh();
     return res;
 }
+const SYSTEM_ID = '2eba6d0a-1edd-4bb6-a85a-a703dab49035';
+/** Набор классов конца — как class_set() базы: список без повторов по порядку. */
+const classSet = (c) => [...new Set(typeof c === 'string' ? [c] : c)].sort().join(', ');
+/**
+ * Имя роли конца — одно на арендатора: в любом другом классе (своём или системном) роль с тем же именем обязана вести
+ * на тот же набор классов (база: sql-write.end_other_class в 60-write.sql, проверка ends при записи Class). Системные
+ * классы занимают роли User и Tenant (member → Account), Group и Object (rule → Resource). Проверка — до записи, по
+ * реестру и самим моделям, с понятным текстом; база проверяет всё равно.
+ */
+function checkEndRoles(reg, models) {
+    const names = new Set(models.map((m) => m.name));
+    const seen = new Map();
+    for (const c of reg.all()) {
+        if (names.has(c.name))
+            continue;
+        for (const [role, e] of Object.entries(c.ends)) {
+            if (!seen.has(role) || c.tenant === SYSTEM_ID)
+                seen.set(role, { cls: c.name, set: classSet(e.class), system: c.tenant === SYSTEM_ID });
+        }
+    }
+    for (const m of models) {
+        for (const [role, e] of Object.entries(m.describe().ends ?? {})) {
+            const mine = classSet(e.class);
+            const other = seen.get(role);
+            if (other && other.set !== mine) {
+                if (other.system)
+                    throw lerr('model.end_role_system', { end: role, model: m.name, cls: other.cls, target: other.set });
+                throw lerr('model.end_role_taken', { end: role, model: m.name, mine, cls: other.cls, target: other.set });
+            }
+            if (!other)
+                seen.set(role, { cls: m.name, set: mine, system: false });
+        }
+    }
+}
 /** Тип TypeScript по JSON Schema подмножества. */
 export function schemaToTs(s, indent = '') {
     if (!s || Object.keys(s).length === 0)
@@ -116,10 +166,9 @@ export function schemaToTs(s, indent = '') {
 }
 /**
  * Объявления `<Класс>Data` и `<Класс>Links` для классов реестра и `<Класс>Model` — имя, алиас, концы с классами целей
- * и предки (ModelLike, typed.ts), — а в конце список `Models`: строгие типы цепочек без моделей Zod, `connect<Models>()`
- * (план 2.0, этап 4, п. 1). Классы арендатора System (системные и классы сидов пакета) — только с includeSystem
- * (`letopis types --system`); без него системные классы даёт встроенный набор SystemModels. Пометка в первой строке —
- * запись каталога model.types_header.
+ * и предки, — а в конце список `Models`: строгие типы цепочек без моделей Zod, `connect<Models>()`. Классы арендатора
+ * System (системные и классы сидов пакета) — только с includeSystem (`letopis types --system`); без него системные
+ * классы даёт встроенный набор SystemModels. Первая строка — пометка «Сгенерировано letopis types — не править руками.»
  */
 export function generateTypes(registry, opts = {}) {
     const out = [`// ${lmsg('model.types_header')}`, ''];

package/dist/tx.d.ts

@@ -23,6 +23,7 @@
  * записи. Неотправленное (ошибка отправки) остаётся в очереди до следующего интервала.
  */
 import type postgres from 'postgres';
+import { type Log } from './log.js';
 type Sql = postgres.Sql<Record<string, unknown>>;
 export type Tx = postgres.TransactionSql<Record<string, unknown>>;
 /** Транзиентные ошибки PG, которые снимает повтор: взаимная блокировка, сериализация. */
@@ -54,11 +55,12 @@ export declare class Notifier {
     private channel;
     private intervalMs;
     private onError;
+    private log;
     private queue;
     private timer;
     private stopped;
     private flushing;
-    constructor(sql: Sql, channel: string, intervalMs: number, onError?: (e: unknown) => void);
+    constructor(sql: Sql, channel: string, intervalMs: number, onError?: (e: unknown) => void, log?: Log);
     /** Добавить нагрузки из letopis.changed (строка через запятую). */
     add(changed: string | null | undefined): void;
     private schedule;
@@ -108,6 +110,8 @@ export interface TxContext {
      * результатов сбрасывает свои ответы сразу (§2.12); raw — запись через db.sql.
      */
     onChanged?: (names: string[], raw: boolean) => void;
+    /** Логгер (lib/src/log.ts): повторы (tx.retry), транзакции db.begin() (tx.begin, tx.commit, tx.rollback). */
+    log?: Log;
 }
 /**
  * Операция одной транзакцией с контекстом сессии и повтором при транзиентных ошибках и конфликте
@@ -145,7 +149,10 @@ export declare class ExplicitTx implements Executor {
     private failure;
     /** В транзакции был сырой SQL (db.sql): после фиксации — весь кэш. */
     private raw;
+    /** Время открытия — для ms у tx.commit и tx.rollback. */
+    private readonly t0;
     private constructor();
+    private get log();
     static open(ctx: TxContext, renewed?: boolean): Promise<ExplicitTx>;
     /** Транзакция ещё открыта (не зафиксирована и не откачена). */
     get active(): boolean;
@@ -156,6 +163,8 @@ export declare class ExplicitTx implements Executor {
     /** Advisory-блокировка до конца транзакции (отдельное от блокировок семейств пространство ключей). */
     lock(...keys: (string | number)[]): Promise<void>;
     commit(): Promise<void>;
+    /** Событие отката (tx.rollback) и ошибка, которой он вызван. */
+    private rolledBack;
     rollback(): Promise<void>;
 }
 export {};

package/dist/tx.js

@@ -1,4 +1,5 @@
 import { LetopisError, fromDbError, lerr, lmsg } from './errors.js';
+import { NOLOG } from './log.js';
 /** Транзиентные ошибки PG, которые снимает повтор: взаимная блокировка, сериализация. */
 export function isTransient(e) {
     const code = e.code;
@@ -56,15 +57,17 @@ export class Notifier {
     channel;
     intervalMs;
     onError;
+    log;
     queue = new Set();
     timer = null;
     stopped = false;
     flushing = Promise.resolve();
-    constructor(sql, channel, intervalMs, onError = () => { }) {
+    constructor(sql, channel, intervalMs, onError = () => { }, log = NOLOG) {
         this.sql = sql;
         this.channel = channel;
         this.intervalMs = intervalMs;
         this.onError = onError;
+        this.log = log;
     }
     /** Добавить нагрузки из letopis.changed (строка через запятую). */
     add(changed) {
@@ -89,7 +92,10 @@ export class Notifier {
             return this.flushing;
         const payloads = [...this.queue];
         this.queue.clear();
-        this.flushing = this.flushing.then(() => this.sql `select pg_notify(${this.channel}, c) from unnest(${payloads}::text[]) as c`.then(() => undefined, (e) => {
+        this.flushing = this.flushing.then(() => this.sql `select pg_notify(${this.channel}, c) from unnest(${payloads}::text[]) as c`.then(() => {
+            if (this.log.wants('signal.send'))
+                this.log.emit('signal.send', { rows: payloads.length });
+        }, (e) => {
             // не отправлено (обрыв связи, отказ базы) — обратно в очередь: уйдёт следующим интервалом
             // (в 1.0.1 такие сигналы терялись, и кэш других процессов устаревал до срока)
             for (const c of payloads)
@@ -204,6 +210,11 @@ export async function runTx(ctx, fn, opts = {}) {
             if (bodyDone && !opts.read && dead)
                 throw commitUnknown(e);
             if (attempt <= retries && (isTransient(e) || isLogConflict(e))) {
+                const log = ctx.log ?? NOLOG;
+                if (log.wants('tx.retry')) {
+                    log.emit('tx.retry', { detail: { attempt, of: retries, sqlstate: e.code,
+                            ...(isLogConflict(e) ? { conflict: 'log_id_rev' } : {}) } });
+                }
                 await retryDelay(attempt);
                 continue;
             }
@@ -243,10 +254,15 @@ export class ExplicitTx {
     failure = null;
     /** В транзакции был сырой SQL (db.sql): после фиксации — весь кэш. */
     raw = false;
+    /** Время открытия — для ms у tx.commit и tx.rollback. */
+    t0 = performance.now();
     constructor(ctx, conn) {
         this.ctx = ctx;
         this.conn = conn;
     }
+    get log() {
+        return this.ctx.log ?? NOLOG;
+    }
     static async open(ctx, renewed = false) {
         if (!renewed && ctx.before)
             await ctx.before(ctx);
@@ -267,6 +283,9 @@ export class ExplicitTx {
                 return ExplicitTx.open(ctx, true);
             throw le;
         }
+        const log = ctx.log ?? NOLOG;
+        if (log.wants('tx.begin'))
+            log.emit('tx.begin', { op: 'begin', detail: { isolation: 'read committed', ...(ctx.reason ? { reason: ctx.reason } : {}) } });
         return new ExplicitTx(ctx, conn);
     }
     /** Транзакция ещё открыта (не зафиксирована и не откачена). */
@@ -307,6 +326,7 @@ export class ExplicitTx {
                 await this.conn.unsafe('rollback').catch(() => { });
             release(this.conn, this.broken);
             this.failure = this.broken;
+            this.rolledBack('error', this.broken);
             throw this.broken;
         }
         let changed = null;
@@ -331,18 +351,40 @@ export class ExplicitTx {
         catch (e) {
             this.failure ??= isConnectionError(e) ? commitUnknown(e) : fromDbError(e);
             release(this.conn, e);
+            this.rolledBack('error', this.failure);
             throw this.failure;
         }
         this.conn.release();
+        // транзакция с записью (write, delete, restore, db.sql, права, креды) — tx.commit уровня info: это и есть
+        // доказательство фиксации её событий записи (у них то же поле tx); без записи — debug, как прежде
+        const writes = this.log.writes ?? 0;
+        const level = writes > 0 ? 'info' : 'debug';
+        if (this.log.level(level)) {
+            this.log.emit('tx.commit', { op: 'commit', level, ms: performance.now() - this.t0,
+                detail: { writes, ...(changed ? { signals: changed.split(',').filter(Boolean).length } : {}) } });
+        }
         this.ctx.notifier?.add(changed);
         if (changed)
             this.ctx.onChanged?.(changedList(changed), this.raw);
         this.ctx.after?.();
     }
+    /** Событие отката (tx.rollback) и ошибка, которой он вызван. */
+    rolledBack(reason, err) {
+        const log = this.log;
+        if (!log.enabled)
+            return;
+        if (err !== undefined)
+            log.error(err, { op: 'commit', ms: performance.now() - this.t0 });
+        if (log.wants('tx.rollback')) {
+            log.emit('tx.rollback', { op: reason === 'error' ? 'commit' : 'rollback', ms: performance.now() - this.t0,
+                detail: { reason, writes: log.writes ?? 0, ...(this.broken ? { broken: true } : {}) } });
+        }
+    }
     async rollback() {
         if (this.done)
             return;
         this.done = true;
+        this.rolledBack('explicit');
         try {
             // соединение, оборванное ошибкой, не трогаем: postgres.js уронил бы процесс записью в закрытый сокет
             if (!isConnectionError(this.broken))

package/dist/typed.d.ts

@@ -6,7 +6,7 @@
  * - переходы цепочки выводятся из концов, как в resolveHop (lib/src/sql.ts): от класса C — роли его семейства (C и
  *   потомков) и классы, связанные с семейством C концом в любую сторону (роль, имя которой совпало с именем класса,
  *   во время выполнения — шаг класса, так же и здесь);
- * - слоты — только роли класса C: `set(id | строка | цепочка)`, `add` и `remove` — у множественного конца, `unset` —
+ * - шаги ролей после глагола — только роли класса C: `set(id | строка | цепочка)`, `add` и `remove` — у множественного конца, `unset` —
  *   у необязательного;
  * - поля фильтров, `or()` и агрегатов `sum`, `avg`, `min`, `max`, `countBy` — поля класса.
  * Чего типы не знают: возврат к узлу связи из пути (pivot) от класса, с которым связь не связана концом, и роль чужого
@@ -16,7 +16,7 @@
  */
 import type { ChainCore, ChainRef } from './chain.js';
 import type { Cursor, Op, OP, Path, Row, Scalar } from './types.js';
-import type { IncMarker } from './write.js';
+import type { DeleteOptions, IncMarker, RestoreOptions } from './write.js';
 /**
  * То, что цепочкам нужно от модели: имя, алиас и типы для вывода — данные строки, концы строки, концы класса (роль →
  * `{ targets: имена классов целей; many; required }`) и имена класса и его предков. Модели letopis/model и объявления
@@ -214,11 +214,11 @@ export type StepsOf<M extends readonly AnyModelLike[]> = {
 } & {
     [K in AllOf<M> as AliasOf<K>]: StepFnOf<K, M>;
 };
-/** Значение слота одиночного конца: id, строка ответа или цепочка. */
+/** Значение шага роли одиночного конца (`.Роль.set(…)`): id, строка ответа или цепочка. */
 type SlotOne = string | {
     readonly id: string;
 } | ChainRef;
-/** Значение слота множественного конца: ещё и список id или строк. */
+/** Значение шага роли множественного конца (`.Роль.add(…)`, `.remove(…)`): ещё и список id или строк. */
 type SlotMany = SlotOne | readonly (string | {
     readonly id: string;
 })[];
@@ -248,7 +248,7 @@ type HopsOf<C, M extends readonly AnyModelLike[], All = AllOf<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.
+ * из концов, шаги ролей после глагола (`.Роль.set(…)`) — роли C, агрегаты — поля C.
  */
 export type TypedChain<C, M extends readonly AnyModelLike[]> = Omit<ChainCore, Retyped> & {
     paths(): Promise<Path[]>;
@@ -290,16 +290,20 @@ export type TypedChain<C, M extends readonly AnyModelLike[]> = Omit<ChainCore, R
     upsert(data: Partial<DataOf<C>>, opts?: {
         reason?: string;
     }): TypedChain<C, M>;
-    /** С `{ confirm: true }` без фильтра, id, `tags()`, `owner()` и `limit()` у шагов — `invalid_query`; всех — `{ all: true }`. */
-    delete(opts?: {
-        confirm?: boolean;
-        all?: boolean;
-        reason?: string;
-    }): TypedChain<C, M>;
+    /**
+     * Без опций — предпросмотр. `{ confirm: true, expect: предпросмотр }` — удалить ровно показанное (цели сужены фильтром, id, `tags()`,
+     * `owner()` или `limit()`); `{ confirm: true }` без `expect` — `invalid_query`;
+     * осознанно удалить текущий состав без сверки — `{ confirm: true, all: true }`.
+     */
+    delete(opts?: DeleteOptions): TypedChain<C, M>;
     forUpdate(): TypedChain<C, M>;
-    restore(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>;