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

package/dist/idempotency/idempotency.interceptor.js

@@ -0,0 +1,317 @@
+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); }
+};
+// IdempotencyInterceptor и хранилище (prd.md §3.3а v1.14, AC-4.14, UC-7). Эталон — O idempotency.interceptor.ts +
+// idempotency.store.ts (KEY_FORMAT, canonicalJson, отпечаток, begin с FOR UPDATE, брошенная in_progress через 5 мин,
+// mismatch до in_progress, release при ошибке, один повтор complete). По PRD: область user/agent → (tenant, sub),
+// service → client_id или (client_id, поле tenantFromBody); Location в ответе; без принципала — 500; коды — DomainError
+// словаря /http; сравнение области — IS NOT DISTINCT FROM (tenant nullable).
+import { createHash, randomUUID } from 'node:crypto';
+import { Inject, Injectable, Logger, } from '@nestjs/common';
+import { HTTP_CODE_METADATA } from '@nestjs/common/constants.js';
+import { Reflector } from '@nestjs/core';
+import { principalOf } from '@verdeect/auth/nest';
+import { and, eq, sql } from 'drizzle-orm';
+import { from, lastValueFrom } from 'rxjs';
+import { Db } from '../database/db.js';
+import { DomainError } from '../http/errors.js';
+import { IDEMPOTENT_METADATA } from '../internal/metadata.js';
+import { sanitizeError } from '../observability/sanitize-error.js';
+import { captureError } from '../observability/sentry.js';
+/** Токен таблицы идемпотентности сервиса (провайдер `KitIdempotencyModule`). */
+export const KIT_IDEMPOTENCY_TABLE = Symbol('KIT_IDEMPOTENCY_TABLE');
+/** Печатные ASCII, ≤ 200 знаков (эталон O). */
+export const KEY_FORMAT = /^[\x21-\x7E]{1,200}$/;
+/** Брошенная `in_progress` (запрос упал без release) переиспользуется через 5 минут (эталон O). */
+const ABANDONED_AFTER_MINUTES = 5;
+/** Срок хранения ответа. */
+const EXPIRES_AFTER_HOURS = 24;
+/** Заголовок ответа повтора. */
+const REPLAYED_HEADER = 'Idempotent-Replayed';
+/** JSON с рекурсивно отсортированными ключами: одинаковое тело — одинаковый отпечаток (эталон O). */
+export function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(',')}]`;
+    }
+    if (typeof value === 'object' && value !== null) {
+        const entries = Object.entries(value)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value ?? null);
+}
+/** SHA-256 hex метода, пути без query и канонического тела. */
+export function fingerprintOf(method, path, body) {
+    const bare = path.split('?')[0] ?? '';
+    return createHash('sha256')
+        .update(`${method} ${bare}\n${canonicalJson(body ?? null)}`)
+        .digest('hex');
+}
+/** Значение поля тела по пути через точку. */
+function fieldOf(body, path) {
+    let current = body;
+    for (const segment of path.split('.')) {
+        if (typeof current !== 'object' || current === null) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Область ключа (§3.3а): пользователь и агент — тенант токена (поле тела игнорируется); служба — `client_id` и тенант
+ * из поля `tenantFromBody`, если это непустая строка, иначе `null`.
+ */
+export function scopeOf(principal, body, options) {
+    if (principal.kind === 'user') {
+        return { tenant: principal.tenant, subject: `user:${principal.sub}` };
+    }
+    if (principal.kind === 'agent') {
+        return { tenant: principal.tenant, subject: `agent:${principal.sub}` };
+    }
+    const value = options.tenantFromBody === undefined ? undefined : fieldOf(body, options.tenantFromBody);
+    return {
+        tenant: typeof value === 'string' && value !== '' ? value : null,
+        subject: `service:${principal.clientId}`,
+    };
+}
+/** Ключ из заголовка: нет — `null`; не строка или не по формату — 422 `VALIDATION_FAILED`. */
+function readKey(request) {
+    const header = request.headers['idempotency-key'];
+    if (header === undefined) {
+        return null;
+    }
+    if (typeof header !== 'string' || !KEY_FORMAT.test(header)) {
+        throw new DomainError('VALIDATION_FAILED', {
+            issues: [{ path: 'Idempotency-Key', code: 'invalid' }],
+        });
+    }
+    return header;
+}
+/**
+ * Интерсептор `@Idempotent` (§3.3а): регистрирует `KitIdempotencyModule` через `APP_INTERCEPTOR`. Повтор — сохранённый
+ * ответ и `Idempotent-Replayed: true`; другое тело — 422 `IDEMPOTENCY_KEY_REUSED`; запрос ещё идёт — 409
+ * `IDEMPOTENCY_IN_PROGRESS`. Сохраняются только успешные ответы.
+ */
+let IdempotencyInterceptor = class IdempotencyInterceptor {
+    reflector;
+    db;
+    table;
+    logger = new Logger('IdempotencyInterceptor');
+    constructor(reflector, db, table) {
+        this.reflector = reflector;
+        this.db = db;
+        this.table = table;
+    }
+    /** Оборачивает обработчик маршрута с `@Idempotent`. */
+    intercept(context, next) {
+        const options = this.reflector.get(IDEMPOTENT_METADATA, context.getHandler());
+        if (options === undefined) {
+            return next.handle();
+        }
+        const request = context.switchToHttp().getRequest();
+        // Принципал — до ключа: без guard'а 500 при любом ключе и без него (PRD v1.14).
+        const principal = principalOf(request);
+        if (principal === null) {
+            throw new Error('@Idempotent: нет проверенного принципала — нужен VerdeectAuthGuard на маршруте');
+        }
+        const key = readKey(request);
+        if (key === null) {
+            if (options.required === true) {
+                throw new DomainError('IDEMPOTENCY_KEY_REQUIRED');
+            }
+            return next.handle();
+        }
+        return from(this.run(context, next, request, principal, options, key));
+    }
+    async run(context, next, request, principal, options, key) {
+        const scope = scopeOf(principal, request.body, options);
+        const ctx = {
+            tenant: scope.tenant,
+            traceId: String(request.id),
+            actor: {
+                ...(principal.clientId === null ? {} : { clientId: principal.clientId }),
+                channel: 'http',
+            },
+        };
+        const fields = {
+            subjectKind: principal.kind,
+            keyPrefix: key.slice(0, 8),
+            traceId: ctx.traceId,
+        };
+        const path = request.originalUrl ?? request.url;
+        const begin = await this.begin(ctx, scope, key, fingerprintOf(request.method, path, request.body));
+        this.logger.debug({ ...fields, state: begin.state }, 'идемпотентность: begin');
+        if (begin.state === 'mismatch') {
+            this.logger.warn(fields, 'идемпотентность: ключ с другим телом');
+            throw new DomainError('IDEMPOTENCY_KEY_REUSED');
+        }
+        if (begin.state === 'in_progress') {
+            this.logger.warn(fields, 'идемпотентность: запрос с ключом ещё выполняется');
+            throw new DomainError('IDEMPOTENCY_IN_PROGRESS');
+        }
+        const reply = context.switchToHttp().getResponse();
+        if (begin.state === 'replay') {
+            void reply.status(begin.status).header(REPLAYED_HEADER, 'true');
+            if (begin.location !== null) {
+                void reply.header('Location', begin.location);
+            }
+            return begin.body;
+        }
+        let body;
+        try {
+            body = await lastValueFrom(next.handle(), { defaultValue: undefined });
+        }
+        catch (error) {
+            await this.release(ctx, scope, key, begin.attempt, fields);
+            throw error;
+        }
+        const status = this.reflector.get(HTTP_CODE_METADATA, context.getHandler()) ??
+            (request.method === 'POST' ? 201 : 200);
+        const header = reply.getHeader('location');
+        const location = typeof header === 'string' ? header : null;
+        await this.completeWithRetry(ctx, scope, key, begin.attempt, { status, body: body ?? null, location }, fields);
+        return body;
+    }
+    where(scope, key) {
+        const t = this.table;
+        return and(sql `${t.tenant} IS NOT DISTINCT FROM ${scope.tenant}`, eq(t.subject, scope.subject), eq(t.key, key));
+    }
+    begin(ctx, scope, key, fingerprint) {
+        const t = this.table;
+        // Метка попытки: ответ пишет только та попытка, что захватила строку (KT-22 п. 3).
+        const attempt = randomUUID();
+        return this.db.transaction(ctx, async (tx) => {
+            // ON CONFLICT DO NOTHING без ON CONSTRAINT работает, пока idempotency_key_scope_key (tenant, subject, key) —
+            // единственное уникальное ограничение таблицы; новое уникальное ограничение — переписать на
+            // ON CONFLICT ON CONSTRAINT idempotency_key_scope_key (KT-21 п. 3).
+            const inserted = await tx
+                .insert(t)
+                .values({ tenant: scope.tenant, subject: scope.subject, key, fingerprint, attempt })
+                .onConflictDoNothing()
+                .returning({ key: t.key });
+            if (inserted.length > 0) {
+                return { state: 'new', attempt };
+            }
+            const [row] = await tx
+                .select({
+                fingerprint: t.fingerprint,
+                state: t.state,
+                status: t.responseStatus,
+                body: t.responseBody,
+                location: t.responseLocation,
+                expired: sql `${t.createdAt} < now() - make_interval(hours => ${EXPIRES_AFTER_HOURS})`,
+                abandoned: sql `${t.state} = 'in_progress' AND ${t.createdAt} < now() - make_interval(mins => ${ABANDONED_AFTER_MINUTES})`,
+            })
+                .from(t)
+                .where(this.where(scope, key))
+                .for('update');
+            if (row === undefined) {
+                throw new Error('idempotency: строка области не найдена после конфликта');
+            }
+            if (row.expired || row.abandoned) {
+                if (row.abandoned && !row.expired) {
+                    this.logger.warn({ keyPrefix: key.slice(0, 8), traceId: ctx.traceId }, 'идемпотентность: брошенная in_progress переиспользована');
+                }
+                await tx
+                    .update(t)
+                    .set({
+                    fingerprint,
+                    attempt,
+                    state: 'in_progress',
+                    responseStatus: null,
+                    responseBody: null,
+                    responseLocation: null,
+                    createdAt: sql `now()`,
+                })
+                    .where(this.where(scope, key));
+                return { state: 'new', attempt };
+            }
+            if (row.fingerprint !== fingerprint) {
+                return { state: 'mismatch' };
+            }
+            if (row.state === 'in_progress') {
+                return { state: 'in_progress' };
+            }
+            return {
+                state: 'replay',
+                status: row.status ?? 200,
+                body: row.body,
+                location: row.location,
+            };
+        });
+    }
+    /**
+     * Обработчик упал: строка своей попытки удаляется — повтор выполнит запрос заново; перехваченную строку другой
+     * попытки не трогает; сбой release не подменяет ответ.
+     */
+    async release(ctx, scope, key, attempt, fields) {
+        try {
+            await this.db.transaction(ctx, (tx) => tx
+                .delete(this.table)
+                .where(and(this.where(scope, key), eq(this.table.state, 'in_progress'), eq(this.table.attempt, attempt))));
+        }
+        catch (error) {
+            this.logger.error({ ...fields, err: sanitizeError(error) }, 'идемпотентность: release не удался');
+            captureError(error);
+        }
+    }
+    /**
+     * Один повтор `complete` сразу после сбоя (эталон O). После двух сбоев ответ клиенту не меняется: строка остаётся
+     * `in_progress` и через 5 минут переиспользуется. Ответ пишется только своей попытки: строку перехватил повторный
+     * запрос (обработчик дольше 5 минут) — ответ не сохраняется, `warn` без ключа и тела (KT-22 п. 3).
+     */
+    async completeWithRetry(ctx, scope, key, attempt, response, fields) {
+        const complete = () => this.db.transaction(ctx, (tx) => tx
+            .update(this.table)
+            .set({
+            state: 'done',
+            responseStatus: response.status,
+            responseBody: response.body,
+            responseLocation: response.location,
+        })
+            .where(and(this.where(scope, key), eq(this.table.attempt, attempt))));
+        // Перехват строки другой попыткой — warn без ключа (даже без префикса) и тела (KT-22 п. 3).
+        const taken = (rowCount) => {
+            if ((rowCount ?? 0) > 0) {
+                return false;
+            }
+            this.logger.warn({ subjectKind: fields.subjectKind, traceId: fields.traceId }, 'идемпотентность: строку перехватила другая попытка — ответ не сохранён');
+            return true;
+        };
+        try {
+            const result = await complete();
+            if (!taken(result.rowCount)) {
+                this.logger.debug({ ...fields, state: 'done' }, 'идемпотентность: complete');
+            }
+            return;
+        }
+        catch (error) {
+            this.logger.warn({ ...fields, err: sanitizeError(error) }, 'идемпотентность: complete не удался, повтор');
+        }
+        try {
+            taken((await complete()).rowCount);
+        }
+        catch (error) {
+            this.logger.error({ ...fields, err: sanitizeError(error) }, 'идемпотентность: complete не удался');
+            captureError(error);
+        }
+    }
+};
+IdempotencyInterceptor = __decorate([
+    Injectable(),
+    __param(2, Inject(KIT_IDEMPOTENCY_TABLE)),
+    __metadata("design:paramtypes", [Reflector,
+        Db, Object])
+], IdempotencyInterceptor);
+export { IdempotencyInterceptor };

package/dist/idempotency/idempotent.decorator.d.ts

@@ -0,0 +1,7 @@
+import { type KitIdempotentOptions } from '../internal/metadata.js';
+/**
+ * Маршрут принимает `Idempotency-Key` (§3.3а): повтор с тем же ключом и телом — сохранённый ответ и
+ * `Idempotent-Replayed: true`. Только на маршрутах с `VerdeectAuthGuard`: без проверенного принципала — 500.
+ * @throws {TypeError} `tenantFromBody` — пустая строка или путь с пустым сегментом.
+ */
+export declare function Idempotent(options?: KitIdempotentOptions): MethodDecorator;

package/dist/idempotency/idempotent.decorator.js

@@ -0,0 +1,16 @@
+// @Idempotent (prd.md §3.3а, AC-4.14). Эталон — O IDEMPOTENT/SetMetadata; ключ метаданных — internal/metadata.ts (его
+// читает OpenAPI /http без импорта idempotency). Без pg.
+import { SetMetadata } from '@nestjs/common';
+import { IDEMPOTENT_METADATA } from '../internal/metadata.js';
+/**
+ * Маршрут принимает `Idempotency-Key` (§3.3а): повтор с тем же ключом и телом — сохранённый ответ и
+ * `Idempotent-Replayed: true`. Только на маршрутах с `VerdeectAuthGuard`: без проверенного принципала — 500.
+ * @throws {TypeError} `tenantFromBody` — пустая строка или путь с пустым сегментом.
+ */
+export function Idempotent(options = {}) {
+    const path = options.tenantFromBody;
+    if (path !== undefined && path.split('.').some((segment) => segment === '')) {
+        throw new TypeError('@Idempotent: tenantFromBody — путь поля через точку без пустых сегментов');
+    }
+    return SetMetadata(IDEMPOTENT_METADATA, options);
+}

package/dist/idempotency/index.d.ts

@@ -0,0 +1,7 @@
+import './peer.js';
+export { Idempotent } from './idempotent.decorator.js';
+export { KitIdempotencyModule } from './kit-idempotency.module.js';
+export type { KitIdempotencyModuleOptions } from './kit-idempotency.module.js';
+export { createIdempotencyTable, idempotencyPurgeSql } from './table.js';
+export type { KitIdempotencyTable } from './table.js';
+export type { KitIdempotentOptions } from '../internal/metadata.js';

package/dist/idempotency/index.js

@@ -0,0 +1,6 @@
+// Точка входа @verdeect/kit/idempotency (prd.md §3.3а, E4): явный список экспортов. Первый импорт — ./peer.js: без pg
+// ошибка AC-1.2 называет /idempotency (requirePeer синхронно, без top-level await — П15).
+import './peer.js';
+export { Idempotent } from './idempotent.decorator.js';
+export { KitIdempotencyModule } from './kit-idempotency.module.js';
+export { createIdempotencyTable, idempotencyPurgeSql } from './table.js';

package/dist/idempotency/kit-idempotency.module.d.ts

@@ -0,0 +1,47 @@
+import { type BeforeApplicationShutdown, type DynamicModule, type OnApplicationBootstrap, type OnModuleInit } from '@nestjs/common';
+import type { Logger as PinoLogger } from 'pino';
+import { Db } from '../database/db.js';
+import type { KitMetrics } from '../observability/metrics.js';
+import { type KitIdempotencyTable } from './table.js';
+/** Опции `KitIdempotencyModule.forRoot`. */
+export interface KitIdempotencyModuleOptions {
+    /** Таблица `createIdempotencyTable(pgSchema(…))` схемы сервиса. */
+    readonly table: KitIdempotencyTable;
+}
+/** Очистка записей старше 24 ч одной репликой (UC-9); внутренний класс модуля. */
+export declare class IdempotencyCleanup implements OnModuleInit, OnApplicationBootstrap, BeforeApplicationShutdown {
+    private readonly db;
+    private readonly schema;
+    private readonly metrics?;
+    private readonly log;
+    private stopped;
+    private interval;
+    private current;
+    private running;
+    constructor(db: Db, schema: string, metrics?: KitMetrics | undefined, logger?: PinoLogger);
+    /** До прослушивания порта: функция очистки есть, иначе отказ запуска. */
+    onModuleInit(): Promise<void>;
+    /** Первый проход сразу после старта, затем раз в час. */
+    onApplicationBootstrap(): void;
+    /** Текущий проход (включая ещё не начатый первый); нет — разрешённый промис. */
+    idle(): Promise<void>;
+    /** Проход очистки; идущий проход не накладывается (пропуск). Ошибка не пробрасывается. */
+    run(limits?: {
+        readonly batchSize: number;
+        readonly maxBatches: number;
+    }): Promise<void>;
+    /** Шаг 3 остановки: пачка дорабатывает, новая не начинается. */
+    beforeApplicationShutdown(): Promise<void>;
+    private pass;
+}
+/**
+ * Идемпотентность маршрутов `@Idempotent` (§3.3а): интерсептор на `Db` сервиса, проверка функции
+ * `idempotency_purge` при старте, очистка записей старше 24 ч раз в час одной репликой. Требует `KitDatabaseModule`.
+ */
+export declare class KitIdempotencyModule {
+    /**
+     * Модуль с таблицей сервиса.
+     * @throws {TypeError} таблица без схемы или имя схемы вне формата имени сервиса.
+     */
+    static forRoot(options: KitIdempotencyModuleOptions): DynamicModule;
+}

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

@@ -0,0 +1,173 @@
+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 KitIdempotencyModule_1;
+// KitIdempotencyModule.forRoot({table}) (prd.md §3.3а v1.14, AC-4.14, AC-9.5, UC-9). Эталон — O idempotency.module.ts +
+// idempotency-cleanup.job.ts (раз в час, пачка 1000, до 100 пачек, остановка); по PRD: очистка через runExclusive
+// функцией idempotency_purge пачками; нет функции — отказ запуска; расписание — таймер (без @nestjs/schedule); пулы и
+// шаги остановки — хуки Nest (KitLifecycle не используется).
+import { Inject, Injectable, Logger, Module, Optional, } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
+import { sql } from 'drizzle-orm';
+import { getTableConfig } from 'drizzle-orm/pg-core';
+import { deleteInBatches } from '../database/batches.js';
+import { Db } from '../database/db.js';
+import { runExclusive } from '../database/run-exclusive.js';
+import { resultOf } from '../internal/cleanup-result.js';
+import { assertServiceName } from '../internal/service-name.js';
+import { quoteIdentifier } from '../internal/sql-identifier.js';
+import { KIT_LOGGER, KIT_METRICS } from '../internal/tokens.js';
+import { sanitizeError } from '../observability/sanitize-error.js';
+import { captureError } from '../observability/sentry.js';
+import { IdempotencyInterceptor, KIT_IDEMPOTENCY_TABLE } from './idempotency.interceptor.js';
+import { IDEMPOTENCY_TABLE, PURGE_FUNCTION } from './table.js';
+/** Интервал очистки (эталон O — раз в час). */
+const CLEANUP_INTERVAL_MS = 3_600_000;
+/** Пределы прохода по умолчанию (эталон O). */
+const CLEANUP_LIMITS = { batchSize: 1000, maxBatches: 100 };
+/** Схема таблицы (внутренний токен). */
+const KIT_IDEMPOTENCY_SCHEMA = Symbol('KIT_IDEMPOTENCY_SCHEMA');
+function nestLog() {
+    const logger = new Logger('IdempotencyCleanup');
+    return {
+        debug: (fields, message) => logger.debug(fields, message),
+        info: (fields, message) => logger.log(fields, message),
+        error: (fields, message) => logger.error(fields, message),
+    };
+}
+/** Очистка записей старше 24 ч одной репликой (UC-9); внутренний класс модуля. */
+let IdempotencyCleanup = class IdempotencyCleanup {
+    db;
+    schema;
+    metrics;
+    log;
+    stopped = false;
+    interval;
+    current;
+    running = false;
+    constructor(db, schema, metrics, logger) {
+        this.db = db;
+        this.schema = schema;
+        this.metrics = metrics;
+        this.log = logger ?? nestLog();
+    }
+    /** До прослушивания порта: функция очистки есть, иначе отказ запуска. */
+    async onModuleInit() {
+        const signature = `${quoteIdentifier(this.schema)}.${quoteIdentifier(PURGE_FUNCTION)}(integer)`;
+        const { rows } = await this.db.readGlobal((reader) => reader.execute(sql `select to_regprocedure(${signature}) is not null as ok`));
+        if (rows[0]?.ok !== true) {
+            throw new Error(`KitIdempotencyModule: нет функции ${this.schema}.${PURGE_FUNCTION} — добавьте idempotencyPurgeSql(${this.schema}) в SQL-миграцию сервиса`);
+        }
+    }
+    /** Первый проход сразу после старта, затем раз в час. */
+    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 = CLEANUP_LIMITS) {
+        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 table = IDEMPOTENCY_TABLE;
+        const fn = sql.raw(`${quoteIdentifier(this.schema)}.${quoteIdentifier(PURGE_FUNCTION)}`);
+        try {
+            const outcome = await runExclusive(this.db, `verdeect-kit:idempotency-cleanup:${this.schema}`, 
+            // Пачки — на соединении блокировки: очистка не берёт второе соединение пула (KT-22 п. 4).
+            (connection) => deleteInBatches({
+                db: this.db,
+                sql: (batch) => sql `select ${fn}(${batch}::int) as deleted`,
+                ...limits,
+                shouldContinue: () => !this.stopped,
+                connection,
+            }));
+            if (!outcome.ran) {
+                this.log.debug({ table }, 'очистка идемпотентности: другая реплика');
+                return;
+            }
+            const { deleted, batches, complete } = outcome.result;
+            const result = resultOf(complete, batches, limits.maxBatches);
+            this.metrics?.cleanupRuns.inc({ table, result });
+            this.log.info({ table, deleted, batches, result }, 'очистка идемпотентности: проход');
+        }
+        catch (error) {
+            this.metrics?.cleanupRuns.inc({ table, result: 'error' });
+            this.log.error({ table, err: sanitizeError(error) }, 'очистка идемпотентности: ошибка');
+            captureError(error);
+        }
+    }
+};
+IdempotencyCleanup = __decorate([
+    Injectable(),
+    __param(1, Inject(KIT_IDEMPOTENCY_SCHEMA)),
+    __param(2, Optional()),
+    __param(2, Inject(KIT_METRICS)),
+    __param(3, Optional()),
+    __param(3, Inject(KIT_LOGGER)),
+    __metadata("design:paramtypes", [Db, String, Object, Object])
+], IdempotencyCleanup);
+export { IdempotencyCleanup };
+/**
+ * Идемпотентность маршрутов `@Idempotent` (§3.3а): интерсептор на `Db` сервиса, проверка функции
+ * `idempotency_purge` при старте, очистка записей старше 24 ч раз в час одной репликой. Требует `KitDatabaseModule`.
+ */
+let KitIdempotencyModule = KitIdempotencyModule_1 = class KitIdempotencyModule {
+    /**
+     * Модуль с таблицей сервиса.
+     * @throws {TypeError} таблица без схемы или имя схемы вне формата имени сервиса.
+     */
+    static forRoot(options) {
+        const schema = getTableConfig(options.table).schema;
+        if (schema === undefined) {
+            throw new TypeError('KitIdempotencyModule: таблица без схемы — createIdempotencyTable(pgSchema(…))');
+        }
+        assertServiceName(schema, 'KitIdempotencyModule');
+        return {
+            module: KitIdempotencyModule_1,
+            global: true,
+            providers: [
+                { provide: KIT_IDEMPOTENCY_TABLE, useValue: options.table },
+                { provide: KIT_IDEMPOTENCY_SCHEMA, useValue: schema },
+                { provide: APP_INTERCEPTOR, useClass: IdempotencyInterceptor },
+                IdempotencyCleanup,
+            ],
+        };
+    }
+};
+KitIdempotencyModule = KitIdempotencyModule_1 = __decorate([
+    Module({})
+], KitIdempotencyModule);
+export { KitIdempotencyModule };

package/dist/idempotency/peer.d.ts

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

package/dist/idempotency/peer.js

@@ -0,0 +1,4 @@
+// Первым импортом index.ts: без pg — текст AC-1.2 с /idempotency, раньше загрузки /database (prd.md §3.3а, NFR-3).
+// Проверка синхронная, без top-level await: схему сервиса грузит drizzle-kit через require (ARCHITECTURE.md, П15).
+import { requirePeer } from '../internal/peer.js';
+requirePeer('pg', 'idempotency');