letopis 0.13.0 → 0.18.0

package/dist/chain.js

@@ -1,10 +1,17 @@
-import { buildRead, runQuery, leafType } from './sql.js';
+import { buildRead, runQuery, leafType, resolveHop, nextNodeKey, } from './sql.js';
 import { runPlan, executeBatch, toRow } from './write.js';
 import { beginTx, lock } from './tx.js';
 import { makeTables } from './tables.js';
 import { makeAuth } from './auth.js';
 import { makeAcl } from './acl.js';
 /** Фильтр-аргумент принимает и Row/Account-объект — берётся его id. */
+// START_CONTRACT: normalizeFilter
+//   PURPOSE: Нормализует фильтр-аргумент — Row/Account-объект сворачивается в свой id.
+//   INPUTS: { f: Filter | undefined - id-строка, объект-предикат, массив либо Row/Account }
+//   OUTPUTS: { Filter | undefined - id-строка для Row/Account, иначе исходный фильтр }
+//   SIDE_EFFECTS: none
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: normalizeFilter
 function normalizeFilter(f) {
     if (f !== undefined &&
         typeof f === 'object' &&
@@ -16,7 +23,74 @@ function normalizeFilter(f) {
     return f;
 }
 const clsOf = (steps) => steps.map((s) => s.cls.id);
+/** Внутренний канал: план чужой ленивой цепочки (слот-значения, entity()). */
+export const PLAN = Symbol('letopis.plan');
+const peekPlan = (x) => x !== null && typeof x === 'object' ? x[PLAN] : undefined;
+/** Конец схемы владельца, принимающий класс слота (legacy: 'Entity'-конец берёт любой HUB). */
+// START_CONTRACT: findEnd
+//   PURPOSE: Находит конец Schema.links владельца, принимающий класс слота (legacy: конец 'Entity' берёт любой HUB при нестрогих концах).
+//   INPUTS: { owner: ClassDef - класс-владелец связей; slot: ClassDef - класс устанавливаемого конца }
+//   OUTPUTS: { LinkEnd | undefined - подходящий конец связи или undefined }
+//   SIDE_EFFECTS: none
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: findEnd
+function findEnd(owner, slot) {
+    return owner.links.find((e) => e.classes.includes(slot.id) || (!owner.strictEnds && e.classes.includes('Entity') && slot.category === 'HUB'));
+}
+/** Значение слота: id-строка | Row | цепочка (одношаговый адрес сворачивается в id). */
+// START_CONTRACT: slotValue
+//   PURPOSE: Приводит значение слота к SlotValue — id-строка, Row (берётся id) или ленивая цепочка (одношаговый адрес db.Класс(id) сворачивается в id, иначе вложенный план).
+//   INPUTS: { slotCls: ClassDef - класс конца связи; v: unknown - id | Row | Chain }
+//   OUTPUTS: { SlotValue - id-строка либо { plan, mods } вложенной цепочки }
+//   SIDE_EFFECTS: бросает при цепочке чужого класса или неподдержанном значении
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: slotValue
+function slotValue(slotCls, v) {
+    if (typeof v === 'string')
+        return v;
+    const plan = peekPlan(v);
+    if (plan) {
+        const [head] = plan.steps;
+        if (plan.steps.length === 1 && !head.op && typeof head.filter === 'string') {
+            if (head.cls.id !== slotCls.id) {
+                throw new Error(`letopis: slot "${slotCls.id}" got a chain of class "${head.cls.id}"`);
+            }
+            return head.filter; // просто адрес db.Класс(id) — без вложенного исполнения
+        }
+        return { plan: plan.steps, mods: plan.mods };
+    }
+    if (v !== null && typeof v === 'object' && typeof v.id === 'string') {
+        return v.id; // Row / Account
+    }
+    throw new Error(`letopis: slot "${slotCls.id}" accepts an id, a Row or a chain`);
+}
+/** Узел для pivot: последний реальный шаг класса cls в ТЕКУЩЕМ читающем сегменте (до op). */
+// START_CONTRACT: pivotNodeOf
+//   PURPOSE: Ищет последний реальный шаг класса cls в текущем читающем сегменте (до первой операции) — узел для pivot-возврата.
+//   INPUTS: { steps: Step[] - шаги цепочки; cls: ClassDef - искомый класс }
+//   OUTPUTS: { Step | undefined - шаг-узел, либо undefined если операция закрыла паттерн }
+//   SIDE_EFFECTS: none
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: pivotNodeOf
+function pivotNodeOf(steps, cls) {
+    for (let i = steps.length - 1; i >= 0; i--) {
+        const s = steps[i];
+        if (s.op)
+            return undefined; // операция закрывает паттерн — узлы до неё недоступны
+        if (s.pivotKey === undefined && s.cls.id === cls.id)
+            return s;
+    }
+    return undefined;
+}
+// START_CONTRACT: runPaths
+//   PURPOSE: Исполняет читающий план в режиме путей — строит SQL через buildRead и мапит строки в Path (узлы каждого варианта).
+//   INPUTS: { ctx: Ctx - контекст соединения/схемы; steps: Step[] - шаги; mods: ChainMods - модификаторы }
+//   OUTPUTS: { Promise<Path[]> - массив путей вида { ключ_шага: Row } }
+//   SIDE_EFFECTS: читает БД через M-SQL.buildRead/runQuery
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: runPaths
 async function runPaths(ctx, steps, mods) {
+    // START_BLOCK_RUN_PATHS
     const q = buildRead(ctx, steps, mods, 'paths');
     const res = await runQuery(ctx, q.text, q.params, 'paths', clsOf(steps));
     return res.map((r) => {
@@ -25,8 +99,17 @@ async function runPaths(ctx, steps, mods) {
             out[k] = toRow(v);
         return out;
     });
+    // END_BLOCK_RUN_PATHS
 }
+// START_CONTRACT: runRows
+//   PURPOSE: Исполняет читающий план в режиме строк — уникальные сущности последнего шага, с $depth при рекурсивном обходе.
+//   INPUTS: { ctx: Ctx; steps: Step[]; mods: ChainMods }
+//   OUTPUTS: { Promise<Row[]> - строки последнего шага (с $depth при deep) }
+//   SIDE_EFFECTS: читает БД через M-SQL.buildRead/runQuery
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: runRows
 async function runRows(ctx, steps, mods) {
+    // START_BLOCK_RUN_ROWS
     const q = buildRead(ctx, steps, mods, 'rows');
     const res = await runQuery(ctx, q.text, q.params, 'rows', clsOf(steps));
     return res.map((r) => {
@@ -34,9 +117,89 @@ async function runRows(ctx, steps, mods) {
         const d = r.row.depth;
         return d != null ? { ...row, $depth: d } : row;
     });
+    // END_BLOCK_RUN_ROWS
+}
+const NO_NODES = new Map();
+/**
+ * Свойство-класс (вызов = шаг/pivot; без скобок = слот). ownerSteps undefined — корень
+ * (db/batch): слот без владельца — ошибка.
+ */
+// START_CONTRACT: classProp
+//   PURPOSE: Строит StepProp для класса — вызов даёт шаг-навигацию или pivot-возврат, обращение без скобок — слот связи (set/unset) записываемой версии.
+//   INPUTS: { ctx: Ctx; name: string - имя/alias класса; cls: ClassDef; ownerSteps: Step[] | undefined - шаги владельца (undefined = корень db/batch); mods: ChainMods; batch: BatchRef | undefined; nodes: NodeMap - карта entity-идентичности; applySlot?: (slotCls, value) => Chain }
+//   OUTPUTS: { StepProp - вызываемый (шаг) Proxy с методами set/unset }
+//   SIDE_EFFECTS: возвращает новые Chain; бросает подсказки при слоте без владельца / не-конце / обращении без вызова
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: classProp
+function classProp(ctx, name, cls, ownerSteps, mods, batch, nodes, applySlot) {
+    // START_BLOCK_CLASS_STEP
+    const step = (filter) => {
+        const prev = ownerSteps?.[ownerSteps.length - 1];
+        // повтор LINK-класса в текущем паттерне — возврат к узлу (pivot)
+        const node = prev && cls.category === 'LINK' ? pivotNodeOf(ownerSteps, cls) : undefined;
+        if (node) {
+            const pivot = { name, cls, filter: normalizeFilter(filter), pivotKey: node.nodeKey };
+            return makeChain(ctx, [...ownerSteps, pivot], mods, batch, nodes);
+        }
+        if (prev && !prev.op)
+            resolveHop(prev.cls, cls); // ранняя проверка пути (после op — продолжение от результата)
+        const next = { name, cls, filter: normalizeFilter(filter), nodeKey: nextNodeKey() };
+        return makeChain(ctx, [...(ownerSteps ?? []), next], ownerSteps ? mods : {}, batch, nodes);
+    };
+    // END_BLOCK_CLASS_STEP
+    // START_BLOCK_LINK_SLOT
+    const slotGuard = () => {
+        if (!ownerSteps?.length || !applySlot) {
+            throw new Error(`letopis: slot "${name}" needs an owner step — start with a class call: db.Класс(…).${name}.set(…)`);
+        }
+        const owner = ownerSteps[ownerSteps.length - 1];
+        if (!findEnd(owner.cls, cls)) {
+            throw new Error(`letopis: "${cls.id}" is not a link end of "${owner.cls.id}" (Schema.links: ${owner.cls.links.map((e) => e.classes.join('|')).join(', ') || '—'})`);
+        }
+        return owner.cls;
+    };
+    return new Proxy(step, {
+        apply: (t, _self, args) => t(...args),
+        get(t, p, r) {
+            if (p === 'set') {
+                return (v) => {
+                    slotGuard();
+                    return applySlot(cls, slotValue(cls, v));
+                };
+            }
+            if (p === 'unset') {
+                return () => {
+                    const ownerCls = slotGuard();
+                    const end = findEnd(ownerCls, cls);
+                    if (ownerCls.strictEnds && !end.optional) {
+                        throw new Error(`letopis: link end "${cls.id}" of "${ownerCls.id}" is required — cannot unset`);
+                    }
+                    return applySlot(cls, null);
+                };
+            }
+            if (p === 'delete') {
+                return () => {
+                    throw new Error(`letopis: slot .delete() renamed to .unset() (0.16.0) — .${name}.unset() removes the link end`);
+                };
+            }
+            if (typeof p === 'symbol' || p === 'then' || p in Function.prototype || p === 'name' || p === 'length' || p === 'prototype') {
+                return Reflect.get(t, p, r);
+            }
+            throw new Error(`letopis: "${name}" without call is a link slot (set/unset); for navigation call ${name}(…)`);
+        },
+    });
+    // END_BLOCK_LINK_SLOT
 }
-function makeChain(ctx, steps, mods, batch) {
+// START_CONTRACT: makeChain
+//   PURPOSE: Собирает Proxy-цепочку над списком шагов — модификаторы и слоты порождают новые цепочки, терминалы делегируют чтение (M-SQL) или исполнение плана (M-WRITE.runPlan).
+//   INPUTS: { ctx: Ctx; steps: Step[] - накопленные шаги; mods: ChainMods; batch?: BatchRef - контекст батча; nodes?: NodeMap - entity-идентичность }
+//   OUTPUTS: { Chain - Proxy с терминалами/модификаторами и свойствами-классами }
+//   SIDE_EFFECTS: терминалы читают/пишут БД (runPaths/runRows/runQuery, runPlan); в батче мутирует очередь через syncBatch
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: makeChain
+function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
     const hasOps = steps.some((s) => s.op);
+    // START_BLOCK_STEP_MUTATORS
     const withLast = (patch) => {
         const last = steps[steps.length - 1];
         if (last.op) {
@@ -44,25 +207,89 @@ function makeChain(ctx, steps, mods, batch) {
         }
         const next = steps.slice();
         next[next.length - 1] = { ...last, ...patch };
-        return makeChain(ctx, next, mods, batch);
+        return makeChain(ctx, next, mods, batch, nodes);
+    };
+    const withMods = (patch) => makeChain(ctx, steps, { ...mods, ...patch }, batch, nodes);
+    // END_BLOCK_STEP_MUTATORS
+    // START_BLOCK_WRITE_DISPATCH
+    /** Обновить план в батче (регистрируется на первой операции, дальше мутируется). */
+    const syncBatch = (next) => {
+        if (!batch)
+            return;
+        if (batch.entry)
+            batch.entry.steps = next;
+        else {
+            batch.entry = { steps: next };
+            batch.queue.push(batch.entry);
+        }
     };
-    const withMods = (patch) => makeChain(ctx, steps, { ...mods, ...patch }, batch);
     /** Операция-звено: op на последний шаг (op уже есть → self-шаг «те же сущности»); mods сбрасываются. */
     const withOp = (op) => {
         const last = steps[steps.length - 1];
         const next = last.op
-            ? [...steps, { name: last.name, cls: last.cls, self: true, op }]
+            ? [...steps, { name: last.name, cls: last.cls, self: true, op, nodeKey: nextNodeKey() }]
             : [...steps.slice(0, -1), { ...last, op }];
-        if (batch) {
-            if (batch.entry)
-                batch.entry.steps = next;
-            else {
-                batch.entry = { steps: next };
-                batch.queue.push(batch.entry);
+        syncBatch(next);
+        return makeChain(ctx, next, {}, batch, nodes);
+    };
+    /**
+     * Слот связи: значение конца ЗАПИСЫВАЕМОЙ версии последнего шага — только после
+     * операции записи (…create(…).Класс.set(x) / …update(…).Класс.unset()): та же версия.
+     */
+    const applySlot = (slotCls, value) => {
+        const last = steps[steps.length - 1];
+        if (!last.op) {
+            throw new Error(`letopis: link slot "${slotCls.alias}" needs a write — add .create(…)/.update(…) before .${slotCls.alias}.${value === null ? 'unset()' : 'set(…)'}`);
+        }
+        if (last.op.kind !== 'create' && last.op.kind !== 'update') {
+            throw new Error(`letopis: link slot after ${last.op.kind}() — slots apply to create()/update()`);
+        }
+        if (last.extraLinks && slotCls.id in last.extraLinks) {
+            throw new Error(`letopis: duplicate link slot "${slotCls.id}" in one write`);
+        }
+        const patched = {
+            ...last,
+            extraLinks: { ...(last.extraLinks ?? {}), [slotCls.id]: value },
+        };
+        const next = [...steps.slice(0, -1), patched];
+        syncBatch(next);
+        return makeChain(ctx, next, mods, batch, nodes);
+    };
+    // END_BLOCK_WRITE_DISPATCH
+    // START_BLOCK_ENTITY_EMBED
+    /** entity(x): вклейка узла/паттерна; та же переменная повторно — возврат к её узлу. */
+    const entityStep = (x) => {
+        const plan = peekPlan(x);
+        if (plan) {
+            const known = nodes.get(x);
+            if (known !== undefined) {
+                const lastX = plan.steps[plan.steps.length - 1];
+                const pivot = { name: lastX.name, cls: lastX.cls, pivotKey: known };
+                return makeChain(ctx, [...steps, pivot], mods, batch, nodes);
             }
+            if (plan.steps.some((s) => s.op)) {
+                throw new Error('letopis: entity() takes a read pattern — a chain with operations cannot be embedded');
+            }
+            const prev = steps[steps.length - 1];
+            if (prev && !prev.op)
+                resolveHop(prev.cls, plan.steps[0].cls); // стык по правилам пути
+            const nodeKey = plan.steps[plan.steps.length - 1].nodeKey;
+            const nextNodes = new Map(nodes);
+            nextNodes.set(x, nodeKey);
+            return makeChain(ctx, [...steps, ...plan.steps], mods, batch, nextNodes);
+        }
+        if (x !== null && typeof x === 'object' && typeof x.id === 'string' && typeof x.class === 'string') {
+            const row = x;
+            const cls = ctx.registry.resolve(row.class);
+            const prev = steps[steps.length - 1];
+            if (prev && !prev.op)
+                resolveHop(prev.cls, cls);
+            const next = { name: cls.alias, cls, filter: row.id, nodeKey: nextNodeKey() };
+            return makeChain(ctx, [...steps, next], mods, batch, nodes);
         }
-        return makeChain(ctx, next, {}, batch);
+        throw new Error('letopis: entity() accepts a lazy chain or a Row');
     };
+    // END_BLOCK_ENTITY_EMBED
     /** Терминал: план (есть операции) — runPlan одной транзакцией; иначе прямое чтение. */
     const guardBatch = () => {
         if (batch && hasOps) {
@@ -71,9 +298,14 @@ function makeChain(ctx, steps, mods, batch) {
     };
     const handler = {
         get(_t, prop) {
+            if (prop === PLAN)
+                return { steps, mods };
             if (typeof prop === 'symbol' || prop === 'then')
                 return undefined;
             switch (prop) {
+                // START_BLOCK_READ_TERMINALS
+                case 'entity':
+                    return entityStep;
                 case 'run':
                     return () => {
                         guardBatch();
@@ -112,6 +344,8 @@ function makeChain(ctx, steps, mods, batch) {
                         const res = await runQuery(ctx, q.text, q.params, 'count', clsOf(steps));
                         return res[0].n;
                     };
+                // END_BLOCK_READ_TERMINALS
+                // START_BLOCK_READ_MODIFIERS
                 case 'limit':
                     return (n) => withMods({ limit: n });
                 case 'offset':
@@ -122,6 +356,8 @@ function makeChain(ctx, steps, mods, batch) {
                     return (t) => withMods({ asOf: t instanceof Date ? t.toISOString() : t });
                 case 'deep':
                     return (max = 32) => withLast({ deepMax: max });
+                // END_BLOCK_READ_MODIFIERS
+                // START_BLOCK_AGGREGATIONS
                 case 'sum':
                 case 'avg':
                 case 'min':
@@ -158,6 +394,8 @@ function makeChain(ctx, steps, mods, batch) {
                             })();
                         return Object.fromEntries(res.map((r) => [r.k ?? 'null', r.n]));
                     };
+                // END_BLOCK_AGGREGATIONS
+                // START_BLOCK_VERSIONS_CURSOR
                 case 'after':
                     return (cursor) => withMods({ after: cursor });
                 case 'versions':
@@ -173,12 +411,31 @@ function makeChain(ctx, steps, mods, batch) {
                             return raw.deleted ? { ...row, $deleted: true } : row;
                         });
                     };
+                // END_BLOCK_VERSIONS_CURSOR
+                // START_BLOCK_WRITE_TERMINALS
+                case 'create':
+                    return (data = {}) => {
+                        const last = steps[steps.length - 1];
+                        if (last && !last.op) { // после op create пишет результат — фильтр там подставит план
+                            if (last.pivotKey !== undefined) {
+                                throw new Error('letopis: create() on a pivot step — pivot returns to an existing node, use update()');
+                            }
+                            if (last.filter !== undefined && typeof last.filter !== 'string') {
+                                throw new Error(`letopis: create() takes no filter — ${last.name}(id).create(…) fixes the id, searching is update()`);
+                            }
+                        }
+                        return withOp({ kind: 'create', data, mods });
+                    };
+                case 'update':
+                    return (data = {}) => withOp({ kind: 'update', data, mods });
                 case 'set':
-                    return (data = {}) => withOp({ kind: 'set', data, mods });
+                    throw new Error('letopis: set() split into create()/update() (0.16.0) — create() inserts, update() versions what the path finds');
                 case 'delete':
                     return (opts) => withOp({ kind: 'delete', confirm: opts?.confirm === true, mods });
                 case 'anonymize':
                     return (fields) => withOp({ kind: 'anonymize', fields, mods });
+                // END_BLOCK_WRITE_TERMINALS
+                // START_BLOCK_COLUMN_MODS
                 case 'alias':
                     return (name) => withLast({ aliasKey: name });
                 case 'tags':
@@ -188,30 +445,34 @@ function makeChain(ctx, steps, mods, batch) {
                 case 'owner':
                     return (v) => withLast({ ownerFilter: typeof v === 'object' ? v.id : v });
                 case 'link':
-                    return (clsName, target) => {
-                        const linkCls = ctx.registry.resolve(clsName);
-                        const last = steps[steps.length - 1];
-                        return withLast({
-                            extraLinks: { ...(last.extraLinks ?? {}), [linkCls.id]: typeof target === 'object' ? target.id : target },
-                        });
-                    };
+                    throw new Error('letopis: .link() removed (0.15.0) — use the link slot: .Класс.set(target)');
+                // END_BLOCK_COLUMN_MODS
             }
+            // START_BLOCK_CLASS_RESOLVE
             if (ctx.registry.has(prop)) {
-                const cls = ctx.registry.resolve(prop);
-                return (filter) => makeChain(ctx, [...steps, { name: prop, cls, filter: normalizeFilter(filter) }], mods, batch);
+                return classProp(ctx, prop, ctx.registry.resolve(prop), steps, mods, batch, nodes, applySlot);
             }
             ctx.registry.resolve(prop); // неизвестный класс — понятная ошибка со списком
             return undefined;
+            // END_BLOCK_CLASS_RESOLVE
         },
     };
     return new Proxy({}, handler);
 }
+// START_CONTRACT: makeBatch
+//   PURPOSE: Собирает Proxy-батч над общей очередью планов — свойства-классы копят цепочки, run() исполняет всю очередь одной транзакцией.
+//   INPUTS: { ctx: Ctx; queue: BatchPlan[] - общая очередь планов батча }
+//   OUTPUTS: { Batch - Proxy с run/discard/size и свойствами-классами }
+//   SIDE_EFFECTS: run() исполняет и очищает очередь через M-WRITE.executeBatch; discard() очищает очередь
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: makeBatch
 function makeBatch(ctx, queue) {
     const handler = {
         get(_t, prop) {
             if (typeof prop === 'symbol' || prop === 'then')
                 return undefined;
             switch (prop) {
+                // START_BLOCK_BATCH_QUEUE
                 case 'run':
                     return async () => {
                         const plans = queue.splice(0, queue.length);
@@ -223,10 +484,10 @@ function makeBatch(ctx, queue) {
                     return () => void queue.splice(0, queue.length);
                 case 'size':
                     return () => queue.length;
+                // END_BLOCK_BATCH_QUEUE
             }
             if (ctx.registry.has(prop)) {
-                const cls = ctx.registry.resolve(prop);
-                return (filter) => makeChain(ctx, [{ name: String(prop), cls, filter: normalizeFilter(filter) }], {}, { queue });
+                return classProp(ctx, String(prop), ctx.registry.resolve(prop), undefined, {}, { queue }, NO_NODES);
             }
             ctx.registry.resolve(prop);
             return undefined;
@@ -234,6 +495,13 @@ function makeBatch(ctx, queue) {
     };
     return new Proxy({}, handler);
 }
+// START_CONTRACT: makeDb
+//   PURPOSE: Фабрика корневого фасада EntityDb над Ctx — классы как стартовые шаги, транзакции (begin/commit/rollback/lock), батчи, watch, служебные таблицы/auth/acl, entity()-старт.
+//   INPUTS: { ctx: Ctx - контекст соединения/схемы (или TxCtx внутри begin()); root?: RootState - общее состояние батчей }
+//   OUTPUTS: { EntityDb - Proxy-фасад }
+//   SIDE_EFFECTS: begin() открывает транзакцию (M-TX.beginTx); watch() ставит LISTEN на канал = имя схемы (ctx.pgSchema); close() закрывает соединение; лениво поднимает M-TABLES/M-AUTH/M-ACL
+//   LINKS: M-CHAIN, V-M-CHAIN
+// END_CONTRACT: makeDb
 export function makeDb(ctx, root) {
     const state = root ?? { batches: new Map() };
     let tables; // лениво, на ctx этого фасада (работает и в tr)
@@ -243,6 +511,7 @@ export function makeDb(ctx, root) {
         get(_t, prop) {
             if (typeof prop === 'symbol' || prop === 'then')
                 return undefined;
+            // START_BLOCK_TABLES_AUTH_ACL
             if (prop === 'accounts' || prop === 'credentials' || prop === 'resources' || prop === 'rules') {
                 tables ??= makeTables(ctx);
                 return tables[prop];
@@ -257,7 +526,9 @@ export function makeDb(ctx, root) {
                 acl ??= makeAcl(tables, ctx.registry);
                 return acl;
             }
+            // END_BLOCK_TABLES_AUTH_ACL
             switch (prop) {
+                // START_BLOCK_TX_LOCK
                 case 'begin':
                     return async () => makeDb(await beginTx(ctx), state);
                 case 'commit':
@@ -280,6 +551,8 @@ export function makeDb(ctx, root) {
                     };
                 case 'lock':
                     return (...keys) => lock(ctx, ...keys);
+                // END_BLOCK_TX_LOCK
+                // START_BLOCK_BATCH_OPEN
                 case 'batch':
                     return (name) => {
                         let q = state.batches.get(name);
@@ -289,6 +562,8 @@ export function makeDb(ctx, root) {
                         }
                         return makeBatch(ctx, q);
                     };
+                // END_BLOCK_BATCH_OPEN
+                // START_BLOCK_WATCH_LISTEN
                 case 'watch':
                     return async (a, b, c) => {
                         const cls = typeof a === 'string' ? ctx.registry.resolve(a).id : undefined;
@@ -328,19 +603,27 @@ export function makeDb(ctx, root) {
                         const { unlisten } = await ctx.sql.listen(ctx.pgSchema, listener, onlisten);
                         return unlisten;
                     };
+                // END_BLOCK_WATCH_LISTEN
+                // START_BLOCK_CLOSE_META
                 case 'close':
                     return () => ctx.sql.end();
                 case 'registry':
                     return ctx.registry;
                 case 'sql':
                     return ctx.sql;
+                // END_BLOCK_CLOSE_META
+            }
+            // START_BLOCK_ENTITY_START
+            if (prop === 'entity') {
+                // старт пути с готового паттерна/строки: db.entity(pos).…
+                return (x) => makeChain(ctx, [], {}, undefined, NO_NODES).entity(x);
             }
             if (ctx.registry.has(prop)) {
-                const cls = ctx.registry.resolve(prop);
-                return (filter) => makeChain(ctx, [{ name: String(prop), cls, filter: normalizeFilter(filter) }], {});
+                return classProp(ctx, String(prop), ctx.registry.resolve(prop), undefined, {}, undefined, NO_NODES);
             }
             ctx.registry.resolve(prop);
             return undefined;
+            // END_BLOCK_ENTITY_START
         },
     };
     return new Proxy({}, handler);

package/dist/index.d.ts

@@ -1,3 +1,9 @@
+/**
+ * letopis: dot-цепочки над append-only Entity-хранилищем (TimescaleDB).
+ *
+ *   const db = await connect({ dsn, schema: 'booking' })
+ *   await db.Сотрудник({ name: 'Вася' }).навык().Услуга().run()
+ */
 import { type EntityDb } from './chain.js';
 import type { ConnectOpts } from './types.js';
 export declare function connect(opts: ConnectOpts): Promise<EntityDb>;
@@ -5,6 +11,7 @@ export declare function connect(opts: ConnectOpts): Promise<EntityDb>;
 export declare function cursorOf(row: import('./types.js').Row, field?: string): import('./types.js').Cursor;
 export { up } from './up.js';
 export type { UpOpts } from './up.js';
+export { uuidv5, uuidv7, LETOPIS_NS } from './uuid.js';
 export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, or, } from './ops.js';
 export type { Row, Path, Filter, ChainMods, Cursor, ConnectOpts, QueryEvent, Account, Credential, Resource, Rule, AclOp, AclDecision, } from './types.js';
 export type { EntityDb, EntityTx, Chain, Batch, WatchEvent, WatchOpts } from './chain.js';

package/dist/index.js

@@ -4,11 +4,38 @@
  *   const db = await connect({ dsn, schema: 'booking' })
  *   await db.Сотрудник({ name: 'Вася' }).навык().Услуга().run()
  */
+// FILE: lib/src/index.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Публичная точка входа пакета — открыть соединение (реестр, опциональный ACL, сборка db) и ре-экспорт публичной поверхности; хелпер курсора.
+//   SCOPE: connect, cursorOf + barrel-реэкспорты
+//   DEPENDS: M-SCHEMA, M-CHAIN, M-TABLES, M-ACL, M-SQL, M-TYPES, M-UP
+//   LINKS: M-CONNECT, V-M-CONNECT
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   connect - открывает pg-соединение, грузит реестр, опц. включает ACL, собирает EntityDb
+//   cursorOf - курсор keyset-пагинации из последней строки страницы
+//   NOTE (re-exports) - up/UpOpts←M-UP; uuidv5/uuidv7/LETOPIS_NS←M-UUID; ops←M-OPS; totpCode/AuthApi/AuthResult←M-AUTH; AclApi←M-ACL; ValidationError←M-WRITE; Registry←M-SCHEMA; Session-типы←M-SESSIONS; базовые типы←M-TYPES; типы chain/tables
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
 import postgres from 'postgres';
 import { loadRegistry } from './schema.js';
 import { makeDb } from './chain.js';
 import { makeTables } from './tables.js';
 import { compileEnforcer } from './acl.js';
+// START_CONTRACT: connect
+//   PURPOSE: Открыть соединение: postgres-пул, реестр схемы, System-аккаунт, опциональный ACL — и собрать EntityDb.
+//   INPUTS: { opts: ConnectOpts { dsn, schema, partition?='entity', max?=10, account?, owner?, enforceAcl?, enforceAccount?, onQuery?, slowMs? } }
+//   OUTPUTS: { Promise<EntityDb> - dot-цепочный db }
+//   SIDE_EFFECTS: открывает пул postgres (timestamptz строкой), читает реестр и System-аккаунт; при enforceAcl без account бросает 'letopis: enforceAcl requires connect({ account })', при ненайденном — 'letopis: enforceAcl — account "…" not found', иначе читает resources/rules и компилит aclDecide; NB: ESM-цикл M-CONNECT↔M-UP (up ре-экспортится здесь)
+//   LINKS: M-CONNECT, V-M-CONNECT, M-SCHEMA, M-CHAIN, M-TABLES, M-ACL, M-SQL
+// END_CONTRACT: connect
 export async function connect(opts) {
     // timestamptz — строкой (JS Date режет микросекунды → ломал бы asOf/cursorOf по updated)
     const sql = postgres(opts.dsn, {
@@ -32,6 +59,7 @@ export async function connect(opts) {
         onQuery: opts.onQuery,
         slowMs: opts.slowMs,
     };
+    // START_BLOCK_ENFORCE_ACL
     // enforceAcl: правила и категории субъекта фиксируются на connect (перечитка — новый connect)
     if (opts.enforceAcl) {
         if (!opts.account)
@@ -46,9 +74,17 @@ export async function connect(opts) {
             throw new Error(`letopis: enforceAcl — account "${opts.account}" not found`);
         ctx.aclDecide = compileEnforcer({ resources, rules }, account.id, account.categories, registry);
     }
+    // END_BLOCK_ENFORCE_ACL
     return makeDb(ctx);
 }
 /** Курсор keyset-пагинации из последней строки страницы (field как в .sort(), вложенные пути поддержаны). */
+// START_CONTRACT: cursorOf
+//   PURPOSE: Собрать курсор keyset-пагинации из последней строки страницы.
+//   INPUTS: { row: Row - строка результата; field?: string='updated' - поле сортировки как в .sort() (вложенные пути 'data.*' поддержаны) }
+//   OUTPUTS: { Cursor - { v, id } для следующей страницы }
+//   SIDE_EFFECTS: none
+//   LINKS: M-CONNECT, V-M-CONNECT, M-TYPES
+// END_CONTRACT: cursorOf
 export function cursorOf(row, field = 'updated') {
     const v = field === 'updated'
         ? row.updated
@@ -57,6 +93,8 @@ export function cursorOf(row, field = 'updated') {
 }
 // одна точка входа: контейнер + готовность + схема + connect
 export { up } from './up.js';
+// генерация id (attributes.id): формула v5 открыта — id считается ДО создания
+export { uuidv5, uuidv7, LETOPIS_NS } from './uuid.js';
 // операторы фильтров
 export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, or, } from './ops.js';
 export { totpCode } from './auth.js';