letopis 3.0.0 → 3.0.1

package/dist/messages/mcp.js

@@ -1,7 +1,7 @@
 /** Неизвестное имя класса, алиаса или роли: агенту доступна не db.registry, а letopis_model. */
 const NAME_HINT = 'проверить имя: похожие названы в тексте и в similar, классы, алиасы и концы — letopis_model';
-/** Удаление сорвалось после превью: превью — заново. */
-const PREVIEW_HINT = 'посмотреть превью заново (delete без confirm) и повторить удаление с confirm: true';
+/** Удаление сорвалось после предпросмотра: предпросмотр — заново. */
+const PREVIEW_HINT = 'посмотреть предпросмотр заново (delete без confirm) и повторить удаление с confirm: true';
 /** Неверная опция createMcpServer. */
 const OPTION_HINT = 'исправить опцию createMcpServer: допустимые значения названы в тексте';
 export const mcp = {
@@ -300,7 +300,7 @@ export const mcp = {
     // mcp.ts, write: код операции агента не совпал с превью (detail.operation — нынешний)
     'mcp.delete_operation_changed': {
         code: 'confirmation_required',
-        ru: 'letopis_write: операция изменилась после превью — посмотрите превью заново',
+        ru: 'letopis_write: операция изменилась после предпросмотра — посмотрите предпросмотр заново',
         hint: PREVIEW_HINT,
     },
     // mcp.ts, write: целей удаления не видно
@@ -308,10 +308,10 @@ export const mcp = {
         code: 'target_not_found',
         ru: 'letopis_write: удалять нечего — целей не видно',
     },
-    // mcp.ts, write: в превью есть $action restrict (detail.preview)
+    // mcp.ts, write: в превью есть $action restrict или сводка скрытых строк $hidden restrict (detail.preview)
     'mcp.delete_restricted': {
         code: 'delete_restricted',
-        ru: 'letopis_write: удалению мешают строки с $action: restrict',
+        ru: 'letopis_write: удалению мешают строки с $action: restrict (или скрытые правами — сводка $hidden: restrict)',
     },
     // mcp.ts, confirmDelete (stateError): requestState не той операции, не того пользователя или подделан
     'mcp.delete_foreign_answer': {
@@ -321,7 +321,7 @@ export const mcp = {
     // mcp.ts, confirmDelete (stateError): срок requestState истёк
     'mcp.delete_answer_expired': {
         code: 'confirmation_required',
-        ru: 'letopis_write: удаление не выполнено — подтверждение устарело — посмотрите превью и подтвердите удаление заново',
+        ru: 'letopis_write: удаление не выполнено — подтверждение устарело — посмотрите предпросмотр и подтвердите удаление заново',
         hint: PREVIEW_HINT,
     },
     // mcp.ts, confirmDelete: человек отказал или закрыл окно
@@ -337,7 +337,7 @@ export const mcp = {
     // mcp.ts, write: повторное превью в транзакции разошлось с подтверждённым
     'mcp.delete_data_changed': {
         code: 'confirmation_required',
-        ru: 'letopis_write: данные изменились после подтверждения — посмотрите превью заново',
+        ru: 'letopis_write: данные изменились после подтверждения — посмотрите предпросмотр заново',
         hint: PREVIEW_HINT,
     },
     // mcp.ts, limitsOf: maxRows, maxBytes — не целое из диапазона

package/dist/messages/model.d.ts

@@ -244,6 +244,22 @@ export declare const model: {
         code: "invalid_query";
         ru: string;
     };
+    'model.cli_unknown_flag': {
+        code: "invalid_query";
+        ru: string;
+    };
+    'model.cli_flag_needs_value': {
+        code: "invalid_query";
+        ru: string;
+    };
+    'model.cli_flag_no_value': {
+        code: "invalid_query";
+        ru: string;
+    };
+    'model.cli_unexpected_arg': {
+        code: "invalid_query";
+        ru: string;
+    };
     'model.types_header': {
         code: "invalid_query";
         ru: string;

package/dist/messages/model.js

@@ -299,6 +299,24 @@ export const model = {
         code: 'invalid_query',
         ru: 'правило {kind} в {path} проверяется только в библиотеке — в базе его нет',
     },
+    // cli.ts, main: ошибка разбора аргументов (node:util parseArgs) — текст по-русски вместо английского текста Node (lmsg,
+    // код не печатается; выход с кодом 2). flag — флаг, как его передали (--aply, -x); arg — лишний аргумент
+    'model.cli_unknown_flag': {
+        code: 'invalid_query',
+        ru: 'неизвестный флаг {flag}; см. letopis --help',
+    },
+    'model.cli_flag_needs_value': {
+        code: 'invalid_query',
+        ru: 'флагу {flag} нужно значение: {flag} <значение> или {flag}=<значение>; см. letopis --help',
+    },
+    'model.cli_flag_no_value': {
+        code: 'invalid_query',
+        ru: 'флаг {flag} не принимает значения — уберите «=…» после него; см. letopis --help',
+    },
+    'model.cli_unexpected_arg': {
+        code: 'invalid_query',
+        ru: 'лишний аргумент {arg}; см. letopis --help',
+    },
     // sync.ts, generateTypes: пометка в первой строке файла типов (после «// ») — текст не для ошибки
     'model.types_header': {
         code: 'invalid_query',
@@ -308,7 +326,7 @@ export const model = {
     // и валидатор letopis его не исполняют, данные записались бы как есть; rules — пути и виды через запятую
     'model.transform_unsupported': {
         code: 'invalid_class',
-        ru: 'преобразования Zod не исполняются при записи: {rules}',
-        hint: 'привести значение до записи в коде сервиса (например, value.trim()) и убрать преобразование из модели; проверку без изменения значения дают .regex(), .min(), .refine()',
+        ru: 'в модели есть преобразования Zod, а при записи их никто не исполняет — значение записалось бы как есть; поля с преобразованием: {rules}',
+        hint: 'уберите из модели .trim(), .toLowerCase(), .transform(), z.preprocess() и .pipe() и приводите значение в коде сервиса до записи (например, name.trim()); проверку без изменения значения дают .regex(), .min(), .refine()',
     },
 };

package/dist/messages/write.d.ts

@@ -172,6 +172,11 @@ export declare const write: {
         ru: string;
         hint: string;
     };
+    'write.delete_restricted': {
+        code: "delete_restricted";
+        ru: string;
+        hint: string;
+    };
     'write.link_in_data': {
         code: "invalid_data";
         ru: string;

package/dist/messages/write.js

@@ -62,7 +62,7 @@ export const write = {
     // create() или upsert() на возврате к узлу пути
     'write.create_on_pivot': {
         code: 'invalid_query',
-        ru: '{verb}() на возврате к узлу — он ведёт к существующей сущности, используйте update()',
+        ru: '{verb}() на возврате к узлу — он ведёт к существующему объекту, используйте update()',
     },
     // create() или upsert() после шага с фильтром, а не с id
     'write.create_with_filter': {
@@ -100,7 +100,7 @@ export const write = {
     // слот после глагола, который слотов не принимает
     'write.slot_bad_verb': {
         code: 'invalid_query',
-        ru: 'слот .{role} после {verb}() — слоты у create(), update() и upsert()',
+        ru: 'шаг роли .{role} после {verb}() — шаги ролей бывают только у create(), update() и upsert()',
     },
     // write.ts:slotRole: имя слота — не роль записываемого класса и не класс реестра
     'write.slot_unknown': {
@@ -115,22 +115,22 @@ export const write = {
     // write.ts:slotRole: класс слота принимают несколько ролей
     'write.slot_ambiguous': {
         code: 'invalid_query',
-        ru: 'слот {name} у класса {cls} неоднозначен: роли {roles} — назовите роль',
+        ru: 'шаг {name} у класса {cls} неоднозначен: роли {roles} — назовите роль',
     },
     // конец из пути: шаг подходит нескольким ролям
     'write.end_ambiguous': {
         code: 'invalid_query',
-        ru: 'конец класса {cls} для шага {step} неоднозначен: роли {roles} — назовите шаг ролью или задайте слот',
+        ru: 'конец класса {cls} для шага {step} неоднозначен: роли {roles} — назовите шаг ролью или задайте конец шагом роли после глагола',
     },
     // конец из пути: шаг дал не одну сущность; count — сколько найдено
     'write.end_not_single': {
         code: 'invalid_query',
-        ru: 'шаг {step} должен дать ровно одну сущность для конца {cls} (найдено {count})',
+        ru: 'шаг {step} должен дать ровно один объект для конца {cls} (найдено {count})',
     },
     // слот .роль.set() одиночного конца — значение дало несколько сущностей
     'write.slot_single_many': {
         code: 'invalid_query',
-        ru: 'слот .{role}.set(): конец одиночный, а значение дало {count} сущностей',
+        ru: 'шаг роли .{role}.set(): конец одиночный, а значение дало объектов: {count}',
     },
     // write.ts:existsError: create() — объект уже есть, id не вычислить
     'write.exists': {
@@ -207,32 +207,40 @@ export const write = {
     // restore({ expect }), delete({ expect }): expect — не список строк { id, rev }; verb — глагол
     'write.bad_expect': {
         code: 'invalid_query',
-        ru: '{verb}({ expect }): expect — список строк { id, rev } (строки ответа)',
+        ru: '{verb}({ expect }): expect — список строк { id, rev } (строки ответа; у delete — и строки-сводки предпросмотра как есть)',
     },
     // delete({ expect }) без confirm: превью сравнивать не с чем
     'write.expect_without_confirm': {
         code: 'invalid_query',
-        ru: 'delete({ expect }) — только с { confirm: true }: без него delete() и есть превью',
+        ru: 'delete({ expect }) — только с { confirm: true }: без него delete() и есть предпросмотр',
     },
     // delete({ confirm: true, expect }): превью в транзакции удаления не совпало с показанным; detail.preview — новое превью
     'write.preview_changed': {
         code: 'conflict',
-        ru: 'delete({ confirm: true, expect }): превью изменилось с тех пор, как его показали — ничего не удалено',
-        hint: 'показать пользователю новое превью (err.detail.preview) и удалить с ним: delete({ confirm: true, expect: err.detail.preview })',
+        ru: 'delete({ confirm: true, expect }): предпросмотр изменился с тех пор, как его показали — ничего не удалено',
+        hint: 'показать пользователю новый предпросмотр (err.detail.preview) и удалить с ним: delete({ confirm: true, expect: err.detail.preview })',
+    },
+    // write.ts, checkRestrict (3.0.1): сверенный предпросмотр delete({ confirm: true, expect }) содержит мешающие строки
+    // (restrict) — видимые или сводку скрытых правами; отказ до удаления. visible — число видимых, others — скрытых;
+    // detail — { rows: [{ id, class }], others }, как у отказа триггера (sql-write.delete_restricted)
+    'write.delete_restricted': {
+        code: 'delete_restricted',
+        ru: 'удалению мешают ссылающиеся строки: видимых {visible}, скрытых правами {others} — ничего не удалено',
+        hint: 'показать пользователю мешающие строки (err.detail.rows); скрытые правами (err.detail.others) видит только их владелец — обратиться к нему; удалить или перевести мешающие строки (или сменить у их конца onDelete) и заново показать предпросмотр delete()',
     },
     // write.ts, checkFullData и checkPatchEnds (3.0, вместо api.validation_failed_end): лишний ключ данных — конец класса
     // (имя роли или класса на конце); keys — такие ключи, role — роль первого из них. Нарушения ValidationError дописывает
     // к тексту сам
     'write.link_in_data': {
         code: 'invalid_data',
-        ru: '{verb}() у {cls}: {keys} — связь, а не поле данных; конец задают путь цепочки или слот после глагола: .{role}.set(id)',
-        hint: 'конец (связь) — не поле данных: путь цепочки (db.Владелец(id).Класс().create(…)) или слот после глагола: db.Класс.create({ … }).Роль.set(id); у конца-списка — .Роль.add(id) / .Роль.remove(id), снять — .Роль.unset()',
+        ru: '{verb}() у {cls}: {keys} — связь, а не поле данных; конец задают путь цепочки или шаг роли после глагола: .{role}.set(id)',
+        hint: 'конец (связь) — не поле данных: путь цепочки (db.Владелец(id).Класс().create(…)) или шаг роли после глагола: db.Класс.create({ … }).Роль.set(id); у конца-списка — .Роль.add(id) / .Роль.remove(id), снять — .Роль.unset()',
     },
     // 3.0: delete({ confirm: true }) без expect и без all — удаление не сверено с показанным превью
     'write.confirm_without_expect': {
         code: 'invalid_query',
-        ru: 'delete({ confirm: true }) без { expect }: удаление не сверено с превью, которое видел пользователь — ничего не удалено',
-        hint: 'передайте expect из превью: const p = await db.Класс(id).delete().rows(); показать p пользователю; await db.Класс(id).delete({ confirm: true, expect: p }).rows(). Осознанно удалить текущий состав без сверки — delete({ confirm: true, all: true })',
+        ru: 'delete({ confirm: true }) без { expect }: удаление не сверено с предпросмотром, который видел пользователь — ничего не удалено',
+        hint: 'передайте expect из предпросмотра: const p = await db.Класс(id).delete().rows(); показать p пользователю; await db.Класс(id).delete({ confirm: true, expect: p }).rows(). Осознанно удалить текущий состав без сверки — delete({ confirm: true, all: true })',
     },
     // 3.0: restore() без expect и без all — и для явных id: последнее надгробие могло смениться с тех пор, как его видели
     'write.restore_without_expect': {

package/dist/model.d.ts

@@ -29,7 +29,11 @@ type TargetName<T> = T extends string ? T : T extends {
 type MinRequired<O> = O extends {
     min: infer N;
 } ? (N extends 0 | undefined ? false : number extends N ? boolean : true) : false;
-/** Конец класса: `one(X)`, `one(A, B)`, `many(X, { min, max })`. `T` — имена классов целей (только для типов). */
+/**
+ * Конец класса: `one(X)`, `one(A, B)`, `many(X, { min, max })`. Параметры типа: `Many` — конец-список, `Required` —
+ * обязателен, `T` — имена классов целей (только для типов). `min`, `max`, `onDeleteRule`, `metaData` необязательны:
+ * не заданы — `undefined`.
+ */
 export declare class End<Many extends boolean = boolean, Required extends boolean = boolean, T extends string = string> {
     readonly targets: readonly Target[];
     readonly many: Many;
@@ -38,7 +42,7 @@ export declare class End<Many extends boolean = boolean, Required extends boolea
     readonly max?: number;
     readonly onDeleteRule?: OnDelete;
     readonly metaData?: Record<string, unknown>;
-    /** Только для вывода типов: имена классов целей — строгие переходы и слоты цепочек (план 2.0, этап 4, п. 1). */
+    /** Только для вывода типов: имена классов целей — строгие переходы и шаги ролей цепочек. */
     readonly __targets?: T;
     constructor(targets: readonly Target[], opts: {
         many: Many;

package/dist/model.js

@@ -14,7 +14,11 @@ import { z } from 'zod';
 import { lerr } from './errors.js';
 import { normalizeSchema } from './jsonschema.js';
 import { RESERVED_CLASS_NAMES } from './types.js';
-/** Конец класса: `one(X)`, `one(A, B)`, `many(X, { min, max })`. `T` — имена классов целей (только для типов). */
+/**
+ * Конец класса: `one(X)`, `one(A, B)`, `many(X, { min, max })`. Параметры типа: `Many` — конец-список, `Required` —
+ * обязателен, `T` — имена классов целей (только для типов). `min`, `max`, `onDeleteRule`, `metaData` необязательны:
+ * не заданы — `undefined`.
+ */
 export class End {
     targets;
     many;

package/dist/registry.d.ts

@@ -41,6 +41,12 @@ interface ClassRow {
         resolved: Record<string, unknown>;
     };
 }
+/**
+ * Реестр классов сессии — `db.registry`: описания классов арендатора и системных классов, как их видит подключение.
+ * Методы: `has(имя)` — есть ли класс или алиас; `find(имя)` — описание `ClassInfo` или `undefined`; `resolve(имя)` — то же,
+ * а неизвестное имя — `invalid_class`; `all()` — все классы; `family(имя)` — класс и его потомки; `leafType(класс, путь)` —
+ * тип поля по пути в данных; `load(строки)` — заменить содержимое (его зовёт само подключение, `db.refresh()`).
+ */
 export declare class Registry {
     private byName;
     private byAlias;

package/dist/registry.js

@@ -5,6 +5,12 @@
  */
 import { lerr } from './errors.js';
 import { compileValidator } from './validate.js';
+/**
+ * Реестр классов сессии — `db.registry`: описания классов арендатора и системных классов, как их видит подключение.
+ * Методы: `has(имя)` — есть ли класс или алиас; `find(имя)` — описание `ClassInfo` или `undefined`; `resolve(имя)` — то же,
+ * а неизвестное имя — `invalid_class`; `all()` — все классы; `family(имя)` — класс и его потомки; `leafType(класс, путь)` —
+ * тип поля по пути в данных; `load(строки)` — заменить содержимое (его зовёт само подключение, `db.refresh()`).
+ */
 export class Registry {
     byName = new Map();
     byAlias = new Map();

package/dist/sync.d.ts

@@ -27,10 +27,9 @@ export declare function syncModels(db: DbCore, models: readonly AnyModel[], opts
 export declare function schemaToTs(s: JsonSchema | undefined, indent?: string): string;
 /**
  * Объявления `<Класс>Data` и `<Класс>Links` для классов реестра и `<Класс>Model` — имя, алиас, концы с классами целей
- * и предки (ModelLike, typed.ts), — а в конце список `Models`: строгие типы цепочек без моделей Zod, `connect<Models>()`
- * (план 2.0, этап 4, п. 1). Классы арендатора System (системные и классы сидов пакета) — только с includeSystem
- * (`letopis types --system`); без него системные классы даёт встроенный набор SystemModels. Пометка в первой строке —
- * запись каталога model.types_header.
+ * и предки, — а в конце список `Models`: строгие типы цепочек без моделей Zod, `connect<Models>()`. Классы арендатора
+ * System (системные и классы сидов пакета) — только с includeSystem (`letopis types --system`); без него системные
+ * классы даёт встроенный набор SystemModels. Первая строка — пометка «Сгенерировано letopis types — не править руками.»
  */
 export declare function generateTypes(registry: Registry, opts?: {
     includeSystem?: boolean;

package/dist/sync.js

@@ -166,10 +166,9 @@ export function schemaToTs(s, indent = '') {
 }
 /**
  * Объявления `<Класс>Data` и `<Класс>Links` для классов реестра и `<Класс>Model` — имя, алиас, концы с классами целей
- * и предки (ModelLike, typed.ts), — а в конце список `Models`: строгие типы цепочек без моделей Zod, `connect<Models>()`
- * (план 2.0, этап 4, п. 1). Классы арендатора System (системные и классы сидов пакета) — только с includeSystem
- * (`letopis types --system`); без него системные классы даёт встроенный набор SystemModels. Пометка в первой строке —
- * запись каталога model.types_header.
+ * и предки, — а в конце список `Models`: строгие типы цепочек без моделей Zod, `connect<Models>()`. Классы арендатора
+ * System (системные и классы сидов пакета) — только с includeSystem (`letopis types --system`); без него системные
+ * классы даёт встроенный набор SystemModels. Первая строка — пометка «Сгенерировано letopis types — не править руками.»
  */
 export function generateTypes(registry, opts = {}) {
     const out = [`// ${lmsg('model.types_header')}`, ''];

package/dist/typed.d.ts

@@ -6,7 +6,7 @@
  * - переходы цепочки выводятся из концов, как в resolveHop (lib/src/sql.ts): от класса C — роли его семейства (C и
  *   потомков) и классы, связанные с семейством C концом в любую сторону (роль, имя которой совпало с именем класса,
  *   во время выполнения — шаг класса, так же и здесь);
- * - слоты — только роли класса C: `set(id | строка | цепочка)`, `add` и `remove` — у множественного конца, `unset` —
+ * - шаги ролей после глагола — только роли класса C: `set(id | строка | цепочка)`, `add` и `remove` — у множественного конца, `unset` —
  *   у необязательного;
  * - поля фильтров, `or()` и агрегатов `sum`, `avg`, `min`, `max`, `countBy` — поля класса.
  * Чего типы не знают: возврат к узлу связи из пути (pivot) от класса, с которым связь не связана концом, и роль чужого
@@ -214,11 +214,11 @@ export type StepsOf<M extends readonly AnyModelLike[]> = {
 } & {
     [K in AllOf<M> as AliasOf<K>]: StepFnOf<K, M>;
 };
-/** Значение слота одиночного конца: id, строка ответа или цепочка. */
+/** Значение шага роли одиночного конца (`.Роль.set(…)`): id, строка ответа или цепочка. */
 type SlotOne = string | {
     readonly id: string;
 } | ChainRef;
-/** Значение слота множественного конца: ещё и список id или строк. */
+/** Значение шага роли множественного конца (`.Роль.add(…)`, `.remove(…)`): ещё и список id или строк. */
 type SlotMany = SlotOne | readonly (string | {
     readonly id: string;
 })[];
@@ -248,7 +248,7 @@ type HopsOf<C, M extends readonly AnyModelLike[], All = AllOf<M>> = {
 type Retyped = 'paths' | 'rows' | 'first' | 'versions' | 'limit' | 'offset' | 'sort' | 'asOf' | 'after' | 'withDeleted' | 'deep' | 'exact' | 'alias' | 'tags' | 'owner' | 'create' | 'update' | 'upsert' | 'delete' | 'forUpdate' | 'restore' | 'cache' | 'sum' | 'avg' | 'min' | 'max' | 'countBy';
 /**
  * Цепочка с текущим классом C (у шага-роли с несколькими целями — их союз): терминалы отдают RowOf<C>, шаги — переходы
- * из концов, слоты — роли C, агрегаты — поля C.
+ * из концов, шаги ролей после глагола (`.Роль.set(…)`) — роли C, агрегаты — поля C.
  */
 export type TypedChain<C, M extends readonly AnyModelLike[]> = Omit<ChainCore, Retyped> & {
     paths(): Promise<Path[]>;
@@ -291,8 +291,8 @@ export type TypedChain<C, M extends readonly AnyModelLike[]> = Omit<ChainCore, R
         reason?: string;
     }): TypedChain<C, M>;
     /**
-     * Без опций — превью. `{ confirm: true, expect: превью }` — удалить ровно показанное (цели сужены фильтром, id, `tags()`,
-     * `owner()` или `limit()`); `{ confirm: true }` без `expect` — `invalid_query` (`write.confirm_without_expect`);
+     * Без опций — предпросмотр. `{ confirm: true, expect: предпросмотр }` — удалить ровно показанное (цели сужены фильтром, id, `tags()`,
+     * `owner()` или `limit()`); `{ confirm: true }` без `expect` — `invalid_query`;
      * осознанно удалить текущий состав без сверки — `{ confirm: true, all: true }`.
      */
     delete(opts?: DeleteOptions): TypedChain<C, M>;

package/dist/types.d.ts

@@ -3,7 +3,7 @@
  */
 /**
  * Ревизия схемы, которую знает эта версия пакета, — номер версии SQL-части letopis (таблиц и функций в схеме установки).
- * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии 2.x `up()` обновляет только с
+ * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии (того же поколения `v2`) `up()` обновляет только с
  * `upgrade: true`, а `connect()` о ней предупреждает.
  */
 export declare const DDL_REVISION = 11;
@@ -18,7 +18,7 @@ export declare const SCHEMA_VERSION = "v2";
  */
 export declare const ACL_CLASS_NAMES: readonly string[];
 /**
- * Имена методов цепочки: модификаторы, терминалы, глаголы записи и слоты концов, а также `then`. После шага цепочки эти
+ * Имена методов цепочки: модификаторы, терминалы, глаголы записи и шаги роли, а также `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", "restore", "alias", "tags", "owner", "forUpdate", "cache"];
@@ -51,17 +51,22 @@ export interface Row<D = Record<string, unknown>, L = Record<string, string | st
     /** Вид операции версии: create, update, delete, restore, … */
     op: string;
     reason?: string;
-    /** Надгробие: удалённая сущность (withDeleted) или версия удаления (versions). */
+    /** Надгробие: удалённый объект (withDeleted) или версия удаления (versions). */
     $deleted?: true;
-    /** Глубина узла при deep() (1 — прямой потомок); в превью удаления — уровень каскада (0 — цель). */
+    /** Глубина узла при deep() (1 — прямой потомок); в предпросмотре удаления — уровень каскада (0 — цель). */
     $depth?: number;
     /** Что сделал upsert. */
     $upsert?: 'created' | 'updated' | 'unchanged';
     /**
      * Превью удаления (delete() без confirm): удалится, снимется конец или помешает (restrict). В ответе
-     * `restore({ expect, partial: true })` — `skip`: цель не восстановлена, причина — `$why`.
+     * `restore({ expect, partial: true })` — `skip`: цель не восстановлена, причина — `$why`. `hidden` — строка-сводка
+     * предпросмотра, а не объект: скрытые правами строки замыкания (что с ними будет — `$hidden`, сколько — `$count`).
      */
-    $action?: 'delete' | 'unset' | 'restrict' | 'skip';
+    $action?: 'delete' | 'unset' | 'restrict' | 'skip' | 'hidden';
+    /** Строка-сводка предпросмотра удаления (`$action: 'hidden'`): что будет со скрытыми правами строками. */
+    $hidden?: 'delete' | 'unset' | 'restrict';
+    /** Строка-сводка предпросмотра удаления (`$action: 'hidden'`): число скрытых правами строк. */
+    $count?: number;
     /**
      * Почему цель `restore({ expect, partial: true })` не восстановлена: `restored` — её уже восстановили, `reissued` — id
      * занял новый объект с тем же ключом, `changed` — после показанного удаления её меняли (удалили снова и т. п.).
@@ -139,7 +144,7 @@ export interface QueryEvent {
 }
 /** Порог логирования: события этого уровня и выше; `'off'` — ничего. */
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'off';
-/** Событие логирования (каталог событий — lib/src/messages/log.ts). Поля без значения в событии отсутствуют. */
+/** Событие логирования (каталог событий — `LOG_EVENTS`). Поля без значения в событии отсутствуют. */
 export interface LogEvent {
     /** Время события, ISO 8601 (UTC). */
     ts: string;
@@ -150,9 +155,9 @@ export interface LogEvent {
     op?: string;
     /** Длительность операции, мс (с точностью до 0,1). */
     ms?: number;
-    /** Арендатор сессии фасада. */
+    /** Арендатор сессии подключения (db, db.as(), db.begin()). */
     tenant?: string;
-    /** Аккаунт фасада: аккаунт сессии или тот, от чьего имени действует db.as(). */
+    /** Аккаунт подключения: аккаунт сессии или тот, от чьего имени действует db.as(). */
     account?: string;
     /** Метка транзакции db.begin() или db.transaction(). */
     tx?: string;

package/dist/types.js

@@ -3,7 +3,7 @@
  */
 /**
  * Ревизия схемы, которую знает эта версия пакета, — номер версии SQL-части letopis (таблиц и функций в схеме установки).
- * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии 2.x `up()` обновляет только с
+ * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии (того же поколения `v2`) `up()` обновляет только с
  * `upgrade: true`, а `connect()` о ней предупреждает.
  */
 export const DDL_REVISION = 11;
@@ -21,7 +21,7 @@ export const ACL_CLASS_NAMES = ['rule', 'Resource', 'member', 'Account', 'Class'
 // Методы цепочки — единственный источник зарезервированных имён (план, §2.14, этап 3, п. 10)
 // ---------------------------------------------------------------------------
 /**
- * Имена методов цепочки: модификаторы, терминалы, глаголы записи и слоты концов, а также `then`. После шага цепочки эти
+ * Имена методов цепочки: модификаторы, терминалы, глаголы записи и шаги роли, а также `then`. После шага цепочки эти
  * имена библиотека не ищет среди классов; все они входят в `RESERVED_CLASS_NAMES`.
  */
 export const CHAIN_METHODS = [

package/dist/up.d.ts

@@ -121,9 +121,11 @@ export interface UpOptions extends Omit<InstallOptions, 'schema' | 'upTo' | 'mig
      */
     login?: LoginOptions;
 }
-/** Роль приложения up({ login }). */
+/** Роль приложения up({ login }): `{ user, password }` (поле — `user`, не `name`). */
 export interface LoginOptions {
+    /** Имя роли PostgreSQL для приложения, например `'shop_app'`: нет — up() её создаёт, есть — меняет пароль. */
     user: string;
+    /** Пароль роли: войдёт в строку подключения `r.login.dsn`. */
     password: string;
 }
 export interface UpResult extends InstallResult {
@@ -200,7 +202,8 @@ export interface TenantOptions {
          * APIKEY, KEYSECRET, OTP, TOTP, KEY, LOCK); иначе invalid_data.
          */
         kind?: string;
-        ttl?: string;
+        /** Срок сессии: как ttl у auth (число секунд, '15m', интервал PostgreSQL '15 minutes'); по умолчанию 7 суток. */
+        ttl?: string | number;
         /** Роли членства (по умолчанию ['owner']); роли уже существующего членства повтор не меняет. */
         roles?: string[];
     };

package/dist/up.js

@@ -19,7 +19,7 @@ import postgres from 'postgres';
 import { DDL_REVISION, RESERVED_CLASS_NAMES, SCHEMA_VERSION } from './types.js';
 import { makeLog, maskDsn, traceSql, traced } from './log.js';
 import { startPglite } from './pglite.js';
-import { hashPassword } from './auth.js';
+import { hashPassword, ttlGuard, ttlOf } from './auth.js';
 import { checkOptions, lerr, lmsg } from './errors.js';
 import { sqlCatalog } from './messages/index.js';
 import { v5Id } from './uuid.js';
@@ -572,8 +572,15 @@ async function ensureLogin(sql, login, owner, app, dsn) {
         const verb = r ? 'alter role %I login password %L' : 'create role %I login password %L';
         const [{ q }] = await tx `select format(${verb}::text, ${login.user}::text, ${login.password}::text) as q`;
         await tx.unsafe(q);
-        const [{ g }] = await tx `select format('grant %I to %I', ${app}::text, ${login.user}::text) as g`;
-        await tx.unsafe(g);
+        const [{ g, installer }] = await tx `select format('grant %I to %I', ${app}::text, ${login.user}::text) as g, current_user::text as installer`;
+        // PostgreSQL 16+: выдать роль может только тот, у кого на неё ADMIN OPTION (или суперпользователь) — понятный отказ
+        // вместо сырого 42501 «permission denied to grant role» (3.0.1)
+        await tx.unsafe(g).catch((e) => {
+            if (e?.code === '42501') {
+                throw lerr('boot.login_grant_denied', { installer, app, user: login.user }, { cause: e });
+            }
+            throw e;
+        });
         return !r;
     });
     let url;
@@ -642,8 +649,9 @@ export async function createTenant(sql, schema, opts, owner = 'letopis_owner') {
     // логин без крайних пробелов, как у auth.setPassword() и verifyPassword() (план 2.1, A12)
     const login = u ? (typeof u.login === 'string' ? u.login.trim() : u.login) : '';
     const user = u ? v5Id(SYSTEM_ID, 'Account', [`user:${login}`]) : null;
+    const ttl = u ? ttlOf(u.ttl, 'createTenant') : null;
     const hash = u ? await hashPassword(u.password) : null;
-    return sql.begin(async (tx) => {
+    return ttlGuard(sql.begin(async (tx) => {
         // под блокировкой схемы, как накат: up({ tenant }) нескольких экземпляров сервиса разом заводит арендатора один
         // раз, остальные находят его по имени (без неё оба вставили бы ту же строку и один упал бы на ключе)
         await lockSchema(tx, schema);
@@ -676,8 +684,8 @@ export async function createTenant(sql, schema, opts, owner = 'letopis_owner') {
             await tx.unsafe(`insert into ${S}.secret (account, kind, ident, material, meta)
         select $1::uuid, $2, $3, convert_to($4, 'UTF8'), '{"confirmed": true}'::jsonb
         where not exists (select 1 from ${S}.secret where kind = $2 and casefold(ident) collate pg_unicode_fast = casefold($3) collate pg_unicode_fast and deleted_at is null)`, [user, kind, login, hash]);
-            token = (await tx.unsafe(`select ${S}.new_session($1::uuid, $2::interval, $3::jsonb) as t`, [user, u.ttl ?? '7 days', { tenant }]))[0].t;
+            token = (await tx.unsafe(`select ${S}.new_session($1::uuid, $2::interval, $3::jsonb) as t`, [user, ttl ?? '7 days', { tenant }]))[0].t;
         }
         return { tenant, user, token, created };
-    });
+    }), u?.ttl, 'createTenant');
 }

package/dist/write.d.ts

@@ -19,19 +19,23 @@ export declare function inc(by: number, opts?: {
 }): IncMarker;
 export declare const isInc: (v: unknown) => v is IncMarker;
 /**
- * Ожидаемая строка `expect` у `restore()` и `delete({ confirm: true })` (план 2.1, A1, A2): строка ответа или её `id`,
- * `rev` (и `$action` превью удаления). Лишние поля строки не мешают.
+ * Ожидаемая строка `expect` у `restore()` и `delete({ confirm: true })`: строка ответа или её `id`, `rev` (и `$action`
+ * предпросмотра удаления). Лишние поля строки не мешают.
  */
 export interface Expected {
     id: string;
     rev: number;
-    /** У строки превью — что с ней будет; строку ответа (с любым $action) можно передать как есть. */
+    /** У строки предпросмотра — что с ней будет; строку ответа (с любым $action) можно передать как есть. */
     $action?: Row['$action'];
+    /** Строка-сводка предпросмотра (`$action: 'hidden'`, 3.0.1): что будет со скрытыми правами строками. */
+    $hidden?: Row['$hidden'];
+    /** Строка-сводка предпросмотра: число скрытых правами строк. */
+    $count?: number;
 }
 /**
- * Опции delete() (3.0): без confirm — превью; `{ confirm: true, expect }` — удалить ровно показанное превью;
+ * Опции delete(): без confirm — предпросмотр; `{ confirm: true, expect }` — удалить ровно показанный предпросмотр;
  * `{ confirm: true, all: true }` — осознанно удалить текущий состав целей без сверки (и без фильтра). `{ confirm: true }`
- * без expect и all — invalid_query (write.confirm_without_expect).
+ * без expect и all — invalid_query.
  */
 export type DeleteOptions = {
     confirm?: false;
@@ -50,9 +54,9 @@ export type DeleteOptions = {
     reason?: string;
 };
 /**
- * Опции restore() (3.0): `{ expect }` — надгробия, которые видел пользователь (ответ delete() или withDeleted()), с
+ * Опции restore(): `{ expect }` — надгробия, которые видел пользователь (ответ delete() или withDeleted()), с
  * `partial: true` — что можно; `{ all: true }` — осознанно вернуть все удалённые цели шага без сверки. Без expect и all —
- * invalid_query (write.restore_without_expect), и для явных id.
+ * invalid_query, и для явных id.
  */
 export type RestoreOptions = {
     expect: readonly Expected[];
@@ -98,7 +102,7 @@ export type PlanOp = ({
 export declare function dropUndefined(data: Record<string, unknown>): Record<string, unknown>;
 /** Причина изменения: строка до 1000 символов без NUL (её не принимает set_config). */
 export declare function checkReason(v: unknown, where: string): string;
-/** Значение слота: id, список id, строка ответа или ленивая цепочка (в той же транзакции). */
+/** Значение шага роли: id, список id, строка ответа или ленивая цепочка (в той же транзакции). */
 export type SlotValue = string | string[] | {
     id: string;
 } | null | {
@@ -111,7 +115,7 @@ export interface Slot {
     op: 'set' | 'unset' | 'add' | 'remove';
     value: SlotValue;
 }
-/** Строка ответа записи (результат upsert — $upsert, превью удаления — $action — поля Row). */
+/** Строка ответа записи (результат upsert — $upsert, предпросмотр удаления — $action — поля Row). */
 export type WriteRow = Row;
 export interface IncSpec {
     path: string[];