letopis 0.5.0 → 0.16.0

package/dist/types.d.ts

@@ -16,8 +16,34 @@ export interface Row {
     /** Глубина узла при .deep()-обходе (1 = прямой ребёнок). */
     $depth?: number;
 }
-/** Результат execute(): вариант пути — узел на каждый шаг цепочки. */
+/** Результат run(): вариант пути — узел на каждый шаг цепочки. */
 export type Path = Record<string, Row>;
+/**
+ * Конец связи класса (Schema.links v2). В БД элемент text[]: JSON-объект
+ * `{"class":"Org","cardinality":1}` / `{"classes":["Service","Complex"],"cardinality":1}`
+ * (союз ролей); legacy-строка 'Org' — сахар для {classes:['Org']} (старые схемы).
+ */
+export interface LinkEnd {
+    /** Допустимые классы конца; ровно один из них присутствует в Entity.links. */
+    classes: string[];
+    /** Конец может отсутствовать. Default false. */
+    optional?: boolean;
+    /** ЗАРЕЗЕРВИРОВАНО (не имплементировано): 0 — безлимит, N — точное число. Default 1. */
+    cardinality?: number;
+}
+/**
+ * Генерация id класса — из attributes.id:
+ *   "uuid" | {type:'uuid'}                    → v4 (random, дефолт);
+ *   {type:'uuid', generate: 7}                → v7 (время в старших битах);
+ *   {type:'uuid', generate: 5, from: ['Slot','Staff']} → v5: детерминированный id из значений
+ *     from — имена ОБЯЗАТЕЛЬНЫХ концов Schema.links (класс или полное имя союза
+ *     'Service|Complex') и/или скалярных полей data.
+ */
+export interface IdGen {
+    version: 4 | 5 | 7;
+    /** Только v5: источники имени (порядок значим). */
+    from?: string[];
+}
 /** Класс из таблицы Schema. */
 export interface ClassDef {
     id: string;
@@ -27,11 +53,20 @@ export interface ClassDef {
     ancestors: string[];
     /** Все потомки (транзитивно) — считает триггер schema_lineage. */
     descendants: string[];
+    /** Поля data с НАСЛЕДОВАНИЕМ по ancestor-цепочке (потомок поверх предка). */
     attributes: Record<string, unknown>;
-    links: string[];
+    links: LinkEnd[];
+    /**
+     * true — хотя бы один конец объявлен объектом (схема v2): строгая валидация
+     * (жадный матчинг по порядку, союзы, optional, лишние связи — ошибка).
+     * false — все концы legacy-строками: старое поведение ('Entity' = полиморф, лишние молчат).
+     */
+    strictEnds: boolean;
     meta: Record<string, unknown>;
     abstract: boolean;
     order: number;
+    /** Как генерить id новой сущности (attributes.id). */
+    idGen: IdGen;
     /** Скомпилированный fastest-validator: true | ошибки. */
     check: (data: Record<string, unknown>) => true | {
         field: string;
@@ -53,6 +88,9 @@ export type FieldType = {
 } | {
     kind: 'record';
     value: FieldType;
+} | {
+    kind: 'object';
+    props: Map<string, FieldType>;
 } | {
     kind: 'any';
 };
@@ -81,6 +119,22 @@ export interface Cursor {
     v: string | number;
     id: string;
 }
+/**
+ * Операция записи, привязанная к шагу цепочки:
+ * .create() / .update() / .delete() / .anonymize().
+ * Терминал исполняет план (все операции + финальное чтение) одной транзакцией.
+ */
+export interface PlanOp {
+    kind: 'create' | 'update' | 'delete' | 'anonymize';
+    /** create/update: данные новой версии (deep-merge листьев). */
+    data?: Record<string, unknown>;
+    /** anonymize: string-поля под '[erased]'. */
+    fields?: string[];
+    /** delete: true — удалить; без confirm — превью (вернуть кандидатов, БД не трогать). */
+    confirm?: boolean;
+    /** Снапшот модификаторов на момент вызова операции (limit/sort для поиска целей). */
+    mods: ChainMods;
+}
 /** Модификаторы выборки цепочки: .limit() / .offset() / .sort() / .asOf() / .after(). */
 export interface ChainMods {
     limit?: number;
@@ -131,6 +185,23 @@ export interface Rule {
     meta: Record<string, unknown> | null;
     enabled: boolean;
 }
+/** Операция над данными = категория Resource: 'READ' | 'WRITE' | 'DELETE'. */
+export type AclOp = 'READ' | 'WRITE' | 'DELETE';
+/** Решение ACL: победившее правило (max weight; при равенстве deny; нет правил — deny). */
+export interface AclDecision {
+    allow: boolean;
+    /** Победившее правило (нет — deny «no matching rule»). */
+    rule?: Rule;
+    /**
+     * Остаточный шаблон строки Entity из pattern победившего allow-ресурса
+     * (ключи-колонки без class, "$account" уже подставлен) — вливается в SQL
+     * до сортировки/лимита. Отсутствует = класс целиком.
+     */
+    filter?: Record<string, unknown>;
+    /** Из meta deny-правила: код и сообщение для ответа клиенту. */
+    code?: number;
+    message?: string;
+}
 /** Событие хука onQuery: один SQL-запрос цепочки (чтение или запись). */
 export interface QueryEvent {
     /** Режим чтения или write-операция. */
@@ -159,6 +230,14 @@ export interface ConnectOpts {
     max?: number;
     /** Жёсткая изоляция арендатора: чтения фильтруются по account, записи пришпилены к нему. */
     enforceAccount?: boolean;
+    /**
+     * ACL по Resource/Rule: категории READ/WRITE/DELETE, pattern — шаблон строки Entity
+     * (колонки + "$account"). Каждый шаг цепочки проверяется на READ, записи — WRITE,
+     * delete — DELETE (включая классы каскада); предикат победившего правила вливается
+     * в SQL до сортировки/лимита. Требует account. Deny-by-default.
+     * Правила читаются один раз при connect (перечитка — новый connect).
+     */
+    enforceAcl?: boolean;
     /** Хук на каждый запрос цепочки (метрики, лог). */
     onQuery?: (e: QueryEvent) => void;
     /** Порог «медленного» запроса, мс: событие получает slow: true; без onQuery — console.warn. */

package/dist/up.d.ts

@@ -0,0 +1,48 @@
+import type { EntityDb } from './chain.js';
+import type { ConnectOpts } from './types.js';
+export interface UpOpts extends Omit<ConnectOpts, 'dsn' | 'schema'> {
+    /** postgres://user:pass@host:port/db. Default postgres://postgres:test@localhost:15432/letopis. */
+    dsn?: string;
+    /** Базовое имя схемы БЕЗ версии и точек (напр. 'booking'). */
+    schema: string;
+    /** Версия движка: итоговая PG-схема "v<N>.<schema>". Бамп руками при breaking-изменении DDL. */
+    version: number;
+    /** Имя dev-контейнера. Default 'letopis-timescale'. */
+    container?: string;
+    /** Имя docker-образа; при отсутствии соберётся из пакованного Dockerfile. Default 'letopis-db'. */
+    image?: string;
+    /**
+     * Где держать данные PG: путь на хосте (bind mount, на Windows/NTFS — на свой риск)
+     * либо имя docker-volume. Default — named volume 'letopis-pgdata' (кроссплатформенно;
+     * переживает пересоздание контейнера).
+     */
+    dataDir?: string;
+    /** Хост-порт Redis контейнера. Default 16379. */
+    redisPort?: number;
+    /**
+     * Сиды после ddl: массив путей — свои файлы (маркер "<SCHEMA-NAME>" в них поддержан);
+     * default — демо booking + auth. Свой сид должен дать хотя бы один класс в Schema
+     * (иначе connect в конце честно упадёт «has no classes»); false — голая структура
+     * без сидов, годится только чтобы поставить движок — connect не переживёт.
+     */
+    seeds?: string[] | false;
+    /** Дропнуть схему и накатить заново. ДАННЫЕ СХЕМЫ ТЕРЯЮТСЯ. */
+    fresh?: boolean;
+    /** Без console.log-прогресса. */
+    quiet?: boolean;
+    /** Максимум ожидания готовности, мс. Default 120 000 (первый запуск: pull образа + initdb). */
+    waitTimeoutMs?: number;
+}
+export interface RunCfg {
+    container: string;
+    image: string;
+    pgPort: string;
+    redisPort: number;
+    user: string;
+    password: string;
+    database: string;
+    dataDir?: string;
+}
+/** argv для docker run (чистая функция — покрыта юнитом). dataDir: путь → bind, имя → volume. */
+export declare function dockerRunArgs(cfg: RunCfg): string[];
+export declare function up(opts: UpOpts): Promise<EntityDb>;

package/dist/up.js

@@ -0,0 +1,209 @@
+/**
+ * letopis.up(): одна точка входа — dev-контейнер (TimescaleDB + Redis), готовность БД,
+ * версионная схема с сидами, connect. Идемпотентно: живой postgres на dsn → docker
+ * пропускается целиком; существующая схема не трогается (fresh: true — дроп и накат).
+ *
+ *   const db = await up({ schema: 'booking', version: 1 });   // → PG-схема "v1.booking"
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { setTimeout as sleep } from 'node:timers/promises';
+import net from 'node:net';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import postgres from 'postgres';
+import { connect } from './index.js';
+const exec = promisify(execFile);
+const DEFAULT_DSN = 'postgres://postgres:test@localhost:15432/letopis';
+const qi = (s) => `"${s.replace(/"/g, '""')}"`;
+const pkgPath = (rel) => fileURLToPath(new URL(rel, import.meta.url));
+/** argv для docker run (чистая функция — покрыта юнитом). dataDir: путь → bind, имя → volume. */
+export function dockerRunArgs(cfg) {
+    const args = ['run', '-d', '--name', cfg.container,
+        '-p', `${cfg.pgPort}:5432`, '-p', `${cfg.redisPort}:6379`,
+        '-v', `${cfg.dataDir ?? 'letopis-pgdata'}:/var/lib/postgresql/data`];
+    if (cfg.user && cfg.user !== 'postgres')
+        args.push('-e', `POSTGRES_USER=${cfg.user}`);
+    // без пароля в dsn контейнер поднимается в trust-режиме (dev), иначе postgres-образ не стартует
+    args.push('-e', cfg.password ? `POSTGRES_PASSWORD=${cfg.password}` : 'POSTGRES_HOST_AUTH_METHOD=trust');
+    args.push('-e', `POSTGRES_DB=${cfg.database}`, cfg.image);
+    return args;
+}
+async function docker(args) {
+    try {
+        const { stdout, stderr } = await exec('docker', args, { maxBuffer: 64 * 1024 * 1024 });
+        return { ok: true, out: stdout.trim(), err: stderr };
+    }
+    catch (e) {
+        const x = e;
+        if (x.code === 'ENOENT')
+            throw new Error('letopis.up: docker CLI not found — install Docker or point dsn at an already running postgres');
+        return { ok: false, out: (x.stdout ?? '').trim(), err: (x.stderr || x.message || '').trim() };
+    }
+}
+async function ensureContainer(cfg, log) {
+    const st = await docker(['container', 'inspect', '--format', '{{.State.Running}}', cfg.container]);
+    if (st.ok && st.out === 'true') {
+        log(`container ${cfg.container} is running — reused`);
+        return;
+    }
+    if (st.ok) {
+        const r = await docker(['start', cfg.container]);
+        if (!r.ok)
+            throw new Error(`letopis.up: docker start ${cfg.container} failed: ${r.err}`);
+        log(`container ${cfg.container} started`);
+        return;
+    }
+    const img = await docker(['image', 'inspect', cfg.image]);
+    if (!img.ok) {
+        log(`building image ${cfg.image} (first time pulls the timescaledb base — may take minutes)…`);
+        const b = await docker(['build', '-t', cfg.image, pkgPath('../docker/')]);
+        if (!b.ok)
+            throw new Error(`letopis.up: docker build ${cfg.image} failed: ${b.err}`);
+        log(`image ${cfg.image} built`);
+    }
+    const r = await docker(dockerRunArgs(cfg));
+    if (!r.ok)
+        throw new Error(`letopis.up: docker run ${cfg.container} failed: ${r.err}`);
+    log(`container ${cfg.container} created (data: ${cfg.dataDir ?? 'volume letopis-pgdata'})`);
+}
+async function pgPing(dsn) {
+    const sql = postgres(dsn, { max: 1, connect_timeout: 3, onnotice: () => { } });
+    try {
+        await sql `select 1`;
+        return { ok: true };
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === '3D000')
+            return { ok: false, kind: 'no-database', err: e }; // сервер жив, базы нет
+        if (code === '57P03')
+            return { ok: false, kind: 'starting', err: e }; // initdb/recovery
+        if (code === '28P01' || code === '28000')
+            return { ok: false, kind: 'fatal', err: e }; // ретраи бессмысленны
+        return { ok: false, kind: 'no-server', err: e };
+    }
+    finally {
+        await sql.end({ timeout: 1 }).catch(() => { });
+    }
+}
+async function ensureDatabase(url, log) {
+    const dbName = decodeURIComponent(url.pathname.slice(1)) || url.username || 'postgres';
+    const admin = new URL(url);
+    admin.pathname = '/postgres';
+    const sql = postgres(admin.toString(), { max: 1, onnotice: () => { } });
+    try {
+        const rows = await sql `SELECT 1 FROM pg_database WHERE datname = ${dbName}`;
+        if (rows.length === 0) {
+            await sql.unsafe(`CREATE DATABASE ${qi(dbName)}`).catch((e) => {
+                if (e.code !== '42P04')
+                    throw e; // 42P04 — гонка параллельных up()
+            });
+            log(`database "${dbName}" created`);
+        }
+    }
+    finally {
+        await sql.end();
+    }
+}
+function tcpAlive(host, port) {
+    return new Promise((res) => {
+        const s = net.connect({ host, port });
+        const done = (v) => { s.destroy(); res(v); };
+        s.once('connect', () => done(true));
+        s.once('error', () => done(false));
+        s.setTimeout(2000, () => done(false));
+    });
+}
+async function applySchema(dsn, full, seeds, fresh, log) {
+    const sql = postgres(dsn, { max: 1, onnotice: () => { } });
+    try {
+        if (fresh) {
+            await sql.unsafe(`DROP SCHEMA IF EXISTS ${qi(full)} CASCADE`);
+            log(`schema "${full}" dropped (fresh)`);
+        }
+        const have = await sql `SELECT 1 FROM information_schema.schemata WHERE schema_name = ${full}`;
+        if (have.length > 0) {
+            log(`schema "${full}" already exists — apply skipped`);
+            return;
+        }
+        const files = [pkgPath('../sql/ddl.sql')];
+        if (seeds === undefined)
+            files.push(pkgPath('../sql/seed.booking.sql'), pkgPath('../sql/seed.auth.sql'));
+        else if (seeds)
+            files.push(...seeds.map((p) => resolve(p)));
+        for (const f of files) {
+            const text = (await readFile(f, 'utf8')).replaceAll('<SCHEMA-NAME>', full);
+            await sql.unsafe(text); // multi-statement simple query
+        }
+        log(`schema "${full}" applied (${files.length} files)`);
+    }
+    finally {
+        await sql.end();
+    }
+}
+export async function up(opts) {
+    const { dsn = DEFAULT_DSN, schema, version, container = 'letopis-timescale', image = 'letopis-db', dataDir, redisPort = 16379, seeds, fresh, quiet, waitTimeoutMs = 120_000, ...connectRest } = opts;
+    if (!/^[a-zA-Z_][a-zA-Z0-9_$]*$/.test(schema))
+        throw new Error(`letopis.up: bad schema name "${schema}" (базовое имя без версии и точек; версию задаёт version)`);
+    if (!Number.isInteger(version) || version < 1)
+        throw new Error(`letopis.up: bad version ${version} (целое ≥ 1)`);
+    const full = `v${version}.${schema}`;
+    const url = new URL(dsn);
+    const host = url.hostname;
+    const local = host === 'localhost' || host === '127.0.0.1' || host === '::1';
+    const log = quiet ? () => { } : (m) => console.log(`[letopis.up] ${m}`);
+    const deadline = Date.now() + waitTimeoutMs;
+    let ping = await pgPing(dsn);
+    if (ping.ok || ping.kind === 'no-database') {
+        // postgres уже отвечает (свой контейнер, CI-сервис, внешняя БД) — docker не нужен
+        if (!ping.ok)
+            await ensureDatabase(url, log);
+        log(`postgres is up at ${host}:${url.port || '5432'} — docker skipped`);
+    }
+    else if (ping.kind === 'fatal') {
+        throw ping.err;
+    }
+    else {
+        if (local) {
+            await ensureContainer({
+                container, image, pgPort: url.port || '5432', redisPort,
+                user: decodeURIComponent(url.username), password: decodeURIComponent(url.password),
+                database: decodeURIComponent(url.pathname.slice(1)) || url.username || 'postgres', dataDir,
+            }, log);
+        }
+        else {
+            log(`waiting for remote postgres at ${host} (no docker for non-local dsn)…`);
+        }
+        const t0 = Date.now();
+        for (;;) {
+            ping = await pgPing(dsn);
+            if (ping.ok)
+                break;
+            if (ping.kind === 'fatal')
+                throw ping.err;
+            if (ping.kind === 'no-database') {
+                await ensureDatabase(url, log);
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new Error(`letopis.up: postgres not ready in ${Math.round(waitTimeoutMs / 1000)} s${local ? ` — check: docker logs ${container}` : ''}`);
+            await sleep(500);
+        }
+        log(`postgres ready in ${((Date.now() - t0) / 1000).toFixed(1)} s`);
+        if (local) {
+            // контейнер поднимали мы — убеждаемся, что и redis-порт жив
+            while (!(await tcpAlive(host, redisPort))) {
+                if (Date.now() > deadline)
+                    throw new Error(`letopis.up: redis not ready on ${redisPort} — check: docker logs ${container}`);
+                await sleep(300);
+            }
+            log(`redis ready on ${redisPort}`);
+        }
+    }
+    await applySchema(dsn, full, seeds, fresh ?? false, log);
+    const db = await connect({ ...connectRest, dsn, schema: full });
+    log(`connected (schema "${full}")`);
+    return db;
+}

package/dist/uuid.d.ts

@@ -0,0 +1,6 @@
+/** Namespace letopis для uuidv5 (фиксированная константа — стабильность id между релизами). */
+export declare const LETOPIS_NS = "c7a2f9d4-3b61-4e8a-9f05-8d2c1e6b7a90";
+/** RFC 4122 v5: sha1(namespace + name); детерминирован — одно имя → один uuid. */
+export declare function uuidv5(name: string, ns?: string): string;
+/** RFC 9562 v7: 48 бит unix-ms + random — время в старших битах, вставки ложатся в хвост индекса. */
+export declare function uuidv7(): string;

package/dist/uuid.js

@@ -0,0 +1,32 @@
+/**
+ * Генерация id по Schema (attributes.id):
+ *   "uuid"                                    → v4 (random) — дефолт;
+ *   { type: 'uuid', generate: 7 }             → v7 (unix-время в старших битах: btree-локальность);
+ *   { type: 'uuid', generate: 5, from: […] }  → v5: sha1 от «схема:партиция:класс:значения from» —
+ *     детерминированный id из концов/полей: та же комбинация → тот же id (идемпотентный create,
+ *     дубль невозможен даже в гонке — оба запроса вычислят один id, второй станет версией).
+ */
+import { createHash, randomBytes } from 'node:crypto';
+/** Namespace letopis для uuidv5 (фиксированная константа — стабильность id между релизами). */
+export const LETOPIS_NS = 'c7a2f9d4-3b61-4e8a-9f05-8d2c1e6b7a90';
+const fmt = (b) => {
+    const h = b.toString('hex');
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
+};
+/** RFC 4122 v5: sha1(namespace + name); детерминирован — одно имя → один uuid. */
+export function uuidv5(name, ns = LETOPIS_NS) {
+    const nsBytes = Buffer.from(ns.replace(/-/g, ''), 'hex');
+    const h = createHash('sha1').update(nsBytes).update(name, 'utf8').digest().subarray(0, 16);
+    h[6] = (h[6] & 0x0f) | 0x50; // version 5
+    h[8] = (h[8] & 0x3f) | 0x80; // variant 10xx
+    return fmt(h);
+}
+/** RFC 9562 v7: 48 бит unix-ms + random — время в старших битах, вставки ложатся в хвост индекса. */
+export function uuidv7() {
+    const b = Buffer.alloc(16);
+    b.writeUIntBE(Date.now(), 0, 6);
+    randomBytes(10).copy(b, 6);
+    b[6] = (b[6] & 0x0f) | 0x70; // version 7
+    b[8] = (b[8] & 0x3f) | 0x80; // variant 10xx
+    return fmt(b);
+}

package/dist/write.d.ts

@@ -31,30 +31,43 @@ export declare function readRows(ctx: Ctx, steps: Step[], mods?: ChainMods): Pro
  */
 export declare function deepMerge(base: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
 /**
- * .set(data):
- *  - пустой фильтр последнего шага и нет data.id → INSERT (links = контекст);
- *  - id (фильтр-строка или data.id) → UPSERT: есть → новая версия (deep-merge), нет → создать;
- *  - фильтр-объект → новая версия каждого найденного (в границах контекста); пусто → [].
+ * .create(data) — «чтобы сущность существовала»:
+ *  - id не задан → INSERT (id по IdGen класса; links = концы из пути + слоты);
+ *  - id известен (Класс(id) / data.id / вычислен v5): есть → новая версия (deep-merge),
+ *    нет → INSERT с этим id (идемпотентный create, REST-PUT семантика);
+ *  - фильтр-объект / pivot — ошибка: create не ищет, это update().
  */
-export declare function setOp(ctx: Ctx, steps: Step[], mods: ChainMods, data: Record<string, unknown>, extraLinks?: Record<string, string>): Promise<Row[]>;
+export declare function createOp(ctx: Ctx, steps: Step[], mods: ChainMods, data: Record<string, unknown>): Promise<Row[]>;
+/**
+ * .update(data?) — новая версия КАЖДОГО найденного путём (deep-merge листьев);
+ * цели: Класс() ≡ Класс({}) — все в границах контекста, id/фильтр/pivot — как в чтении.
+ * Не найдено → [] — update НИКОГДА не создаёт.
+ */
+export declare function updateOp(ctx: Ctx, steps: Step[], mods: ChainMods, data: Record<string, unknown>): Promise<Row[]>;
 /**
  * .anonymize(fields): GDPR-затирание — новая версия с '[erased]' в указанных string-полях
  * + тег 'anonymized'. Только string-поля (по Schema); история сохраняется (см. README).
  */
 export declare function anonymizeOp(ctx: Ctx, steps: Step[], mods: ChainMods, fields: string[]): Promise<Row[]>;
 /**
- * .delete(): цели = фильтр последнего шага + контекст-связи; серверное удаление.
- * Триггер entity_delete: tombstone + рекурсивный каскад (+advisory-lock).
- * Возвращает ВСЁ удалённое (цели + каскад) с $deleted: true.
+ * .delete({confirm}): цели = фильтр последнего шага + контекст-связи.
+ * confirm: true — серверное удаление (триггер entity_delete: tombstone + рекурсивный
+ * каскад + advisory-lock); возвращает ВСЁ удалённое (цели + каскад) с $deleted: true.
+ * Без confirm — ПРЕВЬЮ: то же замыкание (цели + каскад), но БД не трогается.
+ */
+export declare function delOp(ctx: Ctx, steps: Step[], mods: ChainMods, confirm: boolean): Promise<Row[]>;
+export type PlanMode = 'rows' | 'ids' | 'count' | 'paths' | 'versions' | 'agg';
+/**
+ * Исполнить план целиком: все операции + финальное чтение — одна транзакция
+ * (внутренняя, с ретраем transient; внутри db.begin() — транзакция пользователя).
+ * Продолжение после операции: fan-out — каждый следующий сегмент исполняется от каждой
+ * строки результата (контекст = строка); self-шаг (op сразу после op) пишет в те же строки.
+ * После delete продолжение идёт от строк КЛАССА ЦЕЛИ (замыкание каскада шире).
  */
-export declare function delOp(ctx: Ctx, steps: Step[], mods: ChainMods): Promise<Row[]>;
-export interface BatchOp {
-    kind: 'set' | 'delete';
+export declare function runPlan(ctx: Ctx, steps: Step[], mods: ChainMods, mode: PlanMode): Promise<unknown>;
+/** План в очереди батча; steps обновляется по мере роста цепочки. */
+export interface BatchPlan {
     steps: Step[];
-    mods: ChainMods;
-    data?: Record<string, unknown>;
-    /** Связи, довешенные после set() (мутируется билдером до execute()). */
-    extraLinks?: Record<string, string>;
 }
-export declare function executeBatch(ctx: Ctx, queue: BatchOp[]): Promise<Row[][]>;
+export declare function executeBatch(ctx: Ctx, queue: BatchPlan[]): Promise<Row[][]>;
 export {};