letopis 2.0.0 → 3.0.1

package/dist/chain.js

@@ -15,7 +15,9 @@
 import { lerr, lwarn, similar } from './errors.js';
 import { sessionTag } from './cache.js';
 import { buildRead, nextNodeKey, resolveHop, roleTargets, stepClasses, toRow, } from './sql.js';
-import { execBatch, execPlan, precheckPlan, slotRole } from './write.js';
+import { CHAIN_METHODS, OP } from './types.js';
+import { NOLOG, guarded, traced } from './log.js';
+import { completeIssues, dropUndefined, execBatch, execPlan, lockIds, precheckPlan, slotRole, } from './write.js';
 /** Внутренний канал: план чужой ленивой цепочки (entity()). */
 export const PLAN = Symbol('letopis.plan');
 const peekPlan = (x) => x !== null && (typeof x === 'object' || typeof x === 'function') ? x[PLAN] : undefined;
@@ -38,12 +40,75 @@ export function lookupStep(reg, name) {
     const t = targets.map((n) => reg.find(n)).find((c) => !!c);
     return t ? { cls: t, role: name } : undefined;
 }
-/** Имена, которыми начинается шаг: классы, их алиасы и роли концов реестра. */
-const stepNames = (reg) => reg.all().flatMap((c) => [c.name, ...(c.alias ? [c.alias] : []), ...Object.keys(c.ends)]);
-/** Неизвестный класс или роль — с похожими именами реестра (план 2.0, 7.9 №6). */
-const unknownName = (reg, name) => {
-    throw lerr('api.unknown_step', { name, similar: similar(name, stepNames(reg)) });
+/** Системные классы (прав, членств, аккаунтов, описаний): в «похожие» неизвестного шага не идут (план 2.1, A6). */
+const SYSTEM_CLASSES = new Set(['Class', 'Account', 'member', 'Resource', 'rule']);
+const SYSTEM_ID = '2eba6d0a-1edd-4bb6-a85a-a703dab49035';
+const isSystem = (c) => c.ancestors.some((n) => SYSTEM_CLASSES.has(n));
+/** Имена, которыми начинается шаг: классы, их алиасы и роли концов реестра, кроме системных классов. */
+const stepNames = (reg) => reg.all().filter((c) => !isSystem(c)).flatMap((c) => [c.name, ...(c.alias ? [c.alias] : []), ...Object.keys(c.ends)]);
+/**
+ * Свойства массива, которые спрашивают у цепочки, забыв терминал: `.length`, `.map(…)`, `[0]` — не шаги (план 2.1, A6).
+ * Не case-метки member: имена попали бы в зарезервированные (check:docs, reserved) — проверяются после неудачного поиска.
+ */
+const ARRAY_PROPS = new Set(['length', 'map', 'filter', 'forEach', 'reduce', 'find', 'some', 'every', 'slice', 'at', 'toJSON', '0']);
+/**
+ * Неизвестный класс или роль — с похожими именами реестра (план 2.0, 7.9 №6). Свойство массива — api.chain_not_rows.
+ * В реестре только классы System (3.0.1): сессия в личном арендаторе (арендатор = аккаунт сессии) —
+ * api.unknown_step_no_classes, иначе в арендаторе просто нет классов — api.unknown_step_empty_tenant.
+ */
+const unknownName = (ctx, name) => {
+    const reg = ctx.reg;
+    if (ARRAY_PROPS.has(name))
+        throw lerr('api.chain_not_rows', { name });
+    let key = 'api.unknown_step';
+    if (reg.all().every((c) => c.tenant === SYSTEM_ID)) {
+        const tenant = ctx.tenant();
+        const account = ctx.account?.() ?? null;
+        key = tenant !== null && account !== null && tenant.toLowerCase() === account.toLowerCase()
+            ? 'api.unknown_step_no_classes' : 'api.unknown_step_empty_tenant';
+    }
+    throw lerr(key, { name, similar: similar(name, stepNames(reg)) });
+};
+/** Терминалы и агрегаты цепочки: у цепочки без сессии они отдают отказ промисом (sessionless). */
+const TERMINALS = new Set(['rows', 'first', 'ids', 'count', 'paths', 'versions', 'sum', 'avg', 'min', 'max', 'countBy']);
+/**
+ * Неизвестный шаг у фасада без сессии (токен погашен или истёк после connect(), второй раунд 2.1, A5): не синхронный
+ * выброс про «личный арендатор», а цепочка, чьи терминалы отдают api.token_not_active (no_session) отклонённым
+ * промисом — как у любой другой ошибки запроса. Шаги, модификаторы и глаголы такой цепочки ничего не проверяют.
+ */
+function sessionless() {
+    const fail = () => Promise.reject(lerr('api.token_not_active'));
+    const dead = new Proxy(function () { }, {
+        get(_t, p) {
+            if (typeof p === 'symbol' || p === 'then')
+                return undefined;
+            return TERMINALS.has(p) ? fail : dead;
+        },
+        apply: () => dead,
+    });
+    return dead;
+}
+/**
+ * Фасад с токеном без сессии: шага нет среди классов, а арендатора у сессии нет — шаг из sessionless(); батч и
+ * подключение без токена (администраторское) — как прежде.
+ */
+const noSession = (ctx, name) => !ctx.batch && !ARRAY_PROPS.has(name) && ctx.hasToken?.() === true && ctx.tenant() === null;
+/** Перебор цепочки (for…of, spread, Array.from) — понятный отказ вместо «is not iterable». */
+const notIterable = () => {
+    throw lerr('api.chain_not_rows', { name: '[Symbol.iterator]' });
 };
+/**
+ * withDeleted() — модификатор своего шага (план 2.1, A9): у шага не последнего, когда у последнего его нет, — один раз
+ * предупреждение (до 2.1 флаг относился к последнему шагу).
+ */
+function warnWithDeleted(steps, log) {
+    const last = steps[steps.length - 1];
+    if (!last || last.withDeleted)
+        return;
+    const at = steps.slice(0, -1).find((s) => s.withDeleted && s.pivotKey === undefined);
+    if (at)
+        lwarn('api.with_deleted_step', { step: at.name, last: last.name }, { once: `with-deleted|${at.name}|${last.name}`, log });
+}
 const nodeOf = (steps, s) => s.pivotKey === undefined ? s : steps.find((x) => x.nodeKey === s.pivotKey) ?? s;
 /** Узел для возврата: последний реальный шаг того же класса-связи в текущем читающем сегменте. */
 function pivotNodeOf(steps, cls) {
@@ -57,7 +122,7 @@ function pivotNodeOf(steps, cls) {
     return undefined;
 }
 const noHistoryWarned = new Set();
-function warnNoHistory(steps, method) {
+function warnNoHistory(steps, method, log) {
     const cls = steps[steps.length - 1]?.cls;
     if (!cls || cls.history !== false)
         return;
@@ -65,7 +130,7 @@ function warnNoHistory(steps, method) {
     if (noHistoryWarned.has(key))
         return;
     noHistoryWarned.add(key);
-    lwarn('api.no_history', { method, cls: cls.name });
+    lwarn('api.no_history', { method, cls: cls.name }, { log });
 }
 function report(ctx, mode, steps, t0, rows) {
     if (!ctx.onQuery && ctx.slowMs === undefined)
@@ -76,7 +141,235 @@ function report(ctx, mode, steps, t0, rows) {
     if (ctx.onQuery)
         ctx.onQuery({ mode, classes, ms, rows, slow });
     else if (slow)
-        lwarn('api.slow_query', { ms: ms.toFixed(0), mode, classes: classes.join('→') });
+        lwarn('api.slow_query', { ms: ms.toFixed(0), mode, classes: classes.join('→') }, { log: ctx.log });
+}
+/**
+ * Свойства цепочки, вызов которых может отказать синхронно (модификаторы и глаголы): ошибка — событие error. Не
+ * case-метки: check-docs принимает их за зарезервированные имена.
+ */
+const GUARDED = new Set(['entity', 'limit', 'offset', 'sort', 'asOf', 'after', 'withDeleted', 'deep', 'exact', 'alias', 'tags',
+    'owner', 'create', 'update', 'upsert', 'delete', 'forUpdate', 'restore', 'cache']);
+const LIST_MAX = 50;
+/** Сколько строк каждого класса. */
+function byClass(rows) {
+    const m = {};
+    for (const r of rows)
+        m[r.class] = (m[r.class] ?? 0) + 1;
+    return m;
+}
+/** id строк — не больше LIST_MAX. */
+const idsOf = (rows) => rows.slice(0, LIST_MAX).map((r) => r.id);
+/** Значение фильтра или аргумента для текста цепочки: поля-секреты — '***', длинное — обрезано. */
+function fmtVal(log, x, depth = 0) {
+    if (x === undefined)
+        return 'undefined';
+    if (x === null || typeof x === 'number' || typeof x === 'boolean')
+        return String(x);
+    if (typeof x === 'string')
+        return JSON.stringify(x.length > 80 ? `${x.slice(0, 80)}…` : x);
+    if (typeof x === 'bigint')
+        return `${x}n`;
+    if (typeof x !== 'object')
+        return typeof x;
+    if (depth > 3)
+        return '…';
+    if (x instanceof Date)
+        return JSON.stringify(x.toISOString());
+    const op = x[OP];
+    if (typeof op === 'string') {
+        const args = x.args ?? [];
+        return `${op}(${args.map((a) => fmtVal(log, a, depth + 1)).join(', ')})`;
+    }
+    const peek = peekPlan(x);
+    if (peek)
+        return `(${chainText(log, peek.steps, peek.mods)})`;
+    if (Array.isArray(x)) {
+        const head = x.slice(0, 10).map((a) => fmtVal(log, a, depth + 1)).join(',');
+        return `[${head}${x.length > 10 ? `,…+${x.length - 10}` : ''}]`;
+    }
+    const entries = Object.entries(x);
+    const shown = entries.slice(0, 20).map(([k, v]) => `${JSON.stringify(k)}:${log.secret(k) ? '"***"' : fmtVal(log, v, depth + 1)}`);
+    return `{${shown.join(',')}${entries.length > 20 ? `,…+${entries.length - 20}` : ''}}`;
+}
+/** Данные записи — только имена полей (значения в лог не идут). */
+const keysOf = (data) => `{${Object.keys(data ?? {}).join(',')}}`;
+/** Модификаторы выборки текстом: .sort(…).limit(…)… */
+function modsText(m) {
+    if (!m)
+        return '';
+    let t = '';
+    if (m.order !== undefined)
+        t += `.sort(${JSON.stringify(m.order)}${m.desc ? ", 'desc'" : ''})`;
+    if (m.limit !== undefined)
+        t += `.limit(${m.limit})`;
+    if (m.offset !== undefined)
+        t += `.offset(${m.offset})`;
+    if (m.asOf !== undefined)
+        t += `.asOf(${JSON.stringify(m.asOf)})`;
+    if (m.after !== undefined)
+        t += '.after(…)';
+    if (m.forUpdate)
+        t += '.forUpdate()';
+    if (m.cache)
+        t += `.cache(${m.cache.ttl !== undefined ? `{ttl:${m.cache.ttl}}` : ''})`;
+    return t;
+}
+/** Глагол текстом: данные — именами полей, expect — числом строк. */
+function opText(op) {
+    const o = [];
+    if (op.kind === 'create' || op.kind === 'upsert')
+        return `${op.kind}(${keysOf(op.data)})`;
+    if (op.kind === 'update') {
+        if (op.rev !== undefined)
+            o.push(`rev:${op.rev}`);
+        if (op.all)
+            o.push('all:true');
+        return `update(${keysOf(op.data)}${o.length ? `, {${o.join(',')}}` : ''})`;
+    }
+    if (op.kind === 'delete') {
+        if (op.confirm)
+            o.push('confirm:true');
+        if (op.all)
+            o.push('all:true');
+    }
+    if (op.kind === 'restore' && op.partial)
+        o.push('partial:true');
+    if (op.expect !== undefined)
+        o.push(`expect:[${op.expect.length}]`);
+    return `${op.kind}(${o.length ? `{${o.join(',')}}` : ''})`;
+}
+/** Значение слота текстом. */
+function slotText(v) {
+    if (v === null)
+        return 'null';
+    if (typeof v === 'string')
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.length}]`;
+    return 'plan' in v ? '(цепочка)' : JSON.stringify(v.id);
+}
+/**
+ * Цепочка в читаемом виде: `Shop({"name":"A"}).Product.limit(10).rows()`. Фильтры — значениями (поля-секреты — '***'),
+ * данные записи — только именами полей.
+ */
+export function chainText(log, steps, mods, term, args = []) {
+    let out = '';
+    steps.forEach((s, i) => {
+        if (!s.self) {
+            out += `${i ? '.' : ''}${s.name}(${s.filter !== undefined ? fmtVal(log, s.filter) : ''})`;
+            if (s.exact)
+                out += '.exact()';
+            if (s.withDeleted)
+                out += '.withDeleted()';
+            if (s.deepMax !== undefined)
+                out += `.deep(${s.deepMax})`;
+            if (s.aliasKey !== undefined)
+                out += `.alias(${JSON.stringify(s.aliasKey)})`;
+            if (s.tagsFilter !== undefined)
+                out += `.tags(${fmtVal(log, s.tagsFilter)})`;
+            if (s.ownerFilter !== undefined)
+                out += `.owner(${JSON.stringify(s.ownerFilter)})`;
+        }
+        if (s.op) {
+            out += `${modsText(s.opMods)}.${opText(s.op)}`;
+            for (const sl of s.slots ?? [])
+                out += `.${sl.role}.${sl.op}(${sl.op === 'unset' ? '' : slotText(sl.value)})`;
+        }
+        if (out.length > 4000)
+            return;
+    });
+    out += modsText(mods);
+    if (term)
+        out += `.${term}(${args.filter((a) => a !== undefined).map((a) => fmtVal(log, a)).join(', ')})`;
+    return out;
+}
+/** Подробности события записи: состав по классам и id; у удаления — сверка с expect, у restore — пропуски. */
+function writeDetail(op, rows) {
+    const d = {};
+    if (op.kind === 'delete') {
+        d.confirm = op.confirm;
+        d.expect = op.expect !== undefined ? op.expect.length : false;
+        if (op.all)
+            d.all = true;
+        // с expect замыкание каскада блокируется for update и превью сверяется заново (write.ts, deleteOp)
+        if (op.confirm && op.expect !== undefined)
+            d.locked = true;
+        if (rows && !op.confirm) {
+            const actions = {};
+            // строки-сводки скрытых правами строк (3.0.1): в actions.hidden — их число, в классы и id сводки не идут
+            for (const r of rows)
+                if (r.$action)
+                    actions[r.$action] = (actions[r.$action] ?? 0) + (r.$action === 'hidden' ? r.$count ?? 0 : 1);
+            d.actions = actions;
+            rows = rows.filter((r) => r.$action !== 'hidden');
+        }
+    }
+    else if (op.kind === 'restore') {
+        d.expect = op.expect !== undefined ? op.expect.length : false;
+        if (op.partial)
+            d.partial = true;
+        if (rows) {
+            const skipped = rows.filter((r) => r.$action === 'skip');
+            d.restored = rows.length - skipped.length;
+            d.skipped = skipped.slice(0, LIST_MAX).map((r) => ({ id: r.id, why: r.$why }));
+            rows = rows.filter((r) => r.$action !== 'skip');
+        }
+    }
+    else if (rows && op.kind === 'upsert') {
+        const how = {};
+        for (const r of rows)
+            if (r.$upsert)
+                how[r.$upsert] = (how[r.$upsert] ?? 0) + 1;
+        d.upsert = how;
+    }
+    if (rows) {
+        d.classes = byClass(rows);
+        d.ids = idsOf(rows);
+    }
+    return d;
+}
+/** Событие терминала: read — без глаголов, иначе по последнему глаголу write, delete.preview, delete, restore. */
+function termEvent(log, steps, mods, name, args, st, r, ms) {
+    const ops = steps.flatMap((s) => (s.op ? [s.op] : []));
+    const rows = name === 'count' && typeof r === 'number' ? r : st.n;
+    if (!ops.length) {
+        if (!log.wants('read'))
+            return;
+        log.emit('read', { op: name, ms, ...(rows !== undefined ? { rows } : {}), chain: chainText(log, steps, mods, name, args),
+            ...(st.cache ? { detail: { cache: st.cache } } : {}) });
+        return;
+    }
+    const last = ops[ops.length - 1];
+    const event = last.kind === 'delete' ? (last.confirm ? 'delete' : 'delete.preview') : last.kind === 'restore' ? 'restore' : 'write';
+    // запись в db.begin() — в счётчик транзакции: по нему её tx.commit идёт уровнем info
+    log.mark(event);
+    if (!log.wants(event))
+        return;
+    log.emit(event, { op: [...new Set(ops.map((o) => o.kind))].join(','), ms, rows: st.rows ? st.rows.length : rows,
+        chain: chainText(log, steps, mods, name, args), detail: writeDetail(last, st.rows) });
+}
+/** Терминал под логгером: время, событие успеха и error с цепочкой; выключенный логгер — сам вызов. */
+async function traceTerm(ctx, steps, mods, name, args, fn) {
+    const log = ctx.log;
+    if (!log?.enabled)
+        return fn({});
+    const st = {};
+    const t0 = performance.now();
+    let r;
+    try {
+        r = await fn(st);
+    }
+    catch (e) {
+        log.error(e, { op: name, ms: performance.now() - t0, chain: chainText(log, steps, mods, name, args) });
+        throw e;
+    }
+    try {
+        termEvent(log, steps, mods, name, args, st, r, performance.now() - t0);
+    }
+    catch {
+        // событие не собралось — терминал всё равно отработал
+    }
+    return r;
 }
 /** Классы, которые читает цепочка (семейства шагов): по ним сбрасывается её ответ в кэше. */
 function readClasses(reg, steps) {
@@ -94,7 +387,7 @@ function cacheTtl(ctx, steps, mods, classes) {
         return null;
     return Math.min(...marks.map((m) => (m.ttl !== undefined ? m.ttl * 1000 : c.store.ttlMs)));
 }
-async function exec(ctx, q, mode, steps, mods = {}) {
+async function exec(ctx, q, mode, steps, mods = {}, st = {}) {
     const classes = ctx.cache ? readClasses(ctx.reg, steps) : [];
     const ttl = ctx.cache ? cacheTtl(ctx, steps, mods, classes) : null;
     if (ttl !== null) {
@@ -102,8 +395,16 @@ async function exec(ctx, q, mode, steps, mods = {}) {
         const who = ctx.cache.who();
         const key = store.key(q.text, q.params, who);
         const hit = store.get(key);
-        if (hit)
+        const log = ctx.log;
+        if (hit) {
+            st.cache = 'hit';
+            if (log?.wants('cache.hit'))
+                log.emit('cache.hit', { op: mode, rows: hit.length, chain: chainText(log, steps, mods, mode) });
             return hit;
+        }
+        st.cache = 'miss';
+        if (log?.wants('cache.miss'))
+            log.emit('cache.miss', { op: mode, chain: chainText(log, steps, mods, mode), detail: { ttl: ttl / 1000 } });
         const tag = sessionTag(who.token);
         const tok = store.token(classes, tag, who.tenant);
         const t0 = performance.now();
@@ -122,18 +423,24 @@ async function exec(ctx, q, mode, steps, mods = {}) {
     report(ctx, mode, steps, t0, res.length);
     return res;
 }
-async function read(ctx, steps, mods, mode, agg) {
+async function read(ctx, steps, mods, mode, agg, st = {}) {
     const hasOps = steps.some((s) => s.op);
     if (ctx.batch && hasOps)
         throw lerr('api.batch_queued');
+    if (!hasOps)
+        warnWithDeleted(steps, ctx.log);
+    const counted = (r) => {
+        st.n = r.res.length;
+        return r;
+    };
     if (mods.forUpdate)
-        return lockedRead(ctx, steps, mods, mode);
+        return lockedRead(ctx, steps, mods, mode, agg).then(counted);
     if (hasOps)
-        return plan(ctx, steps, mods, mode, agg);
+        return plan(ctx, steps, mods, mode, agg, st).then(counted);
     const { cache: _c, ...plain } = mods;
     const q = buildRead(ctx.reg, ctx.schema, steps, plain, mode, agg);
     const ev = mode === 'countPaths' ? 'count' : mode;
-    return exec(ctx, q, ev, steps, mods).then((res) => ({ q, res }));
+    return exec(ctx, q, ev, steps, mods, st).then((res) => counted({ q, res }));
 }
 /** Модификатор выборки, заданный в mods, — именем метода цепочки; forUpdate() отказывает сам (lock_unsupported). */
 function modName(mods) {
@@ -167,8 +474,13 @@ function checkAfterVerb(steps, mods) {
  * Цепочка с глаголами: весь план одной транзакцией (§2.5). Результат приводится к виду ответа
  * чтения (строки rows/paths, id, n, агрегаты), чтобы терминалы разбирали его одинаково.
  */
-async function plan(ctx, steps, mods, mode, agg) {
-    precheckPlan(ctx.reg, steps, mods.order, agg);
+async function plan(ctx, steps, mods, mode, agg, st = {}) {
+    try {
+        precheckPlan(ctx.reg, steps, mods.order, agg);
+    }
+    catch (e) {
+        throw await completeIssues(ctx, e);
+    }
     const t0 = performance.now();
     const r = await ctx.exec.run((q) => execPlan({ reg: ctx.reg, schema: ctx.schema, q, tenant: ctx.tenant(), owner: ctx.owner, ...reasons(ctx) }, steps, mods, mode, agg));
     if (r.kind === 'read') {
@@ -182,6 +494,7 @@ async function plan(ctx, steps, mods, mode, agg) {
         return r;
     }
     const rows = r.rows;
+    st.rows = rows;
     report(ctx, mode === 'countPaths' ? 'count' : mode === 'paths' ? 'paths' : mode === 'ids' ? 'ids' : 'rows', steps, t0, rows.length);
     // не switch: check-docs принимает case-метки этого файла за имена, которые Proxy разбирает раньше классов
     if (mode === 'paths')
@@ -199,12 +512,18 @@ async function plan(ctx, steps, mods, mode, agg) {
  * которая перестала подходить под условия шага, в ответ не попадает; подходящая, но не
  * заблокированная — acl_denied.
  */
-async function lockedRead(ctx, steps, mods, mode) {
+async function lockedRead(ctx, steps, mods, mode, agg) {
     if (!ctx.exec.explicit)
         throw lerr('api.for_update_outside_tx');
-    if ((mode !== 'rows' && mode !== 'ids') || mods.asOf !== undefined || mods.withDeleted || steps.some((s) => s.deepMax !== undefined || s.op)) {
-        throw lerr('api.for_update_unsupported');
-    }
+    // что именно мешает блокировке — в тексте, что допустимо — в подсказке (второй раунд 2.1, A7)
+    const op = steps.find((s) => s.op)?.op;
+    const what = op ? `${op.kind}()`
+        : mode !== 'rows' && mode !== 'ids' ? `${mode === 'agg' ? agg?.fn ?? 'agg' : mode === 'countPaths' ? 'count' : mode}()`
+            : mods.asOf !== undefined ? 'asOf()'
+                : steps.some((s) => s.withDeleted) ? 'withDeleted()'
+                    : steps.some((s) => s.deepMax !== undefined) ? 'deep()' : undefined;
+    if (what)
+        throw lerr('api.for_update_unsupported', { what });
     const S = `"${ctx.schema.replace(/"/g, '""')}"`;
     const { forUpdate: _f, ...plain } = mods;
     const idsQ = buildRead(ctx.reg, ctx.schema, steps, plain, 'ids');
@@ -215,7 +534,7 @@ async function lockedRead(ctx, steps, mods, mode) {
         const ids = (await q.unsafe(idsQ.text, idsQ.params, { prepare: true })).map((r) => r.id);
         if (!ids.length)
             return [];
-        const locked = new Set((await q.unsafe(`select id from ${S}.entity where id = any ($1::uuid[]) order by id for no key update`, [ids], { prepare: true })).map((r) => r.id));
+        const locked = await lockIds(q, S, ids);
         const want = new Set(ids);
         const fresh = (await q.unsafe(rowsQ.text, rowsQ.params, { prepare: true }))
             .filter((r) => want.has(r.row.id));
@@ -224,15 +543,37 @@ async function lockedRead(ctx, steps, mods, mode) {
             throw lerr('api.lock_denied', { ids: denied.join(', ') }, { detail: { ids: denied } });
         return fresh;
     });
-    report(ctx, mode, steps, t0, res.length);
+    report(ctx, mode === 'ids' ? 'ids' : 'rows', steps, t0, res.length);
     return { q: rowsQ, res: mode === 'ids' ? res.map((r) => ({ id: r.row.id })) : res };
 }
+/**
+ * Промис versions(): методы цепочки на нём (versions().rows(), versions().sort()) — ошибка letopis с подсказкой, а не
+ * TypeError «… is not a function» (3.0). Сам промис уже идёт: его отказ гасится, иначе он ушёл бы в unhandledRejection.
+ */
+function versionsPromise(p) {
+    for (const method of CHAIN_METHODS) {
+        if (method === 'then')
+            continue;
+        Object.defineProperty(p, method, {
+            value: () => {
+                p.catch(() => { });
+                throw lerr('api.versions_terminal', { method });
+            },
+        });
+    }
+    return p;
+}
 /** Причины для плана: по умолчанию у глаголов (у батча — своя) и та, что стоит в транзакции. */
 const reasons = (ctx) => ({ reason: ctx.reason ?? ctx.txReason ?? '', txReason: ctx.txReason ?? '' });
 /** Опция reason глагола (план 1.1, §2.1): проверяет precheckPlan. */
 const reasonOf = (o) => (o?.reason !== undefined ? { reason: o.reason } : {});
-/** Опция all у update() и delete({ confirm: true }): правка всех целей без фильтра (план 2.0, этап 4, п. 2). */
+/**
+ * Опция all у update() и delete({ confirm: true }): правка всех целей без фильтра (план 2.0, этап 4, п. 2); у
+ * delete({ confirm: true }) и restore() ещё — без сверки с expect (3.0).
+ */
 const allOf = (o) => (o?.all === true ? { all: true } : {});
+/** Опция expect у restore() и delete({ confirm: true }) (план 2.1, A1, A2): форму проверяет precheckPlan. */
+const expectOf = (o) => (o?.expect !== undefined ? { expect: o.expect } : {});
 /** Строка ответа: из чтения — to_jsonb узла, из плана — готовая строка записи. */
 const rowOf = (r) => (r.done ? r.row : toRow(r.row));
 /** Значение слота: id, список id, строка ответа или ленивая цепочка. */
@@ -253,7 +594,15 @@ function slotValue(v) {
 }
 function classProp(ctx, name, found, ownerSteps, mods, nodes) {
     const { cls, role } = found;
-    const step = (filter) => {
+    const step = (...args) => {
+        const filter = args[0];
+        // A13: X(undefined) — фильтра нет, шаг найдёт все строки (как X()); чаще всего это пустая переменная с id
+        if (args.length && filter === undefined)
+            lwarn('api.step_undefined_filter', { name }, { once: `undefined-filter|${name}`, log: ctx.log });
+        // A13: sort() относится к последнему шагу цепочки — шаг после него забирает сортировку себе
+        if (ownerSteps && mods.order !== undefined) {
+            lwarn('api.sort_not_last', { field: mods.order, step: name }, { once: `sort-not-last|${mods.order}|${name}`, log: ctx.log });
+        }
         const prev = ownerSteps?.[ownerSteps.length - 1];
         // повтор связи в пути — возврат к её узлу
         const node = prev && cls.kind === 'link' && !role ? pivotNodeOf(ownerSteps, cls.name) : undefined;
@@ -288,10 +637,16 @@ function classProp(ctx, name, found, ownerSteps, mods, nodes) {
             ctx.batch.entry.steps = next;
         return makeChain(ctx, next, mods, nodes);
     };
-    return new Proxy(step, {
+    // ошибка шага или слота (переход, слот без глагола, …) — событие error с цепочкой до него
+    const log = ctx.log;
+    const g = (op, fn) => (log?.enabled
+        ? (...a) => guarded(log, () => ({ op, chain: chainText(log, ownerSteps ?? [], mods) }), () => fn(...a))
+        : fn);
+    const stepFn = g(name, step);
+    return new Proxy(stepFn, {
         get(t, p, r) {
             if (p === 'set' || p === 'unset' || p === 'add' || p === 'remove')
-                return slot(p);
+                return g(`${name}.${p}`, slot(p));
             return Reflect.get(t, p, r);
         },
     });
@@ -368,9 +723,11 @@ export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
         }
         throw lerr('api.entity_arg');
     };
-    const agg = (fn) => async (field) => {
+    /** Терминал: время, событие (read, write, delete, restore) и error — traceTerm. */
+    const term = (name, fn) => (...a) => traceTerm(ctx, steps, mods, name, a, (st) => fn(st, ...a));
+    const agg = (fn) => term(fn, async (st, field) => {
         afterNotPaged(mods, fn);
-        const { q, res } = await read(ctx, steps, mods, 'agg', { fn, field });
+        const { q, res } = await read(ctx, steps, mods, 'agg', { fn, field }, st);
         if (fn === 'countBy')
             return Object.fromEntries(res.map((r) => [r.k ?? 'null', r.n]));
         const v = res[0]?.v;
@@ -381,7 +738,7 @@ export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
         if (fn === 'sum' || fn === 'avg' || q?.aggLeaf === 'numeric')
             return Number(v);
         return v;
-    };
+    });
     /** Свойство цепочки: метод или модификатор — функция, иначе шаг класса, алиаса или роли. */
     const member = (prop) => {
         switch (prop) {
@@ -390,42 +747,42 @@ export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
             case 'entity':
                 return entityStep;
             case 'paths':
-                return async () => {
+                return term('paths', async (st) => {
                     checkAfterVerb(steps, mods);
                     // q === null — пути из результата глагола: строки уже готовы. Ключи — в порядке шагов (jsonb хранит их
                     // по длине), узел последнего шага — последним: по нему cursorOf(путь, поле) берёт курсор (план 2.0, 7.1 №3)
-                    const { q, res } = await read(ctx, steps, mods, 'paths');
+                    const { q, res } = await read(ctx, steps, mods, 'paths', undefined, st);
                     if (q === null)
                         return res.map((r) => r.path);
                     return res.map((r) => Object.fromEntries(q.keys.map((k) => [k, toRow(r.path[k])])));
-                };
+                });
             case 'rows':
-                return async () => {
+                return term('rows', async (st) => {
                     checkAfterVerb(steps, mods);
-                    return (await read(ctx, steps, mods, 'rows')).res.map(rowOf);
-                };
+                    return (await read(ctx, steps, mods, 'rows', undefined, st)).res.map(rowOf);
+                });
             case 'first':
-                return async () => {
+                return term('first', async (st) => {
                     checkAfterVerb(steps, mods);
-                    const { res } = await read(ctx, steps, { ...mods, limit: 1 }, 'rows');
+                    const { res } = await read(ctx, steps, { ...mods, limit: 1 }, 'rows', undefined, st);
                     return res[0] ? rowOf(res[0]) : null;
-                };
+                });
             case 'ids':
-                return async () => {
+                return term('ids', async (st) => {
                     checkAfterVerb(steps, mods);
-                    return (await read(ctx, steps, mods, 'ids')).res.map((r) => r.id);
-                };
+                    return (await read(ctx, steps, mods, 'ids', undefined, st)).res.map((r) => r.id);
+                });
             case 'count':
-                return async (opts) => {
+                return term('count', async (st, opts) => {
                     checkAfterVerb(steps, mods);
                     afterNotPaged(mods, 'count');
-                    return (await read(ctx, steps, mods, opts?.paths ? 'countPaths' : 'count')).res[0].n;
-                };
+                    return (await read(ctx, steps, mods, opts?.paths ? 'countPaths' : 'count', undefined, st)).res[0].n;
+                });
             case 'versions':
-                return async () => {
-                    warnNoHistory(steps, 'versions');
-                    return (await read(ctx, steps, mods, 'versions')).res.map((r) => toRow(r.row));
-                };
+                return (...a) => versionsPromise(term('versions', async (st) => {
+                    warnNoHistory(steps, 'versions', ctx.log);
+                    return (await read(ctx, steps, mods, 'versions', undefined, st)).res.map((r) => toRow(r.row));
+                })(...a));
             case 'sum':
             case 'avg':
             case 'min':
@@ -440,13 +797,14 @@ export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
                 return (field, dir) => withMods({ order: field, desc: dir === true || dir === 'desc' });
             case 'asOf':
                 return (t) => {
-                    warnNoHistory(steps, 'asOf');
+                    warnNoHistory(steps, 'asOf', ctx.log);
                     return withMods({ asOf: t instanceof Date ? t.toISOString() : t });
                 };
             case 'after':
                 return (cursor) => withMods({ after: cursor });
             case 'withDeleted':
-                return () => withMods({ withDeleted: true });
+                // модификатор своего шага (план 2.1, A9): X(id).withDeleted().Y().withDeleted() — удалённые Y удалённого X
+                return () => withLast({ withDeleted: true });
             case 'deep':
                 return (max = 32) => withLast({ deepMax: max });
             case 'exact':
@@ -459,13 +817,13 @@ export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
                 return (v) => withLast({ ownerFilter: typeof v === 'object' ? v.id : v });
             // глаголы записи — звенья плана (этап 4)
             case 'create':
-                return (data = {}, opts) => withOp({ kind: 'create', data, ...reasonOf(opts) });
+                return (data = {}, opts) => withOp({ kind: 'create', data: dropUndefined(data), ...reasonOf(opts) });
             case 'update':
                 return (data = {}, opts) => withOp({ kind: 'update', data, ...(opts?.rev !== undefined ? { rev: opts.rev } : {}), ...allOf(opts), ...reasonOf(opts) });
             case 'upsert':
-                return (data = {}, opts) => withOp({ kind: 'upsert', data, ...reasonOf(opts) });
+                return (data = {}, opts) => withOp({ kind: 'upsert', data: dropUndefined(data), ...reasonOf(opts) });
             case 'delete':
-                return (opts) => withOp({ kind: 'delete', confirm: opts?.confirm === true, ...allOf(opts), ...reasonOf(opts) });
+                return (opts) => withOp({ kind: 'delete', confirm: opts?.confirm === true, ...allOf(opts), ...reasonOf(opts), ...expectOf(opts) });
             case 'set':
             case 'unset':
             case 'add':
@@ -474,7 +832,7 @@ export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
             case 'forUpdate':
                 return () => withMods({ forUpdate: true });
             case 'restore':
-                return (opts) => withOp({ kind: 'restore', ...reasonOf(opts) });
+                return (opts) => withOp({ kind: 'restore', ...allOf(opts), ...reasonOf(opts), ...expectOf(opts), ...(opts?.partial === true ? { partial: true } : {}) });
             case 'cache':
                 return (opts) => {
                     if (opts?.ttl !== undefined && !(opts.ttl > 0))
@@ -482,16 +840,29 @@ export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
                     return withMods({ cache: opts ?? {} });
                 };
         }
-        const found = lookupStep(ctx.reg, prop) ?? unknownName(ctx.reg, prop);
-        return classProp(ctx, prop, found, steps, mods, nodes);
+        const found = lookupStep(ctx.reg, prop);
+        if (!found && noSession(ctx, prop))
+            return sessionless();
+        return classProp(ctx, prop, found ?? unknownName(ctx, prop), steps, mods, nodes);
     };
+    const log = ctx.log;
     const handler = {
         get(_t, prop) {
             if (prop === PLAN)
                 return { steps, mods };
+            if (prop === Symbol.iterator)
+                return notIterable;
             if (typeof prop === 'symbol')
                 return undefined;
-            return member(prop);
+            if (!log?.enabled)
+                return member(prop);
+            // ошибка имени (неизвестный шаг, слот как метод) и модификатора или глагола (после глагола, неверный аргумент) —
+            // событие error с цепочкой до него; терминалы пишут свои события сами (traceTerm)
+            const where = () => ({ op: prop, chain: chainText(log, steps, mods) });
+            const got = guarded(log, where, () => member(prop));
+            return typeof got === 'function' && GUARDED.has(prop)
+                ? (...a) => guarded(log, where, () => got(...a))
+                : got;
         },
     };
     return new Proxy({}, handler);
@@ -505,18 +876,26 @@ export function makeBatch(ctx, queue) {
     const member = (prop) => {
         switch (prop) {
             case 'run':
-                return async () => {
+                return () => traced(ctx.log ?? NOLOG, 'write', { op: 'batch' }, async () => {
                     const entries = queue.splice(0, queue.length);
                     const loose = entries.find((x) => x.loose)?.loose;
                     if (loose)
                         throw afterVerbError(loose.name, loose.verb);
                     const plans = entries.map((x) => x.steps);
-                    for (const p of plans)
-                        precheckPlan(ctx.reg, p);
+                    try {
+                        for (const p of plans)
+                            precheckPlan(ctx.reg, p);
+                    }
+                    catch (e) {
+                        throw await completeIssues(ctx, e);
+                    }
                     if (!plans.length)
                         return [];
                     return ctx.exec.run((q) => execBatch({ reg: ctx.reg, schema: ctx.schema, q, tenant: ctx.tenant(), owner: ctx.owner, ...reasons(ctx) }, plans));
-                };
+                }, (out) => {
+                    const rows = out.flat();
+                    return { rows: rows.length, detail: { plans: out.length, classes: byClass(rows), ids: idsOf(rows) } };
+                });
             case 'discard':
                 return () => void queue.splice(0, queue.length);
             case 'size':
@@ -534,8 +913,10 @@ export function makeBatch(ctx, queue) {
 }
 /** Старт пути от корня db: класс, алиас или роль. */
 export function startStep(ctx, name) {
-    const found = lookupStep(ctx.reg, name) ?? unknownName(ctx.reg, name);
-    return classProp(ctx, name, found, undefined, {}, NO_NODES);
+    const found = lookupStep(ctx.reg, name);
+    if (!found && noSession(ctx, name))
+        return sessionless();
+    return classProp(ctx, name, found ?? unknownName(ctx, name), undefined, {}, NO_NODES);
 }
 /** Старт пути с готового узла: db.entity(row | цепочка). */
 export function startEntity(ctx, x) {