letopis 3.0.0 → 3.0.1

package/dist/acl.d.ts

@@ -51,7 +51,7 @@ export interface AclRuleSpec {
 /** Правило арендатора в виде обёртки. */
 export interface AclRule {
     id: string;
-    /** Роль группы `role:<роль>:ACCOUNT`; null — группа не одной роли (все аккаунты или своя группа). */
+    /** Роль правила; null — правило не одной роли (все аккаунты или своя группа). */
     role: string | null;
     /** Группа всех аккаунтов арендатора: `authenticated:ACCOUNT` от createTenant или `everyone:ACCOUNT` обёртки. */
     everyone: boolean;
@@ -87,7 +87,9 @@ export interface AclApi {
     /** Запретить — те же правила с запретом: при равном весе запрет сильнее разрешения. */
     deny(spec: AclRuleSpec): Promise<AclRule[]>;
     /**
-     * Снять правила роли или всех аккаунтов — разрешения и запреты — для этих операций и целей; число снятых.
+     * Снять правила роли или всех аккаунтов — разрешения и запреты — для этих операций и целей; возвращает число снятых
+     * правил. Операции снимаются по очереди, и правило на несколько операций считается один раз: «можно всё» на чтение,
+     * запись и удаление от createTenant даёт 1.
      * `revoke({ everyone: true, read: '*', write: '*', delete: '*' })` снимает «можно всё» от createTenant: дальше права —
      * только по ролям.
      */

package/dist/admin.d.ts

@@ -30,6 +30,11 @@ export interface AdminCtx {
 export declare function maintain(a: AdminCtx): Promise<MaintainReport>;
 /** Предупреждение о заполненной очереди сигналов (§2.12): больше половины — зависший слушатель. */
 export declare function queueWarning(queue: number): string | null;
+/**
+ * Короткая форма интервала — '500ms', '30s', '15m', '1h', '1d' (дробное число тоже) — в миллисекундах; другая строка —
+ * null. Общая для connect({ maintain }) и срока ttl у auth (3.0.1).
+ */
+export declare function shortIntervalMs(v: string): number | null;
 /**
  * Интервал расписания: число мс или строка '500ms', '30s', '15m', '1h', '1d' — конечный, от 1 мс до 2³¹−1 мс (около 24
  * суток); иначе invalid_data. Ноль, отрицательное, NaN и слишком длинный интервал таймер Node.js превращает в 1 мс —

package/dist/admin.js

@@ -33,6 +33,14 @@ export function queueWarning(queue) {
 }
 /** Самый длинный интервал таймера Node.js — 2³¹−1 мс (около 24,8 суток): дольше таймер не ждёт и срабатывает сразу. */
 const MAX_TIMER_MS = 2 ** 31 - 1;
+/**
+ * Короткая форма интервала — '500ms', '30s', '15m', '1h', '1d' (дробное число тоже) — в миллисекундах; другая строка —
+ * null. Общая для connect({ maintain }) и срока ttl у auth (3.0.1).
+ */
+export function shortIntervalMs(v) {
+    const m = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/.exec(v.trim());
+    return m ? Number(m[1]) * { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]] : null;
+}
 /**
  * Интервал расписания: число мс или строка '500ms', '30s', '15m', '1h', '1d' — конечный, от 1 мс до 2³¹−1 мс (около 24
  * суток); иначе invalid_data. Ноль, отрицательное, NaN и слишком длинный интервал таймер Node.js превращает в 1 мс —
@@ -42,11 +50,8 @@ export function parseInterval(v) {
     let ms = Number.NaN;
     if (typeof v === 'number')
         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]];
-    }
+    else if (typeof v === 'string')
+        ms = shortIntervalMs(v) ?? Number.NaN;
     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 lerr('time.bad_interval', { value: shown });

package/dist/auth.d.ts

@@ -11,6 +11,17 @@ export declare function totpCode(secretBase32: string, atMs?: number): string;
 type AccountRef = string | {
     id: string;
 };
+/**
+ * Срок ttl (3.0.1) — интервал для базы: число секунд, короткая форма как у connect({ maintain }) ('30s', '15m', '2h',
+ * '1d') или строка-интервал PostgreSQL ('15 minutes') — её разбирает база, ошибку разбора переводит ttlGuard. Не задан —
+ * null (срок по умолчанию). Не число больше нуля, пустая строка, другой тип — invalid_data (access.bad_ttl).
+ */
+export declare function ttlOf(v: unknown, where: string): string | null;
+/**
+ * Строка ttl, которую не принял разбор интервала PostgreSQL (22007 — не интервал, 22008 и 22015 — вне диапазона), —
+ * invalid_data access.bad_ttl вместо сырой ошибки базы; прочие ошибки — как есть.
+ */
+export declare function ttlGuard<T>(run: Promise<T>, ttl: unknown, where: string): Promise<T>;
 /** Успешный вход: аккаунт и токен новой сессии. */
 export interface LoginResult {
     account: string;
@@ -46,6 +57,10 @@ export interface Credential {
     created_at: string;
     expires_at: string | null;
 }
+/**
+ * Вход, креды и сессии (`db.auth`). Срок `ttl` у входа, ключей, кодов и сессий — число секунд или строка: короткая форма
+ * `'15m'`/`'2h'`/`'30s'`/`'1d'` либо интервал PostgreSQL `'15 minutes'`; иное — `invalid_data`.
+ */
 export interface AuthApi {
     /** Пароль (и любой «логин/пароль»: `kind` — `PASSWORD`, `EMAIL`, …): создать или заменить. Смена гасит остальные сессии аккаунта. */
     setPassword(a: {
@@ -66,14 +81,14 @@ export interface AuthApi {
         password: string;
         kind?: string;
         requireConfirmed?: boolean;
-        ttl?: number;
+        ttl?: number | string;
         totp?: string;
     }): Promise<LoginResult | null>;
     /** Ключ API `lts_…`: отдаётся один раз. Себе сервис выпускает ключ сам по сессии своего ключа. */
     issueApiKey(a: {
         account: AccountRef;
         name?: string;
-        ttl?: number;
+        ttl?: number | string;
     }): Promise<{
         key: string;
         id: string;
@@ -112,7 +127,7 @@ export interface AuthApi {
         account: AccountRef;
         identifier: string;
         kind?: string;
-        ttl?: number;
+        ttl?: number | string;
         digits?: number;
         maxAttempts?: number;
     }): Promise<{
@@ -147,7 +162,7 @@ export interface AuthApi {
         kind: string;
         identifier: string;
         requireConfirmed?: boolean;
-        ttl?: number;
+        ttl?: number | string;
         totp?: string;
     }): Promise<LoginResult | null>;
     /** Способы входа (креды) аккаунта — без хэшей и секретов. */
@@ -165,9 +180,12 @@ export interface AuthApi {
         confirmed?: boolean;
         enabled?: boolean;
     }): Promise<boolean>;
-    /** Сессия пользователя для другого процесса (право `auth.session`); срок — `ttl` в секундах, по умолчанию 7 суток. */
+    /**
+     * Сессия пользователя для другого процесса (право `auth.session`). Срок `ttl` — число секунд или строка: короткая форма
+     * `'15m'`/`'2h'`/`'30s'`/`'1d'` либо интервал PostgreSQL `'15 minutes'`; по умолчанию 7 суток.
+     */
     sessionFor(account: AccountRef, opts?: {
-        ttl?: number;
+        ttl?: number | string;
     }): Promise<string>;
     /**
      * Сведения о сессии по её токену — для сервиса, который держит токен пользователя (например, в cookie): чья это
@@ -181,9 +199,12 @@ export interface AuthApi {
      * `no_session` — у подключения нет действующей сессии.
      */
     session(token: string): Promise<SessionInfo | null>;
-    /** Продлить текущую сессию; новый срок — от сейчас. */
+    /**
+     * Продлить текущую сессию; новый срок — от сейчас. `ttl` — число секунд или строка: короткая форма `'15m'`/`'2h'`/`'30s'`/`'1d'`
+     * либо интервал PostgreSQL `'15 minutes'`; по умолчанию 7 суток.
+     */
     refresh(opts?: {
-        ttl?: number;
+        ttl?: number | string;
     }): Promise<string>;
     /**
      * Выход. Без аргумента — погасить сессию этого подключения. С токеном — погасить сессию пользователя по её токену

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;
@@ -85,7 +86,44 @@ export function totpCode(secretBase32, atMs = Date.now()) {
 const accId = (a) => (typeof a === 'object' ? a.id : a);
 /** Логин без крайних пробелов (план 2.1, A12): « anna » и «anna» — один логин; не строка — как есть (отказ даст база). */
 const trimLogin = (v) => (typeof v === 'string' ? v.trim() : v);
-const ttlOf = (sec) => (sec === undefined ? null : `${Math.round(sec)} seconds`);
+/**
+ * Срок 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 = []) => {
@@ -95,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) {
@@ -104,7 +143,7 @@ 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 {
@@ -114,6 +153,7 @@ export function makeAuth(S, exec, onSwitch, canSwitch) {
             return r.id;
         },
         async verifyPassword(a) {
+            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);
@@ -124,10 +164,10 @@ export function makeAuth(S, exec, onSwitch, canSwitch) {
                 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;
@@ -152,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) {
@@ -162,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)]));
@@ -175,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;
@@ -183,7 +228,7 @@ 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(token) {
             // с токеном — выход пользователя по токену (план 2.1, A3): право auth.session, как у session(token)

package/dist/chain.d.ts

@@ -12,6 +12,8 @@ export interface ChainCtx {
     readonly exec: Executor;
     /** Арендатор сессии. */
     readonly tenant: () => string | null;
+    /** Аккаунт сессии (с имперсонацией — тот, от чьего имени): арендатор равен ему — личный арендатор. */
+    readonly account?: () => string | null;
     /** Фасад входит по токену сессии (connect({ token }), ключ API): без арендатора сессии шаг — sessionless(). */
     readonly hasToken?: () => boolean;
     /** Владелец новых строк по умолчанию (db.as(…, { owner })). */
@@ -59,7 +61,7 @@ export type Batch = {
 };
 export interface ChainCore {
     /**
-     * Все пути цепочки. Путь — строки всех шагов, по одной на шаг, связанные ссылками; приходит объектом, где ключ — имя
+     * Все пути цепочки. Путь — строки всех шагов, по одной на шаг, связанные концами; приходит объектом, где ключ — имя
      * шага (или имя из `alias()`), а значение — строка этого шага: `{ Shop: …, Product: … }`. Если к объекту последнего
      * шага ведут несколько путей, придут все.
      */
@@ -71,12 +73,12 @@ 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 и номеру версии. Шаг с явными id находит и
+     * Все версии объектов последнего шага (надгробия — $deleted), по id и номеру версии. Шаг с явными id находит и
      * удалённые объекты: `db.Класс(id).versions()` отдаёт историю удалённого.
      */
     versions(): Promise<Row[]>;
@@ -110,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;
@@ -163,7 +169,7 @@ export interface ChainCore {
      * следующий шаг пойдёт от него.
      */
     entity(x: ChainRef | Row): Chain;
-    /** Создать объект: концы — из пути и слотов; занятый ключ — ошибка exists с id. */
+    /** Создать объект: концы — из пути и шагов роли; занятый ключ — ошибка exists с id. */
     create(data?: Record<string, unknown>, opts?: {
         reason?: string;
     }): Chain;
@@ -183,10 +189,10 @@ export interface ChainCore {
     }): Chain;
     /**
      * Удаляет цели шага; строки, которые на них ссылаются, база удаляет вместе с ними, отвязывает или не даёт удалить цель —
-     * как задано в `onDelete` их ссылок. Без `{ confirm: true }` — предпросмотр удаления: ничего не удаляется, терминал
-     * вернёт все строки, которых оно коснулось бы, у каждой `$action` — что с ней будет. `{ confirm: true, expect: превью }`
-     * удаляет ровно показанное: в транзакции удаления превью строится заново и сравнивается с `expect` по `id`, `rev` и
-     * `$action`; расхождение — `conflict` (ничего не удалено, новое превью — `err.detail.preview`); цели сужают фильтр, id,
+     * как задано в `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 }`.
@@ -212,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) & {
@@ -225,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;

package/dist/chain.js

@@ -52,13 +52,21 @@ const stepNames = (reg) => reg.all().filter((c) => !isSystem(c)).flatMap((c) =>
  */
 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 — сессия, похоже, в личном арендаторе (api.unknown_step_no_classes).
+ * Неизвестный класс или роль — с похожими именами реестра (план 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 = (reg, name) => {
+const unknownName = (ctx, name) => {
+    const reg = ctx.reg;
     if (ARRAY_PROPS.has(name))
         throw lerr('api.chain_not_rows', { name });
-    const key = reg.all().every((c) => c.tenant === SYSTEM_ID) ? 'api.unknown_step_no_classes' : 'api.unknown_step';
+    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). */
@@ -288,10 +296,12 @@ function writeDetail(op, rows) {
             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) + 1;
+                    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') {
@@ -833,7 +843,7 @@ export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
         const found = lookupStep(ctx.reg, prop);
         if (!found && noSession(ctx, prop))
             return sessionless();
-        return classProp(ctx, prop, found ?? unknownName(ctx.reg, prop), steps, mods, nodes);
+        return classProp(ctx, prop, found ?? unknownName(ctx, prop), steps, mods, nodes);
     };
     const log = ctx.log;
     const handler = {
@@ -906,7 +916,7 @@ export function startStep(ctx, name) {
     const found = lookupStep(ctx.reg, name);
     if (!found && noSession(ctx, name))
         return sessionless();
-    return classProp(ctx, name, found ?? unknownName(ctx.reg, name), undefined, {}, NO_NODES);
+    return classProp(ctx, name, found ?? unknownName(ctx, name), undefined, {}, NO_NODES);
 }
 /** Старт пути с готового узла: db.entity(row | цепочка). */
 export function startEntity(ctx, x) {

package/dist/cli.js

@@ -26,14 +26,15 @@ import { connect } from './index.js';
 import { syncModels, generateTypes } from './sync.js';
 import { lerr, lmsg } from './errors.js';
 import { stderrLog } from './log.js';
-const USAGE = `letopis sync <модуль> --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--apply | --check]
-letopis types --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--out <файл>] [--system]
-letopis load <файлы…> --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--class <Класс>]
+const USAGE = `letopis sync <модуль> --dsn <строка> --schema <схема> (--token <токен> | --api-key <ключ>) [--apply | --check]
+letopis types --dsn <строка> --schema <схема> (--token <токен> | --api-key <ключ>) [--out <файл>] [--system]
+letopis load <файлы…> --dsn <строка> --schema <схема> (--token <токен> | --api-key <ключ>) [--class <Класс>]
   [--duplicates error|first|last] [--existing error|skip|update] [--commit-every <N>] [--initial]
-letopis maintain --dsn <строка> --schema <v2.имя> [--token <токен> | --api-key <ключ>]
-letopis mcp --dsn <строка> --schema <v2.имя> --token <токен пользователя> [--write]
+letopis maintain --dsn <строка> --schema <схема> [--token <токен> | --api-key <ключ>]
+letopis mcp --dsn <строка> --schema <схема> --token <токен пользователя> [--write]
   (или LETOPIS_DSN, LETOPIS_SCHEMA, LETOPIS_TOKEN; ключ сервиса --api-key не принимается)
-у любой команды: --log[=debug|info|warn|error|off] — события JSON-строками в stderr (без значения — info)`;
+у любой команды: --log[=debug|info|warn|error|off] — события JSON-строками в stderr (без значения — info)
+(<схема> — v2.<имя> или просто <имя>: shop — это v2.shop)`;
 /** Команды CLI: остальное — USAGE с кодом 2 ещё до подключения. */
 const COMMANDS = new Set(['sync', 'types', 'load', 'maintain', 'mcp']);
 const isModel = (v) => typeof v === 'object' && v !== null && typeof v.describe === 'function' && typeof v.name === 'string';
@@ -59,18 +60,47 @@ function logFlag(argv) {
     }
     return { args, log: level === undefined ? {} : { log: stderrLog, logLevel: level } };
 }
+/** Флаги CLI для parseArgs. */
+const OPTIONS = {
+    dsn: { type: 'string' }, schema: { type: 'string' }, token: { type: 'string' }, 'api-key': { type: 'string' },
+    apply: { type: 'boolean' }, out: { type: 'string' }, help: { type: 'boolean' },
+    class: { type: 'string' }, duplicates: { type: 'string' }, existing: { type: 'string' }, 'commit-every': { type: 'string' },
+    initial: { type: 'boolean' }, write: { type: 'boolean' }, system: { type: 'boolean' }, check: { type: 'boolean' },
+};
+/**
+ * Ошибка разбора аргументов parseArgs — русский текст каталога (английский текст Node — только для прочих ошибок);
+ * null — не ошибка разбора.
+ */
+function parseError(e) {
+    const code = e?.code;
+    const message = String(e?.message ?? '');
+    // имя флага или аргумент — первое в кавычках: «Unknown option '--aply'…», «Option '--dsn <value>' argument missing»
+    const quoted = (/'([^']*)'/.exec(message)?.[1] ?? '').split(' ')[0] ?? '';
+    if (code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION')
+        return lmsg('model.cli_unknown_flag', { flag: quoted });
+    if (code === 'ERR_PARSE_ARGS_INVALID_OPTION_VALUE') {
+        // строковому флагу не дали значения или булевому дали
+        return lmsg(/does not take/i.test(message) ? 'model.cli_flag_no_value' : 'model.cli_flag_needs_value', { flag: quoted });
+    }
+    if (code === 'ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL')
+        return lmsg('model.cli_unexpected_arg', { arg: quoted });
+    return null;
+}
 export async function main(argv) {
     const { args, log } = logFlag(argv);
-    const { values, positionals } = parseArgs({
-        args,
-        allowPositionals: true,
-        options: {
-            dsn: { type: 'string' }, schema: { type: 'string' }, token: { type: 'string' }, 'api-key': { type: 'string' },
-            apply: { type: 'boolean' }, out: { type: 'string' }, help: { type: 'boolean' },
-            class: { type: 'string' }, duplicates: { type: 'string' }, existing: { type: 'string' }, 'commit-every': { type: 'string' },
-            initial: { type: 'boolean' }, write: { type: 'boolean' }, system: { type: 'boolean' }, check: { type: 'boolean' },
-        },
-    });
+    let parsed;
+    try {
+        parsed = parseArgs({ args, allowPositionals: true, options: OPTIONS });
+    }
+    catch (e) {
+        const text = parseError(e);
+        if (text === null)
+            throw e;
+        // код выхода 1 — как у прочих ошибок до подключения (прежде — необработанное исключение parseArgs)
+        console.error(`letopis: ${text}`);
+        return 1;
+    }
+    const { values, positionals } = parsed;
     const [cmd, arg] = positionals;
     // клиенты MCP передают строку подключения и токен окружением (план 1.1, §2.5) — только для этой команды
     if (cmd === 'mcp') {

package/dist/errors.d.ts

@@ -84,10 +84,9 @@ export declare function issuesFromDb(issues: unknown): Issue[];
  */
 export declare function findingsFromDb<T>(rows: readonly T[]): T[];
 /**
- * Ошибка базы → LetopisError (ValidationError для invalid_data с нарушениями). Детали из DETAIL (JSON) переносятся в
- * detail; ключ каталога и параметры из DETAIL (lt_fail(ключ, …)) — в key и params, текст — тот, что база собрала по ним
- * из русского шаблона; без ключа — текст базы. У нарушений (issues) и строк отказа (detail.rows) key и params наружу не
- * идут. Внутренняя ошибка базы (XX000) с ключом в DETAIL — код internal. Повторяемый конфликт (40001, 40P01) и прочие
- * ошибки возвращаются как есть: на SQLSTATE конфликта держатся повторы (tx.ts).
+ * Ошибка базы → LetopisError (ValidationError для invalid_data с нарушениями) — для ошибок сырого SQL (`db.sql`,
+ * `db.transaction()`): тот же код, ключ и подробности, что у цепочек. Подробности ошибки базы переходят в `detail`, ключ
+ * каталога и параметры — в `key` и `params`, текст — русский; без ключа — текст базы. Значение не того типа (22P02) —
+ * `invalid_query`. Повторяемый конфликт (40001, 40P01) и прочие ошибки возвращаются как есть.
  */
 export declare function fromDbError(e: unknown): unknown;

package/dist/errors.js

@@ -2,10 +2,10 @@
  * Ошибки letopis 1.0 (план, §7.1, этап 2, п. 10). Текст — «letopis: <код>: <сообщение>», как у ошибок
  * базы; код — имя из каталога (`error_catalog()` в lib/sql/15-errors.sql) или код самой библиотеки.
  *
- * Каталог сообщений (план 2.0, этап 3, п. 3; lib/src/messages): ошибка по ключу — `lerr(ключ, параметры)`, текст —
+ * Каталог сообщений: ошибка по ключу — `lerr(ключ, параметры)`, текст —
  * шаблон записи с параметрами. У каждой ошибки — подсказка «что делать» (`hint`) и ссылка на строку её кода в разделе
  * «Ошибки» README на GitHub по тегу версии (`docs`). База собирает текст по ключу и параметрам из того же шаблона и
- * кладёт их в DETAIL (`lt_fail(ключ, …)`), а fromDbError переносит их в поля ошибки (`key`, `params`); без ключа —
+ * передаёт ключ и параметры вместе с ошибкой, а fromDbError переносит их в поля ошибки (`key`, `params`); без ключа —
  * текст базы как есть. У нарушений (validate_data) и строк отказа ужесточения key и params наружу не идут: issuesFromDb,
  * findingsFromDb.
  */
@@ -213,11 +213,10 @@ function parseDetail(detail) {
     }
 }
 /**
- * Ошибка базы → LetopisError (ValidationError для invalid_data с нарушениями). Детали из DETAIL (JSON) переносятся в
- * detail; ключ каталога и параметры из DETAIL (lt_fail(ключ, …)) — в key и params, текст — тот, что база собрала по ним
- * из русского шаблона; без ключа — текст базы. У нарушений (issues) и строк отказа (detail.rows) key и params наружу не
- * идут. Внутренняя ошибка базы (XX000) с ключом в DETAIL — код internal. Повторяемый конфликт (40001, 40P01) и прочие
- * ошибки возвращаются как есть: на SQLSTATE конфликта держатся повторы (tx.ts).
+ * Ошибка базы → LetopisError (ValidationError для invalid_data с нарушениями) — для ошибок сырого SQL (`db.sql`,
+ * `db.transaction()`): тот же код, ключ и подробности, что у цепочек. Подробности ошибки базы переходят в `detail`, ключ
+ * каталога и параметры — в `key` и `params`, текст — русский; без ключа — текст базы. Значение не того типа (22P02) —
+ * `invalid_query`. Повторяемый конфликт (40001, 40P01) и прочие ошибки возвращаются как есть.
  */
 export function fromDbError(e) {
     const err = e;