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

package/dist/internal/rabbitmq-definitions.d.ts

@@ -0,0 +1,85 @@
+/** Exchange событий; объявляет его только definitions.json, сервис проверяет пассивно. */
+export declare const EVENTS_EXCHANGE = "verdeect.events";
+/** Права пользователя сервиса на vhost (регулярки RabbitMQ). */
+export interface RabbitPermissions {
+    /** Регулярка configure. */
+    readonly configure: string;
+    /** Регулярка write. */
+    readonly write: string;
+    /** Регулярка read. */
+    readonly read: string;
+}
+/** Права M3: свои очереди `<svc>`, `<svc>.retry`, `<svc>.dlq`, `<svc>.replica.<id>`; публикация в `verdeect.events`. */
+export declare function permissionsOf(service: string): RabbitPermissions;
+/** Хеш пароля `rabbit_password_hashing_sha256`: `base64(salt ‖ sha256(salt ‖ utf8(password)))`, соль 4 байта. */
+export declare function hashRabbitPassword(password: string, salt?: Buffer): string;
+/** Ключ окружения CLI с хешем пароля сервиса: `bff-app` → `RABBITMQ_PASSWORD_HASH_BFF_APP` (П3). */
+export declare function passwordHashKey(service: string): string;
+/** Пользователь брокера сервиса: имя по умолчанию — имя сервиса; права — на очереди `service`. */
+export interface KitBrokerUser {
+    /** Имя сервиса — права на его очереди. */
+    readonly service: string;
+    /** Имя пользователя; по умолчанию — имя сервиса. */
+    readonly user?: string;
+    /** Хеш `rabbit_password_hashing_sha256`. */
+    readonly passwordHash: string;
+}
+/** definitions.json формата импорта management plugin RabbitMQ 4.x. */
+export interface RabbitDefinitions {
+    /** Версия брокера формата. */
+    readonly rabbit_version: string;
+    /** vhost. */
+    readonly vhosts: readonly {
+        readonly name: string;
+    }[];
+    /** Пользователи. */
+    readonly users: readonly {
+        /** Имя. */
+        readonly name: string;
+        /** Хеш пароля. */
+        readonly password_hash: string;
+        /** Алгоритм хеша. */
+        readonly hashing_algorithm: string;
+        /** Теги. */
+        readonly tags: readonly string[];
+    }[];
+    /** Права. */
+    readonly permissions: readonly ({
+        /** Имя пользователя; по умолчанию — имя сервиса. */
+        readonly user: string;
+        /** vhost. */
+        readonly vhost: string;
+    } & RabbitPermissions)[];
+    /** Exchange. */
+    readonly exchanges: readonly {
+        /** Имя. */
+        readonly name: string;
+        /** vhost. */
+        readonly vhost: string;
+        /** Тип. */
+        readonly type: 'topic';
+        /** Переживает перезапуск. */
+        readonly durable: true;
+        /** Без автоудаления. */
+        readonly auto_delete: false;
+        /** Не внутренний. */
+        readonly internal: false;
+        /** Аргументы. */
+        readonly arguments: Readonly<Record<string, never>>;
+    }[];
+    /** Очередей нет — их объявляет подписчик. */
+    readonly queues: readonly never[];
+    /** Привязок нет. */
+    readonly bindings: readonly never[];
+}
+/**
+ * definitions.json: vhost, пользователи с хешами, права M3, exchange `verdeect.events` (topic, durable). Очередей нет:
+ * топологию объявляет подписчик (TTL `.retry` не фиксируется в файле развёртывания).
+ * @throws {TypeError} имя сервиса вне формата или дубликат.
+ */
+export declare function buildDefinitions(input: {
+    /** vhost. */
+    readonly vhost?: string;
+    /** Пользователи. */
+    readonly users: readonly KitBrokerUser[];
+}): RabbitDefinitions;

package/dist/internal/rabbitmq-definitions.js

@@ -0,0 +1,73 @@
+// definitions.json RabbitMQ (prd.md §3.4 M3, UC-12, AC-5.10): одна функция для CLI `rabbitmq definitions` и тестового
+// стека. Эталон прав — O docs/messaging.md (or-119), P docs/deployment.md (реплика); обобщение: configure
+// ^<svc>(\..*)?$, read — и своя DLQ (П13). Без внешних пакетов: только node:crypto.
+import { createHash, randomBytes } from 'node:crypto';
+import { assertServiceName } from './service-name.js';
+/** Exchange событий; объявляет его только definitions.json, сервис проверяет пассивно. */
+export const EVENTS_EXCHANGE = 'verdeect.events';
+/** Алгоритм хеша пароля пользователя в definitions. */
+const HASHING = 'rabbit_password_hashing_sha256';
+/** Права M3: свои очереди `<svc>`, `<svc>.retry`, `<svc>.dlq`, `<svc>.replica.<id>`; публикация в `verdeect.events`. */
+export function permissionsOf(service) {
+    const own = `${service.replaceAll('-', '\\-')}(\\..*)?`;
+    return {
+        configure: `^${own}$`,
+        write: `^(verdeect\\.events|amq\\.default|${own})$`,
+        read: `^(verdeect\\.events|${own})$`,
+    };
+}
+/** Хеш пароля `rabbit_password_hashing_sha256`: `base64(salt ‖ sha256(salt ‖ utf8(password)))`, соль 4 байта. */
+export function hashRabbitPassword(password, salt = randomBytes(4)) {
+    const digest = createHash('sha256')
+        .update(Buffer.concat([salt, Buffer.from(password, 'utf8')]))
+        .digest();
+    return Buffer.concat([salt, digest]).toString('base64');
+}
+/** Ключ окружения CLI с хешем пароля сервиса: `bff-app` → `RABBITMQ_PASSWORD_HASH_BFF_APP` (П3). */
+export function passwordHashKey(service) {
+    return `RABBITMQ_PASSWORD_HASH_${service.toUpperCase().replaceAll('-', '_')}`;
+}
+/**
+ * definitions.json: vhost, пользователи с хешами, права M3, exchange `verdeect.events` (topic, durable). Очередей нет:
+ * топологию объявляет подписчик (TTL `.retry` не фиксируется в файле развёртывания).
+ * @throws {TypeError} имя сервиса вне формата или дубликат.
+ */
+export function buildDefinitions(input) {
+    const vhost = input.vhost ?? '/';
+    const seen = new Set();
+    for (const { service } of input.users) {
+        assertServiceName(service, 'rabbitmq definitions');
+        if (seen.has(service)) {
+            throw new TypeError(`rabbitmq definitions: сервис ${service} указан дважды`);
+        }
+        seen.add(service);
+    }
+    return {
+        rabbit_version: '4.3.6',
+        vhosts: [{ name: vhost }],
+        users: input.users.map(({ service, user, passwordHash }) => ({
+            name: user ?? service,
+            password_hash: passwordHash,
+            hashing_algorithm: HASHING,
+            tags: [],
+        })),
+        permissions: input.users.map(({ service, user }) => ({
+            user: user ?? service,
+            vhost,
+            ...permissionsOf(service),
+        })),
+        exchanges: [
+            {
+                name: EVENTS_EXCHANGE,
+                vhost,
+                type: 'topic',
+                durable: true,
+                auto_delete: false,
+                internal: false,
+                arguments: {},
+            },
+        ],
+        queues: [],
+        bindings: [],
+    };
+}

package/dist/internal/redis-acl.d.ts

@@ -0,0 +1,21 @@
+/** Формат хеша пароля в aclfile: sha256, 64 hex в нижнем регистре. */
+export declare const REDIS_PASSWORD_HASH: RegExp;
+/** Пользователь сервиса в aclfile. */
+export interface RedisAclUser {
+    /** Имя сервиса = имя пользователя Redis. */
+    readonly service: string;
+    /** sha256 пароля, 64 hex. */
+    readonly passwordHash: string;
+}
+/** Ключ окружения с хешем пароля сервиса: `REDIS_PASSWORD_HASH_<SVC>` (заглавные, `-` → `_`). */
+export declare function redisPasswordHashKey(service: string): string;
+/** sha256 пароля в формате aclfile. */
+export declare function redisPasswordHash(password: string): string;
+/**
+ * aclfile: первая строка `user default off`, далее по строке на сервис
+ * `user <svc> on #<hash> ~<svc>:* &<svc>:* +@all -@dangerous`, затем `extra` (администратор теста); `\n` в конце.
+ */
+export declare function buildRedisAclFile(options: {
+    readonly users: readonly RedisAclUser[];
+    readonly extra?: readonly string[];
+}): string;

package/dist/internal/redis-acl.js

@@ -0,0 +1,30 @@
+// aclfile Redis (prd.md §3.7, UC-12): общий для CLI redis acl и startTestStack (как internal/rabbitmq-definitions). Пароли —
+// sha256 hex (#<hash>), default off. Права сервиса — свои ключи и каналы <svc>:*, все команды кроме @dangerous (D3 плана
+// E8). Без внешних пакетов: только node:crypto.
+import { createHash } from 'node:crypto';
+import { assertServiceName } from './service-name.js';
+/** Формат хеша пароля в aclfile: sha256, 64 hex в нижнем регистре. */
+export const REDIS_PASSWORD_HASH = /^[0-9a-f]{64}$/;
+/** Ключ окружения с хешем пароля сервиса: `REDIS_PASSWORD_HASH_<SVC>` (заглавные, `-` → `_`). */
+export function redisPasswordHashKey(service) {
+    return `REDIS_PASSWORD_HASH_${service.toUpperCase().replaceAll('-', '_')}`;
+}
+/** sha256 пароля в формате aclfile. */
+export function redisPasswordHash(password) {
+    return createHash('sha256').update(password, 'utf8').digest('hex');
+}
+/**
+ * aclfile: первая строка `user default off`, далее по строке на сервис
+ * `user <svc> on #<hash> ~<svc>:* &<svc>:* +@all -@dangerous`, затем `extra` (администратор теста); `\n` в конце.
+ */
+export function buildRedisAclFile(options) {
+    const lines = ['user default off'];
+    for (const { service, passwordHash } of options.users) {
+        assertServiceName(service, 'buildRedisAclFile');
+        if (!REDIS_PASSWORD_HASH.test(passwordHash)) {
+            throw new TypeError(`buildRedisAclFile: хеш пароля «${service}» — не 64 hex`);
+        }
+        lines.push(`user ${service} on #${passwordHash} ~${service}:* &${service}:* +@all -@dangerous`);
+    }
+    return `${[...lines, ...(options.extra ?? [])].join('\n')}\n`;
+}

package/dist/internal/service-name.d.ts

@@ -0,0 +1,4 @@
+/** Формат имени сервиса. */
+export declare const SERVICE_NAME_PATTERN: RegExp;
+/** Бросает TypeError, если имя вне формата; значение в сообщение попадает (это не секрет). */
+export declare function assertServiceName(service: string, where: string): void;

package/dist/internal/service-name.js

@@ -0,0 +1,10 @@
+// Имя сервиса = имя экземпляра (prd.md §3.4, §3.5, §3.6; CE-3). Одна проверка для startTestStack, bootstrapService,
+// createCipher и модулей.
+/** Формат имени сервиса. */
+export const SERVICE_NAME_PATTERN = /^[a-z][a-z0-9-]{1,31}$/;
+/** Бросает TypeError, если имя вне формата; значение в сообщение попадает (это не секрет). */
+export function assertServiceName(service, where) {
+    if (!SERVICE_NAME_PATTERN.test(service)) {
+        throw new TypeError(`${where}: имя сервиса «${service}» вне формата ^[a-z][a-z0-9-]{1,31}$`);
+    }
+}

package/dist/internal/sql-identifier.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Идентификатор SQL в двойных кавычках: `bff-app` → `"bff-app"`, внутренняя `"` удваивается.
+ * @throws {TypeError} пустое имя или символ NUL.
+ */
+export declare function quoteIdentifier(name: string): string;

package/dist/internal/sql-identifier.js

@@ -0,0 +1,12 @@
+// quoteIdentifier — экранирование идентификаторов PostgreSQL без pg (KT-20 п. 1; алгоритм escapeIdentifier pg:
+// двойные кавычки по краям, внутренняя `"` удваивается).
+/**
+ * Идентификатор SQL в двойных кавычках: `bff-app` → `"bff-app"`, внутренняя `"` удваивается.
+ * @throws {TypeError} пустое имя или символ NUL.
+ */
+export function quoteIdentifier(name) {
+    if (name === '' || name.includes('\0')) {
+        throw new TypeError('quoteIdentifier: пустое имя или символ NUL');
+    }
+    return `"${name.replaceAll('"', '""')}"`;
+}

package/dist/internal/tokens.d.ts

@@ -0,0 +1,10 @@
+/** Токен `KitMetrics` экземпляра приложения. */
+export declare const KIT_METRICS: unique symbol;
+/** Токен логгера pino экземпляра приложения. */
+export declare const KIT_LOGGER: unique symbol;
+/** @internal Префикс ключей и каналов Redis сервиса (`<svc>:`; в тестах — префикс воркера). Наружу не реэкспортируется. */
+export declare const KIT_REDIS_PREFIX: unique symbol;
+/** @internal Подписочное соединение Redis (`KitRedisModule.forRoot({subscriber: true})`). Наружу не реэкспортируется. */
+export declare const KIT_REDIS_SUBSCRIBER: unique symbol;
+/** @internal Логгер фоновых операций /redis (pino экземпляра или адаптер Nest). Наружу не реэкспортируется. */
+export declare const KIT_REDIS_LOG: unique symbol;

package/dist/internal/tokens.js

@@ -0,0 +1,12 @@
+// DI-токены ядра HTTP (prd.md §3.5; KT-11): метрики и логгер pino экземпляра приложения; внутренние токены /redis
+// (§3.7, E8). Классы KitLifecycle и HealthRegistry — сами себе токены. Внутренний модуль: из подпутей не реэкспортируется.
+/** Токен `KitMetrics` экземпляра приложения. */
+export const KIT_METRICS = Symbol('KIT_METRICS');
+/** Токен логгера pino экземпляра приложения. */
+export const KIT_LOGGER = Symbol('KIT_LOGGER');
+/** @internal Префикс ключей и каналов Redis сервиса (`<svc>:`; в тестах — префикс воркера). Наружу не реэкспортируется. */
+export const KIT_REDIS_PREFIX = Symbol('KIT_REDIS_PREFIX');
+/** @internal Подписочное соединение Redis (`KitRedisModule.forRoot({subscriber: true})`). Наружу не реэкспортируется. */
+export const KIT_REDIS_SUBSCRIBER = Symbol('KIT_REDIS_SUBSCRIBER');
+/** @internal Логгер фоновых операций /redis (pino экземпляра или адаптер Nest). Наружу не реэкспортируется. */
+export const KIT_REDIS_LOG = Symbol('KIT_REDIS_LOG');

package/dist/internal/tx-context.d.ts

@@ -0,0 +1,5 @@
+import type { DbContext } from '../database/tenant.js';
+/** Связывает транзакцию `Db.transaction`/`Db.read` с её контекстом; запись живёт, пока жив `tx`. */
+export declare function bindTxContext(tx: object, ctx: DbContext): void;
+/** Контекст транзакции `Db`; для `readGlobal` и чужого объекта — `undefined`. */
+export declare function txContextOf(tx: object): DbContext | undefined;

package/dist/internal/tx-context.js

@@ -0,0 +1,9 @@
+const contexts = new WeakMap();
+/** Связывает транзакцию `Db.transaction`/`Db.read` с её контекстом; запись живёт, пока жив `tx`. */
+export function bindTxContext(tx, ctx) {
+    contexts.set(tx, ctx);
+}
+/** Контекст транзакции `Db`; для `readGlobal` и чужого объекта — `undefined`. */
+export function txContextOf(tx) {
+    return contexts.get(tx);
+}

package/dist/messaging/cleanup.d.ts

@@ -0,0 +1,49 @@
+import type * as Database from '../database/index.js';
+import type { KitMetrics } from '../observability/metrics.js';
+import { type MessagingLog } from './rabbit-connection.js';
+import type { KitInboxTable, KitOutboxTable } from './tables.js';
+/** Пределы прохода. */
+interface CleanupLimits {
+    readonly batchSize: number;
+    readonly maxBatches: number;
+}
+/** Зависимости очистки (внутренние). */
+export interface MessagingCleanupDeps {
+    /** `Db` сервиса. */
+    readonly db: Database.Db;
+    /** Значения /database из динамического импорта `forRoot`. */
+    readonly database: Pick<typeof Database, 'runExclusive' | 'deleteInBatches'>;
+    /** Схема сервиса. */
+    readonly schema: string;
+    /** Заданные таблицы. */
+    readonly tables: {
+        readonly outbox?: KitOutboxTable;
+        readonly inbox?: KitInboxTable;
+    };
+    /** Метрики. */
+    readonly metrics?: KitMetrics;
+    /** Логгер. */
+    readonly log?: MessagingLog;
+}
+/** Очистка опубликованного outbox и inbox старше 7 дней одной репликой (внутренний класс модуля). */
+export declare class MessagingCleanup {
+    private readonly deps;
+    private readonly log;
+    private readonly tables;
+    private stopped;
+    private interval;
+    private current;
+    private running;
+    constructor(deps: MessagingCleanupDeps);
+    /** Первый проход сразу после старта, затем раз в час. */
+    onApplicationBootstrap(): void;
+    /** Текущий проход (включая ещё не начатый первый); нет — разрешённый промис. */
+    idle(): Promise<void>;
+    /** Проход очистки; идущий проход не накладывается. Ошибка не пробрасывается. */
+    run(limits?: CleanupLimits): Promise<void>;
+    /** Шаг 3 остановки: пачка дорабатывает, новая (и новая таблица) не начинается. */
+    beforeApplicationShutdown(): Promise<void>;
+    private pass;
+    private cleanTable;
+}
+export {};

package/dist/messaging/cleanup.js

@@ -0,0 +1,129 @@
+// Очистка outbox и inbox (prd.md §3.4, UC-9, AC-5.11, AC-5.12, AC-9.5). Эталон — O messaging-cleanup.job.ts (ошибка одной
+// таблицы не мешает другой); по PRD — runExclusive, пачки на соединении блокировки (E4 KT-22 п. 4), раз в час. Метрика —
+// verdeect_cleanup_runs_total{table: outbox|inbox} (общая, E4 П8), число строк — info-лог. Расписание и итог прохода —
+// по образцу IdempotencyCleanup. Прямой DELETE под ролью приложения с пустым тенантом: outbox — исключение политики,
+// inbox без RLS (П15). Значения /database (runExclusive, deleteInBatches) передаёт forRoot: messaging их не импортирует.
+import { sql } from 'drizzle-orm';
+import { getTableConfig } from 'drizzle-orm/pg-core';
+import { resultOf } from '../internal/cleanup-result.js';
+import { quoteIdentifier } from '../internal/sql-identifier.js';
+import { sanitizeError } from '../observability/sanitize-error.js';
+import { captureError } from '../observability/sentry.js';
+import { nestLog } from './rabbit-connection.js';
+import { CLEANUP_BATCH_SIZE, CLEANUP_INTERVAL_MS, CLEANUP_MAX_BATCHES, RETENTION_DAYS, } from './topology.js';
+/**
+ * Пачка удаления строк старше RETENTION_DAYS по колонке времени. `lock` — `FOR UPDATE SKIP LOCKED` (outbox: строки
+ * держит relay); inbox — без него: проход один (runExclusive), а `FOR UPDATE` потребовал бы права UPDATE у роли
+ * приложения (сервис выдаёт на inbox только SELECT, INSERT, DELETE).
+ */
+function batchSql(table, column, lock) {
+    const config = getTableConfig(table);
+    const name = sql.raw(`${quoteIdentifier(config.schema ?? '')}.${quoteIdentifier(config.name)}`);
+    const at = sql.raw(quoteIdentifier(column));
+    const locking = sql.raw(lock ? ' for update skip locked' : '');
+    return (batch) => sql `with d as (delete from ${name} where id in (
+            select id from ${name} where ${at} < now() - make_interval(days => ${RETENTION_DAYS})
+            order by ${at} limit ${batch}${locking}) returning 1)
+            select count(*)::int as deleted from d`;
+}
+/** Очистка опубликованного outbox и inbox старше 7 дней одной репликой (внутренний класс модуля). */
+export class MessagingCleanup {
+    deps;
+    log;
+    tables;
+    stopped = false;
+    interval;
+    current;
+    running = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.log = deps.log ?? nestLog('MessagingCleanup');
+        const { outbox, inbox } = deps.tables;
+        this.tables = [
+            ...(outbox === undefined
+                ? []
+                : [['outbox', batchSql(outbox, 'published_at', true)]]),
+            ...(inbox === undefined
+                ? []
+                : [['inbox', batchSql(inbox, 'received_at', false)]]),
+        ];
+    }
+    /** Первый проход сразу после старта, затем раз в час. */
+    onApplicationBootstrap() {
+        this.current = new Promise((resolve) => {
+            setTimeout(resolve, 0).unref();
+        }).then(() => this.run());
+        this.interval = setInterval(() => void this.run(), CLEANUP_INTERVAL_MS);
+        this.interval.unref();
+    }
+    /** Текущий проход (включая ещё не начатый первый); нет — разрешённый промис. */
+    idle() {
+        return this.current ?? Promise.resolve();
+    }
+    /** Проход очистки; идущий проход не накладывается. Ошибка не пробрасывается. */
+    run(limits = { batchSize: CLEANUP_BATCH_SIZE, maxBatches: CLEANUP_MAX_BATCHES }) {
+        if (this.stopped) {
+            return Promise.resolve();
+        }
+        if (this.running && this.current !== undefined) {
+            return this.current;
+        }
+        this.running = true;
+        const pass = this.pass(limits).finally(() => {
+            this.running = false;
+        });
+        this.current = pass;
+        return pass;
+    }
+    /** Шаг 3 остановки: пачка дорабатывает, новая (и новая таблица) не начинается. */
+    async beforeApplicationShutdown() {
+        this.stopped = true;
+        clearInterval(this.interval);
+        await this.current;
+    }
+    async pass(limits) {
+        const { db, database, schema } = this.deps;
+        const tables = this.tables.map(([name]) => name);
+        try {
+            const outcome = await database.runExclusive(db, `verdeect-kit:messaging-cleanup:${schema}`, async (connection) => {
+                for (const [name, sqlOf] of this.tables) {
+                    if (this.stopped) {
+                        break;
+                    }
+                    await this.cleanTable(name, sqlOf, limits, connection);
+                }
+            });
+            if (!outcome.ran) {
+                this.log.debug({ tables }, 'очистка сообщений: другая реплика');
+            }
+        }
+        catch (error) {
+            // Блокировку взять не удалось (БД недоступна): ошибка обеих таблиц.
+            for (const table of tables) {
+                this.deps.metrics?.cleanupRuns.inc({ table, result: 'error' });
+            }
+            this.log.error({ tables, err: sanitizeError(error) }, 'очистка сообщений: ошибка');
+            captureError(error);
+        }
+    }
+    async cleanTable(table, sqlOf, limits, connection) {
+        try {
+            // Пачки — на соединении блокировки: второе соединение пула не берётся (KT-22 п. 4).
+            const { deleted, batches, complete } = await this.deps.database.deleteInBatches({
+                db: this.deps.db,
+                sql: sqlOf,
+                ...limits,
+                shouldContinue: () => !this.stopped,
+                connection,
+            });
+            const result = resultOf(complete, batches, limits.maxBatches);
+            this.deps.metrics?.cleanupRuns.inc({ table, result });
+            this.log.info({ table, deleted, batches, result }, 'очистка сообщений: проход');
+        }
+        catch (error) {
+            this.deps.metrics?.cleanupRuns.inc({ table, result: 'error' });
+            this.log.error({ table, err: sanitizeError(error) }, 'очистка сообщений: ошибка');
+            captureError(error);
+        }
+    }
+}

package/dist/messaging/config.d.ts

@@ -0,0 +1,43 @@
+import type * as Database from '../database/index.js';
+import type { KitEvent } from './define-event.js';
+import type { KitInboxTable, KitOutboxTable } from './tables.js';
+/** Нормализованные опции модуля (внутренние). */
+export interface KitMessagingConfig {
+    /** Имя экземпляра. */
+    readonly service: string;
+    /** Схема таблиц outbox и inbox. */
+    readonly schema: string | undefined;
+    /** Защита от повторов подписчика. */
+    readonly dedupe: 'inbox' | 'none';
+    /** Подписчик задан. */
+    readonly subscriber: boolean;
+    /** События outbox по type. */
+    readonly events: ReadonlyMap<string, KitEvent>;
+    /** Таблица outbox. */
+    readonly outbox: KitOutboxTable | undefined;
+    /** Таблица inbox. */
+    readonly inbox: KitInboxTable | undefined;
+    /** Значения /database — только при outbox или inbox. */
+    readonly database: typeof Database | undefined;
+}
+/** Окружение модуля (внутреннее). */
+export interface KitMessagingRuntimeEnv {
+    /** Адрес брокера. */
+    readonly RABBITMQ_URL: string;
+    /** Пауза переподключения и TTL .retry, с. */
+    readonly RABBITMQ_RETRY_SECONDS: number;
+    /** Реплика. */
+    readonly REPLICA_ID: string;
+    /** Общий срок остановки, мс. */
+    readonly SHUTDOWN_TIMEOUT_MS: number;
+    /** Пауза перед остановкой, мс. */
+    readonly SHUTDOWN_DRAIN_MS: number;
+}
+/** Нормализованные опции (внутренний токен; тесты пакета). */
+export declare const KIT_MESSAGING_OPTIONS: unique symbol;
+/** Окружение модуля (внутренний токен). */
+export declare const KIT_MESSAGING_ENV: unique symbol;
+/** Соединение RabbitConnection (внутренний токен; тесты пакета). */
+export declare const KIT_RABBIT_CONNECTION: unique symbol;
+/** Логгер фоновых операций (внутренний токен). */
+export declare const KIT_MESSAGING_LOG: unique symbol;

package/dist/messaging/config.js

@@ -0,0 +1,8 @@
+/** Нормализованные опции (внутренний токен; тесты пакета). */
+export const KIT_MESSAGING_OPTIONS = Symbol('KIT_MESSAGING_OPTIONS');
+/** Окружение модуля (внутренний токен). */
+export const KIT_MESSAGING_ENV = Symbol('KIT_MESSAGING_ENV');
+/** Соединение RabbitConnection (внутренний токен; тесты пакета). */
+export const KIT_RABBIT_CONNECTION = Symbol('KIT_RABBIT_CONNECTION');
+/** Логгер фоновых операций (внутренний токен). */
+export const KIT_MESSAGING_LOG = Symbol('KIT_MESSAGING_LOG');

package/dist/messaging/define-event.d.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+/** Признак тенанта события: `'required'` — у события всегда есть компания, `'none'` — событие без компании. */
+export type KitEventTenant = 'required' | 'none';
+/** Событие каталога: тип, версия, вид субъекта, признак тенанта, схема `data` (zod без `.strict()`). */
+export interface KitEvent<TType extends string = string, TData extends z.ZodObject = z.ZodObject, TTenant extends KitEventTenant = KitEventTenant> {
+    /** Тип `<service>.<entity>.<action>`. */
+    readonly type: TType;
+    /** Версия схемы `data`, целое ≥ 1. */
+    readonly version: number;
+    /** Вид субъекта (`subject.kind` конверта), например `company`. */
+    readonly subject: string;
+    /** Признак тенанта. */
+    readonly tenant: TTenant;
+    /** Схема `data`. */
+    readonly data: TData;
+}
+/**
+ * Определение события. `tenant` по умолчанию `'required'`. `data` — `z.object` без `.strict()`: новые поля событий
+ * добавляются без мажора. Результат заморожен.
+ * @throws {TypeError} `type` вне формата каталога, `version` не целое ≥ 1, `subject` вне `^[a-z][a-z0-9_]*$`, `tenant`
+ * вне `required | none`, `data` strict.
+ */
+export declare function defineEvent<TType extends string, TData extends z.ZodObject, TTenant extends KitEventTenant = 'required'>(definition: {
+    readonly type: TType;
+    readonly version: number;
+    readonly subject: string;
+    readonly tenant?: TTenant;
+    readonly data: TData;
+}): KitEvent<TType, TData, TTenant>;

package/dist/messaging/define-event.js

@@ -0,0 +1,38 @@
+// defineEvent (prd.md §3.4, AC-5.15): определение события каталога 01 §7.2 с признаком tenant. Эталона в сервисах нет —
+// там схемы событий в @verdict/contracts без признака; формат type — каталог 01 §7.2.
+import { z } from 'zod';
+const TYPE = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9_-]*)+$/;
+const MAX_TYPE = 120;
+const SUBJECT = /^[a-z][a-z0-9_]*$/;
+/**
+ * Определение события. `tenant` по умолчанию `'required'`. `data` — `z.object` без `.strict()`: новые поля событий
+ * добавляются без мажора. Результат заморожен.
+ * @throws {TypeError} `type` вне формата каталога, `version` не целое ≥ 1, `subject` вне `^[a-z][a-z0-9_]*$`, `tenant`
+ * вне `required | none`, `data` strict.
+ */
+export function defineEvent(definition) {
+    const { type, version, subject, data } = definition;
+    const fail = (reason) => {
+        throw new TypeError(`defineEvent(${type}): ${reason}`);
+    };
+    if (!TYPE.test(type) || type.length > MAX_TYPE) {
+        fail('type вне формата <service>.<entity>.<action>');
+    }
+    if (!Number.isInteger(version) || version < 1) {
+        fail('version — целое ≥ 1');
+    }
+    if (!SUBJECT.test(subject)) {
+        fail('subject вне ^[a-z][a-z0-9_]*$');
+    }
+    const tenant = definition.tenant ?? 'required';
+    if (tenant !== 'required' && tenant !== 'none') {
+        fail("tenant — 'required' или 'none'");
+    }
+    if (!(data instanceof z.ZodObject)) {
+        fail('data — z.object');
+    }
+    if (data._zod.def.catchall instanceof z.ZodNever) {
+        fail('data без .strict(): новые поля событий добавляются без мажора');
+    }
+    return Object.freeze({ type, version, subject, tenant, data });
+}