letopis 1.4.0 → 1.4.1

package/dist/errors.js

@@ -12,13 +12,13 @@ export class LetopisError extends Error {
         this.detail = detail;
     }
 }
+/** Версия, в которой снято старое API (её берёт и контракт API — scripts/gen-api-contract.mjs). */
+export const REMOVED_IN = '1.0.0';
 /** Охранник снесённого API (план, этап 3, п. 11): понятная ошибка с версией и заменой. */
 export function removed(name, replacement) {
-    return new LetopisError('removed', `${name} снят в 1.0.0 — ${replacement}`);
-}
-/** Метод зарезервирован, но появится на следующем этапе плана. */
-export function notYet(name, stage) {
-    return new LetopisError('not_implemented', `${name} появится на этапе ${stage} плана 1.0`);
+    // «опция …» — женского рода; методы и свойства — мужского
+    const verb = name.startsWith('опция ') ? 'снята' : 'снят';
+    return new LetopisError('removed', `${name} ${verb} в ${REMOVED_IN} — ${replacement}`);
 }
 /** Данные не проходят описание класса (`invalid_data`). */
 export class ValidationError extends LetopisError {

package/dist/import.js

@@ -625,7 +625,14 @@ export async function import021(opts) {
             }
             if (secretRows.length) {
                 await x.begin(async (tx) => {
+                    // кред аккаунта, которого в установке нет (его нет и в Account 0.21), привязать не к чему: строка secret ссылается
+                    // на аккаунт внешним ключом (ревизия 7) — такой кред пропускается и считается в skipped
+                    const known = new Set((await tx.unsafe(`select id::text as id from ${S}.entity where id = any ($1::uuid[])`, [[...new Set(secretRows.map((s) => s.account))]])).map((r) => r.id));
                     for (const s of secretRows) {
+                        if (!known.has(s.account)) {
+                            report.credentials.skipped++;
+                            continue;
+                        }
                         const [dup] = await tx.unsafe(`select account::text as account from ${S}.secret
             where kind = $1 and casefold(ident) collate pg_unicode_fast = casefold($2) collate pg_unicode_fast and deleted_at is null`, [s.kind, s.ident]);
                         if (dup) {

package/dist/index.d.ts

@@ -29,7 +29,7 @@ export { syncModels, generateTypes, schemaToTs, type SyncResult } from './sync.j
 export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, or, isOp } from './ops.js';
 export { cursorOf } from './sql.js';
 export { inc, isInc, type IncMarker, type WriteRow } from './write.js';
-export { totpCode, hashPassword, verifyHash, type AuthApi, type LoginResult, type Credential } from './auth.js';
+export { totpCode, hashPassword, verifyHash, type AuthApi, type LoginResult, type Credential, type SessionInfo } from './auth.js';
 export type { AclApi, AclDecision, AclDataDecision, AclOp } from './acl.js';
 export type { LoadOptions, LoadReport, LoadIssue, LoadInput } from './load.js';
 export type { Chain, ChainCore, StepFn, BatchEntry } from './chain.js';
@@ -54,36 +54,41 @@ export interface ConnectOptions {
     sql?: postgres.Sql;
     /** Схема установки, например `v2.salon`. */
     schema: string;
-    /** Токен сессии; либо ключ APIKEY в `apiKey` (он же `service` — ключ сервиса) — его обменяют на сессию. */
+    /** Токен сессии; либо ключ `APIKEY` в `apiKey` (он же `service` — ключ сервиса) — его обменяют на сессию. */
     token?: string;
     apiKey?: string;
     service?: string;
     /** Продлевать сессию раз в минуту работы (по умолчанию да, §2.9). */
     refreshSession?: boolean;
-    /** Разрешить роль, которая обходит RLS (суперпользователь, BYPASSRLS, член роли-владельца), — администраторское подключение (§2.9). */
+    /** Разрешить роль, которая обходит RLS (суперпользователь, `BYPASSRLS`, член роли-владельца), — администраторское подключение (§2.9). */
     allowBypassRls?: boolean;
-    /** Имя роли-владельца (по умолчанию letopis_owner). */
+    /** Имя роли-владельца (по умолчанию `letopis_owner`). */
     owner?: string;
     /** Интервал отправки отложенного сигнала, мс (по умолчанию 100; решение 9 точки А). */
     notifyIntervalMs?: number;
-    /** Размер пула, если подключение создаёт сам connect(). */
+    /** Размер пула, если подключение создаёт сам `connect()`. */
     max?: number;
     /** Хук на каждый запрос цепочки (метрики, лог). */
     onQuery?: (e: QueryEvent) => void;
-    /** Порог медленного запроса, мс: событие получает slow; без onQuery — console.warn. */
+    /** Порог медленного запроса, мс: событие получает `slow`; без `onQuery` — `console.warn`. */
     slowMs?: number;
-    /** Модели letopis/model — только для типов цепочек (TypedDb); описания классов берутся из базы. */
+    /** Модели `letopis/model` — только для типов цепочек (`TypedDb`); описания классов берутся из базы. */
     models?: readonly AnyModelLike[];
     /**
-     * Слушать сигналы базы (LISTEN, по умолчанию да). false — пул в режиме транзакций (PgBouncer):
-     * реестр перечитывается через db.refresh(), подписка опрашивает журнал, кэш результатов выключен
-     * (с cache: { ttlOnly: true } — работает только по сроку). В установке с up({ signals: 'none' })
-     * слушателя нет всегда, а реестр раз в 5 с сверяет отпечаток классов.
+     * Слушать сигналы базы (`LISTEN`). `false` — для пула в режиме транзакций (PgBouncer): тогда реестр классов сам не
+     * обновляется (новые и изменённые классы подключение увидит после `db.refresh()`), подписка `watch()` только опрашивает
+     * журнал, а кэш результатов работает лишь с `cache: { ttlOnly: true }` — по сроку. В установке с
+     * `up({ signals: 'none' })` так всегда, только изменения классов подключение раз в 5 секунд проверяет само.
      */
     listen?: boolean;
-    /** Кэш результатов (§2.12): срок по умолчанию, размер, ttlOnly; false — выключен. */
+    /** Кэш результатов (§2.12): срок по умолчанию, размер, `ttlOnly`; `false` — выключен. */
     cache?: CacheOptions | false;
-    /** Запускать maintain() по расписанию ('1h', '15m', мс) под блокировкой обслуживания: работает один процесс. */
+    /**
+     * Запускать `maintain()` по расписанию: интервал — число миллисекунд или строка вроде `'15m'`, `'1h'`, от 1 мс до
+     * 2³¹−1 мс (около 24 суток); иначе `connect()` отказывает с `invalid_data`, не открывая соединений. Если обслуживание в
+     * этот момент уже ведёт другой процесс или ещё идёт прошлый запуск, запуск пропускается. `close()` ждёт, пока идущий
+     * запуск доделает текущую пачку.
+     */
     maintain?: string | number;
 }
 export interface DbCore {
@@ -92,50 +97,72 @@ export interface DbCore {
     /** Арендатор сессии. */
     readonly tenant: string | null;
     readonly registry: Registry;
-    /** Креды, вход и сессии (этап 5). */
+    /**
+     * Вход и сессии: способы входа (креды) — пароль, ключ API, TOTP, одноразовый код из письма или СМС, привязка внешней
+     * учётной записи; вход по ним, выпуск и гашение сессий, выбор арендатора сессии.
+     */
     readonly auth: AuthApi;
-    /** Решения прав: check(endpoint), checkData(class, op) (этап 5). */
+    /**
+     * Права того, от чьего имени идёт запрос, — заранее, для интерфейса и проверок в приложении: `check(endpoint)` — можно
+     * ли обратиться к ресурсу приложения, `checkData(класс, операция)` — можно ли читать, менять или удалять объекты
+     * класса. Сами права база применяет при каждом запросе.
+     */
     readonly acl: AclApi;
-    /** Сырой SQL под сессией и RLS, одной транзакцией (в db.begin() — в ней): db.sql`select …`. */
+    /** Сырой SQL под сессией и RLS, одной транзакцией (в `db.begin()` — в ней): `` db.sql`select …` ``. */
     sql(strings: TemplateStringsArray, ...values: unknown[]): Promise<postgres.Row[]>;
-    /** Транзакция под сессией: fn получает соединение postgres.js (в db.begin() — ту же транзакцию). */
+    /** Транзакция под сессией: `fn` получает соединение postgres.js (в `db.begin()` — ту же транзакцию). */
     transaction<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;
-    /** id объекта класса с ключом в арендаторе сессии. */
+    /** id объекта по классу и значениям ключа — такой же, какой вычислит база в арендаторе сессии. */
     idOf(cls: string, key: Readonly<Record<string, unknown>>): string;
     /** Перечитать описания классов. */
     refresh(): Promise<void>;
     /** Отправить накопленные сигналы сейчас. */
     flushSignals(): Promise<void>;
     /**
-     * Проверка цепочек хэшей и якорь (хэш всех голов); { data: true } — ещё данные, концы, арендаторы,
-     * владельцы и id всех строк. Только системный администратор или администраторское подключение.
+     * Проверяет целостность журнала всей установки: сходится ли хэш каждой версии с хэшем предыдущей и текущая строка
+     * объекта — с его последней версией; с `{ data: true }` проверяет ещё каждую строку. Якорь в ответе — один хэш текущих
+     * версий всех объектов: храните его вне базы, тогда заметна и подмена самых свежих версий. Нужно право `letopis.verify`
+     * (по умолчанию оно у системного администратора) или администраторское подключение.
      */
     verify(opts?: {
         data?: boolean;
     }): Promise<VerifyResult>;
     /** Обслуживание: истёкшие сессии и коды, прореживание журнала по политике хранения, очередь сигналов. */
     maintain(opts?: MaintainOptions): Promise<MaintainReport>;
-    /** Сброс sessions | tenant | all (allowReset установки, право letopis.reset, confirm — имя схемы). */
+    /**
+     * Сбрасывает тестовую установку: сессии, данные одного арендатора или всё — смотря по `level`. Работает, только если
+     * установка поставлена с `up({ allowReset: true })`, у вызывающего есть право `letopis.reset` (или подключение
+     * администраторское), а `confirm` совпадает с именем схемы.
+     */
     reset(opts: ResetOptions): Promise<ResetResult>;
-    /** Обрезка истории до момента: класса (с потомками), id, списка id или строк; версия 1 → запись trim. */
+    /**
+     * Стирает версии, сделанные раньше момента `before`; текущая версия остаётся всегда. Вместо стёртого начала истории
+     * остаётся служебная запись `trim` со временем появления объекта.
+     */
     trimHistory(target: string | string[] | Row | Row[], before: string | Date): Promise<number>;
-    /** Новый ключ класса: строки семейства переносятся на новые id, ссылки переводятся. */
+    /**
+     * Меняет ключ класса. Объекты его семейства (сам класс и потомки), у которых по новому ключу выходит другой id,
+     * переезжают на новый id, а ссылки на них переводятся.
+     */
     rekeyClass(cls: string, key: string[]): Promise<number>;
-    /** Машинное описание модели с метаданными классов (describeText — то же текстом, llms.txt). */
+    /**
+     * Описание модели для программ и языковых моделей: классы арендатора сессии и общие классы System с полями, ключом,
+     * ссылками и метаданными `meta`. `describeText(db.describe())` превращает его в текст.
+     */
     describe(): ModelDescription;
-    /** Подписка по курсору: for await (const ev of db.watch({ from })) …; ev.cursor — откуда продолжить. */
+    /** Подписка по курсору: `for await (const ev of db.watch({ from })) …`; `sub.cursor` — откуда продолжить. */
     watch(opts?: WatchOptions): Subscription;
     /** Кэш результатов подключения. */
     readonly cache: {
         clear(): void;
         stats(): CacheStats;
     };
-    /** Начать путь с готового узла: db.entity(row | цепочка). */
+    /** Начать путь с готового узла: `db.entity(row | цепочка)`. */
     entity(x: Chain | Row): Chain;
     /**
-     * Тот же пул от имени аккаунта (letopis.account: имперсонацию проверяет база — право сервиса
-     * auth.impersonate), в арендаторе tenant (собственный аккаунта или по членству) и с явным владельцем
-     * новых строк: await db.as(account, { tenant, owner }). account = null — тот же актор.
+     * Подключение на том же пуле от имени другого аккаунта: запросы идут с его правами и в его арендаторе. Журнал
+     * записывает автором версий этот аккаунт, а исполнителем (`agent`) — аккаунт сессии, например сервис. Нужно право
+     * `auth.impersonate`.
      */
     as(account: string | {
         id: string;
@@ -143,50 +170,52 @@ export interface DbCore {
         owner?: string;
         tenant?: string;
     }): Promise<Db>;
-    /** Явная транзакция read committed: те же цепочки, commit(), rollback(), lock(), forUpdate(). */
-    /** Явная транзакция; reason — причина изменения для всех операций блока (план 1.1). */
+    /** Явная транзакция `read committed`: те же цепочки, `commit()`, `rollback()`, `lock()`, `forUpdate()`. */
+    /** Явная транзакция; `reason` — причина изменения для всех операций блока (план 1.1). */
     begin(opts?: {
         reason?: string;
     }): Promise<DbTx>;
     /**
-     * Загрузчик (§2.6): строки любых классов — проверки в коде, COPY от роли владельца, один запрос по
-     * целям вне загрузки. Только на администраторском подключении (иначе admin_required).
+     * Массовая загрузка строк любых классов одной транзакцией (или порциями `commitEvery`) — быстрее записи цепочками.
+     * Строки проверяются по тому же описанию класса, что и при обычной записи (данные, ссылки, ключ), уходят в базу
+     * командой `COPY`, а ссылки на объекты вне загрузки сверяет один запрос в конце; права проверяются только при загрузке
+     * от имени пользователя (опция `as`). Работает только на администраторском подключении, иначе `admin_required`.
      */
     load(input: LoadInput, opts?: LoadOptions): Promise<LoadReport>;
     /**
-     * Проектор из журнала (план 1.1, §2.4): строит строки производных классов (derivedBy: имя) из изменений
-     * классов from; run() — догнать журнал и следовать за ним, rebuild() — перестроить с текущего состояния.
-     * Только на администраторском подключении (иначе admin_required).
+     * Проектор из журнала (план 1.1, §2.4): строит строки производных классов (`derivedBy: имя`) из изменений
+     * классов `from`; `run()` — догнать журнал и следовать за ним, `rebuild()` — перестроить с текущего состояния.
+     * Только на администраторском подключении (иначе `admin_required`).
      */
     projector(name: string, opts: ProjectorOptions): Projector;
     /**
      * Ремонт агрегатов в базе (план 1.1, §2.4): поля класса (с потомками) во всех арендаторах — заново из живых строк
      * источников, под исключительными блокировками; версия — только у исправленных. Возвращает их число. Только на
-     * администраторском подключении (иначе admin_required).
+     * администраторском подключении (иначе `admin_required`).
      */
     rebuildAggregates(cls: string): Promise<number>;
     /**
-     * Именованная очередь планов фасада: batch.Класс(…).create(…); batch.run() — одной транзакцией. У корня,
-     * у каждого db.as() и у каждой db.begin() очереди свои: план исполняется от имени фасада, который его поставил.
+     * Именованная очередь планов фасада: `batch.Класс(…).create(…)`; `batch.run()` — одной транзакцией. У корня,
+     * у каждого `db.as()` и у каждой `db.begin()` очереди свои: план исполняется от имени фасада, который его поставил.
      */
     batch(name: string, opts?: {
         reason?: string;
     }): Batch;
-    /** Advisory-блокировка до конца транзакции — только в db.begin() (иначе tx_required). */
+    /** Advisory-блокировка до конца транзакции — только в `db.begin()` (иначе `tx_required`). */
     lock(...keys: (string | number)[]): Promise<void>;
-    /** Зафиксировать транзакцию tr (то же, что tr.commit()). */
+    /** Зафиксировать транзакцию `tr` (то же, что `tr.commit()`). */
     commit(tr?: DbTx): Promise<void>;
-    /** Откатить транзакцию tr (то же, что tr.rollback()). */
+    /** Откатить транзакцию `tr` (то же, что `tr.rollback()`). */
     rollback(tr?: DbTx): Promise<void>;
     close(): Promise<void>;
 }
-/** Подключение: служебные методы и классы как стартовые шаги цепочек — db.Класс(фильтр). */
+/** Подключение: служебные методы и классы как стартовые шаги цепочек — `db.Класс(фильтр)`. */
 export type Db = DbCore & {
     [className: string]: StepFn;
 };
-/** Явная транзакция db.begin(): тот же API; ошибка любого запроса её ломает (§2.5). */
+/** Явная транзакция `db.begin()`: тот же API; ошибка любого запроса её ломает (§2.5). */
 export type DbTx = Db;
-/** Подключение с типами шагов, строк и фильтров по моделям: connect({ models }). */
+/** Подключение с типами шагов, строк и фильтров по моделям: `connect({ models })`. */
 export type TypedDb<M extends readonly AnyModelLike[]> = DbCore & StepsOf<M> & {
     [className: string]: StepFn;
 };

package/dist/index.js

@@ -23,7 +23,7 @@ import { ACL_CLASSES, ResultCache } from './cache.js';
 import { Subscription } from './watch.js';
 import { Projector } from './project.js';
 import { SIGNAL_MODES, Signals, bucket, throttle } from './signals.js';
-import { describe as describeModel, maintain as runMaintain, rebuildAggregates as runRebuildAggregates, rekeyClass as runRekeyClass, reset as runReset, scheduleMaintain, trimHistory as runTrim, verify as runVerify, } from './admin.js';
+import { describe as describeModel, maintain as runMaintain, rebuildAggregates as runRebuildAggregates, rekeyClass as runRekeyClass, reset as runReset, MAINTAIN_STOP, parseInterval, scheduleMaintain, trimHistory as runTrim, verify as runVerify, } from './admin.js';
 import { stampDrift } from './up.js';
 export { DDL_REVISION } from './types.js';
 export { uuidv5, v5Name, v5Id, idOf } from './uuid.js';
@@ -233,6 +233,8 @@ export async function connect(opts) {
     for (const k of Object.keys(opts))
         if (k in REMOVED_OPTIONS)
             throw removed(`опция connect({ ${k} })`, REMOVED_OPTIONS[k]);
+    // интервал обслуживания — до пула и таймеров: неверный не оставляет за собой открытых соединений
+    const maintainEvery = opts.maintain === undefined ? undefined : parseInterval(opts.maintain);
     const own = !opts.sql;
     // timestamptz — строкой: Date в JS режет микросекунды, а на них держатся asOf и курсоры по времени
     const sql = (opts.sql ?? postgres(opts.dsn, {
@@ -268,7 +270,11 @@ export async function connect(opts) {
             throw new LetopisError('invalid_data', `connect: схемы ${opts.schema} нет — установите её: up({ schema })`);
         if (rev < DDL_REVISION)
             console.warn(`letopis: движок схемы ${opts.schema} ревизии ${rev}, библиотека ждёт ${DDL_REVISION} — обновите: up({ schema: '${opts.schema}', upgrade: true })`);
-        else if (rev === DDL_REVISION) {
+        // схему обновил более новый пакет (во время раскатки старые экземпляры ещё работают): подключаемся, но предупреждаем —
+        // этот пакет может не знать функций и колонок новой ревизии; up() такую схему не трогает и отказывает
+        else if (rev > DDL_REVISION)
+            console.warn(`letopis: движок схемы ${opts.schema} ревизии ${rev} новее библиотеки (она знает ${DDL_REVISION}) — обновите пакет letopis`);
+        else {
             // ревизия та же, а функции схемы ставила другая версия движка — штамп в комментарии схемы (99-revision.sql)
             const drift = await stampDrift(opts.schema, String(rv.c ?? ''));
             if (drift)
@@ -472,7 +478,8 @@ export async function connect(opts) {
             signals,
             listen,
             async close() {
-                stopMaintain?.();
+                // идущий maintain() по расписанию доделывает пачку: пул закрывается после неё, а не посреди транзакции
+                await stopMaintain?.();
                 resync.stop();
                 startReload.stop();
                 if (stamper)
@@ -484,8 +491,8 @@ export async function connect(opts) {
             },
         };
         const db = makeDb(shared, { txc: ctx, tenant: () => root.tenant, registry: () => root.registry, root: true }, poolExecutor(ctx));
-        if (opts.maintain !== undefined)
-            stopMaintain = scheduleMaintain(() => db.maintain(), opts.maintain);
+        if (maintainEvery !== undefined)
+            stopMaintain = scheduleMaintain((stopped) => db.maintain({ [MAINTAIN_STOP]: stopped }), maintainEvery);
         return db;
     }
     catch (e) {

package/dist/load.d.ts

@@ -12,7 +12,10 @@ export interface LoadOptions {
     batch?: number;
     /** Фиксировать порциями примерно по N строк (порция — классы в порядке зависимостей, цикл — целиком). */
     commitEvery?: number;
-    /** Режим истории (импорт): строки — версии с $rev, $at и $op; пишутся волнами. */
+    /**
+     * Режим истории (импорт): каждая строка — версия объекта с номером `$rev`, временем `$at` и видом операции `$op`; так
+     * переносят историю объектов из другой системы.
+     */
     withHistory?: boolean;
     /** В конце перепроверить загруженные строки проверкой базы. */
     verify?: boolean;
@@ -20,7 +23,10 @@ export interface LoadOptions {
     class?: string;
     /** Арендатор строк (по умолчанию — арендатор сессии). */
     tenant?: string;
-    /** Агент версий (по умолчанию «letopis load»; импорт — «letopis import»). */
+    /**
+     * Исполнитель записи — строка, которую журнал сохранит в поле `agent` загруженных версий рядом с автором (по умолчанию
+     * «letopis load»; импорт — «letopis import»).
+     */
     agent?: string;
     /**
      * Загрузка от имени пользователя (§2.6, п. 10): автор версий — он; арендатор (по умолчанию —
@@ -128,7 +134,8 @@ export declare function load(env: LoadEnv, input: LoadInput, opts?: LoadOptions)
  * Первая заливка (план 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. В конце — ограничения (дубликат найдёт сортировка), индексы,

package/dist/load.js

@@ -924,7 +924,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 +1020,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 +1042,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 +1053,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. В конце — ограничения (дубликат найдёт сортировка), индексы,
@@ -1081,7 +1088,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 +1118,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)

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

@@ -782,10 +782,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/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;