letopis 0.19.0 → 0.20.1

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,7 +549,24 @@ 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/.withDeleted(): последний шаг включает и удалённые (история/tombstone видны после delete).
@@ -531,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) {
@@ -556,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`);
@@ -577,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();
@@ -606,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` +
@@ -618,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;
         }

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.
@@ -95,7 +96,8 @@ export function makeTables(ctx) {
         // END_CONTRACT: accounts.purge
         async purge(id) {
             if (!ctx.account) {
-                throw new Error('letopis: accounts.purge requires an authenticated caller — connect({ 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');
@@ -222,6 +224,12 @@ export function makeTables(ctx) {
     // 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")

package/dist/types.d.ts

@@ -224,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;
     /** Хук на каждый запрос цепочки (метрики, лог). */
@@ -245,3 +253,38 @@ 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[];
+/**
+ * Ревизия движка (`lib/sql/ddl.sql`), которую ожидает ЭТА версия либы.
+ *
+ * Зачем: `ddl.sql` растёт аддитивно внутри одной версии движка (в 0.19.0, например,
+ * добавились функции purge/purge_closure/purge_account). Схема, накатанная раньше, их
+ * НЕ получает — приложение обновляет пакет и падает сырым `PostgresError: function
+ * "v1.x".purge(...) does not exist` вместо внятного объяснения. `connect()` сравнивает
+ * ожидаемую ревизию с меткой в схеме (`COMMENT ON SCHEMA` — её ставит последняя строка
+ * ddl.sql) и один раз на процесс предупреждает, что и как обновить.
+ *
+ * Файл идемпотентен, поэтому аддитивные правки доезжают повторным накатом:
+ * `up({ upgrade: true })` либо `node db/apply.mjs --upgrade` — данные целы.
+ * Несовместимая правка СТРУКТУРЫ таблиц — это смена version в имени схемы (v1 → v2).
+ *
+ * Совпадение константы с маркером `-- DDL_REVISION:` в ddl.sql проверяет
+ * `scripts/check-docs.mjs` — иначе одно уедет без другого.
+ */
+export declare const DDL_REVISION = 1;
+/** Метка ревизии в комментарии схемы: 'letopis ddl_revision=N' → N; иначе null. */
+export declare function parseDdlRevision(comment: string | null | undefined): number | null;

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,60 @@
 /** Метка операторов фильтра (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
+// START_BLOCK_DDL_REVISION
+/**
+ * Ревизия движка (`lib/sql/ddl.sql`), которую ожидает ЭТА версия либы.
+ *
+ * Зачем: `ddl.sql` растёт аддитивно внутри одной версии движка (в 0.19.0, например,
+ * добавились функции purge/purge_closure/purge_account). Схема, накатанная раньше, их
+ * НЕ получает — приложение обновляет пакет и падает сырым `PostgresError: function
+ * "v1.x".purge(...) does not exist` вместо внятного объяснения. `connect()` сравнивает
+ * ожидаемую ревизию с меткой в схеме (`COMMENT ON SCHEMA` — её ставит последняя строка
+ * ddl.sql) и один раз на процесс предупреждает, что и как обновить.
+ *
+ * Файл идемпотентен, поэтому аддитивные правки доезжают повторным накатом:
+ * `up({ upgrade: true })` либо `node db/apply.mjs --upgrade` — данные целы.
+ * Несовместимая правка СТРУКТУРЫ таблиц — это смена version в имени схемы (v1 → v2).
+ *
+ * Совпадение константы с маркером `-- DDL_REVISION:` в ddl.sql проверяет
+ * `scripts/check-docs.mjs` — иначе одно уедет без другого.
+ */
+export const DDL_REVISION = 1;
+/** Метка ревизии в комментарии схемы: 'letopis ddl_revision=N' → N; иначе null. */
+export function parseDdlRevision(comment) {
+    const m = /letopis ddl_revision=(\d+)/.exec(comment ?? '');
+    return m ? Number(m[1]) : null;
+}
+// END_BLOCK_DDL_REVISION

package/dist/up.d.ts

@@ -28,6 +28,14 @@ export interface UpOpts extends Omit<ConnectOpts, 'dsn' | 'schema'> {
     seeds?: string[] | false;
     /** Дропнуть схему и накатить заново. ДАННЫЕ СХЕМЫ ТЕРЯЮТСЯ. */
     fresh?: boolean;
+    /**
+     * Перекатить `ddl.sql` на СУЩЕСТВУЮЩУЮ схему (сиды не трогаются, данные целы).
+     * Так доезжают аддитивные правки движка: схема, накатанная старой либой, не имеет новых
+     * функций/триггеров (например `purge`/`purge_account` из 0.19.0) и падает сырым
+     * «function … does not exist». О расхождении предупреждает `connect()` (см. `DDL_REVISION`).
+     * Идемпотентно; на несуществующей схеме — обычный первый накат.
+     */
+    upgrade?: boolean;
     /** Без console.log-прогресса. */
     quiet?: boolean;
     /** Максимум ожидания готовности, мс. Default 120 000 (первый запуск: pull образа + initdb). */

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
@@ -17,7 +17,7 @@
 // END_MODULE_CONTRACT
 //
 // START_MODULE_MAP
-//   UpOpts - опции up(): dsn, schema, version, контейнер/образ, dataDir, seeds, fresh, quiet, таймаут
+//   UpOpts - опции up(): dsn, schema, version, контейнер/образ, dataDir, seeds, fresh, upgrade, quiet, таймаут
 //   dockerRunArgs - чистая сборка argv для `docker run` (bind/volume, trust/пароль)
 //   RunCfg - конфиг запуска контейнера (порты, креды, база, dataDir)
 //   up - точка входа: контейнер -> база -> схема -> готовность -> connect (возвращает EntityDb)
@@ -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 (upgrade) -> накат 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';
@@ -181,12 +184,12 @@ function tcpAlive(host, port) {
 }
 // START_CONTRACT: applySchema
 //   PURPOSE: Применяет DDL-схему и сиды — при fresh дропает схему; если схемы нет, накатывает ddl.sql (+ дефолтные booking/auth или свои сиды), подставляя <SCHEMA-NAME>.
-//   INPUTS: { dsn: string; full: string - полное имя схемы v<N>.<schema>; seeds: string[] | false | undefined - свои пути / false (без сидов) / undefined (дефолт); fresh: boolean; log: (m: string) => void }
+//   INPUTS: { dsn: string; full: string - полное имя схемы v<N>.<schema>; seeds: string[] | false | undefined - свои пути / false (без сидов) / undefined (дефолт); fresh: boolean; upgrade: boolean - перекатить ddl на существующую схему; log: (m: string) => void }
 //   OUTPUTS: { Promise<void> }
 //   SIDE_EFFECTS: читает sql-файлы; выполняет DROP/накат схемы в postgres; закрывает соединение
 //   LINKS: M-UP, V-M-UP
 // END_CONTRACT: applySchema
-async function applySchema(dsn, full, seeds, fresh, log) {
+async function applySchema(dsn, full, seeds, fresh, upgrade, log) {
     const sql = postgres(dsn, { max: 1, onnotice: () => { } });
     try {
         if (fresh) {
@@ -195,6 +198,21 @@ async function applySchema(dsn, full, seeds, fresh, log) {
         }
         const have = await sql `SELECT 1 FROM information_schema.schemata WHERE schema_name = ${full}`;
         if (have.length > 0) {
+            // START_BLOCK_UPGRADE_DDL
+            // upgrade: перекатить ТОЛЬКО ddl.sql на существующую схему. Сиды не трогаем — они
+            // вставляют данные, повторный прогон дал бы дубли смысла. Файл идемпотентен
+            // (CREATE OR REPLACE у функций, DROP IF EXISTS + CREATE у триггеров, IF NOT EXISTS
+            // у таблиц/индексов), поэтому данные целы, а аддитивные правки движка доезжают.
+            // Так закрывается разрыв: схема, накатанная старой либой, не имела новых функций
+            // (purge/purge_account из 0.19.0) и падала сырым «function … does not exist».
+            if (upgrade) {
+                const text = (await readFile(pkgPath('../sql/ddl.sql'), 'utf8')).replaceAll('<SCHEMA-NAME>', full);
+                await sql.unsafe(text);
+                await sql.unsafe(`ANALYZE ${qi(full)}."Entity"`);
+                log(`schema "${full}" upgraded (ddl re-applied, data intact)`);
+                return;
+            }
+            // END_BLOCK_UPGRADE_DDL
             log(`schema "${full}" already exists — apply skipped`);
             return;
         }
@@ -207,7 +225,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();
@@ -215,13 +241,13 @@ async function applySchema(dsn, full, seeds, fresh, log) {
 }
 // START_CONTRACT: up
 //   PURPOSE: Единая точка входа dev-bootstrap — валидирует схему/версию, при живом postgres пропускает docker (иначе поднимает контейнер и ждёт готовности PG+Redis), применяет схему и подключается.
-//   INPUTS: { opts: UpOpts - dsn, schema, version, контейнер/образ, dataDir, redisPort, seeds, fresh, quiet, waitTimeoutMs + прочие ConnectOpts }
+//   INPUTS: { opts: UpOpts - dsn, schema, version, контейнер/образ, dataDir, redisPort, seeds, fresh, upgrade, quiet, waitTimeoutMs + прочие ConnectOpts }
 //   OUTPUTS: { Promise<EntityDb> - подключённый фасад на схеме "v<version>.<schema>" }
 //   SIDE_EFFECTS: shell docker через M-UP.ensureContainer; TCP-пинги; чтение sql и накат схемы; console.log с префиксом [letopis.up]; connect (M-CONNECT); бросает при плохом имени схемы/версии и таймауте готовности
 //   LINKS: M-UP, V-M-UP
 // END_CONTRACT: up
 export async function up(opts) {
-    const { dsn = DEFAULT_DSN, schema, version, container = 'letopis-timescale', image = 'letopis-db', dataDir, redisPort = 16379, seeds, fresh, quiet, waitTimeoutMs = 120_000, ...connectRest } = opts;
+    const { dsn = DEFAULT_DSN, schema, version, container = 'letopis-timescale', image = 'letopis-db', dataDir, redisPort = 16379, seeds, fresh, upgrade, quiet, waitTimeoutMs = 120_000, ...connectRest } = opts;
     if (!/^[a-zA-Z_][a-zA-Z0-9_$]*$/.test(schema))
         throw new Error(`letopis.up: bad schema name "${schema}" (базовое имя без версии и точек; версию задаёт version)`);
     if (!Number.isInteger(version) || version < 1)
@@ -284,7 +310,7 @@ export async function up(opts) {
         // END_BLOCK_WAIT_READY
     }
     // START_BLOCK_APPLY_SCHEMA
-    await applySchema(dsn, full, seeds, fresh ?? false, log);
+    await applySchema(dsn, full, seeds, fresh ?? false, upgrade ?? false, log);
     const db = await connect({ ...connectRest, dsn, schema: full });
     log(`connected (schema "${full}")`);
     // END_BLOCK_APPLY_SCHEMA

package/dist/write.js

@@ -16,7 +16,7 @@
  */
 //
 // FILE: lib/src/write.ts
-// VERSION: 1.0.0
+// VERSION: 1.1.0
 // START_MODULE_CONTRACT
 //   PURPOSE: Write-side движок: валидация, резолв концов/слотов, вычисление id (v5/v7), вставка новых версий, каскадное удаление, анонимизация, исполнение планов и батчей в транзакции.
 //   SCOPE: ValidationError, runPlan, executeBatch, createOp/updateOp/delOp/anonymizeOp, toRow/readRows/deepMerge, BatchPlan.
@@ -36,11 +36,13 @@
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+//   LAST_CHANGE: [v1.1.0 - resolveAccount зовёт guardScoped: при enforceAccount без scope (db.as)
+//     запись запрещена с внятной подсказкой; ctx.account теперь приходит из scope, не из connect.
+//     Ранее: Documented existing module: reverse-engineered contract + markup]
 // END_CHANGE_SUMMARY
 import { randomUUID } from 'node:crypto';
 import { uuidv5, uuidv7 } from './uuid.js';
-import { buildRead, runQuery, insertSql, multiInsertSql, deleteSql, closureSql, purgeCallSql, isTransient, retryDelay, RETRIES, } from './sql.js';
+import { buildRead, guardScoped, runQuery, insertSql, multiInsertSql, deleteSql, closureSql, purgeCallSql, isTransient, retryDelay, RETRIES, } from './sql.js';
 import { aclDenied } from './acl.js';
 // START_CONTRACT: ValidationError
 //   PURPOSE: Ошибка валидации класса, несущая список проблемных полей (issues).
@@ -215,14 +217,15 @@ function aclWrite(ctx, step, op) {
     }
 }
 const noFilter = (f) => f === undefined;
-/** Entity.account NOT NULL: модификатор → connect() → System-аккаунт; иначе ошибка. */
+/** Entity.account NOT NULL: модификатор → scope db.as() → System-аккаунт; иначе ошибка. */
 function resolveAccount(ctx, step) {
+    guardScoped(ctx);
     if (ctx.enforceAccount && ctx.account && step.accountFilter && step.accountFilter !== ctx.account) {
         throw new Error(`letopis: enforceAccount is on — writes are pinned to account ${ctx.account}`);
     }
     const acc = step.accountFilter ?? ctx.account ?? ctx.systemAccount;
     if (!acc) {
-        throw new Error('letopis: Entity.account is NOT NULL — set .account(…) / connect({account}) or seed a System account (lib/sql/seed.auth.sql)');
+        throw new Error('letopis: Entity.account is NOT NULL — set .account(…) / db.as(account) or seed a System account (lib/sql/seed.auth.sql)');
     }
     return acc;
 }