letopis 2.0.0 → 3.0.1

package/dist/auth.js

@@ -12,6 +12,7 @@
 import { createHmac, randomBytes, scrypt, timingSafeEqual } from 'node:crypto';
 import { promisify } from 'node:util';
 import { lerr } from './errors.js';
+import { shortIntervalMs } from './admin.js';
 const scryptAsync = promisify(scrypt);
 const SCRYPT = { N: 32768, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
 const KEYLEN = 32;
@@ -83,7 +84,46 @@ export function totpCode(secretBase32, atMs = Date.now()) {
     return String(code).padStart(TOTP_DIGITS, '0');
 }
 const accId = (a) => (typeof a === 'object' ? a.id : a);
-const ttlOf = (sec) => (sec === undefined ? null : `${Math.round(sec)} seconds`);
+/** Логин без крайних пробелов (план 2.1, A12): « anna » и «anna» — один логин; не строка — как есть (отказ даст база). */
+const trimLogin = (v) => (typeof v === 'string' ? v.trim() : v);
+/**
+ * Срок ttl (3.0.1) — интервал для базы: число секунд, короткая форма как у connect({ maintain }) ('30s', '15m', '2h',
+ * '1d') или строка-интервал PostgreSQL ('15 minutes') — её разбирает база, ошибку разбора переводит ttlGuard. Не задан —
+ * null (срок по умолчанию). Не число больше нуля, пустая строка, другой тип — invalid_data (access.bad_ttl).
+ */
+export function ttlOf(v, where) {
+    if (v === undefined || v === null)
+        return null;
+    if (typeof v === 'number') {
+        if (Number.isFinite(v) && v > 0)
+            return `${Math.max(1, Math.round(v))} seconds`;
+    }
+    else if (typeof v === 'string' && v.trim() !== '') {
+        const ms = shortIntervalMs(v);
+        if (ms === null)
+            return v.trim();
+        if (ms > 0)
+            return `${ms / 1000} seconds`;
+    }
+    throw lerr('access.bad_ttl', { where, value: shownTtl(v) });
+}
+const shownTtl = (v) => (typeof v === 'string' ? `'${v}'` : typeof v === 'number' || typeof v === 'boolean' || v == null ? String(v) : typeof v);
+/**
+ * Строка ttl, которую не принял разбор интервала PostgreSQL (22007 — не интервал, 22008 и 22015 — вне диапазона), —
+ * invalid_data access.bad_ttl вместо сырой ошибки базы; прочие ошибки — как есть.
+ */
+export async function ttlGuard(run, ttl, where) {
+    try {
+        return await run;
+    }
+    catch (e) {
+        const code = e?.code;
+        if (typeof ttl === 'string' && (code === '22007' || code === '22008' || code === '22015')) {
+            throw lerr('access.bad_ttl', { where, value: shownTtl(ttl) }, { cause: e });
+        }
+        throw e;
+    }
+}
 /** Фасад db.auth. onSwitch — подключение перечитывает арендатора, реестр и пропуска прав. */
 export function makeAuth(S, exec, onSwitch, canSwitch) {
     const one = async (text, params = []) => {
@@ -93,7 +133,8 @@ export function makeAuth(S, exec, onSwitch, canSwitch) {
     // Вход после первой проверки. Код TOTP проверяет база той же функцией, что verifyTotp (право auth.totp,
     // окно ±1 шаг, повтор шага, счётчик неудач и блокировка), секрет из базы не выходит; способ TOTP
     // сессия получает только после удачи. Без кода — сессия без отметки TOTP, как раньше.
-    const login = async (account, ttl, methods, totp) => {
+    const login = async (account, ttl, methods, totp, where = 'auth') => {
+        const interval = ttlOf(ttl, where);
         if (!account)
             return null;
         if (totp != null) {
@@ -102,28 +143,31 @@ export function makeAuth(S, exec, onSwitch, canSwitch) {
                 return null;
             methods = [...methods, 'TOTP'];
         }
-        const r = await one(`select ${S}.issue_session($1::uuid, coalesce($2::interval, interval '7 days'), $3::text[]) as t`, [account, ttlOf(ttl), methods]);
+        const r = await ttlGuard(one(`select ${S}.issue_session($1::uuid, coalesce($2::interval, interval '7 days'), $3::text[]) as t`, [account, interval, methods]), ttl, where);
         return { account, token: r.t };
     };
     return {
         async setPassword(a) {
             const hash = await hashPassword(a.password);
-            const r = await one(`select ${S}.auth_set_password($1::uuid, $2, $3, $4, $5, $6) as id`, [accId(a.account), a.identifier, hash, a.kind ?? 'PASSWORD', a.confirmed ?? null, a.keepCurrent ?? true]);
+            const r = await one(`select ${S}.auth_set_password($1::uuid, $2, $3, $4, $5, $6) as id`, [accId(a.account), trimLogin(a.identifier), hash, a.kind ?? 'PASSWORD', a.confirmed ?? null, a.keepCurrent ?? true]);
             return r.id;
         },
         async verifyPassword(a) {
-            const rows = await exec.run((q) => q.unsafe(`select account, hash, confirmed from ${S}.auth_password_get($1, $2)`, [a.identifier, a.kind ?? 'PASSWORD']));
-            const cred = rows[0];
+            ttlOf(a.ttl, 'verifyPassword');
+            const get = async (ident) => (await exec.run((q) => q.unsafe(`select account, hash, confirmed from ${S}.auth_password_get($1, $2)`, [ident, a.kind ?? 'PASSWORD'])))[0];
+            // логин без крайних пробелов (план 2.1, A12); кред, записанный до 2.1 с пробелами, находится по логину как есть
+            const ident = trimLogin(a.identifier);
+            const cred = (await get(ident)) ?? (ident !== a.identifier ? await get(a.identifier) : undefined);
             if (!cred)
                 return dummyVerify(a.password).then(() => null);
             if (!(await verifyHash(a.password, cred.hash)))
                 return null;
             if (!cred.confirmed && a.requireConfirmed !== false)
                 return null;
-            return login(cred.account, a.ttl, [a.kind ?? 'PASSWORD'], a.totp);
+            return login(cred.account, a.ttl, [a.kind ?? 'PASSWORD'], a.totp, 'verifyPassword');
         },
         async issueApiKey(a) {
-            return one(`select key, id from ${S}.auth_issue_apikey($1::uuid, $2, $3::interval)`, [accId(a.account), a.name ?? null, ttlOf(a.ttl)]);
+            return ttlGuard(one(`select key, id from ${S}.auth_issue_apikey($1::uuid, $2, $3::interval)`, [accId(a.account), a.name ?? null, ttlOf(a.ttl, 'issueApiKey')]), a.ttl, 'issueApiKey');
         },
         async verifyApiKey(key) {
             return (await one(`select ${S}.auth_login_apikey($1) as r`, [key])).r;
@@ -148,7 +192,11 @@ export function makeAuth(S, exec, onSwitch, canSwitch) {
             return (await one(`select ${S}.auth_totp_enabled($1::uuid) as ok`, [accId(account)])).ok;
         },
         async issueOtp(a) {
-            const r = await one(`select ${S}.auth_issue_otp($1::uuid, $2, $3, coalesce($4::interval, interval '10 minutes'), $5, $6) as c`, [accId(a.account), a.identifier, a.kind ?? 'OTP', ttlOf(a.ttl), a.digits ?? 6, a.maxAttempts ?? 5]);
+            // 3.0.1: число попыток вне 1–10 — отказ, а не молчаливое приведение к пределу в базе
+            const max = a.maxAttempts;
+            if (max !== undefined && !(Number.isInteger(max) && max >= 1 && max <= 10))
+                throw lerr('access.bad_max_attempts', { value: shownTtl(max) });
+            const r = await ttlGuard(one(`select ${S}.auth_issue_otp($1::uuid, $2, $3, coalesce($4::interval, interval '10 minutes'), $5, $6) as c`, [accId(a.account), a.identifier, a.kind ?? 'OTP', ttlOf(a.ttl, 'issueOtp'), a.digits ?? 6, max ?? 5]), a.ttl, 'issueOtp');
             return { code: r.c };
         },
         async verifyOtp(a) {
@@ -158,8 +206,9 @@ export function makeAuth(S, exec, onSwitch, canSwitch) {
             return (await one(`select ${S}.auth_link($1::uuid, $2, $3, $4::jsonb, $5) as id`, [accId(a.account), a.kind, a.identifier, (a.meta ?? {}), a.confirmed ?? false])).id;
         },
         async lookup(a) {
+            ttlOf(a.ttl, 'lookup');
             const r = await one(`select ${S}.auth_lookup($1, $2, $3) as a`, [a.kind, a.identifier, a.requireConfirmed ?? true]);
-            return login(r.a, a.ttl, [a.kind], a.totp);
+            return login(r.a, a.ttl, [a.kind], a.totp, 'lookup');
         },
         async credentials(account) {
             return exec.run((q) => q.unsafe(`select * from ${S}.auth_credentials($1::uuid)`, [accId(account)]));
@@ -171,7 +220,7 @@ export function makeAuth(S, exec, onSwitch, canSwitch) {
             return (await one(`select ${S}.auth_set_flags($1::uuid, $2, $3) as ok`, [id, flags.confirmed ?? null, flags.enabled ?? null])).ok;
         },
         async sessionFor(account, opts) {
-            return (await login(accId(account), opts?.ttl, ['SERVICE'])).token;
+            return (await login(accId(account), opts?.ttl, ['SERVICE'], undefined, 'sessionFor')).token;
         },
         async session(token) {
             const r = (await one(`select ${S}.auth_session_info($1) as r`, [token])).r;
@@ -179,9 +228,12 @@ export function makeAuth(S, exec, onSwitch, canSwitch) {
             return r && { account: r.account, tenant: r.tenant, member: r.member, expiresAt: r.expiresAt, loginAt: r.loginAt, methods: r.methods };
         },
         async refresh(opts) {
-            return (await one(`select ${S}.auth_refresh(coalesce($1::interval, interval '7 days')) as e`, [ttlOf(opts?.ttl)])).e;
+            return (await ttlGuard(one(`select ${S}.auth_refresh(coalesce($1::interval, interval '7 days')) as e`, [ttlOf(opts?.ttl, 'refresh')]), opts?.ttl, 'refresh')).e;
         },
-        async revoke() {
+        async revoke(token) {
+            // с токеном — выход пользователя по токену (план 2.1, A3): право auth.session, как у session(token)
+            if (token !== undefined)
+                return (await one(`select ${S}.auth_logout_token($1) as ok`, [token])).ok;
             return (await one(`select ${S}.auth_logout() as ok`)).ok;
         },
         async revokeAll(account) {
@@ -194,8 +246,9 @@ export function makeAuth(S, exec, onSwitch, canSwitch) {
             await onSwitch();
         },
         async tenants() {
-            const rows = await exec.run((q) => q.unsafe(`select tenant, roles from ${S}.auth_tenants()`));
-            return rows.map((r) => ({ tenant: r.tenant, roles: r.roles }));
+            // name и personal — с ревизии 9 (план 2.1, A5): personal — собственный арендатор аккаунта сессии (tenant = account)
+            const rows = await exec.run((q) => q.unsafe(`select tenant, roles, name, personal from ${S}.auth_tenants()`));
+            return rows.map((r) => ({ tenant: r.tenant, roles: r.roles, name: r.name ?? null, personal: r.personal === true }));
         },
         async purgeAccount(account) {
             const r = (await one(`select ${S}.account_purge($1::uuid) as r`, [accId(account)])).r;
@@ -206,3 +259,64 @@ export function makeAuth(S, exec, onSwitch, canSwitch) {
         },
     };
 }
+const argOf = (args, i = 0) => (args[i] !== null && typeof args[i] === 'object' ? args[i] : {});
+/** Аккаунт аргумента: id или { id }. */
+const accOf = (a) => (typeof a === 'string' ? a : a !== null && typeof a === 'object' && typeof a.id === 'string' ? a.id : undefined);
+const loginOf = (v) => (typeof v === 'string' ? { login: v.trim() } : {});
+/** Вход: успех — auth.login (account — вошедший), отказ — auth.fail. */
+function loginEvent(r, method, extra = {}) {
+    const res = r;
+    const detail = { method, ...extra };
+    return res && typeof res === 'object' ? { event: 'auth.login', account: res.account, detail } : { event: 'auth.fail', detail };
+}
+const credential = (action, detail) => ({ event: 'auth.credential', detail: { action, ...detail } });
+const call = (method, detail = {}) => ({ event: 'auth.call', detail: { method, ...detail } });
+/** Что пишет в лог каждый метод db.auth. */
+export const AUTH_LOG = {
+    setPassword: (args, id) => {
+        const a = argOf(args);
+        return credential('setPassword', { account: accOf(a.account), kind: a.kind ?? 'PASSWORD', ...loginOf(a.identifier), id });
+    },
+    verifyPassword: (args, r) => {
+        const a = argOf(args);
+        return loginEvent(r, String(a.kind ?? 'PASSWORD'), { ...loginOf(a.identifier), ...(a.totp != null ? { totp: true } : {}) });
+    },
+    issueApiKey: (args, r) => credential('issueApiKey', { account: accOf(argOf(args).account), name: argOf(args).name, id: r?.id }),
+    verifyApiKey: (_args, r) => loginEvent(r, 'APIKEY'),
+    issueKeySecret: (args, r) => credential('issueKeySecret', { account: accOf(argOf(args).account), name: argOf(args).name, id: r?.id }),
+    verifyKeySecret: (_args, r) => loginEvent(r, 'KEYSECRET'),
+    enrollTotp: (args) => credential('enrollTotp', { account: accOf(argOf(args).account) }),
+    verifyTotp: (args, ok) => (ok === true
+        ? call('verifyTotp', { account: accOf(argOf(args).account), ok: true })
+        : { event: 'auth.fail', detail: { method: 'TOTP', account: accOf(argOf(args).account) } }),
+    totpEnabled: (args, r) => call('totpEnabled', { account: accOf(args[0]), enabled: r }),
+    issueOtp: (args) => {
+        const a = argOf(args);
+        return credential('issueOtp', { account: accOf(a.account), kind: a.kind ?? 'OTP', ...loginOf(a.identifier) });
+    },
+    verifyOtp: (args, r) => {
+        const a = argOf(args);
+        return loginEvent(r, String(a.kind ?? 'OTP'), loginOf(a.identifier));
+    },
+    link: (args, id) => {
+        const a = argOf(args);
+        return credential('link', { account: accOf(a.account), kind: a.kind, ...loginOf(a.identifier), id });
+    },
+    lookup: (args, r) => {
+        const a = argOf(args);
+        return loginEvent(r, String(a.kind), { ...loginOf(a.identifier), ...(a.totp != null ? { totp: true } : {}) });
+    },
+    credentials: (args, r) => ({ ...call('credentials', { account: accOf(args[0]) }), rows: Array.isArray(r) ? r.length : undefined }),
+    revokeCredential: (args, ok) => ({ event: 'auth.revoke', detail: { target: 'credential', id: args[0], ok } }),
+    setFlags: (args, ok) => credential('setFlags', { id: args[0], ...argOf(args, 1), ok }),
+    sessionFor: (args) => ({ event: 'auth.session', detail: { account: accOf(args[0]), method: 'SERVICE' } }),
+    session: (_args, r) => call('session', { found: r !== null }),
+    refresh: () => call('refresh'),
+    revoke: (args, ok) => (args[0] !== undefined
+        ? { event: 'auth.revoke', detail: { target: 'token', ok } }
+        : { event: 'auth.logout', detail: { ok } }),
+    revokeAll: (args, n) => ({ event: 'auth.revoke', detail: { target: 'all', account: accOf(args[0]), n } }),
+    switch: (args, _r, before) => ({ event: 'auth.switch', tenant: String(args[0]), detail: { from: before } }),
+    tenants: (_args, r) => ({ ...call('tenants'), rows: Array.isArray(r) ? r.length : undefined }),
+    purgeAccount: (args, r) => ({ event: 'account.purge', detail: { account: accOf(args[0]), ...r } }),
+};

package/dist/chain.d.ts

@@ -2,7 +2,9 @@ import { type ResultCache } from './cache.js';
 import type { ClassInfo, Registry } from './registry.js';
 import { type Step } from './sql.js';
 import type { Executor } from './tx.js';
-import type { ChainMods, Cursor, Filter, Path, QueryEvent, Row } from './types.js';
+import { type ChainMods, type Cursor, type Filter, type Path, type QueryEvent, type Row } from './types.js';
+import { type Log } from './log.js';
+import { type DeleteOptions, type RestoreOptions } from './write.js';
 export interface ChainCtx {
     readonly reg: Registry;
     readonly schema: string;
@@ -10,6 +12,10 @@ export interface ChainCtx {
     readonly exec: Executor;
     /** Арендатор сессии. */
     readonly tenant: () => string | null;
+    /** Аккаунт сессии (с имперсонацией — тот, от чьего имени): арендатор равен ему — личный арендатор. */
+    readonly account?: () => string | null;
+    /** Фасад входит по токену сессии (connect({ token }), ключ API): без арендатора сессии шаг — sessionless(). */
+    readonly hasToken?: () => boolean;
     /** Владелец новых строк по умолчанию (db.as(…, { owner })). */
     readonly owner?: string;
     readonly onQuery?: (e: QueryEvent) => void;
@@ -28,6 +34,8 @@ export interface ChainCtx {
             tenant?: string | null;
         };
     };
+    /** Логгер фасада (lib/src/log.ts): события read, write, delete, restore, кэша и error. */
+    readonly log?: Log;
 }
 /** План в очереди батча; steps обновляется по мере роста цепочки. */
 export interface BatchEntry {
@@ -53,7 +61,7 @@ export type Batch = {
 };
 export interface ChainCore {
     /**
-     * Все пути цепочки. Путь — строки всех шагов, по одной на шаг, связанные ссылками; приходит объектом, где ключ — имя
+     * Все пути цепочки. Путь — строки всех шагов, по одной на шаг, связанные концами; приходит объектом, где ключ — имя
      * шага (или имя из `alias()`), а значение — строка этого шага: `{ Shop: …, Product: … }`. Если к объекту последнего
      * шага ведут несколько путей, придут все.
      */
@@ -65,11 +73,14 @@ export interface ChainCore {
     rows(): Promise<Row[]>;
     first(): Promise<Row | null>;
     ids(): Promise<string[]>;
-    /** Число сущностей последнего шага; { paths: true } — число путей. */
+    /** Число объектов последнего шага; { paths: true } — число путей. */
     count(opts?: {
         paths?: boolean;
     }): Promise<number>;
-    /** Все версии сущностей последнего шага (надгробия — $deleted), по id и номеру версии. */
+    /**
+     * Все версии объектов последнего шага (надгробия — $deleted), по id и номеру версии. Шаг с явными id находит и
+     * удалённые объекты: `db.Класс(id).versions()` отдаёт историю удалённого.
+     */
     versions(): Promise<Row[]>;
     /**
      * Сумма поля `'data.<путь>'` по объектам последнего шага: значения приводятся к числу, складывает база. `limit()` и
@@ -101,10 +112,14 @@ export interface ChainCore {
     /**
      * Не больше n строк ответа: объектов последнего шага, у `paths()` — путей, у `versions()` — версий, перед `countBy()` —
      * групп. До глагола сужает его цели. Сразу после глагола перед `rows`, `first`, `ids`, `count` и `paths` —
-     * `invalid_query`: глагол уже прошёл по всем целям, сужать нечего.
+     * `invalid_query`: глагол уже прошёл по всем целям, сужать нечего. `n` — целое от 0: дробное — `invalid_query`,
+     * отрицательное отклоняет PostgreSQL (ошибка базы с SQLSTATE 2201W).
      */
     limit(n: number): Chain;
-    /** Пропустить первые n строк ответа — тех же, что считает `limit()`; где действует — как у `limit()`. */
+    /**
+     * Пропустить первые n строк ответа — тех же, что считает `limit()`; где действует — как у `limit()`. `n` — целое от 0:
+     * дробное — `invalid_query`, отрицательное отклоняет PostgreSQL (ошибка базы с SQLSTATE 2201X).
+     */
     offset(n: number): Chain;
     /** Сортировка по полю последнего шага: 'at' | 'rev' | 'id' | 'data.<путь>'. */
     sort(field: string, dir?: 'asc' | 'desc' | boolean): Chain;
@@ -118,8 +133,9 @@ export interface ChainCore {
      */
     after(cursor: Cursor): Chain;
     /**
-     * Последний шаг находит и удалённые объекты. Удалённый объект приходит надгробием — своей последней версией, версией
-     * удаления, — с `$deleted: true`.
+     * Шаг, после которого стоит, находит и удалённые объекты — модификатор своего шага, как `exact()`:
+     * `db.Member(id).withDeleted().Loan().withDeleted()` — удалённые выдачи удалённого участника. Удалённый объект приходит
+     * надгробием — своей последней версией, версией удаления, — с `$deleted: true`.
      */
     withDeleted(): Chain;
     /** Дети любой глубины на переходе к тому же классу; $depth в строке. */
@@ -153,7 +169,7 @@ export interface ChainCore {
      * следующий шаг пойдёт от него.
      */
     entity(x: ChainRef | Row): Chain;
-    /** Создать объект: концы — из пути и слотов; занятый ключ — ошибка exists с id. */
+    /** Создать объект: концы — из пути и шагов роли; занятый ключ — ошибка exists с id. */
     create(data?: Record<string, unknown>, opts?: {
         reason?: string;
     }): Chain;
@@ -173,22 +189,28 @@ export interface ChainCore {
     }): Chain;
     /**
      * Удаляет цели шага; строки, которые на них ссылаются, база удаляет вместе с ними, отвязывает или не даёт удалить цель —
-     * как задано в `onDelete` их ссылок. Без `{ confirm: true }` — предпросмотр удаления: ничего не удаляется, терминал
-     * вернёт все строки, которых оно коснулось бы, у каждой `$action` — что с ней будет. С `{ confirm: true }` цели сужают
-     * фильтр, id, `tags()`, `owner()` или `limit()` хотя бы у одного шага, иначе `invalid_query`; удаление всех строк —
-     * `{ confirm: true, all: true }`.
+     * как задано в `onDelete` их концов. Без `{ confirm: true }` — предпросмотр удаления: ничего не удаляется, терминал
+     * вернёт все строки, которых оно коснулось бы, у каждой `$action` — что с ней будет. `{ confirm: true, expect: предпросмотр }`
+     * удаляет ровно показанное: в транзакции удаления предпросмотр строится заново и сравнивается с `expect` по `id`, `rev` и
+     * `$action`; расхождение — `conflict` (ничего не удалено, новый предпросмотр — `err.detail.preview`); цели сужают фильтр, id,
+     * `tags()`, `owner()` или `limit()` хотя бы у одного шага, иначе `invalid_query`. `{ confirm: true }` без `expect` —
+     * `invalid_query` (`write.confirm_without_expect`); осознанно удалить текущий состав целей без сверки (и без фильтра —
+     * все строки) — `{ confirm: true, all: true }`.
      */
-    delete(opts?: {
-        confirm?: boolean;
-        all?: boolean;
-        reason?: string;
-    }): Chain;
+    delete(opts?: DeleteOptions): Chain;
     /** Чтение с блокировкой строк последнего шага до конца db.begin() (rows, first, ids). */
     forUpdate(): Chain;
-    /** Восстановить удалённые объекты шага: последний снимок новой версией (id прежний). */
-    restore(opts?: {
-        reason?: string;
-    }): Chain;
+    /**
+     * Восстановить удалённые объекты шага: последний снимок новой версией (id прежний). `{ expect }` — надгробия `{ id, rev }`
+     * из ответа `delete()` или `withDeleted()`: восстанавливаются только цели из `expect`, и только если последняя версия
+     * каждой — та же; иначе ничего не восстановлено: уже восстановлена — `not_deleted` (`write.restore_already`), id занял
+     * новый объект — `not_deleted` (`write.restore_id_taken`), прочее (удалена снова, менялась) — `conflict`
+     * (`write.restore_stale`); причины по целям — `err.detail.stale`. `{ expect, partial: true }` — восстановить то, что
+     * можно: остальные цели приходят строками `{ …строка, $action: 'skip', $why }`. Без `expect` — `invalid_query`
+     * (`write.restore_without_expect`), и для явных id; осознанно вернуть все удалённые цели шага без сверки —
+     * `{ all: true }`.
+     */
+    restore(opts: RestoreOptions): Chain;
     /** Кэш результатов (§2.12): ответ хранится в памяти процесса ttl секунд (по умолчанию 60). */
     cache(opts?: {
         ttl?: number;
@@ -196,8 +218,8 @@ export interface ChainCore {
 }
 /**
  * Шаг цепочки — имя класса, его алиаса или роли с необязательным фильтром: `db.Shop(id).Product({ price: gt(1000) })`;
- * каждый следующий шаг переходит по ссылкам от объектов предыдущего. После `create()`, `update()` или `upsert()` имя
- * роли без вызова задаёт ссылку записываемой строки: `.Роль.set(…)`, `.Роль.unset()`, у множественной ссылки ещё
+ * каждый следующий шаг переходит по концам от объектов предыдущего. После `create()`, `update()` или `upsert()` имя
+ * роли без вызова задаёт конец записываемой строки: `.Роль.set(…)`, `.Роль.unset()`, у множественного конца ещё
  * `.Роль.add(…)` и `.Роль.remove(…)`.
  */
 export type StepFn = ((filter?: Filter) => Chain) & {
@@ -209,7 +231,7 @@ export type StepFn = ((filter?: Filter) => Chain) & {
 export type Chain = ChainCore & {
     [className: string]: StepFn;
 };
-/** Любая цепочка — с типами по моделям (`TypedChain`) или без них (`Chain`): аргумент `entity()` и значение слота. */
+/** Любая цепочка — с типами по моделям (`TypedChain`) или без них (`Chain`): аргумент `entity()` и значение шага роли (`.Роль.set(цепочка)`). */
 export type ChainRef = Pick<ChainCore, 'ids'>;
 /** Внутренний канал: план чужой ленивой цепочки (entity()). */
 export declare const PLAN: unique symbol;
@@ -220,6 +242,11 @@ export declare function lookupStep(reg: Registry, name: string): {
     cls: ClassInfo;
     role?: string;
 } | undefined;
+/**
+ * Цепочка в читаемом виде: `Shop({"name":"A"}).Product.limit(10).rows()`. Фильтры — значениями (поля-секреты — '***'),
+ * данные записи — только именами полей.
+ */
+export declare function chainText(log: Log, steps: readonly Step[], mods?: ChainMods, term?: string, args?: readonly unknown[]): string;
 export declare function makeChain(ctx: ChainCtx, steps: Step[], mods: ChainMods, nodes?: NodeMap): Chain;
 /**
  * Батч: очередь планов; каждый вызов класса — своя ссылка на очередь (свой план). run() исполняет очередь