letopis 0.5.0 → 0.13.0

package/dist/sql.d.ts

@@ -18,7 +18,7 @@
  * Цепочка шагов соединяется JOIN LATERAL — комбинации путей сохраняются.
  */
 import type { Sql } from 'postgres';
-import type { ClassDef, ChainMods, Filter, QueryEvent } from './types.js';
+import type { AclOp, AclDecision, ClassDef, ChainMods, FieldType, Filter, QueryEvent } from './types.js';
 import type { Registry } from './schema.js';
 export interface Ctx {
     sql: Sql;
@@ -31,15 +31,27 @@ export interface Ctx {
     systemAccount?: string;
     /** Жёсткая изоляция арендатора: все чтения фильтруются, записи пришпилены к account. */
     enforceAccount?: boolean;
+    /** enforceAcl: скомпилированный на connect резолвер Rule/Resource (READ/WRITE/DELETE). */
+    aclDecide?: (cls: ClassDef, op: AclOp) => AclDecision;
     /** true внутри db.begin()-транзакции (write не оборачивает в begin повторно). */
     inTx?: boolean;
+    /** true только у db.begin()-транзакций (не у внутренних): управляет подсказкой при 40P01/40001. */
+    userTx?: boolean;
     /** Наблюдаемость: хук на каждый запрос цепочки. */
     onQuery?: (e: QueryEvent) => void;
     /** Порог «медленного» запроса, мс (без onQuery — console.warn). */
     slowMs?: number;
 }
+/** Транзиентные ошибки PG — гонка, снимаемая повтором: deadlock / serialization failure. */
+export declare function isTransient(e: unknown): boolean;
+/** Внутри db.begin() повтор невозможен (вся транзакция aborted) — дописываем подсказку. */
+export declare function hintTxRetry(e: unknown): void;
+export declare const RETRIES = 3;
+export declare const retryDelay: (attempt: number) => Promise<void>;
 /**
  * Единая точка исполнения запросов цепочек: sql.unsafe + событие onQuery/slowMs.
+ * Чтения в автокоммите ретраят transient-ошибки (40P01/40001); внутри db.begin()
+ * повтор запрещён семантикой PG — ошибка уходит наружу с подсказкой.
  * Служебные запросы (loadRegistry, tables, listen) через неё не идут.
  */
 export declare function runQuery<T>(ctx: Ctx, text: string, params: unknown[], mode: QueryEvent['mode'], classes: string[]): Promise<T[]>;
@@ -58,10 +70,20 @@ export interface Step {
     ownerFilter?: string;
     /** Внутреннее (write-цепочки): containment по links — контекст-связи. */
     linksFilter?: Record<string, string>;
+    /** .link(Класс, target) — значение связи при записи БЕЗ участия в фильтре целей. */
+    extraLinks?: Record<string, string>;
+    /** Внутреннее (enforceAcl): предикат WRITE/DELETE-правила — цели ищутся только среди своих. */
+    aclFilter?: Record<string, unknown>;
     /** .deep(max): рекурсивный self-обход (дети любой глубины), только reverse того же класса. */
     deepMax?: number;
+    /** Операция записи на шаге (.set/.delete/.anonymize) — исполняется терминалом плана. */
+    op?: import('./types.js').PlanOp;
+    /** Внутреннее: шаг «те же сущности» (операция сразу после операции) — цель = строки старта. */
+    self?: boolean;
 }
 export declare const entityTable: (pgSchema: string) => string;
+/** Тип листа data-пути по Schema: спуск через record (значение) и object (props). */
+export declare function leafType(cls: ClassDef, path: string[]): FieldType | undefined;
 type HopMode = 'forward' | 'reverse';
 /** Правило обхода между шагами (по реестру Schema). */
 export declare function resolveHop(prev: ClassDef, next: ClassDef): HopMode;

package/dist/sql.js

@@ -1,21 +1,59 @@
 import { OP } from './types.js';
 import { isOp } from './ops.js';
+import { aclDenied } from './acl.js';
+/** Транзиентные ошибки PG — гонка, снимаемая повтором: deadlock / serialization failure. */
+export function isTransient(e) {
+    const code = e.code;
+    return code === '40P01' || code === '40001';
+}
+/** Внутри db.begin() повтор невозможен (вся транзакция aborted) — дописываем подсказку. */
+export function hintTxRetry(e) {
+    const err = e;
+    if (err.letopisHinted || typeof err.message !== 'string')
+        return;
+    err.letopisHinted = true;
+    err.message += ' — letopis: transaction is aborted, retry the whole db.begin() block';
+}
+export const RETRIES = 3;
+export const retryDelay = (attempt) => new Promise((r) => setTimeout(r, 40 * attempt + Math.random() * 40));
+const READ_MODES = new Set([
+    'paths', 'rows', 'ids', 'count', 'versions', 'agg',
+]);
 /**
  * Единая точка исполнения запросов цепочек: sql.unsafe + событие onQuery/slowMs.
+ * Чтения в автокоммите ретраят transient-ошибки (40P01/40001); внутри db.begin()
+ * повтор запрещён семантикой PG — ошибка уходит наружу с подсказкой.
  * Служебные запросы (loadRegistry, tables, listen) через неё не идут.
  */
 export async function runQuery(ctx, text, params, mode, classes) {
-    const t0 = performance.now();
-    const res = (await ctx.sql.unsafe(text, params));
-    if (ctx.onQuery || ctx.slowMs !== undefined) {
-        const ms = performance.now() - t0;
-        const slow = ctx.slowMs !== undefined && ms > ctx.slowMs;
-        if (ctx.onQuery)
-            ctx.onQuery({ mode, classes, ms, rows: res.length, slow });
-        else if (slow)
-            console.warn(`letopis: slow query ${ms.toFixed(0)}ms — ${mode} ${classes.join('→')}`);
+    for (let attempt = 1;; attempt++) {
+        const t0 = performance.now();
+        try {
+            const res = (await ctx.sql.unsafe(text, params));
+            if (ctx.onQuery || ctx.slowMs !== undefined) {
+                const ms = performance.now() - t0;
+                const slow = ctx.slowMs !== undefined && ms > ctx.slowMs;
+                if (ctx.onQuery)
+                    ctx.onQuery({ mode, classes, ms, rows: res.length, slow });
+                else if (slow)
+                    console.warn(`letopis: slow query ${ms.toFixed(0)}ms — ${mode} ${classes.join('→')}`);
+            }
+            return res;
+        }
+        catch (e) {
+            if (isTransient(e)) {
+                if (ctx.inTx) {
+                    if (ctx.userTx)
+                        hintTxRetry(e);
+                }
+                else if (READ_MODES.has(mode) && attempt < RETRIES) {
+                    await retryDelay(attempt);
+                    continue;
+                }
+            }
+            throw e;
+        }
     }
-    return res;
 }
 /** Накопитель позиционных параметров. */
 class Params {
@@ -28,6 +66,35 @@ class Params {
 const escId = (s) => `"${s.replace(/"/g, '""')}"`;
 const escLit = (s) => s.replace(/'/g, "''");
 export const entityTable = (pgSchema) => `${escId(pgSchema)}.${escId('Entity')}`;
+/**
+ * ACL-шаблон строки Entity → WHERE-фраги: колонки равенством, jsonb/tags — containment.
+ * Вливается и в кандидаты (GIN), и в перепроверку — ДО сортировки/лимита (пагинация цела).
+ */
+function rowTemplateFrags(tpl, p) {
+    const frags = [];
+    for (const [k, v] of Object.entries(tpl)) {
+        if (k === 'data' || k === 'links') {
+            const ph = p.push(v);
+            frags.push((a) => `${a}.${k} @> ${ph}::jsonb`);
+        }
+        else if (k === 'tags') {
+            const ph = p.push(Array.isArray(v) ? v : [v]);
+            frags.push((a) => `${a}.tags @> ${ph}`);
+        }
+        else if (k === 'owner' || k === 'account') {
+            const ph = p.push(v);
+            frags.push((a) => `${a}.${k} = ${ph}::uuid`);
+        }
+        else if (k === 'id' || k === 'partition') {
+            const ph = p.push(v);
+            frags.push((a) => `${a}.${k} = ${ph}`);
+        }
+        else {
+            throw new Error(`letopis: acl pattern key "${k}" is not an Entity column`);
+        }
+    }
+    return frags;
+}
 function castOf(ft) {
     switch (ft?.kind) {
         case 'number':
@@ -42,11 +109,23 @@ function castOf(ft) {
 }
 /** Каст параметра по JS-типу (для jsonb_build_array). */
 const jsCast = (v) => typeof v === 'number' ? '::numeric' : typeof v === 'boolean' ? '::boolean' : '::text';
-/** Доступ к полю data: 1 уровень — data->>'f'; 2 (record) — data->'f'->>'k'. */
+/** jsonb-выражение до пути (без извлечения текста): data->'a'->'b'. */
+function jsonbAt(path) {
+    return (a) => `${a}.data${path.map((k) => `->'${escLit(k)}'`).join('')}`;
+}
+/** Текст листа по data-пути ЛЮБОЙ глубины: data->'a'->'b'->>'c'. */
 function accessor(path) {
-    if (path.length === 1)
-        return (a) => `${a}.data->>'${escLit(path[0])}'`;
-    return (a) => `${a}.data->'${escLit(path[0])}'->>'${escLit(path[1])}'`;
+    const head = path.slice(0, -1);
+    const last = path[path.length - 1];
+    return (a) => `${jsonbAt(head)(a)}->>'${escLit(last)}'`;
+}
+/** Тип листа data-пути по Schema: спуск через record (значение) и object (props). */
+export function leafType(cls, path) {
+    let ft = cls.fieldTypes.get(path[0]);
+    for (let i = 1; i < path.length && ft; i++) {
+        ft = ft.kind === 'record' ? ft.value : ft.kind === 'object' ? ft.props.get(path[i]) : undefined;
+    }
+    return ft;
 }
 function compileOp(path, ft, o, p) {
     const lhs = accessor(path);
@@ -79,23 +158,26 @@ function compileOp(path, ft, o, p) {
             return (a) => `${lhs(a)} ILIKE ${p.push(args[0])}`;
         case 'has':
             // jsonb_build_array с кастом по JS-типу — JS-массив postgres.js слал бы как PG-array
-            return (a) => `${a}.data->'${escLit(path[0])}' @> jsonb_build_array(${p.push(args[0])}${jsCast(args[0])})`;
+            return (a) => `${jsonbAt(path)(a)} @> jsonb_build_array(${p.push(args[0])}${jsCast(args[0])})`;
         case 'hasAll': {
             const vs = args[0];
             if (!vs.length)
                 return () => 'TRUE';
-            return (a) => `${a}.data->'${escLit(path[0])}' @> jsonb_build_array(${vs.map((x) => p.push(x) + jsCast(x)).join(', ')})`;
+            return (a) => `${jsonbAt(path)(a)} @> jsonb_build_array(${vs.map((x) => p.push(x) + jsCast(x)).join(', ')})`;
         }
         case 'hasAny': {
             const vs = args[0];
             if (!vs.length)
                 return () => 'FALSE';
-            return (a) => `${a}.data->'${escLit(path[0])}' ?| ARRAY[${vs.map((x) => p.push(String(x))).join(', ')}]::text[]`;
+            return (a) => `${jsonbAt(path)(a)} ?| ARRAY[${vs.map((x) => p.push(String(x))).join(', ')}]::text[]`;
         }
-        case 'exists':
+        case 'exists': {
+            const holder = jsonbAt(path.slice(0, -1));
+            const last = escLit(path[path.length - 1]);
             return args[0]
-                ? (a) => `${a}.data ? '${escLit(path[0])}'`
-                : (a) => `NOT (${a}.data ? '${escLit(path[0])}')`;
+                ? (a) => `${holder(a)} ? '${last}'`
+                : (a) => `NOT (${holder(a)} ? '${last}')`;
+        }
         case 'isNull':
             return (a) => `${lhs(a)} IS NULL`;
         case 'not': {
@@ -157,6 +239,39 @@ function compileFilter(cls, filter, p) {
         return out;
     }
     const eqData = {};
+    const isPlain = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) && !isOp(v);
+    /**
+     * Рекурсивный разбор объекта фильтра на ЛЮБУЮ глубину:
+     * операторы уходят в finalFrags по своему пути (каст по типу листа из Schema),
+     * скаляры/массивы собираются в containment-поддерево (GIN).
+     * Возврат: поддерево для eqData; undefined — внутри были только операторы.
+     */
+    const walk = (path, obj) => {
+        const eq = {};
+        let hadOps = false;
+        for (const [k, v] of Object.entries(obj)) {
+            if (v === undefined)
+                continue;
+            const sub = [...path, k];
+            if (isOp(v)) {
+                out.finalFrags.push(compileOp(sub, leafType(cls, sub), v, p));
+                hadOps = true;
+            }
+            else if (isPlain(v)) {
+                const nested = walk(sub, v);
+                if (nested !== undefined)
+                    eq[k] = nested;
+                else
+                    hadOps = true;
+            }
+            else {
+                eq[k] = v;
+            }
+        }
+        if (Object.keys(eq).length)
+            return eq;
+        return hadOps ? undefined : {}; // пустой объект без операторов → containment {}
+    };
     for (const [key, value] of Object.entries(filter)) {
         if (value === undefined)
             continue;
@@ -169,29 +284,14 @@ function compileFilter(cls, filter, p) {
                 throw new Error('letopis: filter.id accepts string | string[]');
             continue;
         }
-        const ft = cls.fieldTypes.get(key);
         if (isOp(value)) {
-            out.finalFrags.push(compileOp([key], ft, value, p));
+            out.finalFrags.push(compileOp([key], cls.fieldTypes.get(key), value, p));
             continue;
         }
-        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-            // объект: операторы по вложенным путям (record) и/или containment-скаляры
-            const nestedEq = {};
-            let hasNested = false;
-            for (const [sub, sv] of Object.entries(value)) {
-                if (isOp(sv)) {
-                    const vt = ft?.kind === 'record' ? ft.value : undefined;
-                    out.finalFrags.push(compileOp([key, sub], vt, sv, p));
-                    hasNested = true;
-                }
-                else {
-                    nestedEq[sub] = sv;
-                }
-            }
-            if (Object.keys(nestedEq).length)
-                eqData[key] = nestedEq;
-            else if (!hasNested)
-                eqData[key] = value;
+        if (isPlain(value)) {
+            const nested = walk([key], value);
+            if (nested !== undefined)
+                eqData[key] = nested;
             continue;
         }
         // скаляр / массив — точное совпадение через containment (GIN)
@@ -223,19 +323,15 @@ export function resolveHop(prev, next) {
     }
     throw new Error(`letopis: LINK → LINK traversal is not supported (${prev.id} → ${next.id})`);
 }
-/** Тип листа data-пути (для каста агрегаций): 1 уровень или record-значение. */
-function cls0Field(cls, path) {
-    const ft = cls.fieldTypes.get(path[0]);
-    return path.length === 1 ? ft : ft?.kind === 'record' ? ft.value : undefined;
-}
 function sortField(alias, cls, order) {
     if (order === 'updated')
         return `${alias}.updated`;
     if (order.startsWith('data.')) {
-        const field = order.slice(5);
-        return `(${alias}.data->>'${escLit(field)}')${castOf(cls.fieldTypes.get(field))}`;
+        // data-путь любой глубины ('data.settings.booking.deposit.amount') + каст по типу листа
+        const path = order.slice(5).split('.');
+        return `(${accessor(path)(alias)})${castOf(leafType(cls, path))}`;
     }
-    throw new Error(`letopis: order must be 'updated' or 'data.<field>'`);
+    throw new Error(`letopis: order must be 'updated' or 'data.<path>'`);
 }
 function orderExpr(alias, cls, mods) {
     if (!mods.order)
@@ -249,7 +345,7 @@ function afterCond(alias, cls, mods, p) {
     if (!mods.order)
         throw new Error('letopis: .after(cursor) requires .sort(field)');
     const expr = sortField(alias, cls, mods.order);
-    const cast = mods.order === 'updated' ? '::timestamptz' : castOf(cls.fieldTypes.get(mods.order.slice(5)));
+    const cast = mods.order === 'updated' ? '::timestamptz' : castOf(leafType(cls, mods.order.slice(5).split('.')));
     const cmp = mods.desc ? '<' : '>';
     return ` WHERE (${expr}, ${alias}.id) ${cmp} (${p.push(mods.after.v)}${cast}, ${p.push(mods.after.id)})`;
 }
@@ -292,6 +388,25 @@ export function buildRead(ctx, steps, mods, mode) {
             f.candFrags.push(frag);
             f.finalFrags.push(frag);
         }
+        // enforceAcl: READ-право на КАЖДЫЙ шаг; предикат победившего правила — в WHERE заранее
+        if (ctx.aclDecide) {
+            const d = ctx.aclDecide(step.cls, 'READ');
+            if (!d.allow)
+                throw aclDenied('READ', step.cls.id, d);
+            if (d.filter) {
+                for (const fr of rowTemplateFrags(d.filter, p)) {
+                    f.candFrags.push(fr);
+                    f.finalFrags.push(fr);
+                }
+            }
+        }
+        // предикат WRITE/DELETE-правила (поиск целей записи): только свои строки
+        if (step.aclFilter) {
+            for (const fr of rowTemplateFrags(step.aclFilter, p)) {
+                f.candFrags.push(fr);
+                f.finalFrags.push(fr);
+            }
+        }
         const innerWhere = [`e.partition = ${pPart}`, `e.class = ${pCls}`];
         if (mods.asOf !== undefined)
             innerWhere.push(`e.updated <= ${p.push(mods.asOf)}::timestamptz`); // «как было на T»
@@ -404,16 +519,13 @@ export function buildRead(ctx, steps, mods, mode) {
                 throw new Error("letopis: aggregation needs field 'data.<путь>'");
             }
             const path = aggField.slice(5).split('.');
-            const acc = path.length === 1
-                ? `h${last}.data->>'${escLit(path[0])}'`
-                : `h${last}.data->'${escLit(path[0])}'->>'${escLit(path[1])}'`;
+            const acc = accessor(path)(`h${last}`); // data-путь любой глубины
             if (aggFn === 'countBy') {
                 text = `SELECT ${acc} AS k, count(*)::int AS n\n${fromClause}\nGROUP BY 1 ORDER BY 2 DESC`;
             }
             else {
-                // sum/avg — всегда numeric; min/max — по типу поля
-                const ft = cls0Field(lastCls, path);
-                const cast = aggFn === 'sum' || aggFn === 'avg' ? '::numeric' : castOf(ft);
+                // sum/avg — всегда numeric; min/max — по типу листа
+                const cast = aggFn === 'sum' || aggFn === 'avg' ? '::numeric' : castOf(leafType(lastCls, path));
                 text = `SELECT ${aggFn}((${acc})${cast}) AS v\n${fromClause}`;
             }
             break;

package/dist/tx.d.ts

@@ -3,7 +3,7 @@
  * db.commit(tr) / db.rollback(tr) / tr.commit() / tr.rollback().
  * tr.lock(...) — pg_advisory_xact_lock (сериализация гонок, напр. двойная бронь).
  */
-import type { Ctx } from './sql.js';
+import { type Ctx } from './sql.js';
 export interface TxCtx extends Ctx {
     commit(): Promise<void>;
     rollback(): Promise<void>;

package/dist/tx.js

@@ -1,3 +1,9 @@
+/**
+ * Транзакции: db.begin() → tr (тот же API на выделенном соединении),
+ * db.commit(tr) / db.rollback(tr) / tr.commit() / tr.rollback().
+ * tr.lock(...) — pg_advisory_xact_lock (сериализация гонок, напр. двойная бронь).
+ */
+import { hintTxRetry, isTransient } from './sql.js';
 export async function beginTx(ctx) {
     const reserved = await ctx.sql.reserve();
     const r = reserved;
@@ -18,6 +24,7 @@ export async function beginTx(ctx) {
         ...ctx,
         sql: reserved,
         inTx: true,
+        userTx: true,
         commit: () => finish('COMMIT'),
         rollback: () => finish('ROLLBACK'),
     };
@@ -27,5 +34,13 @@ export async function lock(ctx, ...keys) {
     if (!ctx.inTx) {
         throw new Error('letopis: lock() works only inside db.begin() transaction (pg_advisory_xact_lock)');
     }
-    await ctx.sql.unsafe('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))', [keys.join('|')]);
+    try {
+        await ctx.sql.unsafe('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))', [keys.join('|')]);
+    }
+    catch (e) {
+        // встречный порядок lock() двух транзакций → deadlock 40P01 (PG убивает одну)
+        if (isTransient(e))
+            hintTxRetry(e);
+        throw e;
+    }
 }

package/dist/types.d.ts

@@ -16,7 +16,7 @@ export interface Row {
     /** Глубина узла при .deep()-обходе (1 = прямой ребёнок). */
     $depth?: number;
 }
-/** Результат execute(): вариант пути — узел на каждый шаг цепочки. */
+/** Результат run(): вариант пути — узел на каждый шаг цепочки. */
 export type Path = Record<string, Row>;
 /** Класс из таблицы Schema. */
 export interface ClassDef {
@@ -53,6 +53,9 @@ export type FieldType = {
 } | {
     kind: 'record';
     value: FieldType;
+} | {
+    kind: 'object';
+    props: Map<string, FieldType>;
 } | {
     kind: 'any';
 };
@@ -81,6 +84,21 @@ export interface Cursor {
     v: string | number;
     id: string;
 }
+/**
+ * Операция записи, привязанная к шагу цепочки: .set() / .delete() / .anonymize().
+ * Терминал исполняет план (все операции + финальное чтение) одной транзакцией.
+ */
+export interface PlanOp {
+    kind: 'set' | 'delete' | 'anonymize';
+    /** set: данные новой версии (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 +149,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 +194,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>;