letopis 1.0.1 → 1.2.0

package/dist/chain.js

@@ -102,7 +102,7 @@ async function exec(ctx, q, mode, steps, mods = {}) {
         if (hit)
             return hit;
         const tag = sessionTag(who.token);
-        const tok = store.token(classes, tag);
+        const tok = store.token(classes, tag, who.tenant);
         const t0 = performance.now();
         const S = `"${ctx.schema.replace(/"/g, '""')}"`;
         const [res, exp] = await ctx.exec.run((tx) => Promise.all([
@@ -139,7 +139,7 @@ async function read(ctx, steps, mods, mode, agg) {
 async function plan(ctx, steps, mods, mode, agg) {
     precheckPlan(ctx.reg, steps);
     const t0 = performance.now();
-    const r = await ctx.exec.run((q) => execPlan({ reg: ctx.reg, schema: ctx.schema, q, tenant: ctx.tenant(), owner: ctx.owner }, steps, mods, mode, agg));
+    const r = await ctx.exec.run((q) => execPlan({ reg: ctx.reg, schema: ctx.schema, q, tenant: ctx.tenant(), owner: ctx.owner, ...reasons(ctx) }, steps, mods, mode, agg));
     if (r.kind === 'read') {
         report(ctx, mode === 'countPaths' ? 'count' : mode, steps, t0, r.res.length);
         if (r.q === null) {
@@ -196,6 +196,28 @@ async function lockedRead(ctx, steps, mods, mode) {
     report(ctx, mode, steps, t0, res.length);
     return { q: rowsQ, res: mode === 'ids' ? res.map((r) => ({ id: r.row.id })) : res };
 }
+/** Причины для плана: по умолчанию у глаголов (у батча — своя) и та, что стоит в транзакции. */
+const reasons = (ctx) => ({ reason: ctx.reason ?? ctx.txReason ?? '', txReason: ctx.txReason ?? '' });
+/** Опция reason глагола (план 1.1, §2.1): проверяет precheckPlan. */
+const reasonOf = (o) => (o?.reason !== undefined ? { reason: o.reason } : {});
+/** diff({ from, to }): номер версии (целое ≥ 1) или момент (ISO-строка, Date). */
+function versionRef(v, what, moments = true) {
+    if (typeof v === 'number' && Number.isInteger(v) && v >= 1 && v <= 2147483647)
+        return v;
+    if (moments && v instanceof Date && !Number.isNaN(+v))
+        return v.toISOString();
+    if (moments && typeof v === 'string' && !Number.isNaN(Date.parse(v)))
+        return v;
+    throw new LetopisError('invalid_query', `${what}: номер версии (целое ≥ 1)${moments ? ' или момент (ISO-строка, Date)' : ''}`);
+}
+/** blame({ at }): момент (ISO-строка, Date). */
+function momentOf(v, what) {
+    if (v instanceof Date && !Number.isNaN(+v))
+        return v.toISOString();
+    if (typeof v === 'string' && !Number.isNaN(Date.parse(v)))
+        return v;
+    throw new LetopisError('invalid_query', `${what}: момент — ISO-строка или Date`);
+}
 /** Строка ответа: из чтения — to_jsonb узла, из плана — готовая строка записи. */
 const rowOf = (r) => (r.done ? r.row : toRow(r.row));
 /** Значение слота: id, список id, строка ответа или ленивая цепочка. */
@@ -283,6 +305,10 @@ export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
         const last = steps[steps.length - 1];
         if (!last)
             throw new LetopisError('invalid_query', `${op.kind}() — нужен шаг класса: db.Класс(…).${op.kind}(…)`);
+        // батч: причина db.batch(имя, { reason }) — при постановке в очередь, а не при run(): очередь общая по имени, и
+        // run() может позвать фасад без причины или с другой (ревью №1 точки А плана 1.1)
+        if (ctx.batch && op.reason === undefined && ctx.reason !== undefined)
+            op = { ...op, reason: ctx.reason };
         const next = last.op
             ? [...steps, { name: last.name, cls: last.cls, role: last.role, aliasKey: last.aliasKey, self: true, op, opMods: mods, nodeKey: nextNodeKey() }]
             : [...steps.slice(0, -1), { ...last, op, opMods: mods }];
@@ -364,6 +390,29 @@ export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
                         const m = opts?.follow ? { ...mods, follow: true } : mods;
                         return (await read(ctx, steps, m, 'versions')).res.map((r) => toRow(r.row));
                     };
+                case 'diff':
+                    return async (opts = {}) => {
+                        warnNoHistory(steps, 'diff');
+                        const hist = {
+                            ...(opts.from !== undefined ? { from: versionRef(opts.from, 'diff({ from })') } : {}),
+                            ...(opts.to !== undefined ? { to: versionRef(opts.to, 'diff({ to })') } : {}),
+                            ...(opts.follow ? { follow: true } : {}),
+                        };
+                        return (await read(ctx, steps, { ...mods, hist }, 'diff')).res.map((r) => r.row);
+                    };
+                case 'blame':
+                    return async (opts = {}) => {
+                        warnNoHistory(steps, 'blame');
+                        if (opts.limit !== undefined)
+                            versionRef(opts.limit, 'blame({ limit })', false);
+                        const hist = {
+                            ...(opts.at !== undefined ? { at: momentOf(opts.at, 'blame({ at })') } : {}),
+                            ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+                        };
+                        // null — объекта на момент at не было (или он не виден)
+                        return (await read(ctx, steps, { ...mods, hist }, 'blame')).res
+                            .map((r) => r.row).filter((x) => x !== null);
+                    };
                 case 'sum':
                 case 'avg':
                 case 'min':
@@ -404,17 +453,17 @@ export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
                     throw removed('account()', 'арендатор сессии и auth.switch() (этап 5)');
                 // глаголы записи — звенья плана (этап 4)
                 case 'create':
-                    return (data = {}) => withOp({ kind: 'create', data });
+                    return (data = {}, opts) => withOp({ kind: 'create', data, ...reasonOf(opts) });
                 case 'update':
-                    return (data = {}, opts) => withOp({ kind: 'update', data, ...(opts?.rev !== undefined ? { rev: opts.rev } : {}) });
+                    return (data = {}, opts) => withOp({ kind: 'update', data, ...(opts?.rev !== undefined ? { rev: opts.rev } : {}), ...reasonOf(opts) });
                 case 'upsert':
-                    return (data = {}) => withOp({ kind: 'upsert', data });
+                    return (data = {}, opts) => withOp({ kind: 'upsert', data, ...reasonOf(opts) });
                 case 'delete':
-                    return (opts) => withOp({ kind: 'delete', confirm: opts?.confirm === true });
+                    return (opts) => withOp({ kind: 'delete', confirm: opts?.confirm === true, ...reasonOf(opts) });
                 case 'anonymize':
-                    return (fields) => withOp({ kind: 'anonymize', fields });
+                    return (fields, opts) => withOp({ kind: 'anonymize', fields, ...reasonOf(opts) });
                 case 'reclass':
-                    return (cls, data) => withOp({ kind: 'reclass', cls, ...(data !== undefined ? { data } : {}) });
+                    return (cls, data, opts) => withOp({ kind: 'reclass', cls, ...(data !== undefined ? { data } : {}), ...reasonOf(opts) });
                 case 'set':
                 case 'unset':
                 case 'add':
@@ -423,11 +472,11 @@ export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
                 case 'forUpdate':
                     return () => withMods({ forUpdate: true });
                 case 'restore':
-                    return () => withOp({ kind: 'restore' });
+                    return (opts) => withOp({ kind: 'restore', ...reasonOf(opts) });
                 case 'purge':
-                    return (opts) => withOp({ kind: 'purge', confirm: opts?.confirm === true });
+                    return (opts) => withOp({ kind: 'purge', confirm: opts?.confirm === true, ...reasonOf(opts) });
                 case 'rekey':
-                    return (patch) => withOp({ kind: 'rekey', data: patch ?? {} });
+                    return (patch, opts) => withOp({ kind: 'rekey', data: patch ?? {}, ...reasonOf(opts) });
                 case 'cache':
                     return (opts) => {
                         if (opts?.ttl !== undefined && !(opts.ttl > 0))
@@ -459,7 +508,7 @@ export function makeBatch(ctx, queue) {
                             precheckPlan(ctx.reg, p);
                         if (!plans.length)
                             return [];
-                        return ctx.exec.run((q) => execBatch({ reg: ctx.reg, schema: ctx.schema, q, tenant: ctx.tenant(), owner: ctx.owner }, plans));
+                        return ctx.exec.run((q) => execBatch({ reg: ctx.reg, schema: ctx.schema, q, tenant: ctx.tenant(), owner: ctx.owner, ...reasons(ctx) }, plans));
                     };
                 case 'execute':
                     throw removed('batch.execute()', 'batch.run()');

package/dist/cli.js

@@ -6,12 +6,15 @@
  *   letopis sync <модуль моделей> --dsn … --schema v2.x (--token … | --api-key …) [--apply]
  *   letopis types --dsn … --schema v2.x (--token … | --api-key …) [--out types.d.ts]
  *   letopis load <файлы NDJSON…> --dsn … --schema v2.x (--token … | --api-key …) [--class C]
- *     [--duplicates error|first|last] [--existing error|skip|update] [--commit-every N] [--verify]
+ *     [--duplicates error|first|last] [--existing error|skip|update] [--commit-every N] [--verify] [--initial]
  *   letopis verify --dsn … --schema v2.x [--token … | --api-key …] [--data]   — код 1 при находках
  *   letopis maintain --dsn … --schema v2.x [--token … | --api-key …] [--batches N]
  *   letopis describe --dsn … --schema v2.x (--token … | --api-key …) [--format json|text] [--out файл]
  *   letopis import --from <строка 0.21> --from-schema v1.x --dsn … --schema v2.x [--tenant <имя>] [--keyless C]…
- *     [--rename Старое=Новое]… [--update] [--commit-every N] [--partition p]   — код 1, если verify нашёл расхождения
+ *     [--rename Старое=Новое]… [--update] [--commit-every N] [--partition p] [--initial]   — код 1, если verify нашёл расхождения
+ *   --initial — первая заливка (план 1.1, §2.3): пустая схема, одна транзакция, индексы и триггеры — после загрузки
+ *   letopis mcp --dsn … --schema v2.x --token … [--write]   — сервер MCP по stdio (план 1.1, §2.5); dsn, schema и
+ *     token — ещё из LETOPIS_DSN, LETOPIS_SCHEMA, LETOPIS_TOKEN; только токен пользователя: --api-key — отказ
  */
 import { parseArgs } from 'node:util';
 import { readFile, writeFile } from 'node:fs/promises';
@@ -24,12 +27,14 @@ import { import021 } from './import.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 <Класс>]
-  [--duplicates error|first|last] [--existing error|skip|update] [--commit-every <N>] [--verify]
+  [--duplicates error|first|last] [--existing error|skip|update] [--commit-every <N>] [--verify] [--initial]
 letopis verify --dsn <строка> --schema <v2.имя> [--token <токен> | --api-key <ключ>] [--data]
 letopis maintain --dsn <строка> --schema <v2.имя> [--token <токен> | --api-key <ключ>] [--batches <N>]
 letopis describe --dsn <строка> --schema <v2.имя> (--token <токен> | --api-key <ключ>) [--format json|text] [--out <файл>]
 letopis import --from <строка 0.21> --from-schema <v1.имя> --dsn <строка> --schema <v2.имя> [--tenant <имя>] [--keyless <Класс>]…
-  [--rename <Старое>=<Новое>]… [--update] [--commit-every <N>] [--partition <имя>]`;
+  [--rename <Старое>=<Новое>]… [--update] [--commit-every <N>] [--partition <имя>] [--initial]
+letopis mcp --dsn <строка> --schema <v2.имя> --token <токен пользователя> [--write]
+  (или LETOPIS_DSN, LETOPIS_SCHEMA, LETOPIS_TOKEN; ключ сервиса --api-key не принимается)`;
 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({
@@ -43,9 +48,16 @@ export async function main(argv) {
             format: { type: 'string' },
             from: { type: 'string' }, 'from-schema': { type: 'string' }, tenant: { type: 'string' }, partition: { type: 'string' },
             keyless: { type: 'string', multiple: true }, rename: { type: 'string', multiple: true }, update: { type: 'boolean' },
+            initial: { type: 'boolean' }, write: { type: 'boolean' },
         },
     });
     const [cmd, arg] = positionals;
+    // клиенты MCP передают строку подключения и токен окружением (план 1.1, §2.5) — только для этой команды
+    if (cmd === 'mcp') {
+        values.dsn ??= process.env.LETOPIS_DSN || undefined;
+        values.schema ??= process.env.LETOPIS_SCHEMA || undefined;
+        values.token ??= process.env.LETOPIS_TOKEN || undefined;
+    }
     if (values.help || !cmd || !values.dsn || !values.schema) {
         console.log(USAGE);
         return cmd ? 2 : 0;
@@ -68,15 +80,18 @@ export async function main(argv) {
         const r = await import021({
             from: values.from, fromSchema: values['from-schema'], dsn: values.dsn, schema: values.schema, tenant: values.tenant,
             partition: values.partition, keyless: values.keyless, rename, update: values.update,
-            commitEvery: values['commit-every'] ? Number(values['commit-every']) : undefined,
+            commitEvery: values['commit-every'] ? Number(values['commit-every']) : undefined, initial: values.initial,
         });
         console.log(JSON.stringify(r, null, 2));
         return r.verify.ok ? 0 : 1;
     }
+    if (cmd === 'mcp')
+        return mcp(values);
     // загрузчику нужно администраторское подключение (§2.6, п. 1)
     const db = await connect({ dsn: values.dsn, schema: values.schema, token: values.token, apiKey: values['api-key'], max: 2,
-        // verify и maintain работают и на администраторском подключении без сессии
-        ...(cmd === 'load' || cmd === 'verify' || cmd === 'maintain' ? { allowBypassRls: true } : {}) });
+        // verify и maintain работают и на администраторском подключении без сессии; производные классы (derivedBy)
+        // синхронизирует администраторское подключение с сессией арендатора
+        ...(cmd === 'load' || cmd === 'verify' || cmd === 'maintain' || cmd === 'sync' ? { allowBypassRls: true } : {}) });
     try {
         if (cmd === 'sync') {
             if (!arg) {
@@ -116,6 +131,7 @@ export async function main(argv) {
                 existing: values.existing,
                 commitEvery: values['commit-every'] ? Number(values['commit-every']) : undefined,
                 verify: values.verify,
+                initial: values.initial,
             });
             console.log(JSON.stringify(r));
             return 0;
@@ -154,6 +170,42 @@ export async function main(argv) {
         await db.close();
     }
 }
+/**
+ * letopis mcp (план 1.1, §2.5): сервер MCP по stdio от имени одного пользователя. Только токен сессии пользователя —
+ * ключ сервиса даёт все права auth.* (имперсонация, выпуск сессий) и лежал бы на машине агента. Модуль mcp.js и SDK
+ * грузятся только здесь: letopis --help и прочие команды работают без SDK. В stdout — только протокол (предупреждения
+ * connect() идут в stderr); процесс живёт, пока клиент не закроет stdin.
+ */
+async function mcp(v) {
+    if (v['api-key'] !== undefined) {
+        console.error('letopis: user_session_required: letopis mcp принимает только токен сессии пользователя (--token или LETOPIS_TOKEN): ключ сервиса даёт все права auth.* и не должен лежать на машине агента');
+        return 2;
+    }
+    if (!v.token) {
+        console.error('letopis: user_session_required: letopis mcp — нужен токен сессии пользователя: --token или LETOPIS_TOKEN');
+        return 2;
+    }
+    const { createMcpServer } = await import('./mcp.js');
+    const db = await connect({ dsn: v.dsn, schema: v.schema, token: v.token, max: 4 });
+    try {
+        const opts = { write: v.write === true };
+        // учётные данные — до начала протокола: отказ виден кодом выхода и текстом в stderr
+        await createMcpServer(db, opts);
+        const { serveStdio } = await import('@modelcontextprotocol/server/stdio');
+        const closed = new Promise((resolve) => {
+            process.stdin.once('end', resolve);
+            process.stdin.once('close', resolve);
+        });
+        // экземпляр сервера — на соединение (и на пробу server/discover): ревизию протокола выбирает клиент
+        const handle = serveStdio(() => createMcpServer(db, opts), { onerror: (e) => console.error(`letopis mcp: ${e.message}`) });
+        await closed;
+        await handle.close();
+        return 0;
+    }
+    finally {
+        await db.close();
+    }
+}
 // Запущен ли файл как программа. Сравниваются реальные пути: на Linux и macOS `node_modules/.bin/letopis`
 // (npx, скрипты package.json) — симлинк, `process.argv[1]` указывает на него, а `import.meta.url` — на сам файл.
 function isMain() {

package/dist/errors.js

@@ -35,7 +35,8 @@ const LT_NAMES = {
     LT006: 'acl_denied', LT007: 'id_mismatch', LT008: 'id_from_db', LT009: 'immutable_key', LT010: 'invalid_class',
     LT011: 'use_reclass', LT012: 'reclass_denied', LT013: 'tightening_conflict', LT014: 'isolation_level',
     LT015: 'recreated_in_statement', LT016: 'cursor_expired', LT017: 'delete_restricted', LT018: 'not_deleted',
-    LT019: 'reset_disabled', LT020: 'confirm_mismatch',
+    LT019: 'reset_disabled', LT020: 'confirm_mismatch', LT021: 'derived_class', LT022: 'aggregate_field',
+    LT023: 'projector_pending',
 };
 /**
  * Ошибка базы → LetopisError (ValidationError для invalid_data с нарушениями). Детали из DETAIL
@@ -64,7 +65,8 @@ export function fromDbError(e) {
     if (name === 'invalid_data' && Array.isArray(issues)) {
         const cls = /класса (\S+)/.exec(text)?.[1] ?? '?';
         const v = new ValidationError(cls, issues);
-        return Object.assign(v, { cause: e });
+        // текст базы целиком: в нём бывает больше, чем имя класса (у проектора — арендатор и id строки)
+        return Object.assign(v, { cause: e, ...(text ? { message: `letopis: invalid_data: ${text}` } : {}) });
     }
     return Object.assign(new LetopisError(name, text, detail), { cause: e });
 }

package/dist/import.d.ts

@@ -46,6 +46,12 @@ export interface ImportOptions {
     update?: boolean;
     /** Порции загрузчика (§2.6, п. 8). */
     commitEvery?: number;
+    /**
+     * Первая заливка (план 1.1, §2.3): весь импорт — одной транзакцией в пустую схему, индексы и триггеры —
+     * после загрузки; несовместимо с update и commitEvery. Строки, уже лежащие в схеме (системный сид:
+     * ресурсы, правила), пропускаются, как без флага.
+     */
+    initial?: boolean;
     /** Без сообщений в консоль. */
     quiet?: boolean;
 }