letopis 0.18.1 → 0.20.0

package/dist/sql.js

@@ -414,16 +414,31 @@ const whereOf = (conds) => {
     const list = conds.filter((c) => !!c);
     return list.length ? ` WHERE ${list.join(' AND ')}` : '';
 };
+// START_CONTRACT: guardScoped
+//   PURPOSE: enforceAccount без идентичности вызова — фильтровать нечем, значит изоляция не гарантирована: ошибка с подсказкой на db.as().
+//   INPUTS: { ctx: Ctx }
+//   OUTPUTS: { void }
+//   SIDE_EFFECTS: бросает 'letopis: enforceAccount is on — call db.as(account)…' на безличном (корневом) хендле
+//   LINKS: M-SQL, V-M-SQL, M-CHAIN, M-WRITE
+// END_CONTRACT: guardScoped
+/** Корневой хендл при enforceAccount читать/писать не может: арендатора называет db.as(). */
+export function guardScoped(ctx) {
+    if (ctx.enforceAccount && !ctx.account) {
+        throw new Error('letopis: enforceAccount is on — call db.as(account) to name the tenant of this call, ' +
+            'or connect({ enforceAccount: false }) for admin access');
+    }
+}
 // START_CONTRACT: buildRead
 //   PURPOSE: Скомпилировать цепочку шагов+модов в один параметризованный read-запрос (латеральный обход путей, latest-версии, asOf/versions/agg, keyset).
 //   INPUTS: { ctx: Ctx; steps: Step[]; mods: ChainMods; mode: ReadMode }
 //   OUTPUTS: { BuiltQuery - { text, params, keys } }
-//   SIDE_EFFECTS: none (строит SQL; ACL-проверка READ может бросить)
-//   ERRORS: pivot node not in path; enforceAccount pin; acl denies READ; deep on non-self hop; agg needs data.<path>
+//   SIDE_EFFECTS: none (строит SQL; guardScoped и ACL-проверка READ могут бросить)
+//   ERRORS: enforceAccount without db.as(); pivot node not in path; enforceAccount pin; acl denies READ; deep on non-self hop; agg needs data.<path>
 //   LINKS: M-SQL, V-M-SQL, M-ACL, M-DDL
 // END_CONTRACT: buildRead
 /** Построить читающий запрос по цепочке. */
 export function buildRead(ctx, steps, mods, mode) {
+    guardScoped(ctx);
     const p = new Params();
     const ent = entityTable(ctx.pgSchema);
     const pPart = p.push(ctx.partition);
@@ -462,9 +477,19 @@ export function buildRead(ctx, steps, mods, mode) {
                 tailConds.push(fr(a));
             if (step.tagsFilter !== undefined)
                 tailConds.push(compileTags(step.tagsFilter, p)(a));
+            // .exact() на pivot: узел уже материализован полиморфно, поэтому сужаем его
+            // дофильтром по классу — иначе модификатор молча ничего не делал бы
+            if (step.exactClass)
+                tailConds.push(`${a}.class = ${p.push(step.cls.id)}`);
             continue;
         }
-        const pCls = p.push(step.cls.id);
+        // ПОЛИМОРФНОЕ чтение: шаг по родителю отдаёт объединение с потомками (descendants
+        // считает триггер schema_lineage). Запись остаётся строго по точному классу — см. M-WRITE.
+        const family = step.exactClass ? [step.cls.id] : [step.cls.id, ...step.cls.descendants];
+        /** Классы, реально попадающие в выборку: family минус запрещённые ACL. */
+        let classes = family;
+        /** Классы → их row-предикаты из ACL (у каждого потомка может быть своё правило). */
+        const aclFrags = new Map();
         const f = compileFilter(step.cls, step.filter, p);
         // модификаторы шага: .tags() / .account() / .owner()
         if (step.tagsFilter !== undefined) {
@@ -495,17 +520,27 @@ export function buildRead(ctx, steps, mods, mode) {
             f.candFrags.push(frag);
             f.finalFrags.push(frag);
         }
-        // enforceAcl: READ-право на КАЖДЫЙ шаг; предикат победившего правила — в WHERE заранее
+        // enforceAcl: READ-право на КАЖДЫЙ шаг. Шаг полиморфен, поэтому решение берётся по
+        // КОНКРЕТНОМУ классу каждой строки: запрещённые потомки выпадают из выборки, у каждого
+        // разрешённого свой row-предикат. Иначе deny на потомке обходился бы шагом по родителю.
         if (ctx.aclDecide) {
-            const d = ctx.aclDecide(step.cls, 'READ');
-            if (!d.allow)
-                throw aclDenied('READ', step.cls.id, d);
-            if (d.filter) {
-                for (const fr of rowTemplateFrags(d.filter, p)) {
-                    f.candFrags.push(fr);
-                    f.finalFrags.push(fr);
-                }
+            const own = ctx.aclDecide(step.cls, 'READ');
+            const allowed = [];
+            for (const id of family) {
+                const cd = ctx.registry.find(id);
+                if (!cd)
+                    continue;
+                const d = id === step.cls.id ? own : ctx.aclDecide(cd, 'READ');
+                if (!d.allow)
+                    continue;
+                allowed.push(id);
+                if (d.filter)
+                    aclFrags.set(id, rowTemplateFrags(d.filter, p));
             }
+            // ни один класс семейства не разрешён — отказ шага (как было для одиночного класса)
+            if (!allowed.length)
+                throw aclDenied('READ', step.cls.id, own);
+            classes = allowed;
         }
         // предикат WRITE/DELETE-правила (поиск целей записи): только свои строки
         if (step.aclFilter) {
@@ -514,11 +549,30 @@ export function buildRead(ctx, steps, mods, mode) {
                 f.finalFrags.push(fr);
             }
         }
-        const innerWhere = [`e.partition = ${pPart}`, `e.class = ${pCls}`];
+        // Условие по классу: один класс → быстрое равенство (план не меняется); семейство →
+        // OR-ветви, каждая со своим ACL-предикатом. Ставится и во внутренний WHERE, и в
+        // перепроверку на актуальной версии (finalFrags) — иначе предикат обходится версиями.
+        const poly = classes.length > 1;
+        const clsPh = new Map(classes.map((id) => [id, p.push(id)]));
+        const classFrag = (a) => classes
+            .map((id) => {
+            const preds = (aclFrags.get(id) ?? []).map((fr) => fr(a));
+            const eq = `${a}.class = ${clsPh.get(id)}`;
+            return preds.length ? `(${eq} AND ${preds.join(' AND ')})` : eq;
+        })
+            .join(' OR ');
+        const classCond = poly || aclFrags.size ? (a) => `(${classFrag(a)})` : classFrag;
+        // ТОЛЬКО в finalFrags: в candFrags нельзя — иначе кандидатный подзапрос появлялся бы
+        // на КАЖДОМ запросе (условие по классу непустое всегда), а он нужен лишь когда есть
+        // GIN-предикаты. В основной скан условие попадает через innerWhere ниже.
+        f.finalFrags.push(classCond);
+        const innerWhere = [`e.partition = ${pPart}`, classCond('e')];
         if (mods.asOf !== undefined)
             innerWhere.push(`e.updated <= ${p.push(mods.asOf)}::timestamptz`); // «как было на T»
-        // versions: последний шаг включает и удалённые сущности (история существует после delete)
-        const outerWhere = [mode === 'versions' && i === steps.length - 1 ? 'TRUE' : 't.deleted IS NULL'];
+        // versions/.withDeleted(): последний шаг включает и удалённые (история/tombstone видны после delete).
+        // Снимается ТОЛЬКО фильтр deleted — enforceAccount/enforceAcl/контекст-фраги ниже действуют (изоляция цела).
+        const keepDeleted = i === steps.length - 1 && (mode === 'versions' || mods.withDeleted === true);
+        const outerWhere = [keepDeleted ? 'TRUE' : 't.deleted IS NULL'];
         const candWhere = f.candFrags.map((fr) => fr('c'));
         for (const c of f.idConds)
             innerWhere.push(c('e'));
@@ -529,23 +583,35 @@ export function buildRead(ctx, steps, mods, mode) {
             const prev = steps[i - 1];
             const prevAlias = `h${real[i - 1]}`; // pivot: ветвление от узла-возврата
             const hop = resolveHop(prev.cls, step.cls);
+            // ключи Entity.links — ВСЕГДА конкретные id классов, не родительские. Поэтому при
+            // полиморфном шаге ключ берётся из колонки class самой строки, а не из литерала.
+            const prevPoly = prev.cls.descendants.length > 0;
             if (hop === 'forward') {
                 // id неизменен — условие сразу во внутренний WHERE, перепроверка не нужна
-                innerWhere.push(`e.id = ${prevAlias}.links->>${p.push(step.cls.id)}`);
+                innerWhere.push(poly
+                    ? `${prevAlias}.links @> jsonb_build_object(e.class::text, e.id)`
+                    : `e.id = ${prevAlias}.links->>${p.push(step.cls.id)}`);
             }
             else {
                 // reverse containment: кандидаты по GIN + перепроверка на latest
-                const pKey = p.push(prev.cls.id);
-                candWhere.push(`c.links @> jsonb_build_object(${pKey}::text, ${prevAlias}.id)`);
-                outerWhere.push(`t.links @> jsonb_build_object(${pKey}::text, ${prevAlias}.id)`);
+                const key = prevPoly ? `${prevAlias}.class::text` : `${p.push(prev.cls.id)}::text`;
+                candWhere.push(`c.links @> jsonb_build_object(${key}, ${prevAlias}.id)`);
+                outerWhere.push(`t.links @> jsonb_build_object(${key}, ${prevAlias}.id)`);
             }
         }
         if (candWhere.length) {
-            innerWhere.push(`e.id IN (SELECT c.id FROM ${ent} c WHERE c.partition = ${pPart} AND c.class = ${pCls} AND ${candWhere.join(' AND ')})`);
-        }
+            // подзапрос кандидатов нужен только при GIN-предикатах; класс добавляем здесь, а не
+            // через candFrags. При семействе id не уникален между классами → сопоставляем (class, id)
+            const cand = [classCond('c'), ...candWhere].join(' AND ');
+            innerWhere.push(poly
+                ? `(e.class, e.id) IN (SELECT c.class, c.id FROM ${ent} c WHERE c.partition = ${pPart} AND ${cand})`
+                : `e.id IN (SELECT c.id FROM ${ent} c WHERE c.partition = ${pPart} AND ${cand})`);
+        }
+        // «актуальная версия» — по (class, id) при семействе: один id может жить в разных классах
+        const dedupe = poly ? 'e.class, e.id' : 'e.id';
         let block = `(SELECT * FROM (` +
-            `SELECT DISTINCT ON (e.id) e.* FROM ${ent} e WHERE ${innerWhere.join(' AND ')} ` +
-            `ORDER BY e.id, e.updated DESC` +
+            `SELECT DISTINCT ON (${dedupe}) e.* FROM ${ent} e WHERE ${innerWhere.join(' AND ')} ` +
+            `ORDER BY ${dedupe}, e.updated DESC` +
             `) t WHERE ${outerWhere.join(' AND ')}) h${i}`;
         // .deep(): рекурсивный обход детей того же класса (recursive CTE поверх latest-паттерна)
         if (isDeep) {
@@ -554,19 +620,24 @@ export function buildRead(ctx, steps, mods, mode) {
                 throw new Error('letopis: .deep() works on a self hop (same class as previous step)');
             }
             const pMax = p.push(step.deepMax);
-            // latest живые дети узла ref (id-выражение родителя)
-            const kids = (ref) => `(SELECT * FROM (` +
-                `SELECT DISTINCT ON (e.id) e.* FROM ${ent} e WHERE e.partition = ${pPart} AND e.class = ${pCls}` +
-                (mods.asOf !== undefined ? ` AND e.updated <= ${p.push(mods.asOf)}::timestamptz` : '') +
-                ` AND e.id IN (SELECT c.id FROM ${ent} c WHERE c.partition = ${pPart} AND c.class = ${pCls}` +
-                ` AND c.links @> jsonb_build_object(${p.push(step.cls.id)}::text, ${ref}))` +
-                ` ORDER BY e.id, e.updated DESC) t` +
-                ` WHERE t.deleted IS NULL AND t.links @> jsonb_build_object(${p.push(step.cls.id)}::text, ${ref}))`;
+            // latest живые дети узла ref (id-выражение родителя); refCls — класс родителя:
+            // ключ links конкретен, поэтому при семействе берём его из колонки, а не из литерала
+            const kids = (ref, refCls) => {
+                const key = poly ? `${refCls}::text` : `${p.push(step.cls.id)}::text`;
+                return (`(SELECT * FROM (` +
+                    `SELECT DISTINCT ON (${dedupe}) e.* FROM ${ent} e WHERE e.partition = ${pPart} AND ${classCond('e')}` +
+                    (mods.asOf !== undefined ? ` AND e.updated <= ${p.push(mods.asOf)}::timestamptz` : '') +
+                    ` AND e.id IN (SELECT c.id FROM ${ent} c WHERE c.partition = ${pPart} AND ${classCond('c')}` +
+                    ` AND c.links @> jsonb_build_object(${key}, ${ref}))` +
+                    ` ORDER BY ${dedupe}, e.updated DESC) t` +
+                    ` WHERE t.deleted IS NULL AND t.links @> jsonb_build_object(${key}, ${ref}))`);
+            };
+            const prevA = `h${real[i - 1]}`;
             block =
                 `(WITH RECURSIVE d AS (` +
-                    `SELECT k.*, 1 AS depth FROM ${kids(`h${real[i - 1]}.id`)} k` +
+                    `SELECT k.*, 1 AS depth FROM ${kids(`${prevA}.id`, `${prevA}.class`)} k` +
                     ` UNION ALL ` +
-                    `SELECT k.*, d.depth + 1 FROM d JOIN LATERAL ${kids('d.id')} k ON true WHERE d.depth < ${pMax}::int` +
+                    `SELECT k.*, d.depth + 1 FROM d JOIN LATERAL ${kids('d.id', 'd.class')} k ON true WHERE d.depth < ${pMax}::int` +
                     `) SELECT * FROM d) h${i}`;
         }
         blocks.push(i === 0 ? `FROM ${block}` : `JOIN LATERAL ${block} ON true`);
@@ -575,6 +646,8 @@ export function buildRead(ctx, steps, mods, mode) {
     const fromClause = blocks.join('\n');
     const last = real[steps.length - 1]; // pivot в конце → терминал на его узле
     const lastCls = steps[steps.length - 1].cls;
+    /** Последний шаг полиморфен (есть потомки и не снят .exact()) — уникальность по (class, id). */
+    const lastPoly = !steps[steps.length - 1].exactClass && lastCls.descendants.length > 0;
     // ключи шагов в путях: alias → имя вызова; pivot узла не добавляет; дубликаты — _2, _3…
     const keyed = [];
     const seen = new Map();
@@ -604,8 +677,10 @@ export function buildRead(ctx, steps, mods, mode) {
         }
         case 'rows':
         case 'ids': {
-            const inner = `SELECT DISTINCT ON (h${last}.id) h${last}.* \n${fromClause}${whereOf(tailConds)}\n` +
-                `ORDER BY h${last}.id, h${last}.updated DESC`;
+            // при полиморфном последнем шаге уникальность сущности — пара (class, id)
+            const key = lastPoly ? `h${last}.class, h${last}.id` : `h${last}.id`;
+            const inner = `SELECT DISTINCT ON (${key}) h${last}.* \n${fromClause}${whereOf(tailConds)}\n` +
+                `ORDER BY ${key}, h${last}.updated DESC`;
             const sel = mode === 'rows' ? 'to_jsonb(z) AS row' : 'z.id';
             text =
                 `SELECT ${sel} FROM (${inner}) z` +
@@ -616,11 +691,13 @@ export function buildRead(ctx, steps, mods, mode) {
         }
         case 'versions': {
             // ВСЕ версии (включая tombstone) сущностей последнего шага, по возрастанию updated
-            const inner = `SELECT DISTINCT h${last}.id \n${fromClause}${whereOf(tailConds)}`;
+            // класс берём из найденной строки (а не литералом): при полиморфном шаге история
+            // собирается по КАЖДОМУ конкретному классу-потомку
+            const inner = `SELECT DISTINCT h${last}.class, h${last}.id \n${fromClause}${whereOf(tailConds)}`;
             text =
                 `SELECT to_jsonb(v) AS row FROM (${inner}) z ` +
-                    `JOIN ${ent} v ON v.partition = ${pPart} AND v.class = ${p.push(lastCls.id)} AND v.id = z.id ` +
-                    `ORDER BY v.id, v.updated` +
+                    `JOIN ${ent} v ON v.partition = ${pPart} AND v.class = z.class AND v.id = z.id ` +
+                    `ORDER BY v.class, v.id, v.updated` +
                     limitOffset;
             break;
         }
@@ -726,3 +803,18 @@ export function closureSql(pgSchema, n) {
      )
      SELECT DISTINCT ON (class, id) * FROM node ORDER BY class, id, updated DESC`);
 }
+/**
+ * Вызов серверной purge(): $4 dry → превью (актуальные версии замыкания, БД цела), иначе двухфазный
+ * физический снос корня+поддерева. RETURNS SETOF Entity (по строке на сущность). Вся логика
+ * (замыкание, двухфазность, отключение триггера через SET LOCAL) — в БД. $1 partition, $2 class, $3 id, $4 dry.
+ */
+// START_CONTRACT: purgeCallSql
+//   PURPOSE: SQL-обёртка вызова серверной purge() (снос/превью) — вся логика в БД, JS лишь зовёт.
+//   INPUTS: { pgSchema: string }
+//   OUTPUTS: { string - SELECT * FROM "<schema>".purge($1,$2,$3,$4) }
+//   SIDE_EFFECTS: none
+//   LINKS: M-SQL, V-M-SQL, M-DDL, M-WRITE
+// END_CONTRACT: purgeCallSql
+export function purgeCallSql(pgSchema) {
+    return `SELECT * FROM ${escId(pgSchema)}.purge($1, $2, $3, $4)`;
+}

package/dist/tables.d.ts

@@ -17,6 +17,12 @@ export interface AccountsApi {
     set(a: Partial<Account>): Promise<Account>;
     /** Физический DELETE; Credential снесётся FK-каскадом. */
     delete(id: string): Promise<boolean>;
+    /**
+     * Полный физический офбординг тенанта (необратимо): все Entity (account|owner=id) + сам Account
+     * (Credential — FK-каскад), через серверную purge_account(). Предохранители: только Owner/System-вызов;
+     * нельзя снести последний enabled Owner (лок-аут) и свой аккаунт. → true если Account снесён.
+     */
+    purge(id: string): Promise<boolean>;
 }
 export interface CredentialsApi {
     /** deleted IS NULL по умолчанию; withDeleted: true — включая удалённые. */
@@ -72,10 +78,28 @@ export interface RulesApi {
     }): Promise<Rule>;
     delete(account: string, resource: string): Promise<boolean>;
 }
+export interface SchemaApi {
+    /**
+     * Upsert определения класса в таблицу Schema (ON CONFLICT (partition,id) DO UPDATE) + reloadSchema().
+     * Правка «простым SQL», подхватывается сразу без реконнекта. attributes — DSL fastest-validator
+     * (валидирует либа при чтении реестра); ancestors/descendants считает триггер schema_lineage.
+     */
+    define(def: {
+        id: string;
+        alias: string;
+        category: 'HUB' | 'LINK';
+        ancestor?: string | null;
+        attributes?: Record<string, unknown>;
+        meta?: Record<string, unknown>;
+        links?: unknown[];
+        order?: number;
+    }): Promise<void>;
+}
 export interface Tables {
     accounts: AccountsApi;
     credentials: CredentialsApi;
     resources: ResourcesApi;
     rules: RulesApi;
+    schema: SchemaApi;
 }
 export declare function makeTables(ctx: Ctx): Tables;

package/dist/tables.js

@@ -1,3 +1,4 @@
+import { reservedNamesOf } from './types.js';
 const T = (ctx, name) => `"${ctx.pgSchema.replace(/"/g, '""')}"."${name}"`;
 // START_CONTRACT: where
 //   PURPOSE: Собрать SQL WHERE из простых equality-условий, добавляя значения в params.
@@ -85,6 +86,45 @@ export function makeTables(ctx) {
             const rows = await run(`DELETE FROM ${T(ctx, 'Account')} WHERE id = $1 RETURNING id`, [id]);
             return rows.length > 0;
         },
+        // START_CONTRACT: accounts.purge
+        //   PURPOSE: Физический офбординг тенанта через purge_account(); гарды Owner/System, последний Owner, не-себя — до сноса, в одной tx.
+        //   INPUTS: { id: string - целевой аккаунт }
+        //   OUTPUTS: { Promise<boolean> - true если Account физически снесён }
+        //   SIDE_EFFECTS: физ. DELETE всех Entity аккаунта + Account (Credential FK-каскад) через SQL purge_account()
+        //   ERRORS: нет caller/ACL; вызов не Owner/System; снос последнего Owner; снос своего аккаунта
+        //   LINKS: M-TABLES, V-M-TABLES, M-DDL
+        // END_CONTRACT: accounts.purge
+        async purge(id) {
+            if (!ctx.account) {
+                throw new Error('letopis: accounts.purge requires an authenticated caller — call it from a scoped handle: ' +
+                    '(await db.as(caller)).accounts.purge(id)');
+            }
+            if (id === ctx.account) {
+                throw new Error('letopis: accounts.purge cannot purge the calling account itself');
+            }
+            const schema = `"${ctx.pgSchema.replace(/"/g, '""')}"`;
+            return ctx.sql.begin(async (tsql) => {
+                const q = (t, p) => tsql.unsafe(t, p);
+                // вызывающий обязан быть Owner/System
+                const caller = await q(`SELECT categories FROM ${T(ctx, 'Account')} WHERE id = $1`, [ctx.account]);
+                const cats = caller[0]?.categories ?? [];
+                if (!cats.includes('Owner') && !cats.includes('System')) {
+                    throw new Error('letopis: accounts.purge is restricted to Owner/System accounts');
+                }
+                const tgt = await q(`SELECT categories FROM ${T(ctx, 'Account')} WHERE id = $1`, [id]);
+                if (!tgt.length)
+                    return false;
+                // нельзя снести последний enabled Owner → тенант без владельца (лок-аут)
+                if ((tgt[0].categories ?? []).includes('Owner')) {
+                    const cnt = await q(`SELECT count(*)::text AS n FROM ${T(ctx, 'Account')} WHERE 'Owner' = ANY(categories) AND enabled`, []);
+                    if (Number(cnt[0]?.n ?? 0) <= 1) {
+                        throw new Error('letopis: refusing to purge the last enabled Owner (tenant lock-out)');
+                    }
+                }
+                const res = await q(`SELECT ${schema}.purge_account($1::uuid) AS id`, [id]);
+                return res[0]?.id != null;
+            });
+        },
     };
     // END_BLOCK_ACCOUNTS_API
     // START_BLOCK_CREDENTIALS_API
@@ -181,5 +221,28 @@ export function makeTables(ctx) {
         },
     };
     // END_BLOCK_RULES_API
-    return { accounts, credentials, resources, rules };
+    // START_BLOCK_SCHEMA_API
+    const schema = {
+        async define(def) {
+            // класс с именем, которое Proxy разбирает до резолва класса, был бы недостижим как шаг
+            const clash = reservedNamesOf(def);
+            if (clash.length) {
+                throw new Error(`letopis: class name ${clash.map((n) => `"${n}"`).join(' / ')} is reserved by the chain API ` +
+                    `(a step under that name resolves to the method, not the class) — rename the ${clash.includes(def.id) ? 'id' : 'alias'}`);
+            }
+            // jsonb-значения через sql.json() — postgres.js кладёт как jsonb (не PG-массив/строку)
+            const j = (v) => ctx.sql.json(v);
+            await run(`INSERT INTO ${T(ctx, 'Schema')} (partition, id, alias, category, ancestor, attributes, meta, links, "order")
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+         ON CONFLICT (partition, id) DO UPDATE SET
+           alias = EXCLUDED.alias, category = EXCLUDED.category, ancestor = EXCLUDED.ancestor,
+           attributes = EXCLUDED.attributes, meta = EXCLUDED.meta, links = EXCLUDED.links, "order" = EXCLUDED."order"`, [
+                ctx.partition, def.id, def.alias, def.category, def.ancestor ?? null,
+                j(def.attributes ?? {}), j(def.meta ?? {}), j(def.links ?? []), def.order ?? 0,
+            ]);
+            await ctx.reload?.(); // подхватить новое определение сразу (registry + enforcer)
+        },
+    };
+    // END_BLOCK_SCHEMA_API
+    return { accounts, credentials, resources, rules, schema };
 }

package/dist/types.d.ts

@@ -125,12 +125,12 @@ export interface Cursor {
  * Терминал исполняет план (все операции + финальное чтение) одной транзакцией.
  */
 export interface PlanOp {
-    kind: 'create' | 'update' | 'delete' | 'anonymize';
+    kind: 'create' | 'update' | 'delete' | 'anonymize' | 'purge';
     /** create/update: данные новой версии (deep-merge листьев). */
     data?: Record<string, unknown>;
     /** anonymize: string-поля под '[erased]'. */
     fields?: string[];
-    /** delete: true — удалить; без confirm — превью (вернуть кандидатов, БД не трогать). */
+    /** delete/purge: true — выполнить; без confirm — превью (вернуть кандидатов/замыкание, БД не трогать). */
     confirm?: boolean;
     /** Снапшот модификаторов на момент вызова операции (limit/sort для поиска целей). */
     mods: ChainMods;
@@ -149,6 +149,8 @@ export interface ChainMods {
     /** Внутреннее: агрегация терминалов .sum/.avg/.min/.max/.countBy. */
     aggFn?: 'sum' | 'avg' | 'min' | 'max' | 'countBy';
     aggField?: string;
+    /** .withDeleted(): последний шаг включает удалённые (tombstone). Снимает ТОЛЬКО фильтр deleted; enforceAccount/enforceAcl действуют. */
+    withDeleted?: boolean;
 }
 export interface Account {
     id: string;
@@ -222,20 +224,28 @@ export interface ConnectOpts {
     schema: string;
     /** Партиция данных. Default 'entity'. */
     partition?: string;
-    /** Дефолтный account для записей. */
-    account?: string;
-    /** Дефолтный owner для записей. Default = account. */
-    owner?: string;
     /** Размер пула соединений. Default 10. */
     max?: number;
-    /** Жёсткая изоляция арендатора: чтения фильтруются по account, записи пришпилены к нему. */
+    /**
+     * Жёсткая изоляция арендатора: чтения фильтруются по account, записи пришпилены к нему.
+     * **Default true** (с 0.20.0). Идентичность берётся у хендла `db.as(account)`; на
+     * безличном (корневом) хендле чтение/запись при включённой изоляции — ошибка с подсказкой.
+     * Явный `.account(чужой)` на scoped-хендле — тоже ошибка.
+     * Выключать (`false`) осмысленно лишь для админских/сервисных подключений,
+     * которым нужен доступ ко всем арендаторам.
+     */
     enforceAccount?: boolean;
     /**
      * ACL по Resource/Rule: категории READ/WRITE/DELETE, pattern — шаблон строки Entity
      * (колонки + "$account"). Каждый шаг цепочки проверяется на READ, записи — WRITE,
      * delete — DELETE (включая классы каскада); предикат победившего правила вливается
-     * в SQL до сортировки/лимита. Требует account. Deny-by-default.
-     * Правила читаются один раз при connect (перечитка — новый connect).
+     * в SQL до сортировки/лимита. Субъект даёт db.as() (энфорсер компилится на scope).
+     * Deny-by-default.
+     * **Default false** — остаётся opt-in: включённый по умолчанию deny-by-default без
+     * настроенных Resource/Rule давал бы пустые выборки. Пока выключен, connect() один раз
+     * на процесс печатает предупреждение.
+     * Правила снимаются на connect и компилятся в memo-энфорсер; перечитать без
+     * реконнекта — db.reloadSchema() (пересобирает и реестр, и ACL-резолвер).
      */
     enforceAcl?: boolean;
     /** Хук на каждый запрос цепочки (метрики, лог). */
@@ -243,3 +253,18 @@ export interface ConnectOpts {
     /** Порог «медленного» запроса, мс: событие получает slow: true; без onQuery — console.warn. */
     slowMs?: number;
 }
+/**
+ * Имена, которые Proxy цепочки/db разбирает ДО резолва класса, поэтому класс с таким
+ * id/alias НЕДОСТИЖИМ как шаг под этим именем (`db.Клиент(c).link()` уйдёт в
+ * migration-ошибку `.link() removed`, а не в класс `link`).
+ *
+ * Источник истины — `case`-метки switch'ей в chain.ts; совпадение с этим списком
+ * проверяет scripts/check-docs.mjs. Используется как гвард: schema.define() отказывает,
+ * loadRegistry предупреждает.
+ */
+export declare const RESERVED_CLASS_NAMES: readonly string[];
+/** Зарезервированные имена класса среди {id, alias}; пусто — конфликта нет. */
+export declare function reservedNamesOf(def: {
+    id: string;
+    alias?: string;
+}): string[];

package/dist/types.js

@@ -3,7 +3,7 @@
  */
 //
 // FILE: lib/src/types.ts
-// VERSION: 1.0.0
+// VERSION: 1.3.0
 // START_MODULE_CONTRACT
 //   PURPOSE: Общий словарь типов всей библиотеки letopis.
 //   SCOPE: сущности, пути, определения классов, типы полей, фильтры и операторы, курсоры/план записи/модификаторы цепочки, записи auth/ACL, событие запроса и опции connect + символ OP.
@@ -35,11 +35,16 @@
 //   AclOp - операция над данными = категория Resource: 'READ' | 'WRITE' | 'DELETE'.
 //   AclDecision - решение ACL: allow + победившее правило + остаточный filter + code/message.
 //   QueryEvent - событие хука onQuery: режим, классы, ms, rows, slow.
-//   ConnectOpts - опции connect(): dsn/schema/partition/account/owner/max/enforceAccount/enforceAcl/onQuery/slowMs.
+//   ConnectOpts - опции connect(): dsn/schema/partition/max/enforceAccount/enforceAcl/onQuery/slowMs (account/owner — не здесь, их даёт db.as()).
+//   RESERVED_CLASS_NAMES - имена, перехватываемые Proxy до резолва класса (шаг недостижим под этим именем).
+//   reservedNamesOf - зарезервированные имена среди {id, alias} определения класса.
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+//   LAST_CHANGE: [v1.3.0 - BREAKING: из ConnectOpts удалены account/owner (арендатор — свойство
+//     ВЫЗОВА: db.as(account, { owner })); 'as' добавлен в RESERVED_CLASS_NAMES → 52 имени.
+//     Ранее: 'link' убран из RESERVED_CLASS_NAMES (охранник цепочки снят, имя снова
+//     резолвится как класс); enforceAccount задокументирован как Default true]
 // END_CHANGE_SUMMARY
 //
 // START_BLOCK_ENTITY_TYPES
@@ -49,3 +54,35 @@
 /** Метка операторов фильтра (Symbol — не конфликтует с данными). */
 export const OP = Symbol('letopis.op');
 // END_BLOCK_CONNECT_TYPES
+// START_BLOCK_RESERVED_NAMES
+/**
+ * Имена, которые Proxy цепочки/db разбирает ДО резолва класса, поэтому класс с таким
+ * id/alias НЕДОСТИЖИМ как шаг под этим именем (`db.Клиент(c).link()` уйдёт в
+ * migration-ошибку `.link() removed`, а не в класс `link`).
+ *
+ * Источник истины — `case`-метки switch'ей в chain.ts; совпадение с этим списком
+ * проверяет scripts/check-docs.mjs. Используется как гвард: schema.define() отказывает,
+ * loadRegistry предупреждает.
+ */
+export const RESERVED_CLASS_NAMES = [
+    // все три Proxy: then гасится, чтобы цепочка не выглядела thenable для await
+    'then',
+    // chain-уровень (makeChain handler)
+    'entity', 'run', 'execute', 'rows', 'first', 'ids', 'count', 'limit', 'offset', 'sort',
+    'asOf', 'withDeleted', 'deep', 'exact', 'sum', 'avg', 'min', 'max', 'countBy', 'after', 'versions',
+    'create', 'update', 'set', 'delete', 'anonymize', 'purge', 'alias', 'tags', 'account',
+    'owner',
+    // db-уровень (makeDb handler): switch …
+    'as', 'begin', 'commit', 'rollback', 'lock', 'batch', 'watch', 'close', 'reloadSchema',
+    'registry', 'sql',
+    // … и фасады, которые разбираются if'ами ДО switch (служебные таблицы, auth, acl)
+    'accounts', 'credentials', 'resources', 'rules', 'schema', 'auth', 'acl',
+    // batch-уровень (makeBatch handler)
+    'discard', 'size',
+];
+/** Зарезервированные имена класса среди {id, alias}; пусто — конфликта нет. */
+export function reservedNamesOf(def) {
+    const set = new Set(RESERVED_CLASS_NAMES);
+    return [def.id, def.alias].filter((n) => !!n && set.has(n));
+}
+// END_BLOCK_RESERVED_NAMES

package/dist/up.js

@@ -6,7 +6,7 @@
  *   const db = await up({ schema: 'booking', version: 1 });   // → PG-схема "v1.booking"
  */
 // FILE: lib/src/up.ts
-// VERSION: 1.0.0
+// VERSION: 1.1.0
 // START_MODULE_CONTRACT
 //   PURPOSE: Dev-bootstrap — поднять Docker-контейнер Postgres (TimescaleDB) + Redis, обеспечить базу, накатить DDL-схему и сиды, дождаться готовности и подключиться.
 //   SCOPE: валидация схемы/версии; проба postgres; docker build/run/start контейнера; создание базы; ожидание готовности PG и Redis; применение схемы + сиды; connect
@@ -26,11 +26,14 @@
 //   pgPing - (local) проба postgres: ok | no-server | no-database | starting | fatal
 //   ensureDatabase - (local) создать базу, если её нет (гонка 42P04 глушится)
 //   tcpAlive - (local) TCP-проба хоста:порта (для redis)
-//   applySchema - (local) drop (fresh) -> накат ddl+сидов с подстановкой <SCHEMA-NAME>
+//   applySchema - (local) drop (fresh) -> накат ddl+сидов с подстановкой <SCHEMA-NAME> -> ANALYZE Entity
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+//   LAST_CHANGE: [v1.1.0 - applySchema делает ANALYZE Entity после наката: у гипертаблицы нет
+//     статистики родителя, и планировщик оценивает подзапрос кандидатов в 200 строк — выбирался
+//     Nested Loop, чтения были медленнее до x18 (замер в README 14.1).
+//     Ранее: Documented existing module: reverse-engineered contract + markup]
 // END_CHANGE_SUMMARY
 //
 import { execFile } from 'node:child_process';
@@ -207,7 +210,15 @@ async function applySchema(dsn, full, seeds, fresh, log) {
             const text = (await readFile(f, 'utf8')).replaceAll('<SCHEMA-NAME>', full);
             await sql.unsafe(text); // multi-statement simple query
         }
-        log(`schema "${full}" applied (${files.length} files)`);
+        // START_BLOCK_ANALYZE_ENTITY
+        // ANALYZE обязателен: Entity — гипертаблица, у РОДИТЕЛЯ своих строк нет, и без статистики
+        // планировщик берёт дефолт «200 уникальных id». Ядро всех чтений либы — semi-join с
+        // подзапросом кандидатов (`e.id IN (SELECT c.id …)`), и на оценке 200 вместо сотен тысяч
+        // он выбирает Nested Loop: на полигоне 980k это давало 57 с вместо 3 с (×18).
+        // Стоит копейки на свежей схеме; после МАССОВОЙ заливки данных ANALYZE нужно повторить.
+        await sql.unsafe(`ANALYZE ${qi(full)}."Entity"`);
+        // END_BLOCK_ANALYZE_ENTITY
+        log(`schema "${full}" applied (${files.length} files, statistics collected)`);
     }
     finally {
         await sql.end();

package/dist/write.d.ts

@@ -56,6 +56,15 @@ export declare function anonymizeOp(ctx: Ctx, steps: Step[], mods: ChainMods, fi
  * Без confirm — ПРЕВЬЮ: то же замыкание (цели + каскад), но БД не трогается.
  */
 export declare function delOp(ctx: Ctx, steps: Step[], mods: ChainMods, confirm: boolean): Promise<Row[]>;
+/**
+ * .purge({confirm}): ФИЗИЧЕСКИЙ hard-erase — сносит логически удалённые цели + всё поддерево (все версии).
+ * Вся логика — в серверной purge() (двухфазность: живую цель не трогает; замыкание по links; SET LOCAL
+ * отключает entity_delete → плоский снос без TM_SelfModified). JS лишь резолвит цели и зовёт функцию.
+ * confirm: false → dry-превью (что сотрётся, БД цела); true → снос, возвращает снесённое ($deleted).
+ * gate: DELETE-право на класс цели (aclWrite) — поддерево уже было DELETE-авторизовано при мягком удалении.
+ * В отличие от .delete() (tombstone, обратимо) — необратимо, историю НЕ сохраняет.
+ */
+export declare function purgeOp(ctx: Ctx, steps: Step[], mods: ChainMods, confirm: boolean): Promise<Row[]>;
 export type PlanMode = 'rows' | 'ids' | 'count' | 'paths' | 'versions' | 'agg';
 /**
  * Исполнить план целиком: все операции + финальное чтение — одна транзакция