letopis 1.4.0 → 1.4.1

package/dist/up.js

@@ -24,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}$/;
@@ -92,7 +99,7 @@ export async function stampDrift(schema, comment) {
         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}' })`;
+    return `letopis: функции схемы ${schema} поставила ${by}, библиотека — ${code.version}: обновите схему — вызовите up({ schema: '${schema}' })`;
 }
 export function substitute(text, vars) {
     return text.replace(/@([A-Z_]+)@/g, (m, k) => {
@@ -115,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,
@@ -152,13 +176,27 @@ export async function install(sql, opts) {
     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);
-    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;
@@ -236,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) {
@@ -313,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}`);
@@ -362,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} — обновите пакет`);
         }
@@ -374,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`;
@@ -382,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) {
@@ -399,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}': не пустое, без пробелов по
  * краям (маска их отрезает) и запятых (разделитель маски), без фигурных скобок и «!» в начале
@@ -409,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;
@@ -427,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);
@@ -444,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;

package/dist/write.js

@@ -29,8 +29,9 @@ import { applyDefaults } from './validate.js';
 /** Метка приращения; Symbol.for — маркер узнаёт и вторая копия пакета в процессе. */
 export const INC = Symbol.for('letopis.inc');
 /**
- * Приращение в update: `update({ balance: inc(-300) })` — величина прибавляется в базе, внутри
- * оператора, над свежей строкой (функция inc). Поля нет — ошибка; `{ start }` — начать с него.
+ * Приращение числового поля в `update()`: `db.Wallet(w).update({ balance: inc(-300) })`. Сложение делает база над
+ * текущим значением поля в момент записи, поэтому одновременные приращения не теряются. Если поля ещё нет, `{ start }`
+ * задаёт, с чего начать (поле получит `start + by`), а без него — ошибка `invalid_data`.
  */
 export function inc(by, opts = {}) {
     return Object.freeze({ [INC]: true, by, ...(opts.start !== undefined ? { start: opts.start } : {}) });
@@ -377,7 +378,11 @@ function applySlotsLocal(links, ops) {
     }
     return out;
 }
-const tagsValue = (s) => s.tagsFilter === undefined ? null : typeof s.tagsFilter === 'string' ? [s.tagsFilter] : s.tagsFilter;
+/**
+ * Теги, которые пишет глагол: строка или список из `.tags(…)` (перед update они же и отбирают цели). Оператор
+ * (has, hasAny, hasAll) только отбирает — теги целей не меняются; create и upsert его не принимают (precheck).
+ */
+const tagsValue = (s) => typeof s.tagsFilter === 'string' ? [s.tagsFilter] : Array.isArray(s.tagsFilter) ? s.tagsFilter : null;
 /** «Уже существует»: id вычисляет библиотека (idOf), а не разбирает текст ошибки сервера (§2.5). */
 function existsError(w, cls, data, links, given, cause) {
     let id = given;
@@ -440,12 +445,23 @@ async function explainMissing(w, missing, rev) {
     }
     return fail('acl_denied', `строки видны, но изменить их нельзя: ${seen.map((r) => r.id).join(', ')}`, { ids: seen.map((r) => r.id) });
 }
+/**
+ * Строки ответа глагола — в порядке целей (`targetIds`: по `sort()` до глагола, иначе по id). `update … returning`
+ * отдаёт их в порядке обхода таблицы, и `first()` после глагола брал бы случайную из исправленных строк.
+ */
+function inTargetOrder(ids, rows) {
+    const pos = new Map(ids.map((id, i) => [id, i]));
+    return rows.sort((a, b) => (pos.get(a.id) ?? 0) - (pos.get(b.id) ?? 0));
+}
 /** Цели update/delete/anonymize/reclass: id из пути (limit и sort сужают); data.id — если у шага нет фильтра. */
 async function targetIds(w, steps, opStep, dataId) {
     const path = steps.map(bare);
     if (opStep.filter === undefined && dataId !== undefined)
         path[path.length - 1] = { ...path[path.length - 1], filter: dataId };
-    return readIds(w, path, opStep.opMods ?? {});
+    const ids = await readIds(w, path, opStep.opMods ?? {});
+    // без явного порядка — по id: глаголы по списку целей (reclass, rekey и др.) пишут журнал по очереди, и порядок
+    // записей не должен зависеть от плана чтения
+    return opStep.opMods?.order ? ids : [...ids].sort();
 }
 async function updateOp(w, steps, opStep) {
     const op = opStep.op;
@@ -456,7 +472,7 @@ async function updateOp(w, steps, opStep) {
     const ids = await targetIds(w, steps, opStep, useDataId ? dataId : undefined);
     if (op.rev !== undefined) {
         if (ids.length > 1)
-            fail('rev_ambiguous', `update(patch, { rev }): у шага ${opStep.name} ${ids.length} целей — строгий режим только для одной`);
+            fail('rev_ambiguous', `update(patch, { rev }): у шага ${opStep.name} ${ids.length} целей — проверить версию { rev } можно только у одной цели`);
         if (!ids.length)
             fail('target_not_found', `update(patch, { rev }): у шага ${opStep.name} нет цели`);
     }
@@ -481,7 +497,7 @@ async function updateOp(w, steps, opStep) {
         const got = new Set(res.map((r) => r.row.id));
         await explainMissing(w, ids.filter((x) => !got.has(x)), op.rev);
     }
-    return res.map((r) => toRow(r.row));
+    return inTargetOrder(ids, res.map((r) => toRow(r.row)));
 }
 async function deleteOp(w, steps, opStep) {
     const op = opStep.op;
@@ -510,9 +526,11 @@ async function deleteOp(w, steps, opStep) {
     }
     const tombs = await query(w, `select ${rowJson('l')} as row from ${S}.log l where l.tx = pg_current_xact_id() and l.seq > $1::bigint and l.op = 'delete' order by l.seq`, [mark]);
     const out = tombs.map((r) => toRow(r.row));
-    // строки классов без журнала (history: false) надгробий не оставляют — берём их из returning
+    // строки классов без журнала (history: false) надгробий не оставляют — берём их из returning, по id (порядок
+    // returning зависит от плана, а итог delete() — нет: надгробия идут по seq, триггер пишет их в порядке id)
     const have = new Set(out.map((r) => r.id));
-    for (const g of gone) {
+    const byId = (a, b) => String(a.row.id) < String(b.row.id) ? -1 : String(a.row.id) > String(b.row.id) ? 1 : 0;
+    for (const g of [...gone].sort(byId)) {
         if (have.has(g.row.id))
             continue;
         const row = toRow(g.row);
@@ -534,7 +552,7 @@ async function anonymizeOp(w, steps, opStep) {
         const got = new Set(res.map((r) => r.row.id));
         await explainMissing(w, ids.filter((x) => !got.has(x)));
     }
-    return res.map((r) => toRow(r.row));
+    return inTargetOrder(ids, res.map((r) => toRow(r.row)));
 }
 async function reclassOp(w, steps, opStep) {
     const op = opStep.op;
@@ -554,7 +572,8 @@ async function deletedTargets(w, steps, opStep, verb) {
     const dead = rows.filter((r) => r.$deleted);
     if (!dead.length && rows.length)
         fail('not_deleted', `объект не удалён: ${verb}() — только для удалённых${verb === 'purge' ? ', сначала delete()' : ''}`, { ids: rows.map((r) => r.id) });
-    return dead;
+    // без явного порядка — по id: restore и purge пишут журнал по очереди целей
+    return opStep.opMods?.order ? dead : [...dead].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 }
 /** Восстановление (этап 6, п. 2): последний снимок новой версией; база перепроверяет его по текущему описанию. */
 async function restoreOp(w, steps, opStep) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letopis",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "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",

package/sql/10-core.sql

@@ -107,9 +107,12 @@ create index if not exists log_ends on @SCHEMA@.log using gin (@SCHEMA@.link_ids
 -- журнал часто прореживается (§2.11): чаще чистим
 alter table @SCHEMA@.log set (autovacuum_vacuum_scale_factor = 0.02, autovacuum_analyze_scale_factor = 0.02);
 
+-- account — строка entity (аккаунт; у служебных строк KEY, LOCK, PROJECTOR — System): удалённый аккаунт уносит свои строки
+-- каскадом внешнего ключа — сессии, хэши паролей и ключей, секреты TOTP, внешние учётные записи (ревизия 7; в схему
+-- прежней ревизии ключ добавляет миграция 0007). Строка Account у System не удаляется (trg_entity_bd_account, 60-write.sql)
 create table if not exists @SCHEMA@.secret (
   id          uuid primary key default gen_random_uuid(),
-  account     uuid not null,
+  account     uuid not null constraint secret_account_fkey references @SCHEMA@.entity (id) on delete cascade,
   kind        text not null,       -- PASSWORD, APIKEY, KEYSECRET, OTP, TOTP, IDENTITY, SESSION
   ident       text,                -- email, телефон, префикс ключа, внешний id
   material    bytea,               -- хэш пароля, ключа, кода или токена; секрет TOTP
@@ -121,6 +124,8 @@ create table if not exists @SCHEMA@.secret (
 create unique index if not exists secret_kind_ident on @SCHEMA@.secret (kind, casefold(ident) collate pg_unicode_fast)
   where deleted_at is null and ident is not null;
 create index if not exists secret_material on @SCHEMA@.secret (material) where kind = 'SESSION' and deleted_at is null;
+-- строки аккаунта: каскад внешнего ключа при удалении аккаунта и гашение его сессий (auth_kill) — без перебора таблицы
+create index if not exists secret_account on @SCHEMA@.secret (account);
 
 alter table @SCHEMA@.entity owner to @OWNER@;
 alter table @SCHEMA@.log owner to @OWNER@;