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

package/dist/database/migrations.js

@@ -0,0 +1,142 @@
+// runMigrations, moveJournal (prd.md §3.3, AC-4.7, AC-4.17). Эталон — O migrator.ts: пул max 1, срок соединения 5 с,
+// подсчёт применённых двумя запросами, транзакция миграций на выделенном клиенте. По PRD: журнал <schema>.__migrations,
+// папка и схема — от сервиса; схема drizzle не создаётся.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { assertServiceName } from '../internal/service-name.js';
+import { quoteIdentifier } from '../internal/sql-identifier.js';
+import { CONNECTION_TIMEOUT_MS, loadDrizzle, loadPg } from './pg.js';
+/** Таблица журнала миграций в схеме сервиса. */
+export const MIGRATIONS_TABLE = '__migrations';
+/** Журнал drizzle-kit по умолчанию, который переносит `moveJournal`. */
+const LEGACY_TABLE = '__drizzle_migrations';
+/** Неверное использование (нет журнала drizzle-kit в папке); CLI переводит в код `USAGE`. */
+export class KitUsageError extends Error {
+    name = 'KitUsageError';
+}
+function journalName(schema, table) {
+    return `${quoteIdentifier(schema)}.${quoteIdentifier(table)}`;
+}
+async function countApplied(pool, schema) {
+    const journal = journalName(schema, MIGRATIONS_TABLE);
+    // Две команды: PostgreSQL разбирает подзапрос до вычисления CASE — отсутствующая таблица даёт 42P01.
+    const exists = await pool.query('select to_regclass($1) is not null as exists', [journal]);
+    if (exists.rows[0]?.exists !== true) {
+        return 0;
+    }
+    const { rows } = await pool.query(`select count(*)::int as count from ${journal}`);
+    return rows[0]?.count ?? 0;
+}
+async function openPool(url) {
+    const pg = await loadPg();
+    const pool = new pg.Pool({
+        connectionString: url,
+        max: 1,
+        connectionTimeoutMillis: CONNECTION_TIMEOUT_MS,
+    });
+    // Обрыв простаивающего клиента: pg-pool генерирует 'error' на пуле — без слушателя процесс упал бы.
+    pool.on('error', () => undefined);
+    return pool;
+}
+/**
+ * Применяет SQL-миграции drizzle-kit из `folder` под ролью владельца; журнал — `<schema>.__migrations`.
+ * Повтор — `{applied: 0}`.
+ * @throws {TypeError} схема вне формата имени сервиса.
+ * @throws {KitUsageError} в папке нет `meta/_journal.json`.
+ */
+export async function runMigrations(options, logger) {
+    assertServiceName(options.schema, 'runMigrations');
+    if (!existsSync(join(options.folder, 'meta', '_journal.json'))) {
+        throw new KitUsageError(`runMigrations: нет журнала drizzle-kit в ${options.folder}`);
+    }
+    const { drizzle, migrate } = await loadDrizzle();
+    const pool = await openPool(options.url);
+    try {
+        const before = await countApplied(pool, options.schema);
+        logger?.debug({ schema: options.schema, before }, 'runMigrations: применение');
+        // Транзакция миграций — на выделенном клиенте: drizzle-orm 0.45.4 в transaction() над пулом выполняет BEGIN
+        // вне try/finally — при обрыве на BEGIN клиент не возвращался бы и pool.end() висел (эталон O).
+        const client = await pool.connect();
+        let failure;
+        try {
+            await migrate(drizzle(client), {
+                migrationsFolder: options.folder,
+                migrationsSchema: options.schema,
+                migrationsTable: MIGRATIONS_TABLE,
+            });
+        }
+        catch (error) {
+            failure = error instanceof Error ? error : new Error(String(error));
+            throw error;
+        }
+        finally {
+            client.release(failure);
+        }
+        const applied = (await countApplied(pool, options.schema)) - before;
+        logger?.info({ schema: options.schema, applied }, 'runMigrations: готово');
+        return { applied };
+    }
+    finally {
+        await pool.end();
+    }
+}
+/**
+ * Переносит журнал `<from>.__drizzle_migrations` в `<to>.__migrations` (строки, которых нет по `hash`), удаляет старый
+ * журнал и пустую схему `<from>` — в одной транзакции. Повтор — `{moved: 0}`.
+ * @throws {TypeError} схема вне формата или `from === to`.
+ */
+export async function moveJournal(options, logger) {
+    assertServiceName(options.from, 'moveJournal');
+    assertServiceName(options.to, 'moveJournal');
+    if (options.from === options.to) {
+        throw new TypeError('moveJournal: схемы from и to совпадают');
+    }
+    const source = journalName(options.from, LEGACY_TABLE);
+    const target = journalName(options.to, MIGRATIONS_TABLE);
+    const pool = await openPool(options.url);
+    try {
+        const client = await pool.connect();
+        let failure;
+        try {
+            await client.query('BEGIN');
+            const exists = await client.query('select to_regclass($1) is not null as exists', [source]);
+            if (exists.rows[0]?.exists !== true) {
+                await client.query('COMMIT');
+                logger?.info({ from: options.from, to: options.to, moved: 0 }, 'moveJournal: готово');
+                return { moved: 0 };
+            }
+            await client.query(`CREATE TABLE IF NOT EXISTS ${target} (id SERIAL PRIMARY KEY, hash text NOT NULL, created_at bigint)`);
+            const inserted = await client.query(`INSERT INTO ${target} (hash, created_at) SELECT s.hash, s.created_at FROM ${source} s ` +
+                `WHERE NOT EXISTS (SELECT 1 FROM ${target} t WHERE t.hash = s.hash) ORDER BY s.created_at`);
+            const moved = inserted.rowCount ?? 0;
+            await client.query(`DROP TABLE ${source}`);
+            await client.query('SAVEPOINT drop_schema');
+            try {
+                await client.query(`DROP SCHEMA ${quoteIdentifier(options.from)}`);
+                await client.query('RELEASE SAVEPOINT drop_schema');
+            }
+            catch (error) {
+                // 2BP01: в схеме остались объекты — схема остаётся.
+                if (error.code !== '2BP01') {
+                    throw error;
+                }
+                await client.query('ROLLBACK TO SAVEPOINT drop_schema');
+            }
+            await client.query('COMMIT');
+            logger?.info({ from: options.from, to: options.to, moved }, 'moveJournal: готово');
+            return { moved };
+        }
+        catch (error) {
+            await client.query('ROLLBACK').catch((rollbackError) => {
+                failure = rollbackError instanceof Error ? rollbackError : new Error('ROLLBACK');
+            });
+            throw error;
+        }
+        finally {
+            client.release(failure);
+        }
+    }
+    finally {
+        await pool.end();
+    }
+}

package/dist/database/pg.d.ts

@@ -0,0 +1,20 @@
+import type * as DrizzleNodePg from 'drizzle-orm/node-postgres';
+import type * as DrizzleMigrator from 'drizzle-orm/node-postgres/migrator';
+import type Pg from 'pg';
+export type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+export type { Pool, PoolClient, PoolConfig } from 'pg';
+/** Модуль `pg` (значение по умолчанию: `Pool`, `Client`, `escapeLiteral`). */
+export type PgModule = typeof Pg;
+/** Срок установки соединения CLI, миграций и `prepareDatabase`, мс (эталон O pool-options.ts). */
+export declare const CONNECTION_TIMEOUT_MS = 5000;
+/** Драйвер и migrator Drizzle для node-postgres. */
+export interface DrizzleDriver {
+    /** `drizzle()` из `drizzle-orm/node-postgres`. */
+    readonly drizzle: typeof DrizzleNodePg.drizzle;
+    /** `migrate()` из `drizzle-orm/node-postgres/migrator`. */
+    readonly migrate: typeof DrizzleMigrator.migrate;
+}
+/** Модуль `pg`, загружается один раз при первом вызове. */
+export declare function loadPg(): Promise<PgModule>;
+/** Драйвер Drizzle (`drizzle`, `migrate`), загружается один раз при первом вызове. */
+export declare function loadDrizzle(): Promise<DrizzleDriver>;

package/dist/database/pg.js

@@ -0,0 +1,19 @@
+import { requirePeer } from '../internal/peer.js';
+requirePeer('pg', 'database');
+/** Срок установки соединения CLI, миграций и `prepareDatabase`, мс (эталон O pool-options.ts). */
+export const CONNECTION_TIMEOUT_MS = 5000;
+let pgPromise;
+let drizzlePromise;
+/** Модуль `pg`, загружается один раз при первом вызове. */
+export function loadPg() {
+    pgPromise ??= import('pg').then((module) => module.default);
+    return pgPromise;
+}
+/** Драйвер Drizzle (`drizzle`, `migrate`), загружается один раз при первом вызове. */
+export function loadDrizzle() {
+    drizzlePromise ??= Promise.all([
+        import('drizzle-orm/node-postgres'),
+        import('drizzle-orm/node-postgres/migrator'),
+    ]).then(([driver, migrator]) => ({ drizzle: driver.drizzle, migrate: migrator.migrate }));
+    return drizzlePromise;
+}

package/dist/database/prepare-database.d.ts

@@ -0,0 +1,39 @@
+import type { Client } from 'pg';
+import type { Logger } from 'pino';
+/** Параметры `prepareDatabase` (prd.md §3.3). */
+export interface KitPrepareDatabaseOptions {
+    /** Имя сервиса `^[a-z][a-z0-9-]{1,31}$`: роли `<svc>_owner`, `<svc>_app`, `<svc>_directory`, схема `<svc>`. */
+    readonly service: string;
+    /** Адрес БД сервиса под суперпользователем (или ролью с CREATEROLE). */
+    readonly adminUrl: string;
+    /** Пароль `<svc>_owner` (миграции). */
+    readonly ownerPassword: string;
+    /** Пароль `<svc>_app` (приложение). */
+    readonly appPassword: string;
+}
+/** Результат `prepareDatabase`. */
+export interface KitPrepareDatabaseResult {
+    /** Имя подготовленной БД. */
+    readonly database: string;
+    /** Роли сервиса: owner, app, directory. */
+    readonly roles: readonly string[];
+    /** Роли, созданные этим вызовом (повтор — пусто). */
+    readonly created: readonly string[];
+}
+/** Имена ролей сервиса. */
+export declare function serviceRoles(service: string): {
+    readonly owner: string;
+    readonly app: string;
+    readonly directory: string;
+};
+/**
+ * Права ролей сервиса на БД `database` (не на `current_database()`: вызывающий может быть подключён к `postgres`):
+ * владельцу — `CONNECT, CREATE` (схема журнала мигратора), приложению — только `CONNECT` (KT-19 п. 1).
+ */
+export declare function grantDatabaseAccess(client: Pick<Client, 'query'>, service: string, database: string): Promise<void>;
+/**
+ * Идемпотентно создаёт роли `<svc>_owner`, `<svc>_app` (LOGIN, NOBYPASSRLS), `<svc>_directory` (NOLOGIN, BYPASSRLS)
+ * и схему `<svc>` владельца; повтор меняет пароли на переданные. Права на таблицы и FORCE RLS — SQL-миграции сервиса.
+ * @throws {TypeError} имя сервиса вне формата (до подключения).
+ */
+export declare function prepareDatabase(options: KitPrepareDatabaseOptions, logger?: Logger): Promise<KitPrepareDatabaseResult>;

package/dist/database/prepare-database.js

@@ -0,0 +1,75 @@
+import { assertServiceName } from '../internal/service-name.js';
+import { quoteIdentifier } from '../internal/sql-identifier.js';
+import { CONNECTION_TIMEOUT_MS, loadPg } from './pg.js';
+const LOGIN_ATTRIBUTES = 'LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOBYPASSRLS';
+const DIRECTORY_ATTRIBUTES = 'NOLOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE BYPASSRLS';
+/** Имена ролей сервиса. */
+export function serviceRoles(service) {
+    return { owner: `${service}_owner`, app: `${service}_app`, directory: `${service}_directory` };
+}
+/** CREATE или ALTER роли с атрибутами; `true` — роль создана сейчас. DDL ролей не принимает `$1`. */
+async function upsertRole(client, role, attributes, logger) {
+    const { rowCount } = await client.query('SELECT 1 FROM pg_roles WHERE rolname = $1', [role]);
+    const exists = (rowCount ?? 0) > 0;
+    await client.query(`${exists ? 'ALTER' : 'CREATE'} ROLE ${quoteIdentifier(role)} ${attributes}`);
+    logger?.debug({ role, action: exists ? 'alter' : 'create' }, 'prepareDatabase: роль');
+    return !exists;
+}
+/**
+ * Права ролей сервиса на БД `database` (не на `current_database()`: вызывающий может быть подключён к `postgres`):
+ * владельцу — `CONNECT, CREATE` (схема журнала мигратора), приложению — только `CONNECT` (KT-19 п. 1).
+ */
+export async function grantDatabaseAccess(client, service, database) {
+    const roles = serviceRoles(service);
+    const db = quoteIdentifier(database);
+    await client.query(`GRANT CONNECT, CREATE ON DATABASE ${db} TO ${quoteIdentifier(roles.owner)}`);
+    await client.query(`GRANT CONNECT ON DATABASE ${db} TO ${quoteIdentifier(roles.app)}`);
+}
+/**
+ * Идемпотентно создаёт роли `<svc>_owner`, `<svc>_app` (LOGIN, NOBYPASSRLS), `<svc>_directory` (NOLOGIN, BYPASSRLS)
+ * и схему `<svc>` владельца; повтор меняет пароли на переданные. Права на таблицы и FORCE RLS — SQL-миграции сервиса.
+ * @throws {TypeError} имя сервиса вне формата (до подключения).
+ */
+export async function prepareDatabase(options, logger) {
+    assertServiceName(options.service, 'prepareDatabase');
+    const roles = serviceRoles(options.service);
+    const pg = await loadPg();
+    const client = new pg.Client({
+        connectionString: options.adminUrl,
+        connectionTimeoutMillis: CONNECTION_TIMEOUT_MS,
+    });
+    // Ошибка простаивающего клиента до end() не должна ронять процесс.
+    client.on('error', () => undefined);
+    await client.connect();
+    try {
+        const created = [];
+        const logins = [
+            [roles.owner, options.ownerPassword],
+            [roles.app, options.appPassword],
+        ];
+        for (const [role, password] of logins) {
+            const attributes = `${LOGIN_ATTRIBUTES} PASSWORD ${pg.escapeLiteral(password)}`;
+            if (await upsertRole(client, role, attributes, logger)) {
+                created.push(role);
+            }
+        }
+        if (await upsertRole(client, roles.directory, DIRECTORY_ATTRIBUTES, logger)) {
+            created.push(roles.directory);
+        }
+        // Владелец передаёт функции SECURITY DEFINER роли directory (ALTER FUNCTION … OWNER).
+        await client.query(`GRANT ${quoteIdentifier(roles.directory)} TO ${quoteIdentifier(roles.owner)}`);
+        const { rows } = await client.query('SELECT current_database() AS database');
+        const database = rows[0]?.database ?? '';
+        await grantDatabaseAccess(client, options.service, database);
+        const schema = quoteIdentifier(options.service);
+        const owner = quoteIdentifier(roles.owner);
+        await client.query(`CREATE SCHEMA IF NOT EXISTS ${schema} AUTHORIZATION ${owner}`);
+        await client.query(`ALTER SCHEMA ${schema} OWNER TO ${owner}`);
+        await client.query(`GRANT USAGE ON SCHEMA ${schema} TO ${quoteIdentifier(roles.app)}, ${quoteIdentifier(roles.directory)}`);
+        logger?.info({ service: options.service, database, created }, 'prepareDatabase: готово');
+        return { database, roles: [roles.owner, roles.app, roles.directory], created };
+    }
+    finally {
+        await client.end();
+    }
+}

package/dist/database/run-exclusive.d.ts

@@ -0,0 +1,19 @@
+import { type Db } from './db.js';
+import type { PoolClient } from './pg.js';
+/**
+ * `fn` выполняется не больше чем в одной реплике одновременно: блокировка `pg_try_advisory_lock(hashtextextended(key,
+ * 0))` без ожидания; занято — `{ran: false}`. Блокировка держит одно соединение основного пула; `fn` получает его
+ * аргументом — работа на нём (например, `deleteInBatches({connection})`) не берёт второе соединение, поэтому
+ * достаточно `DB_POOL_MAX = 1` (KT-22 п. 4). Транзакции `fn` через `Db` берут другие соединения пула.
+ *
+ * Внутри `fn` на переданном соединении запрещены `SET` (без `LOCAL`) и `set_config(…, false)`: сеансовые настройки —
+ * тенант `app.tenant` в том числе — пережили бы `fn`. Перед возвратом в пул пакет выполняет `RESET ALL`. Настройки
+ * транзакции — `SET LOCAL` или `set_config(…, true)` внутри транзакции (`deleteInBatches` делает это сам).
+ * @throws {TypeError} пустой `key`.
+ */
+export declare function runExclusive<T>(db: Db, key: string, fn: (connection: PoolClient) => Promise<T>): Promise<{
+    readonly ran: true;
+    readonly result: T;
+} | {
+    readonly ran: false;
+}>;

package/dist/database/run-exclusive.js

@@ -0,0 +1,62 @@
+// runExclusive (prd.md §3.3, AC-4.12, UC-9): pg_try_advisory_lock на выделенном соединении основного пула. Эталон O
+// job-lock (Redis) не переносится — по PRD advisory lock. Review E4: RESET ALL перед возвратом соединения в пул.
+import { Logger } from '@nestjs/common';
+import { sanitizeError } from '../observability/sanitize-error.js';
+import { mainPoolOf, withPoolClient } from './db.js';
+const logger = new Logger('runExclusive');
+/**
+ * `fn` выполняется не больше чем в одной реплике одновременно: блокировка `pg_try_advisory_lock(hashtextextended(key,
+ * 0))` без ожидания; занято — `{ran: false}`. Блокировка держит одно соединение основного пула; `fn` получает его
+ * аргументом — работа на нём (например, `deleteInBatches({connection})`) не берёт второе соединение, поэтому
+ * достаточно `DB_POOL_MAX = 1` (KT-22 п. 4). Транзакции `fn` через `Db` берут другие соединения пула.
+ *
+ * Внутри `fn` на переданном соединении запрещены `SET` (без `LOCAL`) и `set_config(…, false)`: сеансовые настройки —
+ * тенант `app.tenant` в том числе — пережили бы `fn`. Перед возвратом в пул пакет выполняет `RESET ALL`. Настройки
+ * транзакции — `SET LOCAL` или `set_config(…, true)` внутри транзакции (`deleteInBatches` делает это сам).
+ * @throws {TypeError} пустой `key`.
+ */
+export async function runExclusive(db, key, fn) {
+    if (key === '') {
+        throw new TypeError('runExclusive: пустой ключ');
+    }
+    return withPoolClient(mainPoolOf(db), async (client) => {
+        const { rows } = await client.query('select pg_try_advisory_lock(hashtextextended($1, 0)) as locked', [key]);
+        if (rows[0]?.locked !== true) {
+            logger.debug({ key }, 'runExclusive: занято');
+            return { ran: false };
+        }
+        try {
+            return { ran: true, result: await fn(client) };
+        }
+        finally {
+            if (await unlock(client, key)) {
+                await resetSession(client, key);
+            }
+        }
+    });
+}
+/** Снимает блокировку; `false` — клиент помечен сломанным (release(error) закроет его вместе с блокировкой). */
+async function unlock(client, key) {
+    try {
+        await client.query('select pg_advisory_unlock(hashtextextended($1, 0))', [key]);
+        return true;
+    }
+    catch (error) {
+        logger.warn({ key, err: sanitizeError(error) }, 'runExclusive: снять блокировку не удалось');
+        client.emit('error', error instanceof Error ? error : new Error('unlock'));
+        return false;
+    }
+}
+/**
+ * Сеансовые настройки `fn` не уходят следующему запросу пула. `DISCARD ALL` не годится: снимает advisory-блокировки
+ * и подготовленные выражения драйвера. Сбой — клиент помечается сломанным и уничтожается пулом.
+ */
+async function resetSession(client, key) {
+    try {
+        await client.query('RESET ALL');
+    }
+    catch (error) {
+        logger.warn({ key, err: sanitizeError(error) }, 'runExclusive: сбросить сеанс не удалось');
+        client.emit('error', error instanceof Error ? error : new Error('reset'));
+    }
+}

package/dist/database/tenant.d.ts

@@ -0,0 +1,34 @@
+import type { PgColumn, PgPolicy } from 'drizzle-orm/pg-core';
+/** Настройка сеанса с тенантом транзакции (`set_config('app.tenant', …, true)`). */
+export declare const TENANT_SETTING = "app.tenant";
+/** Контекст операции с БД (prd.md §3.3): тенант, трассировка, субъект — поля `actor` конверта 01 §7.1. */
+export interface DbContext {
+    /** Тенант (компания) или `null` — операция без тенанта (системная, `readGlobal`). */
+    readonly tenant: string | null;
+    /** Идентификатор трассировки запроса. */
+    readonly traceId: string;
+    /** Субъект операции. */
+    readonly actor: {
+        /** `client_id` служебного клиента. */
+        readonly clientId?: string;
+        /** Учётная запись пользователя. */
+        readonly accountId?: string;
+        /** Участник компании. */
+        readonly memberId?: string;
+        /** От чьего имени действует агент или служба. */
+        readonly onBehalfOf?: string;
+        /** Канал: `http`, `system`, `agent` и т. п. */
+        readonly channel: string;
+    };
+}
+/**
+ * Колонка тенанта `text not null` (по умолчанию имя `tenant`; проверки `assertStrictTenantIsolation` ищут `tenant`).
+ * Nullable-тенант — только у `createIdempotencyTable` и outbox E5.
+ */
+export declare function tenantColumn(name?: string): import("drizzle-orm").NotNull<import("drizzle-orm/pg-core").PgTextBuilderInitial<string, [string, ...string[]]>>;
+/**
+ * Строгая политика RLS `tenant_isolation`: `<column> = current_setting('app.tenant', true)` для чтения и записи.
+ * SQL генерирует `drizzle-kit` сервиса. В сервисе нужна SQL-миграция
+ * `ALTER TABLE <svc>.<таблица> FORCE ROW LEVEL SECURITY` и права `GRANT … TO <svc>_app` (README).
+ */
+export declare function tenantPolicy(column: PgColumn): PgPolicy;

package/dist/database/tenant.js

@@ -0,0 +1,28 @@
+// DbContext, tenantColumn, tenantPolicy (prd.md §3.3, AC-4.8, P0 — только строгий RLS). Эталон — O columns.ts
+// tenantIsolation; I (пустой тенант видит всё) не переносится. Файл не импортирует pg: его грузит drizzle-kit со схемой.
+import { sql } from 'drizzle-orm';
+import { pgPolicy, text } from 'drizzle-orm/pg-core';
+/** Настройка сеанса с тенантом транзакции (`set_config('app.tenant', …, true)`). */
+export const TENANT_SETTING = 'app.tenant';
+/**
+ * Колонка тенанта `text not null` (по умолчанию имя `tenant`; проверки `assertStrictTenantIsolation` ищут `tenant`).
+ * Nullable-тенант — только у `createIdempotencyTable` и outbox E5.
+ */
+export function tenantColumn(name = 'tenant') {
+    return text(name).notNull();
+}
+/**
+ * Строгая политика RLS `tenant_isolation`: `<column> = current_setting('app.tenant', true)` для чтения и записи.
+ * SQL генерирует `drizzle-kit` сервиса. В сервисе нужна SQL-миграция
+ * `ALTER TABLE <svc>.<таблица> FORCE ROW LEVEL SECURITY` и права `GRANT … TO <svc>_app` (README).
+ */
+export function tenantPolicy(column) {
+    const condition = sql `${column} = current_setting('app.tenant', true)`;
+    return pgPolicy('tenant_isolation', {
+        as: 'permissive',
+        for: 'all',
+        to: 'public',
+        using: condition,
+        withCheck: condition,
+    });
+}

package/dist/http/api/api.decorator.d.ts

@@ -0,0 +1,18 @@
+import type { z } from 'zod';
+/** Ключ метаданных `@Api`. */
+export declare const API_METADATA = "verdeect-kit:api";
+/** Опции `@Api` (§3.5). */
+export interface KitApiOptions {
+    /** Краткое описание операции. */
+    readonly summary: string;
+    /** Схема тела успешного ответа; нет — ответ без тела. */
+    readonly response?: z.ZodType;
+    /** Конверт ответа: `page` — `{items, nextCursor}`, `items` — `{items}`, `array` — массив; нет — объект как есть. */
+    readonly envelope?: 'page' | 'items' | 'array';
+    /** Коды ошибок маршрута из словаря `defineErrors` дополнительно к стандартным 400/401/403/422/429. */
+    readonly errors?: readonly string[];
+    /** Поля операции OpenAPI, которые генерация не выражает (SSE, сырой прокси); сливаются глубоко. */
+    readonly extra?: Readonly<Record<string, unknown>>;
+}
+/** Включает маршрут в документ OpenAPI `verdeect-kit openapi`; маршрут без `@Api` в документ не попадает. */
+export declare function Api(options: KitApiOptions): MethodDecorator;

package/dist/http/api/api.decorator.js

@@ -0,0 +1,9 @@
+// @Api — описание маршрута для OpenAPI 3.1 (prd.md §3.5, AC-3.7). Эталон — I open-api.decorator.ts (SetMetadata, envelope).
+// По PRD: errors — коды словаря defineErrors (статусы берутся из реестра), extra — то, что генерация не выражает.
+import { SetMetadata } from '@nestjs/common';
+/** Ключ метаданных `@Api`. */
+export const API_METADATA = 'verdeect-kit:api';
+/** Включает маршрут в документ OpenAPI `verdeect-kit openapi`; маршрут без `@Api` в документ не попадает. */
+export function Api(options) {
+    return SetMetadata(API_METADATA, options);
+}

package/dist/http/api/openapi-document.d.ts

@@ -0,0 +1,40 @@
+import type { DynamicModule, Type } from '@nestjs/common';
+import type { Logger } from 'pino';
+/** JSON Schema или объект OpenAPI. */
+export type JsonObject = Record<string, unknown>;
+/** Документ OpenAPI 3.1. */
+export interface OpenApiDocument {
+    /** Версия спецификации. */
+    readonly openapi: '3.1.0';
+    /** Название и версия API. */
+    readonly info: {
+        readonly title: string;
+        readonly version: string;
+    };
+    /** Операции по путям. */
+    readonly paths: Record<string, Record<string, JsonObject>>;
+    /** Схемы безопасности и общие схемы. */
+    readonly components: JsonObject;
+}
+/** Корень модуля в метаданных `imports`. */
+type ModuleEntry = Type | DynamicModule | Promise<DynamicModule> | {
+    forwardRef: () => unknown;
+};
+/** Глубокое слияние `extra` (операция, `contracts/openapi.extra.json`): объекты сливаются, прочее заменяется. */
+export declare function deepMerge(target: JsonObject, extra: Readonly<JsonObject>): JsonObject;
+/** Схема успешного ответа, статус и описанные статусы ошибок маршрута для `expectMatchesApi`. Внутренняя функция. */
+export declare function routeResponseSchema(route: readonly [Type, string]): {
+    readonly status: number;
+    readonly schema: JsonObject | null;
+    readonly errorStatuses: readonly number[];
+    readonly errorSchema: JsonObject;
+};
+/**
+ * Документ OpenAPI 3.1 сервиса по метаданным модулей и контроллеров (§3.5): приложение не создаётся, окружение не
+ * нужно. В документ входят только маршруты с `@Api`; пути и коды отсортированы. Внутренняя функция (CLI, тесты).
+ */
+export declare function buildOpenApiDocument(module: ModuleEntry, info: {
+    readonly title: string;
+    readonly version: string;
+}, logger?: Pick<Logger, 'debug'>): Promise<OpenApiDocument>;
+export {};