letopis 0.18.1 → 0.20.0

package/dist/acl.d.ts

@@ -33,7 +33,11 @@ export interface AclApi {
     checkData(account: string | {
         id: string;
     }, className: string, op: AclOp): Promise<AclDecision>;
-    /** Сбросить кэш Resource/Rule фасада (enforceAcl-цепочки перечитывают только новым connect). */
+    /**
+     * Сбросить кэш Resource/Rule ЭТОГО фасада (db.acl.check/checkData).
+     * NB: энфорсер цепочек под `enforceAcl` — отдельная подсистема; его пересобирает
+     * `db.reloadSchema()` (реестр + ACL-резолвер), а не этот reload().
+     */
     reload(): void;
 }
 interface AclSource {
@@ -41,7 +45,8 @@ interface AclSource {
     rules: Rule[];
 }
 export declare function makeAcl(tables: Tables, registry: Registry): AclApi;
-/** Синхронный резолвер для цепочек: категории субъекта и правила зафиксированы на connect. */
+/** Синхронный резолвер для цепочек: категории субъекта и правила — снимок на момент
+ *  компиляции (connect либо db.reloadSchema(), который пересобирает энфорсер). */
 export declare function compileEnforcer(src: AclSource, account: string, cats: string[], registry: Registry): (cls: ClassDef, op: AclOp) => AclDecision;
 /** Читаемая ошибка отказа для цепочек. */
 export declare function aclDenied(op: AclOp, clsId: string, d: AclDecision): Error;

package/dist/acl.js

@@ -232,13 +232,14 @@ export function makeAcl(tables, registry) {
 }
 // --- enforce-компилятор (connect({enforceAcl: true})) ----------------------------
 // START_CONTRACT: compileEnforcer
-//   PURPOSE: Скомпилировать синхронный энфорсер (ClassDef, op) → AclDecision с мемоизацией — субъект и правила зафиксированы на connect.
+//   PURPOSE: Скомпилировать синхронный энфорсер (ClassDef, op) → AclDecision с мемоизацией — субъект и правила снимаются В МОМЕНТ вызова (на connect либо на db.reloadSchema()).
 //   INPUTS: { src: AclSource; account: string; cats: string[]; registry: Registry }
 //   OUTPUTS: { (cls: ClassDef, op: AclOp) => AclDecision }
 //   SIDE_EFFECTS: none (мемо-кэш решений)
 //   LINKS: M-ACL, V-M-ACL, M-SQL, M-WRITE
 // END_CONTRACT: compileEnforcer
-/** Синхронный резолвер для цепочек: категории субъекта и правила зафиксированы на connect. */
+/** Синхронный резолвер для цепочек: категории субъекта и правила — снимок на момент
+ *  компиляции (connect либо db.reloadSchema(), который пересобирает энфорсер). */
 export function compileEnforcer(src, account, cats, registry) {
     // START_BLOCK_ENFORCER_MEMO
     const subjects = subjectAliases(src.resources, cats);

package/dist/chain.d.ts

@@ -33,10 +33,23 @@ export interface ChainCore {
     asOf(t: string | Date): Chain;
     /** Keyset-пагинация: строго после курсора (см. cursorOf). Требует .sort(). */
     after(cursor: import('./types.js').Cursor): Chain;
+    /**
+     * Включить в выдачу последнего шага удалённые (tombstone). Снимает ТОЛЬКО фильтр deleted —
+     * изоляция арендатора (enforceAccount) и ACL (enforceAcl) остаются в силе.
+     */
+    withDeleted(): Chain;
     /** ВСЕ версии сущностей последнего шага (включая tombstone → $deleted), по возрастанию updated. */
     versions(): Promise<Row[]>;
     /** Рекурсивный self-обход: дети любой глубины (тот же класс), $depth в Row. */
     deep(max?: number): Chain;
+    /**
+     * Только ЭТОТ класс, без классов-потомков. По умолчанию шаг полиморфен: родитель отдаёт
+     * объединение с потомками (`db.Контрагент()` → Мастера + Клиенты). `.exact()` нужен, когда
+     * наследование в домене — переиспользование attributes, а не «is-a» для выборки:
+     * в демо `запись` наследует `окно`, но смена ≠ бронь, поэтому «смены мастера» —
+     * `db.Мастер(id).окно().exact()`.
+     */
+    exact(): Chain;
     /** Агрегации по полю последнего шага ('data.<путь>'), считает БД. */
     sum(field: string): Promise<number | null>;
     avg(field: string): Promise<number | null>;
@@ -89,6 +102,15 @@ export interface ChainCore {
     delete(opts?: {
         confirm?: boolean;
     }): Chain;
+    /**
+     * ФИЗИЧЕСКИЙ hard-erase (необратимо): сносит УЖЕ логически удалённые (tombstone) цели + всё
+     * поддерево по links (все версии). Живую сущность не трогает — сначала .delete(). { confirm: true }
+     * — стирает; без confirm — превью замыкания (что сотрётся), БД не тронута. Историю НЕ сохраняет
+     * (в отличие от .delete()). Реализуется серверной purge() (SET LOCAL letopis.purge отключает триггер).
+     */
+    purge(opts?: {
+        confirm?: boolean;
+    }): Chain;
 }
 /**
  * Свойство-класс на цепочке:
@@ -111,6 +133,23 @@ export type Chain = ChainCore & {
     [className: string]: StepProp;
 };
 export interface DbCore {
+    /**
+     * Идентичность ВЫЗОВА: хендл того же пула, работающий от имени account.
+     * Арендатор — свойство вызова, а не подключения (в connect() опции account нет):
+     *
+     *   const db = await connect({ dsn, schema })   // пул, безличный
+     *   const t  = await db.as(req.accountId)       // кто именно делает этот вызов
+     *   await t.Клиент().rows()                     // изолировано по account
+     *
+     * При enforceAccount (default) чтение/запись возможны только с такого хендла.
+     * При enforceAcl энфорсер компилится под ЭТОГО субъекта (у каждого scope свой).
+     * owner по умолчанию = account; переопределяется вторым аргументом.
+     */
+    as(account: string | {
+        id: string;
+    }, opts?: {
+        owner?: string;
+    }): Promise<EntityDb>;
     /** Открыть транзакцию: tr — тот же API + commit/rollback/lock. */
     begin(): Promise<EntityTx>;
     commit(tr: EntityTx): Promise<void>;
@@ -126,6 +165,11 @@ export interface DbCore {
     watch(cb: (e: WatchEvent) => void, opts?: WatchOpts): Promise<() => void>;
     watch(cls: string, cb: (e: WatchEvent) => void, opts?: WatchOpts): Promise<() => void>;
     close(): Promise<void>;
+    /**
+     * Перечитать определения классов из таблицы Schema (после правки её простым SQL / db.schema.define):
+     * пересобирает registry и, при enforceAcl, ACL-резолвер — без реконнекта. Подхват «сразу».
+     */
+    reloadSchema(): Promise<void>;
     registry: Registry;
     /** Голый postgres-клиент (тесты, EXPLAIN). */
     sql: Ctx['sql'];
@@ -134,6 +178,8 @@ export interface DbCore {
     credentials: Tables['credentials'];
     resources: Tables['resources'];
     rules: Tables['rules'];
+    /** Определения классов: db.schema.define(def) — upsert в таблицу Schema + reloadSchema(). */
+    schema: Tables['schema'];
     /** Вход по кредам (пароль/api-key/key-secret/внешние identity) + сессии в Redis. */
     auth: AuthApi;
     /** ACL по Resource/Rule: check(эндпоинт) / checkData(класс, READ|WRITE|DELETE) / reload. */

package/dist/chain.js

@@ -354,8 +354,13 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
                     return (field, dir) => withMods({ order: field, desc: dir === true || dir === 'desc' });
                 case 'asOf':
                     return (t) => withMods({ asOf: t instanceof Date ? t.toISOString() : t });
+                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':
@@ -434,6 +439,8 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
                     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
                 case 'alias':
@@ -444,8 +451,10 @@ function makeChain(ctx, steps, mods, batch, nodes = NO_NODES) {
                     return (v) => withLast({ accountFilter: typeof v === 'object' ? v.id : v });
                 case 'owner':
                     return (v) => withLast({ ownerFilter: typeof v === 'object' ? v.id : v });
-                case 'link':
-                    throw new Error('letopis: .link() removed (0.15.0) — use the link slot: .Класс.set(target)');
+                // NB: охранника `case 'link'` здесь больше нет (снят в 0.20.0). Он затенял РЕАЛЬНЫЙ
+                // класс схемы: в демо-домене `link` — абстрактный корень всех связок, и шаг
+                // db.Клиент(c).link() падал migration-ошибкой вместо обхода. Обратная совместимость
+                // со снесённым в 0.15.0 методом .link() принесена в жертву достижимости класса.
                 // END_BLOCK_COLUMN_MODS
             }
             // START_BLOCK_CLASS_RESOLVE
@@ -512,7 +521,7 @@ export function makeDb(ctx, root) {
             if (typeof prop === 'symbol' || prop === 'then')
                 return undefined;
             // START_BLOCK_TABLES_AUTH_ACL
-            if (prop === 'accounts' || prop === 'credentials' || prop === 'resources' || prop === 'rules') {
+            if (prop === 'accounts' || prop === 'credentials' || prop === 'resources' || prop === 'rules' || prop === 'schema') {
                 tables ??= makeTables(ctx);
                 return tables[prop];
             }
@@ -528,6 +537,27 @@ export function makeDb(ctx, root) {
             }
             // 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);
@@ -607,6 +637,11 @@ export function makeDb(ctx, root) {
                 // 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':

package/dist/index.d.ts

@@ -1,8 +1,13 @@
 /**
  * letopis: dot-цепочки над append-only Entity-хранилищем (TimescaleDB).
  *
- *   const db = await connect({ dsn, schema: 'booking' })
- *   await db.Сотрудник({ name: 'Вася' }).навык().Услуга().run()
+ * schema — ПОЛНОЕ имя PG-схемы С версией движка ("v1.booking"); префикс либа НЕ достраивает
+ * (создаёт up({ schema: 'booking', version: 1 }) либо db/apply.mjs). Шаг цепочки — id ИЛИ
+ * alias класса из таблицы Schema (db.Staff ≡ db.Мастер).
+ *
+ *   const db = await connect({ dsn, schema: 'v1.booking' })   // безличный пул
+ *   const t  = await db.as(accountId)                          // арендатор ВЫЗОВА
+ *   await t.Мастер({ name: 'Вася' }).навык().Услуга().run()
  */
 import { type EntityDb } from './chain.js';
 import type { ConnectOpts } from './types.js';
@@ -15,7 +20,7 @@ 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';
-export type { Tables, AccountsApi, CredentialsApi, ResourcesApi, RulesApi } from './tables.js';
+export type { Tables, AccountsApi, CredentialsApi, ResourcesApi, RulesApi, SchemaApi } from './tables.js';
 export { totpCode } from './auth.js';
 export type { AuthApi, AuthResult } from './auth.js';
 export type { AclApi } from './acl.js';

package/dist/index.js

@@ -1,11 +1,16 @@
 /**
  * letopis: dot-цепочки над append-only Entity-хранилищем (TimescaleDB).
  *
- *   const db = await connect({ dsn, schema: 'booking' })
- *   await db.Сотрудник({ name: 'Вася' }).навык().Услуга().run()
+ * schema — ПОЛНОЕ имя PG-схемы С версией движка ("v1.booking"); префикс либа НЕ достраивает
+ * (создаёт up({ schema: 'booking', version: 1 }) либо db/apply.mjs). Шаг цепочки — id ИЛИ
+ * alias класса из таблицы Schema (db.Staff ≡ db.Мастер).
+ *
+ *   const db = await connect({ dsn, schema: 'v1.booking' })   // безличный пул
+ *   const t  = await db.as(accountId)                          // арендатор ВЫЗОВА
+ *   await t.Мастер({ name: 'Вася' }).навык().Услуга().run()
  */
 // FILE: lib/src/index.ts
-// VERSION: 1.0.0
+// VERSION: 1.2.0
 // START_MODULE_CONTRACT
 //   PURPOSE: Публичная точка входа пакета — открыть соединение (реестр, опциональный ACL, сборка db) и ре-экспорт публичной поверхности; хелпер курсора.
 //   SCOPE: connect, cursorOf + barrel-реэкспорты
@@ -22,7 +27,10 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+//   LAST_CHANGE: [v1.2.0 - BREAKING: opts.account/opts.owner сняты — подключение безличное,
+//     арендатора и субъекта ACL называет db.as(account, { owner }). Компиляция энфорсера
+//     вынесена в ctx.compileAcl(ctx-scope), ctx.reload обновляет только реестр.
+//     Ранее: enforceAccount по умолчанию true; предупреждение при выключенном enforceAcl]
 // END_CHANGE_SUMMARY
 import postgres from 'postgres';
 import { loadRegistry } from './schema.js';
@@ -30,12 +38,14 @@ 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 ре-экспортится здесь)
+//   PURPOSE: Открыть БЕЗЛИЧНОЕ соединение: postgres-пул, реестр схемы, System-аккаунт, хук компиляции ACL — и собрать EntityDb (арендатора вызова называет db.as()).
+//   INPUTS: { opts: ConnectOpts { dsn, schema, partition?='entity', max?=10, enforceAcl?, enforceAccount?=true, onQuery?, slowMs? } }
+//   OUTPUTS: { Promise<EntityDb> - dot-цепочный db без идентичности; db.as(account) даёт scoped-хендл }
+//   SIDE_EFFECTS: открывает пул postgres (timestamptz строкой), читает реестр и System-аккаунт; ставит ctx.compileAcl (зовётся из db.as: читает resources/rules и компилит aclDecide под субъекта scope; при ненайденном аккаунте — 'letopis: enforceAcl — account "…" not found'); без enforceAcl печатает предупреждение один раз на процесс; 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
+/** Предупреждение об отключённом enforceAcl печатается один раз на процесс. */
+let warnedNoAcl = false;
 export async function connect(opts) {
     // timestamptz — строкой (JS Date режет микросекунды → ломал бы asOf/cursorOf по updated)
     const sql = postgres(opts.dsn, {
@@ -52,28 +62,49 @@ export async function connect(opts) {
         registry,
         pgSchema: opts.schema,
         partition,
-        account: opts.account,
-        owner: opts.owner,
+        // account/owner тут НЕ задаются: подключение безличное, арендатора называет db.as().
         systemAccount: sys[0]?.id,
-        enforceAccount: opts.enforceAccount,
+        // Изоляция арендатора ВКЛЮЧЕНА по умолчанию (0.20.0): забыть её было слишком легко,
+        // а цена забывчивости — чужие строки в выдаче. Без идентичности вызова (корневой
+        // хендл) чтение/запись при ней запрещены — см. guardScoped в sql.ts.
+        enforceAccount: opts.enforceAccount ?? true,
         onQuery: opts.onQuery,
         slowMs: opts.slowMs,
     };
     // START_BLOCK_ENFORCE_ACL
-    // enforceAcl: правила и категории субъекта фиксируются на connect (перечитка — новый connect)
-    if (opts.enforceAcl) {
-        if (!opts.account)
-            throw new Error('letopis: enforceAcl requires connect({ account })');
-        const tables = makeTables(ctx);
+    // enforceAcl: правила и категории субъекта компилятся в резолвер ПОД КОНКРЕТНЫЙ scope.
+    // Функция живёт на ctx, потому что зовут её двое: db.as() (новый субъект) и reload
+    // (тот же субъект на свежем реестре). Субъект берётся из c.account, т.е. из scope.
+    ctx.compileAcl = async (c) => {
+        if (!opts.enforceAcl)
+            return;
+        if (!c.account)
+            throw new Error('letopis: enforceAcl is on — call db.as(account) to name the subject');
+        const tables = makeTables(c);
         const [account, resources, rules] = await Promise.all([
-            tables.accounts.get(opts.account),
+            tables.accounts.get(c.account),
             tables.resources.find(),
             tables.rules.find({ enabled: true }),
         ]);
         if (!account)
-            throw new Error(`letopis: enforceAcl — account "${opts.account}" not found`);
-        ctx.aclDecide = compileEnforcer({ resources, rules }, account.id, account.categories, registry);
+            throw new Error(`letopis: enforceAcl — account "${c.account}" not found`);
+        c.aclDecide = compileEnforcer({ resources, rules }, account.id, account.categories, c.registry);
+    };
+    // enforceAcl остаётся OPT-IN: включить его по умолчанию нельзя (он работает
+    // deny-by-default, т.е. без настроенных Resource/Rule выдача стала бы пустой).
+    // Поэтому — предупреждение: молчаливое отсутствие авторизации хуже шумного.
+    // Один раз на процесс, иначе утонет в логах приложения с пулом подключений.
+    if (!opts.enforceAcl && !warnedNoAcl) {
+        warnedNoAcl = true;
+        console.warn('letopis: enforceAcl is off — Resource/Rule are NOT checked, reads and writes pass ' +
+            'authorization unconditionally. For production use connect({ enforceAcl: true }) + db.as(account).');
     }
+    // db.reloadSchema(): перечитать определения классов из таблицы Schema без реконнекта.
+    // На корневом хендле обновляется только реестр (субъекта тут нет); scoped-хендлы
+    // подхватывают его и перекомпилируют свой энфорсер сами (chain.ts, case 'as').
+    ctx.reload = async () => {
+        ctx.registry = await loadRegistry(sql, opts.schema, partition);
+    };
     // END_BLOCK_ENFORCE_ACL
     return makeDb(ctx);
 }

package/dist/schema.js

@@ -9,7 +9,7 @@
  */
 //
 // FILE: lib/src/schema.ts
-// VERSION: 1.0.0
+// VERSION: 1.1.0
 // START_MODULE_CONTRACT
 //   PURPOSE: Строит реестр классов из таблицы Schema — резолв наследования/link-ends, типы полей, компиляция валидаторов.
 //   SCOPE: Registry (add/find/resolve/has), loadRegistry, fieldTypeOf; локальные parseEnd/parseIdGen/buildDef.
@@ -26,9 +26,11 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+//   LAST_CHANGE: [v1.1.0 - loadRegistry: 42P01/3F000 перехватываются и заменяются адресной ошибкой
+//     (передано базовое имя вместо "vN.имя") со списком letopis-схем — паритет с валидацией up()]
 // END_CHANGE_SUMMARY
 import { createRequire } from 'node:module';
+import { reservedNamesOf } from './types.js';
 const Validator = createRequire(import.meta.url)('fastest-validator');
 const v = new Validator({ useNewCustomCheckerFunction: true });
 export class Registry {
@@ -288,15 +290,34 @@ function buildDef(row, byId) {
 //   PURPOSE: Прочитать классы партиции из таблицы Schema и построить Registry со скомпилированными check.
 //   INPUTS: { sql: postgres.Sql; pgSchema: string; partition: string }
 //   OUTPUTS: { Promise<Registry> - реестр всех классов партиции }
-//   SIDE_EFFECTS: SELECT из "<pgSchema>"."Schema"
-//   ERRORS: schema has no classes for partition
+//   SIDE_EFFECTS: SELECT из "<pgSchema>"."Schema"; на 42P01/3F000 — доп. SELECT списка схем для подсказки
+//   ERRORS: schema has no classes for partition; schema has no "Schema" table (передано базовое имя вместо "vN.имя")
 //   LINKS: M-SCHEMA, V-M-SCHEMA, M-DDL
 // END_CONTRACT: loadRegistry
+/** Уже предупреждённые «схема:класс» — чтобы не повторять на каждый connect/reloadSchema. */
+const warnedReserved = new Set();
 export async function loadRegistry(sql, pgSchema, partition) {
     // START_BLOCK_LOAD_QUERY
     const ident = `"${pgSchema.replace(/"/g, '""')}"`;
-    const rows = (await sql.unsafe(`SELECT id, alias, category, ancestor, attributes, links, meta, "order", ancestors, descendants
-       FROM ${ident}."Schema" WHERE partition = $1 ORDER BY category, "order"`, [partition]));
+    let rows;
+    try {
+        rows = (await sql.unsafe(`SELECT id, alias, category, ancestor, attributes, links, meta, "order", ancestors, descendants
+         FROM ${ident}."Schema" WHERE partition = $1 ORDER BY category, "order"`, [partition]));
+    }
+    catch (e) {
+        // 42P01 undefined_table / 3F000 invalid_schema_name — типовая ошибка: передали БАЗОВОЕ имя
+        // ('booking') вместо полного с версией ('v1.booking'). Подсказываем вместо сырой ошибки PG.
+        const code = e.code;
+        if (code !== '42P01' && code !== '3F000')
+            throw e;
+        // перечисляем ТОЛЬКО схемы letopis (те, где есть таблица Schema), а не все namespace БД
+        const found = (await sql.unsafe(`SELECT table_schema AS s FROM information_schema.tables
+         WHERE table_name = 'Schema' ORDER BY 1`));
+        throw new Error(`letopis: schema "${pgSchema}" has no "Schema" table — connect({ schema }) takes the FULL ` +
+            `PG-schema name WITH the engine version ("v1.booking"); the library adds no prefix. ` +
+            `letopis schemas here: ${found.map((r) => r.s).join(', ') || '(none)'}. ` +
+            `Create one with up({ schema, version }) or db/apply.mjs --schema=… --version=…`);
+    }
     if (!rows.length) {
         throw new Error(`letopis: schema "${pgSchema}" has no classes for partition "${partition}"`);
     }
@@ -305,5 +326,26 @@ export async function loadRegistry(sql, pgSchema, partition) {
     const registry = new Registry();
     for (const row of rows)
         registry.add(buildDef(row, byId));
+    // START_BLOCK_RESERVED_WARN
+    // Имя, перехватываемое Proxy до резолва класса, делает шаг недостижимым ПОД ЭТИМ именем
+    // (второе имя класса, если оно свободно, работает). Предупреждаем, а НЕ бросаем: демо-сид
+    // содержит класс id "link", и throw уронил бы up() на штатной схеме.
+    // Один раз на (схема, класс) за процесс: loadRegistry зовётся на каждый connect и
+    // reloadSchema — иначе штатный прогон утонул бы в повторах.
+    for (const def of registry.all) {
+        const clash = reservedNamesOf(def);
+        if (!clash.length)
+            continue;
+        const seen = `${pgSchema}:${def.id}`;
+        if (warnedReserved.has(seen))
+            continue;
+        warnedReserved.add(seen);
+        const free = [def.id, def.alias].filter((n) => !clash.includes(n));
+        console.warn(`letopis: class name ${clash.map((n) => `"${n}"`).join(' / ')} is reserved by the chain API — ` +
+            (free.length
+                ? `use ${free.map((n) => `"${n}"`).join(' / ')} for chain steps`
+                : 'this class is unreachable as a chain step; rename it'));
+    }
+    // END_BLOCK_RESERVED_WARN
     return registry;
 }

package/dist/sql.d.ts

@@ -25,14 +25,22 @@ export interface Ctx {
     registry: Registry;
     pgSchema: string;
     partition: string;
+    /** Арендатор ВЫЗОВА: заполнен у scoped-хендла db.as(account), пуст у корневого. */
     account?: string;
+    /** Дефолтный owner записей этого scope (db.as(account, { owner })). Default = account. */
     owner?: string;
     /** System-аккаунт — fallback для NOT NULL Entity.account (загружается при connect). */
     systemAccount?: string;
     /** Жёсткая изоляция арендатора: все чтения фильтруются, записи пришпилены к account. */
     enforceAccount?: boolean;
-    /** enforceAcl: скомпилированный на connect резолвер Rule/Resource (READ/WRITE/DELETE). */
+    /** enforceAcl: скомпилированный резолвер Rule/Resource (READ/WRITE/DELETE) для account ЭТОГО ctx. */
     aclDecide?: (cls: ClassDef, op: AclOp) => AclDecision;
+    /**
+     * enforceAcl: скомпилировать энфорсер под субъекта переданного ctx (пишет в c.aclDecide).
+     * Ставит connect(); зовут db.as() и reload. Один энфорсер = один субъект: memo в acl.ts
+     * ключуется классом+операцией БЕЗ аккаунта, переиспользование между scope — утечка решения.
+     */
+    compileAcl?: (c: Ctx) => Promise<void>;
     /** true внутри db.begin()-транзакции (write не оборачивает в begin повторно). */
     inTx?: boolean;
     /** true только у db.begin()-транзакций (не у внутренних): управляет подсказкой при 40P01/40001. */
@@ -41,6 +49,8 @@ export interface Ctx {
     onQuery?: (e: QueryEvent) => void;
     /** Порог «медленного» запроса, мс (без onQuery — console.warn). */
     slowMs?: number;
+    /** Перечитать определения классов из таблицы Schema: пересобрать registry (+ enforcer при enforceAcl). Ставит connect(). */
+    reload?: () => Promise<void>;
 }
 /** Транзиентные ошибки PG — гонка, снимаемая повтором: deadlock / serialization failure. */
 export declare function isTransient(e: unknown): boolean;
@@ -76,6 +86,13 @@ export interface Step {
     pivotKey?: number;
     /** .alias(name) — ключ шага в путях. */
     aliasKey?: string;
+    /**
+     * .exact() — только ЭТОТ класс, без классов-потомков. По умолчанию шаг полиморфен
+     * (родитель отдаёт объединение с потомками); нужно, когда наследование в домене
+     * использовано для переиспользования attributes, а не как «is-a» для выборки
+     * (демо: `запись` наследует `окно`, но смена ≠ бронь).
+     */
+    exactClass?: boolean;
     /** .tags(…) — фильтр по колонке tags: строка | string[] (все) | has/hasAny/hasAll. */
     tagsFilter?: unknown;
     /** .account(uuid|Row) — фильтр по колонке account. */
@@ -114,6 +131,8 @@ export interface BuiltQuery {
     /** Ключи шагов в путях (после alias/dedupe). */
     keys: string[];
 }
+/** Корневой хендл при enforceAccount читать/писать не может: арендатора называет db.as(). */
+export declare function guardScoped(ctx: Ctx): void;
 /** Построить читающий запрос по цепочке. */
 export declare function buildRead(ctx: Ctx, steps: Step[], mods: ChainMods, mode: ReadMode): BuiltQuery;
 /** INSERT новой версии/tombstone. $9 = updated прошлой версии (или null), $10 = deleted. */
@@ -131,4 +150,10 @@ export declare function deleteSql(pgSchema: string, n: number): string;
  * Рекурсивный CTE; каждый узел — актуальная живая версия. $1 partition, $2 class, $3+ — ids.
  */
 export declare function closureSql(pgSchema: string, n: number): string;
+/**
+ * Вызов серверной purge(): $4 dry → превью (актуальные версии замыкания, БД цела), иначе двухфазный
+ * физический снос корня+поддерева. RETURNS SETOF Entity (по строке на сущность). Вся логика
+ * (замыкание, двухфазность, отключение триггера через SET LOCAL) — в БД. $1 partition, $2 class, $3 id, $4 dry.
+ */
+export declare function purgeCallSql(pgSchema: string): string;
 export {};