letopis 1.3.0 → 1.4.1

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';
@@ -23,6 +24,13 @@ 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';
+/**
+ * Advisory-ключ наката одной схемы: пара int4, как у общей части установки (`hashtext('install')`), — имя схемы
+ * всегда с точкой (`v2.имя`), поэтому со словом install ключи не совпадут.
+ */
+async function lockSchema(tx, schema) {
+    await tx.unsafe(`select pg_advisory_xact_lock(hashtext('letopis'), hashtext($1))`, [schema]);
+}
 const SQL_DIR = fileURLToPath(new URL('../sql/', import.meta.url));
 const MIGRATE_DIR = join(SQL_DIR, 'migrate');
 const ROLE_NAME = /^[a-z_][a-z0-9_]{0,62}$/;
@@ -34,6 +42,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))
@@ -55,23 +122,40 @@ export async function install(sql, opts) {
     const [{ v }] = await sql `select current_setting('server_version_num') as v`;
     if (Number(v) < 180000)
         throw new Error(`letopis.up: нужен PostgreSQL 18 или новее, а сервер — ${v}`);
-    // Роли — общие для кластера; создаются идемпотентно.
-    for (const r of [owner, app]) {
-        await sql.unsafe(`do $$ begin
-      if not exists (select 1 from pg_roles where rolname = ${quoteLiteral(r)}) then
-        create role ${quoteIdent(r)} nologin;
-      end if;
-    exception when duplicate_object then null; end $$`);
-    }
-    // Установщик получает права владельца только на время set role (план, §2.9).
-    await sql.unsafe(`grant ${quoteIdent(owner)} to current_user with inherit false, set true`).catch((e) => {
-        if (e.code !== '0LP01')
-            throw e; // уже выдано циклом — нет
+    // Общая часть установки — роли, членство установщика, pgcrypto и право владельца на схему pgcrypto — одна на все
+    // установки базы, а роли — на весь кластер. Параллельные up() разных схем меняли её одновременно: grant на схему
+    // pgcrypto переписывает её строку pg_namespace, даже если право уже есть, и второй такой grant падал «tuple
+    // concurrently updated» (XX000); на чистой базе второй create role или create extension упал бы на уникальном индексе
+    // каталога. Поэтому общая часть — отдельная транзакция под advisory-блокировкой: другой up() ждёт её фиксации и
+    // видит готовые объекты. Строка-замок, как у внутренних блокировок движка (60-write.sql), не годится: таблицы secret
+    // до установки нет, и у каждой схемы она своя — разные установки друг друга не увидели бы. Advisory-ключ может занять
+    // любая роль базы (ревью безопасности №2 и №3), но так посторонний задержит только up() — операцию администратора, а
+    // не запись; кто держит ключ, видно в pg_locks. Ключ — пара int4: это пространство ключей отдельно от lock() явной
+    // транзакции (int8). Блокировка живёт до конца транзакции, обрыв соединения её снимает.
+    // Advisory-блокировка действует в пределах базы, а роли общие для кластера: up() в другой базе может создать роль
+    // или членство одновременно с этим, тогда здесь unique_violation (23505) — роль или членство уже есть.
+    const nsp = await sql.begin(async (tx) => {
+        await tx.unsafe(`select pg_advisory_xact_lock(hashtext('letopis'), hashtext('install'))`);
+        for (const r of [owner, app]) {
+            await tx.unsafe(`do $$ begin
+        if not exists (select 1 from pg_roles where rolname = ${quoteLiteral(r)}) then
+          create role ${quoteIdent(r)} nologin;
+        end if;
+      exception when duplicate_object or unique_violation then null; end $$`);
+        }
+        // Установщик получает права владельца только на время set role (план, §2.9). Отказ гранта откатывает только
+        // точку сохранения, а не всю транзакцию.
+        await tx.savepoint((sp) => sp.unsafe(`grant ${quoteIdent(owner)} to current_user with inherit false, set true`))
+            .catch((e) => {
+            if (e.code !== '0LP01' && e.code !== '23505')
+                throw e; // уже выдано циклом — нет; 23505 — выдал up() другой базы
+        });
+        await tx.unsafe(`create extension if not exists pgcrypto`);
+        const [{ nsp }] = await tx.unsafe(`
+      select n.nspname as nsp from pg_extension e join pg_namespace n on n.oid = e.extnamespace where e.extname = 'pgcrypto'`);
+        await tx.unsafe(`grant usage on schema ${quoteIdent(nsp)} to ${quoteIdent(owner)}`);
+        return nsp;
     });
-    await sql.unsafe(`create extension if not exists pgcrypto`);
-    const [{ nsp }] = await sql `
-    select n.nspname as nsp from pg_extension e join pg_namespace n on n.oid = e.extnamespace where e.extname = 'pgcrypto'`;
-    await sql.unsafe(`grant usage on schema ${quoteIdent(nsp)} to ${quoteIdent(owner)}`);
     const vars = {
         SCHEMA: quoteIdent(opts.schema),
         SCHEMA_NAME: opts.schema,
@@ -88,13 +172,31 @@ export async function install(sql, opts) {
         // режим сигналов — после set role: сохранённый режим лежит в строке ключа secret владельца
         SIGNALS: 'class',
     };
-    // Схема создаётся до set role: у владельца может не быть права CREATE в базе.
-    await sql.unsafe(`create schema if not exists ${quoteIdent(opts.schema)} authorization ${quoteIdent(owner)}`);
+    // штамп движка — в комментарий схемы (99-revision.sql): по нему connect() узнаёт схему, не накатанную этой версией
+    const st = await engineStamp();
+    vars.ENGINE_VERSION = st.version;
+    vars.ENGINE_SQL = st.sql;
     const files = await engineFiles(opts.upTo);
-    const migrations = opts.migrateFrom === undefined ? [] : await migrationFiles(opts.migrationsDir ?? MIGRATE_DIR, opts.migrateFrom);
+    let migrations = [];
+    let found = null;
     let serviceKey = null;
     let signals = 'class';
     await sql.begin(async (tx) => {
+        // Накат схемы — под advisory-блокировкой самой схемы. Несколько экземпляров сервиса зовут up() одной схемы при
+        // запуске разом: без блокировки второй create schema падал на уникальном индексе каталога (23505), а второй
+        // create or replace function или comment — «tuple concurrently updated» (XX000). С ней следующий up() ждёт, пока
+        // предыдущий зафиксирует накат, и делает повторный накат по готовой схеме. Поэтому и fresh, и ревизия, от которой
+        // считаются миграции, — под блокировкой: up() видит ревизию до неё, и второй upgrade повторил бы миграции, уже
+        // накатанные первым. Разные схемы друг друга не ждут: ключ — имя схемы.
+        await lockSchema(tx, opts.schema);
+        if (opts.fresh)
+            await tx.unsafe(`drop schema if exists ${quoteIdent(opts.schema)} cascade`);
+        found = await schemaRevision(tx, opts.schema);
+        if (opts.migrateFrom !== undefined && found !== null) {
+            migrations = await migrationFiles(opts.migrationsDir ?? MIGRATE_DIR, Math.max(opts.migrateFrom, found));
+        }
+        // Схема создаётся до set role: у владельца может не быть права CREATE в базе.
+        await tx.unsafe(`create schema if not exists ${quoteIdent(opts.schema)} authorization ${quoteIdent(owner)}`);
         await tx.unsafe(`set local role ${quoteIdent(owner)}`);
         // режим сигналов (план 1.1, §2.6): опция, иначе сохранённый в схеме (meta строки ключа), иначе class
         let saved = null;
@@ -172,7 +274,7 @@ export async function install(sql, opts) {
             }
         }
     });
-    return { schema: opts.schema, owner, app, serviceKey, migrations, signals };
+    return { schema: opts.schema, owner, app, serviceKey, migrations, signals, found };
 }
 /** Миграции с номером выше ревизии from и не выше DDL_REVISION: `0004-описание.sql`, по номеру. */
 export async function migrationFiles(dir, from) {
@@ -249,14 +351,15 @@ export function checkServer(versionNum, encoding) {
 }
 /** Ревизия движка схемы по комментарию 'letopis ddl_revision=N'; схемы нет — null. */
 export async function schemaRevision(sql, schema) {
-    const [r] = await sql `select obj_description(n.oid, 'pg_namespace') as c from pg_namespace n where n.nspname = ${schema}`;
+    const [r] = await sql.unsafe(`select obj_description(n.oid, 'pg_namespace') as c from pg_namespace n where n.nspname = $1`, [schema]);
     if (!r)
         return null;
     return Number(/ddl_revision=(\d+)/.exec(String(r.c ?? ''))?.[1] ?? 0);
 }
 /**
- * Поставить или обновить установку letopis. Схема есть и её ревизия совпадает — повторный накат
- * (идемпотентный); ревизия отстала — только с upgrade: true; новее библиотеки — отказ.
+ * Ставит или обновляет установку letopis в схеме. Если схема уже есть и её ревизия та же, что у пакета, `up()` выполняет
+ * повторный накат: заново ставит функции, не трогая данные, — поэтому его можно вызывать при каждом запуске приложения.
+ * Схему отставшей ревизии `up()` обновляет только с `upgrade: true`, а на схеме новее пакета отказывает.
  */
 export async function up(opts) {
     const log = opts.quiet ? () => { } : (m) => console.log(`letopis.up: ${m}`);
@@ -298,11 +401,8 @@ export async function up(opts) {
         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)`);
-        }
-        const before = await schemaRevision(sql, schema);
+        // ревизия до блокировки схемы — для ранних отказов; что накатывать, install() решает по ревизии под блокировкой
+        const before = opts.fresh ? null : await schemaRevision(sql, schema);
         if (before !== null && before > DDL_REVISION) {
             throw new Error(`letopis.up: схема ${schema} ревизии ${before}, а библиотека знает только ${DDL_REVISION} — обновите пакет`);
         }
@@ -310,7 +410,11 @@ export async function up(opts) {
             throw new Error(`letopis.up: схема ${schema} ревизии ${before}, библиотека — ${DDL_REVISION}: обновите её up({ schema: '${schema}', upgrade: true })`);
         }
         const { dsn: _d, sql: _s, schema: _sc, fresh: _f, upgrade: _u, quiet: _q, waitTimeoutMs: _w, pglite: _p, ...rest } = opts;
-        const res = await install(sql, { ...rest, schema, ...(before !== null && before < DDL_REVISION ? { migrateFrom: before } : {}) });
+        const { found, ...res } = await install(sql, {
+            ...rest, schema, ...(opts.fresh ? { fresh: true } : {}), ...(before !== null && before < DDL_REVISION ? { migrateFrom: before } : {}),
+        });
+        if (opts.fresh)
+            log(`схема ${schema} удалена и поставлена заново (fresh)`);
         // ANALYZE — только там, где статистики ещё нет: на повторном накате это самая дорогая часть
         const fresh = await sql `select relname from pg_stat_user_tables
       where schemaname = ${schema} and last_analyze is null and last_autoanalyze is null order by relname`;
@@ -318,9 +422,9 @@ export async function up(opts) {
         for (const t of analyzed)
             await sql.unsafe(`analyze ${quoteIdent(schema)}.${quoteIdent(t)}`);
         const revision = (await schemaRevision(sql, schema)) ?? 0;
-        log(`${before === null ? 'схема поставлена' : before < DDL_REVISION ? `схема обновлена с ревизии ${before}` : 'повторный накат'}: ${schema}, ревизия ${revision}`);
+        log(`${found === null ? 'схема поставлена' : found < DDL_REVISION ? `схема обновлена с ревизии ${found}` : 'повторный накат'}: ${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, warnings,
+        return { ...res, created: found === null, upgraded: found !== null && found < DDL_REVISION, revision, analyzed, warnings,
             ...(lite ? { pglite: lite } : {}), ...(tenant ? { tenant } : {}) };
     }
     catch (e) {
@@ -335,8 +439,11 @@ export async function up(opts) {
             await sql.end({ timeout: 5 }).catch(() => { });
     }
 }
+/** Служебные виды строк secret: их не принимают функции кредов (auth_kind_ok в 80-auth.sql) и createTenant. */
+const SERVICE_KINDS = ['SESSION', 'APIKEY', 'KEYSECRET', 'OTP', 'TOTP', 'KEY', 'PROJECTOR', 'LOCK'];
 /**
- * Опции арендатора до записи; возвращает роли членства пользователя (по умолчанию owner). Членство
+ * Опции арендатора до записи; возвращает роли членства пользователя (по умолчанию owner). Вид пароля user.kind — как у
+ * функций кредов (auth_kind_ok). Членство
  * пишет sys_create от владельца — без проверки класса member, поэтому список ролей проверяется здесь:
  * непустой, без повторов, каждая роль — имя, а не маска группы '{a,b}': не пустое, без пробелов по
  * краям (маска их отрезает) и запятых (разделитель маски), без фигурных скобок и «!» в начале
@@ -345,6 +452,12 @@ export async function up(opts) {
 function checkTenant(opts) {
     if (!opts.name)
         throw new Error('letopis.createTenant: имя арендатора обязательно');
+    // вид пароля — по правилу функций кредов (auth_kind_ok в 80-auth.sql): пароль пишет функция владельца мимо них, а с
+    // видом в другом регистре или служебным (SESSION, TOTP…) по нему не войти, и служебные строки он подменял бы
+    const kind = opts.user?.kind;
+    if (kind != null && (typeof kind !== 'string' || !/^[A-Z][A-Z0-9_]{1,31}$/.test(kind) || SERVICE_KINDS.includes(kind))) {
+        throw new LetopisError('invalid_data', `createTenant: user.kind ${JSON.stringify(kind)} — вид пароля: заглавная латинская буква, затем заглавные буквы, цифры или «_», всего от 2 до 32 знаков; служебные виды ${SERVICE_KINDS.join(', ')} заняты (по умолчанию — PASSWORD)`);
+    }
     if (opts.user?.roles === undefined)
         return ['owner'];
     const roles = opts.user.roles;
@@ -363,14 +476,10 @@ function checkTenant(opts) {
     return roles;
 }
 /**
- * Арендатор и его первый пользователь — то, что раньше делал свой сид функциями владельца
- * (sys_create, sys_grant_all). Нужно администраторское подключение (роль может стать владельцем);
- * всё — одной транзакцией от владельца. Повтор с тем же именем и логином ничего не дублирует:
- * id — v5 от имени и логина, существующие строки пропускаются (пароль и роли членства не меняются),
- * сессия выдаётся заново. Удалённые арендатор, аккаунт пользователя или членство (строки нет, а
- * журнал id есть) — отказ invalid_data, транзакция откатывается целиком: повтор не воскрешает то,
- * что удалил администратор (up({ tenant }) идёт при каждом запуске), а sys_create пишет только
- * версию 1 — её занимает история; вернуть строку — restore() цепочкой.
+ * Заводит арендатора и, по желанию, его первого пользователя (аккаунт, членство, пароль, сессию) одной транзакцией от
+ * роли-владельца схемы — поэтому нужен администраторский пул. Повтор с тем же именем и логином ничего не дублирует и не
+ * меняет, только выдаёт пользователю новую сессию; одновременные вызовы заводят арендатора один раз. Если арендатор,
+ * пользователь или членство были удалены, повтор их не воскрешает — отказ `invalid_data`.
  */
 export async function createTenant(sql, schema, opts, owner = 'letopis_owner') {
     const roles = checkTenant(opts);
@@ -380,6 +489,9 @@ export async function createTenant(sql, schema, opts, owner = 'letopis_owner') {
     const user = u ? v5Id(SYSTEM_ID, 'Account', [`user:${u.login}`]) : null;
     const hash = u ? await hashPassword(u.password) : null;
     return sql.begin(async (tx) => {
+        // под блокировкой схемы, как накат: up({ tenant }) нескольких экземпляров сервиса разом заводит арендатора один
+        // раз, остальные находят его по имени (без неё оба вставили бы ту же строку и один упал бы на ключе)
+        await lockSchema(tx, schema);
         await tx.unsafe(`set local role ${quoteIdent(owner)}`);
         /** Строка есть — true, не было — false; строки нет, а журнал id есть, — удалена: отказ gone (что и как вернуть). */
         const exists = async (id, cls, gone) => {

package/dist/validate.d.ts

@@ -17,8 +17,15 @@ export interface Validator {
     /** Нарушения ([] — данные приняты). */
     (data: unknown): Issue[];
 }
-/** Компилирует JSON Schema (разворот resolved.schema класса) в функцию проверки. */
+/**
+ * Превращает JSON Schema данных класса в функцию проверки — ту же проверку, что выполняет база при записи. Схема
+ * класса — `db.registry.resolve(имя).schema`.
+ */
 export declare function compileValidator(schema: JsonSchema): Validator;
-/** Умолчания, как apply_defaults в базе: на каждом уровне, во вложенные объекты — только если они есть. */
+/**
+ * Подставляет в данные значения по умолчанию (`default`) из JSON Schema класса, как база перед проверкой при каждой
+ * записи: только в отсутствующие поля, а во вложенный объект — только если он в данных уже есть. Исходные данные не
+ * меняются.
+ */
 export declare function applyDefaults(schema: JsonSchema, data: unknown): unknown;
 export {};

package/dist/validate.js

@@ -136,7 +136,16 @@ function compileNode(s, sel, path, inAny, out) {
     if (sch.multipleOf !== undefined)
         out.push({ path, keyword: 'multipleOf', select: sel, test: num((v, b) => isMultiple(v, b), sch.multipleOf) });
     if (sch.pattern !== undefined) {
-        const re = new RegExp(translatePattern(sch.pattern));
+        const src = translatePattern(sch.pattern); // то, чего база не понимает, — своя ошибка invalid_class
+        let re;
+        try {
+            re = new RegExp(src);
+        }
+        catch {
+            // шаблон, неверный уже для JavaScript (незакрытая скобка и т. п.): translatePattern его пропускает, RegExp — нет.
+            // Текст V8 в сообщение не идёт: он зависит от версии движка
+            fail(path, `pattern ${JSON.stringify(sch.pattern)} — неверное регулярное выражение`);
+        }
         out.push({ path, keyword: 'pattern', select: sel, test: (v) => typeof v !== 'string' || re.test(v) });
     }
     if (sch.format !== undefined) {
@@ -211,7 +220,10 @@ function compileNode(s, sel, path, inAny, out) {
                 : (v) => branches.filter((b) => b(v)).length === 1 });
     }
 }
-/** Компилирует JSON Schema (разворот resolved.schema класса) в функцию проверки. */
+/**
+ * Превращает JSON Schema данных класса в функцию проверки — ту же проверку, что выполняет база при записи. Схема
+ * класса — `db.registry.resolve(имя).schema`.
+ */
 export function compileValidator(schema) {
     const rules = [];
     compileNode(schema, (root) => [root], [], false, rules);
@@ -233,7 +245,11 @@ export function compileValidator(schema) {
         return issues;
     };
 }
-/** Умолчания, как apply_defaults в базе: на каждом уровне, во вложенные объекты — только если они есть. */
+/**
+ * Подставляет в данные значения по умолчанию (`default`) из JSON Schema класса, как база перед проверкой при каждой
+ * записи: только в отсутствующие поля, а во вложенный объект — только если он в данных уже есть. Исходные данные не
+ * меняются.
+ */
 export function applyDefaults(schema, data) {
     if (!isObj(data) || !isObj(schema.properties))
         return data;

package/dist/watch.d.ts

@@ -2,13 +2,17 @@ import type { Executor } from './tx.js';
 import type { Row } from './types.js';
 import type { Signal } from './signals.js';
 export interface WatchOptions {
-    /** Откуда: курсор события, 'now' (по умолчанию — изменения после подписки) или 'start' (весь журнал). */
+    /** Откуда: курсор (sub.cursor или курсор события), 'now' (по умолчанию — изменения после подписки) или 'start' (весь журнал). */
     from?: string;
     /** Только эти классы (с потомками). */
     classes?: string[];
     /** Событий за запрос (по умолчанию 500). */
     batch?: number;
-    /** Запасной опрос, мс (по умолчанию 1000; без LISTEN — единственный способ узнать о событиях). */
+    /**
+     * Как часто подписка сама проверяет журнал, мс (по умолчанию 1000): так она находит события, даже если сигнал базы не
+     * пришёл. Без сигналов (`connect({ listen: false })` или установка с `up({ signals: 'none' })`) новые события она
+     * узнаёт только так.
+     */
     pollMs?: number;
 }
 export interface WatchEvent {
@@ -43,6 +47,8 @@ export declare class Subscription implements AsyncIterable<WatchEvent> {
     private opts;
     private pos;
     private buf;
+    /** Курсор после последнего выданного события, пока в буфере есть невыданные (pos — уже после всей пачки). */
+    private given;
     private closed;
     private wake;
     private dirty;
@@ -56,11 +62,17 @@ export declare class Subscription implements AsyncIterable<WatchEvent> {
     /** Вызовы next() — по очереди: параллельные получают разные события (доработки после точки Б). */
     private queue;
     constructor(ctx: WatchCtx, opts: WatchOptions);
-    /** Курсор последнего выданного события (или начальной точки). */
+    /**
+     * Курсор подписки: позиция после последнего выданного события (или начальная точка). Догнав журнал, подписка обновляет
+     * в нём время и на пустых опросах, поэтому его, а не курсор события, сохраняют, чтобы продолжить после перезапуска:
+     * курсор события хранит время события, и когда оно выйдет за ярус all политики хранения, продолжение с него —
+     * cursor_expired.
+     */
     get cursor(): string | null;
     /**
-     * Начальная точка взята (доработки после точки Б): у from: 'now' — горизонт и снимок момента подписки (watch_head());
-     * у 'start' и курсора — сразу. Запись после await sub.ready() придёт в поток; ошибка начальной точки — отказ.
+     * Промис выполняется, когда подписка запомнила начальную точку: запись, сделанная после этого, придёт в поток
+     * (доработки после точки Б). У `from: 'now'` точку запоминает отдельный запрос к базе, у `'start'` и курсора промис
+     * выполняется сразу; если запрос не удался, промис отклоняется с его ошибкой.
      */
     ready(): Promise<void>;
     private head;

package/dist/watch.js

@@ -13,7 +13,9 @@
  * без LISTEN и на случай потери сигнала — запасной опрос.
  *
  * Курсор подписчика старше яруса all политики хранения его классов — cursor_expired: события могли
- * проредиться, нужно перечитать текущее состояние и подписаться заново.
+ * проредиться, нужно перечитать текущее состояние и подписаться заново. Время курсора подписки — время последнего
+ * события, а догнавшей журнал подписки — время опроса (не позже самой старой ещё не отданной записи): подписка без
+ * событий не стареет. Курсор события хранит время события.
  */
 import { LetopisError } from './errors.js';
 import { toRow } from './sql.js';
@@ -54,6 +56,8 @@ export class Subscription {
     opts;
     pos = null;
     buf = [];
+    /** Курсор после последнего выданного события, пока в буфере есть невыданные (pos — уже после всей пачки). */
+    given = null;
     closed = false;
     wake = null;
     dirty = true;
@@ -95,13 +99,21 @@ export class Subscription {
         }, this.pollMs);
         this.timer.unref?.();
     }
-    /** Курсор последнего выданного события (или начальной точки). */
+    /**
+     * Курсор подписки: позиция после последнего выданного события (или начальная точка). Догнав журнал, подписка обновляет
+     * в нём время и на пустых опросах, поэтому его, а не курсор события, сохраняют, чтобы продолжить после перезапуска:
+     * курсор события хранит время события, и когда оно выйдет за ярус all политики хранения, продолжение с него —
+     * cursor_expired.
+     */
     get cursor() {
+        if (this.buf.length)
+            return this.given;
         return this.pos ? encode(this.pos) : null;
     }
     /**
-     * Начальная точка взята (доработки после точки Б): у from: 'now' — горизонт и снимок момента подписки (watch_head());
-     * у 'start' и курсора — сразу. Запись после await sub.ready() придёт в поток; ошибка начальной точки — отказ.
+     * Промис выполняется, когда подписка запомнила начальную точку: запись, сделанная после этого, придёт в поток
+     * (доработки после точки Б). У `from: 'now'` точку запоминает отдельный запрос к базе, у `'start'` и курсора промис
+     * выполняется сразу; если запрос не удался, промис отклоняется с его ошибкой.
      */
     async ready() {
         if (!this.pos && this.start)
@@ -122,18 +134,28 @@ export class Subscription {
         // уход строки из классов подписки сменой класса без смены id (хвост ревью безопасности №3) — надгробием прежней
         // версии в том же окне: полная пачка watch_read ограничивает окно своей последней строкой. Оба потока — одним
         // оператором: общий снимок и горизонт, иначе курсор перескочил бы событие, зафиксированное между запросами
-        // (автоматическое ревью). Потоки сливаются по (tx, seq) до границы — последней строки потока, обрезанного лимитом
+        // (автоматическое ревью). Потоки сливаются по (tx, seq) до границы — последней строки потока, обрезанного лимитом.
+        // Третья строка (src 2) — время курсора, когда пачка неполная (подписка догнала журнал): «сейчас», но не позже самой
+        // старой записи подписки, которая уже зафиксирована, а горизонт ещё не прошла (её держит более старая транзакция;
+        // снимок «now» — без записей, которые подписка не отдаёт). Тот же снимок, что у watch_read
         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 });
+         (select tx from u), (select seq from u)) l
+       union all
+       select 2 as src, null, null, jsonb_build_object('at', least(statement_timestamp(), min(l.at))) from ${S}.log l
+       where (select count(*) from r) < $5 and (l.tx, l.seq) > ($1::text::xid8, $2::bigint)
+         and l.tx >= pg_snapshot_xmin(pg_current_snapshot()) and ($4::text[] is null or l.class = any ($4::text[]))
+         and ($6::text::pg_snapshot is null or not pg_visible_in_snapshot(l.tx, $6::text::pg_snapshot))
+       having (select count(*) from r) < $5`, [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);
+        const caught = both.find((r) => r.src === 2);
         let rows = read;
         {
             const upto = read.length === this.batch ? read[read.length - 1] : null;
@@ -145,12 +167,19 @@ export class Subscription {
                 rows = [...read, ...away].sort(order).filter((r) => !bound || !before(bound, r));
             }
         }
+        // пока события пачки не выданы, курсор подписки — позиция до пачки
+        if (rows.length)
+            this.given = encode(p);
         for (const r of rows) {
             const row = toRow(r.row);
             const snap = keepSnap(p.snap, r.tx);
             this.pos = { tx: r.tx, seq: r.seq, at: row.at, ...(snap ? { snap } : {}) };
             this.buf.push({ cursor: encode(this.pos), row, id: row.id, class: row.class, op: row.op, rev: row.rev, at: row.at });
         }
+        // догнала журнал — время курсора подписки (sub.cursor) обновляется и на пустых опросах: прореживать после него нечего,
+        // и подписка, к которой долго не было событий, не получает ложный cursor_expired. Курсоры событий хранят время события
+        if (caught && away.length < this.batch)
+            this.pos = { ...(this.pos ?? p), at: String(caught.row.at) };
         return rows.length;
     }
     /**
@@ -167,8 +196,11 @@ export class Subscription {
         for (;;) {
             if (this.failure)
                 throw this.failure;
-            if (this.buf.length)
-                return { value: this.buf.shift(), done: false };
+            if (this.buf.length) {
+                const ev = this.buf.shift();
+                this.given = ev.cursor;
+                return { value: ev, done: false };
+            }
             if (this.closed)
                 return { value: undefined, done: true };
             if (this.dirty) {

package/dist/write.d.ts

@@ -10,8 +10,9 @@ export interface IncMarker {
     readonly start?: number;
 }
 /**
- * Приращение в update: `update({ balance: inc(-300) })` — величина прибавляется в базе, внутри
- * оператора, над свежей строкой (функция inc). Поля нет — ошибка; `{ start }` — начать с него.
+ * Приращение числового поля в `update()`: `db.Wallet(w).update({ balance: inc(-300) })`. Сложение делает база над
+ * текущим значением поля в момент записи, поэтому одновременные приращения не теряются. Если поля ещё нет, `{ start }`
+ * задаёт, с чего начать (поле получит `start + by`), а без него — ошибка `invalid_data`.
  */
 export declare function inc(by: number, opts?: {
     start?: number;