letopis 0.20.3 → 1.0.0

package/dist/chain.js

@@ -1,351 +1,375 @@
-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
+/**
+ * Цепочки чтения (план, этап 3, п. 1, 6, 7, 11): `t.Класс(фильтр).Связь().Класс().rows()`.
+ *
+ * db и цепочка — Proxy над реестром классов: имя класса, его алиас или имя роли (конца) — шаг пути.
+ * Шаг-роль ведёт именно этим концом: `t.Folder(f).Parent()` — родительская папка,
+ * `t.Referal(anna).Customer()` — клиенты, которых привела anna. Повтор связи в пути — возврат к её
+ * узлу (pivot): от него ветвится следующий шаг. Модификаторы возвращают новую цепочку; терминалы
+ * строят один запрос (sql.ts) и исполняют его транзакцией под сессией (tx.ts).
+ *
+ * Запись (этап 4): глаголы create, update, upsert, delete, anonymize, reclass — звенья плана; слоты
+ * `.Роль.set/unset/add/remove` правят концы записываемой версии. Терминал цепочки с глаголами
+ * исполняет весь план одной транзакцией (write.ts): продолжение идёт от результата глагола.
+ * Этап 6: restore, purge, rekey; versions({ follow }); кэш результатов .cache() (cache.ts).
+ */
+import { LetopisError, removed } from './errors.js';
+import { sessionTag } from './cache.js';
+import { buildRead, nextNodeKey, resolveHop, roleTargets, stepClasses, toRow, } from './sql.js';
+import { execBatch, execPlan, precheckPlan, slotRole } from './write.js';
+/** Внутренний канал: план чужой ленивой цепочки (entity()). */
+export const PLAN = Symbol('letopis.plan');
+const peekPlan = (x) => x !== null && (typeof x === 'object' || typeof x === 'function') ? x[PLAN] : undefined;
+const NO_NODES = new Map();
+/** Строка ответа как фильтр — её id. */
 function normalizeFilter(f) {
-    if (f !== undefined &&
-        typeof f === 'object' &&
-        !Array.isArray(f) &&
-        typeof f.id === 'string' &&
-        (typeof f.class === 'string' || 'categories' in f)) {
-        return f.id;
+    if (f !== null && typeof f === 'object' && !Array.isArray(f)) {
+        const o = f;
+        if (typeof o.id === 'string' && typeof o.class === 'string')
+            return o.id;
     }
     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`);
+/** Класс, алиас или роль → класс шага (для роли — первый класс её целей). */
+export function lookupStep(reg, name) {
+    const cls = reg.find(name);
+    if (cls)
+        return { cls };
+    const targets = roleTargets(reg, name);
+    const t = targets.map((n) => reg.find(n)).find((c) => !!c);
+    return t ? { cls: t, role: name } : undefined;
 }
-/** Узел для 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
+const unknownName = (name) => {
+    throw new LetopisError('invalid_class', `класс или роль ${name} не найдены`);
+};
+const nodeOf = (steps, s) => s.pivotKey === undefined ? s : steps.find((x) => x.nodeKey === s.pivotKey) ?? s;
+/** Узел для возврата: последний реальный шаг того же класса-связи в текущем читающем сегменте. */
 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 undefined; // глагол закрывает паттерн — узлы до него недоступны
+        if (s.pivotKey === undefined && !s.role && s.cls.name === cls)
             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) => {
-        const out = {};
-        for (const [k, v] of Object.entries(r.path))
-            out[k] = toRow(v);
-        return out;
-    });
-    // END_BLOCK_RUN_PATHS
+const noHistoryWarned = new Set();
+function warnNoHistory(steps, method) {
+    const cls = steps[steps.length - 1]?.cls;
+    if (!cls || cls.history !== false)
+        return;
+    const key = `${cls.name}|${method}`;
+    if (noHistoryWarned.has(key))
+        return;
+    noHistoryWarned.add(key);
+    console.warn(`letopis: .${method}() у класса ${cls.name} без журнала (history: false) — истории нет`);
 }
-// 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) => {
-        const row = toRow(r.row);
-        const d = r.row.depth;
-        return d != null ? { ...row, $depth: d } : row;
-    });
-    // END_BLOCK_RUN_ROWS
+function report(ctx, mode, steps, t0, rows) {
+    if (!ctx.onQuery && ctx.slowMs === undefined)
+        return;
+    const ms = performance.now() - t0;
+    const slow = ctx.slowMs !== undefined && ms > ctx.slowMs;
+    const classes = steps.map((s) => s.cls.name);
+    if (ctx.onQuery)
+        ctx.onQuery({ mode, classes, ms, rows, slow });
+    else if (slow)
+        console.warn(`letopis: медленный запрос ${ms.toFixed(0)} мс — ${mode} ${classes.join('→')}`);
+}
+/** Классы, которые читает цепочка (семейства шагов): по ним сбрасывается её ответ в кэше. */
+function readClasses(reg, steps) {
+    return [...new Set(steps.flatMap((s) => stepClasses(reg, s)))];
+}
+/** Срок ответа в кэше, мс: .cache({ ttl }) или пометка cache у всех классов чтения; null — не кэшировать. */
+function cacheTtl(ctx, steps, mods, classes) {
+    const c = ctx.cache;
+    if (!c || !c.store.enabled || ctx.exec.explicit || ctx.batch || mods.forUpdate)
+        return null;
+    if (mods.cache)
+        return mods.cache.ttl !== undefined ? mods.cache.ttl * 1000 : c.store.ttlMs;
+    const marks = classes.map((n) => ctx.reg.find(n)?.cache);
+    if (!marks.length || marks.some((m) => !m))
+        return null;
+    return Math.min(...marks.map((m) => (m.ttl !== undefined ? m.ttl * 1000 : c.store.ttlMs)));
+}
+async function exec(ctx, q, mode, steps, mods = {}) {
+    const classes = ctx.cache ? readClasses(ctx.reg, steps) : [];
+    const ttl = ctx.cache ? cacheTtl(ctx, steps, mods, classes) : null;
+    if (ttl !== null) {
+        const store = ctx.cache.store;
+        const who = ctx.cache.who();
+        const key = store.key(q.text, q.params, who);
+        const hit = store.get(key);
+        if (hit)
+            return hit;
+        const tag = sessionTag(who.token);
+        const tok = store.token(classes, tag);
+        const t0 = performance.now();
+        const S = `"${ctx.schema.replace(/"/g, '""')}"`;
+        const [res, exp] = await ctx.exec.run((tx) => Promise.all([
+            tx.unsafe(q.text, q.params, { prepare: true }),
+            tx.unsafe(`select ${S}.session_expires() as e`),
+        ]), { read: true });
+        report(ctx, mode, steps, t0, res.length);
+        const e = exp[0]?.e;
+        store.set(key, [...res], classes, tag, tok, ttl, e ? Date.parse(e) : null);
+        return res;
+    }
+    const t0 = performance.now();
+    const res = await ctx.exec.run((tx) => tx.unsafe(q.text, q.params, { prepare: true }), { read: true });
+    report(ctx, mode, steps, t0, res.length);
+    return res;
+}
+async function read(ctx, steps, mods, mode, agg) {
+    const hasOps = steps.some((s) => s.op);
+    if (ctx.batch && hasOps)
+        throw new LetopisError('invalid_query', 'план стоит в очереди батча — его исполнит batch.run()');
+    if (mods.forUpdate)
+        return lockedRead(ctx, steps, mods, mode);
+    if (hasOps)
+        return plan(ctx, steps, mods, mode, agg);
+    const { cache: _c, ...plain } = mods;
+    const q = buildRead(ctx.reg, ctx.schema, steps, plain, mode, agg);
+    const ev = mode === 'countPaths' ? 'count' : mode;
+    return exec(ctx, q, ev, steps, mods).then((res) => ({ q, res }));
 }
-const NO_NODES = new Map();
 /**
- * Свойство-класс (вызов = шаг/pivot; без скобок = слот). ownerSteps undefined — корень
- * (db/batch): слот без владельца — ошибка.
+ * Цепочка с глаголами: весь план одной транзакцией (§2.5). Результат приводится к виду ответа
+ * чтения (строки rows/paths, id, n, агрегаты), чтобы терминалы разбирали его одинаково.
  */
-// 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
+async function plan(ctx, steps, mods, mode, agg) {
+    precheckPlan(ctx.reg, steps);
+    const t0 = performance.now();
+    const r = await ctx.exec.run((q) => execPlan({ reg: ctx.reg, schema: ctx.schema, q, tenant: ctx.tenant(), owner: ctx.owner }, steps, mods, mode, agg));
+    if (r.kind === 'read') {
+        report(ctx, mode === 'countPaths' ? 'count' : mode, steps, t0, r.res.length);
+        if (r.q === null) {
+            if (mode === 'count' || mode === 'countPaths')
+                return { q: null, res: [{ n: 0 }] };
+            if (mode === 'agg')
+                return { q: null, res: agg?.fn === 'countBy' ? [] : [{ v: null }] };
+        }
+        return r;
+    }
+    const rows = r.rows;
+    report(ctx, mode === 'countPaths' ? 'count' : mode === 'paths' ? 'paths' : mode === 'ids' ? 'ids' : 'rows', steps, t0, rows.length);
+    // не switch: check-docs принимает case-метки этого файла за имена, которые Proxy разбирает раньше классов
+    if (mode === 'paths')
+        return { q: null, res: rows.map((row) => ({ path: { [r.key]: row } })) };
+    if (mode === 'ids')
+        return { q: null, res: rows.map((row) => ({ id: row.id })) };
+    if (mode === 'count' || mode === 'countPaths')
+        return { q: null, res: [{ n: rows.length }] };
+    return { q: null, res: (mods.limit !== undefined ? rows.slice(0, mods.limit) : rows).map((row) => ({ row, done: true })) };
+}
+/**
+ * Чтение с блокировкой (§2.5, этап 4, п. 9): строки последнего шага блокируются for no key update
+ * в порядке id до конца явной транзакции. Сначала id шага, затем блокировка (политики правки RLS
+ * не дают заблокировать то, что править нельзя), затем то же чтение по свежим строкам: строка,
+ * которая перестала подходить под условия шага, в ответ не попадает; подходящая, но не
+ * заблокированная — acl_denied.
+ */
+async function lockedRead(ctx, steps, mods, mode) {
+    if (!ctx.exec.explicit)
+        throw new LetopisError('tx_required', 'forUpdate() — только внутри db.begin(): вне явной транзакции блокировка снялась бы сразу');
+    if ((mode !== 'rows' && mode !== 'ids') || mods.asOf !== undefined || mods.withDeleted || steps.some((s) => s.deepMax !== undefined || s.op)) {
+        throw new LetopisError('lock_unsupported', 'forUpdate() — с терминалами rows, first, ids, без агрегатов, asOf, versions, withDeleted, deep и глаголов');
+    }
+    const S = `"${ctx.schema.replace(/"/g, '""')}"`;
+    const { forUpdate: _f, ...plain } = mods;
+    const idsQ = buildRead(ctx.reg, ctx.schema, steps, plain, 'ids');
+    const { limit: _l, offset: _o, after: _a, ...unbounded } = plain;
+    const rowsQ = buildRead(ctx.reg, ctx.schema, steps, unbounded, 'rows');
+    const t0 = performance.now();
+    const res = await ctx.exec.run(async (q) => {
+        const ids = (await q.unsafe(idsQ.text, idsQ.params, { prepare: true })).map((r) => r.id);
+        if (!ids.length)
+            return [];
+        const locked = new Set((await q.unsafe(`select id from ${S}.entity where id = any ($1::uuid[]) order by id for no key update`, [ids], { prepare: true })).map((r) => r.id));
+        const want = new Set(ids);
+        const fresh = (await q.unsafe(rowsQ.text, rowsQ.params, { prepare: true }))
+            .filter((r) => want.has(r.row.id));
+        const denied = fresh.filter((r) => !locked.has(r.row.id)).map((r) => r.row.id);
+        if (denied.length)
+            throw new LetopisError('acl_denied', `строки видны, но заблокировать их нельзя: ${denied.join(', ')}`, { ids: denied });
+        return fresh;
+    });
+    report(ctx, mode, steps, t0, res.length);
+    return { q: rowsQ, res: mode === 'ids' ? res.map((r) => ({ id: r.row.id })) : res };
+}
+/** Строка ответа: из чтения — to_jsonb узла, из плана — готовая строка записи. */
+const rowOf = (r) => (r.done ? r.row : toRow(r.row));
+/** Значение слота: id, список id, строка ответа или ленивая цепочка. */
+function slotValue(v) {
+    const peek = peekPlan(v);
+    if (peek)
+        return { plan: peek.steps, mods: peek.mods };
+    if (v === null || typeof v === 'string')
+        return v;
+    if (Array.isArray(v))
+        return v.map((x) => (typeof x === 'string' ? x : x.id));
+    if (typeof v === 'object' && typeof v.id === 'string')
+        return { id: v.id };
+    throw new LetopisError('invalid_query', 'значение слота — id, список id, строка ответа или цепочка');
+}
+function classProp(ctx, name, found, ownerSteps, mods, nodes) {
+    const { cls, role } = found;
     const step = (filter) => {
         const prev = ownerSteps?.[ownerSteps.length - 1];
-        // повтор LINK-класса в текущем паттерне — возврат к узлу (pivot)
-        const node = prev && cls.category === 'LINK' ? pivotNodeOf(ownerSteps, cls) : undefined;
+        // повтор связи в пути — возврат к её узлу
+        const node = prev && cls.kind === 'link' && !role ? pivotNodeOf(ownerSteps, cls.name) : undefined;
         if (node) {
-            const pivot = { name, cls, filter: normalizeFilter(filter), pivotKey: node.nodeKey };
-            return makeChain(ctx, [...ownerSteps, pivot], mods, batch, nodes);
+            return makeChain(ctx, [...ownerSteps, { name, cls, filter: normalizeFilter(filter), pivotKey: node.nodeKey }], mods, 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);
+        const next = { name, cls, role, filter: normalizeFilter(filter), nodeKey: nextNodeKey() };
+        if (prev)
+            resolveHop(ctx.reg, nodeOf(ownerSteps, prev), next); // ранняя проверка пути
+        return makeChain(ctx, [...(ownerSteps ?? []), next], ownerSteps ? mods : {}, 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(…)`);
+    // слот: .Роль.set(x) / .unset() / .add(x) / .remove(x) — концы версии, которую пишет глагол
+    const slot = (op) => (v) => {
+        const last = ownerSteps?.[ownerSteps.length - 1];
+        const kind = last?.op?.kind;
+        if (!last || (kind !== 'create' && kind !== 'update' && kind !== 'upsert')) {
+            throw new LetopisError('invalid_query', `слот .${name}.${op}() — после create(), update() или upsert(): db.Класс(…).update(…).${name}.${op}(…)`);
         }
-        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(', ') || '—'})`);
+        const role = slotRole(ctx.reg, last.cls, name);
+        const end = last.cls.ends[role];
+        if ((op === 'add' || op === 'remove') && !end.many)
+            throw new LetopisError('invalid_query', `слот .${name}.${op}(): конец ${role} одиночный — set() или unset()`);
+        if (op === 'unset' && (end.required || (end.min ?? 0) > 0))
+            throw new LetopisError('invalid_query', `слот .${name}.unset(): конец ${role} обязателен`);
+        if ((op === 'set' || op === 'unset') && last.slots?.some((x) => x.role === role && (x.op === 'set' || x.op === 'unset'))) {
+            throw new LetopisError('invalid_query', `слот ${role} задан дважды в одной записи`);
         }
-        return owner.cls;
+        const value = op === 'unset' ? null : slotValue(v);
+        const next = ownerSteps.slice();
+        next[next.length - 1] = { ...last, slots: [...(last.slots ?? []), { role, op, value }] };
+        if (ctx.batch?.entry)
+            ctx.batch.entry.steps = next;
+        return makeChain(ctx, next, mods, nodes);
     };
     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}(…)`);
+            if (p === 'set' || p === 'unset' || p === 'add' || p === 'remove')
+                return slot(p);
+            return Reflect.get(t, p, r);
         },
     });
-    // END_BLOCK_LINK_SLOT
 }
-// 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
+export function makeChain(ctx, steps, mods, nodes = NO_NODES) {
     const withLast = (patch) => {
-        const last = steps[steps.length - 1];
-        if (last.op) {
-            throw new Error(`letopis: step modifier after ${last.op.kind}() — add a class step first`);
-        }
+        const lastOp = steps[steps.length - 1]?.op;
+        if (lastOp)
+            throw new LetopisError('invalid_query', `модификатор шага после ${lastOp.kind}() — сначала шаг класса`);
         const next = steps.slice();
-        next[next.length - 1] = { ...last, ...patch };
-        return makeChain(ctx, next, mods, batch, nodes);
+        next[next.length - 1] = { ...steps[steps.length - 1], ...patch };
+        return makeChain(ctx, next, mods, nodes);
     };
-    const withMods = (patch) => makeChain(ctx, steps, { ...mods, ...patch }, batch, nodes);
-    // END_BLOCK_STEP_MUTATORS
-    // START_BLOCK_WRITE_DISPATCH
-    /** Обновить план в батче (регистрируется на первой операции, дальше мутируется). */
+    const withMods = (patch) => makeChain(ctx, steps, { ...mods, ...patch }, nodes);
+    /** Батч: первый глагол ставит план в очередь, следующие звенья обновляют его. */
     const syncBatch = (next) => {
-        if (!batch)
+        const b = ctx.batch;
+        if (!b)
             return;
-        if (batch.entry)
-            batch.entry.steps = next;
+        if (b.entry)
+            b.entry.steps = next;
         else {
-            batch.entry = { steps: next };
-            batch.queue.push(batch.entry);
+            b.entry = { steps: next };
+            b.queue.push(b.entry);
         }
     };
-    /** Операция-звено: op на последний шаг (op уже есть → self-шаг «те же сущности»); mods сбрасываются. */
+    /** Глагол — звено плана на последнем шаге (глагол уже есть — новый шаг «те же сущности»); модификаторы — его целям. */
     const withOp = (op) => {
         const last = steps[steps.length - 1];
+        if (!last)
+            throw new LetopisError('invalid_query', `${op.kind}() — нужен шаг класса: db.Класс(…).${op.kind}(…)`);
         const next = last.op
-            ? [...steps, { name: last.name, cls: last.cls, self: true, op, nodeKey: nextNodeKey() }]
-            : [...steps.slice(0, -1), { ...last, op }];
-        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];
+            ? [...steps, { name: last.name, cls: last.cls, role: last.role, aliasKey: last.aliasKey, self: true, op, opMods: mods, nodeKey: nextNodeKey() }]
+            : [...steps.slice(0, -1), { ...last, op, opMods: mods }];
         syncBatch(next);
-        return makeChain(ctx, next, mods, batch, nodes);
+        return makeChain(ctx, next, {}, nodes);
     };
-    // END_BLOCK_WRITE_DISPATCH
-    // START_BLOCK_ENTITY_EMBED
-    /** entity(x): вклейка узла/паттерна; та же переменная повторно — возврат к её узлу. */
     const entityStep = (x) => {
         const plan = peekPlan(x);
+        const prev = steps.length ? nodeOf(steps, steps[steps.length - 1]) : undefined;
+        if (plan?.steps.some((s) => s.op))
+            throw new LetopisError('invalid_query', 'entity() принимает читающий паттерн — цепочку с глаголами вклеить нельзя');
         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);
+                return makeChain(ctx, [...steps, { name: lastX.name, cls: lastX.cls, pivotKey: known }], mods, 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); // стык по правилам пути
+            if (prev)
+                resolveHop(ctx.reg, prev, plan.steps[0]);
             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);
+            return makeChain(ctx, [...steps, ...plan.steps], mods, 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);
+            const cls = ctx.reg.resolve(row.class);
+            const next = { name: cls.name, cls, filter: row.id, nodeKey: nextNodeKey(), exact: true };
+            if (prev)
+                resolveHop(ctx.reg, prev, next);
+            return makeChain(ctx, [...steps, next], mods, nodes);
         }
-        throw new Error('letopis: entity() accepts a lazy chain or a Row');
+        throw new LetopisError('invalid_query', 'entity() принимает ленивую цепочку или строку ответа');
     };
-    // END_BLOCK_ENTITY_EMBED
-    /** Терминал: план (есть операции) — runPlan одной транзакцией; иначе прямое чтение. */
-    const guardBatch = () => {
-        if (batch && hasOps) {
-            throw new Error('letopis: plan is queued in the batch — call batch.run()');
-        }
+    const agg = (fn) => async (field) => {
+        const { q, res } = await read(ctx, steps, mods, 'agg', { fn, field });
+        if (fn === 'countBy')
+            return Object.fromEntries(res.map((r) => [r.k ?? 'null', r.n]));
+        const v = res[0]?.v;
+        if (v === null || v === undefined)
+            return null;
+        if (typeof v !== 'string')
+            return v;
+        if (fn === 'sum' || fn === 'avg' || q?.aggLeaf === 'numeric')
+            return Number(v);
+        return v;
     };
     const handler = {
         get(_t, prop) {
             if (prop === PLAN)
                 return { steps, mods };
-            if (typeof prop === 'symbol' || prop === 'then')
+            if (typeof prop === 'symbol')
                 return undefined;
             switch (prop) {
-                // START_BLOCK_READ_TERMINALS
+                case 'then':
+                    return undefined;
                 case 'entity':
                     return entityStep;
-                case 'run':
-                    return () => {
-                        guardBatch();
-                        return hasOps ? runPlan(ctx, steps, mods, 'paths') : runPaths(ctx, steps, mods);
+                case 'paths':
+                    return async () => {
+                        // q === null — пути из результата глагола: строки уже готовы
+                        const { q, res } = await read(ctx, steps, mods, 'paths');
+                        return res.map((r) => Object.fromEntries(Object.entries(r.path).map(([k, v]) => [k, q === null ? v : toRow(v)])));
                     };
-                case 'execute':
-                    throw new Error('letopis: execute() renamed to run() (0.11.0)');
                 case 'rows':
-                    return () => {
-                        guardBatch();
-                        return hasOps ? runPlan(ctx, steps, mods, 'rows') : runRows(ctx, steps, mods);
-                    };
+                    return async () => (await read(ctx, steps, mods, 'rows')).res.map(rowOf);
                 case 'first':
                     return async () => {
-                        guardBatch();
-                        const rows = hasOps
-                            ? (await runPlan(ctx, steps, mods, 'rows'))
-                            : await runRows(ctx, steps, { ...mods, limit: 1 });
-                        return rows[0] ?? null;
+                        const { res } = await read(ctx, steps, { ...mods, limit: 1 }, 'rows');
+                        return res[0] ? rowOf(res[0]) : null;
                     };
                 case 'ids':
-                    return async () => {
-                        guardBatch();
-                        if (hasOps)
-                            return runPlan(ctx, steps, mods, 'ids');
-                        const q = buildRead(ctx, steps, mods, 'ids');
-                        const res = await runQuery(ctx, q.text, q.params, 'ids', clsOf(steps));
-                        return res.map((r) => r.id);
-                    };
+                    return async () => (await read(ctx, steps, mods, 'ids')).res.map((r) => r.id);
                 case 'count':
-                    return async () => {
-                        guardBatch();
-                        if (hasOps)
-                            return runPlan(ctx, steps, mods, 'count');
-                        const q = buildRead(ctx, steps, mods, 'count');
-                        const res = await runQuery(ctx, q.text, q.params, 'count', clsOf(steps));
-                        return res[0].n;
+                    return async (opts) => (await read(ctx, steps, mods, opts?.paths ? 'countPaths' : 'count')).res[0].n;
+                case 'versions':
+                    return async (opts) => {
+                        warnNoHistory(steps, 'versions');
+                        const m = opts?.follow ? { ...mods, follow: true } : mods;
+                        return (await read(ctx, steps, m, 'versions')).res.map((r) => toRow(r.row));
                     };
-                // END_BLOCK_READ_TERMINALS
-                // START_BLOCK_READ_MODIFIERS
+                case 'sum':
+                case 'avg':
+                case 'min':
+                case 'max':
+                case 'countBy':
+                    return agg(prop);
                 case 'limit':
                     return (n) => withMods({ limit: n });
                 case 'offset':
@@ -353,313 +377,107 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
                 case 'sort':
                     return (field, dir) => withMods({ order: field, desc: dir === true || dir === 'desc' });
                 case 'asOf':
-                    return (t) => withMods({ asOf: t instanceof Date ? t.toISOString() : t });
+                    return (t) => {
+                        warnNoHistory(steps, 'asOf');
+                        return withMods({ asOf: t instanceof Date ? t.toISOString() : t });
+                    };
+                case 'after':
+                    return (cursor) => withMods({ after: cursor });
                 case 'withDeleted':
                     return () => withMods({ withDeleted: true });
                 case 'deep':
                     return (max = 32) => withLast({ deepMax: max });
                 case 'exact':
-                    // снять полиморфизм ТЕКУЩЕГО шага: только свой класс, без потомков
-                    return () => withLast({ exactClass: true });
-                // END_BLOCK_READ_MODIFIERS
-                // START_BLOCK_AGGREGATIONS
-                case 'sum':
-                case 'avg':
-                case 'min':
-                case 'max':
-                    return async (field) => {
-                        guardBatch();
-                        const aggMods = { ...mods, aggFn: prop, aggField: field };
-                        const res = hasOps
-                            ? (await runPlan(ctx, steps, aggMods, 'agg'))
-                            : await (async () => {
-                                const q = buildRead(ctx, steps, aggMods, 'agg');
-                                return runQuery(ctx, q.text, q.params, 'agg', clsOf(steps));
-                            })();
-                        const v = res[0]?.v;
-                        if (v === null || v === undefined)
-                            return null;
-                        if (typeof v !== 'string')
-                            return v;
-                        if (prop === 'sum' || prop === 'avg')
-                            return Number(v);
-                        // min/max: postgres.js отдаёт numeric строкой — приводим, если лист числовой по Schema
-                        const leaf = leafType(steps[steps.length - 1].cls, field.slice(5).split('.'));
-                        return leaf?.kind === 'number' ? Number(v) : v;
-                    };
-                case 'countBy':
-                    return async (field) => {
-                        guardBatch();
-                        const aggMods = { ...mods, aggFn: 'countBy', aggField: field };
-                        const res = hasOps
-                            ? (await runPlan(ctx, steps, aggMods, 'agg'))
-                            : await (async () => {
-                                const q = buildRead(ctx, steps, aggMods, 'agg');
-                                return runQuery(ctx, q.text, q.params, 'agg', clsOf(steps));
-                            })();
-                        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':
-                    return async () => {
-                        guardBatch();
-                        if (hasOps)
-                            return runPlan(ctx, steps, mods, 'versions');
-                        const q = buildRead(ctx, steps, mods, 'versions');
-                        const res = await runQuery(ctx, q.text, q.params, 'versions', clsOf(steps));
-                        return res.map((r) => {
-                            const raw = r.row;
-                            const row = toRow(r.row);
-                            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':
-                    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 });
-                case 'purge':
-                    return (opts) => withOp({ kind: 'purge', confirm: opts?.confirm === true, mods });
-                // END_BLOCK_WRITE_TERMINALS
-                // START_BLOCK_COLUMN_MODS
+                    return () => withLast({ exact: true });
                 case 'alias':
                     return (name) => withLast({ aliasKey: name });
                 case 'tags':
                     return (v) => withLast({ tagsFilter: v });
-                case 'account':
-                    return (v) => withLast({ accountFilter: typeof v === 'object' ? v.id : v });
                 case 'owner':
                     return (v) => withLast({ ownerFilter: typeof v === 'object' ? v.id : v });
-                // NB: охранника `case 'link'` здесь больше нет (снят в 0.20.0). Он затенял РЕАЛЬНЫЙ
-                // класс схемы: в демо-домене `link` — абстрактный корень всех связок, и шаг
-                // db.Клиент(c).link() падал migration-ошибкой вместо обхода. Обратная совместимость
-                // со снесённым в 0.15.0 методом .link() принесена в жертву достижимости класса.
-                // END_BLOCK_COLUMN_MODS
-            }
-            // START_BLOCK_CLASS_RESOLVE
-            if (ctx.registry.has(prop)) {
-                return classProp(ctx, prop, ctx.registry.resolve(prop), steps, mods, batch, nodes, applySlot);
+                // охранники снесённого API (этап 3, п. 11)
+                case 'run':
+                    throw removed('run()', 'paths()');
+                case 'execute':
+                    throw removed('execute()', 'paths()');
+                case 'account':
+                    throw removed('account()', 'арендатор сессии и auth.switch() (этап 5)');
+                // глаголы записи — звенья плана (этап 4)
+                case 'create':
+                    return (data = {}) => withOp({ kind: 'create', data });
+                case 'update':
+                    return (data = {}, opts) => withOp({ kind: 'update', data, ...(opts?.rev !== undefined ? { rev: opts.rev } : {}) });
+                case 'upsert':
+                    return (data = {}) => withOp({ kind: 'upsert', data });
+                case 'delete':
+                    return (opts) => withOp({ kind: 'delete', confirm: opts?.confirm === true });
+                case 'anonymize':
+                    return (fields) => withOp({ kind: 'anonymize', fields });
+                case 'reclass':
+                    return (cls, data) => withOp({ kind: 'reclass', cls, ...(data !== undefined ? { data } : {}) });
+                case 'set':
+                case 'unset':
+                case 'add':
+                case 'remove':
+                    throw new LetopisError('invalid_query', `${prop}() — метод слота: db.Класс(…).update(…).Роль.${prop}(…)`);
+                case 'forUpdate':
+                    return () => withMods({ forUpdate: true });
+                case 'restore':
+                    return () => withOp({ kind: 'restore' });
+                case 'purge':
+                    return (opts) => withOp({ kind: 'purge', confirm: opts?.confirm === true });
+                case 'rekey':
+                    return (patch) => withOp({ kind: 'rekey', data: patch ?? {} });
+                case 'cache':
+                    return (opts) => {
+                        if (opts?.ttl !== undefined && !(opts.ttl > 0))
+                            throw new LetopisError('invalid_query', 'cache({ ttl }): срок — положительное число секунд');
+                        return withMods({ cache: opts ?? {} });
+                    };
             }
-            ctx.registry.resolve(prop); // неизвестный класс — понятная ошибка со списком
-            return undefined;
-            // END_BLOCK_CLASS_RESOLVE
+            const found = lookupStep(ctx.reg, prop) ?? unknownName(prop);
+            return classProp(ctx, prop, found, steps, mods, nodes);
         },
     };
     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 = {
+/**
+ * Батч: очередь планов; каждый вызов класса — своя ссылка на очередь (свой план). run() исполняет очередь
+ * в контексте ctx (актор, арендатор, владелец, транзакция) — поэтому очередь принадлежит фасаду этого ctx
+ * и общей с другими фасадами быть не может: иначе план исполнился бы от имени чужого актора.
+ */
+export function makeBatch(ctx, queue) {
+    return new Proxy({}, {
         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);
-                        return executeBatch(ctx, plans);
+                        const plans = queue.splice(0, queue.length).map((x) => x.steps);
+                        for (const p of plans)
+                            precheckPlan(ctx.reg, p);
+                        if (!plans.length)
+                            return [];
+                        return ctx.exec.run((q) => execBatch({ reg: ctx.reg, schema: ctx.schema, q, tenant: ctx.tenant(), owner: ctx.owner }, plans));
                     };
                 case 'execute':
-                    throw new Error('letopis: batch.execute() renamed to batch.run() (0.11.0)');
+                    throw removed('batch.execute()', 'batch.run()');
                 case 'discard':
                     return () => void queue.splice(0, queue.length);
                 case 'size':
                     return () => queue.length;
-                // END_BLOCK_BATCH_QUEUE
             }
-            if (ctx.registry.has(prop)) {
-                return classProp(ctx, String(prop), ctx.registry.resolve(prop), undefined, {}, { queue }, NO_NODES);
-            }
-            ctx.registry.resolve(prop);
-            return undefined;
+            return startStep({ ...ctx, batch: { queue } }, prop);
         },
-    };
-    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)
-    let auth;
-    let acl;
-    const handler = {
-        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' || prop === 'schema') {
-                tables ??= makeTables(ctx);
-                return tables[prop];
-            }
-            if (prop === 'auth') {
-                tables ??= makeTables(ctx);
-                auth ??= makeAuth(tables);
-                return auth;
-            }
-            if (prop === 'acl') {
-                tables ??= makeTables(ctx);
-                acl ??= makeAcl(tables, ctx.registry);
-                return acl;
-            }
-            // END_BLOCK_TABLES_AUTH_ACL
-            switch (prop) {
-                // START_BLOCK_SCOPE_AS
-                // db.as(account): тот же пул, но вызов от имени этого арендатора. Дешёвый клон ctx
-                // (как beginTx), НЕ новое соединение. Батчи не наследуются: очередь планов, общая
-                // для разных арендаторов, — это утечка записи между ними.
-                case 'as':
-                    return async (a, o) => {
-                        const account = typeof a === 'object' ? a?.id : a;
-                        if (!account)
-                            throw new Error('letopis: db.as(account) requires an account id (uuid or { id })');
-                        const scoped = { ...ctx, account, owner: o?.owner, aclDecide: undefined };
-                        // reloadSchema() со scope: реестр перечитывает КОРЕНЬ (единый источник), затем
-                        // scope подхватывает его и перекомпилирует свой энфорсер под своего субъекта.
-                        scoped.reload = async () => {
-                            await ctx.reload?.();
-                            scoped.registry = ctx.registry;
-                            await ctx.compileAcl?.(scoped);
-                        };
-                        await ctx.compileAcl?.(scoped);
-                        return makeDb(scoped);
-                    };
-                // END_BLOCK_SCOPE_AS
-                // START_BLOCK_TX_LOCK
-                case 'begin':
-                    return async () => makeDb(await beginTx(ctx), state);
-                case 'commit':
-                    return (tr) => {
-                        if (tr)
-                            return tr.commit();
-                        const c = ctx;
-                        if (typeof c.commit === 'function')
-                            return c.commit();
-                        throw new Error('letopis: commit() needs a transaction: db.commit(tr) or tr.commit()');
-                    };
-                case 'rollback':
-                    return (tr) => {
-                        if (tr)
-                            return tr.rollback();
-                        const c = ctx;
-                        if (typeof c.rollback === 'function')
-                            return c.rollback();
-                        throw new Error('letopis: rollback() needs a transaction: db.rollback(tr) or tr.rollback()');
-                    };
-                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);
-                        if (!q) {
-                            q = [];
-                            state.batches.set(name, q);
-                        }
-                        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;
-                        const cb = typeof a === 'function' ? a : b;
-                        const opts = (typeof a === 'function' ? b : c) ?? {};
-                        const listener = (payload) => {
-                            const e = JSON.parse(payload);
-                            if (e.partition !== ctx.partition)
-                                return;
-                            if (cls && e.class !== cls)
-                                return;
-                            // enforceAcl: отдаём только при БЕЗУСЛОВНОМ allow — payload не содержит
-                            // owner/account/data, предикат строки проверить нечем (id — тоже утечка)
-                            if (ctx.aclDecide) {
-                                try {
-                                    const d = ctx.aclDecide(ctx.registry.resolve(e.class), 'READ');
-                                    if (!d.allow || d.filter)
-                                        return;
-                                }
-                                catch {
-                                    return;
-                                }
-                            }
-                            cb(e);
-                        };
-                        // postgres.js: dedicated LISTEN-соединение само переподключается (backoff) и
-                        // повторяет LISTEN; onlisten зовётся на первом connect И на каждом re-listen.
-                        // NOTIFY за время разрыва потеряны — onReconnect даёт точку дочитать пропущенное.
-                        let first = true;
-                        const onlisten = () => {
-                            if (first) {
-                                first = false;
-                                return;
-                            }
-                            opts.onReconnect?.();
-                        };
-                        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 'reloadSchema':
-                    return async () => {
-                        await ctx.reload?.();
-                        acl = undefined; // db.acl-фасад перестроится на свежем registry при следующем доступе
-                    };
-                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)) {
-                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);
+/** Старт пути от корня db: класс, алиас или роль. */
+export function startStep(ctx, name) {
+    const found = lookupStep(ctx.reg, name) ?? unknownName(name);
+    return classProp(ctx, name, found, undefined, {}, NO_NODES);
+}
+/** Старт пути с готового узла: db.entity(row | цепочка). */
+export function startEntity(ctx, x) {
+    return makeChain(ctx, [], {}, NO_NODES).entity(x);
 }