@verdeect/kit 0.0.0-stage → 1.0.0-rc.2

package/dist/messaging/tables.d.ts

@@ -0,0 +1,315 @@
+import { type PgSchema } from 'drizzle-orm/pg-core';
+/** Опции `createOutboxTable`. */
+export interface KitOutboxTableOptions {
+    /** `true` — колонка `tenant` допускает NULL (события `tenant: 'none'`, роль Identity). По умолчанию `false`. */
+    readonly tenantNullable?: boolean;
+}
+/**
+ * Таблица `<schema>.outbox` (§6): `id` (`evt_` + ULID), `seq` (identity, порядок публикации), `tenant`, `type`,
+ * `version`, `subject_id`, `actor`, `trace_id`, `data`, `occurred_at`, `published_at`, `attempts`, `last_error`;
+ * индексы неопубликованных по `seq` и опубликованных по `published_at`; политика `outbox_tenant_isolation` —
+ * исключение строгой модели (пустой тенант видит все строки для relay и очистки). Сервис добавляет миграцией
+ * `ALTER TABLE <schema>.outbox FORCE ROW LEVEL SECURITY` и `GRANT SELECT, INSERT, UPDATE, DELETE` роли `<svc>_app`.
+ * @throws {TypeError} имя схемы вне `^[a-z][a-z0-9-]{1,31}$`.
+ */
+export declare function createOutboxTable(schema: PgSchema, options?: KitOutboxTableOptions): import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "outbox";
+    schema: string;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "outbox";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        seq: import("drizzle-orm/pg-core").PgColumn<{
+            name: "seq";
+            tableName: "outbox";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: "always";
+            generated: undefined;
+        }, {}, {}>;
+        tenant: import("drizzle-orm/pg-core").PgColumn<{
+            name: string;
+            tableName: "outbox";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        type: import("drizzle-orm/pg-core").PgColumn<{
+            name: "type";
+            tableName: "outbox";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        version: import("drizzle-orm/pg-core").PgColumn<{
+            name: "version";
+            tableName: "outbox";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        subjectId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "subject_id";
+            tableName: "outbox";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        actor: import("drizzle-orm/pg-core").PgColumn<{
+            name: "actor";
+            tableName: "outbox";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Record<string, unknown>;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, unknown>;
+        }>;
+        traceId: import("drizzle-orm/pg-core").PgColumn<{
+            name: "trace_id";
+            tableName: "outbox";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        data: import("drizzle-orm/pg-core").PgColumn<{
+            name: "data";
+            tableName: "outbox";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Record<string, unknown>;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, unknown>;
+        }>;
+        occurredAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "occurred_at";
+            tableName: "outbox";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        publishedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "published_at";
+            tableName: "outbox";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        attempts: import("drizzle-orm/pg-core").PgColumn<{
+            name: "attempts";
+            tableName: "outbox";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        lastError: import("drizzle-orm/pg-core").PgColumn<{
+            name: "last_error";
+            tableName: "outbox";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+/**
+ * Таблица `<schema>.inbox` (§6): `id` (PK, id события), `type`, `received_at`; индекс по `received_at` для очистки.
+ * Без RLS (служебная). Сервис выдаёт миграцией `GRANT SELECT, INSERT, DELETE` роли `<svc>_app`.
+ * @throws {TypeError} имя схемы вне `^[a-z][a-z0-9-]{1,31}$`.
+ */
+export declare function createInboxTable(schema: PgSchema): import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "inbox";
+    schema: string;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "inbox";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        type: import("drizzle-orm/pg-core").PgColumn<{
+            name: "type";
+            tableName: "inbox";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        receivedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "received_at";
+            tableName: "inbox";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+/** Таблица outbox (`createOutboxTable`). */
+export type KitOutboxTable = ReturnType<typeof createOutboxTable>;
+/** Таблица inbox (`createInboxTable`). */
+export type KitInboxTable = ReturnType<typeof createInboxTable>;
+/** Колонка `tenant` таблицы outbox допускает NULL (`tenantNullable: true`). */
+export declare function outboxTenantNullable(table: KitOutboxTable): boolean;

package/dist/messaging/tables.js

@@ -0,0 +1,72 @@
+// createOutboxTable, createInboxTable (prd.md §3.4, §6, AC-5.15). Эталон — O outbox.schema.ts, inbox.schema.ts; из I —
+// nullable tenant (tenantNullable); по PRD §6 — subject_id вместо subject jsonb, id inbox — id события. Файл без pg и
+// без ./peer.js: схему сервиса грузит drizzle-kit через require; проверку peer делает index.ts.
+import { sql } from 'drizzle-orm';
+import { bigint, getTableConfig, index, integer, jsonb, pgPolicy, text, timestamp, } from 'drizzle-orm/pg-core';
+import { INBOX_TABLE, OUTBOX_POLICY, OUTBOX_POLICY_SQL, OUTBOX_TABLE, } from '../internal/outbox-policy.js';
+import { assertServiceName } from '../internal/service-name.js';
+/**
+ * Таблица `<schema>.outbox` (§6): `id` (`evt_` + ULID), `seq` (identity, порядок публикации), `tenant`, `type`,
+ * `version`, `subject_id`, `actor`, `trace_id`, `data`, `occurred_at`, `published_at`, `attempts`, `last_error`;
+ * индексы неопубликованных по `seq` и опубликованных по `published_at`; политика `outbox_tenant_isolation` —
+ * исключение строгой модели (пустой тенант видит все строки для relay и очистки). Сервис добавляет миграцией
+ * `ALTER TABLE <schema>.outbox FORCE ROW LEVEL SECURITY` и `GRANT SELECT, INSERT, UPDATE, DELETE` роли `<svc>_app`.
+ * @throws {TypeError} имя схемы вне `^[a-z][a-z0-9-]{1,31}$`.
+ */
+export function createOutboxTable(schema, options = {}) {
+    assertServiceName(schema.schemaName, 'createOutboxTable');
+    // Тип колонки один (string | null); NOT NULL — в конфигурации колонки, его читает outboxTenantNullable.
+    const tenant = options.tenantNullable === true
+        ? text('tenant')
+        : text('tenant').notNull();
+    return schema.table(OUTBOX_TABLE, {
+        id: text('id').primaryKey(),
+        seq: bigint('seq', { mode: 'number' }).generatedAlwaysAsIdentity(),
+        tenant,
+        type: text('type').notNull(),
+        version: integer('version').notNull(),
+        subjectId: text('subject_id').notNull(),
+        actor: jsonb('actor').$type().notNull(),
+        traceId: text('trace_id').notNull(),
+        data: jsonb('data').$type().notNull(),
+        occurredAt: timestamp('occurred_at', { withTimezone: true, mode: 'date' })
+            .notNull()
+            .defaultNow(),
+        publishedAt: timestamp('published_at', { withTimezone: true, mode: 'date' }),
+        attempts: integer('attempts').notNull().default(0),
+        lastError: text('last_error'),
+    }, (t) => [
+        index('outbox_unpublished_seq_idx')
+            .on(t.seq)
+            .where(sql `${t.publishedAt} is null`),
+        index('outbox_published_at_idx')
+            .on(t.publishedAt)
+            .where(sql `${t.publishedAt} is not null`),
+        pgPolicy(OUTBOX_POLICY, {
+            as: 'permissive',
+            for: 'all',
+            to: 'public',
+            using: sql.raw(OUTBOX_POLICY_SQL),
+            withCheck: sql.raw(OUTBOX_POLICY_SQL),
+        }),
+    ]);
+}
+/**
+ * Таблица `<schema>.inbox` (§6): `id` (PK, id события), `type`, `received_at`; индекс по `received_at` для очистки.
+ * Без RLS (служебная). Сервис выдаёт миграцией `GRANT SELECT, INSERT, DELETE` роли `<svc>_app`.
+ * @throws {TypeError} имя схемы вне `^[a-z][a-z0-9-]{1,31}$`.
+ */
+export function createInboxTable(schema) {
+    assertServiceName(schema.schemaName, 'createInboxTable');
+    return schema.table(INBOX_TABLE, {
+        id: text('id').primaryKey(),
+        type: text('type').notNull(),
+        receivedAt: timestamp('received_at', { withTimezone: true, mode: 'date' })
+            .notNull()
+            .defaultNow(),
+    }, (t) => [index('inbox_received_at_idx').on(t.receivedAt)]);
+}
+/** Колонка `tenant` таблицы outbox допускает NULL (`tenantNullable: true`). */
+export function outboxTenantNullable(table) {
+    return (getTableConfig(table).columns.find((column) => column.name === 'tenant')?.notNull !== true);
+}

package/dist/messaging/topology.d.ts

@@ -0,0 +1,56 @@
+export { EVENTS_EXCHANGE } from '../internal/rabbitmq-definitions.js';
+/** Заголовок причины у копии в DLQ (§3.4). */
+export declare const DLQ_REASON_HEADER = "x-dlq-reason";
+/** Неподтверждённых сообщений на потребителя (§3.4, AC-5.17). */
+export declare const CONSUMER_PREFETCH = 10;
+/** Повторов по `x-death`, затем DLQ (§3.4). */
+export declare const MAX_RETRIES = 5;
+/** Heartbeat, с; пауза переподключения — RABBITMQ_RETRY_SECONDS. */
+export declare const HEARTBEAT_SECONDS = 10;
+/** Ожидание ответа брокера на закрытие канала, мс. */
+export declare const CHANNEL_CLOSE_TIMEOUT_MS = 2000;
+/** Ожидание ответа брокера на закрытие соединения, мс. */
+export declare const CONNECTION_CLOSE_TIMEOUT_MS = 1000;
+/** Пачка relay (§3.4). */
+export declare const RELAY_BATCH_SIZE = 100;
+/** Общий срок подтверждений одной пачки, мс (§3.4). */
+export declare const RELAY_BATCH_DEADLINE_MS = 5000;
+/** Опрос outbox, мс (§3.4, AC-5.3). */
+export declare const RELAY_POLL_MS = 1000;
+/** Пауза строки после неудачи: 1 с → 5 мин, удвоение (§3.4, AC-5.16). */
+export declare const RELAY_BACKOFF_MIN_MS = 1000;
+/** Предел паузы строки, мс. */
+export declare const RELAY_BACKOFF_MAX_MS = 300000;
+/** Неудач строки до error-лога и GlitchTip (AC-5.16). */
+export declare const RELAY_ALERT_ATTEMPTS = 5;
+/** Таймаут подтверждения публикации, мс. */
+export declare const PUBLISH_CONFIRM_TIMEOUT_MS = 10000;
+/** Хранение опубликованного outbox и inbox, дни (§3.4, AC-5.12). */
+export declare const RETENTION_DAYS = 7;
+/** Интервал очистки, мс. */
+export declare const CLEANUP_INTERVAL_MS = 3600000;
+/** Пачка очистки. */
+export declare const CLEANUP_BATCH_SIZE = 1000;
+/** Пачек за проход. */
+export declare const CLEANUP_MAX_BATCHES = 100;
+/** Очереди сервиса. */
+export interface KitQueues {
+    /** Основная очередь. */
+    readonly main: string;
+    /** Очередь отложенного повтора (TTL → основная). */
+    readonly retry: string;
+    /** Неразбираемые и исчерпавшие повторы. */
+    readonly dlq: string;
+}
+/** Очереди экземпляра: `<svc>`, `<svc>.retry`, `<svc>.dlq`. */
+export declare function queuesOf(service: string): KitQueues;
+/** Очередь реплики `<svc>.replica.<REPLICA_ID>` (AC-5.9). */
+export declare function replicaQueueOf(service: string, replica: string): string;
+/**
+ * Общий срок обработчиков остановки (relay, подписчик), мс: остаток SHUTDOWN_TIMEOUT_MS после паузы SHUTDOWN_DRAIN_MS и
+ * закрытия канала и соединения, не меньше 1 с (П9).
+ */
+export declare function handlersDeadlineMs(env: {
+    readonly SHUTDOWN_TIMEOUT_MS: number;
+    readonly SHUTDOWN_DRAIN_MS: number;
+}): number;

package/dist/messaging/topology.js

@@ -0,0 +1,56 @@
+// Топология RabbitMQ и числа relay, подписчика и очистки (prd.md §3.4, AC-5.3, AC-5.7, AC-5.11, AC-5.12, AC-5.16, AC-5.17).
+// Эталон — O topology.ts; имена очередей — от имени экземпляра, заголовок x-dlq-reason (PRD) вместо x-<svc>-dlq-reason,
+// общий срок обработчиков остановки от SHUTDOWN_TIMEOUT_MS (П9) вместо константы O 8000.
+export { EVENTS_EXCHANGE } from '../internal/rabbitmq-definitions.js';
+/** Заголовок причины у копии в DLQ (§3.4). */
+export const DLQ_REASON_HEADER = 'x-dlq-reason';
+/** Неподтверждённых сообщений на потребителя (§3.4, AC-5.17). */
+export const CONSUMER_PREFETCH = 10;
+/** Повторов по `x-death`, затем DLQ (§3.4). */
+export const MAX_RETRIES = 5;
+/** Heartbeat, с; пауза переподключения — RABBITMQ_RETRY_SECONDS. */
+export const HEARTBEAT_SECONDS = 10;
+/** Ожидание ответа брокера на закрытие канала, мс. */
+export const CHANNEL_CLOSE_TIMEOUT_MS = 2_000;
+/** Ожидание ответа брокера на закрытие соединения, мс. */
+export const CONNECTION_CLOSE_TIMEOUT_MS = 1_000;
+/** Пачка relay (§3.4). */
+export const RELAY_BATCH_SIZE = 100;
+/** Общий срок подтверждений одной пачки, мс (§3.4). */
+export const RELAY_BATCH_DEADLINE_MS = 5_000;
+/** Опрос outbox, мс (§3.4, AC-5.3). */
+export const RELAY_POLL_MS = 1_000;
+/** Пауза строки после неудачи: 1 с → 5 мин, удвоение (§3.4, AC-5.16). */
+export const RELAY_BACKOFF_MIN_MS = 1_000;
+/** Предел паузы строки, мс. */
+export const RELAY_BACKOFF_MAX_MS = 300_000;
+/** Неудач строки до error-лога и GlitchTip (AC-5.16). */
+export const RELAY_ALERT_ATTEMPTS = 5;
+/** Таймаут подтверждения публикации, мс. */
+export const PUBLISH_CONFIRM_TIMEOUT_MS = 10_000;
+/** Хранение опубликованного outbox и inbox, дни (§3.4, AC-5.12). */
+export const RETENTION_DAYS = 7;
+/** Интервал очистки, мс. */
+export const CLEANUP_INTERVAL_MS = 3_600_000;
+/** Пачка очистки. */
+export const CLEANUP_BATCH_SIZE = 1_000;
+/** Пачек за проход. */
+export const CLEANUP_MAX_BATCHES = 100;
+/** Очереди экземпляра: `<svc>`, `<svc>.retry`, `<svc>.dlq`. */
+export function queuesOf(service) {
+    return { main: service, retry: `${service}.retry`, dlq: `${service}.dlq` };
+}
+/** Очередь реплики `<svc>.replica.<REPLICA_ID>` (AC-5.9). */
+export function replicaQueueOf(service, replica) {
+    return `${service}.replica.${replica}`;
+}
+/**
+ * Общий срок обработчиков остановки (relay, подписчик), мс: остаток SHUTDOWN_TIMEOUT_MS после паузы SHUTDOWN_DRAIN_MS и
+ * закрытия канала и соединения, не меньше 1 с (П9).
+ */
+export function handlersDeadlineMs(env) {
+    return Math.max(1_000, env.SHUTDOWN_TIMEOUT_MS -
+        env.SHUTDOWN_DRAIN_MS -
+        CHANNEL_CLOSE_TIMEOUT_MS -
+        CONNECTION_CLOSE_TIMEOUT_MS);
+}

package/dist/observability/fail-startup.d.ts

@@ -0,0 +1,14 @@
+import type { Logger } from 'pino';
+/** Ошибка запуска сервиса (§3.2): код и подробности без секретов попадают в fatal-лог и тег события. */
+export interface StartupFailure {
+    /** Код отказа (SCREAMING_SNAKE). */
+    readonly startupCode: string;
+    /** Подробности для лога — без значений окружения, секретов и ПДн. */
+    startupDetails(): Readonly<Record<string, unknown>>;
+}
+/**
+ * Отказ запуска (§3.2, UC-3): `fatal`-лог, событие GlitchTip с ожиданием отправки до 2 с, `exit(1)`.
+ * `InvalidEnvironmentError` — код и имена ключей; `StartupFailure` — `startupCode` и `startupDetails()`;
+ * прочее — через `sanitizeError`.
+ */
+export declare function failStartup(raw: unknown, logger: Logger): Promise<never>;

package/dist/observability/fail-startup.js

@@ -0,0 +1,51 @@
+// failStartup и StartupFailure (prd.md §3.2, AC-2.9, UC-3, NFR-4, NFR-9). Эталон — O fail-startup.ts: доменная ветка
+// ModelCatalogError заменена интерфейсом StartupFailure (распознаётся по форме), параметр exit не переносится.
+import * as Sentry from '@sentry/nestjs';
+import { InvalidEnvironmentError } from '../config/parse-env.js';
+import { sanitizeError } from './sanitize-error.js';
+import { captureError } from './sentry.js';
+/** Ожидание отправки события GlitchTip перед выходом (§3.2). */
+const SENTRY_FLUSH_MS = 2000;
+/** Код события прочих отказов запуска. */
+const STARTUP_FAILED = 'STARTUP_FAILED';
+function isStartupFailure(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        return false;
+    }
+    const { startupCode, startupDetails } = raw;
+    return typeof startupCode === 'string' && typeof startupDetails === 'function';
+}
+/** Подробности отказа; исключение в startupDetails() не отменяет fatal-лог, событие и exit(1). */
+function detailsOf(raw) {
+    try {
+        return raw.startupDetails();
+    }
+    catch {
+        return {};
+    }
+}
+/** Пишет fatal-лог отказа и возвращает код события. */
+function logFailure(raw, logger) {
+    if (raw instanceof InvalidEnvironmentError) {
+        // Только имена ключей: значения окружения не попадают никуда (NFR-4).
+        logger.fatal({ code: raw.code, keys: raw.keys }, 'Неверное окружение — запуск остановлен');
+        return raw.code;
+    }
+    if (isStartupFailure(raw)) {
+        logger.fatal({ ...detailsOf(raw), code: raw.startupCode }, 'Отказ запуска');
+        return raw.startupCode;
+    }
+    logger.fatal({ code: STARTUP_FAILED, err: sanitizeError(raw) }, 'Отказ запуска');
+    return STARTUP_FAILED;
+}
+/**
+ * Отказ запуска (§3.2, UC-3): `fatal`-лог, событие GlitchTip с ожиданием отправки до 2 с, `exit(1)`.
+ * `InvalidEnvironmentError` — код и имена ключей; `StartupFailure` — `startupCode` и `startupDetails()`;
+ * прочее — через `sanitizeError`.
+ */
+export async function failStartup(raw, logger) {
+    const code = logFailure(raw, logger);
+    captureError(raw, { tags: { code } });
+    await Sentry.flush(SENTRY_FLUSH_MS);
+    return process.exit(1);
+}

package/dist/observability/health-registry.d.ts

@@ -0,0 +1,34 @@
+import type { Logger } from 'pino';
+/** Проба зависимости: `true` — up. Исключение и ответ дольше 2 с — down. */
+export type HealthProbe = () => Promise<boolean>;
+/** Ответ `/health` (§3.2). */
+export interface HealthReport {
+    /** `ok` — всё up; `degraded` — down некритичная; `unavailable` — down критичная или идёт остановка. */
+    readonly status: 'ok' | 'degraded' | 'unavailable';
+    /** Состояние каждой пробы по имени. */
+    readonly checks: Readonly<Record<string, 'up' | 'down'>>;
+}
+/** Срок пробы (§3.2). */
+export declare const PROBE_TIMEOUT_MS = 2000;
+/** Реестр проб готовности; один на экземпляр приложения. */
+export declare class HealthRegistry {
+    private readonly logger;
+    private readonly probes;
+    private readonly lastState;
+    private stopping;
+    constructor(options: {
+        readonly logger: Logger;
+    });
+    /** Регистрирует пробу; повторная регистрация имени заменяет прежнюю. */
+    register(name: string, probe: HealthProbe, options: {
+        readonly critical: boolean;
+    }): void;
+    /** Шаг 1 остановки: с этого момента `evaluate` — `unavailable` без запуска проб. */
+    markStopping(): void;
+    /** Идёт ли остановка. */
+    get isStopping(): boolean;
+    /** Запускает пробы параллельно и сводит статус; при остановке — `unavailable` без проб. */
+    evaluate(): Promise<HealthReport>;
+    /** Лог только при смене состояния: up → down (и первый down) — warn, down → up — info. */
+    private trackState;
+}