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

package/dist/redis/kit-redis.module.js

@@ -0,0 +1,131 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var KitRedisModule_1;
+// KitRedisModule (prd.md §3.7, UC-11, AC-8.1, AC-8.2, AC-8.6). Эталон — O shared/redis/redis.provider.ts + redis.module.ts
+// (опции, проба, закрытие); префикс — keyPrefix и KitRedisChannels вместо ручных префиксов O. Закрытие —
+// onApplicationShutdown (шаг 4), KitLifecycle не нужен.
+import { Inject, Injectable, Module, Optional, } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { assertServiceName } from '../internal/service-name.js';
+import { KIT_LOGGER, KIT_REDIS_LOG, KIT_REDIS_PREFIX, KIT_REDIS_SUBSCRIBER, } from '../internal/tokens.js';
+import { HealthRegistry } from '../observability/health-registry.js';
+import { KitRedisChannels } from './channels.js';
+import { KIT_REDIS, closeRedisConnection, createRedisConnection, redisNestLog, } from './client.js';
+import { RateLimiter } from './rate-limiter.js';
+function redisUrl(config) {
+    if (config === undefined) {
+        throw new Error('KitRedisModule: модуль сервиса не импортирует KitConfigModule.forRoot({schema}) с envRedis');
+    }
+    return config.getOrThrow('REDIS_URL');
+}
+/** Проба `/health` и закрытие соединений на шаге 4 (внутренний). */
+let RedisLifecycle = class RedisLifecycle {
+    redis;
+    log;
+    subscriber;
+    health;
+    constructor(redis, log, subscriber, health) {
+        this.redis = redis;
+        this.log = log;
+        this.subscriber = subscriber;
+        this.health = health;
+    }
+    /** Проба `redis` некритичная: недоступен → `degraded` (§3.7). */
+    onModuleInit() {
+        this.health?.register('redis', async () => (await this.redis.ping()) === 'PONG', {
+            critical: false,
+        });
+    }
+    /** Шаг 4 остановки: закрытие соединений. */
+    async onApplicationShutdown() {
+        this.log.debug({}, 'KitRedisModule: закрытие соединений');
+        await Promise.all([
+            closeRedisConnection(this.redis, 'main', this.log),
+            ...(this.subscriber === undefined
+                ? []
+                : [closeRedisConnection(this.subscriber, 'subscriber', this.log)]),
+        ]);
+    }
+};
+RedisLifecycle = __decorate([
+    Injectable(),
+    __param(0, Inject(KIT_REDIS)),
+    __param(1, Inject(KIT_REDIS_LOG)),
+    __param(2, Optional()),
+    __param(2, Inject(KIT_REDIS_SUBSCRIBER)),
+    __param(3, Optional()),
+    __metadata("design:paramtypes", [Function, Object, Function, HealthRegistry])
+], RedisLifecycle);
+/**
+ * Redis сервиса (§3.7): основное соединение `KIT_REDIS` с `keyPrefix <svc>:` (срок команды 500 мс), `KitRedisChannels`,
+ * `RateLimiter`, проба `/health` `redis` (некритичная), закрытие на шаге 4. `subscriber: true` — второе соединение для
+ * подписок (срок 5 с); без него второго соединения нет. `keyPrefix` не действует на шаблоны `KEYS`/`SCAN` — префикс в
+ * шаблон ставит сервис. `REDIS_URL` — из `KitConfigModule` (`envRedis`).
+ */
+let KitRedisModule = KitRedisModule_1 = class KitRedisModule {
+    /** Модуль Redis сервиса; глобальный. */
+    static forRoot(options) {
+        const { service } = options;
+        assertServiceName(service, 'KitRedisModule');
+        const subscriber = options.subscriber === true
+            ? [
+                {
+                    provide: KIT_REDIS_SUBSCRIBER,
+                    useFactory: (config, log) => createRedisConnection({
+                        url: redisUrl(config),
+                        connection: 'subscriber',
+                        service,
+                        log,
+                    }),
+                    inject: [{ token: ConfigService, optional: true }, KIT_REDIS_LOG],
+                },
+            ]
+            : [];
+        return {
+            module: KitRedisModule_1,
+            global: true,
+            providers: [
+                {
+                    provide: KIT_REDIS_LOG,
+                    useFactory: (logger) => logger ?? redisNestLog('KitRedis'),
+                    inject: [{ token: KIT_LOGGER, optional: true }],
+                },
+                { provide: KIT_REDIS_PREFIX, useValue: `${service}:` },
+                {
+                    provide: KIT_REDIS,
+                    useFactory: (config, prefix, log) => createRedisConnection({
+                        url: redisUrl(config),
+                        connection: 'main',
+                        service,
+                        keyPrefix: prefix,
+                        log,
+                    }),
+                    inject: [
+                        { token: ConfigService, optional: true },
+                        KIT_REDIS_PREFIX,
+                        KIT_REDIS_LOG,
+                    ],
+                },
+                ...subscriber,
+                KitRedisChannels,
+                RateLimiter,
+                RedisLifecycle,
+            ],
+            exports: [KIT_REDIS, KitRedisChannels, RateLimiter],
+        };
+    }
+};
+KitRedisModule = KitRedisModule_1 = __decorate([
+    Module({})
+], KitRedisModule);
+export { KitRedisModule };

package/dist/redis/peer.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/redis/peer.js

@@ -0,0 +1,4 @@
+// Проверка опционального peer /redis при загрузке подпути (prd.md NFR-3, AC-1.2; П15): без top-level await. Первый
+// импорт index.ts — текст AC-1.2 называет /redis. Сам ioredis грузит client.ts динамическим import() в фабрике провайдера.
+import { requirePeer } from '../internal/peer.js';
+requirePeer('ioredis', 'redis');

package/dist/redis/rate-limiter.d.ts

@@ -0,0 +1,49 @@
+import type { Redis } from 'ioredis';
+import type { KitMetrics } from '../observability/metrics.js';
+import { type RedisLog } from './client.js';
+/** Опции проверки лимита. */
+export interface RateLimitOptions {
+    /** Допустимое число попаданий в окне, целое ≥ 1. */
+    readonly limit: number;
+    /** Окно, мс, целое ≥ 1; отсчитывается от первого попадания. */
+    readonly windowMs: number;
+}
+/** Итог проверки лимита. */
+export interface RateLimitResult {
+    /** Запрос разрешён. */
+    readonly allowed: boolean;
+    /** Сколько попаданий осталось в окне. */
+    readonly remaining: number;
+    /** Через сколько мс окно закончится; `0`, если разрешено. */
+    readonly retryAfterMs: number;
+}
+/**
+ * Ограничитель частоты (§3.7): фиксированное окно от первого попадания, ключ в Redis — `<svc>:rl:<key>`. `hit` считает
+ * попадание, `peek` только читает. Redis недоступен — fail-open: `{allowed: true, remaining: limit}`, метрика
+ * `verdeect_rate_limit_unavailable_total` +1 на каждую проверку, `warn` не чаще раза в 60 с (алерт
+ * `VerdeectRateLimitUnavailable`).
+ *
+ * @example
+ * const result = await limiter.hit(`login:${ip}`, { limit: 30, windowMs: 60_000 });
+ * if (!result.allowed) {
+ *     throwRateLimited(result);
+ * }
+ */
+export declare class RateLimiter {
+    #private;
+    private readonly redis;
+    private readonly log;
+    private readonly metrics?;
+    constructor(redis: Redis, log: RedisLog, metrics?: KitMetrics | undefined);
+    /** Считает попадание: `INCR`, `PEXPIRE … NX`, `PTTL` одним `MULTI`; `allowed = count ≤ limit`. */
+    hit(key: string, options: RateLimitOptions): Promise<RateLimitResult>;
+    /** Читает счётчик без изменения: `GET`, `PTTL` одним `MULTI`; `allowed = count < limit`. */
+    peek(key: string, options: RateLimitOptions): Promise<RateLimitResult>;
+    private resultOf;
+    private failOpen;
+}
+/**
+ * Бросает `DomainError('RATE_LIMITED', {retryAfterSec})` — 429 и `Retry-After` в секундах вверх (не меньше 1) через
+ * `KitExceptionFilter` (§3.5, §3.7). `result.allowed === true` — `TypeError` (ошибка разработчика).
+ */
+export declare function throwRateLimited(result: RateLimitResult): never;

package/dist/redis/rate-limiter.js

@@ -0,0 +1,139 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+// RateLimiter, throwRateLimited (prd.md §3.7, UC-11, AC-8.3, AC-8.4, AC-9.5). Эталон — I shared/security/rate-limiter.ts
+// (consume → hit, peek, scope); из B — PTTL и fail-open без GlitchTip. Окно в мс, PEXPIRE NX в одном MULTI.
+import { Inject, Injectable, Optional } from '@nestjs/common';
+import { KIT_METRICS, KIT_REDIS_LOG } from '../internal/tokens.js';
+import { sanitizeError } from '../observability/sanitize-error.js';
+import { DomainError } from '../http/errors.js';
+import { KIT_REDIS } from './client.js';
+/** Не чаще раза в это время на процесс — `warn` о недоступном Redis, мс. */
+const UNAVAILABLE_WARN_INTERVAL_MS = 60_000;
+function assertOptions(key, options) {
+    if (key.length === 0) {
+        throw new TypeError('RateLimiter: key — непустая строка');
+    }
+    if (!Number.isInteger(options.limit) || options.limit < 1) {
+        throw new TypeError('RateLimiter: limit — целое ≥ 1');
+    }
+    if (!Number.isInteger(options.windowMs) || options.windowMs < 1) {
+        throw new TypeError('RateLimiter: windowMs — целое ≥ 1');
+    }
+}
+/** Значения команд MULTI; ошибка любой команды или `null` (EXEC прерван) — исключение (fail-open выше). */
+function valuesOf(result) {
+    if (result === null) {
+        throw new Error('RateLimiter: EXEC прерван');
+    }
+    return result.map(([error, value]) => {
+        if (error !== null) {
+            throw error;
+        }
+        return value;
+    });
+}
+/**
+ * Ограничитель частоты (§3.7): фиксированное окно от первого попадания, ключ в Redis — `<svc>:rl:<key>`. `hit` считает
+ * попадание, `peek` только читает. Redis недоступен — fail-open: `{allowed: true, remaining: limit}`, метрика
+ * `verdeect_rate_limit_unavailable_total` +1 на каждую проверку, `warn` не чаще раза в 60 с (алерт
+ * `VerdeectRateLimitUnavailable`).
+ *
+ * @example
+ * const result = await limiter.hit(`login:${ip}`, { limit: 30, windowMs: 60_000 });
+ * if (!result.allowed) {
+ *     throwRateLimited(result);
+ * }
+ */
+let RateLimiter = class RateLimiter {
+    redis;
+    log;
+    metrics;
+    #lastUnavailableWarnAt;
+    constructor(redis, log, metrics) {
+        this.redis = redis;
+        this.log = log;
+        this.metrics = metrics;
+    }
+    /** Считает попадание: `INCR`, `PEXPIRE … NX`, `PTTL` одним `MULTI`; `allowed = count ≤ limit`. */
+    async hit(key, options) {
+        assertOptions(key, options);
+        const redisKey = `rl:${key}`;
+        try {
+            const [count, , pttl] = valuesOf(await this.redis
+                .multi()
+                .incr(redisKey)
+                .pexpire(redisKey, options.windowMs, 'NX')
+                .pttl(redisKey)
+                .exec());
+            return this.resultOf(key, Number(count), Number(pttl), options.limit, false);
+        }
+        catch (error) {
+            return this.failOpen(error, options.limit);
+        }
+    }
+    /** Читает счётчик без изменения: `GET`, `PTTL` одним `MULTI`; `allowed = count < limit`. */
+    async peek(key, options) {
+        assertOptions(key, options);
+        const redisKey = `rl:${key}`;
+        try {
+            const [count, pttl] = valuesOf(await this.redis.multi().get(redisKey).pttl(redisKey).exec());
+            return this.resultOf(key, Number(count ?? 0), Number(pttl), options.limit, true);
+        }
+        catch (error) {
+            return this.failOpen(error, options.limit);
+        }
+    }
+    resultOf(key, count, pttl, limit, peek) {
+        const allowed = peek ? count < limit : count <= limit;
+        if (!allowed) {
+            // scope — часть ключа до первого «:»; сам ключ (IP, логин) в лог не пишется.
+            this.log.debug({ scope: key.split(':', 1)[0] }, 'лимитер: лимит исчерпан');
+        }
+        return {
+            allowed,
+            remaining: Math.max(0, limit - count),
+            retryAfterMs: allowed ? 0 : Math.max(0, pttl),
+        };
+    }
+    failOpen(error, limit) {
+        this.metrics?.rateLimitUnavailable.inc();
+        const now = Date.now();
+        // ponytail: один таймер warn на процесс, по ключам — если понадобится разбор по scope.
+        if (this.#lastUnavailableWarnAt === undefined ||
+            now - this.#lastUnavailableWarnAt >= UNAVAILABLE_WARN_INTERVAL_MS) {
+            this.#lastUnavailableWarnAt = now;
+            this.log.warn({ err: sanitizeError(error) }, 'лимитер: Redis недоступен, запрос пропущен');
+        }
+        return { allowed: true, remaining: limit, retryAfterMs: 0 };
+    }
+};
+RateLimiter = __decorate([
+    Injectable(),
+    __param(0, Inject(KIT_REDIS)),
+    __param(1, Inject(KIT_REDIS_LOG)),
+    __param(2, Optional()),
+    __param(2, Inject(KIT_METRICS)),
+    __metadata("design:paramtypes", [Function, Object, Object])
+], RateLimiter);
+export { RateLimiter };
+/**
+ * Бросает `DomainError('RATE_LIMITED', {retryAfterSec})` — 429 и `Retry-After` в секундах вверх (не меньше 1) через
+ * `KitExceptionFilter` (§3.5, §3.7). `result.allowed === true` — `TypeError` (ошибка разработчика).
+ */
+export function throwRateLimited(result) {
+    if (result.allowed) {
+        throw new TypeError('throwRateLimited: результат allowed — запрос разрешён');
+    }
+    const retryAfterSec = Math.max(1, Math.ceil(result.retryAfterMs / 1000));
+    throw new DomainError('RATE_LIMITED', { retryAfterSec });
+}

package/dist/testing/count-queries.d.ts

@@ -0,0 +1,30 @@
+/** Клиент пула с методом `query` (`pg.PoolClient`). */
+interface CountableClient {
+    query: (...args: never[]) => unknown;
+}
+/** Пул с событием `acquire` (`pg.Pool`). */
+export interface KitCountablePool {
+    /** Подписка на выдачу клиента. */
+    on(event: 'acquire', listener: (client: CountableClient) => void): unknown;
+    /** Отписка. */
+    off(event: 'acquire', listener: (client: CountableClient) => void): unknown;
+}
+/** Опции `countQueries`. */
+export interface KitCountQueriesOptions {
+    /**
+     * Вызывается синхронно до отправки каждого запроса пула за время `fn` с текстом SQL без параметров. Исключение
+     * колбэка не прерывает запрос, а пробрасывается из `countQueries` после `fn`.
+     */
+    readonly onQuery?: (text: string) => void;
+}
+/**
+ * Считает все запросы пула за время `fn` (по порядку, текст SQL без параметров). Параллельная нагрузка на тот же пул
+ * попадёт в счёт; запросы, начатые до вызова, — нет. Методы клиентов восстанавливаются после. `options.onQuery` —
+ * сигнал на каждый запрос (например, «первая пачка началась») без пауз в тесте.
+ */
+export declare function countQueries<T>(pool: KitCountablePool, fn: () => Promise<T>, options?: KitCountQueriesOptions): Promise<{
+    readonly result: T;
+    readonly count: number;
+    readonly queries: readonly string[];
+}>;
+export {};

package/dist/testing/count-queries.js

@@ -0,0 +1,58 @@
+// countQueries (prd.md §3.8, AC-4.15, UC-14): подсчёт запросов пула за время fn — обёртка query выданных клиентов.
+// pg не импортируется: пул — структурный тип.
+function textOf(query) {
+    if (typeof query === 'string') {
+        return query;
+    }
+    const text = query?.text;
+    return typeof text === 'string' ? text : String(query);
+}
+/**
+ * Считает все запросы пула за время `fn` (по порядку, текст SQL без параметров). Параллельная нагрузка на тот же пул
+ * попадёт в счёт; запросы, начатые до вызова, — нет. Методы клиентов восстанавливаются после. `options.onQuery` —
+ * сигнал на каждый запрос (например, «первая пачка началась») без пауз в тесте.
+ */
+export async function countQueries(pool, fn, options = {}) {
+    const queries = [];
+    let callbackError;
+    // undefined — query был методом прототипа: восстановление снимает собственное свойство.
+    const wrapped = new Map();
+    const onAcquire = (client) => {
+        if (wrapped.has(client)) {
+            return;
+        }
+        const original = client.query;
+        wrapped.set(client, Object.hasOwn(client, 'query') ? original : undefined);
+        // boundary: обёртка сохраняет все перегрузки query pg (текст, конфиг, обратный вызов).
+        client.query = ((...args) => {
+            const text = textOf(args[0]);
+            queries.push(text);
+            try {
+                options.onQuery?.(text);
+            }
+            catch (error) {
+                callbackError ??= { error };
+            }
+            return original.apply(client, args);
+        });
+    };
+    pool.on('acquire', onAcquire);
+    try {
+        const result = await fn();
+        if (callbackError !== undefined) {
+            throw callbackError.error;
+        }
+        return { result, count: queries.length, queries: [...queries] };
+    }
+    finally {
+        pool.off('acquire', onAcquire);
+        for (const [client, original] of wrapped) {
+            if (original === undefined) {
+                delete client.query;
+            }
+            else {
+                client.query = original;
+            }
+        }
+    }
+}

package/dist/testing/create-test-app.d.ts

@@ -0,0 +1,26 @@
+import type { DynamicModule, Type } from '@nestjs/common';
+import type { NestFastifyApplication } from '@nestjs/platform-fastify';
+/** Подмена провайдера модуля сервиса. */
+export interface KitTestOverride {
+    /** Токен DI: класс, символ или строка. */
+    readonly provide: unknown;
+    /** Значение вместо провайдера. */
+    readonly useValue: unknown;
+}
+/** Опции `createTestApp` (§3.8). */
+export interface KitTestAppOptions {
+    /** Корневой модуль сервиса (импортирует `KitConfigModule.forRoot`). */
+    readonly module: Type | DynamicModule;
+    /** Имя сервиса `^[a-z][a-z0-9-]{1,31}$` — как у `bootstrapService`. */
+    readonly service: string;
+    /** Подмены провайдеров. */
+    readonly overrides?: readonly KitTestOverride[];
+    /** Лимит тела запроса, байт. */
+    readonly bodyLimit?: number;
+}
+/**
+ * Приложение сервиса для тестов (§3.8): тот же `createHttpApp`, запросы — `app.inject(...)` без порта. Окружение —
+ * из `process.env` через `KitConfigModule`. Закрытие — `app.close()`: шаги остановки 1–5 без сторожа и `exit`.
+ * Нужен `@nestjs/testing` в зависимостях сервиса.
+ */
+export declare function createTestApp(options: KitTestAppOptions): Promise<NestFastifyApplication>;

package/dist/testing/create-test-app.js

@@ -0,0 +1,32 @@
+import { buildHttpApp } from '../http/create-http-app.js';
+import { loadPeer } from '../internal/peer.js';
+import { assertServiceName } from '../internal/service-name.js';
+import { KIT_LOGGER } from '../internal/tokens.js';
+/**
+ * Приложение сервиса для тестов (§3.8): тот же `createHttpApp`, запросы — `app.inject(...)` без порта. Окружение —
+ * из `process.env` через `KitConfigModule`. Закрытие — `app.close()`: шаги остановки 1–5 без сторожа и `exit`.
+ * Нужен `@nestjs/testing` в зависимостях сервиса.
+ */
+export async function createTestApp(options) {
+    assertServiceName(options.service, 'createTestApp');
+    const { Test } = await loadPeer('@nestjs/testing', 'testing');
+    const app = await buildHttpApp({
+        module: options.module,
+        service: options.service,
+        bodyLimit: options.bodyLimit,
+        caller: 'createTestApp',
+        compile: async (root, adapter) => {
+            const builder = Test.createTestingModule({ imports: [root] });
+            for (const override of options.overrides ?? []) {
+                // boundary: токен DI — класс, символ или строка; тип @nestjs/testing шире unknown не принимает.
+                builder.overrideProvider(override.provide).useValue(override.useValue);
+            }
+            const moduleRef = await builder.compile();
+            return moduleRef.createNestApplication(adapter, {
+                bufferLogs: true,
+            });
+        },
+    });
+    app.get(KIT_LOGGER).debug({ service: options.service, overrides: options.overrides?.length ?? 0 }, 'testing: приложение собрано');
+    return app;
+}

package/dist/testing/expect-matches-api.d.ts

@@ -0,0 +1,8 @@
+import type { Type } from '@nestjs/common';
+import type { KitTestResponse } from './expect-problem.js';
+/**
+ * Проверяет ответ маршрута `[Controller, 'method']` по его `@Api` (§3.8). Статус операции — тело по схеме `response` с
+ * конвертом `envelope`; описанный статус ошибки — тело `{error: {code, message, details}}`; прочий статус — ошибка.
+ * Несовпадение — `AssertionError` с путями ошибок Ajv; маршрут без `@Api` — ошибка с именем маршрута.
+ */
+export declare function expectMatchesApi(response: KitTestResponse, route: readonly [Type, string]): void;

package/dist/testing/expect-matches-api.js

@@ -0,0 +1,49 @@
+// expectMatchesApi (prd.md §3.8 — E3, AC-3.7; KT-17): ответ соответствует @Api маршрута — тот же построитель, что у CLI
+// verdeect-kit openapi. Успешный статус — схема response с конвертом; описанный статус ошибки (стандартные, errors
+// маршрута, 401/403/409 guard'а @verdeect/auth) — ErrorResponse. Эталона нет: пишется по PRD. Валидатор — Ajv 2020 (ajv —
+// внутренняя деталь /testing, NFR-3), скомпилированная схема кэшируется по маршруту и статусу; утверждения —
+// node:assert/strict.
+import assert from 'node:assert/strict';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { routeResponseSchema } from '../http/api/openapi-document.js';
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+/** Скомпилированные схемы: класс контроллера → `<метод>:<статус>` → валидатор. */
+const validators = new WeakMap();
+function validatorOf(route, status, schema) {
+    const [controller, handlerName] = route;
+    const byRoute = validators.get(controller) ?? new Map();
+    validators.set(controller, byRoute);
+    const key = `${handlerName}:${status}`;
+    const cached = byRoute.get(key);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const validate = ajv.compile(schema);
+    byRoute.set(key, validate);
+    return validate;
+}
+/**
+ * Проверяет ответ маршрута `[Controller, 'method']` по его `@Api` (§3.8). Статус операции — тело по схеме `response` с
+ * конвертом `envelope`; описанный статус ошибки — тело `{error: {code, message, details}}`; прочий статус — ошибка.
+ * Несовпадение — `AssertionError` с путями ошибок Ajv; маршрут без `@Api` — ошибка с именем маршрута.
+ */
+export function expectMatchesApi(response, route) {
+    const { status, schema, errorStatuses, errorSchema } = routeResponseSchema(route);
+    const name = `${route[0].name}.${route[1]}`;
+    const isError = response.statusCode !== status;
+    if (isError && !errorStatuses.includes(response.statusCode)) {
+        assert.fail(`${name}: статус ${response.statusCode} не описан в @Api (успех — ${status}, ошибки — ${errorStatuses.join(', ')})`);
+    }
+    const expected = isError ? errorSchema : schema;
+    if (expected === null) {
+        return;
+    }
+    const validate = validatorOf(route, response.statusCode, expected);
+    const body = response.json();
+    if (!validate(body)) {
+        const errors = (validate.errors ?? [])
+            .map((error) => `${error.instancePath || '(root)'} ${error.message ?? ''}`.trim())
+            .join('; ');
+        assert.fail(`${name}: ответ вне схемы @Api — ${errors}`);
+    }
+}

package/dist/testing/expect-problem.d.ts

@@ -0,0 +1,24 @@
+/** Ответ inject Fastify или похожий: статус и разбор тела. */
+export interface KitTestResponse {
+    /** HTTP-статус. */
+    readonly statusCode: number;
+    /** Тело ответа, разобранное как JSON. */
+    json(): unknown;
+}
+/** Ожидаемая ошибка. */
+export interface KitExpectedProblem {
+    /** HTTP-статус. */
+    readonly status: number;
+    /** Код ошибки словаря. */
+    readonly code: string;
+    /** Ожидаемые `details.issues` (глубокое сравнение), для 422 `VALIDATION_FAILED`. */
+    readonly issues?: readonly {
+        readonly path: string;
+        readonly code: string;
+    }[];
+}
+/**
+ * Проверяет ответ-ошибку (§3.5): статус, форма `{error: {code, message: string, details: object}}`, код и (если задано)
+ * `details.issues`. Несовпадение — `AssertionError` с понятным текстом.
+ */
+export declare function expectProblem(response: KitTestResponse, expected: KitExpectedProblem): void;

package/dist/testing/expect-problem.js

@@ -0,0 +1,23 @@
+// expectProblem (prd.md §3.8 — E3, §3.5): утверждение об ответе-ошибке {error: {code, message, details}}. Эталона нет —
+// ближайшее O test/support/http.ts (errorCode). Утверждения — node:assert/strict: peer vitest не загружается.
+import assert from 'node:assert/strict';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Проверяет ответ-ошибку (§3.5): статус, форма `{error: {code, message: string, details: object}}`, код и (если задано)
+ * `details.issues`. Несовпадение — `AssertionError` с понятным текстом.
+ */
+export function expectProblem(response, expected) {
+    const body = response.json();
+    const text = JSON.stringify(body);
+    assert.strictEqual(response.statusCode, expected.status, `статус ${response.statusCode}, ожидался ${expected.status}: ${text}`);
+    const error = isRecord(body) ? body.error : undefined;
+    assert.ok(isRecord(error), `тело не в форме {error: {code, message, details}}: ${text}`);
+    assert.strictEqual(typeof error.message, 'string', `error.message не строка: ${text}`);
+    assert.ok(isRecord(error.details), `error.details не объект: ${text}`);
+    assert.strictEqual(error.code, expected.code, `код ${String(error.code)}, ожидался ${expected.code}`);
+    if (expected.issues !== undefined) {
+        assert.deepStrictEqual(error.details.issues, expected.issues, `details.issues: ${text}`);
+    }
+}

package/dist/testing/images.d.ts

@@ -0,0 +1,10 @@
+/** Образы тестов и compose сервисов (§3.8); мажорная смена образа — мажор пакета (G14). */
+export declare const TEST_IMAGES: {
+    readonly postgres: "postgres:17.11-alpine3.24";
+    readonly redis: "redis:7.4.11-alpine";
+    readonly rabbitmq: "rabbitmq:4.3.6-management-alpine";
+    readonly mailpit: "axllent/mailpit:v1.31.6";
+    readonly minio: "pgsty/minio:RELEASE.2026-08-04T00-00-00Z";
+};
+/** Репозиторий образа — часть до последнего `:` (`axllent/mailpit`); внутренний помощник правил §3.8. */
+export declare function imageRepository(image: string): string;

package/dist/testing/images.js

@@ -0,0 +1,14 @@
+// Образы тестового контура (prd.md §3.8, E1); эталон — O test/support/images.ts, mailpit — I global-setup.ts.
+/** Образы тестов и compose сервисов (§3.8); мажорная смена образа — мажор пакета (G14). */
+export const TEST_IMAGES = {
+    postgres: 'postgres:17.11-alpine3.24',
+    redis: 'redis:7.4.11-alpine',
+    rabbitmq: 'rabbitmq:4.3.6-management-alpine',
+    mailpit: 'axllent/mailpit:v1.31.6',
+    minio: 'pgsty/minio:RELEASE.2026-08-04T00-00-00Z',
+};
+/** Репозиторий образа — часть до последнего `:` (`axllent/mailpit`); внутренний помощник правил §3.8. */
+export function imageRepository(image) {
+    const colon = image.lastIndexOf(':');
+    return colon === -1 ? image : image.slice(0, colon);
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,23 @@
+export { createTestApp } from './create-test-app.js';
+export type { KitTestAppOptions, KitTestOverride } from './create-test-app.js';
+export { expectMatchesApi } from './expect-matches-api.js';
+export { expectProblem } from './expect-problem.js';
+export type { KitExpectedProblem, KitTestResponse } from './expect-problem.js';
+export { TEST_IMAGES } from './images.js';
+export { startTestStack } from './start-test-stack.js';
+export { tcpProxy } from './tcp-proxy.js';
+export type { TcpProxy } from './tcp-proxy.js';
+export { TEST_TIMEOUT_SCALE } from './timeout-scale.js';
+export { assertRepoConventions } from './repo-conventions.js';
+export { timingGuard } from './timing-guard.js';
+export { createScratchDatabase } from './scratch-database.js';
+export type { KitScratchDatabase } from './scratch-database.js';
+export { redisWorkerOverride } from './redis-worker.js';
+export { workerScope } from './worker-scope.js';
+export type { KitWorkerScope } from './worker-scope.js';
+export { countQueries } from './count-queries.js';
+export type { KitCountablePool, KitCountQueriesOptions } from './count-queries.js';
+export { assertAppRoleIsNotOwner, assertStrictTenantIsolation } from './tenant-isolation.js';
+export type { KitQueryable, KitTenantIsolationOptions } from './tenant-isolation.js';
+export { assertOutboxCoverage, expectOutbox } from './outbox-coverage.js';
+export { publishTestEvent, waitForInbox } from './test-events.js';