letopis 1.4.2 → 3.0.0

package/dist/up.js

@@ -6,9 +6,9 @@
  * неё только на время явного `set role`. Повторный накат ничего не меняет.
  *
  * up() — оркестратор без Docker: ждёт базу (удалённую — до таймаута), создаёт её, проверяет версию
- * PostgreSQL (18+) и кодировку UTF8, ставит схему (fresh — заново), обновляет отставшую (upgrade:
+ * PostgreSQL (18+) и кодировку UTF8, ставит схему (fresh — заново), обновляет отставшую ревизию 2.x (upgrade:
  * миграции lib/sql/migrate/ и повторный накат), кладёт сиды, выдаёт или регистрирует сервисный ключ и
- * выполняет ANALYZE только для таблиц без статистики.
+ * выполняет ANALYZE только для таблиц без статистики. Схему letopis 1.x не трогает: 2.0 ставится только заново.
  */
 import { readFile, readdir } from 'node:fs/promises';
 import { createRequire } from 'node:module';
@@ -16,14 +16,31 @@ import { fileURLToPath } from 'node:url';
 import { join, resolve } from 'node:path';
 import { createHash, randomBytes } from 'node:crypto';
 import postgres from 'postgres';
-import { DDL_REVISION, RESERVED_CLASS_NAMES } from './types.js';
+import { DDL_REVISION, RESERVED_CLASS_NAMES, SCHEMA_VERSION } from './types.js';
+import { makeLog, maskDsn, traceSql, traced } from './log.js';
 import { startPglite } from './pglite.js';
 import { hashPassword } from './auth.js';
-import { LetopisError } from './errors.js';
+import { checkOptions, lerr, lmsg } from './errors.js';
+import { sqlCatalog } from './messages/index.js';
 import { v5Id } from './uuid.js';
 import { SIGNAL_MODES } from './signals.js';
 export const SYSTEM_ID = '2eba6d0a-1edd-4bb6-a85a-a703dab49035';
-export const SCHEMA_VERSION = 'v2';
+export { SCHEMA_VERSION };
+/**
+ * Первая ревизия движка 2.0 (план 2.0, редакция 2): схема ниже неё — letopis 1.x или схема без штампа ревизии. Её
+ * `up()` не обновляет, а `connect()` к ней не подключается: 2.0 ставится только заново (`up({ fresh: true })`), данные
+ * 1.x не переносятся. Накат миграций `up({ upgrade })` — в пределах 2.x, от этой ревизии до `DDL_REVISION`.
+ */
+export const FIRST_REVISION = 8;
+/**
+ * Отказ на схеме letopis 1.x (план 2.0, 7.10 №5): ревизия из комментария схемы ниже `FIRST_REVISION` — 7 и ниже у 1.x,
+ * 0 — штампа ревизии нет. `up()` зовёт её до любых изменений (до общей части `install()`), `connect()` — до входа по
+ * ключу: функции схемы 1.x не вызываются.
+ */
+export function refuse1x(schema, rev) {
+    if (rev < FIRST_REVISION)
+        throw lerr('boot.schema_1x', { schema, rev, first: FIRST_REVISION });
+}
 /**
  * Advisory-ключ наката одной схемы: пара int4, как у общей части установки (`hashtext('install')`), — имя схемы
  * всегда с точкой (`v2.имя`), поэтому со словом install ключи не совпадут.
@@ -44,8 +61,9 @@ export async function engineFiles(upTo = 99) {
 }
 let stamp;
 /**
- * Штамп движка этого пакета. Хэш — по исходному тексту файлов ядра до подстановок (переводы строк — LF): одна и та же
- * сборка даёт один штамп при любых опциях установки, а версия пакета без правок SQL штамп не меняет.
+ * Штамп движка этого пакета. Хэш — по исходному тексту файлов ядра до подстановок (переводы строк — LF) и по каталогу
+ * сообщений базы (разделы sql-*, подстановка @MESSAGES@): одна и та же сборка даёт один штамп при любых опциях
+ * установки, а версия пакета без правок SQL и этих разделов штамп не меняет.
  */
 export async function engineStamp() {
     if (stamp)
@@ -53,6 +71,7 @@ export async function engineStamp() {
     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`);
+    h.update(`@MESSAGES@\n${JSON.stringify(sqlCatalog())}\n`);
     const version = createRequire(import.meta.url)('../package.json').version;
     return (stamp = { version, sql: h.digest('hex').slice(0, 16) });
 }
@@ -95,16 +114,16 @@ export async function stampDrift(schema, comment) {
     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}' })`;
+    // схему обновила версия новее пакета — или в штампе нет версии (его правили руками: штамп ревизии 2.x up() пишет
+    // всегда с версией), другая сборка той же версии, другая версия
+    const key = was && compareVersions(was, code.version) > 0 ? 'boot.stamp_newer'
+        : !was ? 'boot.stamp_unknown' : was === code.version ? 'boot.stamp_other_build' : 'boot.stamp_other_version';
+    return 'letopis: ' + lmsg(key, { schema, version: code.version, ...(was ? { was } : {}) });
 }
 export function substitute(text, vars) {
     return text.replace(/@([A-Z_]+)@/g, (m, k) => {
         if (!(k in vars))
-            throw new Error(`letopis.up: неизвестный маркер ${m} в SQL`);
+            throw lerr('boot.unknown_marker', { marker: m });
         return vars[k];
     });
 }
@@ -112,16 +131,16 @@ export async function install(sql, opts) {
     const owner = opts.owner ?? 'letopis_owner';
     const app = opts.app ?? 'letopis_app';
     if (!SCHEMA_NAME.test(opts.schema))
-        throw new Error(`letopis.up: bad schema name "${opts.schema}" (нужно v<N>.<имя>)`);
+        throw lerr('boot.install_schema_name', { schema: opts.schema });
     for (const r of [owner, app])
         if (!ROLE_NAME.test(r))
-            throw new Error(`letopis.up: bad role name "${r}"`);
+            throw lerr('boot.role_name', { role: r });
     if (opts.signals !== undefined && !SIGNAL_MODES.includes(opts.signals)) {
-        throw new Error(`letopis.up: signals — ${SIGNAL_MODES.join(', ')}, а не ${String(opts.signals)}`);
+        throw lerr('boot.signals_mode', { modes: SIGNAL_MODES.join(', '), signals: String(opts.signals) });
     }
     const [{ v }] = await sql `select current_setting('server_version_num') as v`;
     if (Number(v) < 180000)
-        throw new Error(`letopis.up: нужен PostgreSQL 18 или новее, а сервер — ${v}`);
+        throw new Error(`letopis.up: ${lmsg('boot.install_pg_version', { version: v })}`);
     // Общая часть установки — роли, членство установщика, pgcrypto и право владельца на схему pgcrypto — одна на все
     // установки базы, а роли — на весь кластер. Параллельные up() разных схем меняли её одновременно: grant на схему
     // pgcrypto переписывает её строку pg_namespace, даже если право уже есть, и второй такой grant падал «tuple
@@ -150,7 +169,7 @@ export async function install(sql, opts) {
             // роль владельца создал кто-то другой, а у установщика нет на неё ADMIN — понятная ошибка вместо сырой 42501
             // (план 2.0, 7.5 №3)
             if (e.code === '42501') {
-                throw Object.assign(new Error(`letopis.up: роль ${owner} уже есть, а у установщика нет на неё ADMIN OPTION — установку ведёт роль, создавшая ${owner}, или роль с этим правом (grant ${owner} to <установщик> with admin option)`), { cause: e });
+                throw lerr('boot.owner_no_admin', { owner }, { cause: e });
             }
             if (e.code !== '0LP01' && e.code !== '23505')
                 throw e; // уже выдано циклом — нет; 23505 — выдал up() другой базы
@@ -170,10 +189,11 @@ export async function install(sql, opts) {
         APP_NAME: app,
         PGCRYPTO: quoteIdent(nsp),
         SYSTEM: SYSTEM_ID,
-        ALLOW_RESET: opts.allowReset ? 'true' : 'false',
-        HISTORY_DEFAULT: quoteLiteral(JSON.stringify(opts.history ?? null)),
         // методы цепочки — в тексте функции reserved_names() (план, §2.14)
         RESERVED_NAMES: RESERVED_CLASS_NAMES.map(quoteLiteral).join(', '),
+        // каталог сообщений базы — разделы sql-* (план 2.0, этап 3, п. 3): ключ → имя ошибки и русский шаблон, JSON-литерал
+        // функции message_catalog() (15-errors.sql); обновляет его каждый up(), как прочие функции
+        MESSAGES: quoteLiteral(JSON.stringify(sqlCatalog())),
         // режим сигналов — после set role: сохранённый режим лежит в строке ключа secret владельца
         SIGNALS: 'class',
     };
@@ -194,8 +214,19 @@ export async function install(sql, opts) {
         // считаются миграции, — под блокировкой: up() видит ревизию до неё, и второй upgrade повторил бы миграции, уже
         // накатанные первым. Разные схемы друг друга не ждут: ключ — имя схемы.
         await lockSchema(tx, opts.schema);
-        if (opts.fresh)
+        if (opts.fresh) {
+            // схему удаляет её владелец или суперпользователь. Установщик без суперпользователя состоит в роли владельца без
+            // наследования прав (inherit false, set true): сам он получил бы «must be owner of schema» (42501), а от роли
+            // владельца — удаляет (ревью: fresh от такого установщика падал)
+            const [own] = await tx.unsafe(`select r.rolname as role, not pg_has_role(current_user, n.nspowner, 'USAGE')
+          and pg_has_role(current_user, n.nspowner, 'SET') as via
+        from pg_namespace n join pg_roles r on r.oid = n.nspowner where n.nspname = $1`, [opts.schema]);
+            if (own?.via)
+                await tx.unsafe(`set local role ${quoteIdent(own.role)}`);
             await tx.unsafe(`drop schema if exists ${quoteIdent(opts.schema)} cascade`);
+            if (own?.via)
+                await tx.unsafe('set local role none');
+        }
         found = await schemaRevision(tx, opts.schema);
         if (opts.migrateFrom !== undefined && found !== null) {
             migrations = await migrationFiles(opts.migrationsDir ?? MIGRATE_DIR, Math.max(opts.migrateFrom, found));
@@ -239,7 +270,7 @@ export async function install(sql, opts) {
             // имя сида пакета или путь к своему файлу
             const own = seed.endsWith('.sql') || /[\\/]/.test(seed);
             if (!own && !/^[a-z0-9-]+$/.test(seed))
-                throw new Error(`letopis.up: bad seed name "${seed}"`);
+                throw lerr('boot.seed_name', { seed });
             const f = own ? resolve(seed) : join(SQL_DIR, `seed.${seed}.sql`);
             try {
                 await tx.unsafe(substitute(await readFile(f, 'utf8'), vars));
@@ -250,19 +281,12 @@ export async function install(sql, opts) {
                 throw err;
             }
         }
-        if (opts.history && files.some((f) => f.startsWith('40-'))) {
-            // умолчание проверяется той же метасхемой, что политика класса (сроки по возрастанию, all ≥ суток)
-            await tx.unsafe(`select ${quoteIdent(opts.schema)}.class_prepare($1::jsonb, $2::uuid)`, [{ name: 'HistoryDefault', kind: 'hub', history: opts.history }, SYSTEM_ID]).catch((e) => {
-                e.message = `letopis.up: history: ${e.message}`;
-                throw e;
-            });
-        }
         if (files.some((f) => f.startsWith('95-'))) {
             const S = quoteIdent(opts.schema);
             if (opts.serviceKey) {
                 // свой ключ: регистрируется, если его ещё нет (ключ хранится как sha256)
                 if (!/^lts_[0-9a-f]{32,128}$/.test(opts.serviceKey))
-                    throw new Error('letopis.up: serviceKey — lts_ и не меньше 32 шестнадцатеричных знаков');
+                    throw lerr('boot.service_key_format');
                 const hash = createHash('sha256').update(opts.serviceKey, 'utf8').digest();
                 const [{ n }] = await tx.unsafe(`select count(*)::int as n from ${S}.secret where kind = 'APIKEY' and material = $1 and deleted_at is null`, [hash]);
                 if (n === 0) {
@@ -294,6 +318,12 @@ export async function migrationFiles(dir, from) {
         .filter((f) => Number(f.slice(0, 4)) > from && Number(f.slice(0, 4)) <= DDL_REVISION)
         .sort();
 }
+/** Все опции up(): неизвестная — invalid_data с похожими именами до подключения (checkOptions; план 2.0, 7.10 №4). */
+const UP_OPTIONS = {
+    dsn: true, sql: true, schema: true, fresh: true, upgrade: true, quiet: true, waitTimeoutMs: true, pglite: true, tenant: true,
+    login: true, owner: true, app: true, seeds: true, migrationsDir: true, serviceKey: true,
+    signals: true, log: true, logLevel: true, redact: true,
+};
 /** Проба сервера: ok | нет сервера | нет базы | запускается | роковая ошибка (неверный пароль). */
 export async function pgPing(dsn) {
     const sql = postgres(dsn, { max: 1, connect_timeout: 3, onnotice: () => { } });
@@ -330,7 +360,7 @@ export async function ensureDatabase(dsn, log = () => { }) {
             if (e.code !== '42P04')
                 throw e;
         });
-        log(`база ${name} создана`);
+        log(lmsg('boot.log_database_created', { name }));
         return true;
     }
     finally {
@@ -342,19 +372,18 @@ export async function ensureDatabase(dsn, log = () => { }) {
  * иначе отказ. Возвращает предупреждения: с чем установка работает, но рискует.
  */
 export function checkServer(versionNum, encoding) {
+    // обычный Error: подходящего кода нет
     if (versionNum < 180000)
-        throw new Error(`letopis.up: нужен PostgreSQL 18 или новее, а сервер — ${Math.floor(versionNum / 10000)} (${versionNum})`);
+        throw new Error(`letopis.up: ${lmsg('boot.pg_version', { major: Math.floor(versionNum / 10000), num: versionNum })}`);
     if (encoding.toUpperCase() !== 'UTF8')
-        throw new Error(`letopis.up: база в кодировке ${encoding}, нужна UTF8 (casefold и коллация pg_unicode_fast)`);
+        throw new Error(`letopis.up: ${lmsg('boot.encoding', { encoding })}`);
     const warnings = [];
     // план 1.1, этап 2: исправлено в 18.2
-    if (versionNum < 180002) {
-        warnings.push(`PostgreSQL ${Math.floor(versionNum / 10000)}.${versionNum % 10000}: до 18.2 сервер мог усечь CLOG, который ещё нужен `
-            + 'непрочитанным сигналам NOTIFY; обновите сервер до 18.2 или новее');
-    }
+    if (versionNum < 180002)
+        warnings.push(lmsg('boot.pg_clog', { version: `${Math.floor(versionNum / 10000)}.${versionNum % 10000}` }));
     return warnings;
 }
-/** Ревизия движка схемы по комментарию 'letopis ddl_revision=N'; схемы нет — null. */
+/** Ревизия движка схемы по комментарию 'letopis ddl_revision=N'; схемы нет — null, штампа ревизии нет — 0. */
 export async function schemaRevision(sql, 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)
@@ -364,16 +393,43 @@ export async function schemaRevision(sql, schema) {
 /**
  * Ставит или обновляет установку letopis в схеме. Если схема уже есть и её ревизия та же, что у пакета, `up()` выполняет
  * повторный накат: заново ставит функции, не трогая данные, — поэтому его можно вызывать при каждом запуске приложения.
- * Схему отставшей ревизии `up()` обновляет только с `upgrade: true`, а на схеме новее пакета отказывает.
+ * Схему отставшей ревизии 2.x `up()` обновляет только с `upgrade: true`, а на схеме новее пакета отказывает. Схему без
+ * штампа ревизии не трогает и отказывает (`invalid_data`): заново её ставит `up({ fresh: true })`.
  */
 export async function up(opts) {
-    const log = opts.quiet ? () => { } : (m) => console.log(`letopis.up: ${m}`);
+    checkOptions('up', opts, UP_OPTIONS);
+    // логирование 3.0: события up, migrate, up.step, tenant.create, warning, error, sql — в логгер opts.log (или LETOPIS_LOG)
+    const lg = makeLog({ log: opts.log, logLevel: opts.logLevel, redact: opts.redact });
+    return traced(lg, 'up', { op: 'up' }, () => upCore(opts, lg), (r) => ({
+        detail: {
+            // schema — фактическое имя (имя без точки получает префикс версии: 'salon' → 'v2.salon'); requested — как передано
+            schema: r.schema, ...(opts.schema !== r.schema ? { requested: opts.schema } : {}),
+            created: r.created, upgraded: r.upgraded, revision: r.revision, signals: r.signals,
+            ...(opts.dsn ? { dsn: maskDsn(opts.dsn) } : {}), ...(r.pglite ? { pglite: true } : {}), ...(opts.fresh ? { fresh: true } : {}),
+            analyzed: r.analyzed.length, warnings: r.warnings.length, ...(r.serviceKey ? { issuedKey: true } : {}),
+            ...(r.tenant ? { tenant: r.tenant.tenant } : {}), ...(r.login ? { login: r.login.user } : {}),
+        },
+    }));
+}
+/** up() после проверки опций; lg — логгер. */
+async function upCore(opts, lg) {
+    // сообщения шагов: при заданном логгере — событие up.step вместо console.log
+    const log = opts.quiet ? () => { } : lg.active ? (m) => lg.emit('up.step', { op: 'up', msg: m }) : (m) => console.log(`letopis.up: ${m}`);
+    /** Предупреждение: в логгер (warning), иначе console.warn без quiet. */
+    const warn = (w) => {
+        if (lg.active)
+            lg.warning(undefined, w);
+        else if (!opts.quiet)
+            console.warn(`letopis.up: ${w}`);
+    };
     const schema = opts.schema.includes('.') ? opts.schema : `${SCHEMA_VERSION}.${opts.schema}`;
     if (!SCHEMA_NAME.test(schema))
-        throw new Error(`letopis.up: bad schema name "${opts.schema}" (нужно <имя> или v<N>.<имя>)`);
-    // опции арендатора — до подключения и наката: с неверными up() ничего не начинает
+        throw lerr('boot.up_schema_name', { schema: opts.schema });
+    // опции арендатора и роли приложения — до подключения и наката: с неверными up() ничего не начинает
     if (opts.tenant)
         checkTenant(opts.tenant);
+    if (opts.login !== undefined)
+        checkLogin(opts.login);
     let sql = opts.sql;
     const own = !sql;
     const lite = opts.pglite ? await startPglite(opts.pglite === true ? {} : opts.pglite) : undefined;
@@ -381,7 +437,7 @@ export async function up(opts) {
         sql = postgres(lite.dsn, { max: 1, onnotice: () => { } });
     if (!sql) {
         if (!opts.dsn)
-            throw new Error('letopis.up: нужен dsn или sql');
+            throw lerr('boot.no_connection');
         const deadline = Date.now() + (opts.waitTimeoutMs ?? 60_000);
         for (;;) {
             const ping = await pgPing(opts.dsn);
@@ -393,44 +449,88 @@ export async function up(opts) {
                 await ensureDatabase(opts.dsn, log);
                 continue;
             }
-            if (Date.now() > deadline)
-                throw new Error(`letopis.up: база ${new URL(opts.dsn).host} не готова за ${Math.round((opts.waitTimeoutMs ?? 60_000) / 1000)} с`);
+            if (Date.now() > deadline) {
+                throw new Error(`letopis.up: ${lmsg('boot.wait_timeout', { host: new URL(opts.dsn).host, seconds: Math.round((opts.waitTimeoutMs ?? 60_000) / 1000) })}`);
+            }
             await new Promise((r) => setTimeout(r, 500));
         }
         sql = postgres(opts.dsn, { max: 1, onnotice: () => { } });
     }
+    // порог debug — событие sql на каждый запрос установки (тексты create/alter role — без пароля)
+    sql = traceSql(sql, lg);
     try {
         const [srv] = await sql `select current_setting('server_version_num')::int as v, pg_encoding_to_char(encoding) as enc
       from pg_database where datname = current_database()`;
         const warnings = checkServer(srv.v, srv.enc);
-        if (!opts.quiet)
-            for (const w of warnings)
-                console.warn(`letopis.up: ${w}`);
+        for (const w of warnings)
+            warn(w);
         // ревизия до блокировки схемы — для ранних отказов; что накатывать, 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} — обновите пакет`);
+            throw new Error(`letopis.up: ${lmsg('boot.schema_newer', { schema, rev: before, known: DDL_REVISION })}`);
         }
+        // схема letopis 1.x — отказ до любых изменений, с upgrade тоже: 2.0 ставится только заново (план 2.0, 7.10 №5)
+        if (before !== null)
+            refuse1x(schema, before);
+        // отставшая ревизия 2.x — только с upgrade (миграции lib/sql/migrate/)
         if (before !== null && before < DDL_REVISION && !opts.upgrade) {
-            throw new Error(`letopis.up: схема ${schema} ревизии ${before}, библиотека — ${DDL_REVISION}: обновите её up({ schema: '${schema}', upgrade: true })`);
+            throw new Error(`letopis.up: ${lmsg('boot.schema_older', { schema, rev: before, want: DDL_REVISION })}`);
         }
-        const { dsn: _d, sql: _s, schema: _sc, fresh: _f, upgrade: _u, quiet: _q, waitTimeoutMs: _w, pglite: _p, ...rest } = opts;
+        const { dsn: _d, sql: _s, schema: _sc, fresh: _f, upgrade: _u, quiet: _q, waitTimeoutMs: _w, pglite: _p, login: _l, log: _lg, logLevel: _ll, redact: _rd, ...rest } = opts;
+        const t0 = performance.now();
         const { found, ...res } = await install(sql, {
             ...rest, schema, ...(opts.fresh ? { fresh: true } : {}), ...(before !== null && before < DDL_REVISION ? { migrateFrom: before } : {}),
         });
+        if (found !== null && found < DDL_REVISION && lg.wants('migrate')) {
+            lg.emit('migrate', { op: 'up', ms: performance.now() - t0, rows: res.migrations.length, detail: { schema, from: found, to: DDL_REVISION, files: res.migrations } });
+        }
         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`;
-        const analyzed = fresh.map((r) => r.relname);
-        for (const t of analyzed)
-            await sql.unsafe(`analyze ${quoteIdent(schema)}.${quoteIdent(t)}`);
+            log(lmsg('boot.log_fresh', { schema }));
+        // ANALYZE — только там, где статистики ещё нет: на повторном накате это самая дорогая часть. От роли владельца, как у
+        // загрузчика: таблицы принадлежат ей, а установщик без суперпользователя наследования её прав не имеет — его ANALYZE
+        // PostgreSQL пропускал с WARNING (ревью). В analyzed — только таблицы, где статистика появилась; оставшиеся без
+        // неё — предупреждение
+        const missing = async () => (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`).map((r) => r.relname);
+        const todo = await missing();
+        if (todo.length) {
+            await sql.begin(async (tx) => {
+                await tx.unsafe(`set local role ${quoteIdent(res.owner)}`);
+                for (const t of todo)
+                    await tx.unsafe(`analyze ${quoteIdent(schema)}.${quoteIdent(t)}`);
+            });
+        }
+        const left = todo.length ? await missing() : [];
+        const analyzed = todo.filter((t) => !left.includes(t));
+        if (left.length) {
+            const w = lmsg('boot.analyze_skipped', { owner: res.owner, tables: left.map((t) => `${schema}.${t}`).join(', ') });
+            warnings.push(w);
+            warn(w);
+        }
+        // хабы с зарезервированными именами, заведённые мимо проверки базы (план 2.0, этап 4, п. 2; 7.10 №3): накат их
+        // оставляет и называет, новых таких база не пишет. Строки Class — от роли владельца, как ANALYZE: у установщика без
+        // суперпользователя прав на таблицы нет, а RLS владельца таблицы не касается
+        const reserved = await sql.begin(async (tx) => {
+            await tx.unsafe(`set local role ${quoteIdent(res.owner)}`);
+            return tx.unsafe(`select x.data->>'name' as name, x.tenant::text as tenant from ${quoteIdent(schema)}.entity x
+        where x.class = 'Class' and x.data->>'kind' = 'hub' and x.data->>'name' = any ($1::text[])
+        order by x.data->>'name', x.tenant`, [[...RESERVED_CLASS_NAMES]]);
+        });
+        if (reserved.length) {
+            const w = lmsg('boot.reserved_hubs', { hubs: reserved.map((h) => `${h.name} (${h.tenant})`).join(', ') });
+            warnings.push(w);
+            warn(w);
+        }
         const revision = (await schemaRevision(sql, schema)) ?? 0;
-        log(`${found === null ? 'схема поставлена' : found < DDL_REVISION ? `схема обновлена с ревизии ${found}` : 'повторный накат'}: ${schema}, ревизия ${revision}`);
-        const tenant = opts.tenant ? await createTenant(sql, schema, opts.tenant, opts.owner) : undefined;
+        log(lmsg(found === null ? 'boot.log_installed' : found < DDL_REVISION ? 'boot.log_upgraded' : 'boot.log_reapplied', { schema, revision, from: found }));
+        const tenant = opts.tenant
+            ? await traced(lg, 'tenant.create', { op: 'createTenant' }, () => createTenant(sql, schema, opts.tenant, opts.owner), (t) => ({ tenant: t.tenant, ...(t.user ? { account: t.user } : {}), detail: { name: opts.tenant.name, created: t.created, user: Boolean(t.user) } }))
+            : undefined;
+        const login = opts.login ? await ensureLogin(sql, opts.login, res.owner, res.app, opts.dsn ?? lite?.dsn) : undefined;
+        if (login)
+            log(lmsg(login.created ? 'boot.log_login_created' : 'boot.log_login_updated', { user: login.user }));
         return { ...res, created: found === null, upgraded: found !== null && found < DDL_REVISION, revision, analyzed, warnings,
-            ...(lite ? { pglite: lite } : {}), ...(tenant ? { tenant } : {}) };
+            ...(lite ? { pglite: lite } : {}), ...(tenant ? { tenant } : {}), ...(login ? { login } : {}) };
     }
     catch (e) {
         if (lite)
@@ -444,8 +544,49 @@ export async function up(opts) {
             await sql.end({ timeout: 5 }).catch(() => { });
     }
 }
+/** Проверка up({ login }) до подключения: имя роли и пароль. */
+function checkLogin(login) {
+    if (!login || typeof login !== 'object')
+        throw lerr('boot.login_not_object');
+    const { user, password } = login;
+    if (typeof user !== 'string' || !user.trim() || Buffer.byteLength(user, 'utf8') > 63 || user.startsWith('pg_') || user.includes('\0')) {
+        throw lerr('boot.login_user', { user: JSON.stringify(user) });
+    }
+    if (typeof password !== 'string' || !password || password.includes('\0'))
+        throw lerr('boot.login_password');
+}
+/**
+ * Роль приложения up({ login }) (план 2.0, 7.9 №4): заводится или получает новый пароль, затем членство в роли
+ * приложения. Роли — объекты кластера: под той же блокировкой, что общая часть install(). Текст create/alter/grant
+ * собирает база (`format` с `%I` и `%L`), поэтому кавычки в имени и пароле не ломают SQL.
+ */
+async function ensureLogin(sql, login, owner, app, dsn) {
+    const created = await sql.begin(async (tx) => {
+        await tx `select pg_advisory_xact_lock(hashtext('letopis'), hashtext('install'))`;
+        const [r] = await tx `select r.rolsuper or r.rolcreaterole or r.rolcreatedb or r.rolreplication or r.rolbypassrls
+        or pg_has_role(r.oid, ${owner}, 'USAGE') or pg_has_role(r.oid, ${owner}, 'SET') as privileged
+      from pg_roles r where r.rolname = ${login.user}`;
+        if (r?.privileged || login.user === owner || login.user === app) {
+            throw lerr('boot.login_privileged', { user: login.user });
+        }
+        const verb = r ? 'alter role %I login password %L' : 'create role %I login password %L';
+        const [{ q }] = await tx `select format(${verb}::text, ${login.user}::text, ${login.password}::text) as q`;
+        await tx.unsafe(q);
+        const [{ g }] = await tx `select format('grant %I to %I', ${app}::text, ${login.user}::text) as g`;
+        await tx.unsafe(g);
+        return !r;
+    });
+    let url;
+    if (dsn) {
+        const u = new URL(dsn);
+        u.username = login.user;
+        u.password = login.password;
+        url = u.toString();
+    }
+    return { user: login.user, created, ...(url ? { dsn: url } : {}) };
+}
 /** Служебные виды строк secret: их не принимают функции кредов (auth_kind_ok в 80-auth.sql) и createTenant. */
-const SERVICE_KINDS = ['SESSION', 'APIKEY', 'KEYSECRET', 'OTP', 'TOTP', 'KEY', 'PROJECTOR', 'LOCK'];
+const SERVICE_KINDS = ['SESSION', 'APIKEY', 'KEYSECRET', 'OTP', 'TOTP', 'KEY', 'LOCK'];
 /**
  * Опции арендатора до записи; возвращает роли членства пользователя (по умолчанию owner). Вид пароля user.kind — как у
  * функций кредов (auth_kind_ok). Членство
@@ -456,28 +597,26 @@ const SERVICE_KINDS = ['SESSION', 'APIKEY', 'KEYSECRET', 'OTP', 'TOTP', 'KEY', '
  */
 function checkTenant(opts) {
     if (!opts.name)
-        throw new Error('letopis.createTenant: имя арендатора обязательно');
+        throw lerr('boot.tenant_name_required');
     // вид пароля — по правилу функций кредов (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)`);
+        throw lerr('boot.tenant_kind', { kind: JSON.stringify(kind), kinds: SERVICE_KINDS.join(', ') });
     }
     if (opts.user?.roles === undefined)
         return ['owner'];
     const roles = opts.user.roles;
-    const bad = (why) => new LetopisError('invalid_data', `createTenant: user.roles — ${why}`);
     if (!Array.isArray(roles) || roles.length === 0)
-        throw bad("непустой список ролей, например ['staff']");
+        throw lerr('boot.tenant_roles_empty');
     for (const r of roles) {
         if (typeof r !== 'string')
-            throw bad(`роль — строка, а не ${r === null ? 'null' : typeof r}`);
-        if (!r || r !== r.trim() || /[,{}]/.test(r) || r.startsWith('!')) {
-            throw bad(`роль ${JSON.stringify(r)}: нужно имя роли, а не маска группы — не пустое, без пробелов по краям, запятых, фигурных скобок и «!» в начале`);
-        }
+            throw lerr('boot.tenant_role_type', { type: r === null ? 'null' : typeof r });
+        if (!r || r !== r.trim() || /[,{}]/.test(r) || r.startsWith('!'))
+            throw lerr('boot.tenant_role_mask', { role: JSON.stringify(r) });
     }
     if (new Set(roles).size !== roles.length)
-        throw bad('роли повторяются');
+        throw lerr('boot.tenant_roles_repeat');
     return roles;
 }
 /**
@@ -487,28 +626,37 @@ function checkTenant(opts) {
  * пользователь или членство были удалены, повтор их не воскрешает — отказ `invalid_data`.
  */
 export async function createTenant(sql, schema, opts, owner = 'letopis_owner') {
+    // admin — пул postgres(): строка DSN, подключение connect() letopis или другой объект упали бы голым TypeError на
+    // sql.begin (3.0)
+    const pool = sql;
+    if (typeof pool !== 'function' || typeof pool.begin !== 'function' || typeof pool.unsafe !== 'function') {
+        throw lerr('api.create_tenant_admin', { type: pool === null ? 'null' : typeof pool });
+    }
+    // имя схемы — как у connect() и up(): без точки — с префиксом версии (v2.salon)
+    if (typeof schema === 'string' && !schema.includes('.'))
+        schema = `${SCHEMA_VERSION}.${schema}`;
     const roles = checkTenant(opts);
     const S = quoteIdent(schema);
     const tenant = v5Id(SYSTEM_ID, 'Account', [`tenant:${opts.name}`]);
     const u = opts.user;
-    const user = u ? v5Id(SYSTEM_ID, 'Account', [`user:${u.login}`]) : null;
+    // логин без крайних пробелов, как у auth.setPassword() и verifyPassword() (план 2.1, A12)
+    const login = u ? (typeof u.login === 'string' ? u.login.trim() : u.login) : '';
+    const user = u ? v5Id(SYSTEM_ID, 'Account', [`user:${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) => {
+        /** Строка есть — true, не было — false; строки нет, а журнал id есть, — удалена: отказ по ключу gone (что и как вернуть). */
+        const exists = async (id, cls, gone, params) => {
             const [r] = await tx.unsafe(`select exists (select 1 from ${S}.entity where id = $1::uuid) as live,
           exists (select 1 from ${S}.log where id = $1::uuid) as was`, [id]);
             if (!r.live && r.was)
-                throw new LetopisError('invalid_data', `createTenant: ${gone}`, { id, class: cls });
+                throw lerr(gone, { ...params, id }, { detail: { id, class: cls } });
             return r.live;
         };
-        const why = 'а его история осталась в журнале — повтор удалённое не воскрешает';
-        const created = !(await exists(tenant, 'Account', `арендатор «${opts.name}» (${tenant}) удалён, ${why}: `
-            + 'верните его db.Account(id).restore() от имени системного администратора или выберите другое имя'));
+        const created = !(await exists(tenant, 'Account', 'boot.tenant_deleted', { name: opts.name }));
         if (created) {
             await tx.unsafe(`select ${S}.sys_create($1::uuid, 'Account', $2::uuid, '{}', $3::jsonb)`, [tenant, SYSTEM_ID, { name: opts.name, categories: [], enabled: true }]);
             if (opts.grantAll !== false)
@@ -516,20 +664,18 @@ export async function createTenant(sql, schema, opts, owner = 'letopis_owner') {
         }
         let token = null;
         if (u && user) {
-            if (!(await exists(user, 'Account', `аккаунт пользователя ${u.login} (${user}) удалён, ${why}: `
-                + 'верните его db.Account(id).restore() от имени системного администратора или выберите другой логин'))) {
+            if (!(await exists(user, 'Account', 'boot.tenant_user_deleted', { login }))) {
                 await tx.unsafe(`select ${S}.sys_create($1::uuid, 'Account', $2::uuid, '{}', $3::jsonb)`, [user, SYSTEM_ID, { name: u.name, categories: ['User'], enabled: true }]);
             }
             const member = (await tx.unsafe(`select ${S}.v5_id($1::uuid, 'member', array[$2::text, $1::text]) as id`, [tenant, user]))[0].id;
             // существующее членство не трогаем: повтор с другими ролями их не меняет (их правят правкой member)
-            if (!(await exists(member, 'member', `членство ${u.login} в арендаторе «${opts.name}» (${member}) удалено, ${why}: `
-                + 'верните его db.member(id).restore() в этом арендаторе или выберите другой логин'))) {
+            if (!(await exists(member, 'member', 'boot.tenant_member_deleted', { login, name: opts.name }))) {
                 await tx.unsafe(`select ${S}.sys_create($1::uuid, 'member', $2::uuid, $3::jsonb, $4::jsonb)`, [member, tenant, { User: user, Tenant: tenant }, { roles }]);
             }
             const kind = u.kind ?? 'PASSWORD';
             await tx.unsafe(`insert into ${S}.secret (account, kind, ident, material, meta)
         select $1::uuid, $2, $3, convert_to($4, 'UTF8'), '{"confirmed": true}'::jsonb
-        where not exists (select 1 from ${S}.secret where kind = $2 and casefold(ident) collate pg_unicode_fast = casefold($3) collate pg_unicode_fast and deleted_at is null)`, [user, kind, u.login, hash]);
+        where not exists (select 1 from ${S}.secret where kind = $2 and casefold(ident) collate pg_unicode_fast = casefold($3) collate pg_unicode_fast and deleted_at is null)`, [user, kind, login, hash]);
             token = (await tx.unsafe(`select ${S}.new_session($1::uuid, $2::interval, $3::jsonb) as t`, [user, u.ttl ?? '7 days', { tenant }]))[0].t;
         }
         return { tenant, user, token, created };

package/dist/uuid.d.ts

@@ -1,3 +1,11 @@
+/** uuid в каноническом виде 8-4-4-4-12 (регистр любой) — общий для построителя, загрузчика и MCP. */
+export declare const UUID_RE: RegExp;
+/**
+ * Любой вид uuid, который принимает приведение PostgreSQL `::uuid`: 32 шестнадцатеричные цифры, дефис — после любой
+ * группы из четырёх (или без дефисов), весь в фигурных скобках или без них. Фильтр с таким id работал и до проверки,
+ * поэтому проверка до запроса (sql.ts, compileFilter) отказывает только тому, что отклонила бы база.
+ */
+export declare const PG_UUID_RE: RegExp;
 /** RFC 4122 v5: sha1(пространство + имя); одно имя в одном пространстве — один id. */
 export declare function uuidv5(name: string, ns: string): string;
 /** Имя v5: JSON-массив из имени класса и значений ключа — как `jsonb_build_array(…)::text` в базе. */