letopis 1.2.0 → 1.4.0

package/dist/project.js

@@ -50,7 +50,7 @@ function withFailed(meta, failed) {
         delete next.failed;
     return next;
 }
-const emptyReport = () => ({ batches: 0, changes: 0, created: 0, updated: 0, deleted: 0, unchanged: 0, skipped: 0, rebuilds: 0 });
+const emptyReport = () => ({ batches: 0, changes: 0, created: 0, updated: 0, deleted: 0, unchanged: 0, skipped: 0, rebuilds: 0, locked: [] });
 function change(row, cursor, rebuild = false) {
     return {
         cursor, id: row.id, class: row.class, tenant: row.tenant, op: rebuild ? 'create' : row.op, rev: row.rev, at: row.at,
@@ -67,6 +67,10 @@ function change(row, cursor, rebuild = false) {
  * значениями (22…) и пределами размера (54…). Сбой окружения (блокировки, отмена запроса, связь) — не причина
  * выводить арендатора: пачка откатывается целиком, повтор начнётся с того же курсора.
  */
+/** Ожидание чужой блокировки строки дольше lock_timeout (55P03): сбой окружения, проход повторяется. */
+function lockWait(e) {
+    return e?.code === '55P03';
+}
 function tenantFault(e) {
     if (e instanceof LetopisError)
         return true;
@@ -198,12 +202,18 @@ export class Projector {
     /** Источники арендатора без журнала (history: false): их изменений проектор не увидит — арендатор выбывает. */
     blind = new Map();
     stale = true;
+    /** В чекпоинте есть начатая перестройка арендатора пачками (по последней пачке; до первой — проверить). */
+    tenantsPending = true;
     running = false;
     stopped = false;
     wake = null;
     off = null;
     batch;
     pollMs;
+    lockMs;
+    lockRetries;
+    /** Проходов подряд, в которых запись арендатора упиралась в lockTimeout (lockRetries). */
+    lockHits = new Map();
     only;
     constructor(env, name, def) {
         this.env = env;
@@ -228,6 +238,12 @@ export class Projector {
         this.only = def.tenants ? new Set(def.tenants.map((x) => x.toLowerCase())) : null;
         this.batch = def.batch ?? 500;
         this.pollMs = def.pollMs ?? 1000;
+        this.lockMs = def.lockTimeout ?? 5000;
+        if (!Number.isInteger(this.lockMs) || this.lockMs < 0)
+            throw new LetopisError('invalid_data', `проектор ${name}: lockTimeout — целое число мс, 0 и больше`);
+        this.lockRetries = def.lockRetries ?? 0;
+        if (!Number.isInteger(this.lockRetries) || this.lockRetries < 0)
+            throw new LetopisError('invalid_data', `проектор ${name}: lockRetries — целое число, 0 и больше`);
         if (!Number.isInteger(this.batch) || this.batch < 1 || this.batch > 10_000)
             throw new LetopisError('invalid_data', `проектор ${name}: batch — от 1 до 10 000`);
         if (env.onSignal) {
@@ -261,18 +277,37 @@ export class Projector {
                     r = await this.step(rep);
                 }
                 catch (e) {
-                    if (!(e instanceof LetopisError && e.code === 'cursor_expired' && this.def.onExpired === 'rebuild'))
+                    if (lockWait(e)) {
+                        rep.skipped++;
+                        r = 'busy';
+                    }
+                    else if (e instanceof LetopisError && e.code === 'cursor_expired' && this.def.onExpired === 'rebuild') {
+                        r = 'rebuild';
+                    }
+                    else
                         throw e;
-                    r = 'rebuild';
                 }
                 // курсор истёк у части арендаторов: с onExpired: 'rebuild' они перестраиваются сами, пачками (доработки после
                 // точки Б). Состояние — в чекпоинте, поэтому перестройку продолжает run() любого процесса, а занятая
-                // блокировка — только повтор на следующем проходе; ошибка данных выводит арендатора с её кодом, без повторов
-                if (this.def.onExpired === 'rebuild' && r !== 'rebuild' && (await this.tenantWork(rep)) && r !== 'busy')
-                    r = 'more';
-                // пачку перестройки держит другой процесс того же проектора — подождать и продолжить
-                if (r === 'rebuild')
-                    r = (await this.rebuildNow(rep, 'auto')) === 'busy' ? 'busy' : 'more';
+                // блокировка — только повтор на следующем проходе; ошибка данных выводит арендатора с её кодом, без повторов.
+                // Начатую перестройку арендатора пачками — и прерванную rebuild({ tenant, chunked: true }) — продвигает run()
+                // и без onExpired (ревью безопасности №3): иначе хвост бессрочно пропускал бы изменения арендатора с id выше
+                // последней пачки. Начинает перестройку выбывших по ярусу только onExpired: 'rebuild'. Блокировку проектора держит
+                // другой процесс (busy) — перестройку продвинет он: чтение чекпоинта ждало бы его пачку
+                const auto = this.def.onExpired === 'rebuild';
+                try {
+                    if (r !== 'rebuild' && r !== 'busy' && (auto || this.tenantsPending) && (await this.tenantWork(rep, auto)))
+                        r = 'more';
+                    // пачку перестройки держит другой процесс того же проектора — подождать и продолжить
+                    if (r === 'rebuild')
+                        r = (await this.rebuildNow(rep, 'auto')) === 'busy' ? 'busy' : 'more';
+                }
+                catch (e) {
+                    if (!lockWait(e))
+                        throw e;
+                    rep.skipped++;
+                    r = 'busy';
+                }
                 if (r === 'more')
                     continue;
                 if (opts.once)
@@ -306,16 +341,28 @@ export class Projector {
                 return rep;
             }
             await this.startTenant(rep, tenant, false);
+            const started = rep.rebuilds;
             for (;;) {
-                const r = await this.tenantChunk(rep, tenant);
+                // занятая строка (lockTimeout) — как занятая блокировка проектора: подождать и повторить пачку
+                const r = await this.tenantChunk(rep, tenant).catch((e) => {
+                    if (!lockWait(e))
+                        throw e;
+                    rep.skipped++;
+                    return 'busy';
+                });
                 if (r === 'busy')
                     await new Promise((res) => setTimeout(res, 20));
                 if (r !== 'done')
                     continue;
-                // ошибка данных арендатора — как у перестройки одной транзакцией: отказ, арендатор выбывший
-                const f = (await this.tx(async (q) => this.state(q))).failed?.[tenant];
+                // ошибка данных арендатора — как у перестройки одной транзакцией: отказ, арендатор выбывший; чекпоинт держит
+                // пачка run() другого процесса дольше lockTimeout — подождать
+                const f = (await this.untilFree(rep, () => this.tx(async (q) => this.state(q)))).failed?.[tenant];
                 if (f)
                     throw new LetopisError(f.code, f.message);
+                // последнюю пачку мог записать run() другого процесса (он продвигает начатые перестройки): перестройка этого
+                // вызова всё равно завершена
+                if (rep.rebuilds === started)
+                    rep.rebuilds++;
                 return rep;
             }
         }
@@ -369,6 +416,10 @@ export class Projector {
             await q.unsafe('begin isolation level read committed');
             await q.unsafe(`set local role ${ident(this.env.ownerRole)}`);
             await q.unsafe(`set local timezone = 'UTC'`);
+            // чужая блокировка строки (транзакция любого арендатора держит итог или цель) не держит пачку всех арендаторов
+            // дольше lockTimeout (хвост ревью безопасности №3): 55P03 — проход пропускается, курсор остаётся
+            if (this.lockMs > 0)
+                await q.unsafe(`set local lock_timeout = ${this.lockMs}`);
             const out = await fn(q);
             await q.unsafe('commit');
             return out;
@@ -489,6 +540,7 @@ export class Projector {
                 return 'rebuild';
             if (meta.version !== this.def.version)
                 throw this.versionError(meta);
+            this.tenantsPending = Object.values(meta.retenant ?? {}).some((v) => !v.done);
             const cur = dec(meta.cursor);
             const rows = await q.unsafe(`select l.tx::text as tx, l.seq::text as seq, ${rowJson('l')} as row
         from ${this.env.S}.watch_read($1::text::xid8, $2::bigint, null, $3::text[], $4::int, $5::text::pg_snapshot, true) l`, [cur.tx, cur.seq, [...this.from, '#reset'], this.batch, cur.snap ?? null]);
@@ -682,6 +734,27 @@ export class Projector {
             catch (e) {
                 // причина — первая ошибка базы группы (следом за ней база отвечает лишь «транзакция прервана»)
                 const cause = out.aborted ?? e;
+                // строку арендатора держит чужая транзакция дольше lockTimeout (хвост ревью доработок после 1.2.0): отчёт
+                // называет арендатора; с lockRetries после стольких проходов подряд он выбывает, и пачка идёт для остальных,
+                // иначе откатывается вся пачка и проход повторяется
+                if (failed && lockWait(cause)) {
+                    if (!rep.locked.includes(tenant))
+                        rep.locked.push(tenant);
+                    const hits = (this.lockHits.get(tenant) ?? 0) + 1;
+                    if (this.lockRetries === 0 || hits < this.lockRetries) {
+                        this.lockHits.set(tenant, hits);
+                        throw e;
+                    }
+                    this.lockHits.delete(tenant);
+                    await q.unsafe('rollback to savepoint letopis_projector');
+                    await q.unsafe('release savepoint letopis_projector');
+                    failed[tenant] = {
+                        cursor: list[0].cursor || start,
+                        code: '55P03',
+                        message: `проектор ${this.name}: строку арендатора ${tenant} держит чужая транзакция — ${hits} проходов подряд дольше lockTimeout`,
+                    };
+                    continue;
+                }
                 if (!failed || !out.owns(e) || !tenantFault(cause))
                     throw e;
                 await q.unsafe('rollback to savepoint letopis_projector');
@@ -696,6 +769,7 @@ export class Projector {
             }
             if (failed)
                 await q.unsafe('release savepoint letopis_projector');
+            this.lockHits.delete(tenant);
             rep.created += out.stats.created;
             rep.updated += out.stats.updated;
             rep.deleted += out.stats.deleted;
@@ -961,6 +1035,9 @@ export class Projector {
      */
     async startTenant(rep, tenant, auto) {
         for (;;) {
+            // строку арендатора (его производные строки удаляются) держит чужая транзакция дольше lockTimeout — как занятая
+            // блокировка проектора: run() повторит на следующем проходе, rebuild() подождёт (хвост ревью доработок после 1.2.0:
+            // rebuild({ tenant, chunked: true }) отдавал сырую 55P03)
             const r = await this.tx(async (q) => {
                 if (!(await this.lock(q)))
                     return 'busy';
@@ -992,6 +1069,12 @@ export class Projector {
                     delete next.resync;
                 await this.advance(q, meta.cursor, withFailed(next, failed));
                 return 'ok';
+            }).catch((e) => {
+                if (!lockWait(e))
+                    throw e;
+                if (!auto)
+                    rep.skipped++;
+                return 'busy';
             });
             if (r !== 'busy' || auto) {
                 if (r === 'busy')
@@ -1059,29 +1142,47 @@ export class Projector {
         });
     }
     /**
-     * Автоматическая перестройка выбывших по cursor_expired (onExpired: 'rebuild') — проход run(): начинает перестройку
-     * пачками у каждого такого арендатора и продвигает начатые на пачку. true — работа ещё осталась.
+     * Перестройка арендаторов пачками — проход run(): с start (onExpired: 'rebuild') начинает её у каждого выбывшего по
+     * cursor_expired, затем продвигает на пачку каждую начатую — автоматическую и прерванную rebuild({ tenant, chunked:
+     * true }). true — работа ещё осталась.
      */
-    async tenantWork(rep) {
+    async tenantWork(rep, start) {
         const meta = await this.tx(async (q) => this.state(q));
         if (!meta.cursor || meta.state === 'rebuilding' || meta.version !== this.def.version)
             return false;
         let more = false;
-        for (const [t, f] of Object.entries(meta.failed ?? {})) {
-            if (f.code !== 'cursor_expired' || this.blind.has(t) || !this.scopes.has(t))
-                continue;
-            if ((await this.startTenant(rep, t, true)) === 'ok')
-                more = true;
+        if (start) {
+            for (const [t, f] of Object.entries(meta.failed ?? {})) {
+                if (f.code !== 'cursor_expired' || this.blind.has(t) || !this.scopes.has(t))
+                    continue;
+                if ((await this.startTenant(rep, t, true)) === 'ok')
+                    more = true;
+            }
         }
-        const fresh = await this.tx(async (q) => this.state(q));
+        const fresh = start ? await this.tx(async (q) => this.state(q)) : meta;
         for (const [t, v] of Object.entries(fresh.retenant ?? {})) {
             if (v.done)
                 continue;
             if ((await this.tenantChunk(rep, t)) === 'more')
                 more = true;
         }
+        this.tenantsPending = more;
         return more;
     }
+    /** Повторять fn, пока строку держит чужая транзакция дольше lockTimeout (55P03): пауза 20 мс, проход — в skipped. */
+    async untilFree(rep, fn) {
+        for (;;) {
+            try {
+                return await fn();
+            }
+            catch (e) {
+                if (!lockWait(e))
+                    throw e;
+                rep.skipped++;
+            }
+            await new Promise((res) => setTimeout(res, 20));
+        }
+    }
     /** Ждать сигнал источников, остановку или запасной опрос. */
     sleep() {
         return new Promise((resolve) => {

package/dist/sync.js

@@ -11,13 +11,28 @@ function canon(v) {
 export async function syncModels(db, models, opts = {}) {
     const res = { applied: Boolean(opts.apply), created: [], updated: [], unchanged: [], skipped: [], lost: models.flatMap((m) => m.lostRules()) };
     const S = `"${db.schema.replace(/"/g, '""')}"`;
-    // предок раньше потомка
+    // предок раньше потомка; класс-источник агрегата раньше цели: агрегат над классом, которого ещё нет, база отклоняет.
+    // Круг (агрегат над собственным потомком, цикл агрегатов) так не упорядочить — отказ до записи с самим кругом (хвост
+    // ревью доработок после 1.2.0: раньше обход молча ставил потомка раньше предка)
     const ordered = [];
+    const path = [];
     const visit = (m) => {
         if (ordered.includes(m))
             return;
+        const at = path.indexOf(m);
+        if (at >= 0) {
+            throw new LetopisError('invalid_class', `syncModels: модели зависят друг от друга по кругу: ${[...path.slice(at), m].map((x) => x.name).join(' → ')} — `
+                + 'родителя и источник агрегата база ждёт раньше класса');
+        }
+        path.push(m);
         if (m.parent && models.includes(m.parent))
             visit(m.parent);
+        for (const a of Object.values(m.describe().aggregate ?? {})) {
+            const src = models.find((x) => x.name === a.of);
+            if (src)
+                visit(src);
+        }
+        path.pop();
         ordered.push(m);
     };
     models.forEach(visit);

package/dist/up.d.ts

@@ -57,6 +57,23 @@ export interface InstallResult {
 export declare const quoteIdent: (name: string) => string;
 /** Файлы ядра по номеру: `10-core.sql` … `99-revision.sql`; сиды демо-домена сюда не входят. */
 export declare function engineFiles(upTo?: number): Promise<string[]>;
+/** Штамп движка: версия пакета и хэш файлов ядра (`99-revision.sql` пишет его в комментарий схемы). */
+export interface EngineStamp {
+    version: string;
+    sql: string;
+}
+/**
+ * Штамп движка этого пакета. Хэш — по исходному тексту файлов ядра до подстановок (переводы строк — LF): одна и та же
+ * сборка даёт один штамп при любых опциях установки, а версия пакета без правок SQL штамп не меняет.
+ */
+export declare function engineStamp(): Promise<EngineStamp>;
+/** Сравнение версий semver (метаданные сборки не учитываются): меньше нуля, ноль, больше нуля. */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Штамп схемы (комментарий схемы) против файлов ядра пакета — текст предупреждения или null. Ревизия та же, а
+ * функции поставила другая версия движка: после обновления пакета не накатили up() (так было при 1.1 → 1.2).
+ */
+export declare function stampDrift(schema: string, comment: string): Promise<string | null>;
 export declare function substitute(text: string, vars: Record<string, string>): string;
 export declare function install(sql: postgres.Sql, opts: InstallOptions): Promise<InstallResult>;
 /** Миграции с номером выше ревизии from и не выше DDL_REVISION: `0004-описание.sql`, по номеру. */

package/dist/up.js

@@ -11,6 +11,7 @@
  * выполняет ANALYZE только для таблиц без статистики.
  */
 import { readFile, readdir } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { join, resolve } from 'node:path';
 import { createHash, randomBytes } from 'node:crypto';
@@ -34,6 +35,65 @@ export async function engineFiles(upTo = 99) {
     const files = (await readdir(SQL_DIR)).filter((f) => /^\d{2}-[a-z0-9.-]+\.sql$/.test(f));
     return files.filter((f) => Number(f.slice(0, 2)) <= upTo).sort();
 }
+let stamp;
+/**
+ * Штамп движка этого пакета. Хэш — по исходному тексту файлов ядра до подстановок (переводы строк — LF): одна и та же
+ * сборка даёт один штамп при любых опциях установки, а версия пакета без правок SQL штамп не меняет.
+ */
+export async function engineStamp() {
+    if (stamp)
+        return stamp;
+    const h = createHash('sha256');
+    for (const f of await engineFiles())
+        h.update(`${f}\n${(await readFile(join(SQL_DIR, f), 'utf8')).replace(/\r\n/g, '\n')}\n`);
+    const version = createRequire(import.meta.url)('../package.json').version;
+    return (stamp = { version, sql: h.digest('hex').slice(0, 16) });
+}
+/** Сравнение версий semver (метаданные сборки не учитываются): меньше нуля, ноль, больше нуля. */
+export function compareVersions(a, b) {
+    const parse = (v) => {
+        const [core, pre] = v.split('+')[0].split(/-(.*)/s);
+        return { core: core.split('.').map(Number), pre: pre ? pre.split('.') : [] };
+    };
+    const x = parse(a);
+    const y = parse(b);
+    for (let i = 0; i < 3; i++)
+        if ((x.core[i] ?? 0) !== (y.core[i] ?? 0))
+            return (x.core[i] ?? 0) - (y.core[i] ?? 0);
+    if (!x.pre.length || !y.pre.length)
+        return y.pre.length - x.pre.length; // выпуск старше своих предварительных версий
+    for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+        const p = x.pre[i];
+        const q = y.pre[i];
+        if (p === undefined || q === undefined)
+            return p === undefined ? -1 : 1;
+        if (p === q)
+            continue;
+        const pn = /^\d+$/.test(p);
+        const qn = /^\d+$/.test(q);
+        if (pn && qn)
+            return Number(p) - Number(q);
+        if (pn !== qn)
+            return pn ? -1 : 1;
+        return p < q ? -1 : 1;
+    }
+    return 0;
+}
+/**
+ * Штамп схемы (комментарий схемы) против файлов ядра пакета — текст предупреждения или null. Ревизия та же, а
+ * функции поставила другая версия движка: после обновления пакета не накатили up() (так было при 1.1 → 1.2).
+ */
+export async function stampDrift(schema, comment) {
+    const code = await engineStamp().catch(() => null); // файлов ядра рядом со сборкой нет — сверять не с чем
+    if (!code || /\bsql=([0-9a-f]+)/.exec(comment)?.[1] === code.sql)
+        return null;
+    const was = /\bengine=(\S+)/.exec(comment)?.[1];
+    if (was && compareVersions(was, code.version) > 0) {
+        return `letopis: схему ${schema} обновила letopis ${was}, библиотека старее (${code.version}) — обновите пакет: up() этой версией вернул бы прежние функции`;
+    }
+    const by = !was ? 'версия до 1.4.0' : was === code.version ? `другая сборка letopis ${was}` : `letopis ${was}`;
+    return `letopis: функции схемы ${schema} поставила ${by}, библиотека — ${code.version}: накатите up({ schema: '${schema}' })`;
+}
 export function substitute(text, vars) {
     return text.replace(/@([A-Z_]+)@/g, (m, k) => {
         if (!(k in vars))
@@ -88,6 +148,10 @@ export async function install(sql, opts) {
         // режим сигналов — после set role: сохранённый режим лежит в строке ключа secret владельца
         SIGNALS: 'class',
     };
+    // штамп движка — в комментарий схемы (99-revision.sql): по нему connect() узнаёт схему, не накатанную этой версией
+    const st = await engineStamp();
+    vars.ENGINE_VERSION = st.version;
+    vars.ENGINE_SQL = st.sql;
     // Схема создаётся до set role: у владельца может не быть права CREATE в базе.
     await sql.unsafe(`create schema if not exists ${quoteIdent(opts.schema)} authorization ${quoteIdent(owner)}`);
     const files = await engineFiles(opts.upTo);

package/dist/watch.js

@@ -116,10 +116,35 @@ export class Subscription {
         if (!this.pos)
             this.pos = await (this.start ?? this.head());
         const p = this.pos;
-        const rows = await this.ctx.exec.run((q) => q.unsafe(`select l.tx::text as tx, l.seq::text as seq, jsonb_build_object('id', l.id, 'rev', l.rev, 'class', l.class, 'tenant', l.tenant, `
+        const cols = `l.tx::text as tx, l.seq::text as seq, jsonb_build_object('id', l.id, 'rev', l.rev, 'class', l.class, 'tenant', l.tenant, `
             + `'owner', l.owner, 'links', l.links, 'data', l.data, 'tags', l.tags, 'at', l.at, 'author', l.author, 'agent', l.agent, `
-            + `'op', l.op, 'reason', l.reason, 'moved', l.moved) as row `
-            + `from ${this.ctx.S}.watch_read($1::text::xid8, $2::bigint, $3::text::timestamptz, $4::text[], $5::int, $6::text::pg_snapshot) l`, [p.tx, p.seq, p.at, this.ctx.classes, this.batch, p.snap ?? null]), { read: true });
+            + `'op', l.op, 'reason', l.reason, 'moved', l.moved) as row`;
+        // уход строки из классов подписки сменой класса без смены id (хвост ревью безопасности №3) — надгробием прежней
+        // версии в том же окне: полная пачка watch_read ограничивает окно своей последней строкой. Оба потока — одним
+        // оператором: общий снимок и горизонт, иначе курсор перескочил бы событие, зафиксированное между запросами
+        // (автоматическое ревью). Потоки сливаются по (tx, seq) до границы — последней строки потока, обрезанного лимитом
+        const S = this.ctx.S;
+        const both = await this.ctx.exec.run((q) => q.unsafe(`with r as (select l.* from ${S}.watch_read($1::text::xid8, $2::bigint, $3::text::timestamptz, $4::text[], $5::int, $6::text::pg_snapshot) l),
+            u as (select r.tx, r.seq from r where (select count(*) from r) = $5 order by r.tx desc, r.seq desc limit 1)
+       select 0 as src, ${cols} from r l
+       union all
+       select 1 as src, ${cols} from ${S}.watch_leaving($1::text::xid8, $2::bigint, $4::text[], $5::int, $6::text::pg_snapshot,
+         (select tx from u), (select seq from u)) l`, [p.tx, p.seq, p.at, this.ctx.classes, this.batch, p.snap ?? null]), { read: true });
+        const before = (a, b) => BigInt(a.tx) < BigInt(b.tx) || (a.tx === b.tx && BigInt(a.seq) < BigInt(b.seq));
+        const order = (a, b) => (before(a, b) ? -1 : before(b, a) ? 1 : 0);
+        const read = both.filter((r) => r.src === 0).sort(order);
+        const away = both.filter((r) => r.src === 1).sort(order);
+        let rows = read;
+        {
+            const upto = read.length === this.batch ? read[read.length - 1] : null;
+            if (away.length) {
+                let bound = upto;
+                const lastAway = away[away.length - 1];
+                if (away.length === this.batch && (!bound || before(lastAway, bound)))
+                    bound = lastAway;
+                rows = [...read, ...away].sort(order).filter((r) => !bound || !before(bound, r));
+            }
+        }
         for (const r of rows) {
             const row = toRow(r.row);
             const snap = keepSnap(p.snap, r.tx);

package/llms.txt

@@ -2,7 +2,7 @@
 
 > Versioned entity store for Node.js on PostgreSQL 18. Every change is a version in a journal (history, reads as of a date, cursor subscriptions). Integrity, tenant isolation and access rules are enforced by the database itself (triggers and row-level security), so they hold for raw SQL too. Data is read and written with chains like `db.Shop(shop).Product().rows()`.
 
-Key facts for writing code with letopis 1.2:
+Key facts for writing code with letopis 1.4:
 
 - ESM package, Node 22+, PostgreSQL 18+ with pgcrypto, database encoding UTF8. Runtime dependency: `postgres`. Zod 4 is an optional peer dependency needed only by `letopis/model`; `@modelcontextprotocol/server`, only by `letopis/mcp`.
 - Install a schema with `up({ dsn, schema })` from an admin role; the schema is named `v2.<name>`. The application connects with a LOGIN role that is a member of `letopis_app`: `connect({ dsn, schema: 'v2.<name>', token | apiKey })`. A role that bypasses RLS is refused (`bypass_rls`) unless `allowBypassRls: true`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letopis",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Letopis (летопись): versioned entity store on PostgreSQL 18 — integrity, history, tenants and access control enforced by the database itself, dot-notation chains on top",
   "keywords": [
     "postgres",
@@ -101,6 +101,7 @@
     "@types/node": "^22.20.5",
     "letopis-0": "npm:letopis@0.21.0",
     "letopis-1": "npm:letopis@1.0.1",
+    "letopis-11": "npm:letopis@1.1.0",
     "tsx": "^4.23.15",
     "typescript": "~5.9.3",
     "zod": "4.6.5"

package/sql/10-core.sql

@@ -6,7 +6,9 @@
 revoke all on schema @SCHEMA@ from public;
 grant usage on schema @SCHEMA@ to @APP@;
 
--- Все цели концов плоским списком: {роль: id} или {роль: [id, …]}.
+-- Все цели концов плоским списком: {роль: id} или {роль: [id, …]}. Тело — SQL-стандарта (return): имена связываются
+-- при создании и от search_path сеанса не зависят, а колонку ends вычисляет роль приложения. Вариант на plpgsql быстрее
+-- на 17 % (бенч gencols), но его имена разрешались бы при исполнении (ревью безопасности доработок после 1.2.0)
 create or replace function @SCHEMA@.link_ids(links jsonb) returns uuid[]
 language sql immutable parallel safe
 return (

package/sql/50-acl.sql

@@ -228,9 +228,13 @@ begin
                                         and jsonb_typeof(x.pattern->'class') <> 'string', false) as bad) m
     where x.deny or not m.bad
   ), cl as (
-    select c.data->>'name' as name, c.data->>'alias' as alias, c.data->'resolved'->'ancestors' as anc
+    -- один класс на имя — тот, что строки арендатора находят по имени (class_row): свой, иначе System. Одноимённый
+    -- класс System, заведённый после класса арендатора, в план не входит: его предки и алиас давали бы права на строки
+    -- класса арендатора (хвост ревью доработок после 1.2.0)
+    select distinct on (c.data->>'name') c.data->>'name' as name, c.data->>'alias' as alias, c.data->'resolved'->'ancestors' as anc
     from @SCHEMA@.entity c
     where c.class = 'Class' and c.tenant in (p_tenant, '@SYSTEM@'::uuid)
+    order by c.data->>'name', c.tenant = '@SYSTEM@'::uuid
   ), k as (
     select cl.name,
            array(select jsonb_array_elements_text(cl.anc))