letopis 1.4.0 → 1.4.2

package/dist/chain.d.ts

@@ -32,6 +32,11 @@ export interface ChainCtx {
 /** План в очереди батча; steps обновляется по мере роста цепочки. */
 export interface BatchEntry {
     steps: Step[];
+    /** Модификатор выборки, поставленный сразу после последнего глагола плана: run() откажет (`afterVerbError`). */
+    loose?: {
+        name: string;
+        verb: string;
+    };
 }
 /** Ссылка цепочки на очередь: первый глагол регистрирует план, следующие — обновляют. */
 export interface BatchRef {
@@ -47,9 +52,16 @@ export type Batch = {
     [className: string]: StepFn;
 };
 export interface ChainCore {
-    /** Пути: [{ шаг1: Row, шаг2: Row, … }] — узлы каждого варианта. */
+    /**
+     * Все пути цепочки. Путь — строки всех шагов, по одной на шаг, связанные ссылками; приходит объектом, где ключ — имя
+     * шага (или имя из `alias()`), а значение — строка этого шага: `{ Shop: …, Product: … }`. Если к объекту последнего
+     * шага ведут несколько путей, придут все.
+     */
     paths(): Promise<Path[]>;
-    /** Уникальные сущности последнего шага. */
+    /**
+     * Строки объектов последнего шага — каждый объект один раз, сколько бы путей к нему ни вело. Если цепочка кончается
+     * глаголом записи — строки этого глагола.
+     */
     rows(): Promise<Row[]>;
     first(): Promise<Row | null>;
     ids(): Promise<string[]>;
@@ -68,41 +80,93 @@ export interface ChainCore {
     diff(opts?: DiffOptions): Promise<DiffResult[]>;
     /** Кто, когда и почему последним изменил каждое поле версии (по умолчанию текущей), план 1.1. */
     blame(opts?: BlameOptions): Promise<BlameResult[]>;
-    /** Агрегаты по полю последнего шага ('data.<путь>') — по сущностям, считает база. */
+    /**
+     * Сумма поля `'data.<путь>'` по объектам последнего шага: значения приводятся к числу, складывает база. `limit()` и
+     * `offset()` на итог не влияют; нет ни одного значения — `null`.
+     */
     sum(field: string): Promise<number | null>;
+    /**
+     * Среднее значение поля `'data.<путь>'` по объектам последнего шага: значения приводятся к числу, считает база.
+     * `limit()` и `offset()` на итог не влияют; нет ни одного значения — `null`.
+     */
     avg(field: string): Promise<number | null>;
+    /**
+     * Наименьшее значение поля `'data.<путь>'` среди объектов последнего шага; считает база. Числа сравниваются как числа
+     * и приходят числом, даты — как даты, поле без описания в классе — как текст. `limit()` и `offset()` на итог не
+     * влияют; нет ни одного значения — `null`.
+     */
     min(field: string): Promise<unknown>;
+    /**
+     * Наибольшее значение поля `'data.<путь>'` среди объектов последнего шага; считает база. Числа сравниваются как числа
+     * и приходят числом, даты — как даты, поле без описания в классе — как текст. `limit()` и `offset()` на итог не
+     * влияют; нет ни одного значения — `null`.
+     */
     max(field: string): Promise<unknown>;
+    /**
+     * Сколько объектов последнего шага с каждым значением поля `'data.<путь>'`: объект «значение → число», объекты без
+     * значения — под ключом `'null'`. Перед `countBy()` `limit()` и `offset()` отбирают группы — от самых частых значений.
+     */
     countBy(field: string): Promise<Record<string, number>>;
+    /**
+     * Не больше n строк ответа: объектов последнего шага, у `paths()` — путей, у `versions()` — версий, перед `countBy()` —
+     * групп. До глагола сужает его цели. Сразу после глагола перед `rows`, `first`, `ids`, `count` и `paths` —
+     * `invalid_query`: глагол уже прошёл по всем целям, сужать нечего.
+     */
     limit(n: number): Chain;
+    /** Пропустить первые n строк ответа — тех же, что считает `limit()`; где действует — как у `limit()`. */
     offset(n: number): Chain;
     /** Сортировка по полю последнего шага: 'at' | 'rev' | 'id' | 'data.<путь>'. */
     sort(field: string, dir?: 'asc' | 'desc' | boolean): Chain;
     /** Срез «как было на момент T»: версии журнала. */
     asOf(t: string | Date): Chain;
-    /** Keyset-пагинация: строго после курсора (cursorOf). Требует sort(). */
+    /**
+     * Постраничный вывод по курсору: ответ начинается строго после строки, на которой кончилась прошлая страница, в
+     * порядке `sort()` (без `sort()` — ошибка `invalid_query`). Курсор этой строки даёт `cursorOf(строка, поле)` с тем же
+     * полем, что в `sort()`. Листает `rows()`, `ids()`, `versions()` и `paths()` (курсор пути — `cursorOf(путь, поле)`);
+     * `count()`, агрегаты, `diff()` и `blame()` курсор не учитывают.
+     */
     after(cursor: Cursor): Chain;
-    /** Последний шаг включает удалённые (надгробия, $deleted). */
+    /**
+     * Последний шаг находит и удалённые объекты. Удалённый объект приходит надгробием — своей последней версией, версией
+     * удаления, — с `$deleted: true`.
+     */
     withDeleted(): Chain;
     /** Дети любой глубины на переходе к тому же классу; $depth в строке. */
     deep(max?: number): Chain;
-    /** Только сам класс шага, без потомков. */
+    /**
+     * Последний шаг находит объекты только своего класса — без классов-наследников (`extends` в модели), которых без
+     * `exact()` находит тоже.
+     */
     exact(): Chain;
     /** Ключ текущего шага в путях. */
     alias(name: string): Chain;
-    /** Колонка tags: строка | список (все) | has / hasAny / hasAll. */
+    /**
+     * Теги строки. В чтении и перед глаголами — отбор: строка или список — строки со всеми этими тегами (пустой список
+     * подходит любой строке), `has`, `hasAny`, `hasAll` — оператором. Перед `create()` и `upsert()` — теги новой строки
+     * (строка или список). Перед `update()` строка или список и отбирают, и заменяют теги целиком, а оператор только
+     * отбирает.
+     */
     tags(v: string | string[] | object): Chain;
-    /** Колонка owner. */
+    /**
+     * Владелец строк последнего шага (поле `owner`). В чтении и перед `update()`, `delete()` и другими глаголами — отбор:
+     * только строки этого владельца; перед `create()` и `upsert()` — владелец новой строки (существующей строке `upsert()`
+     * владельца не меняет).
+     */
     owner(v: string | {
         id: string;
     }): Chain;
-    /** Вставить узел: ленивая цепочка-паттерн или строка ответа; та же переменная повторно — возврат к её узлу. */
+    /**
+     * Добавляет в цепочку шаги из строки ответа (шаг её класса с её id) или из ещё не исполненной цепочки без глаголов
+     * записи (все её шаги как есть); `limit()`, `sort()`, `asOf()` и другие модификаторы всей цепочки не переносятся. Та
+     * же цепочка (та же переменная) второй раз в одном пути шагов не добавляет, а возвращает к своему последнему шагу:
+     * следующий шаг пойдёт от него.
+     */
     entity(x: Chain | Row): Chain;
     /** Создать объект: концы — из пути и слотов; занятый ключ — ошибка exists с id. */
     create(data?: Record<string, unknown>, opts?: {
         reason?: string;
     }): Chain;
-    /** Новая версия каждой цели шага: слияние патча в базе; inc(n) — приращение; { rev } — строгий режим. */
+    /** Новая версия каждой цели шага: слияние патча в базе; inc(n) — приращение; { rev } — с проверкой версии. */
     update(patch?: Record<string, unknown>, opts?: {
         rev?: number;
         reason?: string;
@@ -111,7 +175,11 @@ export interface ChainCore {
     upsert(data: Record<string, unknown>, opts?: {
         reason?: string;
     }): Chain;
-    /** Удалить цели шага с каскадом; без { confirm: true } — превью замыкания ($action). */
+    /**
+     * Удаляет цели шага; строки, которые на них ссылаются, база удаляет вместе с ними, отвязывает или не даёт удалить цель —
+     * как задано в `onDelete` их ссылок. Без `{ confirm: true }` — предпросмотр удаления: ничего не удаляется, терминал
+     * вернёт все строки, которых оно коснулось бы, у каждой `$action` — что с ней будет.
+     */
     delete(opts?: {
         confirm?: boolean;
         reason?: string;
@@ -130,12 +198,19 @@ export interface ChainCore {
     restore(opts?: {
         reason?: string;
     }): Chain;
-    /** Стереть историю удалённых объектов шага; без { confirm: true } — превью ($versions). */
+    /**
+     * Стирает историю удалённых объектов шага: все их версии в журнале, от каждого остаётся одна запись `purge`. Удалённые
+     * объекты шаг находит сам, без `withDeleted()`. Без `{ confirm: true }` — предпросмотр: ничего не стирается, терминал
+     * вернёт надгробия с `$versions` — сколько версий сотрётся.
+     */
     purge(opts?: {
         confirm?: boolean;
         reason?: string;
     }): Chain;
-    /** Новое значение ключа: строка с новым id, ссылки переведены (поля — данные, роли — концы). */
+    /**
+     * Новое значение ключа объектов шага. id вычисляется из ключа, поэтому объект получает новый id: ссылки других строк
+     * на него переводятся на новый id, а журнал связывает старый id с новым.
+     */
     rekey(patch: Record<string, unknown>, opts?: {
         reason?: string;
     }): Chain;
@@ -145,8 +220,10 @@ export interface ChainCore {
     }): Chain;
 }
 /**
- * Шаг цепочки: вызов — переход (фильтр); после глагола записи без вызова — слот конца версии:
- * `.Роль.set(id | [id] | строка | цепочка)`, `.unset()`, у множественного конца `.add()` и `.remove()`.
+ * Шаг цепочки — имя класса, его алиаса или роли с необязательным фильтром: `db.Shop(id).Product({ price: gt(1000) })`;
+ * каждый следующий шаг переходит по ссылкам от объектов предыдущего. После `create()`, `update()` или `upsert()` имя
+ * роли без вызова задаёт ссылку записываемой строки: `.Роль.set(…)`, `.Роль.unset()`, у множественной ссылки ещё
+ * `.Роль.add(…)` и `.Роль.remove(…)`.
  */
 export type StepFn = ((filter?: Filter) => Chain) & {
     set(value: unknown): Chain;

package/dist/chain.js

@@ -132,6 +132,27 @@ async function read(ctx, steps, mods, mode, agg) {
     const ev = mode === 'countPaths' ? 'count' : mode;
     return exec(ctx, q, ev, steps, mods).then((res) => ({ q, res }));
 }
+/** Модификатор выборки, заданный в mods, — именем метода цепочки; forUpdate() отказывает сам (lock_unsupported). */
+function modName(mods) {
+    const key = Object.keys(mods).find((k) => mods[k] !== undefined && k !== 'forUpdate');
+    return key === 'order' || key === 'desc' ? 'sort' : key;
+}
+function afterVerbError(name, verb) {
+    return new LetopisError('invalid_query', `${name}() после ${verb}() ни на что не действует: глагол проходит по всем целям шага, а ответ — его строки. ` +
+        `Цели сужают limit(), offset() и sort() до глагола: db.Класс(…).limit(n).${verb}(…)`);
+}
+/**
+ * Терминалы rows, first, ids, count и paths цепочки, которая кончается глаголом, отдают строки самой правки.
+ * Модификатор выборки между глаголом и терминалом ни на что не подействовал бы: limit резал бы только ответ, хотя
+ * правка прошла по всем целям, остальные молча пропускались. Поэтому — отказ до записи. После глагола модификатор
+ * относится к чтению за ним (шаг класса, versions(), diff(), blame(), агрегаты) или сужает цели следующего глагола.
+ */
+function checkAfterVerb(steps, mods) {
+    const op = steps[steps.length - 1]?.op;
+    const name = op ? modName(mods) : undefined;
+    if (op && name)
+        throw afterVerbError(name, op.kind);
+}
 /**
  * Цепочка с глаголами: весь план одной транзакцией (§2.5). Результат приводится к виду ответа
  * чтения (строки rows/paths, id, n, агрегаты), чтобы терминалы разбирали его одинаково.
@@ -223,8 +244,11 @@ const rowOf = (r) => (r.done ? r.row : toRow(r.row));
 /** Значение слота: id, список id, строка ответа или ленивая цепочка. */
 function slotValue(v) {
     const peek = peekPlan(v);
-    if (peek)
+    if (peek) {
+        // модификатор сразу после глагола вложенной цепочки — тот же отказ, что у терминала (план 2.0, 7.2 №3)
+        checkAfterVerb(peek.steps, peek.mods);
         return { plan: peek.steps, mods: peek.mods };
+    }
     if (v === null || typeof v === 'string')
         return v;
     if (Array.isArray(v))
@@ -279,6 +303,13 @@ function classProp(ctx, name, found, ownerSteps, mods, nodes) {
     });
 }
 export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
+    // батч: терминала нет, план исполнит run() — он и откажет, если цепочка кончилась модификатором после глагола
+    // (как checkAfterVerb вне батча); следующий шаг или глагол забирает модификатор себе, и отметка снимается
+    if (ctx.batch?.entry) {
+        const op = steps[steps.length - 1]?.op;
+        const name = op ? modName(mods) : undefined;
+        ctx.batch.entry.loose = op && name ? { name, verb: op.kind } : undefined;
+    }
     const withLast = (patch) => {
         const lastOp = steps[steps.length - 1]?.op;
         if (lastOp)
@@ -369,21 +400,35 @@ export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
                     return entityStep;
                 case 'paths':
                     return async () => {
-                        // q === null — пути из результата глагола: строки уже готовы
+                        checkAfterVerb(steps, mods);
+                        // q === null — пути из результата глагола: строки уже готовы. Ключи — в порядке шагов (jsonb хранит их
+                        // по длине), узел последнего шага — последним: по нему cursorOf(путь, поле) берёт курсор (план 2.0, 7.1 №3)
                         const { q, res } = await read(ctx, steps, mods, 'paths');
-                        return res.map((r) => Object.fromEntries(Object.entries(r.path).map(([k, v]) => [k, q === null ? v : toRow(v)])));
+                        if (q === null)
+                            return res.map((r) => r.path);
+                        return res.map((r) => Object.fromEntries(q.keys.map((k) => [k, toRow(r.path[k])])));
                     };
                 case 'rows':
-                    return async () => (await read(ctx, steps, mods, 'rows')).res.map(rowOf);
+                    return async () => {
+                        checkAfterVerb(steps, mods);
+                        return (await read(ctx, steps, mods, 'rows')).res.map(rowOf);
+                    };
                 case 'first':
                     return async () => {
+                        checkAfterVerb(steps, mods);
                         const { res } = await read(ctx, steps, { ...mods, limit: 1 }, 'rows');
                         return res[0] ? rowOf(res[0]) : null;
                     };
                 case 'ids':
-                    return async () => (await read(ctx, steps, mods, 'ids')).res.map((r) => r.id);
+                    return async () => {
+                        checkAfterVerb(steps, mods);
+                        return (await read(ctx, steps, mods, 'ids')).res.map((r) => r.id);
+                    };
                 case 'count':
-                    return async (opts) => (await read(ctx, steps, mods, opts?.paths ? 'countPaths' : 'count')).res[0].n;
+                    return async (opts) => {
+                        checkAfterVerb(steps, mods);
+                        return (await read(ctx, steps, mods, opts?.paths ? 'countPaths' : 'count')).res[0].n;
+                    };
                 case 'versions':
                     return async (opts) => {
                         warnNoHistory(steps, 'versions');
@@ -503,7 +548,11 @@ export function makeBatch(ctx, queue) {
             switch (prop) {
                 case 'run':
                     return async () => {
-                        const plans = queue.splice(0, queue.length).map((x) => x.steps);
+                        const entries = queue.splice(0, queue.length);
+                        const loose = entries.find((x) => x.loose)?.loose;
+                        if (loose)
+                            throw afterVerbError(loose.name, loose.verb);
+                        const plans = entries.map((x) => x.steps);
                         for (const p of plans)
                             precheckPlan(ctx.reg, p);
                         if (!plans.length)

package/dist/cli.js

@@ -24,6 +24,7 @@ import { resolve } from 'node:path';
 import { connect, describeText } from './index.js';
 import { syncModels, generateTypes } from './sync.js';
 import { import021 } from './import.js';
+import { LetopisError } from './errors.js';
 const USAGE = `letopis sync <модуль> --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--apply]
 letopis types --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--out <файл>]
 letopis load <файлы…> --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--class <Класс>]
@@ -35,6 +36,8 @@ letopis import --from <строка 0.21> --from-schema <v1.имя> --dsn <ст
   [--rename <Старое>=<Новое>]… [--update] [--commit-every <N>] [--partition <имя>] [--initial]
 letopis mcp --dsn <строка> --schema <v2.имя> --token <токен пользователя> [--write]
   (или LETOPIS_DSN, LETOPIS_SCHEMA, LETOPIS_TOKEN; ключ сервиса --api-key не принимается)`;
+/** Команды CLI: остальное — USAGE с кодом 2 ещё до подключения. */
+const COMMANDS = new Set(['sync', 'types', 'load', 'verify', 'maintain', 'describe', 'import', 'mcp']);
 const isModel = (v) => typeof v === 'object' && v !== null && typeof v.describe === 'function' && typeof v.name === 'string';
 export async function main(argv) {
     const { values, positionals } = parseArgs({
@@ -58,7 +61,12 @@ export async function main(argv) {
         values.schema ??= process.env.LETOPIS_SCHEMA || undefined;
         values.token ??= process.env.LETOPIS_TOKEN || undefined;
     }
-    if (values.help || !cmd || !values.dsn || !values.schema) {
+    // --help — всегда код 0; неизвестная команда — USAGE до подключения к базе (план 2.0, 7.5 №4)
+    if (values.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    if (!cmd || !COMMANDS.has(cmd) || !values.dsn || !values.schema) {
         console.log(USAGE);
         return cmd ? 2 : 0;
     }
@@ -117,7 +125,7 @@ export async function main(argv) {
                 return 2;
             }
             if (values.trust)
-                throw new Error('letopis: removed: --trust снят в 1.0.0 — запрос по целям вне загрузки стоит 0,1–1,3 % её времени');
+                throw new LetopisError('removed', '--trust снят в 1.0.0 — запрос по целям вне загрузки стоит 0,1–1,3 % её времени');
             // несколько файлов — одна загрузка и одна транзакция; в файле — объект на строку
             const rows = [];
             for (const f of files) {
@@ -146,6 +154,12 @@ export async function main(argv) {
             console.log(JSON.stringify(r));
             return 0;
         }
+        if (cmd === 'describe' || cmd === 'types') {
+            // обе команды читают реестр сессии: без действующей сессии (токен истёк, погашен, неверен или не задан) он пуст,
+            // и команда выдала бы пустой результат с кодом 0, а с --out затёрла бы им файл. acl.check ничего не пишет, а без
+            // сессии отказывает no_session — тогда выход с кодом 1, файл не тронут
+            await db.acl.check('letopis.cli');
+        }
         if (cmd === 'describe') {
             const d = db.describe();
             const text = values.format === 'text' ? describeText(d) : JSON.stringify(d, null, 2);

package/dist/errors.d.ts

@@ -13,10 +13,10 @@ export declare class LetopisError extends Error {
     readonly detail: unknown;
     constructor(code: string, message: string, detail?: unknown);
 }
+/** Версия, в которой снято старое API (её берёт и контракт API — scripts/gen-api-contract.mjs). */
+export declare const REMOVED_IN = "1.0.0";
 /** Охранник снесённого API (план, этап 3, п. 11): понятная ошибка с версией и заменой. */
 export declare function removed(name: string, replacement: string): LetopisError;
-/** Метод зарезервирован, но появится на следующем этапе плана. */
-export declare function notYet(name: string, stage: number): LetopisError;
 /** Данные не проходят описание класса (`invalid_data`). */
 export declare class ValidationError extends LetopisError {
     readonly issues: Issue[];

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('опция ') ? 'снята' : / и /.test(name) ? 'сняты' : 'снят';
+    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) {