letopis 1.3.0 → 1.4.1

package/dist/admin.js

@@ -1,6 +1,8 @@
 import { LetopisError, fromDbError } from './errors.js';
 import { runTx } from './tx.js';
 import { CHAIN_METHODS, DB_METHODS } from './types.js';
+/** Внутренняя опция maintain(): остановка запуска по расписанию — текущая пачка доделывается, следующая не начинается. */
+export const MAINTAIN_STOP = Symbol('letopis.maintain.stop');
 const SYSTEM_CLASSES = new Set(['Class', 'Account', 'member', 'Resource', 'rule']);
 const one = async (a, text, params = []) => a.exec.run(async (q) => (await q.unsafe(text, params))[0]);
 export async function verify(a, opts = {}) {
@@ -24,6 +26,9 @@ export async function maintain(a, opts = {}) {
     const report = { skipped: false, sessions: 0, codes: 0, thinned: 0, batches: 0, more: false, queue: 0 };
     const max = opts.batches ?? 100;
     for (let i = 0; i < max; i++) {
+        // запуск по расписанию остановлен (close()): следующая пачка не начинается, отчёт — с more: true
+        if (i > 0 && opts[MAINTAIN_STOP]?.())
+            break;
         // блокировку берёт сама maintain() базы — строку-замок, которую посторонняя роль не займёт; занята — null
         const [{ r }] = await runTx(a.txc, (q) => q.unsafe(`select ${a.S}.maintain($1::text::timestamptz, $2::int) as r`, [now, opts.limit ?? 10_000]));
         if (r === null) {
@@ -50,28 +55,49 @@ export async function maintain(a, opts = {}) {
 export function queueWarning(queue) {
     return queue > 0.5 ? `letopis: очередь сигналов PostgreSQL заполнена на ${(queue * 100).toFixed(0)} % — проверьте зависших слушателей` : null;
 }
-/** Интервал расписания: число мс или '30s', '15m', '1h', '1d'. */
+/** Самый длинный интервал таймера Node.js — 2³¹−1 мс (около 24,8 суток): дольше таймер не ждёт и срабатывает сразу. */
+const MAX_TIMER_MS = 2 ** 31 - 1;
+/**
+ * Интервал расписания: число мс или строка '500ms', '30s', '15m', '1h', '1d' — конечный, от 1 мс до 2³¹−1 мс (около 24
+ * суток); иначе invalid_data. Ноль, отрицательное, NaN и слишком длинный интервал таймер Node.js превращает в 1 мс —
+ * обслуживание шло бы без перерыва.
+ */
 export function parseInterval(v) {
+    let ms = Number.NaN;
     if (typeof v === 'number')
-        return v;
-    const m = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/.exec(v.trim());
-    if (!m)
-        throw new LetopisError('invalid_data', `интервал ${v}: число мс или '30s', '15m', '1h', '1d'`);
-    const n = Number(m[1]);
-    return n * { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+        ms = v;
+    else if (typeof v === 'string') {
+        const m = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/.exec(v.trim());
+        if (m)
+            ms = Number(m[1]) * { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+    }
+    if (!Number.isFinite(ms) || ms < 1 || ms > MAX_TIMER_MS) {
+        const shown = typeof v === 'string' ? `'${v}'` : typeof v === 'number' || typeof v === 'boolean' || v == null ? String(v) : typeof v;
+        throw new LetopisError('invalid_data', `интервал ${shown}: число мс или строка '30s', '15m', '1h', '1d' — от 1 мс до 2³¹−1 мс (около 24 суток)`);
+    }
+    return ms;
 }
-/** Запуск maintain() по расписанию (connect({ maintain: '1h' })): ошибки — предупреждением. */
-export function scheduleMaintain(run, every) {
-    const ms = parseInterval(every);
-    let busy = false;
+/**
+ * Запуск maintain() по расписанию (connect({ maintain: '1h' }); ms — уже проверенный интервал): ошибки — предупреждением,
+ * следующий запуск не начинается, пока идёт прежний. Возвращает остановку: она снимает таймер, просит идущий запуск не
+ * начинать новых пачек и ждёт его конца — close() закрывает пул после неё, а не посреди пачки.
+ */
+export function scheduleMaintain(run, ms) {
+    let stopped = false;
+    let current = null;
     const timer = setInterval(() => {
-        if (busy)
+        if (current || stopped)
             return;
-        busy = true;
-        run().catch((e) => console.warn(`letopis: maintain по расписанию: ${e.message}`)).finally(() => (busy = false));
+        current = run(() => stopped)
+            .then(() => { }, (e) => console.warn(`letopis: maintain по расписанию: ${e.message}`))
+            .finally(() => (current = null));
     }, ms);
     timer.unref?.();
-    return () => clearInterval(timer);
+    return async () => {
+        stopped = true;
+        clearInterval(timer);
+        await current;
+    };
 }
 /**
  * Сброс (этап 6, п. 6). Предохранители — в базе: флаг allowReset установки, право letopis.reset,
@@ -163,7 +189,7 @@ export function describe(a) {
     })).sort((x, y) => Number(x.system) - Number(y.system) || x.name.localeCompare(y.name));
     return { schema: a.schema, tenant: a.tenant(), classes, methods: { chain: CHAIN_METHODS, db: DB_METHODS } };
 }
-/** Описание модели текстом для языковых моделей (llms.txt). */
+/** Описание модели текстом для языковых моделей. */
 export function describeText(d) {
     const out = [`# letopis: модель схемы ${d.schema}`, '',
         'Цепочка: db.Класс(фильтр).Связь().Класс().rows(); запись — create, update, upsert, delete; история — versions(), asOf(), withDeleted().', ''];

package/dist/auth.d.ts

@@ -15,6 +15,24 @@ export interface LoginResult {
     account: string;
     token: string;
 }
+/** Сведения о сессии по её токену (`db.auth.session()`). Время — строкой ISO 8601. */
+export interface SessionInfo {
+    /** Аккаунт сессии. */
+    account: string;
+    /** Рабочий арендатор сессии: выбранный `auth.switch()` или собственный арендатор аккаунта. */
+    tenant: string;
+    /** Членство в рабочем арендаторе цело и арендатор включён; в собственном арендаторе — всегда true. */
+    member: boolean;
+    /** Когда сессия истечёт, если ею не пользоваться (подключение продлевает её само). */
+    expiresAt: string;
+    /** Время входа. */
+    loginAt: string;
+    /**
+     * Способы входа: вид креда, по которому вошли (`PASSWORD`, `APIKEY`, `KEYSECRET`, `OTP`, `TELEGRAM` и т. п.), `SERVICE` —
+     * сессию выпустил сервис (`sessionFor()`), `TOTP` — пройден второй фактор. У сессии от `createTenant()` список пуст.
+     */
+    methods: string[];
+}
 /** Кред без секретного материала. */
 export interface Credential {
     id: string;
@@ -28,7 +46,7 @@ export interface Credential {
     expires_at: string | null;
 }
 export interface AuthApi {
-    /** Пароль (и любой «логин/пароль»: kind — PASSWORD, EMAIL, …): создать или заменить. Смена гасит остальные сессии аккаунта. */
+    /** Пароль (и любой «логин/пароль»: `kind` — `PASSWORD`, `EMAIL`, …): создать или заменить. Смена гасит остальные сессии аккаунта. */
     setPassword(a: {
         account: AccountRef;
         identifier: string;
@@ -38,9 +56,9 @@ export interface AuthApi {
         keepCurrent?: boolean;
     }): Promise<string>;
     /**
-     * Вход по паролю — для сервиса с правом auth.password и auth.session. Неудача — null. С `totp` после
-     * верного пароля база проверяет код TOTP аккаунта (право auth.totp; счётчик неудач и блокировка — общие
-     * с verifyTotp): верный — сессия со способами [kind, 'TOTP'], неверный или повторный — null.
+     * Вход по паролю — для сервиса с правом `auth.password` и `auth.session`. Неудача — `null`. С `totp` после
+     * верного пароля база проверяет код TOTP аккаунта (право `auth.totp`; счётчик неудач и блокировка — общие
+     * с `verifyTotp()`): верный — сессия со способами `[kind, 'TOTP']`, неверный или повторный — `null`.
      */
     verifyPassword(a: {
         identifier: string;
@@ -70,7 +88,10 @@ export interface AuthApi {
         id: string;
     }>;
     verifyKeySecret(key: string, secret: string): Promise<LoginResult | null>;
-    /** TOTP: секрет в base32 и ссылка otpauth:// для QR; фактор включает первая успешная проверка. */
+    /**
+     * Подключает второй фактор TOTP: выдаёт секрет (base32) и адрес `otpauth://` для QR-кода в приложении-аутентификаторе.
+     * Фактор включится после первой верной проверки кода — `verifyTotp()` или входа с `totp`.
+     */
     enrollTotp(a: {
         account: AccountRef;
         issuer?: string;
@@ -85,7 +106,7 @@ export interface AuthApi {
         window?: number;
     }): Promise<boolean>;
     totpEnabled(account: AccountRef): Promise<boolean>;
-    /** Одноразовый код для доставки сервисом (право auth.otp). */
+    /** Одноразовый код для доставки сервисом (право `auth.otp`). */
     issueOtp(a: {
         account: AccountRef;
         identifier: string;
@@ -96,13 +117,19 @@ export interface AuthApi {
     }): Promise<{
         code: string;
     }>;
-    /** Вход по одноразовому коду: успех и перебор (лимит задал выпуск, 1–10, по умолчанию 5) сжигают код. */
+    /**
+     * Вход по одноразовому коду: верный код открывает новую сессию. Код сгорает после верного ввода и после исчерпания
+     * неверных попыток — их число задаёт `issueOtp({ maxAttempts })`.
+     */
     verifyOtp(a: {
         identifier: string;
         code: string;
         kind?: string;
     }): Promise<LoginResult | null>;
-    /** Внешняя identity (TELEGRAM, GOOGLE, SSO): токен проверяет сервис, здесь — связка. */
+    /**
+     * Привязывает к аккаунту внешнюю учётную запись — например, для входа через Telegram, Google или SSO. Входят по привязке
+     * через `lookup()`; токен внешнего сервиса ваш сервис проверяет сам.
+     */
     link(a: {
         account: AccountRef;
         kind: string;
@@ -110,7 +137,11 @@ export interface AuthApi {
         meta?: Record<string, unknown>;
         confirmed?: boolean;
     }): Promise<string>;
-    /** Вход по identity — для сервиса с правами auth.identity и auth.session; `totp` — как у verifyPassword. */
+    /**
+     * Вход через привязанную внешнюю учётную запись: находит аккаунт по виду и id у внешнего сервиса и открывает ему новую
+     * сессию. Вызывает сервис с правами `auth.identity` и `auth.session`, когда уже сам проверил токен внешнего сервиса;
+     * `totp` — как у `verifyPassword()`.
+     */
     lookup(a: {
         kind: string;
         identifier: string;
@@ -118,36 +149,48 @@ export interface AuthApi {
         ttl?: number;
         totp?: string;
     }): Promise<LoginResult | null>;
-    /** Креды аккаунта без секретов. */
+    /** Способы входа (креды) аккаунта — без хэшей и секретов. */
     credentials(account: AccountRef): Promise<Credential[]>;
     /**
      * Удалить кред. Ключ API и пара ключ + секрет гасят только свои сессии, прочие креды — остальные сессии
-     * аккаунта; текущая гаснет, если keepCurrent: false. Свои ключи сервис отзывает сам; последний
-     * действующий ключ сервиса не отзывается (acl_denied).
+     * аккаунта; текущая гаснет, если `keepCurrent: false`. Свои ключи сервис отзывает сам; последний
+     * действующий ключ сервиса не отзывается (`acl_denied`).
      */
     revokeCredential(id: string, opts?: {
         keepCurrent?: boolean;
     }): Promise<boolean>;
-    /** Признаки креда confirmed и enabled (право auth.credential). */
+    /** Признаки креда `confirmed` и `enabled` (право `auth.credential`). */
     setFlags(id: string, flags: {
         confirmed?: boolean;
         enabled?: boolean;
     }): Promise<boolean>;
-    /** Короткая сессия пользователя для другого процесса (право auth.session). */
+    /** Сессия пользователя для другого процесса (право `auth.session`); срок — `ttl` в секундах, по умолчанию 7 суток. */
     sessionFor(account: AccountRef, opts?: {
         ttl?: number;
     }): Promise<string>;
+    /**
+     * Сведения о сессии по её токену — для сервиса, который держит токен пользователя (например, в cookie): чья это
+     * сессия, в каком арендаторе она работает, цело ли там членство, когда истечёт, когда и как был вход. Подключение
+     * по этому токену не открывается, срок сессии не продлевается. Вызывает сервис или системный администратор
+     * (право `auth.session`).
+     * @param token Токен сессии пользователя — тот, что выдали вход или `sessionFor()`.
+     * @returns Сведения о сессии или `null`: токен неверный, сессия погашена или истекла, аккаунт отключён — причина
+     * не различается.
+     * @throws LetopisError `acl_denied` — у вызывающего нет права `auth.session` (например, это обычный пользователь);
+     * `no_session` — у подключения нет действующей сессии.
+     */
+    session(token: string): Promise<SessionInfo | null>;
     /** Продлить текущую сессию; новый срок — от сейчас. */
     refresh(opts?: {
         ttl?: number;
     }): Promise<string>;
     /** Выход: погасить текущую сессию. */
     revoke(): Promise<boolean>;
-    /** Выход везде: все сессии аккаунта (чужого — с правом auth.session). */
+    /** Выход везде: все сессии аккаунта (чужого — с правом `auth.session`). */
     revokeAll(account?: AccountRef): Promise<number>;
     /** Переключить арендатора сессии: собственный или по членству. */
     switch(tenant: string): Promise<void>;
-    /** Арендаторы, доступные аккаунту сессии: собственный (owner) и по членству. */
+    /** Арендаторы, доступные аккаунту сессии: собственный (`owner`) и по членству. */
     tenants(): Promise<{
         tenant: string;
         roles: string[];
@@ -155,7 +198,8 @@ export interface AuthApi {
     /**
      * Удалить аккаунт (этап 6; accounts.purge 0.21): системный администратор или владелец его
      * арендатора; себя и последнего владельца арендатора — нельзя. Данные арендатора стираются,
-     * владение строками в чужих арендаторах переходит им, сессии гаснут, креды удаляются.
+     * владение строками в чужих арендаторах переходит им, сессии гаснут, креды удаляются. Владелец стирает
+     * и арендатора, в котором работает: его сессия возвращается в личный арендатор.
      */
     purgeAccount(account: AccountRef): Promise<{
         account: string;

package/dist/auth.js

@@ -27,7 +27,12 @@ export async function verifyHash(password, stored) {
     if (algo !== 'scrypt' || !hashB64)
         return false;
     const want = Buffer.from(hashB64, 'base64');
-    const got = await scryptAsync(password, Buffer.from(saltB64, 'base64'), want.length, { N: Number(N), r: Number(r), p: Number(p), maxmem: SCRYPT.maxmem });
+    // N, r, p — из строки хэша (подходят и хэши, импортированные из других систем), память — не больше 64 МБ: хэш,
+    // которому нужно больше, или с недопустимыми параметрами scrypt Node.js отвергает — это понятная ошибка, а не «неверный
+    // пароль» (false). Текст Node.js в сообщение не идёт: он зависит от сборки OpenSSL
+    const got = await scryptAsync(password, Buffer.from(saltB64, 'base64'), want.length, { N: Number(N), r: Number(r), p: Number(p), maxmem: SCRYPT.maxmem }).catch(() => {
+        throw new LetopisError('invalid_data', `хэш пароля: параметры scrypt N=${N}, r=${r}, p=${p} недопустимы или требуют больше 64 МБ памяти`);
+    });
     return got.length === want.length && timingSafeEqual(got, want);
 }
 /** Холостая проверка: «идентификатора нет» отвечает не быстрее, чем «пароль неверен». */
@@ -178,6 +183,11 @@ function makeAuthCore(S, exec, onSwitch, canSwitch) {
         async sessionFor(account, opts) {
             return (await login(accId(account), opts?.ttl, ['SERVICE'])).token;
         },
+        async session(token) {
+            const r = (await one(`select ${S}.auth_session_info($1) as r`, [token])).r;
+            // jsonb хранит ключи в своём порядке — объект собирается в порядке описания SessionInfo
+            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;
         },
@@ -198,7 +208,11 @@ function makeAuthCore(S, exec, onSwitch, canSwitch) {
             return rows.map((r) => ({ tenant: r.tenant, roles: r.roles }));
         },
         async purgeAccount(account) {
-            return (await one(`select ${S}.account_purge($1::uuid) as r`, [accId(account)])).r;
+            const r = (await one(`select ${S}.account_purge($1::uuid) as r`, [accId(account)])).r;
+            // стёрт арендатор, в котором работала сессия корня: база вернула её в личный арендатор — перечитать
+            if (canSwitch)
+                await onSwitch();
+            return r;
         },
     };
 }

package/dist/cache.d.ts

@@ -4,7 +4,11 @@ export declare const ACL_CLASSES: ReadonlySet<string>;
 export interface CacheOptions {
     /** Срок ответа по умолчанию, секунды (60). */
     ttl?: number;
-    /** Работать без слушателя сигналов — только по сроку (пул в режиме транзакций, §2.12). */
+    /**
+     * Включает кэш, даже когда подключение не слушает сигналы базы: `connect({ listen: false })` (например, за PgBouncer в
+     * режиме транзакций) или установка с `up({ signals: 'none' })`; без опции кэш тогда выключен. Такой ответ живёт до
+     * конца срока: записи других процессов его не сбрасывают, записи этого подключения — сбрасывают (§2.12).
+     */
     ttlOnly?: boolean;
     /** Не больше ответов в памяти (10 000): старые вытесняются. */
     max?: number;

package/dist/chain.d.ts

@@ -32,6 +32,11 @@ export interface ChainCtx {
 /** План в очереди батча; steps обновляется по мере роста цепочки. */
 export interface BatchEntry {
     steps: Step[];
+    /** Модификатор выборки, поставленный сразу после последнего глагола плана: run() откажет (`afterVerbError`). */
+    loose?: {
+        name: string;
+        verb: string;
+    };
 }
 /** Ссылка цепочки на очередь: первый глагол регистрирует план, следующие — обновляют. */
 export interface BatchRef {
@@ -47,9 +52,16 @@ export type Batch = {
     [className: string]: StepFn;
 };
 export interface ChainCore {
-    /** Пути: [{ шаг1: Row, шаг2: Row, … }] — узлы каждого варианта. */
+    /**
+     * Все пути цепочки. Путь — строки всех шагов, по одной на шаг, связанные ссылками; приходит объектом, где ключ — имя
+     * шага (или имя из `alias()`), а значение — строка этого шага: `{ Shop: …, Product: … }`. Если к объекту последнего
+     * шага ведут несколько путей, придут все.
+     */
     paths(): Promise<Path[]>;
-    /** Уникальные сущности последнего шага. */
+    /**
+     * Строки объектов последнего шага — каждый объект один раз, сколько бы путей к нему ни вело. Если цепочка кончается
+     * глаголом записи — строки этого глагола.
+     */
     rows(): Promise<Row[]>;
     first(): Promise<Row | null>;
     ids(): Promise<string[]>;
@@ -68,41 +80,92 @@ export interface ChainCore {
     diff(opts?: DiffOptions): Promise<DiffResult[]>;
     /** Кто, когда и почему последним изменил каждое поле версии (по умолчанию текущей), план 1.1. */
     blame(opts?: BlameOptions): Promise<BlameResult[]>;
-    /** Агрегаты по полю последнего шага ('data.<путь>') — по сущностям, считает база. */
+    /**
+     * Сумма поля `'data.<путь>'` по объектам последнего шага: значения приводятся к числу, складывает база. `limit()` и
+     * `offset()` на итог не влияют; нет ни одного значения — `null`.
+     */
     sum(field: string): Promise<number | null>;
+    /**
+     * Среднее значение поля `'data.<путь>'` по объектам последнего шага: значения приводятся к числу, считает база.
+     * `limit()` и `offset()` на итог не влияют; нет ни одного значения — `null`.
+     */
     avg(field: string): Promise<number | null>;
+    /**
+     * Наименьшее значение поля `'data.<путь>'` среди объектов последнего шага; считает база. Числа сравниваются как числа
+     * и приходят числом, даты — как даты, поле без описания в классе — как текст. `limit()` и `offset()` на итог не
+     * влияют; нет ни одного значения — `null`.
+     */
     min(field: string): Promise<unknown>;
+    /**
+     * Наибольшее значение поля `'data.<путь>'` среди объектов последнего шага; считает база. Числа сравниваются как числа
+     * и приходят числом, даты — как даты, поле без описания в классе — как текст. `limit()` и `offset()` на итог не
+     * влияют; нет ни одного значения — `null`.
+     */
     max(field: string): Promise<unknown>;
+    /**
+     * Сколько объектов последнего шага с каждым значением поля `'data.<путь>'`: объект «значение → число», объекты без
+     * значения — под ключом `'null'`. Перед `countBy()` `limit()` и `offset()` отбирают группы — от самых частых значений.
+     */
     countBy(field: string): Promise<Record<string, number>>;
+    /**
+     * Не больше n строк ответа: объектов последнего шага, у `paths()` — путей, у `versions()` — версий, перед `countBy()` —
+     * групп. До глагола сужает его цели. Сразу после глагола перед `rows`, `first`, `ids`, `count` и `paths` —
+     * `invalid_query`: глагол уже прошёл по всем целям, сужать нечего.
+     */
     limit(n: number): Chain;
+    /** Пропустить первые n строк ответа — тех же, что считает `limit()`; где действует — как у `limit()`. */
     offset(n: number): Chain;
     /** Сортировка по полю последнего шага: 'at' | 'rev' | 'id' | 'data.<путь>'. */
     sort(field: string, dir?: 'asc' | 'desc' | boolean): Chain;
     /** Срез «как было на момент T»: версии журнала. */
     asOf(t: string | Date): Chain;
-    /** Keyset-пагинация: строго после курсора (cursorOf). Требует sort(). */
+    /**
+     * Постраничный вывод по курсору: ответ начинается строго после строки, на которой кончилась прошлая страница, в
+     * порядке `sort()` (без `sort()` — ошибка `invalid_query`). Курсор этой строки даёт `cursorOf(строка, поле)` с тем же
+     * полем, что в `sort()`.
+     */
     after(cursor: Cursor): Chain;
-    /** Последний шаг включает удалённые (надгробия, $deleted). */
+    /**
+     * Последний шаг находит и удалённые объекты. Удалённый объект приходит надгробием — своей последней версией, версией
+     * удаления, — с `$deleted: true`.
+     */
     withDeleted(): Chain;
     /** Дети любой глубины на переходе к тому же классу; $depth в строке. */
     deep(max?: number): Chain;
-    /** Только сам класс шага, без потомков. */
+    /**
+     * Последний шаг находит объекты только своего класса — без классов-наследников (`extends` в модели), которых без
+     * `exact()` находит тоже.
+     */
     exact(): Chain;
     /** Ключ текущего шага в путях. */
     alias(name: string): Chain;
-    /** Колонка tags: строка | список (все) | has / hasAny / hasAll. */
+    /**
+     * Теги строки. В чтении и перед глаголами — отбор: строка или список — строки со всеми этими тегами (пустой список
+     * подходит любой строке), `has`, `hasAny`, `hasAll` — оператором. Перед `create()` и `upsert()` — теги новой строки
+     * (строка или список). Перед `update()` строка или список и отбирают, и заменяют теги целиком, а оператор только
+     * отбирает.
+     */
     tags(v: string | string[] | object): Chain;
-    /** Колонка owner. */
+    /**
+     * Владелец строк последнего шага (поле `owner`). В чтении и перед `update()`, `delete()` и другими глаголами — отбор:
+     * только строки этого владельца; перед `create()` и `upsert()` — владелец новой строки (существующей строке `upsert()`
+     * владельца не меняет).
+     */
     owner(v: string | {
         id: string;
     }): Chain;
-    /** Вставить узел: ленивая цепочка-паттерн или строка ответа; та же переменная повторно — возврат к её узлу. */
+    /**
+     * Добавляет в цепочку шаги из строки ответа (шаг её класса с её id) или из ещё не исполненной цепочки без глаголов
+     * записи (все её шаги как есть); `limit()`, `sort()`, `asOf()` и другие модификаторы всей цепочки не переносятся. Та
+     * же цепочка (та же переменная) второй раз в одном пути шагов не добавляет, а возвращает к своему последнему шагу:
+     * следующий шаг пойдёт от него.
+     */
     entity(x: Chain | Row): Chain;
     /** Создать объект: концы — из пути и слотов; занятый ключ — ошибка exists с id. */
     create(data?: Record<string, unknown>, opts?: {
         reason?: string;
     }): Chain;
-    /** Новая версия каждой цели шага: слияние патча в базе; inc(n) — приращение; { rev } — строгий режим. */
+    /** Новая версия каждой цели шага: слияние патча в базе; inc(n) — приращение; { rev } — с проверкой версии. */
     update(patch?: Record<string, unknown>, opts?: {
         rev?: number;
         reason?: string;
@@ -111,7 +174,11 @@ export interface ChainCore {
     upsert(data: Record<string, unknown>, opts?: {
         reason?: string;
     }): Chain;
-    /** Удалить цели шага с каскадом; без { confirm: true } — превью замыкания ($action). */
+    /**
+     * Удаляет цели шага; строки, которые на них ссылаются, база удаляет вместе с ними, отвязывает или не даёт удалить цель —
+     * как задано в `onDelete` их ссылок. Без `{ confirm: true }` — предпросмотр удаления: ничего не удаляется, терминал
+     * вернёт все строки, которых оно коснулось бы, у каждой `$action` — что с ней будет.
+     */
     delete(opts?: {
         confirm?: boolean;
         reason?: string;
@@ -130,12 +197,19 @@ export interface ChainCore {
     restore(opts?: {
         reason?: string;
     }): Chain;
-    /** Стереть историю удалённых объектов шага; без { confirm: true } — превью ($versions). */
+    /**
+     * Стирает историю удалённых объектов шага: все их версии в журнале, от каждого остаётся одна запись `purge`. Удалённые
+     * объекты шаг находит сам, без `withDeleted()`. Без `{ confirm: true }` — предпросмотр: ничего не стирается, терминал
+     * вернёт надгробия с `$versions` — сколько версий сотрётся.
+     */
     purge(opts?: {
         confirm?: boolean;
         reason?: string;
     }): Chain;
-    /** Новое значение ключа: строка с новым id, ссылки переведены (поля — данные, роли — концы). */
+    /**
+     * Новое значение ключа объектов шага. id вычисляется из ключа, поэтому объект получает новый id: ссылки других строк
+     * на него переводятся на новый id, а журнал связывает старый id с новым.
+     */
     rekey(patch: Record<string, unknown>, opts?: {
         reason?: string;
     }): Chain;
@@ -145,8 +219,10 @@ export interface ChainCore {
     }): Chain;
 }
 /**
- * Шаг цепочки: вызов — переход (фильтр); после глагола записи без вызова — слот конца версии:
- * `.Роль.set(id | [id] | строка | цепочка)`, `.unset()`, у множественного конца `.add()` и `.remove()`.
+ * Шаг цепочки — имя класса, его алиаса или роли с необязательным фильтром: `db.Shop(id).Product({ price: gt(1000) })`;
+ * каждый следующий шаг переходит по ссылкам от объектов предыдущего. После `create()`, `update()` или `upsert()` имя
+ * роли без вызова задаёт ссылку записываемой строки: `.Роль.set(…)`, `.Роль.unset()`, у множественной ссылки ещё
+ * `.Роль.add(…)` и `.Роль.remove(…)`.
  */
 export type StepFn = ((filter?: Filter) => Chain) & {
     set(value: unknown): Chain;

package/dist/chain.js

@@ -132,6 +132,27 @@ async function read(ctx, steps, mods, mode, agg) {
     const ev = mode === 'countPaths' ? 'count' : mode;
     return exec(ctx, q, ev, steps, mods).then((res) => ({ q, res }));
 }
+/** Модификатор выборки, заданный в mods, — именем метода цепочки; forUpdate() отказывает сам (lock_unsupported). */
+function modName(mods) {
+    const key = Object.keys(mods).find((k) => mods[k] !== undefined && k !== 'forUpdate');
+    return key === 'order' || key === 'desc' ? 'sort' : key;
+}
+function afterVerbError(name, verb) {
+    return new LetopisError('invalid_query', `${name}() после ${verb}() ни на что не действует: глагол проходит по всем целям шага, а ответ — его строки. ` +
+        `Цели сужают limit(), offset() и sort() до глагола: db.Класс(…).limit(n).${verb}(…)`);
+}
+/**
+ * Терминалы rows, first, ids, count и paths цепочки, которая кончается глаголом, отдают строки самой правки.
+ * Модификатор выборки между глаголом и терминалом ни на что не подействовал бы: limit резал бы только ответ, хотя
+ * правка прошла по всем целям, остальные молча пропускались. Поэтому — отказ до записи. После глагола модификатор
+ * относится к чтению за ним (шаг класса, versions(), diff(), blame(), агрегаты) или сужает цели следующего глагола.
+ */
+function checkAfterVerb(steps, mods) {
+    const op = steps[steps.length - 1]?.op;
+    const name = op ? modName(mods) : undefined;
+    if (op && name)
+        throw afterVerbError(name, op.kind);
+}
 /**
  * Цепочка с глаголами: весь план одной транзакцией (§2.5). Результат приводится к виду ответа
  * чтения (строки rows/paths, id, n, агрегаты), чтобы терминалы разбирали его одинаково.
@@ -279,6 +300,13 @@ function classProp(ctx, name, found, ownerSteps, mods, nodes) {
     });
 }
 export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
+    // батч: терминала нет, план исполнит run() — он и откажет, если цепочка кончилась модификатором после глагола
+    // (как checkAfterVerb вне батча); следующий шаг или глагол забирает модификатор себе, и отметка снимается
+    if (ctx.batch?.entry) {
+        const op = steps[steps.length - 1]?.op;
+        const name = op ? modName(mods) : undefined;
+        ctx.batch.entry.loose = op && name ? { name, verb: op.kind } : undefined;
+    }
     const withLast = (patch) => {
         const lastOp = steps[steps.length - 1]?.op;
         if (lastOp)
@@ -369,21 +397,32 @@ export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
                     return entityStep;
                 case 'paths':
                     return async () => {
+                        checkAfterVerb(steps, mods);
                         // q === null — пути из результата глагола: строки уже готовы
                         const { q, res } = await read(ctx, steps, mods, 'paths');
                         return res.map((r) => Object.fromEntries(Object.entries(r.path).map(([k, v]) => [k, q === null ? v : toRow(v)])));
                     };
                 case 'rows':
-                    return async () => (await read(ctx, steps, mods, 'rows')).res.map(rowOf);
+                    return async () => {
+                        checkAfterVerb(steps, mods);
+                        return (await read(ctx, steps, mods, 'rows')).res.map(rowOf);
+                    };
                 case 'first':
                     return async () => {
+                        checkAfterVerb(steps, mods);
                         const { res } = await read(ctx, steps, { ...mods, limit: 1 }, 'rows');
                         return res[0] ? rowOf(res[0]) : null;
                     };
                 case 'ids':
-                    return async () => (await read(ctx, steps, mods, 'ids')).res.map((r) => r.id);
+                    return async () => {
+                        checkAfterVerb(steps, mods);
+                        return (await read(ctx, steps, mods, 'ids')).res.map((r) => r.id);
+                    };
                 case 'count':
-                    return async (opts) => (await read(ctx, steps, mods, opts?.paths ? 'countPaths' : 'count')).res[0].n;
+                    return async (opts) => {
+                        checkAfterVerb(steps, mods);
+                        return (await read(ctx, steps, mods, opts?.paths ? 'countPaths' : 'count')).res[0].n;
+                    };
                 case 'versions':
                     return async (opts) => {
                         warnNoHistory(steps, 'versions');
@@ -503,7 +542,11 @@ export function makeBatch(ctx, queue) {
             switch (prop) {
                 case 'run':
                     return async () => {
-                        const plans = queue.splice(0, queue.length).map((x) => x.steps);
+                        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);
                         if (!plans.length)

package/dist/cli.js

@@ -146,6 +146,12 @@ export async function main(argv) {
             console.log(JSON.stringify(r));
             return 0;
         }
+        if (cmd === 'describe' || cmd === 'types') {
+            // обе команды читают реестр сессии: без действующей сессии (токен истёк, погашен, неверен или не задан) он пуст,
+            // и команда выдала бы пустой результат с кодом 0, а с --out затёрла бы им файл. acl.check ничего не пишет, а без
+            // сессии отказывает no_session — тогда выход с кодом 1, файл не тронут
+            await db.acl.check('letopis.cli');
+        }
         if (cmd === 'describe') {
             const d = db.describe();
             const text = values.format === 'text' ? describeText(d) : JSON.stringify(d, null, 2);

package/dist/errors.d.ts

@@ -13,10 +13,10 @@ export declare class LetopisError extends Error {
     readonly detail: unknown;
     constructor(code: string, message: string, detail?: unknown);
 }
+/** Версия, в которой снято старое API (её берёт и контракт API — scripts/gen-api-contract.mjs). */
+export declare const REMOVED_IN = "1.0.0";
 /** Охранник снесённого API (план, этап 3, п. 11): понятная ошибка с версией и заменой. */
 export declare function removed(name: string, replacement: string): LetopisError;
-/** Метод зарезервирован, но появится на следующем этапе плана. */
-export declare function notYet(name: string, stage: number): LetopisError;
 /** Данные не проходят описание класса (`invalid_data`). */
 export declare class ValidationError extends LetopisError {
     readonly issues: Issue[];