letopis 1.0.0 → 1.1.0

package/dist/signals.js

@@ -0,0 +1,169 @@
+/**
+ * Сигналы базы по режимам установки (план 1.1, §2.2, этап 2): разбор нагрузки и токены.
+ *
+ * Канал — имя схемы; нагрузку строит функция базы signal() по режиму up({ signals }):
+ *   - class — `Booking` (как в 1.0); tenant — `Booking@<токен арендатора>`;
+ *   - opaque — `<токен класса>@<токен арендатора>`; none — сигналов нет;
+ *   - сессии — `session:<16 hex>` и `session:*`, сброс — `*` (кроме none).
+ * Токен — первые 96 бит HMAC-SHA256 от «назначение:значение» на ключе сигналов (signal_key(): HMAC
+ * ключа строки KEY по 'letopis:signals'), 24 строчных шестнадцатеричных знака. Имя класса не содержит
+ * `@`, `:` и `*` (метасхема Class), поэтому нагрузка разбирается однозначно.
+ *
+ * Процесс с ключом (право letopis.signals, сид выдаёт его сервисам) узнаёт классы по токенам и сбрасывает
+ * кэш с точностью до арендатора. Процесс без ключа работает «грубо»: в режиме tenant сбрасывает класс во
+ * всех арендаторах, в режиме opaque любой сигнал сбрасывает весь кэш.
+ */
+import { createHmac } from 'node:crypto';
+import { ACL_CLASS_NAMES } from './types.js';
+export const SIGNAL_MODES = ['class', 'tenant', 'opaque', 'none'];
+const SYSTEM_ID = '2eba6d0a-1edd-4bb6-a85a-a703dab49035';
+/** Имя класса — по метасхеме Class (40-class.sql). */
+const NAME = /^[A-Za-zА-Яа-яЁё_][A-Za-zА-Яа-яЁё0-9_]{0,62}$/;
+const TOKEN = /^[0-9a-f]{24}$/;
+export class Signals {
+    mode;
+    key = null;
+    hex = null;
+    names = new Set(ACL_CLASS_NAMES);
+    byToken = new Map();
+    tenants = new Map();
+    system = null;
+    constructor(mode = 'class') {
+        this.mode = mode;
+    }
+    /** У процесса есть ключ сигналов. */
+    get keyed() {
+        return this.key !== null;
+    }
+    /** Ключ из signal_key() (hex); null — процесс без ключа. true — ключ сменился (токены другие). */
+    setKey(hex) {
+        if (hex === this.hex)
+            return false;
+        this.hex = hex;
+        this.key = hex ? Buffer.from(hex, 'hex') : null;
+        this.tenants.clear();
+        this.system = this.key ? this.token('tenant', SYSTEM_ID) : null;
+        this.rebuild();
+        return true;
+    }
+    /** Имена классов реестров процесса: по ним узнаются токены классов в режиме opaque. */
+    setClasses(names) {
+        this.names = new Set([...ACL_CLASS_NAMES, ...names]);
+        this.rebuild();
+    }
+    rebuild() {
+        this.byToken.clear();
+        if (!this.key || this.mode !== 'opaque')
+            return;
+        for (const n of this.names)
+            this.byToken.set(this.token('class', n), n);
+    }
+    /** Токен — как signal_token() базы. */
+    token(purpose, value) {
+        return createHmac('sha256', this.key).update(`${purpose}:${value}`, 'utf8').digest('hex').slice(0, 24);
+    }
+    /** Токен арендатора для записей кэша и фильтра подписки; null — точности по арендатору нет. */
+    tenantToken(id) {
+        if (!id || !this.key || (this.mode !== 'tenant' && this.mode !== 'opaque'))
+            return null;
+        let t = this.tenants.get(id);
+        if (t === undefined) {
+            if (this.tenants.size >= 10_000)
+                this.tenants.clear();
+            t = this.token('tenant', id.toLowerCase());
+            this.tenants.set(id, t);
+        }
+        return t;
+    }
+    /** Разобрать нагрузку сигнала или элемент letopis.changed своей транзакции. */
+    parse(p) {
+        if (p === '*')
+            return { kind: 'all' };
+        if (p === 'session:*')
+            return { kind: 'sessions' };
+        if (p.startsWith('session:'))
+            return /^session:[0-9a-f]{16}$/.test(p) ? { kind: 'session', tag: p.slice(8) } : { kind: 'foreign' };
+        const at = p.indexOf('@');
+        const head = at < 0 ? p : p.slice(0, at);
+        const tail = at < 0 ? null : p.slice(at + 1);
+        // в режиме none сигналов нет, но своя транзакция копит в letopis.changed имена классов
+        if (this.mode === 'class' || this.mode === 'none') {
+            return tail === null && NAME.test(head) ? { kind: 'class', cls: head, tenant: null } : { kind: 'foreign' };
+        }
+        if (tail === null || !TOKEN.test(tail))
+            return { kind: 'foreign' };
+        // токен System — строки, общие для всех арендаторов: сброс класса везде
+        const tenant = this.key && tail !== this.system ? tail : null;
+        if (this.mode === 'tenant')
+            return NAME.test(head) ? { kind: 'class', cls: head, tenant } : { kind: 'foreign' };
+        if (!TOKEN.test(head))
+            return { kind: 'foreign' };
+        if (!this.key)
+            return { kind: 'opaque' };
+        const cls = this.byToken.get(head);
+        return cls ? { kind: 'class', cls, tenant } : { kind: 'unknown', tenant };
+    }
+}
+/**
+ * Не чаще раза в ms: первый вызов — сразу, вызовы внутри окна — один раз в его конце. Так заливка
+ * канала сигналами (в том числе поддельными) не превращается в поток перечитываний реестра.
+ */
+/**
+ * Ведро жетонов: count вызовов подряд — сразу, дальше не чаще раза в ms (жетон возвращается раз в ms); вызовы
+ * в ожидании сливаются в один. Короткая серия проходит без задержки, заливка — с заданной частотой.
+ */
+export function bucket(fn, count, ms) {
+    let tokens = count;
+    let at = Date.now();
+    let timer = null;
+    const call = () => {
+        if (timer)
+            return;
+        const now = Date.now();
+        tokens = Math.min(count, tokens + (now - at) / ms);
+        at = now;
+        if (tokens >= 1) {
+            tokens -= 1;
+            return fn();
+        }
+        timer = setTimeout(() => {
+            timer = null;
+            call();
+        }, Math.ceil((1 - tokens) * ms));
+        timer.unref?.();
+    };
+    return Object.assign(call, {
+        stop: () => {
+            if (timer)
+                clearTimeout(timer);
+            timer = null;
+        },
+    });
+}
+export function throttle(fn, ms) {
+    let last = -Infinity;
+    let timer = null;
+    const run = () => {
+        last = Date.now();
+        fn();
+    };
+    const call = () => {
+        if (timer)
+            return;
+        const wait = last + ms - Date.now();
+        if (wait <= 0)
+            return run();
+        timer = setTimeout(() => {
+            timer = null;
+            run();
+        }, wait);
+        timer.unref?.();
+    };
+    return Object.assign(call, {
+        stop: () => {
+            if (timer)
+                clearTimeout(timer);
+            timer = null;
+        },
+    });
+}

package/dist/sql.d.ts

@@ -29,7 +29,7 @@ export interface Step {
 }
 /** Уникальная метка узла пути. */
 export declare const nextNodeKey: () => number;
-export type ReadMode = 'paths' | 'rows' | 'ids' | 'count' | 'countPaths' | 'versions' | 'agg';
+export type ReadMode = 'paths' | 'rows' | 'ids' | 'count' | 'countPaths' | 'versions' | 'agg' | 'diff' | 'blame';
 export interface AggSpec {
     fn: 'sum' | 'avg' | 'min' | 'max' | 'countBy';
     field: string;

package/dist/sql.js

@@ -439,6 +439,9 @@ export function cursorOf(row, field) {
 // Построение запроса
 // ---------------------------------------------------------------------------
 const COLS = ['id', 'rev', 'class', 'tenant', 'owner', 'links', 'data', 'tags', 'at', 'author', 'agent', 'op', 'reason', 'moved'];
+/** Колонки журнала, выданные приложению: все, кроме changed (ревью №1 точки А плана 1.1, 10-core.sql). */
+const LOG_COLS = ['seq', 'tx', 'id', 'rev', 'class', 'cv', 'tenant', 'owner', 'links', 'data', 'tags', 'at', 'author', 'agent', 'op', 'reason',
+    'moved', 'prev_hash', 'hash'].map((c) => 'l.' + c).join(', ');
 const colsOf = (a) => COLS.map((c) => `${a}.${c}`).join(', ');
 export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
     if (!steps.length)
@@ -534,7 +537,7 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
         const logPart = (pairs) => 
         // версия журнала по паре (id, rev): вложенный цикл по индексу log_id_rev, без перебора журнала
         `select ${colsOf('x')}, null::int as depth from (${pairs}) f(id, rev) `
-            + `cross join lateral (select * from ${S}.log l where l.id = f.id and l.rev = f.rev) x where ${where('x')}`;
+            + `cross join lateral (select ${LOG_COLS} from ${S}.log l where l.id = f.id and l.rev = f.rev) x where ${where('x')}`;
         const parts = [];
         if (i === 0) {
             if (step.deepMax !== undefined)
@@ -698,6 +701,18 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
                 : `${withClause}select to_jsonb(v) as row from (select ${colsOf('l')}, null::int as depth from ${S}.log l `
                     + `where l.id in (select z.id from ${ents} z)) v order by v.id, v.rev${limitOffset()}`;
             break;
+        case 'diff':
+        case 'blame': {
+            // план 1.1, §2.1: функции базы считают по журналу под RLS — по одному документу на объект шага
+            const h = mods.hist ?? {};
+            const num = (v) => (typeof v === 'number' ? `${p.push(v)}::int` : 'null');
+            const ts = (v) => (typeof v === 'string' ? `${p.push(v)}::text::timestamptz` : 'null');
+            const call = mode === 'diff'
+                ? `${S}.diff_versions(z.id, ${num(h.from)}, ${num(h.to)}, ${ts(h.from)}, ${ts(h.to)}, ${h.follow ? 'true' : 'false'})`
+                : `${S}.blame(z.id, ${ts(h.at)}, ${num(h.limit)})`;
+            text = `${withClause}select ${call} as row from (select distinct z.id from ${ents} z) z order by z.id`;
+            break;
+        }
         case 'agg': {
             if (!agg || !agg.field.startsWith('data.'))
                 fail("агрегат по полю 'data.<путь>'");
@@ -718,7 +733,7 @@ export function buildRead(reg, schema, steps, mods, mode, agg, opts = {}) {
 }
 /** Строка из to_jsonb(узла): служебные поля в $deleted / $depth, пустые необязательные — без ключа. */
 export function toRow(raw) {
-    const { depth, agent, reason, moved, ...rest } = raw;
+    const { depth, agent, reason, moved, changed: _changed, ...rest } = raw;
     const row = rest;
     if (agent != null)
         row.agent = agent;

package/dist/tx.d.ts

@@ -17,9 +17,10 @@
  * исходную ошибку — при каждом вызове. Обрыв связи во время COMMIT — commit_unknown, без повтора.
  *
  * Сигналы (решение 9 точки А): транзакции библиотеки помечены `letopis.notify = 'deferred'` —
- * триггер не шлёт NOTIFY, а копит имена изменённых классов в `letopis.changed`; после фиксации
- * их забирает нотификатор процесса и раз в интервал (по умолчанию 100 мс) отправляет одной
- * транзакцией без данных: такая фиксация не ждёт диск и не задерживает чужие записи.
+ * триггер не шлёт NOTIFY, а копит готовые нагрузки (по режиму сигналов установки, план 1.1) в
+ * `letopis.changed`; после фиксации их забирает нотификатор процесса и раз в интервал (по умолчанию
+ * 100 мс) отправляет одной транзакцией без данных: такая фиксация не ждёт диск и не задерживает чужие
+ * записи. Неотправленное (ошибка отправки) остаётся в очереди до следующего интервала.
  */
 import type postgres from 'postgres';
 type Sql = postgres.Sql<Record<string, unknown>>;
@@ -32,7 +33,7 @@ export declare function isLogConflict(e: unknown): boolean;
 export declare function isConnectionError(e: unknown): boolean;
 export declare const RETRIES = 3;
 export declare const retryDelay: (attempt: number) => Promise<void>;
-/** Нотификатор процесса: копит имена классов и отправляет их пачкой раз в интервал. */
+/** Нотификатор процесса: копит нагрузки сигналов и отправляет их пачкой раз в интервал. */
 export declare class Notifier {
     private sql;
     private channel;
@@ -43,8 +44,9 @@ export declare class Notifier {
     private stopped;
     private flushing;
     constructor(sql: Sql, channel: string, intervalMs: number, onError?: (e: unknown) => void);
-    /** Добавить классы из letopis.changed (строка через запятую). */
+    /** Добавить нагрузки из letopis.changed (строка через запятую). */
     add(changed: string | null | undefined): void;
+    private schedule;
     /** Отправить накопленное сейчас (вызывается по таймеру и при закрытии). */
     flush(): Promise<void>;
     close(): Promise<void>;
@@ -77,8 +79,8 @@ export interface TxContext {
     /** После успешной операции (продление сессии раз в минуту). */
     after?: () => void;
     /**
-     * После фиксации записи: имена из letopis.changed (классы, session:<тег>) — кэш результатов
-     * сбрасывает свои ответы сразу (§2.12); raw — запись через db.sql.
+     * После фиксации записи: нагрузки из letopis.changed (сигналы записи, session:<тег>) — кэш
+     * результатов сбрасывает свои ответы сразу (§2.12); raw — запись через db.sql.
      */
     onChanged?: (names: string[], raw: boolean) => void;
 }

package/dist/tx.js

@@ -39,7 +39,7 @@ function hintTxRetry(e) {
 }
 export const RETRIES = 3;
 export const retryDelay = (attempt) => new Promise((r) => setTimeout(r, 40 * attempt + Math.random() * 40));
-/** Нотификатор процесса: копит имена классов и отправляет их пачкой раз в интервал. */
+/** Нотификатор процесса: копит нагрузки сигналов и отправляет их пачкой раз в интервал. */
 export class Notifier {
     sql;
     channel;
@@ -55,14 +55,17 @@ export class Notifier {
         this.intervalMs = intervalMs;
         this.onError = onError;
     }
-    /** Добавить классы из letopis.changed (строка через запятую). */
+    /** Добавить нагрузки из letopis.changed (строка через запятую). */
     add(changed) {
         if (!changed || this.stopped)
             return;
         for (const c of changed.split(','))
             if (c)
                 this.queue.add(c);
-        if (!this.timer && this.queue.size)
+        this.schedule();
+    }
+    schedule() {
+        if (!this.timer && this.queue.size && !this.stopped)
             this.timer = setTimeout(() => void this.flush(), this.intervalMs);
     }
     /** Отправить накопленное сейчас (вызывается по таймеру и при закрытии). */
@@ -73,9 +76,16 @@ export class Notifier {
         }
         if (!this.queue.size)
             return this.flushing;
-        const classes = [...this.queue];
+        const payloads = [...this.queue];
         this.queue.clear();
-        this.flushing = this.flushing.then(() => this.sql `select pg_notify(${this.channel}, c) from unnest(${classes}::text[]) as c`.then(() => undefined, this.onError));
+        this.flushing = this.flushing.then(() => this.sql `select pg_notify(${this.channel}, c) from unnest(${payloads}::text[]) as c`.then(() => undefined, (e) => {
+            // не отправлено (обрыв связи, отказ базы) — обратно в очередь: уйдёт следующим интервалом
+            // (в 1.0.1 такие сигналы терялись, и кэш других процессов устаревал до срока)
+            for (const c of payloads)
+                this.queue.add(c);
+            this.schedule();
+            this.onError(e);
+        }));
         return this.flushing;
     }
     async close() {

package/dist/typed.d.ts

@@ -70,24 +70,39 @@ export type TypedChain<C, M extends readonly AnyModelLike[]> = Omit<ChainCore, R
     owner(v: string | {
         id: string;
     }): TypedChain<C, M>;
-    create(data: Partial<DataOf<C>>): TypedChain<C, M>;
+    create(data: Partial<DataOf<C>>, opts?: {
+        reason?: string;
+    }): TypedChain<C, M>;
     update(patch?: PatchOf<DataOf<C>>, opts?: {
         rev?: number;
+        reason?: string;
+    }): TypedChain<C, M>;
+    upsert(data: Partial<DataOf<C>>, opts?: {
+        reason?: string;
     }): TypedChain<C, M>;
-    upsert(data: Partial<DataOf<C>>): TypedChain<C, M>;
     delete(opts?: {
         confirm?: boolean;
+        reason?: string;
+    }): TypedChain<C, M>;
+    anonymize(fields: (keyof DataOf<C> & string)[], opts?: {
+        reason?: string;
     }): TypedChain<C, M>;
-    anonymize(fields: (keyof DataOf<C> & string)[]): TypedChain<C, M>;
-    reclass(cls: string, data?: Record<string, unknown>): TypedChain<unknown, M>;
+    reclass(cls: string, data?: Record<string, unknown>, opts?: {
+        reason?: string;
+    }): TypedChain<unknown, M>;
     forUpdate(): TypedChain<C, M>;
-    restore(): TypedChain<C, M>;
+    restore(opts?: {
+        reason?: string;
+    }): TypedChain<C, M>;
     purge(opts?: {
         confirm?: boolean;
+        reason?: string;
     }): TypedChain<C, M>;
     rekey(patch: Partial<DataOf<C>> & Partial<Record<keyof LinksOf<C>, string | {
         id: string;
-    }>>): TypedChain<C, M>;
+    }>>, opts?: {
+        reason?: string;
+    }): TypedChain<C, M>;
     cache(opts?: {
         ttl?: number;
     }): TypedChain<C, M>;

package/dist/types.d.ts

@@ -2,9 +2,14 @@
  * Общие типы letopis 1.0. Файл наполняется по этапам плана (reports/PLAN-LETOPIS-1.0.md).
  */
 /** Ревизия движка в базе: штамп в lib/sql/99-revision.sql должен совпадать (этап 1). */
-export declare const DDL_REVISION = 5;
+export declare const DDL_REVISION = 6;
+/**
+ * Классы, строки которых меняют права и схему: их запись повышает счётчик прав (загрузчик), а сигнал
+ * сбрасывает весь кэш результатов и пропуска прав. Тот же список — в триггерах базы (60-write.sql).
+ */
+export declare const ACL_CLASS_NAMES: readonly string[];
 /** Методы цепочки: терминалы, модификаторы, глаголы записи (этап 4), охранники снесённого API. */
-export declare const CHAIN_METHODS: readonly ["then", "entity", "paths", "rows", "first", "ids", "count", "limit", "offset", "sort", "asOf", "withDeleted", "deep", "exact", "sum", "avg", "min", "max", "countBy", "after", "versions", "create", "update", "upsert", "set", "unset", "add", "remove", "delete", "anonymize", "reclass", "restore", "purge", "alias", "tags", "owner", "forUpdate", "cache", "rekey", "run", "execute", "account"];
+export declare const CHAIN_METHODS: readonly ["then", "entity", "paths", "rows", "first", "ids", "count", "limit", "offset", "sort", "asOf", "withDeleted", "deep", "exact", "sum", "avg", "min", "max", "countBy", "after", "versions", "create", "update", "upsert", "set", "unset", "add", "remove", "delete", "anonymize", "reclass", "restore", "purge", "alias", "tags", "owner", "forUpdate", "cache", "rekey", "run", "execute", "account", "diff", "blame"];
 /** Свойства корня db (и транзакции db.begin()). */
 export declare const DB_METHODS: readonly ["as", "begin", "commit", "rollback", "lock", "batch", "watch", "close", "registry", "sql", "load", "verify", "maintain", "reset", "describe", "auth", "acl", "idOf", "refresh", "transaction", "flushSignals", "schema", "token", "tenant", "reloadSchema", "accounts", "credentials", "resources", "rules", "compact", "trimHistory", "rekeyClass", "cache"];
 /** Свойства батча db.batch(name). */
@@ -98,10 +103,18 @@ export interface ChainMods {
     cache?: {
         ttl?: number;
     };
+    /** Параметры терминалов diff() и blame() (план 1.1, §2.1): номера версий или моменты (ISO). */
+    hist?: {
+        from?: number | string;
+        to?: number | string;
+        at?: string;
+        follow?: boolean;
+        limit?: number;
+    };
 }
 /** Событие хука onQuery: один запрос цепочки. */
 export interface QueryEvent {
-    mode: 'paths' | 'rows' | 'ids' | 'count' | 'versions' | 'agg';
+    mode: 'paths' | 'rows' | 'ids' | 'count' | 'versions' | 'agg' | 'diff' | 'blame';
     /** Классы шагов цепочки. */
     classes: string[];
     ms: number;
@@ -109,3 +122,63 @@ export interface QueryEvent {
     /** ms > slowMs. */
     slow: boolean;
 }
+/** Изменение пути: added — не было, removed — не стало, changed — другое значение. */
+export interface DiffChange {
+    /** Путь: первый сегмент — раздел строки (data, links, tags, owner, class). */
+    path: string[];
+    kind: 'added' | 'removed' | 'changed';
+    before?: unknown;
+    after?: unknown;
+}
+/** Различия объекта между двумя версиями (diff()). */
+export interface DiffResult {
+    id: string;
+    class: string | null;
+    from: {
+        rev: number;
+        at: string;
+        id?: string;
+    } | null;
+    to: {
+        rev: number;
+        at: string;
+        id?: string;
+        deleted?: true;
+    } | null;
+    changes: DiffChange[];
+}
+/** Кто и почему последним изменил лист версии (blame()). */
+export interface BlameField {
+    path: string[];
+    rev: number;
+    at: string;
+    author: string;
+    agent?: string;
+    op: string;
+    reason?: string;
+    /** Другой id (история прошла через смену id при reclass или rekey). */
+    id?: string;
+    /** false — до найденной версии история неполная: изменение могло быть раньше. */
+    exact: boolean;
+}
+/** Поля версии объекта с версиями, которые их изменили (blame()). */
+export interface BlameResult {
+    id: string;
+    class: string;
+    rev: number;
+    deleted?: true;
+    /** История просмотрена целиком и без пропусков. */
+    complete: boolean;
+    fields: BlameField[];
+}
+/** diff(): «до» и «после» — номер версии или момент (ISO-строка, Date); follow — через смену id. */
+export interface DiffOptions {
+    from?: number | string | Date;
+    to?: number | string | Date;
+    follow?: boolean;
+}
+/** blame(): версия на момент at (по умолчанию текущая); limit — сколько версий просматривать (1000). */
+export interface BlameOptions {
+    at?: string | Date;
+    limit?: number;
+}

package/dist/types.js

@@ -2,7 +2,12 @@
  * Общие типы letopis 1.0. Файл наполняется по этапам плана (reports/PLAN-LETOPIS-1.0.md).
  */
 /** Ревизия движка в базе: штамп в lib/sql/99-revision.sql должен совпадать (этап 1). */
-export const DDL_REVISION = 5;
+export const DDL_REVISION = 6;
+/**
+ * Классы, строки которых меняют права и схему: их запись повышает счётчик прав (загрузчик), а сигнал
+ * сбрасывает весь кэш результатов и пропуска прав. Тот же список — в триггерах базы (60-write.sql).
+ */
+export const ACL_CLASS_NAMES = ['rule', 'Resource', 'member', 'Account', 'Class'];
 // ---------------------------------------------------------------------------
 // Методы цепочки — единственный источник зарезервированных имён (план, §2.14, этап 3, п. 10)
 // ---------------------------------------------------------------------------
@@ -11,7 +16,7 @@ export const CHAIN_METHODS = [
     'then', 'entity', 'paths', 'rows', 'first', 'ids', 'count', 'limit', 'offset', 'sort', 'asOf', 'withDeleted',
     'deep', 'exact', 'sum', 'avg', 'min', 'max', 'countBy', 'after', 'versions', 'create', 'update', 'upsert', 'set',
     'unset', 'add', 'remove', 'delete', 'anonymize', 'reclass', 'restore', 'purge', 'alias', 'tags', 'owner',
-    'forUpdate', 'cache', 'rekey', 'run', 'execute', 'account',
+    'forUpdate', 'cache', 'rekey', 'run', 'execute', 'account', 'diff', 'blame',
 ];
 /** Свойства корня db (и транзакции db.begin()). */
 export const DB_METHODS = [

package/dist/up.d.ts

@@ -1,5 +1,6 @@
 import postgres from 'postgres';
 import { type PgliteOptions, type PgliteServer } from './pglite.js';
+import { type SignalMode } from './signals.js';
 export declare const SYSTEM_ID = "2eba6d0a-1edd-4bb6-a85a-a703dab49035";
 export declare const SCHEMA_VERSION = "v2";
 export interface InstallOptions {
@@ -25,6 +26,12 @@ export interface InstallOptions {
     migrationsDir?: string;
     /** Свой ключ сервиса: зарегистрировать, если такого ещё нет (вместо выпуска случайного). */
     serviceKey?: string;
+    /**
+     * Режим сигналов NOTIFY (план 1.1, §2.2): 'class' (по умолчанию, как в 1.0) — имена классов; 'tenant' —
+     * имя класса и токен арендатора; 'opaque' — только токены; 'none' — сигналов нет. Режим хранится в
+     * схеме: накат без опции его не меняет, reset({ all }) — сохраняет.
+     */
+    signals?: SignalMode;
 }
 /** Политика хранения истории (§2.11): сроки ярусов по возрастанию, 'forever' — бессрочно. */
 export interface HistoryPolicy {
@@ -44,6 +51,8 @@ export interface InstallResult {
     serviceKey: string | null;
     /** Применённые миграции. */
     migrations: string[];
+    /** Режим сигналов установки после наката. */
+    signals: SignalMode;
 }
 export declare const quoteIdent: (name: string) => string;
 /** Файлы ядра по номеру: `10-core.sql` … `99-revision.sql`; сиды демо-домена сюда не входят. */
@@ -88,6 +97,8 @@ export interface UpResult extends InstallResult {
     pglite?: PgliteServer;
     /** up({ tenant }): арендатор (и его первый пользователь с сессией). */
     tenant?: TenantResult;
+    /** Предупреждения (версия сервера); без quiet каждое уже напечатано через console.warn. */
+    warnings: string[];
 }
 type Ping = {
     ok: true;
@@ -100,8 +111,11 @@ type Ping = {
 export declare function pgPing(dsn: string): Promise<Ping>;
 /** Создать базу строки подключения, если её нет (гонка параллельных up() — 42P04 — не ошибка). */
 export declare function ensureDatabase(dsn: string, log?: (m: string) => void): Promise<boolean>;
-/** Версия сервера и кодировка базы: PostgreSQL 18+ и UTF8 (casefold и pg_unicode_fast требуют UTF8). */
-export declare function checkServer(versionNum: number, encoding: string): void;
+/**
+ * Версия сервера и кодировка базы: PostgreSQL 18+ и UTF8 (casefold и pg_unicode_fast требуют UTF8) —
+ * иначе отказ. Возвращает предупреждения: с чем установка работает, но рискует.
+ */
+export declare function checkServer(versionNum: number, encoding: string): string[];
 /** Ревизия движка схемы по комментарию 'letopis ddl_revision=N'; схемы нет — null. */
 export declare function schemaRevision(sql: postgres.Sql, schema: string): Promise<number | null>;
 /**

package/dist/up.js

@@ -20,6 +20,7 @@ import { startPglite } from './pglite.js';
 import { hashPassword } from './auth.js';
 import { LetopisError } from './errors.js';
 import { v5Id } from './uuid.js';
+import { SIGNAL_MODES } from './signals.js';
 export const SYSTEM_ID = '2eba6d0a-1edd-4bb6-a85a-a703dab49035';
 export const SCHEMA_VERSION = 'v2';
 const SQL_DIR = fileURLToPath(new URL('../sql/', import.meta.url));
@@ -48,6 +49,9 @@ export async function install(sql, opts) {
     for (const r of [owner, app])
         if (!ROLE_NAME.test(r))
             throw new Error(`letopis.up: bad role name "${r}"`);
+    if (opts.signals !== undefined && !SIGNAL_MODES.includes(opts.signals)) {
+        throw new Error(`letopis.up: signals — ${SIGNAL_MODES.join(', ')}, а не ${String(opts.signals)}`);
+    }
     const [{ v }] = await sql `select current_setting('server_version_num') as v`;
     if (Number(v) < 180000)
         throw new Error(`letopis.up: нужен PostgreSQL 18 или новее, а сервер — ${v}`);
@@ -81,14 +85,27 @@ export async function install(sql, opts) {
         HISTORY_DEFAULT: quoteLiteral(JSON.stringify(opts.history ?? null)),
         // методы цепочки — в тексте функции reserved_names() (план, §2.14)
         RESERVED_NAMES: RESERVED_CLASS_NAMES.map(quoteLiteral).join(', '),
+        // режим сигналов — после set role: сохранённый режим лежит в строке ключа secret владельца
+        SIGNALS: 'class',
     };
     // Схема создаётся до set role: у владельца может не быть права CREATE в базе.
     await sql.unsafe(`create schema if not exists ${quoteIdent(opts.schema)} authorization ${quoteIdent(owner)}`);
     const files = await engineFiles(opts.upTo);
     const migrations = opts.migrateFrom === undefined ? [] : await migrationFiles(opts.migrationsDir ?? MIGRATE_DIR, opts.migrateFrom);
     let serviceKey = null;
+    let signals = 'class';
     await sql.begin(async (tx) => {
         await tx.unsafe(`set local role ${quoteIdent(owner)}`);
+        // режим сигналов (план 1.1, §2.6): опция, иначе сохранённый в схеме (meta строки ключа), иначе class
+        let saved = null;
+        const [reg] = await tx.unsafe(`select to_regclass($1) is not null as ok`, [`${quoteIdent(opts.schema)}.secret`]);
+        if (reg?.ok) {
+            const [k] = await tx.unsafe(`select meta->>'signals' as m from ${quoteIdent(opts.schema)}.secret where id = $1::uuid and kind = 'KEY'`, [SYSTEM_ID]);
+            if (SIGNAL_MODES.includes(k?.m))
+                saved = k.m;
+        }
+        signals = opts.signals ?? saved ?? 'class';
+        vars.SIGNALS = signals;
         // структурные изменения прежних ревизий — до повторного наката функций (этап 6, п. 10)
         for (const m of migrations) {
             try {
@@ -155,7 +172,7 @@ export async function install(sql, opts) {
             }
         }
     });
-    return { schema: opts.schema, owner, app, serviceKey, migrations };
+    return { schema: opts.schema, owner, app, serviceKey, migrations, signals };
 }
 /** Миграции с номером выше ревизии from и не выше DDL_REVISION: `0004-описание.sql`, по номеру. */
 export async function migrationFiles(dir, from) {
@@ -213,12 +230,22 @@ export async function ensureDatabase(dsn, log = () => { }) {
         await sql.end({ timeout: 1 });
     }
 }
-/** Версия сервера и кодировка базы: PostgreSQL 18+ и UTF8 (casefold и pg_unicode_fast требуют UTF8). */
+/**
+ * Версия сервера и кодировка базы: PostgreSQL 18+ и UTF8 (casefold и pg_unicode_fast требуют UTF8) —
+ * иначе отказ. Возвращает предупреждения: с чем установка работает, но рискует.
+ */
 export function checkServer(versionNum, encoding) {
     if (versionNum < 180000)
         throw new Error(`letopis.up: нужен PostgreSQL 18 или новее, а сервер — ${Math.floor(versionNum / 10000)} (${versionNum})`);
     if (encoding.toUpperCase() !== 'UTF8')
         throw new Error(`letopis.up: база в кодировке ${encoding}, нужна UTF8 (casefold и коллация pg_unicode_fast)`);
+    const warnings = [];
+    // план 1.1, этап 2: исправлено в 18.2
+    if (versionNum < 180002) {
+        warnings.push(`PostgreSQL ${Math.floor(versionNum / 10000)}.${versionNum % 10000}: до 18.2 сервер мог усечь CLOG, который ещё нужен `
+            + 'непрочитанным сигналам NOTIFY; обновите сервер до 18.2 или новее');
+    }
+    return warnings;
 }
 /** Ревизия движка схемы по комментарию 'letopis ddl_revision=N'; схемы нет — null. */
 export async function schemaRevision(sql, schema) {
@@ -267,7 +294,10 @@ export async function up(opts) {
     try {
         const [srv] = await sql `select current_setting('server_version_num')::int as v, pg_encoding_to_char(encoding) as enc
       from pg_database where datname = current_database()`;
-        checkServer(srv.v, srv.enc);
+        const warnings = checkServer(srv.v, srv.enc);
+        if (!opts.quiet)
+            for (const w of warnings)
+                console.warn(`letopis.up: ${w}`);
         if (opts.fresh) {
             await sql.unsafe(`drop schema if exists ${quoteIdent(schema)} cascade`);
             log(`схема ${schema} удалена (fresh)`);
@@ -290,7 +320,7 @@ export async function up(opts) {
         const revision = (await schemaRevision(sql, schema)) ?? 0;
         log(`${before === null ? 'схема поставлена' : before < DDL_REVISION ? `схема обновлена с ревизии ${before}` : 'повторный накат'}: ${schema}, ревизия ${revision}`);
         const tenant = opts.tenant ? await createTenant(sql, schema, opts.tenant, opts.owner) : undefined;
-        return { ...res, created: before === null, upgraded: before !== null && before < DDL_REVISION, revision, analyzed,
+        return { ...res, created: before === null, upgraded: before !== null && before < DDL_REVISION, revision, analyzed, warnings,
             ...(lite ? { pglite: lite } : {}), ...(tenant ? { tenant } : {}) };
     }
     catch (e) {