@nage-api/core 1.0.0-beta.2

package/dist/guards/api-version.guard.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Enforces the version rules declared by `@ForVersion` and friends
+ * (PLAN.md §16.2).
+ *
+ * A route that does not apply to the requested version is reported as **not
+ * found**, not as a validation error: from the client's point of view that
+ * endpoint does not exist in the version it asked for.
+ */
+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); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiVersionGuard = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const constants_js_1 = require("../constants.js");
+const request_context_service_js_1 = require("../context/request-context.service.js");
+const catalog_js_1 = require("../errors/catalog.js");
+const version_decorators_js_1 = require("../decorators/version.decorators.js");
+const tokens_js_1 = require("../tokens.js");
+let ApiVersionGuard = class ApiVersionGuard {
+    reflector;
+    context;
+    config;
+    constructor(reflector, context, config) {
+        this.reflector = reflector;
+        this.context = context;
+        this.config = config;
+    }
+    canActivate(context) {
+        if (context.getType() !== 'http')
+            return true;
+        if (this.config.versioning?.enabled === false)
+            return true;
+        const requested = this.context.get()?.apiVersion ??
+            this.config.versioning?.defaultVersion ??
+            constants_js_1.DEFAULT_API_VERSION;
+        const minimum = this.config.versioning?.minVersion;
+        if (minimum !== undefined && requested < minimum) {
+            throw new catalog_js_1.NotFoundError({
+                meta: { reason: 'below-minimum-version', requested, minimum },
+            });
+        }
+        const rule = this.reflector.getAllAndOverride(constants_js_1.METADATA_KEYS.versionRule, [context.getHandler(), context.getClass()]);
+        // No rule means the route serves every version.
+        if (rule === undefined)
+            return true;
+        if (!(0, version_decorators_js_1.versionSatisfies)(rule, requested)) {
+            throw new catalog_js_1.NotFoundError({ meta: { reason: 'version-mismatch', requested, rule } });
+        }
+        return true;
+    }
+};
+exports.ApiVersionGuard = ApiVersionGuard;
+exports.ApiVersionGuard = ApiVersionGuard = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(core_1.Reflector)),
+    __param(1, (0, common_1.Inject)(request_context_service_js_1.RequestContextService)),
+    __param(2, (0, common_1.Inject)(tokens_js_1.NAGE_CONFIG)),
+    __metadata("design:paramtypes", [core_1.Reflector,
+        request_context_service_js_1.RequestContextService, Object])
+], ApiVersionGuard);
+//# sourceMappingURL=api-version.guard.js.map

package/dist/http/all-exceptions.filter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The single global exception filter (PLAN.md §17).
+ *
+ * Every thrown value — framework error, Nest `HttpException`, or an unexpected
+ * `TypeError` from a driver — leaves as the same error envelope. The client gets
+ * a stable code and a safe message; the stack, the SQL and the upstream body go
+ * to the log, keyed by the same request id the client received.
+ */
+import { type ArgumentsHost } from '@nestjs/common';
+import type { ExceptionFilter } from '@nestjs/common';
+import { HttpAdapterHost } from '@nestjs/core';
+import type { LoggerPort } from '@nage-api/contracts';
+import { RequestContextService } from '../context/request-context.service.js';
+import { NageError } from '../errors/nage.error.js';
+export declare class AllExceptionsFilter implements ExceptionFilter {
+    #private;
+    private readonly adapterHost;
+    private readonly context;
+    private readonly logger;
+    constructor(adapterHost: HttpAdapterHost, context: RequestContextService, logger: LoggerPort);
+    catch(exception: unknown, host: ArgumentsHost): void;
+}
+/** Re-exported so applications can narrow in their own filters. */
+export { NageError };
+//# sourceMappingURL=all-exceptions.filter.d.ts.map

package/dist/http/all-exceptions.filter.js

@@ -0,0 +1,256 @@
+"use strict";
+/**
+ * The single global exception filter (PLAN.md §17).
+ *
+ * Every thrown value — framework error, Nest `HttpException`, or an unexpected
+ * `TypeError` from a driver — leaves as the same error envelope. The client gets
+ * a stable code and a safe message; the stack, the SQL and the upstream body go
+ * to the log, keyed by the same request id the client received.
+ */
+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); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NageError = exports.AllExceptionsFilter = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const constants_js_1 = require("../constants.js");
+const request_context_service_js_1 = require("../context/request-context.service.js");
+const request_context_middleware_js_1 = require("../context/request-context.middleware.js");
+const catalog_js_1 = require("../errors/catalog.js");
+const nage_error_js_1 = require("../errors/nage.error.js");
+Object.defineProperty(exports, "NageError", { enumerable: true, get: function () { return nage_error_js_1.NageError; } });
+const redaction_js_1 = require("../security/redaction.js");
+const tokens_js_1 = require("../tokens.js");
+const envelope_js_1 = require("./envelope.js");
+/** Nest maps its own exceptions to statuses; we map statuses back to codes. */
+const CODE_BY_STATUS = {
+    [common_1.HttpStatus.BAD_REQUEST]: 'INVALID_QUERY',
+    [common_1.HttpStatus.UNAUTHORIZED]: 'AUTH_REQUIRED',
+    [common_1.HttpStatus.FORBIDDEN]: 'FORBIDDEN',
+    [common_1.HttpStatus.NOT_FOUND]: 'RESOURCE_NOT_FOUND',
+    [common_1.HttpStatus.PRECONDITION_FAILED]: 'PRECONDITION_FAILED',
+    [common_1.HttpStatus.CONFLICT]: 'RESOURCE_CONFLICT',
+    [common_1.HttpStatus.GONE]: 'RESOURCE_GONE',
+    [common_1.HttpStatus.PAYLOAD_TOO_LARGE]: 'PAYLOAD_TOO_LARGE',
+    [common_1.HttpStatus.UNPROCESSABLE_ENTITY]: 'VALIDATION_FAILED',
+    [common_1.HttpStatus.TOO_MANY_REQUESTS]: 'RATE_LIMIT_EXCEEDED',
+    [common_1.HttpStatus.NOT_IMPLEMENTED]: 'UNSUPPORTED_OPERATION',
+    [common_1.HttpStatus.BAD_GATEWAY]: 'EXTERNAL_SERVICE_ERROR',
+};
+/**
+ * The 4xx status a body-parser error carries, or `undefined` for anything else.
+ *
+ * `raw-body` and `body-parser` set `type` (`entity.too.large`,
+ * `entity.parse.failed`, `encoding.unsupported`) and a 4xx `status`/`statusCode`
+ * on an ordinary `Error`. Only 4xx is honoured, and only with a recognised
+ * `type`: an arbitrary object that happens to have a numeric `status` must not be
+ * able to choose the response status, which is how an internal failure gets
+ * reported to a client as its own fault.
+ */
+const BODY_PARSER_ERROR_TYPES = new Set([
+    'entity.too.large',
+    'entity.parse.failed',
+    'entity.verify.failed',
+    'request.aborted',
+    'request.size.invalid',
+    'stream.encoding.set',
+    'parameters.too.many',
+    'charset.unsupported',
+    'encoding.unsupported',
+]);
+function bodyParserStatus(exception) {
+    if (!(exception instanceof Error))
+        return undefined;
+    const { type, status, statusCode } = exception;
+    if (typeof type !== 'string' || !BODY_PARSER_ERROR_TYPES.has(type))
+        return undefined;
+    const candidate = typeof status === 'number' ? status : statusCode;
+    if (typeof candidate !== 'number' || candidate < 400 || candidate > 499)
+        return undefined;
+    return candidate;
+}
+/** The inbound correlation id, if the caller sent one. */
+function headerOf(request) {
+    const raw = request.headers?.[constants_js_1.REQUEST_ID_HEADER];
+    return Array.isArray(raw) ? raw[0] : raw;
+}
+/**
+ * `ValidationPipe` throws a `BadRequestException` whose body carries an array of
+ * messages. Lift those into `details` so clients get field-level feedback in the
+ * documented shape instead of a wall of prose.
+ */
+function toValidationDetails(response) {
+    if (response === null || typeof response !== 'object')
+        return undefined;
+    const message = response.message;
+    if (!Array.isArray(message))
+        return undefined;
+    const details = message
+        .filter((entry) => typeof entry === 'string')
+        .map((entry) => ({ message: entry }));
+    return details.length > 0 ? details : undefined;
+}
+/**
+ * Flatten an exception's `cause` chain into log text.
+ *
+ * `Error.stack` does not include the cause on V8, so logging the stack alone
+ * drops the driver's own message: a `DatabaseError` wrapping a unique-constraint
+ * violation would be logged as "insert failed" with no mention of which
+ * constraint. §17 promises the operator gets everything, and this is the part
+ * that is easiest to lose. Depth is bounded because a chain can be cyclic.
+ */
+function causeChain(exception, depth = 0) {
+    if (depth > 4 || !(exception instanceof Error))
+        return [];
+    const cause = exception.cause;
+    if (cause === undefined)
+        return [];
+    // An `Error` cause is flattened to text, since its own stack would double the
+    // length of the line for no new information. Anything else is kept as it is, so
+    // that `redact` still walks it and blanks a credential-named field inside.
+    const described = cause instanceof Error ? `${cause.name}: ${cause.message}` : cause;
+    return [described, ...causeChain(cause, depth + 1)];
+}
+let AllExceptionsFilter = class AllExceptionsFilter {
+    adapterHost;
+    context;
+    logger;
+    constructor(adapterHost, context, logger) {
+        this.adapterHost = adapterHost;
+        this.context = context;
+        this.logger = logger;
+    }
+    catch(exception, host) {
+        if (host.getType() !== 'http')
+            throw exception;
+        const normalized = this.#normalize(exception);
+        const requestContext = this.context.get();
+        const http = host.switchToHttp();
+        const request = http.getRequest();
+        // Normally the middleware has already settled this and everything from the
+        // guards onwards shares it. It has not on one path: body parsing runs before
+        // module middleware, so an oversized or malformed body is rejected with no
+        // context open — and §17 promises the client a failure it can quote back.
+        // `resolveRequestId` is the middleware's own function, so a caller-supplied
+        // id gets the same validation here as everywhere else rather than being
+        // echoed unchecked into a log line.
+        const requestId = requestContext?.requestId ?? (0, request_context_middleware_js_1.resolveRequestId)(headerOf(request));
+        // A token in the query string (as the legacy socket handshake used) would
+        // otherwise be written to the log on every failure.
+        this.#log(exception, normalized, { method: request.method, url: (0, redaction_js_1.redactUrl)(request.url) });
+        const body = (0, envelope_js_1.errorEnvelope)(normalized.payload, {
+            requestId,
+            ...(requestContext?.apiVersion === undefined ? {} : { version: requestContext.apiVersion }),
+        });
+        const { httpAdapter } = this.adapterHost;
+        const response = http.getResponse();
+        // The middleware sets this header on its way out; on the pre-middleware path
+        // nothing has, and an id in the body that is not in the headers is the one
+        // place a client's logging middleware would miss it.
+        if (requestContext === undefined) {
+            httpAdapter.setHeader(response, constants_js_1.REQUEST_ID_HEADER, requestId);
+        }
+        httpAdapter.reply(response, body, normalized.status);
+    }
+    #normalize(exception) {
+        if ((0, nage_error_js_1.isNageError)(exception)) {
+            return {
+                status: exception.httpStatus,
+                payload: exception.toPayload(),
+                logMeta: { ...exception.meta },
+            };
+        }
+        if (exception instanceof common_1.HttpException) {
+            const status = exception.getStatus();
+            const response = exception.getResponse();
+            const details = toValidationDetails(response);
+            const code = details === undefined
+                ? (CODE_BY_STATUS[status] ?? (status >= 500 ? 'INTERNAL_ERROR' : 'INVALID_QUERY'))
+                : 'VALIDATION_FAILED';
+            // A 5xx from Nest may carry an internal message; only sub-500 messages
+            // are considered safe to pass through.
+            const message = status >= 500
+                ? catalog_js_1.DEFAULT_SAFE_MESSAGE.INTERNAL_ERROR
+                : typeof response === 'string'
+                    ? response
+                    : response.message !== undefined &&
+                        typeof response.message === 'string'
+                        ? response.message
+                        : catalog_js_1.DEFAULT_SAFE_MESSAGE[code];
+            return {
+                status: details === undefined ? status : common_1.HttpStatus.UNPROCESSABLE_ENTITY,
+                payload: details === undefined
+                    ? { code, message }
+                    : { code, message: 'Validation failed', details },
+                logMeta: {},
+            };
+        }
+        // body-parser rejects an oversized or malformed body from middleware, before
+        // any handler exists to throw an `HttpException`. Its errors are plain
+        // `Error`s carrying `type` and `status`, so without this they fall through to
+        // the bug branch below and a client that sent 6 MB is told the server broke.
+        const parserStatus = bodyParserStatus(exception);
+        if (parserStatus !== undefined) {
+            const code = CODE_BY_STATUS[parserStatus] ?? 'INVALID_QUERY';
+            return {
+                status: parserStatus,
+                payload: { code, message: catalog_js_1.DEFAULT_SAFE_MESSAGE[code] },
+                // The declared limit and the length that breached it, for the operator
+                // only: a client that can discover the exact ceiling can size requests to
+                // sit just under it.
+                logMeta: {
+                    parserErrorType: exception.type,
+                    limit: exception.limit,
+                    length: exception.length,
+                },
+            };
+        }
+        // Anything else is a bug: nothing about it is safe to return.
+        return {
+            status: common_1.HttpStatus.INTERNAL_SERVER_ERROR,
+            payload: { code: 'INTERNAL_ERROR', message: catalog_js_1.DEFAULT_SAFE_MESSAGE.INTERNAL_ERROR },
+            logMeta: {},
+        };
+    }
+    #log(exception, normalized, request) {
+        const causes = causeChain(exception);
+        const fields = {
+            code: normalized.payload.code,
+            httpStatus: normalized.status,
+            method: request.method,
+            url: request.url,
+            ...normalized.logMeta,
+            ...(exception instanceof Error
+                ? { error: exception.name, detail: exception.message, stack: exception.stack }
+                : { error: 'UnknownException', detail: String(exception) }),
+            ...(causes.length === 0 ? {} : { causes }),
+        };
+        // 5xx is ours to fix; 4xx is the caller's mistake and only worth a warning.
+        if (normalized.status >= 500) {
+            this.logger.error('Request failed', fields);
+        }
+        else {
+            this.logger.warn('Request rejected', fields);
+        }
+    }
+};
+exports.AllExceptionsFilter = AllExceptionsFilter;
+exports.AllExceptionsFilter = AllExceptionsFilter = __decorate([
+    (0, common_1.Catch)(),
+    __param(0, (0, common_1.Inject)(core_1.HttpAdapterHost)),
+    __param(1, (0, common_1.Inject)(request_context_service_js_1.RequestContextService)),
+    __param(2, (0, common_1.Inject)(tokens_js_1.NAGE_LOGGER)),
+    __metadata("design:paramtypes", [core_1.HttpAdapterHost,
+        request_context_service_js_1.RequestContextService, Object])
+], AllExceptionsFilter);
+//# sourceMappingURL=all-exceptions.filter.js.map

package/dist/http/envelope.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Builders for the single API envelope (PLAN.md §16.1).
+ *
+ * One place constructs the success shape, one place constructs the error shape;
+ * the interceptor and the filter are thin wrappers around these. The legacy
+ * framework assembled the envelope by hand in 18 controllers.
+ */
+import type { ErrorPayload, ErrorResponse, Paginated, PaginationMeta, ResponseMeta, SuccessResponse } from '@nage-api/contracts';
+export interface EnvelopeMetaInput {
+    readonly requestId: string;
+    readonly version?: number;
+    readonly pagination?: PaginationMeta;
+    /** Injectable for deterministic tests; defaults to now. */
+    readonly timestamp?: string;
+}
+export declare function buildMeta(input: EnvelopeMetaInput): ResponseMeta;
+export declare function successEnvelope<TData>(data: TData, meta: EnvelopeMetaInput): SuccessResponse<TData>;
+export declare function errorEnvelope(error: ErrorPayload, meta: EnvelopeMetaInput): ErrorResponse;
+/**
+ * Recognise a repository page so the interceptor can lift `records` to `data`
+ * and `pagination` into `meta` — the client contract stays flat while services
+ * keep returning a single value.
+ */
+export declare function isPaginated(value: unknown): value is Paginated<unknown>;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/http/envelope.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Builders for the single API envelope (PLAN.md §16.1).
+ *
+ * One place constructs the success shape, one place constructs the error shape;
+ * the interceptor and the filter are thin wrappers around these. The legacy
+ * framework assembled the envelope by hand in 18 controllers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMeta = buildMeta;
+exports.successEnvelope = successEnvelope;
+exports.errorEnvelope = errorEnvelope;
+exports.isPaginated = isPaginated;
+function buildMeta(input) {
+    return {
+        requestId: input.requestId,
+        timestamp: input.timestamp ?? new Date().toISOString(),
+        ...(input.version === undefined ? {} : { version: input.version }),
+        ...(input.pagination === undefined ? {} : { pagination: input.pagination }),
+    };
+}
+function successEnvelope(data, meta) {
+    return { success: true, data, meta: buildMeta(meta) };
+}
+function errorEnvelope(error, meta) {
+    return { success: false, error, meta: buildMeta(meta) };
+}
+/**
+ * Recognise a repository page so the interceptor can lift `records` to `data`
+ * and `pagination` into `meta` — the client contract stays flat while services
+ * keep returning a single value.
+ */
+function isPaginated(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    if (!Array.isArray(candidate.records))
+        return false;
+    if (candidate.pagination === null || typeof candidate.pagination !== 'object')
+        return false;
+    const pagination = candidate.pagination;
+    return typeof pagination['limit'] === 'number';
+}
+//# sourceMappingURL=envelope.js.map

package/dist/http/no-envelope.decorator.d.ts

@@ -0,0 +1,11 @@
+import { type CustomDecorator } from '@nestjs/common';
+/**
+ * Opt a route out of the response envelope — file downloads, health probes
+ * consumed by an orchestrator, and third-party webhook callbacks that require
+ * an exact body shape.
+ *
+ * It is the only sanctioned escape hatch, which is what keeps the envelope a
+ * guarantee rather than a convention.
+ */
+export declare const NoEnvelope: () => CustomDecorator;
+//# sourceMappingURL=no-envelope.decorator.d.ts.map

package/dist/http/no-envelope.decorator.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoEnvelope = void 0;
+const common_1 = require("@nestjs/common");
+const constants_js_1 = require("../constants.js");
+/**
+ * Opt a route out of the response envelope — file downloads, health probes
+ * consumed by an orchestrator, and third-party webhook callbacks that require
+ * an exact body shape.
+ *
+ * It is the only sanctioned escape hatch, which is what keeps the envelope a
+ * guarantee rather than a convention.
+ */
+const NoEnvelope = () => (0, common_1.SetMetadata)(constants_js_1.METADATA_KEYS.noEnvelope, true);
+exports.NoEnvelope = NoEnvelope;
+//# sourceMappingURL=no-envelope.decorator.js.map

package/dist/http/request-timeout.decorators.d.ts

@@ -0,0 +1,23 @@
+import { type CustomDecorator } from '@nestjs/common';
+/**
+ * Give one route a different budget from the global one (§21).
+ *
+ * The routes that need it are the ones whose duration is the caller's business:
+ * a large upload, a report, a long poll.
+ *
+ * ```ts
+ * @RequestTimeout(120_000)
+ * @Post('reports/annual')
+ * ```
+ */
+export declare const RequestTimeout: (timeoutMs: number) => CustomDecorator;
+/**
+ * Remove the ceiling for one route — server-sent events and streaming
+ * downloads, where the response is meant to stay open.
+ *
+ * Prefer `RequestTimeout` with a generous value: "no ceiling" means a wedged
+ * dependency on this route holds its connection until the client gives up, and
+ * during a deploy it is what the drain waits for.
+ */
+export declare const SkipRequestTimeout: () => CustomDecorator;
+//# sourceMappingURL=request-timeout.decorators.d.ts.map

package/dist/http/request-timeout.decorators.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkipRequestTimeout = exports.RequestTimeout = void 0;
+const common_1 = require("@nestjs/common");
+const constants_js_1 = require("../constants.js");
+/**
+ * Give one route a different budget from the global one (§21).
+ *
+ * The routes that need it are the ones whose duration is the caller's business:
+ * a large upload, a report, a long poll.
+ *
+ * ```ts
+ * @RequestTimeout(120_000)
+ * @Post('reports/annual')
+ * ```
+ */
+const RequestTimeout = (timeoutMs) => (0, common_1.SetMetadata)(constants_js_1.METADATA_KEYS.requestTimeout, timeoutMs);
+exports.RequestTimeout = RequestTimeout;
+/**
+ * Remove the ceiling for one route — server-sent events and streaming
+ * downloads, where the response is meant to stay open.
+ *
+ * Prefer `RequestTimeout` with a generous value: "no ceiling" means a wedged
+ * dependency on this route holds its connection until the client gives up, and
+ * during a deploy it is what the drain waits for.
+ */
+const SkipRequestTimeout = () => (0, common_1.SetMetadata)(constants_js_1.METADATA_KEYS.requestTimeout, 0);
+exports.SkipRequestTimeout = SkipRequestTimeout;
+//# sourceMappingURL=request-timeout.decorators.js.map

package/dist/http/request-timeout.interceptor.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A ceiling on how long a request may take (PLAN.md §21).
+ *
+ * Before this there was none, at any layer: not in `bootstrap`, not in the
+ * config surface, not in Nest. A handler awaiting a dependency that never
+ * answers held its connection until the caller's own timeout fired, and until
+ * then it also held a rate-limit slot, an unfinished log line, and — during a
+ * deploy — a drain that could not complete.
+ *
+ * What this does **not** do, and cannot: cancel the handler. Node cannot abort a
+ * promise that is already running, so the work continues in the background after
+ * the caller has been answered 504. That is still the right trade — the client
+ * and the socket are released on a schedule the server controls — but it means
+ * this is not a substitute for a deadline on the dependency itself
+ * (`acquireTimeoutMs` on the pool, a timeout on the HTTP client). It bounds the
+ * caller's wait, not the process's work.
+ */
+import { type CallHandler, type ExecutionContext, type NestInterceptor } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import type { NageCoreConfig } from '@nage-api/contracts';
+import { type Observable } from 'rxjs';
+export declare class RequestTimeoutInterceptor implements NestInterceptor {
+    #private;
+    private readonly reflector;
+    constructor(reflector: Reflector, config: NageCoreConfig);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+//# sourceMappingURL=request-timeout.interceptor.d.ts.map

package/dist/http/request-timeout.interceptor.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * A ceiling on how long a request may take (PLAN.md §21).
+ *
+ * Before this there was none, at any layer: not in `bootstrap`, not in the
+ * config surface, not in Nest. A handler awaiting a dependency that never
+ * answers held its connection until the caller's own timeout fired, and until
+ * then it also held a rate-limit slot, an unfinished log line, and — during a
+ * deploy — a drain that could not complete.
+ *
+ * What this does **not** do, and cannot: cancel the handler. Node cannot abort a
+ * promise that is already running, so the work continues in the background after
+ * the caller has been answered 504. That is still the right trade — the client
+ * and the socket are released on a schedule the server controls — but it means
+ * this is not a substitute for a deadline on the dependency itself
+ * (`acquireTimeoutMs` on the pool, a timeout on the HTTP client). It bounds the
+ * caller's wait, not the process's work.
+ */
+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); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestTimeoutInterceptor = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const rxjs_1 = require("rxjs");
+const operators_1 = require("rxjs/operators");
+const constants_js_1 = require("../constants.js");
+const catalog_js_1 = require("../errors/catalog.js");
+const tokens_js_1 = require("../tokens.js");
+let RequestTimeoutInterceptor = class RequestTimeoutInterceptor {
+    reflector;
+    #timeoutMs;
+    constructor(reflector, config) {
+        this.reflector = reflector;
+        this.#timeoutMs = config.http?.requestTimeoutMs ?? constants_js_1.DEFAULT_REQUEST_TIMEOUT_MS;
+    }
+    intercept(context, next) {
+        // Only HTTP: a queue consumer's deadline is the job's, and a websocket
+        // handler has no request to time out.
+        if (context.getType() !== 'http')
+            return next.handle();
+        const ms = this.#resolve(context);
+        if (ms <= 0)
+            return next.handle();
+        return next.handle().pipe((0, operators_1.timeout)({
+            // `each`, not `first`: the budget is per emission, so a streaming
+            // response is not cut off for having taken a long time in total.
+            each: ms,
+            with: () => (0, rxjs_1.throwError)(() => new catalog_js_1.RequestTimeoutError(ms)),
+        }));
+    }
+    /** Route metadata wins over the class, and both win over configuration. */
+    #resolve(context) {
+        const override = this.reflector.getAllAndOverride(constants_js_1.METADATA_KEYS.requestTimeout, [context.getHandler(), context.getClass()]);
+        return typeof override === 'number' ? override : this.#timeoutMs;
+    }
+};
+exports.RequestTimeoutInterceptor = RequestTimeoutInterceptor;
+exports.RequestTimeoutInterceptor = RequestTimeoutInterceptor = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(core_1.Reflector)),
+    __param(1, (0, common_1.Inject)(tokens_js_1.NAGE_CONFIG)),
+    __metadata("design:paramtypes", [core_1.Reflector, Object])
+], RequestTimeoutInterceptor);
+//# sourceMappingURL=request-timeout.interceptor.js.map

package/dist/http/response.interceptor.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The single global response interceptor (PLAN.md §16.1).
+ *
+ * Controllers `return data`. This wraps it. Nothing in application code touches
+ * `res` — the `@Res()` escape hatch used by 18 legacy controllers bypassed the
+ * interceptor pipeline entirely and is what made the envelope inconsistent.
+ */
+import { type CallHandler, type ExecutionContext, type NestInterceptor } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import type { Observable } from 'rxjs';
+import { RequestContextService } from '../context/request-context.service.js';
+export declare class ResponseInterceptor implements NestInterceptor {
+    #private;
+    private readonly reflector;
+    private readonly context;
+    constructor(reflector: Reflector, context: RequestContextService);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}
+//# sourceMappingURL=response.interceptor.d.ts.map