letopis 0.16.0 → 0.18.0

package/dist/up.js

@@ -5,6 +5,34 @@
  *
  *   const db = await up({ schema: 'booking', version: 1 });   // → PG-схема "v1.booking"
  */
+// FILE: lib/src/up.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Dev-bootstrap — поднять Docker-контейнер Postgres (TimescaleDB) + Redis, обеспечить базу, накатить DDL-схему и сиды, дождаться готовности и подключиться.
+//   SCOPE: валидация схемы/версии; проба postgres; docker build/run/start контейнера; создание базы; ожидание готовности PG и Redis; применение схемы + сиды; connect
+//   DEPENDS: M-CONNECT, M-CHAIN, M-TYPES
+//   LINKS: M-UP, V-M-UP
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   UpOpts - опции up(): dsn, schema, version, контейнер/образ, dataDir, seeds, fresh, quiet, таймаут
+//   dockerRunArgs - чистая сборка argv для `docker run` (bind/volume, trust/пароль)
+//   RunCfg - конфиг запуска контейнера (порты, креды, база, dataDir)
+//   up - точка входа: контейнер -> база -> схема -> готовность -> connect (возвращает EntityDb)
+//   docker - (local) обёртка execFile над docker CLI (ENOENT -> понятная ошибка)
+//   ensureContainer - (local) reuse/start/build+run dev-контейнера
+//   pgPing - (local) проба postgres: ok | no-server | no-database | starting | fatal
+//   ensureDatabase - (local) создать базу, если её нет (гонка 42P04 глушится)
+//   tcpAlive - (local) TCP-проба хоста:порта (для redis)
+//   applySchema - (local) drop (fresh) -> накат ddl+сидов с подстановкой <SCHEMA-NAME>
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
+//
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { setTimeout as sleep } from 'node:timers/promises';
@@ -19,6 +47,13 @@ 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. */
+// START_CONTRACT: dockerRunArgs
+//   PURPOSE: Чистая функция — собирает argv для `docker run` dev-контейнера (порты PG/Redis, том данных, режим trust либо пароль).
+//   INPUTS: { cfg: RunCfg - контейнер/образ, порты, креды, база, dataDir (путь -> bind, имя -> volume) }
+//   OUTPUTS: { string[] - аргументы командной строки docker run }
+//   SIDE_EFFECTS: none
+//   LINKS: M-UP, V-M-UP
+// END_CONTRACT: dockerRunArgs
 export function dockerRunArgs(cfg) {
     const args = ['run', '-d', '--name', cfg.container,
         '-p', `${cfg.pgPort}:5432`, '-p', `${cfg.redisPort}:6379`,
@@ -42,6 +77,13 @@ async function docker(args) {
         return { ok: false, out: (x.stdout ?? '').trim(), err: (x.stderr || x.message || '').trim() };
     }
 }
+// START_CONTRACT: ensureContainer
+//   PURPOSE: Гарантирует запущенный dev-контейнер — reuse запущенного, start остановленного, иначе build образа (если нет) и run.
+//   INPUTS: { cfg: RunCfg - параметры контейнера/образа/портов; log: (m: string) => void - прогресс }
+//   OUTPUTS: { Promise<void> }
+//   SIDE_EFFECTS: вызывает docker inspect/start/build/run через execFile; бросает при неудаче start/build/run
+//   LINKS: M-UP, V-M-UP
+// END_CONTRACT: ensureContainer
 async function ensureContainer(cfg, log) {
     const st = await docker(['container', 'inspect', '--format', '{{.State.Running}}', cfg.container]);
     if (st.ok && st.out === 'true') {
@@ -68,6 +110,13 @@ async function ensureContainer(cfg, log) {
         throw new Error(`letopis.up: docker run ${cfg.container} failed: ${r.err}`);
     log(`container ${cfg.container} created (data: ${cfg.dataDir ?? 'volume letopis-pgdata'})`);
 }
+// START_CONTRACT: pgPing
+//   PURPOSE: Одноразовая проба postgres по dsn — классифицирует ответ: ok, no-database (3D000), starting (57P03), fatal (28P01/28000), no-server.
+//   INPUTS: { dsn: string - строка подключения }
+//   OUTPUTS: { Promise<Ping> - { ok: true } | { ok: false, kind, err } }
+//   SIDE_EFFECTS: открывает и закрывает разовое соединение postgres (max 1, connect_timeout 3)
+//   LINKS: M-UP, V-M-UP
+// END_CONTRACT: pgPing
 async function pgPing(dsn) {
     const sql = postgres(dsn, { max: 1, connect_timeout: 3, onnotice: () => { } });
     try {
@@ -88,6 +137,13 @@ async function pgPing(dsn) {
         await sql.end({ timeout: 1 }).catch(() => { });
     }
 }
+// START_CONTRACT: ensureDatabase
+//   PURPOSE: Создаёт целевую базу, если её ещё нет — подключаясь к служебной базе postgres (гонку параллельных up() 42P04 глушит).
+//   INPUTS: { url: URL - разобранный dsn (имя базы из pathname/username); log: (m: string) => void }
+//   OUTPUTS: { Promise<void> }
+//   SIDE_EFFECTS: подключается к базе postgres, выполняет CREATE DATABASE; закрывает соединение
+//   LINKS: M-UP, V-M-UP
+// END_CONTRACT: ensureDatabase
 async function ensureDatabase(url, log) {
     const dbName = decodeURIComponent(url.pathname.slice(1)) || url.username || 'postgres';
     const admin = new URL(url);
@@ -107,6 +163,13 @@ async function ensureDatabase(url, log) {
         await sql.end();
     }
 }
+// START_CONTRACT: tcpAlive
+//   PURPOSE: TCP-проба доступности хоста:порта (готовность Redis) с таймаутом 2 с.
+//   INPUTS: { host: string; port: number }
+//   OUTPUTS: { Promise<boolean> - true если соединение установилось }
+//   SIDE_EFFECTS: открывает и сразу закрывает TCP-сокет
+//   LINKS: M-UP, V-M-UP
+// END_CONTRACT: tcpAlive
 function tcpAlive(host, port) {
     return new Promise((res) => {
         const s = net.connect({ host, port });
@@ -116,6 +179,13 @@ function tcpAlive(host, port) {
         s.setTimeout(2000, () => done(false));
     });
 }
+// START_CONTRACT: applySchema
+//   PURPOSE: Применяет DDL-схему и сиды — при fresh дропает схему; если схемы нет, накатывает ddl.sql (+ дефолтные booking/auth или свои сиды), подставляя <SCHEMA-NAME>.
+//   INPUTS: { dsn: string; full: string - полное имя схемы v<N>.<schema>; seeds: string[] | false | undefined - свои пути / false (без сидов) / undefined (дефолт); fresh: boolean; log: (m: string) => void }
+//   OUTPUTS: { Promise<void> }
+//   SIDE_EFFECTS: читает sql-файлы; выполняет DROP/накат схемы в postgres; закрывает соединение
+//   LINKS: M-UP, V-M-UP
+// END_CONTRACT: applySchema
 async function applySchema(dsn, full, seeds, fresh, log) {
     const sql = postgres(dsn, { max: 1, onnotice: () => { } });
     try {
@@ -143,6 +213,13 @@ async function applySchema(dsn, full, seeds, fresh, log) {
         await sql.end();
     }
 }
+// START_CONTRACT: up
+//   PURPOSE: Единая точка входа dev-bootstrap — валидирует схему/версию, при живом postgres пропускает docker (иначе поднимает контейнер и ждёт готовности PG+Redis), применяет схему и подключается.
+//   INPUTS: { opts: UpOpts - dsn, schema, version, контейнер/образ, dataDir, redisPort, seeds, fresh, quiet, waitTimeoutMs + прочие ConnectOpts }
+//   OUTPUTS: { Promise<EntityDb> - подключённый фасад на схеме "v<version>.<schema>" }
+//   SIDE_EFFECTS: shell docker через M-UP.ensureContainer; TCP-пинги; чтение sql и накат схемы; console.log с префиксом [letopis.up]; connect (M-CONNECT); бросает при плохом имени схемы/версии и таймауте готовности
+//   LINKS: M-UP, V-M-UP
+// END_CONTRACT: up
 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))
@@ -166,6 +243,7 @@ export async function up(opts) {
         throw ping.err;
     }
     else {
+        // START_BLOCK_ENSURE_CONTAINER
         if (local) {
             await ensureContainer({
                 container, image, pgPort: url.port || '5432', redisPort,
@@ -176,6 +254,8 @@ export async function up(opts) {
         else {
             log(`waiting for remote postgres at ${host} (no docker for non-local dsn)…`);
         }
+        // END_BLOCK_ENSURE_CONTAINER
+        // START_BLOCK_WAIT_READY
         const t0 = Date.now();
         for (;;) {
             ping = await pgPing(dsn);
@@ -201,9 +281,12 @@ export async function up(opts) {
             }
             log(`redis ready on ${redisPort}`);
         }
+        // END_BLOCK_WAIT_READY
     }
+    // START_BLOCK_APPLY_SCHEMA
     await applySchema(dsn, full, seeds, fresh ?? false, log);
     const db = await connect({ ...connectRest, dsn, schema: full });
     log(`connected (schema "${full}")`);
+    // END_BLOCK_APPLY_SCHEMA
     return db;
 }

package/dist/uuid.js

@@ -6,6 +6,28 @@
  *     детерминированный id из концов/полей: та же комбинация → тот же id (идемпотентный create,
  *     дубль невозможен даже в гонке — оба запроса вычислят один id, второй станет версией).
  */
+//
+// FILE: lib/src/uuid.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Детерминированная (v5) и упорядоченная по времени (v7) генерация UUID для id сущностей.
+//   SCOPE: namespace-константа LETOPIS_NS, форматирование 16 байт в каноничный UUID, v5 (sha1 от namespace+name), v7 (unix-ms в старших битах + random).
+//   DEPENDS: none
+//   LINKS: M-UUID, V-M-UUID
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   LETOPIS_NS - фиксированный namespace letopis для uuidv5 (стабильность id между релизами).
+//   fmt - (локальная) форматирует 16-байтный Buffer в каноничную строку UUID 8-4-4-4-12.
+//   uuidv5 - RFC 4122 v5: детерминированный uuid = sha1(namespace + name).
+//   uuidv7 - RFC 9562 v7: 48 бит unix-ms в старших битах + random.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
 import { createHash, randomBytes } from 'node:crypto';
 /** Namespace letopis для uuidv5 (фиксированная константа — стабильность id между релизами). */
 export const LETOPIS_NS = 'c7a2f9d4-3b61-4e8a-9f05-8d2c1e6b7a90';
@@ -13,6 +35,13 @@ 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)}`;
 };
+// START_CONTRACT: uuidv5
+//   PURPOSE: Детерминированный UUID v5 из имени и namespace (одно имя → один uuid).
+//   INPUTS: { name: string - имя (склеенные значения from класса), ns: string - namespace (default LETOPIS_NS) }
+//   OUTPUTS: { string - каноничный UUID v5 (version=5, variant=10xx) }
+//   SIDE_EFFECTS: none (чистая функция — только хэширование входа)
+//   LINKS: M-UUID, V-M-UUID
+// END_CONTRACT: uuidv5
 /** RFC 4122 v5: sha1(namespace + name); детерминирован — одно имя → один uuid. */
 export function uuidv5(name, ns = LETOPIS_NS) {
     const nsBytes = Buffer.from(ns.replace(/-/g, ''), 'hex');
@@ -21,6 +50,13 @@ export function uuidv5(name, ns = LETOPIS_NS) {
     h[8] = (h[8] & 0x3f) | 0x80; // variant 10xx
     return fmt(h);
 }
+// START_CONTRACT: uuidv7
+//   PURPOSE: Упорядоченный по времени UUID v7 — 48 бит unix-ms в старших битах + random.
+//   INPUTS: { none }
+//   OUTPUTS: { string - каноничный UUID v7 (version=7, variant=10xx) }
+//   SIDE_EFFECTS: недетерминирован — читает Date.now() и криптослучайные байты (randomBytes)
+//   LINKS: M-UUID, V-M-UUID
+// END_CONTRACT: uuidv7
 /** RFC 9562 v7: 48 бит unix-ms + random — время в старших битах, вставки ложатся в хвост индекса. */
 export function uuidv7() {
     const b = Buffer.alloc(16);

package/dist/write.js

@@ -14,10 +14,41 @@
  *           .Запись().delete({ confirm: true }).rows()        // сегмент 2: снести записи каждого
  * Продолжение после операции идёт ОТ ЕЁ РЕЗУЛЬТАТА (fan-out по записанным строкам).
  */
+//
+// FILE: lib/src/write.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Write-side движок: валидация, резолв концов/слотов, вычисление id (v5/v7), вставка новых версий, каскадное удаление, анонимизация, исполнение планов и батчей в транзакции.
+//   SCOPE: ValidationError, runPlan, executeBatch, createOp/updateOp/delOp/anonymizeOp, toRow/readRows/deepMerge, BatchPlan.
+//   DEPENDS: M-UUID, M-TYPES, M-SQL, M-ACL
+//   LINKS: M-WRITE, V-M-WRITE
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   ValidationError - ошибка валидации с полями issues
+//   toRow/readRows/deepMerge - нормализация строки, чтение, deep-merge патча
+//   createOp/updateOp/anonymizeOp/delOp - операции записи (create/update/anonymize/delete)
+//   runPlan - исполнить план (сегменты op + читающий хвост) одной транзакцией
+//   executeBatch - исполнить очередь планов (fast-path multi-insert для чистых INSERT)
+//   BatchPlan/PlanMode - модель плана батча и режимы чтения
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
 import { randomUUID } from 'node:crypto';
 import { uuidv5, uuidv7 } from './uuid.js';
 import { buildRead, runQuery, insertSql, multiInsertSql, deleteSql, closureSql, isTransient, retryDelay, RETRIES, } from './sql.js';
 import { aclDenied } from './acl.js';
+// START_CONTRACT: ValidationError
+//   PURPOSE: Ошибка валидации класса, несущая список проблемных полей (issues).
+//   INPUTS: { cls: string; issues: {field, message?}[] }
+//   OUTPUTS: { Error - message с перечнем «поле — сообщение» }
+//   SIDE_EFFECTS: none
+//   LINKS: M-WRITE, V-M-WRITE
+// END_CONTRACT: ValidationError
 export class ValidationError extends Error {
     issues;
     constructor(cls, issues) {
@@ -59,6 +90,14 @@ export function deepMerge(base, patch) {
     }
     return out;
 }
+// START_CONTRACT: validate
+//   PURPOSE: Проверить данные по fastest-validator (строго, + id) и концы LINK; вернуть очищенные данные.
+//   INPUTS: { cls: ClassDef; id: string; data: object; links: object }
+//   OUTPUTS: { object - валидные данные (без id) }
+//   SIDE_EFFECTS: none
+//   ERRORS: class is abstract; ValidationError; link requires end; stray link(s)
+//   LINKS: M-WRITE, V-M-WRITE, M-SCHEMA
+// END_CONTRACT: validate
 /** Валидация данных по fastest-validator (строгая, + id) и концов LINK. */
 function validate(cls, id, data, links) {
     if (cls.abstract)
@@ -68,6 +107,7 @@ function validate(cls, id, data, links) {
     if (res !== true)
         throw new ValidationError(cls.id, res);
     delete merged.id;
+    // START_BLOCK_VALIDATE_LINK_ENDS
     if (cls.category === 'LINK') {
         const present = new Set(Object.keys(links));
         if (cls.strictEnds) {
@@ -101,8 +141,16 @@ function validate(cls, id, data, links) {
             }
         }
     }
+    // END_BLOCK_VALIDATE_LINK_ENDS
     return merged;
 }
+// START_CONTRACT: insertOne
+//   PURPOSE: INSERT одной строки-версии с ретраем гонок (23505 коллизия updated, 40P01/40001 transient) вне транзакции.
+//   INPUTS: { ctx: Ctx; a: InsertArgs }
+//   OUTPUTS: { Promise<Row> - вставленная строка }
+//   SIDE_EFFECTS: INSERT в Entity через runQuery
+//   LINKS: M-WRITE, V-M-WRITE, M-SQL, M-DDL
+// END_CONTRACT: insertOne
 /** INSERT одной строки с ретраем гонок: 23505 (коллизия updated) и transient (40P01/40001). */
 async function insertOne(ctx, a) {
     // jsonb-параметры — JS-объектами (postgres.js сериализует сам)
@@ -110,6 +158,7 @@ async function insertOne(ctx, a) {
         ctx.partition, a.id, a.cls.id, a.data, a.links, a.tags,
         a.account, a.owner, a.prevUpdated, a.deleted,
     ];
+    // START_BLOCK_INSERT_ONE_RETRY
     for (let attempt = 1;; attempt++) {
         try {
             const res = await runQuery(ctx, insertSql(ctx.pgSchema), params, 'insert', [a.cls.id]);
@@ -128,6 +177,7 @@ async function insertOne(ctx, a) {
             throw e;
         }
     }
+    // END_BLOCK_INSERT_ONE_RETRY
 }
 /**
  * enforceAcl: право операции на класс цели. Предикат победившего правила:
@@ -136,6 +186,14 @@ async function insertOne(ctx, a) {
  *    (явный чужой модификатор на цепочке → ошибка).
  * Мутирует step (объект создаётся цепочкой на вызов — локально безопасно).
  */
+// START_CONTRACT: aclWrite
+//   PURPOSE: enforceAcl-проверка права записи/удаления на класс цели; предикат правила пришпиливает owner/account и фильтрует цели.
+//   INPUTS: { ctx: Ctx; step: Step; op: 'WRITE'|'DELETE' }
+//   OUTPUTS: { void - мутирует step (aclFilter/ownerFilter/accountFilter) }
+//   SIDE_EFFECTS: мутирует step
+//   ERRORS: acl denies WRITE/DELETE; acl pins writes to owner/account
+//   LINKS: M-WRITE, V-M-WRITE, M-ACL
+// END_CONTRACT: aclWrite
 function aclWrite(ctx, step, op) {
     if (!ctx.aclDecide)
         return;
@@ -188,6 +246,14 @@ function endFor(target, cls) {
  * target, обязан дать ровно одну сущность (id-фильтр — как есть; иначе чтение путём
  * от начала до него: контекст честно учитывается).
  */
+// START_CONTRACT: resolvePathEnds
+//   PURPOSE: Связи создаваемой сущности из пути: каждый шаг-предок, чей класс — конец target, должен дать ровно одну сущность.
+//   INPUTS: { ctx: Ctx; steps: Step[] }
+//   OUTPUTS: { Promise<Record<string,string>> - класс конца → id }
+//   SIDE_EFFECTS: чтения контекста (readRows)
+//   ERRORS: context step must resolve to exactly one entity
+//   LINKS: M-WRITE, V-M-WRITE
+// END_CONTRACT: resolvePathEnds
 async function resolvePathEnds(ctx, steps) {
     const target = steps[steps.length - 1].cls;
     const links = {};
@@ -213,6 +279,14 @@ async function resolvePathEnds(ctx, steps) {
     return links;
 }
 /** Резолв слот-значений: строки как есть; вложенные планы — в той же транзакции, ровно одна сущность. */
+// START_CONTRACT: resolveSlots
+//   PURPOSE: Резолв слот-значений (.Класс.set/.unset): строки как есть, вложенные планы — та же транзакция и ровно одна сущность; союз-конец снимается целиком.
+//   INPUTS: { ctx: Ctx; target: ClassDef; extra: Step['extraLinks'] }
+//   OUTPUTS: { Promise<{ vals: Record<string,string>; drops: Set<string> }> }
+//   SIDE_EFFECTS: может исполнять вложенные планы/чтения
+//   ERRORS: slot value plan must resolve to exactly one entity; resolved to class "<x>"
+//   LINKS: M-WRITE, V-M-WRITE
+// END_CONTRACT: resolveSlots
 async function resolveSlots(ctx, target, extra) {
     const vals = {};
     const drops = new Set();
@@ -245,11 +319,36 @@ async function resolveSlots(ctx, target, extra) {
 }
 /** id новой сущности по IdGen класса (v5 считается отдельно — нужны концы/данные). */
 const genId = (cls) => (cls.idGen.version === 7 ? uuidv7() : randomUUID());
+/**
+ * default поля из правила Schema.attributes: объект-правило `{default: …}` или
+ * DSL-строка `'string|default:базовая'`. Нужен v5Id: id считается ДО валидации (та
+ * подставляет defaults позже), поэтому необязательное from-поле берёт дефолт здесь.
+ */
+function defaultOf(rule) {
+    if (rule && typeof rule === 'object' && !Array.isArray(rule) && 'default' in rule) {
+        return rule.default;
+    }
+    if (typeof rule === 'string') {
+        const seg = rule.split('|').map((s) => s.trim()).find((s) => s.startsWith('default:'));
+        if (seg)
+            return seg.slice('default:'.length);
+    }
+    return undefined;
+}
 /**
  * Детерминированный id (uuid v5): имя = «схема:партиция:класс:значения from».
  * from-источник — конец Schema.links (класс или полное имя союза 'Service|Complex';
- * значение — id присутствующего класса конца) или скалярное поле data.
+ * значение — id присутствующего класса конца) или скалярное поле data (если не задано —
+ * его default из Schema.attributes: id стабилен и без явного ввода необязательного поля).
  */
+// START_CONTRACT: v5Id
+//   PURPOSE: Детерминированный id (uuid v5) из «схема:партиция:класс:значения from» (концы Schema.links или скалярные поля/дефолты).
+//   INPUTS: { ctx: Ctx; cls: ClassDef; links: object; data: object }
+//   OUTPUTS: { string - uuid v5 }
+//   SIDE_EFFECTS: none
+//   ERRORS: needs end "<...>"; needs scalar data field "<f>"
+//   LINKS: M-WRITE, V-M-WRITE, M-UUID
+// END_CONTRACT: v5Id
 function v5Id(ctx, cls, links, data) {
     const parts = [];
     for (const f of cls.idGen.from) {
@@ -262,7 +361,7 @@ function v5Id(ctx, cls, links, data) {
             parts.push(links[hit]);
         }
         else {
-            const v = data[f];
+            const v = data[f] === undefined ? defaultOf(cls.attributes[f]) : data[f];
             if (v === undefined || v === null || typeof v === 'object') {
                 throw new Error(`letopis: id (uuid v5) of "${cls.id}" needs scalar data field "${f}"`);
             }
@@ -297,7 +396,16 @@ async function versionRows(ctx, target, found, data, slots) {
  *    нет → INSERT с этим id (идемпотентный create, REST-PUT семантика);
  *  - фильтр-объект / pivot — ошибка: create не ищет, это update().
  */
+// START_CONTRACT: createOp
+//   PURPOSE: .create(data) — INSERT новой сущности либо новая версия при известном/вычисленном id (идемпотентный create); поиск — это update().
+//   INPUTS: { ctx: Ctx; steps: Step[]; mods: ChainMods; data: object }
+//   OUTPUTS: { Promise<Row[]> }
+//   SIDE_EFFECTS: INSERT в Entity (в транзакции runPlan)
+//   ERRORS: create() on a pivot; takes no filter; got two ids; computes id (remove explicit); acl denies WRITE
+//   LINKS: M-WRITE, V-M-WRITE, M-ACL
+// END_CONTRACT: createOp
 export async function createOp(ctx, steps, mods, data) {
+    // START_BLOCK_CREATE_RESOLVE
     const target = steps[steps.length - 1];
     const cls = target.cls;
     aclWrite(ctx, target, 'WRITE');
@@ -361,12 +469,20 @@ export async function createOp(ctx, steps, mods, data) {
             tags: tagsValue(target) ?? [], account, owner, prevUpdated: null, deleted: null,
         }),
     ];
+    // END_BLOCK_CREATE_RESOLVE
 }
 /**
  * .update(data?) — новая версия КАЖДОГО найденного путём (deep-merge листьев);
  * цели: Класс() ≡ Класс({}) — все в границах контекста, id/фильтр/pivot — как в чтении.
  * Не найдено → [] — update НИКОГДА не создаёт.
  */
+// START_CONTRACT: updateOp
+//   PURPOSE: .update(data?) — новая версия каждого найденного путём (deep-merge листьев); никогда не создаёт.
+//   INPUTS: { ctx: Ctx; steps: Step[]; mods: ChainMods; data: object }
+//   OUTPUTS: { Promise<Row[]> }
+//   SIDE_EFFECTS: INSERT новых версий
+//   LINKS: M-WRITE, V-M-WRITE
+// END_CONTRACT: updateOp
 export async function updateOp(ctx, steps, mods, data) {
     const target = steps[steps.length - 1];
     aclWrite(ctx, target, 'WRITE');
@@ -411,6 +527,7 @@ export async function anonymizeOp(ctx, steps, mods, fields) {
 async function inTransaction(ctx, fn) {
     if (ctx.inTx)
         return fn(ctx);
+    // START_BLOCK_IN_TRANSACTION_RETRY
     for (let attempt = 1;; attempt++) {
         try {
             return (await ctx.sql.begin(async (tsql) => fn({ ...ctx, sql: tsql, inTx: true })));
@@ -423,6 +540,7 @@ async function inTransaction(ctx, fn) {
             throw e;
         }
     }
+    // END_BLOCK_IN_TRANSACTION_RETRY
 }
 /**
  * .delete({confirm}): цели = фильтр последнего шага + контекст-связи.
@@ -430,6 +548,14 @@ async function inTransaction(ctx, fn) {
  * каскад + advisory-lock); возвращает ВСЁ удалённое (цели + каскад) с $deleted: true.
  * Без confirm — ПРЕВЬЮ: то же замыкание (цели + каскад), но БД не трогается.
  */
+// START_CONTRACT: delOp
+//   PURPOSE: .delete({confirm}) — серверное удаление (tombstone + рекурсивный каскад) при confirm, иначе превью замыкания; DELETE-право на каждый класс каскада.
+//   INPUTS: { ctx: Ctx; steps: Step[]; mods: ChainMods; confirm: boolean }
+//   OUTPUTS: { Promise<Row[]> - удалённые (цели+каскад) с $deleted, либо превью }
+//   SIDE_EFFECTS: DELETE в Entity (триггер entity_delete) при confirm
+//   ERRORS: acl denies DELETE (в каскаде)
+//   LINKS: M-WRITE, V-M-WRITE, M-ACL, M-DDL
+// END_CONTRACT: delOp
 export async function delOp(ctx, steps, mods, confirm) {
     const target = steps[steps.length - 1];
     aclWrite(ctx, target, 'DELETE');
@@ -437,6 +563,7 @@ export async function delOp(ctx, steps, mods, confirm) {
     if (!targets.length)
         return [];
     const params = [ctx.partition, target.cls.id, ...targets.map((r) => r.id)];
+    // START_BLOCK_DELETE_CASCADE
     return inTransaction(ctx, async (c) => {
         const closure = await runQuery(c, closureSql(c.pgSchema, targets.length), params, 'delete', [target.cls.id]);
         if (!confirm)
@@ -452,6 +579,7 @@ export async function delOp(ctx, steps, mods, confirm) {
         await runQuery(c, deleteSql(c.pgSchema, targets.length), params, 'delete', [target.cls.id]);
         return closure.map((r) => ({ ...toRow(r), $deleted: true }));
     });
+    // END_BLOCK_DELETE_CASCADE
 }
 /** Разрезать план: сегменты (…шаги + op-шаг) и читающий хвост после последней операции. */
 function splitPlan(steps) {
@@ -495,9 +623,17 @@ const RawRowFmt = {
  * строки результата (контекст = строка); self-шаг (op сразу после op) пишет в те же строки.
  * После delete продолжение идёт от строк КЛАССА ЦЕЛИ (замыкание каскада шире).
  */
+// START_CONTRACT: runPlan
+//   PURPOSE: Исполнить план целиком (сегменты операций + читающий хвост) одной транзакцией; продолжение = fan-out по строкам результата.
+//   INPUTS: { ctx: Ctx; steps: Step[]; mods: ChainMods; mode: PlanMode }
+//   OUTPUTS: { Promise<unknown> - результат в запрошенном режиме }
+//   SIDE_EFFECTS: записи + чтения в одной транзакции
+//   LINKS: M-WRITE, V-M-WRITE, M-SQL
+// END_CONTRACT: runPlan
 export async function runPlan(ctx, steps, mods, mode) {
     const { segments, tail } = splitPlan(steps);
     return inTransaction(ctx, async (c) => {
+        // START_BLOCK_RUNPLAN_SEGMENTS
         let last = []; // полный результат последней операции (для терминала)
         let start = []; // строки для продолжения (класс цели)
         for (let i = 0; i < segments.length; i++) {
@@ -517,6 +653,7 @@ export async function runPlan(ctx, steps, mods, mode) {
             }
             start = seg.op.kind === 'delete' ? last.filter((r) => r.class === targetCls.id) : last;
         }
+        // END_BLOCK_RUNPLAN_SEGMENTS
         const opStep = segments[segments.length - 1].steps.at(-1);
         const keyName = opStep.aliasKey ?? opStep.name;
         // хвост-чтение от результата последней операции (в той же транзакции)
@@ -595,6 +732,13 @@ const isPureInsertPlan = (p) => p.steps.length === 1 &&
     typeof p.steps[0].op.data?.id !== 'string' &&
     !Object.keys(p.steps[0].extraLinks ?? {}).length &&
     p.steps[0].cls.idGen.version !== 5;
+// START_CONTRACT: executeBatch
+//   PURPOSE: Исполнить очередь планов одной транзакцией; подряд идущие чистые INSERT одного класса склеиваются в multi-VALUES.
+//   INPUTS: { ctx: Ctx; queue: BatchPlan[] }
+//   OUTPUTS: { Promise<Row[][]> - результат по каждому плану }
+//   SIDE_EFFECTS: INSERT (multi/по-плану) в транзакции
+//   LINKS: M-WRITE, V-M-WRITE, M-SQL
+// END_CONTRACT: executeBatch
 export async function executeBatch(ctx, queue) {
     if (!queue.length)
         return [];
@@ -602,6 +746,7 @@ export async function executeBatch(ctx, queue) {
         const results = new Array(queue.length);
         let i = 0;
         while (i < queue.length) {
+            // START_BLOCK_BATCH_FASTPATH
             if (isPureInsertPlan(queue[i])) {
                 const cls = queue[i].steps[0].cls;
                 let j = i;
@@ -623,6 +768,7 @@ export async function executeBatch(ctx, queue) {
                 i = j;
                 continue;
             }
+            // END_BLOCK_BATCH_FASTPATH
             results[i] = (await runPlan(c, queue[i].steps, {}, 'rows'));
             i++;
         }

package/docker/Dockerfile

@@ -4,6 +4,28 @@
 #   docker run -d --name letopis-timescale -p 15432:5432 -p 16379:6379 \
 #     -v letopis-pgdata:/var/lib/postgresql/data \
 #     -e POSTGRES_PASSWORD=test -e POSTGRES_DB=letopis letopis-db
+# FILE: lib/docker/Dockerfile
+# VERSION: 1.0.0
+# START_MODULE_CONTRACT
+#   PURPOSE: Dev-образ БД — TimescaleDB pg17 + Redis в одном контейнере (для letopis.up()).
+#   SCOPE: базовый образ, установка redis, копирование start.sh, EXPOSE 5432/6379, entrypoint.
+#   DEPENDS: none
+#   LINKS: M-DOCKER, V-M-DOCKER
+#   ROLE: CONFIG
+#   MAP_MODE: SUMMARY
+# END_MODULE_CONTRACT
+#
+# START_MODULE_MAP
+#   FROM timescale/timescaledb:latest-pg17 - база (PostgreSQL 17 + TimescaleDB)
+#   apk add redis - Redis в тот же образ
+#   ENTRYPOINT start-letopis.sh - запуск redis + postgres
+# END_MODULE_MAP
+#
+# START_CHANGE_SUMMARY
+#   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+# END_CHANGE_SUMMARY
+
+# START_BLOCK_IMAGE_BUILD
 FROM timescale/timescaledb:latest-pg17
 
 RUN apk add --no-cache redis
@@ -15,3 +37,4 @@ EXPOSE 5432 6379
 
 ENTRYPOINT ["/usr/local/bin/start-letopis.sh"]
 CMD ["postgres"]
+# END_BLOCK_IMAGE_BUILD

package/docker/start.sh

@@ -1,4 +1,18 @@
 #!/bin/sh
+# FILE: lib/docker/start.sh
+# VERSION: 1.0.0
+# START_MODULE_CONTRACT
+#   PURPOSE: Entrypoint dev-контейнера — поднять Redis фоном, затем штатный postgres docker-entrypoint.
+#   SCOPE: redis-server (daemonize) + exec docker-entrypoint.sh.
+#   DEPENDS: none
+#   LINKS: M-DOCKER, V-M-DOCKER
+#   ROLE: SCRIPT
+#   MAP_MODE: NONE
+# END_MODULE_CONTRACT
+#
+# START_CHANGE_SUMMARY
+#   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+# END_CHANGE_SUMMARY
 # Redis фоном (dev: без пароля и персиста — сессии эфемерны), затем штатный entrypoint postgres.
 redis-server --port 6379 --bind 0.0.0.0 --protected-mode no --save '' --appendonly no --daemonize yes
 exec docker-entrypoint.sh "$@"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letopis",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Letopis (летопись): append-only versioned entity store on TimescaleDB with dot-notation chains — every change is a new row, history is first-class (asOf, versions, watch, cascade tombstones)",
   "keywords": [
     "timescaledb",