letopis 1.4.0 → 1.4.1

package/dist/ops.js

@@ -6,39 +6,79 @@
 import { OP } from './types.js';
 const op = (name, ...args) => ({ [OP]: name, args });
 export const isOp = (v) => typeof v === 'object' && v !== null && OP in v;
-/** ≠ (IS DISTINCT FROM) */
+/**
+ * Не равно: `db.Order({ status: ne('cancelled') })`. Подходят и строки, где поля нет или в нём `null`, а `ne(null)` —
+ * строки, где у поля есть значение.
+ */
 export const ne = (v) => op('ne', v);
-/** > */
+/**
+ * Больше: `db.Product({ price: gt(1000) })`. Сравнение — по типу поля из описания класса (числа — как числа, даты — как
+ * даты), поле без описания сравнивается как текст; строки без поля не подходят.
+ */
 export const gt = (v) => op('gt', v);
-/** ≥ */
+/** Больше или равно: `db.Product({ price: gte(500) })`. Сравнение — как у `gt()`. */
 export const gte = (v) => op('gte', v);
-/** < */
+/** Меньше: `db.Product({ price: lt(1000) })`. Сравнение — как у `gt()`. */
 export const lt = (v) => op('lt', v);
-/** ≤ */
+/** Меньше или равно: `db.Product({ price: lte(900) })`. Сравнение — как у `gt()`. */
 export const lte = (v) => op('lte', v);
-/** a ≤ x ≤ b */
+/**
+ * От `a` до `b` включительно: `db.Product({ price: between(500, 3000) })`. Сравнение — как у `gt()`; если `a` больше
+ * `b`, не подходит ни одна строка.
+ */
 export const between = (a, b) => op('between', a, b);
-/** значение из списка */
+/**
+ * Одно из значений списка: `db.Product({ sku: inList(['K-1', 'M-1']) })`. Сравнение — по типу поля, как у `gt()`;
+ * пустой список не находит ничего, а `null` в списке не находит строк без значения — для них есть `isNull()`.
+ */
 export const inList = (vs) => op('in', vs);
-/** LIKE (шаблон с % и _) */
+/**
+ * Текст по шаблону с учётом регистра: `%` — любые символы, в том числе ни одного, `_` — ровно один символ;
+ * `db.Product({ title: like('%чай%') })`. Поле берётся как текст; буквальные `%` и `_` пишут с обратной косой чертой:
+ * `like('100\\%')`.
+ */
 export const like = (s) => op('like', s);
-/** ILIKE (без регистра) */
+/** Как `like()`, но без учёта регистра: `db.Product({ title: ilike('%чай%') })`. */
 export const ilike = (s) => op('ilike', s);
-/** начинается с */
+/**
+ * Текст начинается с `s`, с учётом регистра: `db.Product({ sku: starts('T-') })`. Это `like(s + '%')`: `%`, `_` и
+ * обратная косая черта внутри `s` не экранируются и работают как в шаблоне `like()`.
+ */
 export const starts = (s) => op('like', s + '%');
-/** заканчивается на */
+/**
+ * Текст заканчивается на `s`, с учётом регистра: `db.Product({ sku: ends('-1') })`. Это `like('%' + s)`: `%`, `_` и
+ * обратная косая черта внутри `s` не экранируются и работают как в шаблоне `like()`.
+ */
 export const ends = (s) => op('like', '%' + s);
-/** массив-поле содержит значение */
+/**
+ * Поле-массив содержит элемент `v`: `db.Product({ labels: has('хит') })`. Тип важен: `has(5)` найдёт число 5, но не
+ * строку `'5'`.
+ */
 export const has = (v) => op('has', v);
-/** массив-поле содержит хотя бы одно из */
+/**
+ * Поле-массив содержит хотя бы один элемент из списка: `db.Product({ labels: hasAny(['хит', 'акция']) })`. Находит
+ * только строковые элементы; пустой список не находит ничего.
+ */
 export const hasAny = (vs) => op('hasAny', vs);
-/** массив-поле содержит все */
+/**
+ * Поле-массив содержит все элементы списка, в любом порядке: `db.Product({ labels: hasAll(['хит', 'стекло']) })`. Тип
+ * элементов важен, как у `has()`; пустой список подходит любой строке, даже без этого поля.
+ */
 export const hasAll = (vs) => op('hasAll', vs);
-/** поле присутствует (true) или отсутствует (false) */
+/**
+ * Поле есть в данных (`true`, по умолчанию) или его нет (`false`); значение не важно — поле с `null` тоже есть:
+ * `db.Product({ labels: exists(false) })` — товары без поля `labels`.
+ */
 export const exists = (yes = true) => op('exists', yes);
-/** поле null или отсутствует */
+/** В поле `null` или поля нет совсем: `db.Product({ specs: isNull() })`. Отличить одно от другого помогает `exists()`. */
 export const isNull = () => op('isNull');
-/** НЕ-условие по полю: not(ilike('%тест%')); скаляр — «не равно» */
+/**
+ * Отрицание оператора: `db.Product({ price: not(gte(1000)) })` — цена меньше 1000 или поля нет. Простое значение вместо
+ * оператора значит «не равно», как `ne()`: `db.Order({ status: not('cancelled') })`.
+ */
 export const not = (v) => op('not', v);
-/** ИЛИ на уровне фильтра шага: t.booking(or({ notes: 'a' }, { notes: 'b' })) */
+/**
+ * Хотя бы один из фильтров: `db.Product(or({ sku: 'K-1' }, { price: lt(500) }))` — товар K-1 или дешевле 500. Ставится
+ * вместо всего фильтра шага, а не значением поля; условия внутри одного фильтра соединяются через «и».
+ */
 export const or = (...filters) => op('or', filters);

package/dist/project.d.ts

@@ -61,18 +61,25 @@ export interface ProjectorOut {
         tenant: string;
     }): void;
     /**
-     * Создать (поля без строки — от 0) или дополнить строку и прибавить числа: коммутативная свёртка без чтения.
-     * Приращения строки, заданной одними полями ключа (или одним $id), складываются до отправки в базу, пока между ними
-     * нет upsert, delete или get: одна правка строки на пачку.
+     * Прибавляет к полям строки числа из `deltas`: читать строку не нужно, и итог не зависит от порядка приращений. Поле
+     * приращения, которого в строке нет, считается от 0, а если нет самой строки, она создаётся; поля `row` дописываются в
+     * её данные. Приращения одной строки, заданной только полями ключа (или только `$id`), до отправки в базу складываются
+     * в одну правку, пока между ними нет `upsert`, `delete` или `get`.
      */
     inc(cls: string, row: ProjectorRow, deltas: Record<string, number>, opts: {
         tenant: string;
     }): void;
-    /** Удалить по ключу или id; строки нет — ничего. */
+    /**
+     * Удалить строку: у класса с ключом — по полям ключа, у класса без ключа — по id (строкой или { $id }); строки нет —
+     * ничего. Один id у класса с ключом — invalid_data.
+     */
     delete(cls: string, keyOrId: string | ProjectorRow, opts: {
         tenant: string;
     }): void;
-    /** Текущая строка внутри пачки (с записями пачки, сделанными до вызова); нет — null. */
+    /**
+     * Текущая строка внутри пачки (с записями пачки, сделанными до вызова); нет — null. Строку называют, как в delete: у
+     * класса с ключом — полями ключа, у класса без ключа — id; один id у класса с ключом — invalid_data.
+     */
     get(cls: string, keyOrId: string | ProjectorRow, opts: {
         tenant: string;
     }): Promise<Row | null>;
@@ -82,21 +89,28 @@ export interface ProjectorOptions {
     from: string[];
     /** Производные классы (с потомками): описание каждого — derivedBy: имя проектора. */
     into: string[];
-    /** Версия проектора: другая версия в чекпоинте — rebuild_required, нужна перестройка. */
+    /**
+     * Версия логики проектора — целое число от 1. Вместе с позицией в журнале проектор хранит в базе версию, которой
+     * построена проекция: если она другая, `run()` и `rebuild({ tenant })` отклоняются с `rebuild_required`, а полная
+     * перестройка `rebuild()` строит проекцию заново и запоминает новую версию.
+     */
     version: number;
-    /** Изменения одного арендатора (пачка делится по арендаторам) и запись его результатов. */
+    /**
+     * Функция `handle(changes, out)`: получает изменения одного арендатора и пишет его результаты через `out`. Пачку журнала
+     * проектор делит по арендаторам и вызывает `handle` для каждого по очереди.
+     */
     handle(changes: ProjectorChange[], out: ProjectorOut): void | Promise<void>;
     /** Подавать прошлую версию объекта (before). */
     withBefore?: boolean;
     /**
      * Курсор старше яруса all политики хранения источников (cursor_expired): 'rebuild' — перестроить самому, пачками.
-     * Ярус — по арендатору: истёк у части участников — выбывают они (с 'rebuild' — перестраиваются сами, каждый своей
-     * транзакцией), у всех — вся проекция.
+     * Ярус — по арендатору: истёк у части участников — выбывают они (с 'rebuild' — перестраиваются сами, по одному, пачками), у
+     * всех — вся проекция.
      */
     onExpired?: 'rebuild' | 'error';
     /** Изменений в пачке (по умолчанию 500). */
     batch?: number;
-    /** Запасной опрос журнала, мс (по умолчанию 1000; сигналы источников будят раньше). */
+    /** Как часто проектор сам проверяет журнал, если сигнал не пришёл, мс (по умолчанию 1000); сигналы источников будят его раньше. */
     pollMs?: number;
     /**
      * Сколько транзакция проектора ждёт чужую блокировку строки, мс (по умолчанию 5000; 0 — без предела). Дольше —
@@ -280,8 +294,13 @@ export declare class Projector {
     private ours;
     /** Смена класса без смены id, после которой строка вне семейства from арендатора, — возможно, уход из него (leaving). */
     private leaves;
-    /** Класс результата в арендаторе — из его семейства into. */
+    /**
+     * Входит ли класс `cls` в классы `into` проектора у арендатора `tenant` — сами эти классы или их потомки. Служебный
+     * метод: им `out` проверяет, что `handle` пишет только в эти классы.
+     */
     intoOf(tenant: string, cls: string): boolean;
+    /** Поля ключа класса into арендатора (пусто — класс без ключа). */
+    keyOf(tenant: string, cls: string): string[];
     /**
      * Ключ свёртки inc: класс и строка из одних полей ключа класса или одного $id; иначе null. Строку с другими полями
      * (данные, $tags, $owner) inc не складывает: её поля правят строку, и порядок таких правок важен.

package/dist/project.js

@@ -67,6 +67,10 @@ function change(row, cursor, rebuild = false) {
  * значениями (22…) и пределами размера (54…). Сбой окружения (блокировки, отмена запроса, связь) — не причина
  * выводить арендатора: пачка откатывается целиком, повтор начнётся с того же курсора.
  */
+/** «1 прохода», «2 проходов», «21 прохода» — число проходов в родительном падеже («в течение …»). */
+function passesGen(n) {
+    return `${n} ${n % 10 === 1 && n % 100 !== 11 ? 'прохода' : 'проходов'}`;
+}
 /** Ожидание чужой блокировки строки дольше lock_timeout (55P03): сбой окружения, проход повторяется. */
 function lockWait(e) {
     return e?.code === '55P03';
@@ -161,17 +165,32 @@ class Out {
         if (key !== null)
             this.folds.set(key, d);
     }
+    /**
+     * Строка для delete и get. У класса с ключом её называют полями ключа: id такой строки — v5 от ключа, и по одному id
+     * (строкой или { $id }) база искала бы строку с пустым ключом — get отвечал бы null, а delete выводил арендатора с
+     * id_mismatch. Это ошибка кода handle, а не данных: invalid_data сразу, пачка откатывается целиком.
+     */
+    target(cls, tenant, keyOrId) {
+        const row = this.rowOf(keyOrId);
+        const key = this.p.keyOf(tenant, cls);
+        if (key.length && Object.keys(row).every((n) => n === '$id')) {
+            throw new LetopisError('invalid_data', `проектор ${this.p.name}: у класса ${cls} есть ключ (${key.join(', ')}) — строку называют полями ключа, например { ${key.map((k) => `${k}: …`).join(', ')} }, а не id`);
+        }
+        return row;
+    }
     delete(cls, keyOrId, opts) {
         const tenant = this.check(cls, opts?.tenant);
+        const row = this.target(cls, tenant, keyOrId);
         this.folds.clear();
-        this.ops.push({ op: 'delete', class: cls, tenant, row: this.rowOf(keyOrId) });
+        this.ops.push({ op: 'delete', class: cls, tenant, row });
     }
     async get(cls, keyOrId, opts) {
         const tenant = this.check(cls, opts?.tenant);
+        const row = this.target(cls, tenant, keyOrId);
         await this.flush();
         const S = this.p.env.S;
         const [r] = await this.db(() => this.q.unsafe(`select ${rowJson('e')} as row from ${S}.entity e
-      where e.id = ${S}.derived_id($1, $2::uuid, $3::text::jsonb) and e.class = $1 and e.tenant = $2::uuid`, [cls, tenant, JSON.stringify(this.rowOf(keyOrId))]));
+      where e.id = ${S}.derived_id($1, $2::uuid, $3::text::jsonb) and e.class = $1 and e.tenant = $2::uuid`, [cls, tenant, JSON.stringify(row)]));
         return r ? toRow(r.row) : null;
     }
     async flush() {
@@ -751,7 +770,7 @@ export class Projector {
                     failed[tenant] = {
                         cursor: list[0].cursor || start,
                         code: '55P03',
-                        message: `проектор ${this.name}: строку арендатора ${tenant} держит чужая транзакция — ${hits} проходов подряд дольше lockTimeout`,
+                        message: `проектор ${this.name}: строку арендатора ${tenant} держит чужая транзакция — в течение ${passesGen(hits)} подряд дольше lockTimeout`,
                     };
                     continue;
                 }
@@ -808,10 +827,17 @@ export class Projector {
         const sc = this.scopes.get(row.tenant);
         return sc !== undefined && !failed?.[row.tenant] && row.op === 'reclass' && !row.moved && !sc.from.has(row.class) && row.class !== '#reset';
     }
-    /** Класс результата в арендаторе — из его семейства into. */
+    /**
+     * Входит ли класс `cls` в классы `into` проектора у арендатора `tenant` — сами эти классы или их потомки. Служебный
+     * метод: им `out` проверяет, что `handle` пишет только в эти классы.
+     */
     intoOf(tenant, cls) {
         return this.scopes.get(tenant)?.into.has(cls) ?? false;
     }
+    /** Поля ключа класса into арендатора (пусто — класс без ключа). */
+    keyOf(tenant, cls) {
+        return this.scopes.get(tenant)?.keys.get(cls) ?? [];
+    }
     /**
      * Ключ свёртки inc: класс и строка из одних полей ключа класса или одного $id; иначе null. Строку с другими полями
      * (данные, $tags, $owner) inc не складывает: её поля правят строку, и порядок таких правок важен.

package/dist/registry.d.ts

@@ -68,7 +68,10 @@ export declare class Registry {
     all(): ClassInfo[];
     /** Класс и все его потомки (семейство). */
     family(name: string): ClassInfo[];
-    /** Тип листа по пути полей класса: по JSON Schema (type и format). */
+    /**
+     * Тип листа — поля в конце пути `path` — у класса `cls`, по его JSON Schema (`type` и `format`). По этому типу
+     * библиотека сравнивает значения поля в фильтрах, сортировке и итогах.
+     */
     leafType(cls: string, path: readonly string[]): LeafType;
 }
 export {};

package/dist/registry.js

@@ -70,7 +70,10 @@ export class Registry {
         const root = this.resolve(name).name;
         return this.all().filter((c) => c.ancestors.includes(root));
     }
-    /** Тип листа по пути полей класса: по JSON Schema (type и format). */
+    /**
+     * Тип листа — поля в конце пути `path` — у класса `cls`, по его JSON Schema (`type` и `format`). По этому типу
+     * библиотека сравнивает значения поля в фильтрах, сортировке и итогах.
+     */
     leafType(cls, path) {
         let node = this.resolve(cls).schema;
         for (const p of path) {

package/dist/sql.d.ts

@@ -62,7 +62,10 @@ export interface Hop {
  *    хаб → связь — назад; связь → хаб и хаб → хаб — вперёд; нет нужного — другое направление.
  */
 export declare function resolveHop(reg: Registry, prev: Step, next: Step): Hop;
-/** Курсор keyset-пагинации из последней строки страницы. */
+/**
+ * Курсор постраничного вывода для `after()`: `{ v, id }` — значение поля сортировки и id последней строки страницы.
+ * Поле — то же, что в `sort()`; если его нет в данных строки, `v` — `null`.
+ */
 export declare function cursorOf(row: Row, field: string): Cursor;
 export interface BuildOptions {
     /**

package/dist/sql.js

@@ -422,7 +422,10 @@ function cursorParams(c, sort) {
     }
     return { v: value, id };
 }
-/** Курсор keyset-пагинации из последней строки страницы. */
+/**
+ * Курсор постраничного вывода для `after()`: `{ v, id }` — значение поля сортировки и id последней строки страницы.
+ * Поле — то же, что в `sort()`; если его нет в данных строки, `v` — `null`.
+ */
 export function cursorOf(row, field) {
     const f = field === 'updated' ? 'at' : field;
     if (f === 'at' || f === 'rev' || f === 'id')
@@ -609,10 +612,13 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
                     + `where (v.op = 'delete') = ${isDead} and v.op not in ('purge', 'trim', 'reset')${dataCond('v')}${endsCond(`${S}.link_ids(v.links)`)}${rolesCond('v', 's.src')})`;
             };
             ctes.push(`p${i}a as (select q.src, q.id, q.rev from ${hopCall(atPh, false)} q)`);
-            parts.push(cur ? entityByIds(`select q.id from p${i}a q`) : logPart(`select q.id, q.rev from p${i}a q`));
+            // пары переходов — по одной на (источник, цель): объект, который ссылается на несколько объектов прошлого шага,
+            // встречается в них несколько раз; строка узла — одна на id, иначе rows(), count() и агрегаты его удваивали
+            // (entityByIds повторы отбрасывает сам, срез asOf() и надгробия withDeleted() — через distinct здесь)
+            parts.push(cur ? entityByIds(`select q.id from p${i}a q`) : logPart(`select distinct q.id, q.rev from p${i}a q`));
             if (dead) {
                 ctes.push(`p${i}d as (select q.src, q.id, q.rev from ${hopCall(atPh, true)} q)`);
-                parts.push(logPart(`select q.id, q.rev from p${i}d q`));
+                parts.push(logPart(`select distinct q.id, q.rev from p${i}d q`));
                 ctes.push(`p${i} as (select src, id from p${i}a union all select src, id from p${i}d)`);
             }
             else {
@@ -728,7 +734,9 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
             }
             else {
                 const cast = agg.fn === 'sum' || agg.fn === 'avg' ? '::numeric' : CAST[aggLeaf];
-                text = `${withClause}select ${agg.fn}((${acc})${cast}) as v from ${ents} z`;
+                // у boolean в PostgreSQL нет min и max; false меньше true: наименьшее — «все ли true», наибольшее — «есть ли true»
+                const fn = aggLeaf === 'boolean' && agg.fn === 'min' ? 'bool_and' : aggLeaf === 'boolean' && agg.fn === 'max' ? 'bool_or' : agg.fn;
+                text = `${withClause}select ${fn}((${acc})${cast}) as v from ${ents} z`;
             }
             break;
         }

package/dist/tx.js

@@ -282,7 +282,16 @@ export class ExplicitTx {
         let changed = null;
         try {
             // чтение letopis.changed и COMMIT — одним конвейером (как в runTx); обрыв — исход неизвестен
-            const [rows, res] = await Promise.all([this.conn.unsafe(`select current_setting('letopis.changed', true) as changed`), this.conn.unsafe('commit')]);
+            const read = this.conn.unsafe(`select current_setting('letopis.changed', true) as changed`);
+            const commit = this.conn.unsafe('commit');
+            const [rows, res] = (await Promise.all([read, commit]).catch(async (e) => {
+                // транзакцию уже прервала ошибка, которую код внутри db.begin() поймал и проглотил: чтение получает 25P02,
+                // а COMMIT того же конвейера отвечает ROLLBACK — это tx_rolled_back, а не сырая ошибка PostgreSQL
+                const tail = e.code === '25P02' ? await commit.catch(() => null) : null;
+                if (tail?.command === 'ROLLBACK')
+                    return [[], tail];
+                throw e;
+            }));
             changed = rows[0]?.changed ?? null;
             if (res.command === 'ROLLBACK') {
                 this.failure = new LetopisError('tx_rolled_back', 'commit: PostgreSQL откатил транзакцию (в ней была ошибка)');

package/dist/types.d.ts

@@ -1,23 +1,30 @@
 /**
  * Общие типы letopis 1.0. Файл наполняется по этапам плана (reports/PLAN-LETOPIS-1.0.md).
  */
-/** Ревизия движка в базе: штамп в lib/sql/99-revision.sql должен совпадать (этап 1). */
-export declare const DDL_REVISION = 6;
+/**
+ * Ревизия схемы, которую знает эта версия пакета, — номер версии SQL-части letopis (таблиц и функций в схеме установки).
+ * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии `up()` обновляет только с `upgrade: true`,
+ * а `connect()` о ней предупреждает.
+ */
+export declare const DDL_REVISION = 7;
 /**
  * Классы, строки которых меняют права и схему: их запись повышает счётчик прав (загрузчик), а сигнал
  * сбрасывает весь кэш результатов и пропуска прав. Тот же список — в триггерах базы (60-write.sql).
  */
 export declare const ACL_CLASS_NAMES: readonly string[];
-/** Методы цепочки: терминалы, модификаторы, глаголы записи (этап 4), охранники снесённого API. */
+/**
+ * Имена методов цепочки: модификаторы, терминалы, глаголы записи и слоты концов, а также `then` и снятые методы прежних
+ * версий. После шага цепочки эти имена библиотека не ищет среди классов; все они входят в `RESERVED_CLASS_NAMES`.
+ */
 export declare const CHAIN_METHODS: readonly ["then", "entity", "paths", "rows", "first", "ids", "count", "limit", "offset", "sort", "asOf", "withDeleted", "deep", "exact", "sum", "avg", "min", "max", "countBy", "after", "versions", "create", "update", "upsert", "set", "unset", "add", "remove", "delete", "anonymize", "reclass", "restore", "purge", "alias", "tags", "owner", "forUpdate", "cache", "rekey", "run", "execute", "account", "diff", "blame"];
 /** Свойства корня db (и транзакции db.begin()). */
 export declare const DB_METHODS: readonly ["as", "begin", "commit", "rollback", "lock", "batch", "watch", "close", "registry", "sql", "load", "verify", "maintain", "reset", "describe", "auth", "acl", "idOf", "refresh", "transaction", "flushSignals", "schema", "token", "tenant", "reloadSchema", "accounts", "credentials", "resources", "rules", "compact", "trimHistory", "rekeyClass", "cache", "projector", "rebuildAggregates"];
 /** Свойства батча db.batch(name). */
 export declare const BATCH_METHODS: readonly ["discard", "size"];
 /**
- * Зарезервированные имена: Proxy разбирает их раньше классов, поэтому класс с таким именем
- * недостижим как шаг. Установщик подставляет список в функцию базы reserved_names(), которая
- * отклоняет связи с такими именами; совпадение со switch Proxy проверяет check-docs.
+ * Имена методов цепочки, корня `db` и батча. Там, где имя занято методом, библиотека не ищет его среди классов, и шаг с
+ * таким именем до класса не дойдёт; класс-связь (`link`) с таким именем база не создаст (`invalid_class`). Не давайте
+ * классам эти имена.
  */
 export declare const RESERVED_CLASS_NAMES: readonly string[];
 /** Строка ответа: текущая версия (или версия журнала для asOf, versions, withDeleted). */
@@ -78,7 +85,7 @@ export type Filter = string | string[] | Op | {
 } | {
     [field: string]: FieldFilter | undefined;
 };
-/** Курсор keyset-пагинации: значение поля сортировки и id последней строки страницы. */
+/** Курсор постраничного вывода для `after()`: значение поля сортировки и id последней строки страницы. */
 export interface Cursor {
     v: string | number | boolean | null;
     id: string;

package/dist/types.js

@@ -1,8 +1,12 @@
 /**
  * Общие типы letopis 1.0. Файл наполняется по этапам плана (reports/PLAN-LETOPIS-1.0.md).
  */
-/** Ревизия движка в базе: штамп в lib/sql/99-revision.sql должен совпадать (этап 1). */
-export const DDL_REVISION = 6;
+/**
+ * Ревизия схемы, которую знает эта версия пакета, — номер версии SQL-части letopis (таблиц и функций в схеме установки).
+ * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии `up()` обновляет только с `upgrade: true`,
+ * а `connect()` о ней предупреждает.
+ */
+export const DDL_REVISION = 7;
 /**
  * Классы, строки которых меняют права и схему: их запись повышает счётчик прав (загрузчик), а сигнал
  * сбрасывает весь кэш результатов и пропуска прав. Тот же список — в триггерах базы (60-write.sql).
@@ -11,7 +15,10 @@ export const ACL_CLASS_NAMES = ['rule', 'Resource', 'member', 'Account', 'Class'
 // ---------------------------------------------------------------------------
 // Методы цепочки — единственный источник зарезервированных имён (план, §2.14, этап 3, п. 10)
 // ---------------------------------------------------------------------------
-/** Методы цепочки: терминалы, модификаторы, глаголы записи (этап 4), охранники снесённого API. */
+/**
+ * Имена методов цепочки: модификаторы, терминалы, глаголы записи и слоты концов, а также `then` и снятые методы прежних
+ * версий. После шага цепочки эти имена библиотека не ищет среди классов; все они входят в `RESERVED_CLASS_NAMES`.
+ */
 export const CHAIN_METHODS = [
     'then', 'entity', 'paths', 'rows', 'first', 'ids', 'count', 'limit', 'offset', 'sort', 'asOf', 'withDeleted',
     'deep', 'exact', 'sum', 'avg', 'min', 'max', 'countBy', 'after', 'versions', 'create', 'update', 'upsert', 'set',
@@ -28,9 +35,9 @@ export const DB_METHODS = [
 /** Свойства батча db.batch(name). */
 export const BATCH_METHODS = ['discard', 'size'];
 /**
- * Зарезервированные имена: Proxy разбирает их раньше классов, поэтому класс с таким именем
- * недостижим как шаг. Установщик подставляет список в функцию базы reserved_names(), которая
- * отклоняет связи с такими именами; совпадение со switch Proxy проверяет check-docs.
+ * Имена методов цепочки, корня `db` и батча. Там, где имя занято методом, библиотека не ищет его среди классов, и шаг с
+ * таким именем до класса не дойдёт; класс-связь (`link`) с таким именем база не создаст (`invalid_class`). Не давайте
+ * классам эти имена.
  */
 export const RESERVED_CLASS_NAMES = [...new Set([...CHAIN_METHODS, ...DB_METHODS, ...BATCH_METHODS])];
 /** Метка операторов фильтра (символ не пересекается с данными). */

package/dist/up.d.ts

@@ -8,28 +8,36 @@ export interface InstallOptions {
     schema: string;
     owner?: string;
     app?: string;
-    /** Константа установки: разрешён ли reset (план, §2.2). По умолчанию выключен. */
+    /**
+     * Разрешить `db.reset()` и `maintain({ now })` — для тестовых установок и стендов; по умолчанию запрещено. Значение
+     * задаётся при установке и хранится в схеме: каждый `up()` записывает его заново (план, §2.2).
+     */
     allowReset?: boolean;
     /**
-     * Константа установки: политика хранения истории для классов без своей (план, §2.11), например
-     * `{ all: '1 day', daily: '1 week', weekly: '1 month', monthly: '1 year', yearly: 'forever' }`.
-     * Не задана — история хранится вся.
+     * Политика хранения истории для классов без своей, например
+     * `{ all: '1 day', daily: '1 week', weekly: '1 month', monthly: '1 year', yearly: 'forever' }`; не задана — история
+     * хранится вся. Значение задаётся при установке и хранится в схеме: каждый `up()` записывает его заново (план, §2.11).
      */
     history?: HistoryPolicy;
     /** Номер последнего накатываемого файла — для пошаговых тестов. */
     upTo?: number;
     /** Сиды после ядра: имена lib/sql/seed.<имя>.sql (например 'booking') или пути к своим файлам .sql. */
     seeds?: string[];
-    /** Обновление (upgrade): ревизия схемы до наката — миграции lib/sql/migrate/ с номером выше неё. */
+    /**
+     * Обновление (upgrade): ревизия схемы до наката — миграции lib/sql/migrate/ с номером выше неё. Если под блокировкой
+     * схемы видна более новая ревизия (её уже обновил одновременный up()), миграции считаются от неё.
+     */
     migrateFrom?: number;
+    /** Удалить схему и поставить заново (up({ fresh })) — под той же блокировкой схемы, что и накат. ДАННЫЕ ТЕРЯЮТСЯ. */
+    fresh?: boolean;
     /** Каталог миграций (по умолчанию lib/sql/migrate). */
     migrationsDir?: string;
     /** Свой ключ сервиса: зарегистрировать, если такого ещё нет (вместо выпуска случайного). */
     serviceKey?: string;
     /**
-     * Режим сигналов NOTIFY (план 1.1, §2.2): 'class' (по умолчанию, как в 1.0) — имена классов; 'tenant' —
-     * имя класса и токен арендатора; 'opaque' — только токены; 'none' — сигналов нет. Режим хранится в
-     * схеме: накат без опции его не меняет, reset({ all }) — сохраняет.
+     * Что видно в сигналах базы (`NOTIFY`): `'class'` (у новой схемы по умолчанию) — имя класса; `'tenant'` — имя класса и
+     * псевдоним арендатора (токен); `'opaque'` — только псевдонимы класса и арендатора; `'none'` — сигналов нет.
+     * Режим хранится в схеме: `up()` без опции его не меняет, `reset({ all })` сохраняет (план 1.1, §2.2).
      */
     signals?: SignalMode;
 }
@@ -47,7 +55,11 @@ export interface InstallResult {
     schema: string;
     owner: string;
     app: string;
-    /** Ключ сервисного аккаунта; выдаётся только при первой установке (или зарегистрированный свой), дальше — null. */
+    /**
+     * Ключ API сервисного аккаунта, выпущенный или зарегистрированный этим накатом, иначе `null`. Без опции `serviceKey`
+     * новый ключ выпускается на любом накате, где в схеме не осталось ни одного неотозванного ключа API, — не только при
+     * первой установке; свой `serviceKey` регистрируется и возвращается, если неотозванного ключа с таким значением ещё нет.
+     */
     serviceKey: string | null;
     /** Применённые миграции. */
     migrations: string[];
@@ -75,7 +87,9 @@ export declare function compareVersions(a: string, b: string): number;
  */
 export declare function stampDrift(schema: string, comment: string): Promise<string | null>;
 export declare function substitute(text: string, vars: Record<string, string>): string;
-export declare function install(sql: postgres.Sql, opts: InstallOptions): Promise<InstallResult>;
+export declare function install(sql: postgres.Sql, opts: InstallOptions): Promise<InstallResult & {
+    found: number | null;
+}>;
 /** Миграции с номером выше ревизии from и не выше DDL_REVISION: `0004-описание.sql`, по номеру. */
 export declare function migrationFiles(dir: string, from: number): Promise<string[]>;
 export interface UpOptions extends Omit<InstallOptions, 'schema' | 'upTo' | 'migrateFrom'> {
@@ -94,11 +108,16 @@ export interface UpOptions extends Omit<InstallOptions, 'schema' | 'upTo' | 'mig
     /** Сколько ждать базу, мс (по умолчанию 60 000). */
     waitTimeoutMs?: number;
     /**
-     * База для разработки без PostgreSQL (решение 6 точки А): PGlite с pgcrypto через pglite-socket;
-     * одно соединение — connect({ dsn: r.pglite.dsn, listen: false, max: 1 }); не для гонок и CI.
+     * Запустить PGlite — PostgreSQL прямо в процессе Node — для разработки без своего сервера (решение 6 точки А);
+     * подключение к нему — `connect({ dsn: r.pglite.dsn, schema: r.schema, listen: false, max: 1, allowBypassRls: true })`.
+     * Соединение у PGlite одно, поэтому одновременные транзакции и гонки на нём не проверить: для таких тестов и в CI нужен
+     * настоящий PostgreSQL.
      */
     pglite?: boolean | PgliteOptions;
-    /** Арендатор и его первый пользователь — без своего сида (createTenant). */
+    /**
+     * Арендатор и его первый пользователь: после установки `up()` заводит их сам, как `createTenant()` с этими опциями, и
+     * кладёт итог в `r.tenant` — свой сид для этого не нужен.
+     */
     tenant?: TenantOptions;
 }
 export interface UpResult extends InstallResult {
@@ -134,14 +153,18 @@ export declare function ensureDatabase(dsn: string, log?: (m: string) => void):
  */
 export declare function checkServer(versionNum: number, encoding: string): string[];
 /** Ревизия движка схемы по комментарию 'letopis ddl_revision=N'; схемы нет — null. */
-export declare function schemaRevision(sql: postgres.Sql, schema: string): Promise<number | null>;
+export declare function schemaRevision(sql: Pick<postgres.Sql, 'unsafe'>, schema: string): Promise<number | null>;
 /**
- * Поставить или обновить установку letopis. Схема есть и её ревизия совпадает — повторный накат
- * (идемпотентный); ревизия отстала — только с upgrade: true; новее библиотеки — отказ.
+ * Ставит или обновляет установку letopis в схеме. Если схема уже есть и её ревизия та же, что у пакета, `up()` выполняет
+ * повторный накат: заново ставит функции, не трогая данные, — поэтому его можно вызывать при каждом запуске приложения.
+ * Схему отставшей ревизии `up()` обновляет только с `upgrade: true`, а на схеме новее пакета отказывает.
  */
 export declare function up(opts: UpOptions): Promise<UpResult>;
 export interface TenantOptions {
-    /** Имя арендатора (аккаунт в System; id — v5 от «tenant:<имя>», как у letopis import --tenant). */
+    /**
+     * Имя арендатора — его аккаунта в System. Из имени вычисляется id арендатора, поэтому одно имя — всегда один и тот же
+     * арендатор (так же его находит `letopis import --tenant`).
+     */
     name: string;
     /** Правило арендатора «аутентифицированным можно всё» (READ, WRITE, DELETE; по умолчанию да). */
     grantAll?: boolean;
@@ -150,6 +173,10 @@ export interface TenantOptions {
         name: string;
         login: string;
         password: string;
+        /**
+         * Вид пароля (по умолчанию PASSWORD) — как у auth.setPassword: `^[A-Z][A-Z0-9_]{1,31}$`, не служебный вид (SESSION,
+         * APIKEY, KEYSECRET, OTP, TOTP, KEY, PROJECTOR, LOCK); иначе invalid_data.
+         */
         kind?: string;
         ttl?: string;
         /** Роли членства (по умолчанию ['owner']); роли уже существующего членства повтор не меняет. */
@@ -167,14 +194,10 @@ export interface TenantResult {
     created: boolean;
 }
 /**
- * Арендатор и его первый пользователь — то, что раньше делал свой сид функциями владельца
- * (sys_create, sys_grant_all). Нужно администраторское подключение (роль может стать владельцем);
- * всё — одной транзакцией от владельца. Повтор с тем же именем и логином ничего не дублирует:
- * id — v5 от имени и логина, существующие строки пропускаются (пароль и роли членства не меняются),
- * сессия выдаётся заново. Удалённые арендатор, аккаунт пользователя или членство (строки нет, а
- * журнал id есть) — отказ invalid_data, транзакция откатывается целиком: повтор не воскрешает то,
- * что удалил администратор (up({ tenant }) идёт при каждом запуске), а sys_create пишет только
- * версию 1 — её занимает история; вернуть строку — restore() цепочкой.
+ * Заводит арендатора и, по желанию, его первого пользователя (аккаунт, членство, пароль, сессию) одной транзакцией от
+ * роли-владельца схемы — поэтому нужен администраторский пул. Повтор с тем же именем и логином ничего не дублирует и не
+ * меняет, только выдаёт пользователю новую сессию; одновременные вызовы заводят арендатора один раз. Если арендатор,
+ * пользователь или членство были удалены, повтор их не воскрешает — отказ `invalid_data`.
  */
 export declare function createTenant(sql: postgres.Sql, schema: string, opts: TenantOptions, owner?: string): Promise<TenantResult>;
 export {};