letopis 1.4.0 → 1.4.2

package/dist/load.js

@@ -26,6 +26,7 @@ import { v5Id } from './uuid.js';
 import { applyDefaults } from './validate.js';
 import { isInc } from './write.js';
 import { ACL_CLASS_NAMES } from './types.js';
+import { isConnectionError, release, rollbackAfter } from './tx.js';
 const SYSTEM_ID = '2eba6d0a-1edd-4bb6-a85a-a703dab49035';
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /** Классы, строки которых первая заливка сохраняет и возвращает: описания классов, аккаунты, членства, права. */
@@ -568,14 +569,15 @@ export async function load(env, input, opts = {}) {
             const classesTouched = new Set();
             // существующие объекты — только в режимах skip и update, одним запросом на пачку и до проверок:
             // пропущенный объект для ссылок на него — вне загрузки (его сверит запрос в конце)
-            const live = new Set();
+            // живые строки пачки: id → класс (existing: 'update' правит только объект того же класса)
+            const live = new Map();
             const past = new Map();
             if (existing !== 'error' && !opts.withHistory) {
                 for (let b = 0; b < portion.length; b += batch) {
                     const ids = portion.slice(b, b + batch).map((i) => p1[i].id);
                     const lock = existing === 'update' ? ' order by e.id for no key update' : '';
-                    for (const r of await conn.unsafe(`select e.id from ${S}.entity e where e.id = any ($1::uuid[])${lock}`, [ids]))
-                        live.add(r.id);
+                    for (const r of await conn.unsafe(`select e.id, e.class from ${S}.entity e where e.id = any ($1::uuid[])${lock}`, [ids]))
+                        live.set(r.id, r.class);
                     for (const r of await conn.unsafe(`select distinct on (l.id) l.id, l.rev, l.hash, l.at::text as at from ${S}.log l
               where l.id = any ($1::uuid[]) order by l.id, l.rev desc`, [ids]))
                         past.set(r.id, r);
@@ -690,12 +692,13 @@ export async function load(env, input, opts = {}) {
         }
         catch (e) {
             failed = e;
+            // обрыв: в мёртвое соединение не пишут и в пул его не возвращают (план 2.0, 7.4 №7)
             if (!ini)
-                await conn.unsafe('rollback').catch(() => { });
+                await rollbackAfter(conn, e);
         }
         finally {
             if (!ini)
-                conn.release();
+                release(conn, failed);
         }
         if (failed) {
             const err = failed;
@@ -848,6 +851,13 @@ export async function load(env, input, opts = {}) {
             if (!sh || issues.any)
                 continue;
             if (live.has(id)) {
+                // строка с тем же id, но другого класса (класс без ключа после reclass, повторный импорт по $ext): правка
+                // прошла бы мимо триггеров с данными, проверенными по чужой схеме, — exists (план 2.0, 7.2 №4)
+                const was = live.get(id);
+                if (was !== cls.name) {
+                    issues.add({ line: i + 1, code: 'exists', message: `объект с этим id уже есть в классе ${was}: строка класса ${cls.name} его не правит`, id, class: cls.name });
+                    continue;
+                }
                 updates.push({ id, data: sh.data, links: sh.links, tags: sh.tags ?? null, line: i + 1 });
                 continue;
             }
@@ -924,7 +934,7 @@ export async function load(env, input, opts = {}) {
           lg as (
             insert into ${S}.log (id, rev, class, cv, tenant, owner, links, data, tags, at, author, agent, op, reason, moved, prev_hash)
             select id, rev, class, cv, tenant, owner, links, data, tags, at, author, agent, op, reason, moved, prev_hash from up
-            where ${S}.history_on(up.class, up.tenant))
+            where ${S}.history_on(up.class, up.tenant) order by up.id)
         select up.id, up.class from up`, [updates.map((u) => ({ id: u.id, data: u.data, links: u.links, tags: u.tags })), ts, author, agent]);
             report.updated += res.length;
             report.skipped += updates.length - res.length;
@@ -1020,12 +1030,17 @@ export async function load(env, input, opts = {}) {
         await copyLines(conn, `copy ${S}.entity (${ENTITY_COLS}) from stdin${ini?.freeze ? ' with (freeze)' : ''}`, ent);
     }
 }
-/** Определения из каталога: ограничения (первичный ключ, уникальные), прочие индексы, триггеры с режимом, колонки. */
+/**
+ * Определения из каталога: ограничения (первичный ключ, уникальные), внешние ключи других таблиц на entity и log
+ * (secret.account, ревизия 7), прочие индексы, триггеры с режимом, колонки.
+ */
 async function catalogOf(conn, S) {
     const rels = [`${S}.entity`, `${S}.log`];
     const sel = `(select x::regclass from unnest($1::text[]) x)`;
     const constraints = await conn.unsafe(`select conname as name, conrelid::regclass::text as tbl, pg_get_constraintdef(oid) as def
     from pg_constraint where conrelid in ${sel} and contype in ('p', 'u') order by conrelid, conname`, [rels]);
+    const foreign = await conn.unsafe(`select conname as name, conrelid::regclass::text as tbl, pg_get_constraintdef(oid) as def
+    from pg_constraint where confrelid in ${sel} and contype = 'f' order by conrelid, conname`, [rels]);
     const indexes = await conn.unsafe(`select i.indexrelid::regclass::text as name, pg_get_indexdef(i.indexrelid) as def
     from pg_index i where i.indrelid in ${sel}
       and not exists (select 1 from pg_constraint c where c.conindid = i.indexrelid and c.conrelid = i.indrelid and c.contype in ('p', 'u', 'x'))
@@ -1037,6 +1052,7 @@ async function catalogOf(conn, S) {
     where attrelid = $1::regclass and attnum > 0 and not attisdropped and attgenerated = ''`, [rel]))[0].c;
     return {
         constraints: constraints,
+        foreign: foreign,
         indexes: indexes,
         triggers: triggers,
         entityCols: await cols(rels[0]),
@@ -1047,7 +1063,8 @@ async function catalogOf(conn, S) {
  * Первая заливка (план 1.1, §2.3): загрузки fn — одной транзакцией в пустую схему. Блокировка таблиц до
  * проверки; в схеме только строки системных классов и записи reset (иначе not_empty); они (с seq и tx
  * журнала) и определения ограничений, индексов и триггеров из каталога (с режимом включения tgenabled:
- * pg_get_triggerdef его не передаёт) сохраняются в памяти; TRUNCATE; триггеры, ограничения и индексы
+ * pg_get_triggerdef его не передаёт) сохраняются в памяти; внешний ключ secret.account снимается до TRUNCATE и
+ * возвращается после первичного ключа entity; TRUNCATE; триггеры, ограничения и индексы
  * снимаются — BEFORE ROW делает COPY построчным одним своим наличием, триггеры после оператора копят
  * переходные таблицы; системные строки возвращаются (seq журнала — generated always: overriding system
  * value); загрузки пишут COPY FREEZE. В конце — ограничения (дубликат найдёт сортировка), индексы,
@@ -1061,6 +1078,7 @@ export async function initialSession(env, fn, tune = {}) {
     const ident = (n) => `"${n.replace(/"/g, '""')}"`;
     const conn = await env.sql.reserve();
     const q = (text, params = []) => conn.unsafe(text, params);
+    let initialFailure = null;
     try {
         await q('begin isolation level read committed');
         await q(`set local role ${ident(env.ownerRole)}`);
@@ -1081,7 +1099,11 @@ export async function initialSession(env, fn, tune = {}) {
         const triggers = tune.keepTriggers ? [] : cat.triggers;
         const keys = tune.keepKeys ? [] : cat.constraints;
         const indexes = cat.indexes.filter((i) => !(tune.keepGin && /\busing gin\b/i.test(i.def)));
-        // 4. TRUNCATE; триггеры, ограничения и индексы — снять
+        // 4. TRUNCATE; триггеры, ограничения и индексы — снять. Внешний ключ secret.account на entity (ревизия 7) — до
+        // TRUNCATE при любом keepKeys: таблицу, на которую ссылается внешний ключ, TRUNCATE без неё не очищает, а secret
+        // (ключ установки, сессии, креды) заливка не трогает
+        for (const f of cat.foreign)
+            await q(`alter table ${f.tbl} drop constraint ${ident(f.name)}`);
         await q(`truncate ${S}.entity, ${S}.log`);
         for (const t of triggers)
             await q(`drop trigger ${ident(t.name)} on ${t.tbl}`);
@@ -1107,6 +1129,10 @@ export async function initialSession(env, fn, tune = {}) {
         least(current_setting('max_parallel_workers')::int, 4))::text, true)`);
         for (const c of keys)
             await q(`alter table ${c.tbl} add constraint ${ident(c.name)} ${c.def}`);
+        // внешние ключи на entity — после её первичного ключа: системные строки вернулись с прежними id, строки secret
+        // ссылаются на них
+        for (const f of cat.foreign)
+            await q(`alter table ${f.tbl} add constraint ${ident(f.name)} ${f.def}`);
         for (const i of indexes)
             await q(i.def);
         // 8. триггеры — с прежним режимом включения (ENABLE ALWAYS работает и при session_replication_role = replica)
@@ -1162,10 +1188,12 @@ export async function initialSession(env, fn, tune = {}) {
         return out;
     }
     catch (e) {
-        await q('rollback').catch(() => { });
+        initialFailure = e;
+        if (!isConnectionError(e))
+            await q('rollback').catch(() => { });
         throw e instanceof LetopisError ? e : fromDbError(e);
     }
     finally {
-        conn.release();
+        release(conn, initialFailure);
     }
 }

package/dist/mcp.d.ts

@@ -3,26 +3,35 @@ import type { Db } from './index.js';
 export interface McpOptions {
     /** Инструмент letopis_write (create, update, upsert, delete); по умолчанию сервер только читает. */
     write?: boolean;
-    /** Строк в ответе не больше (по умолчанию 100); дальше — курсор. */
+    /**
+     * Предел строк в одном ответе (по умолчанию 100). Остальные строки `letopis_query` отдаёт на следующих страницах по
+     * курсору, а версии, группы `countBy` и изменения `diff` и `blame` сверх предела обрезаются с пометкой `more` или
+     * `truncated`.
+     */
     maxRows?: number;
-    /** Байт JSON строк в ответе не больше (по умолчанию 50 000); дальше — курсор. */
+    /**
+     * Предел размера строк одного ответа в байтах JSON (по умолчанию 50 000); что не поместилось — так же, как сверх
+     * `maxRows`. Описание модели больше предела `letopis_model` отдаёт кратким.
+     */
     maxBytes?: number;
     /**
-     * letopis_write пишет и классы прав — rule, Resource, member, Account, Class и их потомков (правила, членства,
-     * описания классов). По умолчанию — отказ acl_denied: агент под инъекцией в данных выдал бы постороннему членство или
-     * правило без подтверждения человека (ревью безопасности №2, О5).
+     * Разрешить `letopis_write` писать и классы прав — `rule`, `Resource`, `member`, `Account`, `Class` и их потомков
+     * (правила, ресурсы, членства, аккаунты, описания классов). По умолчанию — отказ `acl_denied`: агент, которому в данных
+     * подсунули чужие инструкции, мог бы без подтверждения человека выдать постороннему членство или право
+     * (ревью безопасности №2, О5).
      */
     allowAclWrite?: boolean;
     /**
-     * Сессия в арендаторе System — так работает системный администратор: его роль admin даёт права на аккаунты,
-     * членства, правила и letopis.*. По умолчанию — отказ user_session_required (ревью безопасности №2, О5).
+     * Принять сессию в арендаторе System, то есть сессию системного администратора: с `true` агент получает его права на
+     * аккаунты, членства, правила и `letopis.*`, но писать классы прав по-прежнему может только с `allowAclWrite`. По
+     * умолчанию такая сессия — отказ `user_session_required` (ревью безопасности №2, О5).
      */
     allowSystemAdmin?: boolean;
 }
 /**
- * Сервер MCP для одного пользователя letopis: инструменты letopis_model, letopis_query, letopis_history и при
- * { write: true } — letopis_write. Подключение — сессия пользователя (connect({ token })) или фасад db.as(пользователь).
- * Транспорт выбирает приложение: server.connect(транспорт), serveStdio(() => createMcpServer(db)) или
- * createMcpHandler(() => createMcpServer(db)) SDK — со своей авторизацией.
+ * Сервер MCP для одного пользователя letopis: инструменты `letopis_model`, `letopis_query`, `letopis_history`, а с
+ * `{ write: true }` — ещё `letopis_write`. Подключение — сессия пользователя (`connect({ token })`) или фасад
+ * `db.as(пользователь)`. Транспорт выбирает приложение: `server.connect(транспорт)`, `serveStdio(() => createMcpServer(db))`
+ * или обработчик HTTP `createMcpHandler(() => createMcpServer(db))` из SDK; токен запроса HTTP проверяет приложение.
  */
 export declare function createMcpServer(db: Db, opts?: McpOptions): Promise<McpServer>;

package/dist/mcp.js

@@ -78,7 +78,7 @@ const describeQuery = (o) => [
     'Чтение JSON-цепочкой, без SQL. Старт: class (класс, алиас или роль) и filter, id или ids.',
     'steps — переходы по связям: [{ step: "Роль или Класс", filter? | id? | ids? }].',
     'Фильтр: { поле: значение } — равенство; вложенные поля — вложенным объектом; конец — { Роль: id };',
-    'операторы — { поле: { $gt: 5 } }: $ne, $gt, $gte, $lt, $lte, $between [a, b], $in [..], $like, $ilike, $starts, $ends, $has, $hasAny [..], $hasAll [..], $exists true|false, $isNull true, $not; ИЛИ — { $or: [фильтр, …] }.',
+    'операторы — { поле: { $gt: 5 } }: $ne, $gt, $gte, $lt, $lte, $between [a, b], $in [..], $like, $ilike, $starts, $ends (% и _ в значении $starts и $ends — шаблон LIKE, не экранируются), $has, $hasAny [..], $hasAll [..], $exists true|false, $isNull true, $not; ИЛИ — { $or: [фильтр, …] }.',
     'Модификаторы: asOf (момент ISO — срез на дату), withDeleted, sort { field: "at" | "rev" | "id" | "data.<путь>", dir }, limit, cursor (из прошлого ответа).',
     'terminal: rows (по умолчанию), first, ids, count, sum, avg, min, max, countBy — с field "data.<путь>".',
     `Ответ — не больше ${o.maxRows} строк и ${o.maxBytes} байт; дальше — cursor. Без sort строки идут по id. Только чтение.`,
@@ -522,7 +522,9 @@ async function query(db, a, o) {
     const got = await chain.limit(want + 1).rows();
     const page = got.slice(0, fit(got.slice(0, want), o));
     const more = got.length > page.length;
-    const next = more && page.length ? encodeCursor({ f: field, d: dir, ...cursorOf(page[page.length - 1], field) }) : undefined;
+    const last = more && page.length ? cursorOf(page[page.length - 1], field) : undefined;
+    // курсор MCP — { f, d, v, id }: списки rows и ids листаются без rev (он разводит только версии)
+    const next = last ? encodeCursor({ f: field, d: dir, v: last.v, id: last.id }) : undefined;
     const body = terminal === 'ids' ? { ids: page.map((r) => r.id) } : { rows: page };
     return ok({ ...body, count: page.length, more, ...(next ? { cursor: next } : {}) });
 }
@@ -782,10 +784,10 @@ async function checkCredentials(db, o) {
     return { account: c.account, tenant: String(c.tenant ?? '') };
 }
 /**
- * Сервер MCP для одного пользователя letopis: инструменты letopis_model, letopis_query, letopis_history и при
- * { write: true } — letopis_write. Подключение — сессия пользователя (connect({ token })) или фасад db.as(пользователь).
- * Транспорт выбирает приложение: server.connect(транспорт), serveStdio(() => createMcpServer(db)) или
- * createMcpHandler(() => createMcpServer(db)) SDK — со своей авторизацией.
+ * Сервер MCP для одного пользователя letopis: инструменты `letopis_model`, `letopis_query`, `letopis_history`, а с
+ * `{ write: true }` — ещё `letopis_write`. Подключение — сессия пользователя (`connect({ token })`) или фасад
+ * `db.as(пользователь)`. Транспорт выбирает приложение: `server.connect(транспорт)`, `serveStdio(() => createMcpServer(db))`
+ * или обработчик HTTP `createMcpHandler(() => createMcpServer(db))` из SDK; токен запроса HTTP проверяет приложение.
  */
 export async function createMcpServer(db, opts = {}) {
     const o = limitsOf(opts);

package/dist/model.d.ts

@@ -191,7 +191,10 @@ type ShapeOf<F> = F extends z.ZodObject<infer S> ? S : F extends z.ZodRawShape ?
 type AliasOf<D> = D extends {
     alias: infer A extends string;
 } ? A : string;
-/** Хаб — объект (мастер, услуга). */
+/**
+ * Описывает класс объектов (хаб): поля, ключ, концы и свойства класса. Класс-связь объектов со своими данными
+ * описывает `link()`.
+ */
 export declare function hub<N extends string, S extends z.ZodRawShape>(name: N, shape: S, opts: Omit<ClassDef, 'fields'>): Model<N, z.output<z.ZodObject<S>>, Record<never, never>>;
 export declare function hub<N extends string, const D extends ClassDef<z.ZodRawShape, EndsInput, AnyModel | undefined>>(name: N, def?: D): Model<N, DataOf<D['extends'], ShapeOf<D['fields']>>, AllLinks<D['extends'], D['ends'] extends EndsInput ? D['ends'] : Record<never, never>>, AliasOf<D>>;
 /** Связь — отношение между объектами со своими данными (бронь, навык). */

package/dist/model.js

@@ -64,6 +64,8 @@ export function many(target, opts = {}) {
     return new End(targets, { many: true, required: (opts.min ?? 0) > 0, min: opts.min, max: opts.max, onDelete: opts.onDelete });
 }
 const NAME = /^[A-Za-zА-Яа-яЁё_][A-Za-zА-Яа-яЁё0-9_]{0,62}$/;
+/** Ключи полной формы описания класса (ClassDef). */
+const DEF_KEYS = new Set(['alias', 'extends', 'abstract', 'ends', 'fields', 'key', 'onDelete', 'history', 'ownerDefault', 'cache', 'meta', 'derivedBy', 'aggregate']);
 function isZod(v) {
     return typeof v === 'object' && v !== null && '_zod' in v;
 }
@@ -94,7 +96,11 @@ function makeModel(kind, name, defArg, optsArg) {
         throw new LetopisError('invalid_class', `имя класса ${name} недопустимо`);
     // короткая форма: hub(name, { поле: z…, … }, { key, meta, … })
     let def;
-    const isShape = defArg && typeof defArg === 'object' && Object.values(defArg).length > 0 && Object.values(defArg).every(isZod);
+    // { fields: z.object(…) } без других ключей описания — полная форма, а не класс с единственным полем fields (план 2.0,
+    // 7.5 №2); короткая форма — все значения Zod и хотя бы один ключ вне описания класса
+    const fullForm = !!defArg && typeof defArg === 'object' && defArg.fields instanceof z.ZodObject
+        && Object.keys(defArg).every((k) => DEF_KEYS.has(k));
+    const isShape = !fullForm && defArg && typeof defArg === 'object' && Object.values(defArg).length > 0 && Object.values(defArg).every(isZod);
     if (optsArg !== undefined || isShape) {
         def = { ...optsArg, fields: (defArg ?? {}) };
     }

package/dist/ops.d.ts

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

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 — без предела). Дольше —
@@ -181,6 +195,10 @@ export declare class Projector {
     /** Источники арендатора без журнала (history: false): их изменений проектор не увидит — арендатор выбывает. */
     private blind;
     private stale;
+    /** Когда состав читался в последний раз: без LISTEN сигнала о новых классах нет (план 2.0, 7.4 №6). */
+    private resolvedAt;
+    /** Участники, которых чекпоинт ещё не знает: им начальная перестройка пачками (tenantWork). */
+    private newcomers;
     /** В чекпоинте есть начатая перестройка арендатора пачками (по последней пачке; до первой — проверить). */
     private tenantsPending;
     private running;
@@ -194,6 +212,11 @@ export declare class Projector {
     /** Проходов подряд, в которых запись арендатора упиралась в lockTimeout (lockRetries). */
     private readonly lockHits;
     private readonly only;
+    /**
+     * Перечитать состав: по сигналу классов, а без LISTEN (сигналов нет) — не реже раза в 5 с, как реестр подключения в
+     * режиме none, и в начале run() (план 2.0, 7.4 №6): иначе арендатор, вступивший после запуска, не участвовал бы.
+     */
+    private due;
     constructor(env: ProjectorEnv, name: string, def: ProjectorOptions);
     /**
      * Догнать журнал и следовать за ним до stop(); { once: true } — только догнать. Первый запуск (проекции
@@ -280,8 +303,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 не складывает: её поля правят строку, и порядок таких правок важен.