@nage-api/core 1.0.0-beta.2

package/dist/http/response.interceptor.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * 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.
+ */
+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.ResponseInterceptor = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const operators_1 = require("rxjs/operators");
+const constants_js_1 = require("../constants.js");
+const request_context_service_js_1 = require("../context/request-context.service.js");
+const envelope_js_1 = require("./envelope.js");
+let ResponseInterceptor = class ResponseInterceptor {
+    reflector;
+    context;
+    constructor(reflector, context) {
+        this.reflector = reflector;
+        this.context = context;
+    }
+    intercept(context, next) {
+        // Only HTTP responses carry the envelope; websocket and microservice
+        // payloads have their own contracts.
+        if (context.getType() !== 'http')
+            return next.handle();
+        const noEnvelope = this.reflector.getAllAndOverride(constants_js_1.METADATA_KEYS.noEnvelope, [context.getHandler(), context.getClass()]);
+        if (noEnvelope === true)
+            return next.handle();
+        return next.handle().pipe((0, operators_1.map)((data) => this.#wrap(data)));
+    }
+    #wrap(data) {
+        const requestContext = this.context.get();
+        const requestId = requestContext?.requestId ?? 'unknown';
+        const version = requestContext?.apiVersion;
+        if ((0, envelope_js_1.isPaginated)(data)) {
+            return (0, envelope_js_1.successEnvelope)(data.records, {
+                requestId,
+                pagination: data.pagination,
+                ...(version === undefined ? {} : { version }),
+            });
+        }
+        // A handler that returns nothing (204, or a delete) still gets a body-shaped
+        // envelope with `data: null`, so clients can parse one shape unconditionally.
+        return (0, envelope_js_1.successEnvelope)(data === undefined ? null : data, {
+            requestId,
+            ...(version === undefined ? {} : { version }),
+        });
+    }
+};
+exports.ResponseInterceptor = ResponseInterceptor;
+exports.ResponseInterceptor = ResponseInterceptor = __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)),
+    __metadata("design:paramtypes", [core_1.Reflector,
+        request_context_service_js_1.RequestContextService])
+], ResponseInterceptor);
+//# sourceMappingURL=response.interceptor.js.map

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `@nage-api/core` — the small mandatory layer every application depends on
+ * (PLAN.md §7.2).
+ *
+ * Core depends on `@nage-api/contracts` and on nothing else: never on a feature
+ * package, never on a project entity. That direction is what the legacy
+ * `src/core` inverted, and it is enforced in CI.
+ */
+export type * from '@nage-api/contracts';
+export { NAGE_CORE_VERSION, NAGE_MIN_NODE_VERSION } from './version.js';
+export { DEFAULT_REDACTED_FIELDS, DEFAULT_REQUEST_TIMEOUT_MS, API_VERSION_HEADER, CORRELATION_ID_HEADER, DEFAULT_API_VERSION, METADATA_KEYS, REQUEST_ID_HEADER, REQUEST_ID_PATTERN, } from './constants.js';
+export { createToken, keyValueStoreToken, repositoryToken, NAGE_CONFIG, NAGE_LIFECYCLE, NAGE_LOGGER, NAGE_RATE_LIMIT_STORE, NAGE_REQUEST_CONTEXT, NAGE_UNIT_OF_WORK, type Token, } from './tokens.js';
+export { getActiveContext, runWithContext, setContextValue, type MutableRequestContext, } from './context/active-context.js';
+export { RequestContextService } from './context/request-context.service.js';
+export { RequestContextMiddleware, parseApiVersion, resolveRequestId, } from './context/request-context.middleware.js';
+export * from './errors/index.js';
+export { buildMeta, errorEnvelope, isPaginated, successEnvelope, type EnvelopeMetaInput, } from './http/envelope.js';
+export { NoEnvelope } from './http/no-envelope.decorator.js';
+export { ResponseInterceptor } from './http/response.interceptor.js';
+export { AllExceptionsFilter } from './http/all-exceptions.filter.js';
+export { RequestTimeoutInterceptor } from './http/request-timeout.interceptor.js';
+export { RequestTimeout, SkipRequestTimeout } from './http/request-timeout.decorators.js';
+export { Public, isPublicRoute } from './decorators/public.decorator.js';
+export { Owner, OptionalOwner } from './decorators/owner.decorator.js';
+export { BetweenVersions, ForVersion, FromVersion, TillVersion, versionSatisfies, type VersionRule, } from './decorators/version.decorators.js';
+export { ApiVersionGuard } from './guards/api-version.guard.js';
+export { createJob, emptyPage, paginate, type CreateJobInput } from './job/job.factory.js';
+export { JsonLogger } from './logging/json.logger.js';
+export { NestLoggerAdapter } from './logging/nest-logger.adapter.js';
+export * from './security/index.js';
+export { NageCoreModule, buildValidationPipe, type NageCoreModuleOptions, } from './module/core.module.js';
+export { bootstrap, createApplication, resolveCorsOptions, type ApplicationModule, type BootstrapOptions, } from './bootstrap/bootstrap.js';
+export { enableQueryDsl } from './bootstrap/query-parser.js';
+export { LifecycleState, processLifecycle, type LifecyclePhase } from './bootstrap/lifecycle.js';
+export { RequestDrain, requestDrainFor, registerRequestDrain, type DrainMiddleware, type DrainResponseLike, type RequestDrainOptions, } from './bootstrap/drain.js';
+export { installShutdown, shutdownHandleFor, registerShutdownHandle, type ClosableApplication, type ShutdownHandle, type ShutdownOptions, } from './bootstrap/shutdown.js';
+export { installProcessGuards, type DisposeProcessGuards, type FatalKind, type ProcessGuardOptions, } from './bootstrap/process-guards.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * `@nage-api/core` — the small mandatory layer every application depends on
+ * (PLAN.md §7.2).
+ *
+ * Core depends on `@nage-api/contracts` and on nothing else: never on a feature
+ * package, never on a project entity. That direction is what the legacy
+ * `src/core` inverted, and it is enforced in CI.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonLogger = exports.paginate = exports.emptyPage = exports.createJob = exports.ApiVersionGuard = exports.versionSatisfies = exports.TillVersion = exports.FromVersion = exports.ForVersion = exports.BetweenVersions = exports.OptionalOwner = exports.Owner = exports.isPublicRoute = exports.Public = exports.SkipRequestTimeout = exports.RequestTimeout = exports.RequestTimeoutInterceptor = exports.AllExceptionsFilter = exports.ResponseInterceptor = exports.NoEnvelope = exports.successEnvelope = exports.isPaginated = exports.errorEnvelope = exports.buildMeta = exports.resolveRequestId = exports.parseApiVersion = exports.RequestContextMiddleware = exports.RequestContextService = exports.setContextValue = exports.runWithContext = exports.getActiveContext = exports.NAGE_UNIT_OF_WORK = exports.NAGE_REQUEST_CONTEXT = exports.NAGE_RATE_LIMIT_STORE = exports.NAGE_LOGGER = exports.NAGE_LIFECYCLE = exports.NAGE_CONFIG = exports.repositoryToken = exports.keyValueStoreToken = exports.createToken = exports.REQUEST_ID_PATTERN = exports.REQUEST_ID_HEADER = exports.METADATA_KEYS = exports.DEFAULT_API_VERSION = exports.CORRELATION_ID_HEADER = exports.API_VERSION_HEADER = exports.DEFAULT_REQUEST_TIMEOUT_MS = exports.DEFAULT_REDACTED_FIELDS = exports.NAGE_MIN_NODE_VERSION = exports.NAGE_CORE_VERSION = void 0;
+exports.installProcessGuards = exports.registerShutdownHandle = exports.shutdownHandleFor = exports.installShutdown = exports.registerRequestDrain = exports.requestDrainFor = exports.RequestDrain = exports.processLifecycle = exports.LifecycleState = exports.enableQueryDsl = exports.resolveCorsOptions = exports.createApplication = exports.bootstrap = exports.buildValidationPipe = exports.NageCoreModule = exports.NestLoggerAdapter = void 0;
+var version_js_1 = require("./version.js");
+Object.defineProperty(exports, "NAGE_CORE_VERSION", { enumerable: true, get: function () { return version_js_1.NAGE_CORE_VERSION; } });
+Object.defineProperty(exports, "NAGE_MIN_NODE_VERSION", { enumerable: true, get: function () { return version_js_1.NAGE_MIN_NODE_VERSION; } });
+// Configuration surface consumed by bootstrap; the types themselves live in
+// @nage-api/contracts and are re-exported above. @nage-api/config produces a value.
+var constants_js_1 = require("./constants.js");
+Object.defineProperty(exports, "DEFAULT_REDACTED_FIELDS", { enumerable: true, get: function () { return constants_js_1.DEFAULT_REDACTED_FIELDS; } });
+Object.defineProperty(exports, "DEFAULT_REQUEST_TIMEOUT_MS", { enumerable: true, get: function () { return constants_js_1.DEFAULT_REQUEST_TIMEOUT_MS; } });
+Object.defineProperty(exports, "API_VERSION_HEADER", { enumerable: true, get: function () { return constants_js_1.API_VERSION_HEADER; } });
+Object.defineProperty(exports, "CORRELATION_ID_HEADER", { enumerable: true, get: function () { return constants_js_1.CORRELATION_ID_HEADER; } });
+Object.defineProperty(exports, "DEFAULT_API_VERSION", { enumerable: true, get: function () { return constants_js_1.DEFAULT_API_VERSION; } });
+Object.defineProperty(exports, "METADATA_KEYS", { enumerable: true, get: function () { return constants_js_1.METADATA_KEYS; } });
+Object.defineProperty(exports, "REQUEST_ID_HEADER", { enumerable: true, get: function () { return constants_js_1.REQUEST_ID_HEADER; } });
+Object.defineProperty(exports, "REQUEST_ID_PATTERN", { enumerable: true, get: function () { return constants_js_1.REQUEST_ID_PATTERN; } });
+// DI tokens — how feature packages collaborate without importing each other.
+var tokens_js_1 = require("./tokens.js");
+Object.defineProperty(exports, "createToken", { enumerable: true, get: function () { return tokens_js_1.createToken; } });
+Object.defineProperty(exports, "keyValueStoreToken", { enumerable: true, get: function () { return tokens_js_1.keyValueStoreToken; } });
+Object.defineProperty(exports, "repositoryToken", { enumerable: true, get: function () { return tokens_js_1.repositoryToken; } });
+Object.defineProperty(exports, "NAGE_CONFIG", { enumerable: true, get: function () { return tokens_js_1.NAGE_CONFIG; } });
+Object.defineProperty(exports, "NAGE_LIFECYCLE", { enumerable: true, get: function () { return tokens_js_1.NAGE_LIFECYCLE; } });
+Object.defineProperty(exports, "NAGE_LOGGER", { enumerable: true, get: function () { return tokens_js_1.NAGE_LOGGER; } });
+Object.defineProperty(exports, "NAGE_RATE_LIMIT_STORE", { enumerable: true, get: function () { return tokens_js_1.NAGE_RATE_LIMIT_STORE; } });
+Object.defineProperty(exports, "NAGE_REQUEST_CONTEXT", { enumerable: true, get: function () { return tokens_js_1.NAGE_REQUEST_CONTEXT; } });
+Object.defineProperty(exports, "NAGE_UNIT_OF_WORK", { enumerable: true, get: function () { return tokens_js_1.NAGE_UNIT_OF_WORK; } });
+// Request context (CLS).
+var active_context_js_1 = require("./context/active-context.js");
+Object.defineProperty(exports, "getActiveContext", { enumerable: true, get: function () { return active_context_js_1.getActiveContext; } });
+Object.defineProperty(exports, "runWithContext", { enumerable: true, get: function () { return active_context_js_1.runWithContext; } });
+Object.defineProperty(exports, "setContextValue", { enumerable: true, get: function () { return active_context_js_1.setContextValue; } });
+var request_context_service_js_1 = require("./context/request-context.service.js");
+Object.defineProperty(exports, "RequestContextService", { enumerable: true, get: function () { return request_context_service_js_1.RequestContextService; } });
+var request_context_middleware_js_1 = require("./context/request-context.middleware.js");
+Object.defineProperty(exports, "RequestContextMiddleware", { enumerable: true, get: function () { return request_context_middleware_js_1.RequestContextMiddleware; } });
+Object.defineProperty(exports, "parseApiVersion", { enumerable: true, get: function () { return request_context_middleware_js_1.parseApiVersion; } });
+Object.defineProperty(exports, "resolveRequestId", { enumerable: true, get: function () { return request_context_middleware_js_1.resolveRequestId; } });
+// Typed error catalog.
+__exportStar(require("./errors/index.js"), exports);
+// Response envelope, interceptor and exception filter.
+var envelope_js_1 = require("./http/envelope.js");
+Object.defineProperty(exports, "buildMeta", { enumerable: true, get: function () { return envelope_js_1.buildMeta; } });
+Object.defineProperty(exports, "errorEnvelope", { enumerable: true, get: function () { return envelope_js_1.errorEnvelope; } });
+Object.defineProperty(exports, "isPaginated", { enumerable: true, get: function () { return envelope_js_1.isPaginated; } });
+Object.defineProperty(exports, "successEnvelope", { enumerable: true, get: function () { return envelope_js_1.successEnvelope; } });
+var no_envelope_decorator_js_1 = require("./http/no-envelope.decorator.js");
+Object.defineProperty(exports, "NoEnvelope", { enumerable: true, get: function () { return no_envelope_decorator_js_1.NoEnvelope; } });
+var response_interceptor_js_1 = require("./http/response.interceptor.js");
+Object.defineProperty(exports, "ResponseInterceptor", { enumerable: true, get: function () { return response_interceptor_js_1.ResponseInterceptor; } });
+var all_exceptions_filter_js_1 = require("./http/all-exceptions.filter.js");
+Object.defineProperty(exports, "AllExceptionsFilter", { enumerable: true, get: function () { return all_exceptions_filter_js_1.AllExceptionsFilter; } });
+// Request timeout (§21): on by default, per-route overrides for the routes whose
+// duration is the caller's business.
+var request_timeout_interceptor_js_1 = require("./http/request-timeout.interceptor.js");
+Object.defineProperty(exports, "RequestTimeoutInterceptor", { enumerable: true, get: function () { return request_timeout_interceptor_js_1.RequestTimeoutInterceptor; } });
+var request_timeout_decorators_js_1 = require("./http/request-timeout.decorators.js");
+Object.defineProperty(exports, "RequestTimeout", { enumerable: true, get: function () { return request_timeout_decorators_js_1.RequestTimeout; } });
+Object.defineProperty(exports, "SkipRequestTimeout", { enumerable: true, get: function () { return request_timeout_decorators_js_1.SkipRequestTimeout; } });
+// Base decorators and guards.
+var public_decorator_js_1 = require("./decorators/public.decorator.js");
+Object.defineProperty(exports, "Public", { enumerable: true, get: function () { return public_decorator_js_1.Public; } });
+Object.defineProperty(exports, "isPublicRoute", { enumerable: true, get: function () { return public_decorator_js_1.isPublicRoute; } });
+var owner_decorator_js_1 = require("./decorators/owner.decorator.js");
+Object.defineProperty(exports, "Owner", { enumerable: true, get: function () { return owner_decorator_js_1.Owner; } });
+Object.defineProperty(exports, "OptionalOwner", { enumerable: true, get: function () { return owner_decorator_js_1.OptionalOwner; } });
+var version_decorators_js_1 = require("./decorators/version.decorators.js");
+Object.defineProperty(exports, "BetweenVersions", { enumerable: true, get: function () { return version_decorators_js_1.BetweenVersions; } });
+Object.defineProperty(exports, "ForVersion", { enumerable: true, get: function () { return version_decorators_js_1.ForVersion; } });
+Object.defineProperty(exports, "FromVersion", { enumerable: true, get: function () { return version_decorators_js_1.FromVersion; } });
+Object.defineProperty(exports, "TillVersion", { enumerable: true, get: function () { return version_decorators_js_1.TillVersion; } });
+Object.defineProperty(exports, "versionSatisfies", { enumerable: true, get: function () { return version_decorators_js_1.versionSatisfies; } });
+var api_version_guard_js_1 = require("./guards/api-version.guard.js");
+Object.defineProperty(exports, "ApiVersionGuard", { enumerable: true, get: function () { return api_version_guard_js_1.ApiVersionGuard; } });
+// Job / pagination helpers.
+var job_factory_js_1 = require("./job/job.factory.js");
+Object.defineProperty(exports, "createJob", { enumerable: true, get: function () { return job_factory_js_1.createJob; } });
+Object.defineProperty(exports, "emptyPage", { enumerable: true, get: function () { return job_factory_js_1.emptyPage; } });
+Object.defineProperty(exports, "paginate", { enumerable: true, get: function () { return job_factory_js_1.paginate; } });
+// Logging.
+var json_logger_js_1 = require("./logging/json.logger.js");
+Object.defineProperty(exports, "JsonLogger", { enumerable: true, get: function () { return json_logger_js_1.JsonLogger; } });
+var nest_logger_adapter_js_1 = require("./logging/nest-logger.adapter.js");
+Object.defineProperty(exports, "NestLoggerAdapter", { enumerable: true, get: function () { return nest_logger_adapter_js_1.NestLoggerAdapter; } });
+// Security baseline (§12): CSPRNG, redaction, TLS policy, throttling, audit.
+__exportStar(require("./security/index.js"), exports);
+// Module and bootstrap.
+var core_module_js_1 = require("./module/core.module.js");
+Object.defineProperty(exports, "NageCoreModule", { enumerable: true, get: function () { return core_module_js_1.NageCoreModule; } });
+Object.defineProperty(exports, "buildValidationPipe", { enumerable: true, get: function () { return core_module_js_1.buildValidationPipe; } });
+var bootstrap_js_1 = require("./bootstrap/bootstrap.js");
+Object.defineProperty(exports, "bootstrap", { enumerable: true, get: function () { return bootstrap_js_1.bootstrap; } });
+Object.defineProperty(exports, "createApplication", { enumerable: true, get: function () { return bootstrap_js_1.createApplication; } });
+Object.defineProperty(exports, "resolveCorsOptions", { enumerable: true, get: function () { return bootstrap_js_1.resolveCorsOptions; } });
+var query_parser_js_1 = require("./bootstrap/query-parser.js");
+Object.defineProperty(exports, "enableQueryDsl", { enumerable: true, get: function () { return query_parser_js_1.enableQueryDsl; } });
+// Production lifecycle (§21): ordered drain, readiness phase, fatal-error policy.
+var lifecycle_js_1 = require("./bootstrap/lifecycle.js");
+Object.defineProperty(exports, "LifecycleState", { enumerable: true, get: function () { return lifecycle_js_1.LifecycleState; } });
+Object.defineProperty(exports, "processLifecycle", { enumerable: true, get: function () { return lifecycle_js_1.processLifecycle; } });
+var drain_js_1 = require("./bootstrap/drain.js");
+Object.defineProperty(exports, "RequestDrain", { enumerable: true, get: function () { return drain_js_1.RequestDrain; } });
+Object.defineProperty(exports, "requestDrainFor", { enumerable: true, get: function () { return drain_js_1.requestDrainFor; } });
+Object.defineProperty(exports, "registerRequestDrain", { enumerable: true, get: function () { return drain_js_1.registerRequestDrain; } });
+var shutdown_js_1 = require("./bootstrap/shutdown.js");
+Object.defineProperty(exports, "installShutdown", { enumerable: true, get: function () { return shutdown_js_1.installShutdown; } });
+Object.defineProperty(exports, "shutdownHandleFor", { enumerable: true, get: function () { return shutdown_js_1.shutdownHandleFor; } });
+Object.defineProperty(exports, "registerShutdownHandle", { enumerable: true, get: function () { return shutdown_js_1.registerShutdownHandle; } });
+var process_guards_js_1 = require("./bootstrap/process-guards.js");
+Object.defineProperty(exports, "installProcessGuards", { enumerable: true, get: function () { return process_guards_js_1.installProcessGuards; } });
+//# sourceMappingURL=index.js.map

package/dist/job/job.factory.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Runtime helpers for the `Job` / `Paginated` contracts (PLAN.md §13, §14.1).
+ *
+ * The `Job` work unit and its lifecycle hooks are the legacy framework's best
+ * idea; what undercut them was `body: any` / `records: any[]`. `@nage-api/data`
+ * (Phase 5) builds every job through these helpers so a job is typed against its
+ * entity from the moment it is created.
+ */
+import type { DeepPartial, Job, JobAction, Paginated, PaginationMeta, RequestContext, UnknownRecord } from '@nage-api/contracts';
+export interface CreateJobInput<TEntity, TBody, TParams extends UnknownRecord> {
+    readonly action: JobAction;
+    readonly params?: TParams;
+    readonly query?: Job<TEntity, TBody, TParams>['query'];
+    readonly body?: TBody;
+    readonly id?: Job<TEntity, TBody, TParams>['id'];
+    readonly deleteMode?: Job<TEntity, TBody, TParams>['deleteMode'];
+    /** Defaults to the ambient request context. */
+    readonly context?: RequestContext;
+}
+/**
+ * Build a job, defaulting the owner and context from the active request — the
+ * reason audit columns and ownership scoping need no plumbing at call sites.
+ */
+export declare function createJob<TEntity, TBody = DeepPartial<TEntity>, TParams extends UnknownRecord = UnknownRecord>(input: CreateJobInput<TEntity, TBody, TParams>): Job<TEntity, TBody, TParams>;
+/** Assemble the standard page shape returned by every repository. */
+export declare function paginate<TEntity>(records: readonly TEntity[], pagination: PaginationMeta): Paginated<TEntity>;
+/** An empty page — the correct answer for a filtered query with no matches. */
+export declare function emptyPage<TEntity>(offset?: number, limit?: number): Paginated<TEntity>;
+//# sourceMappingURL=job.factory.d.ts.map

package/dist/job/job.factory.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Runtime helpers for the `Job` / `Paginated` contracts (PLAN.md §13, §14.1).
+ *
+ * The `Job` work unit and its lifecycle hooks are the legacy framework's best
+ * idea; what undercut them was `body: any` / `records: any[]`. `@nage-api/data`
+ * (Phase 5) builds every job through these helpers so a job is typed against its
+ * entity from the moment it is created.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createJob = createJob;
+exports.paginate = paginate;
+exports.emptyPage = emptyPage;
+const active_context_js_1 = require("../context/active-context.js");
+const catalog_js_1 = require("../errors/catalog.js");
+/**
+ * Build a job, defaulting the owner and context from the active request — the
+ * reason audit columns and ownership scoping need no plumbing at call sites.
+ */
+function createJob(input) {
+    const context = input.context ?? (0, active_context_js_1.getActiveContext)();
+    if (context === undefined) {
+        throw new catalog_js_1.InternalError({
+            detail: 'A job needs a request context',
+            meta: {
+                action: input.action,
+                hint: 'Create the job inside a request, or pass `context` explicitly for background work.',
+            },
+        });
+    }
+    return {
+        action: input.action,
+        params: input.params ?? {},
+        query: input.query ?? {},
+        body: input.body ?? {},
+        context,
+        ...(input.id === undefined ? {} : { id: input.id }),
+        ...(context.user === undefined ? {} : { owner: context.user }),
+        ...(input.deleteMode === undefined ? {} : { deleteMode: input.deleteMode }),
+    };
+}
+/** Assemble the standard page shape returned by every repository. */
+function paginate(records, pagination) {
+    return { records, pagination };
+}
+/** An empty page — the correct answer for a filtered query with no matches. */
+function emptyPage(offset = 0, limit = 0) {
+    return { records: [], pagination: { offset, limit, count: 0 } };
+}
+//# sourceMappingURL=job.factory.js.map

package/dist/logging/json.logger.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal structured logger (PLAN.md §18).
+ *
+ * Newline-delimited JSON to stdout, with the correlation id pulled from the
+ * ambient context so no caller has to remember to pass it, and configured
+ * fields redacted before anything is written. `@nage-api/observability` (Phase 8)
+ * replaces this with pino behind the same `LoggerPort` — nothing else changes.
+ */
+import type { LogFields, LoggerPort, NageCoreConfig } from '@nage-api/contracts';
+import { RequestContextService } from '../context/request-context.service.js';
+export declare class JsonLogger implements LoggerPort {
+    #private;
+    private readonly context?;
+    constructor(context?: RequestContextService | undefined, config?: NageCoreConfig);
+    trace(message: string, fields?: LogFields): void;
+    debug(message: string, fields?: LogFields): void;
+    info(message: string, fields?: LogFields): void;
+    warn(message: string, fields?: LogFields): void;
+    error(message: string, fields?: LogFields): void;
+    fatal(message: string, fields?: LogFields): void;
+    child(bindings: LogFields): LoggerPort;
+}
+//# sourceMappingURL=json.logger.d.ts.map

package/dist/logging/json.logger.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * Minimal structured logger (PLAN.md §18).
+ *
+ * Newline-delimited JSON to stdout, with the correlation id pulled from the
+ * ambient context so no caller has to remember to pass it, and configured
+ * fields redacted before anything is written. `@nage-api/observability` (Phase 8)
+ * replaces this with pino behind the same `LoggerPort` — nothing else changes.
+ */
+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 JsonLogger_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonLogger = void 0;
+const common_1 = require("@nestjs/common");
+const request_context_service_js_1 = require("../context/request-context.service.js");
+const redaction_js_1 = require("../security/redaction.js");
+const tokens_js_1 = require("../tokens.js");
+const LEVEL_ORDER = {
+    trace: 10,
+    debug: 20,
+    info: 30,
+    warn: 40,
+    error: 50,
+    fatal: 60,
+};
+let JsonLogger = JsonLogger_1 = class JsonLogger {
+    context;
+    #minimum;
+    #redacted;
+    #json;
+    #config;
+    /** Set only via `child()`; not a constructor parameter, which Nest would try to inject. */
+    #bindings = {};
+    constructor(context, config) {
+        this.context = context;
+        this.#minimum = LEVEL_ORDER[config?.logging?.level ?? 'info'];
+        this.#redacted = (0, redaction_js_1.redactionSet)(config?.logging?.redact ?? []);
+        this.#json = config?.logging?.json ?? config?.app.environment !== 'development';
+        this.#config = config;
+    }
+    trace(message, fields) {
+        this.#write('trace', message, fields);
+    }
+    debug(message, fields) {
+        this.#write('debug', message, fields);
+    }
+    info(message, fields) {
+        this.#write('info', message, fields);
+    }
+    warn(message, fields) {
+        this.#write('warn', message, fields);
+    }
+    error(message, fields) {
+        this.#write('error', message, fields);
+    }
+    fatal(message, fields) {
+        this.#write('fatal', message, fields);
+    }
+    child(bindings) {
+        const logger = new JsonLogger_1(this.context, this.#config);
+        logger.#bindings = { ...this.#bindings, ...bindings };
+        return logger;
+    }
+    #write(level, message, fields = {}) {
+        if (LEVEL_ORDER[level] < this.#minimum)
+            return;
+        const context = this.context?.get();
+        const scrubbed = (0, redaction_js_1.redact)(fields, this.#redacted);
+        const entry = {
+            level,
+            time: new Date().toISOString(),
+            message,
+            ...this.#bindings,
+            ...(context === undefined
+                ? {}
+                : {
+                    requestId: context.requestId,
+                    ...(context.user === undefined ? {} : { userId: context.user.id }),
+                    ...(context.tenantId === undefined ? {} : { tenantId: context.tenantId }),
+                }),
+            ...scrubbed,
+        };
+        // The pretty line gets the *scrubbed* fields, not the originals. It used to
+        // print `fields`, so `logging.json: false` — the documented setting for
+        // human-readable output, and the default outside production — wrote
+        // passwords and bearer tokens in clear.
+        const fallback = { level, time: entry.time, message };
+        const line = this.#json
+            ? safeStringify(entry, fallback)
+            : `${entry.time} ${level.toUpperCase().padEnd(5)} ${message} ${safeStringify(scrubbed, {})}`;
+        // Written directly rather than through console so the stream stays a single
+        // newline-delimited JSON document, exactly as a log shipper expects.
+        const stream = LEVEL_ORDER[level] >= LEVEL_ORDER.error ? process.stderr : process.stdout;
+        stream.write(`${line}\n`);
+    }
+};
+exports.JsonLogger = JsonLogger;
+exports.JsonLogger = JsonLogger = JsonLogger_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Optional)()),
+    __param(0, (0, common_1.Inject)(request_context_service_js_1.RequestContextService)),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(tokens_js_1.NAGE_CONFIG)),
+    __metadata("design:paramtypes", [request_context_service_js_1.RequestContextService, Object])
+], JsonLogger);
+/**
+ * A log call must never be the thing that fails a request.
+ *
+ * `redact` already replaces cycles, but a field can still carry a getter that
+ * throws or a `toJSON` that does, and `JSON.stringify` propagates both. The
+ * fallback keeps the level, time and message — what an operator needs in order
+ * to find the request — and records why the fields are missing.
+ */
+function safeStringify(entry, fallback) {
+    try {
+        return JSON.stringify(entry);
+    }
+    catch (error) {
+        return JSON.stringify({
+            ...fallback,
+            fieldsError: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+//# sourceMappingURL=json.logger.js.map

package/dist/logging/nest-logger.adapter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Bridges Nest's internal `LoggerService` onto our `LoggerPort` (PLAN.md §18).
+ *
+ * Without this, a process emits two log formats: Nest's coloured boot lines and
+ * the framework's JSON. One structured stream is the whole point — a log shipper
+ * should never have to parse two grammars from one stdout.
+ */
+import type { LoggerService } from '@nestjs/common';
+import type { LoggerPort } from '@nage-api/contracts';
+export declare class NestLoggerAdapter implements LoggerService {
+    private readonly logger;
+    constructor(logger: LoggerPort);
+    log(message: unknown, ...optional: unknown[]): void;
+    error(message: unknown, ...optional: unknown[]): void;
+    warn(message: unknown, ...optional: unknown[]): void;
+    debug(message: unknown, ...optional: unknown[]): void;
+    verbose(message: unknown, ...optional: unknown[]): void;
+    fatal(message: unknown, ...optional: unknown[]): void;
+}
+//# sourceMappingURL=nest-logger.adapter.d.ts.map

package/dist/logging/nest-logger.adapter.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Bridges Nest's internal `LoggerService` onto our `LoggerPort` (PLAN.md §18).
+ *
+ * Without this, a process emits two log formats: Nest's coloured boot lines and
+ * the framework's JSON. One structured stream is the whole point — a log shipper
+ * should never have to parse two grammars from one stdout.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NestLoggerAdapter = void 0;
+function fields(context, extra = {}) {
+    return typeof context === 'string' ? { context, ...extra } : extra;
+}
+function messageOf(message) {
+    return typeof message === 'string' ? message : JSON.stringify(message);
+}
+class NestLoggerAdapter {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    log(message, ...optional) {
+        this.logger.info(messageOf(message), fields(optional[0]));
+    }
+    error(message, ...optional) {
+        const [trace, context] = optional;
+        this.logger.error(messageOf(message), {
+            ...fields(context ?? trace),
+            ...(typeof trace === 'string' ? { stack: trace } : {}),
+        });
+    }
+    warn(message, ...optional) {
+        this.logger.warn(messageOf(message), fields(optional[0]));
+    }
+    debug(message, ...optional) {
+        this.logger.debug(messageOf(message), fields(optional[0]));
+    }
+    verbose(message, ...optional) {
+        this.logger.trace(messageOf(message), fields(optional[0]));
+    }
+    fatal(message, ...optional) {
+        this.logger.fatal(messageOf(message), fields(optional[0]));
+    }
+}
+exports.NestLoggerAdapter = NestLoggerAdapter;
+//# sourceMappingURL=nest-logger.adapter.js.map

package/dist/module/core.module.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `NageCoreModule.forRoot(config)` — the one module every application imports
+ * (PLAN.md §7.3).
+ *
+ * Registering the interceptor, filter and guard as providers (rather than
+ * `app.useGlobal*`) keeps them inside the DI container, so they can inject the
+ * context and the logger, and so tests get the same wiring as production.
+ */
+import { ValidationPipe, type DynamicModule, type MiddlewareConsumer, type NestModule } from '@nestjs/common';
+import type { NageCoreConfig, RateLimitStore } from '@nage-api/contracts';
+/**
+ * Validation defaults (§16.2). `forbidNonWhitelisted` means an unexpected
+ * property is an error rather than something silently dropped — a mass-assignment
+ * guard, not a style preference.
+ */
+export declare function buildValidationPipe(config: NageCoreConfig): ValidationPipe;
+/**
+ * Wiring that is a decision rather than configuration, so it does not belong in
+ * `NageCoreConfig` — a `NageCoreConfig` is data, loadable from a file or an
+ * environment, and a store is an object with a connection.
+ */
+export interface NageCoreModuleOptions {
+    /**
+     * Counter store behind the global throttle (§12). Defaults to
+     * `MemoryRateLimitStore`, which counts **per process** — so with the default,
+     * a limit of N across M instances is really N×M. A multi-instance deployment
+     * passes a shared implementation here.
+     *
+     * Supplying it from the application module instead does not work and is worth
+     * saying explicitly: `forRoot` binds `NAGE_RATE_LIMIT_STORE` inside this
+     * module, and `RateLimitGuard` resolves it from this module's injector, so an
+     * app-level provider for the same token is simply not the one the guard sees.
+     */
+    readonly rateLimitStore?: RateLimitStore;
+}
+export declare class NageCoreModule implements NestModule {
+    static forRoot(config: NageCoreConfig, options?: NageCoreModuleOptions): DynamicModule;
+    configure(consumer: MiddlewareConsumer): void;
+}
+//# sourceMappingURL=core.module.d.ts.map