letopis 0.20.0 → 0.20.1

package/dist/index.js

@@ -10,7 +10,7 @@
  *   await t.Мастер({ name: 'Вася' }).навык().Услуга().run()
  */
 // FILE: lib/src/index.ts
-// VERSION: 1.2.0
+// VERSION: 1.3.0
 // START_MODULE_CONTRACT
 //   PURPOSE: Публичная точка входа пакета — открыть соединение (реестр, опциональный ACL, сборка db) и ре-экспорт публичной поверхности; хелпер курсора.
 //   SCOPE: connect, cursorOf + barrel-реэкспорты
@@ -21,22 +21,24 @@
 // END_MODULE_CONTRACT
 //
 // START_MODULE_MAP
-//   connect - открывает pg-соединение, грузит реестр, опц. включает ACL, собирает EntityDb
+//   connect - открывает pg-соединение, грузит реестр, опц. включает ACL (снимок Resource/Rule на подключение), собирает EntityDb
 //   cursorOf - курсор keyset-пагинации из последней строки страницы
 //   NOTE (re-exports) - up/UpOpts←M-UP; uuidv5/uuidv7/LETOPIS_NS←M-UUID; ops←M-OPS; totpCode/AuthApi/AuthResult←M-AUTH; AclApi←M-ACL; ValidationError←M-WRITE; Registry←M-SCHEMA; Session-типы←M-SESSIONS; базовые типы←M-TYPES; типы chain/tables
 // END_MODULE_MAP
 //
 // START_CHANGE_SUMMARY
-//   LAST_CHANGE: [v1.2.0 - BREAKING: opts.account/opts.owner сняты — подключение безличное,
-//     арендатора и субъекта ACL называет db.as(account, { owner }). Компиляция энфорсера
-//     вынесена в ctx.compileAcl(ctx-scope), ctx.reload обновляет только реестр.
-//     Ранее: enforceAccount по умолчанию true; предупреждение при выключенном enforceAcl]
+//   LAST_CHANGE: [v1.3.0 - Словарь Resource/Rule снимается ОДИН раз на подключение и
+//     переиспользуется всеми db.as(): scope-per-request под enforceAcl платил два лишних
+//     SELECT на каждый HTTP-запрос. Per-scope остались чтение своего аккаунта и компиляция
+//     энфорсера (один энфорсер = один субъект). Снимок сбрасывает reloadSchema().
+//     Ранее: BREAKING — opts.account/opts.owner сняты, арендатора называет db.as()]
 // END_CHANGE_SUMMARY
 import postgres from 'postgres';
 import { loadRegistry } from './schema.js';
 import { makeDb } from './chain.js';
 import { makeTables } from './tables.js';
 import { compileEnforcer } from './acl.js';
+import { DDL_REVISION, parseDdlRevision } from './types.js';
 // START_CONTRACT: connect
 //   PURPOSE: Открыть БЕЗЛИЧНОЕ соединение: postgres-пул, реестр схемы, System-аккаунт, хук компиляции ACL — и собрать EntityDb (арендатора вызова называет db.as()).
 //   INPUTS: { opts: ConnectOpts { dsn, schema, partition?='entity', max?=10, enforceAcl?, enforceAccount?=true, onQuery?, slowMs? } }
@@ -46,6 +48,36 @@ import { compileEnforcer } from './acl.js';
 // END_CONTRACT: connect
 /** Предупреждение об отключённом enforceAcl печатается один раз на процесс. */
 let warnedNoAcl = false;
+/** Схемы, про чью ревизию движка уже предупредили (один раз на схему за процесс). */
+const warnedDdl = new Set();
+// START_CONTRACT: checkDdlRevision
+//   PURPOSE: Сверить ревизию движка схемы (COMMENT ON SCHEMA) с ожидаемой либой; при отставании предупредить с командой апгрейда.
+//   INPUTS: { sql: Ctx['sql'] - открытый пул; schema: string - полное имя PG-схемы }
+//   OUTPUTS: { Promise<void> }
+//   SIDE_EFFECTS: один SELECT из obj_description; console.warn один раз на схему за процесс (никогда не бросает: правки ddl аддитивны)
+//   LINKS: M-CONNECT, V-M-CONNECT, M-DDL, M-TYPES
+// END_CONTRACT: checkDdlRevision
+async function checkDdlRevision(sql, schema) {
+    // NB: ::regnamespace тут нельзя — имена схем letopis содержат точку ("v1.booking"),
+    // и приведение разберёт их как «схема v1, объект booking» → invalid name syntax.
+    const rows = (await sql `
+    SELECT obj_description(n.oid, 'pg_namespace') AS c FROM pg_namespace n WHERE n.nspname = ${schema}
+  `);
+    const have = parseDdlRevision(rows[0]?.c);
+    if (have === DDL_REVISION)
+        return;
+    if (warnedDdl.has(schema))
+        return;
+    warnedDdl.add(schema);
+    const чего = have === null
+        ? 'ревизия не помечена (схема накатана либой до появления метки)'
+        : `ревизия схемы ${have}, либа ожидает ${DDL_REVISION}`;
+    console.warn(`letopis: движок схемы "${schema}" отстал — ${чего}. Схема продолжит работать, но новых ` +
+        'функций/триггеров в ней нет (например purge/purge_account из 0.19.0) — вызов упадёт ' +
+        'ошибкой PostgreSQL "function … does not exist". ddl.sql идемпотентен, накат повторный ' +
+        'и данные целы: up({ …, upgrade: true }) либо node db/apply.mjs --dsn=… --schema=<имя> ' +
+        '--version=<N> --upgrade');
+}
 export async function connect(opts) {
     // timestamptz — строкой (JS Date режет микросекунды → ломал бы asOf/cursorOf по updated)
     const sql = postgres(opts.dsn, {
@@ -57,6 +89,13 @@ export async function connect(opts) {
     // Entity.account NOT NULL: fallback — System-аккаунт (семантика legacy-движка)
     const ident = `"${opts.schema.replace(/"/g, '""')}"`;
     const sys = (await sql.unsafe(`SELECT id FROM ${ident}."Account" WHERE 'System' = ANY(categories) LIMIT 1`));
+    // START_BLOCK_CHECK_DDL_REVISION
+    // Схема, накатанная более старой либой, не получает аддитивных правок ddl.sql (в 0.19.0
+    // так появились purge/purge_closure/purge_account). Без этой проверки приложение узнаёт
+    // о расхождении из сырого `PostgresError: function … does not exist`.
+    // Предупреждение, а не отказ: правки аддитивны — то, что уже работало, работает.
+    await checkDdlRevision(sql, opts.schema);
+    // END_BLOCK_CHECK_DDL_REVISION
     const ctx = {
         sql,
         registry,
@@ -75,20 +114,34 @@ export async function connect(opts) {
     // enforceAcl: правила и категории субъекта компилятся в резолвер ПОД КОНКРЕТНЫЙ scope.
     // Функция живёт на ctx, потому что зовут её двое: db.as() (новый субъект) и reload
     // (тот же субъект на свежем реестре). Субъект берётся из c.account, т.е. из scope.
+    //
+    // Словарь Resource/Rule ОДИН для всех субъектов — снимается один раз на подключение и
+    // переиспользуется каждым db.as(). Иначе scope-per-request (штатный режим в вебе) платил
+    // бы два лишних SELECT на КАЖДЫЙ HTTP-запрос. Per-scope остаётся только чтение своего
+    // аккаунта (категории субъекта) и сама компиляция: один энфорсер = один субъект, иначе
+    // memo в acl.ts (ключ «класс + операция», без аккаунта) отдал бы чужое решение.
+    // Снимок сбрасывает reloadSchema() — как и обещано в README §9.2/§11.10.
+    let aclDict = null;
+    const aclSource = (c) => {
+        aclDict ??= (async () => {
+            const tables = makeTables(c);
+            const [resources, rules] = await Promise.all([tables.resources.find(), tables.rules.find({ enabled: true })]);
+            return { resources, rules };
+        })().catch((e) => {
+            aclDict = null; // не кэшируем провал: следующий db.as() попробует снова
+            throw e;
+        });
+        return aclDict;
+    };
     ctx.compileAcl = async (c) => {
         if (!opts.enforceAcl)
             return;
         if (!c.account)
             throw new Error('letopis: enforceAcl is on — call db.as(account) to name the subject');
-        const tables = makeTables(c);
-        const [account, resources, rules] = await Promise.all([
-            tables.accounts.get(c.account),
-            tables.resources.find(),
-            tables.rules.find({ enabled: true }),
-        ]);
+        const [account, dict] = await Promise.all([makeTables(c).accounts.get(c.account), aclSource(c)]);
         if (!account)
             throw new Error(`letopis: enforceAcl — account "${c.account}" not found`);
-        c.aclDecide = compileEnforcer({ resources, rules }, account.id, account.categories, c.registry);
+        c.aclDecide = compileEnforcer(dict, account.id, account.categories, c.registry);
     };
     // enforceAcl остаётся OPT-IN: включить его по умолчанию нельзя (он работает
     // deny-by-default, т.е. без настроенных Resource/Rule выдача стала бы пустой).
@@ -100,9 +153,11 @@ export async function connect(opts) {
             'authorization unconditionally. For production use connect({ enforceAcl: true }) + db.as(account).');
     }
     // db.reloadSchema(): перечитать определения классов из таблицы Schema без реконнекта.
+    // Заодно сбрасывается снимок Resource/Rule: правки словаря ACL подхватываются здесь.
     // На корневом хендле обновляется только реестр (субъекта тут нет); scoped-хендлы
     // подхватывают его и перекомпилируют свой энфорсер сами (chain.ts, case 'as').
     ctx.reload = async () => {
+        aclDict = null;
         ctx.registry = await loadRegistry(sql, opts.schema, partition);
     };
     // END_BLOCK_ENFORCE_ACL

package/dist/types.d.ts

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

package/dist/types.js

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

package/dist/up.d.ts

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

package/dist/up.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letopis",
-  "version": "0.20.0",
+  "version": "0.20.1",
   "description": "Letopis (летопись): append-only versioned entity store on TimescaleDB with dot-notation chains — every change is a new row, history is first-class (asOf, versions, watch, cascade tombstones)",
   "keywords": [
     "timescaledb",

package/scripts/check-docs.mjs

@@ -260,8 +260,9 @@ async function checkReserved() {
   const счётчики = [
     ['lib/README.md', readme, new RegExp(`Всего ${n} им`)],
     ['AGENT-CHEATSHEET.md', await rd('AGENT-CHEATSHEET.md'), new RegExp(`\\*\\*Зарезервированные имена классов\\*\\*: ${n} им`)],
-    // только ТЕКУЩАЯ запись CHANGELOG: прошлые версии описывают своё время и неприкосновенны
-    ['lib/CHANGELOG.md', (await rd('lib/CHANGELOG.md')).split(/^## \[/m)[1] ?? '', new RegExp(`\\*\\*${n} им`)],
+    // CHANGELOG целиком: число называет та запись, которая его изменила, — следующие релизы
+    // его не повторяют. Меняется число — релиз обязан это записать, иначе проверка встанет.
+    ['lib/CHANGELOG.md', await rd('lib/CHANGELOG.md'), new RegExp(`\\*\\*${n} им`)],
   ];
   for (const [file, text, re] of счётчики) {
     if (!re.test(text)) fail('reserved', `${file} не называет актуальное число зарезервированных имён (${n})`);
@@ -317,6 +318,41 @@ async function checkDemos() {
 }
 
 // END_BLOCK_CHECK_DEMOS
+// START_BLOCK_CHECK_DDL_REVISION
+/**
+ * Класс дефекта: ревизия движка живёт в ДВУХ местах — маркер `-- DDL_REVISION:` в ddl.sql
+ * (штампуется в COMMENT ON SCHEMA последней строкой файла) и константа DDL_REVISION в
+ * types.ts (её сверяет connect()). Разъедутся — либа начнёт предупреждать про отставание
+ * на свежей схеме либо промолчит на отставшей. Плюс проверяем, что штамп в ddl.sql вообще
+ * есть и стоит ПОСЛЕДНИМ выражением: иначе метка появится при частично применённом файле.
+ */
+async function checkDdlRevision() {
+  const ddl = await rd('lib/sql/ddl.sql');
+  const types = await rd('lib/src/types.ts');
+
+  const marker = /^--\s*DDL_REVISION:\s*(\d+)/m.exec(ddl);
+  const konst = /export const DDL_REVISION = (\d+)/.exec(types);
+  const stamp = /COMMENT ON SCHEMA "<SCHEMA-NAME>" IS 'letopis ddl_revision=(\d+)';/.exec(ddl);
+
+  if (!marker) return fail('ddl-revision', 'в lib/sql/ddl.sql нет маркера "-- DDL_REVISION: N"');
+  if (!konst) return fail('ddl-revision', 'в lib/src/types.ts нет "export const DDL_REVISION = N"');
+  if (!stamp) return fail('ddl-revision', 'ddl.sql не штампует ревизию: нет COMMENT ON SCHEMA … ddl_revision=N');
+
+  const [m, k, s] = [marker[1], konst[1], stamp[1]];
+  if (!(m === k && k === s)) {
+    fail('ddl-revision', `ревизии разошлись: маркер ddl.sql ${m}, штамп COMMENT ${s}, DDL_REVISION в types.ts ${k}`);
+  }
+  // штамп обязан быть последним ВЫРАЖЕНИЕМ файла (комментарии после — можно)
+  const tail = ddl.slice(ddl.indexOf(stamp[0]) + stamp[0].length);
+  if (/^\s*[^-\s]/m.test(tail.replace(/^\s*--.*$/gm, ''))) {
+    fail('ddl-revision', 'после COMMENT ON SCHEMA в ddl.sql есть ещё выражения — метка встанет на неполном накате');
+  }
+  if (!problems.some((p) => p.startsWith('ddl-revision:'))) {
+    ok('ddl-revision', `ревизия движка ${k}: маркер ddl.sql ↔ штамп COMMENT ↔ DDL_REVISION в types.ts совпадают`);
+  }
+}
+
+// END_BLOCK_CHECK_DDL_REVISION
 // START_BLOCK_MAIN
 await checkVersion();
 await checkLinks();
@@ -325,6 +361,7 @@ await checkSeedCounts();
 await checkCodescribe();
 await checkApiContract();
 await checkReserved();
+await checkDdlRevision();
 await checkDemos();
 
 for (const p of passed) console.log(`  ok  ${p}`);

package/scripts/gen-api-contract.mjs

@@ -38,6 +38,9 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { join } from 'node:path';
 
+/** Детерминированный порядок: кодовые единицы UTF-16, одинаково на любой ОС и локали. */
+const byCode = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
 const LIB = fileURLToPath(new URL('..', import.meta.url));
 const args = Object.fromEntries(process.argv.slice(2).map((a) => a.replace(/^--/, '').split('=')));
 const out = args.out ?? join(LIB, '..', 'docs', 'api-contract.json');
@@ -127,7 +130,9 @@ function removedNames(chain) {
       message: `letopis: ${text}`,
     });
   }
-  return [...byMsg.values()].sort((a, b) => String(a.removed).localeCompare(String(b.removed)));
+  // ВАЖНО: сравнение по кодовым единицам, а не localeCompare — тот зависит от локали и версии
+  // ICU, поэтому Windows и linux-раннер давали РАЗНЫЙ порядок, и контракт числился устаревшим.
+  return [...byMsg.values()].sort((a, b) => byCode(String(a.removed), String(b.removed)));
 }
 
 // START_CONTRACT: errorCatalog
@@ -145,7 +150,7 @@ function errorCatalog(files) {
       if (!rows.some((r) => r.message === msg)) rows.push({ module: mod, message: msg });
     }
   }
-  return rows.sort((a, b) => a.message.localeCompare(b.message));
+  return rows.sort((a, b) => byCode(a.message, b.message));
 }
 
 // START_BLOCK_MAIN

package/sql/ddl.sql

@@ -7,7 +7,8 @@
 -- =============================================================================
 
 -- FILE: lib/sql/ddl.sql
--- VERSION: 1.0.0
+-- VERSION: 1.1.0
+-- DDL_REVISION: 1   (последняя строка файла штампует её в COMMENT ON SCHEMA; см. там же)
 -- START_MODULE_CONTRACT
 --   PURPOSE: Движок-хранилище PostgreSQL/TimescaleDB — таблицы, Entity-hypertable, индексы и триггеры целостности (валидация, версионирование, каскад-tombstone, lineage, notify).
 --   SCOPE: таблицы Schema/Entity/Account/Credential/Resource/Rule + триггеры schema_lineage/entity_check/entity_update/entity_delete/entity_notify.
@@ -570,6 +571,19 @@ CREATE TRIGGER entity_notify
     AFTER INSERT ON "<SCHEMA-NAME>"."Entity"
     FOR EACH ROW EXECUTE FUNCTION "<SCHEMA-NAME>".entity_notify();
 
+-- -----------------------------------------------------------------------------
+-- Метка ревизии движка — ПОСЛЕДНЕЙ строкой: комментарий появляется только если весь
+-- файл применился. Её читает connect() и предупреждает, если схема отстала от либы
+-- (DDL_REVISION в lib/src/types.ts; совпадение сверяет scripts/check-docs.mjs).
+--
+-- Ревизия — про АДДИТИВНЫЕ правки внутри одной версии движка (новые функции/триггеры/
+-- индексы): файл идемпотентен, поэтому такие правки доезжают повторным накатом
+-- (up({ upgrade: true }) / node db/apply.mjs --upgrade), данные при этом целы.
+-- Несовместимая правка СТРУКТУРЫ таблиц — это смена version в имени схемы (v1 → v2),
+-- а не ревизия.
+-- -----------------------------------------------------------------------------
+COMMENT ON SCHEMA "<SCHEMA-NAME>" IS 'letopis ddl_revision=1';
+
 -- -----------------------------------------------------------------------------
 -- Опционально (включать по мере роста данных):
 --