letopis 1.0.1 → 1.1.0

package/dist/cache.js

@@ -6,23 +6,34 @@
  * запрос разным пользователям отдаёт разные строки. Сброс:
  *   - свои записи — сразу после фиксации, по классам из letopis.changed (туда попадают и классы
  *     каскада, unset, смены класса и ключа); запись через db.sql — весь кэш;
- *   - чужие записи — по сигналу базы с именем класса; классы прав и схемы (rule, Resource, member,
- *     Account, Class) и «*» — весь кэш; `session:<16 hex>` — ответы погашенной сессии, `session:*` — все;
- *   - гонка запроса и сигнала: счётчики сигналов по классам и сессиям снимаются до запроса, ответ
- *     кладётся, только если они не изменились;
+ *   - чужие записи — по сигналу базы (нагрузка по режиму установки, signals.ts): класс в арендаторе
+ *     сигнала (ответ помнит токен арендатора запроса; сигнал System и процесс без ключа — во всех), в режиме
+ *     opaque без ключа — весь кэш; классы прав и схемы (rule, Resource, member, Account, Class) и «*» —
+ *     весь кэш; `session:<16 hex>` — ответы погашенной сессии, `session:*` — все;
+ *   - гонка запроса и сигнала: счётчики сигналов по классам, парам «класс, арендатор» и сессиям
+ *     снимаются до запроса, ответ кладётся, только если они не изменились;
  *   - (пере)подключение слушателя сигналов — весь кэш: сигналы за время обрыва потеряны; без слушателя
  *     кэш выключен (с ttlOnly — работает только по сроку);
  *   - срок (по умолчанию 60 с) — предохранитель; ответы истёкшей сессии не используются.
  * Внутри db.begin() и в db.sql кэш не работает.
  */
 import { createHash } from 'node:crypto';
+import { ACL_CLASS_NAMES } from './types.js';
+import { Signals } from './signals.js';
 /** Классы, строки которых меняют права и схему: их сигнал сбрасывает весь кэш. */
-export const ACL_CLASSES = new Set(['rule', 'Resource', 'member', 'Account', 'Class']);
+export const ACL_CLASSES = new Set(ACL_CLASS_NAMES);
+/** Счётчиков сигналов в каждой карте не больше: имена в нагрузке присылает любая роль базы. */
+const EPOCH_MAX = 100_000;
 /** Начало sha256 токена — так база называет сессию в сигнале session:<16 hex>. */
 export const sessionTag = (token) => token ? createHash('sha256').update(token, 'utf8').digest('hex').slice(0, 16) : '';
 export class ResultCache {
+    sig;
+    allTenants;
     map = new Map();
     classEpoch = new Map();
+    /** Сигналы класса в арендаторе: по паре и по классу в любом арендаторе (для ответов без арендатора). */
+    pairEpoch = new Map();
+    anyEpoch = new Map();
     sessionEpoch = new Map();
     epoch = 0;
     listening = false;
@@ -30,7 +41,13 @@ export class ResultCache {
     ttlMs;
     ttlOnly;
     max;
-    constructor(opts = {}) {
+    /**
+     * sig — режим сигналов и ключ подключения (разбор нагрузки, токены арендаторов); allTenants —
+     * подключение видит строки всех арендаторов (обходит RLS): ответ сбрасывается сигналом из любого.
+     */
+    constructor(opts = {}, sig = new Signals(), allTenants = false) {
+        this.sig = sig;
+        this.allTenants = allTenants;
         this.ttlMs = (opts.ttl ?? 60) * 1000;
         this.ttlOnly = opts.ttlOnly === true;
         this.max = opts.max ?? 10_000;
@@ -43,14 +60,19 @@ export class ResultCache {
     key(text, params, who) {
         return JSON.stringify([text, params, who.token ?? '', who.account ?? '', who.tenant ?? '']);
     }
-    /** Снимок счётчиков классов и сессии — до запроса. */
-    token(classes, session) {
+    /** Снимок счётчиков классов, пар с арендатором запроса (id) и сессии — до запроса. */
+    token(classes, session, tenantId) {
+        const tenant = this.allTenants ? null : this.sig.tenantToken(tenantId);
         return {
             epoch: this.epoch,
-            classes: classes.map((c) => [c, this.classEpoch.get(c) ?? 0]),
+            classes: classes.map((c) => [c, this.classEpoch.get(c) ?? 0, this.pairCount(c, tenant)]),
             session: this.sessionEpoch.get(session) ?? 0,
+            tenant,
         };
     }
+    pairCount(cls, tenant) {
+        return (tenant === null ? this.anyEpoch.get(cls) : this.pairEpoch.get(`${cls}@${tenant}`)) ?? 0;
+    }
     get(key) {
         if (!this.enabled)
             return undefined;
@@ -71,70 +93,97 @@ export class ResultCache {
             return false;
         const stale = tok.epoch !== this.epoch
             || tok.session !== (this.sessionEpoch.get(session) ?? 0)
-            || tok.classes.some(([c, n]) => (this.classEpoch.get(c) ?? 0) !== n);
+            || tok.classes.some(([c, n, m]) => (this.classEpoch.get(c) ?? 0) !== n || this.pairCount(c, tok.tenant) !== m);
         if (stale) {
             this.st.raced++;
             return false;
         }
         if (this.map.size >= this.max)
             this.map.delete(this.map.keys().next().value);
-        this.map.set(key, { value, classes: [...classes], session, expires: Date.now() + ttlMs, sessionExpires });
+        this.map.set(key, { value, classes: [...classes], session, tenant: tok.tenant, expires: Date.now() + ttlMs, sessionExpires });
         this.st.stores++;
         return true;
     }
-    /** Сбросить ответы, читавшие эти классы. */
+    /** Сбросить ответы, читавшие эти классы (во всех арендаторах). */
     invalidate(classes) {
         const set = new Set(classes);
         if (!set.size)
             return;
         for (const c of set)
-            this.classEpoch.set(c, (this.classEpoch.get(c) ?? 0) + 1);
+            this.bump(this.classEpoch, c);
         for (const [k, e] of this.map)
             if (e.classes.some((c) => set.has(c)))
                 this.map.delete(k);
     }
+    /** Сбросить ответы класса в арендаторе (токен) и ответы без арендатора; null — во всех. */
+    invalidateIn(cls, tenant) {
+        if (tenant === null)
+            return this.invalidate([cls]);
+        this.bump(this.pairEpoch, `${cls}@${tenant}`);
+        this.bump(this.anyEpoch, cls);
+        for (const [key, e] of this.map)
+            if ((e.tenant === null || e.tenant === tenant) && e.classes.includes(cls))
+                this.map.delete(key);
+    }
     /** Сбросить ответы сессии (тег — начало sha256 токена). */
     invalidateSession(tag) {
-        this.sessionEpoch.set(tag, (this.sessionEpoch.get(tag) ?? 0) + 1);
+        this.bump(this.sessionEpoch, tag);
         for (const [k, e] of this.map)
             if (e.session === tag)
                 this.map.delete(k);
     }
+    /**
+     * Счётчик сигналов по ключу (класс, пара «класс, арендатор», сессия). Ключи приходят в нагрузке сигнала, а её
+     * может прислать любая роль базы: при переполнении карта очищается, и снимки в полёте устаревают целиком
+     * (epoch), — иначе заливка разными именами копила бы счётчики без предела (ревью №1 точки А плана 1.1).
+     */
+    bump(m, k) {
+        if (m.size >= EPOCH_MAX && !m.has(k)) {
+            m.clear();
+            this.epoch++;
+        }
+        m.set(k, (m.get(k) ?? 0) + 1);
+    }
     /** Весь кэш. */
     clear() {
         this.epoch++;
         this.map.clear();
     }
+    /** Сброс по разобранному сигналу. */
+    apply(s) {
+        switch (s.kind) {
+            case 'session':
+                return this.invalidateSession(s.tag);
+            case 'class':
+                return ACL_CLASSES.has(s.cls) ? this.clear() : this.invalidateIn(s.cls, s.tenant);
+            case 'unknown':
+                // класса нет в реестрах процесса — и ответов с ним нет
+                return;
+            default:
+                // *, session:*, opaque без ключа, нагрузка не по режиму
+                return this.clear();
+        }
+    }
     /**
-     * Имена из сигнала или из letopis.changed своей транзакции: классы, `*`, `session:<тег>`,
-     * `session:*`. raw — запись через db.sql: весь кэш.
+     * Нагрузки из letopis.changed своей транзакции (те же, что уйдут сигналом). raw — запись через db.sql:
+     * весь кэш.
      */
     changed(names, raw = false) {
-        const classes = [];
         let any = false;
         for (const n of names) {
             if (!n)
                 continue;
             any = true;
-            if (n === '*' || n === 'session:*' || ACL_CLASSES.has(n)) {
-                this.clear();
-                return;
-            }
-            if (n.startsWith('session:'))
-                this.invalidateSession(n.slice(8));
-            else
-                classes.push(n);
+            if (!raw)
+                this.apply(this.sig.parse(n));
         }
-        if (raw && any) {
+        if (raw && any)
             this.clear();
-            return;
-        }
-        this.invalidate(classes);
     }
-    /** Сигнал от базы. */
-    signal(name) {
+    /** Сигнал от базы: нагрузка или уже разобранный. */
+    signal(s) {
         this.st.signals++;
-        this.changed([name]);
+        this.apply(typeof s === 'string' ? this.sig.parse(s) : s);
     }
     /** Слушатель (пере)подключился: сигналы за время обрыва потеряны — весь кэш. */
     listen() {

package/dist/chain.d.ts

@@ -2,7 +2,7 @@ import { type ResultCache } from './cache.js';
 import type { ClassInfo, Registry } from './registry.js';
 import { type Step } from './sql.js';
 import type { Executor } from './tx.js';
-import type { ChainMods, Cursor, Filter, Path, QueryEvent, Row } from './types.js';
+import type { BlameOptions, BlameResult, ChainMods, Cursor, DiffOptions, DiffResult, Filter, Path, QueryEvent, Row } from './types.js';
 export interface ChainCtx {
     readonly reg: Registry;
     readonly schema: string;
@@ -16,6 +16,9 @@ export interface ChainCtx {
     readonly slowMs?: number;
     /** Цепочка из батча: план копится в очереди до batch.run(). */
     readonly batch?: BatchRef;
+    /** Причина изменения по умолчанию для глаголов (db.batch(имя, { reason })) и та, что стоит в транзакции (db.begin({ reason })). */
+    readonly reason?: string;
+    readonly txReason?: string;
     /** Кэш результатов подключения и тот, кто спрашивает (ключ ответа, §2.12). */
     readonly cache?: {
         store: ResultCache;
@@ -61,6 +64,10 @@ export interface ChainCore {
     versions(opts?: {
         follow?: boolean;
     }): Promise<Row[]>;
+    /** Что изменилось между двумя версиями или моментами (по умолчанию — предыдущая версия → последняя), план 1.1. */
+    diff(opts?: DiffOptions): Promise<DiffResult[]>;
+    /** Кто, когда и почему последним изменил каждое поле версии (по умолчанию текущей), план 1.1. */
+    blame(opts?: BlameOptions): Promise<BlameResult[]>;
     /** Агрегаты по полю последнего шага ('data.<путь>') — по сущностям, считает база. */
     sum(field: string): Promise<number | null>;
     avg(field: string): Promise<number | null>;
@@ -92,31 +99,46 @@ export interface ChainCore {
     /** Вставить узел: ленивая цепочка-паттерн или строка ответа; та же переменная повторно — возврат к её узлу. */
     entity(x: Chain | Row): Chain;
     /** Создать объект: концы — из пути и слотов; занятый ключ — ошибка exists с id. */
-    create(data?: Record<string, unknown>): Chain;
+    create(data?: Record<string, unknown>, opts?: {
+        reason?: string;
+    }): Chain;
     /** Новая версия каждой цели шага: слияние патча в базе; inc(n) — приращение; { rev } — строгий режим. */
     update(patch?: Record<string, unknown>, opts?: {
         rev?: number;
+        reason?: string;
     }): Chain;
     /** Создать или заменить целиком (класс с ключом); строка ответа несёт $upsert. */
-    upsert(data: Record<string, unknown>): Chain;
+    upsert(data: Record<string, unknown>, opts?: {
+        reason?: string;
+    }): Chain;
     /** Удалить цели шага с каскадом; без { confirm: true } — превью замыкания ($action). */
     delete(opts?: {
         confirm?: boolean;
+        reason?: string;
     }): Chain;
     /** Затереть строковые поля ('[erased]') и пометить тегом anonymized. */
-    anonymize(fields: string[]): Chain;
+    anonymize(fields: string[], opts?: {
+        reason?: string;
+    }): Chain;
     /** Сменить класс: у класса с ключом — новый id и перевод ссылок. */
-    reclass(cls: string, data?: Record<string, unknown>): Chain;
+    reclass(cls: string, data?: Record<string, unknown>, opts?: {
+        reason?: string;
+    }): Chain;
     /** Чтение с блокировкой строк последнего шага до конца db.begin() (rows, first, ids). */
     forUpdate(): Chain;
     /** Восстановить удалённые объекты шага: последний снимок новой версией (id прежний). */
-    restore(): Chain;
+    restore(opts?: {
+        reason?: string;
+    }): Chain;
     /** Стереть историю удалённых объектов шага; без { confirm: true } — превью ($versions). */
     purge(opts?: {
         confirm?: boolean;
+        reason?: string;
     }): Chain;
     /** Новое значение ключа: строка с новым id, ссылки переведены (поля — данные, роли — концы). */
-    rekey(patch: Record<string, unknown>): Chain;
+    rekey(patch: Record<string, unknown>, opts?: {
+        reason?: string;
+    }): Chain;
     /** Кэш результатов (§2.12): ответ хранится в памяти процесса ttl секунд (по умолчанию 60). */
     cache(opts?: {
         ttl?: number;

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,13 @@
  *   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): пустая схема, одна транзакция, индексы и триггеры — после загрузки
  */
 import { parseArgs } from 'node:util';
 import { readFile, writeFile } from 'node:fs/promises';
@@ -24,12 +25,12 @@ 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]`;
 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,6 +44,7 @@ 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' },
         },
     });
     const [cmd, arg] = positionals;
@@ -68,7 +70,7 @@ 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;
@@ -116,6 +118,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;

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;
 }