@nage-api/contracts 1.0.0-beta.2

package/dist/config.types.d.ts

@@ -0,0 +1,314 @@
+/**
+ * The typed configuration surface (PLAN.md §11).
+ *
+ * These live in `@nage-api/contracts`, not in `@nage-api/config`, for a layering reason:
+ * a feature package needs to read the shape of *its own* config block, and
+ * feature packages may not import each other. Types at the bottom of the graph
+ * are readable by everyone; `@nage-api/config` owns the runtime that produces and
+ * validates a value of this shape.
+ *
+ * Every default implied here is the safe one (§12): CORS is off until an
+ * allow-list is given, TLS verification is full, and features are disabled until
+ * switched on.
+ */
+export type NodeEnvironment = 'development' | 'test' | 'staging' | 'production';
+/**
+ * Cross-origin policy. `origins` is an explicit allow-list; the literal `'*'` is
+ * accepted but must be written out, and is refused in production.
+ */
+export interface CorsConfig {
+    readonly origins: readonly string[] | '*';
+    readonly credentials?: boolean;
+    readonly methods?: readonly string[];
+    readonly allowedHeaders?: readonly string[];
+    readonly exposedHeaders?: readonly string[];
+    readonly maxAge?: number;
+}
+export interface HelmetConfig {
+    readonly enabled?: boolean;
+    /** Content-Security-Policy. Disable only for routes serving Swagger UI. */
+    readonly contentSecurityPolicy?: boolean;
+    /** HSTS is forced on in production regardless of this flag. */
+    readonly hsts?: boolean;
+    readonly crossOriginResourcePolicy?: 'same-origin' | 'same-site' | 'cross-origin';
+}
+export interface HttpConfig {
+    /** Omit to disable CORS entirely — the safe default. */
+    readonly cors?: CorsConfig;
+    readonly helmet?: HelmetConfig;
+    readonly compression?: boolean;
+    readonly bodyLimit?: string;
+    /** Number of reverse proxies to trust, or `false`. Affects the client IP. */
+    readonly trustProxy?: number | boolean;
+    /**
+     * Ceiling on how long a handler may take before the caller is answered 504
+     * (§21). Defaults to 30 seconds; `0` removes the ceiling, which means one
+     * wedged dependency can hold connections until the clients give up.
+     */
+    readonly requestTimeoutMs?: number;
+}
+export interface VersioningConfig {
+    readonly enabled?: boolean;
+    /** Defaults to `x-application-version`, retained from the legacy framework. */
+    readonly header?: string;
+    readonly defaultVersion?: number;
+    /** Lowest version the API still serves; older requests are refused. */
+    readonly minVersion?: number;
+}
+export interface ValidationConfig {
+    readonly enabled?: boolean;
+    readonly whitelist?: boolean;
+    readonly forbidNonWhitelisted?: boolean;
+    readonly transform?: boolean;
+}
+/**
+ * Global request throttling (§12). The legacy framework imported a throttler but
+ * never registered a guard, so nothing was actually limited — here it is on by
+ * default and switching it off is a `doctor` finding.
+ */
+export interface RateLimitConfig extends FeatureToggle {
+    /** Requests permitted per window, per caller. */
+    readonly limit?: number;
+    /** Window length in milliseconds. */
+    readonly windowMs?: number;
+    /** Paths excluded from the global limit, e.g. `/health/live`. */
+    readonly excludePaths?: readonly string[];
+    /** Count authenticated callers per user rather than per IP. */
+    readonly perUser?: boolean;
+}
+export interface SecurityConfig {
+    readonly rateLimit?: RateLimitConfig;
+    /**
+     * Refuse to boot when the configuration contains a critical finding. On by
+     * default in production and staging (§21).
+     */
+    readonly assertOnBoot?: boolean;
+}
+/**
+ * Graceful shutdown (§21).
+ *
+ * The three deadlines exist because each stage can be held up by a different
+ * party: the load balancer (`readinessDelayMs`), a slow handler
+ * (`drainTimeoutMs`), and a module whose `close()` never returns
+ * (`forceExitAfterMs`). A single timeout would let the slowest one consume the
+ * whole budget and leave the container to be `SIGKILL`ed mid-write.
+ */
+export interface ShutdownConfig {
+    /** Registers `SIGTERM`/`SIGINT` hooks so pools drain before exit (§21). */
+    readonly enabled?: boolean;
+    /**
+     * Time to keep serving after readiness starts failing, before the listener
+     * closes. Orchestrator endpoint removal is asynchronous, so a pod that stops
+     * listening the instant it is signalled refuses requests that were routed to
+     * it a moment earlier. Defaults to 0 — set it to your readiness period plus a
+     * margin (typically 5000) behind a load balancer.
+     */
+    readonly readinessDelayMs?: number;
+    /** How long in-flight requests may take to finish. Defaults to 10 seconds. */
+    readonly drainTimeoutMs?: number;
+    /**
+     * Hard deadline for the whole sequence. On expiry the process exits non-zero
+     * rather than waiting for a hook that will never return. Defaults to 30
+     * seconds — keep it below the orchestrator's `terminationGracePeriodSeconds`,
+     * or the `SIGKILL` arrives first and the deadline never applies.
+     */
+    readonly forceExitAfterMs?: number;
+}
+export interface AppConfig {
+    readonly name: string;
+    readonly environment: NodeEnvironment;
+    readonly port?: number;
+    readonly host?: string;
+    readonly globalPrefix?: string;
+    /** Current API version served by this deployment. */
+    readonly version?: number;
+}
+export interface LoggingConfig {
+    readonly level?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+    /** Field names redacted from every log line (§18). */
+    readonly redact?: readonly string[];
+    /** Emit newline-delimited JSON. Off means human-readable lines for dev. */
+    readonly json?: boolean;
+}
+/** What `@nage-api/core` needs in order to boot an application. */
+export interface NageCoreConfig {
+    readonly app: AppConfig;
+    readonly http?: HttpConfig;
+    readonly versioning?: VersioningConfig;
+    readonly validation?: ValidationConfig;
+    readonly shutdown?: ShutdownConfig;
+    readonly logging?: LoggingConfig;
+    readonly security?: SecurityConfig;
+}
+/** Every optional feature is off until it is switched on. */
+export interface FeatureToggle {
+    readonly enabled?: boolean;
+}
+export type SqlDialect = 'postgres' | 'mysql' | 'mariadb' | 'sqlite';
+export type DatabaseDriver = SqlDialect | 'mongodb';
+/**
+ * TLS mode for the database connection. `no-verify` exists so that disabling
+ * certificate validation is a deliberate, greppable choice — the legacy
+ * `rejectUnauthorized: false` was neither (§12).
+ */
+export type TlsMode = 'disable' | 'require' | 'verify-full' | 'no-verify';
+export interface PoolConfig {
+    readonly min?: number;
+    readonly max?: number;
+    readonly idleTimeoutMs?: number;
+    readonly acquireTimeoutMs?: number;
+}
+export interface DatabaseConfig extends FeatureToggle {
+    /** One driver per workspace; the other is never installed (§14.1). */
+    readonly driver: DatabaseDriver;
+    readonly url?: string;
+    readonly host?: string;
+    readonly port?: number;
+    readonly database?: string;
+    readonly username?: string;
+    readonly schema?: string;
+    readonly pool?: PoolConfig;
+    readonly ssl?: TlsMode;
+    readonly migrations?: {
+        readonly directory?: string;
+        readonly table?: string;
+        /** Run pending migrations on boot. Off in production by default (§21). */
+        readonly runOnBoot?: boolean;
+    };
+    readonly seeds?: {
+        readonly directory?: string;
+    };
+    /** Hard ceiling applied to every model's query policy (§12). */
+    readonly maxQueryLimit?: number;
+}
+export interface JwtConfig {
+    /** RS256 by default — asymmetric, so verifiers never hold a signing key. */
+    readonly algorithm?: 'RS256' | 'RS512' | 'ES256' | 'HS256';
+    readonly accessTtl?: string;
+    readonly issuer: string;
+    readonly audience?: string | readonly string[];
+    /** Key id published in the JWT header, so keys can be rotated. */
+    readonly keyId?: string;
+}
+export interface RefreshTokenConfig {
+    readonly ttl?: string;
+    readonly rotate?: boolean;
+    readonly reuseDetection?: boolean;
+}
+export interface PasswordPolicyConfig {
+    readonly algorithm?: 'argon2id' | 'bcrypt';
+    readonly minLength?: number;
+    readonly requireMixedCase?: boolean;
+    readonly requireNumber?: boolean;
+    readonly requireSymbol?: boolean;
+    /** Check candidates against a breached-password list. */
+    readonly breachCheck?: boolean;
+}
+export interface OtpConfig {
+    readonly length?: number;
+    readonly ttl?: string;
+    readonly maxAttempts?: number;
+    readonly resendCooldown?: string;
+}
+export interface LockoutConfig {
+    readonly maxAttempts?: number;
+    readonly window?: string;
+    readonly duration?: string;
+}
+export interface AuthConfig extends FeatureToggle {
+    readonly strategy?: 'jwt';
+    readonly jwt?: JwtConfig;
+    readonly refresh?: RefreshTokenConfig;
+    readonly password?: PasswordPolicyConfig;
+    readonly otp?: OtpConfig;
+    readonly lockout?: LockoutConfig;
+    readonly apiKeys?: FeatureToggle;
+}
+export interface CacheConfig extends FeatureToggle {
+    readonly driver?: 'memory' | 'redis' | 'two-tier';
+    readonly url?: string;
+    readonly ttl?: string;
+    readonly namespace?: string;
+}
+export interface QueueConfig extends FeatureToggle {
+    readonly driver?: 'bullmq';
+    readonly url?: string;
+    readonly prefix?: string;
+    readonly concurrency?: number;
+    /** Keep a durable record of each job run (the legacy `JobLog`). */
+    readonly jobLogs?: boolean;
+}
+export interface StorageConfig extends FeatureToggle {
+    readonly cdn?: 'local' | 's3' | 'azure';
+    readonly bucket?: string;
+    readonly region?: string;
+    readonly publicBaseUrl?: string;
+    readonly validation?: {
+        readonly maxSize?: string;
+        readonly mime?: readonly string[];
+        /** Verify the declared MIME type against the file's magic bytes (§12). */
+        readonly magicBytes?: boolean;
+    };
+}
+export interface RealtimeConfig extends FeatureToggle {
+    readonly adapter?: 'memory' | 'redis';
+    readonly url?: string;
+    readonly path?: string;
+}
+export interface NotifyConfig extends FeatureToggle {
+    readonly channels?: readonly ('email' | 'sms' | 'push')[];
+    readonly from?: string;
+    readonly templateDirectory?: string;
+}
+export interface ObservabilityConfig {
+    readonly logging?: 'json' | 'pino' | 'pretty';
+    readonly tracing?: FeatureToggle & {
+        readonly endpoint?: string;
+        readonly sampleRatio?: number;
+    };
+    readonly metrics?: FeatureToggle & {
+        readonly path?: string;
+    };
+    readonly sentry?: FeatureToggle & {
+        readonly dsn?: string;
+    };
+    readonly redact?: readonly string[];
+}
+/** Where secrets come from (§11.1 item 5). Never `nage.config.ts`. */
+export interface SecretsConfig {
+    readonly provider?: 'env' | 'aws' | 'vault';
+    /** Prefix applied to every lookup, e.g. `prod/my-app/`. */
+    readonly prefix?: string;
+    readonly region?: string;
+    /** Cache resolved secrets for this long; `0` disables caching. */
+    readonly cacheTtlSeconds?: number;
+}
+/**
+ * The complete configuration of an application: what core needs, plus one block
+ * per optional feature. `@nage-api/config`'s `defineConfig()` produces it.
+ */
+export interface NageConfig extends NageCoreConfig {
+    readonly database?: DatabaseConfig;
+    readonly auth?: AuthConfig;
+    readonly cache?: CacheConfig;
+    readonly queue?: QueueConfig;
+    readonly storage?: StorageConfig;
+    readonly realtime?: RealtimeConfig;
+    readonly notify?: NotifyConfig;
+    readonly observability?: ObservabilityConfig;
+    readonly secrets?: SecretsConfig;
+}
+/**
+ * Pluggable secret source (§11.1, §12). Implementations live in `@nage-api/config`;
+ * consumers depend on this port, so moving from env vars to AWS Secrets Manager
+ * or Vault is a configuration change, not a code change.
+ */
+export interface SecretProviderPort {
+    /** Identifier used in diagnostics, e.g. `env` or `aws-secrets-manager`. */
+    readonly provider: string;
+    /** Resolve a secret, or `null` when it is not set. */
+    get(name: string): Promise<string | null>;
+    /** Resolve a secret, or reject when it is missing. */
+    require(name: string): Promise<string>;
+}
+//# sourceMappingURL=config.types.d.ts.map

package/dist/config.types.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * The typed configuration surface (PLAN.md §11).
+ *
+ * These live in `@nage-api/contracts`, not in `@nage-api/config`, for a layering reason:
+ * a feature package needs to read the shape of *its own* config block, and
+ * feature packages may not import each other. Types at the bottom of the graph
+ * are readable by everyone; `@nage-api/config` owns the runtime that produces and
+ * validates a value of this shape.
+ *
+ * Every default implied here is the safe one (§12): CORS is off until an
+ * allow-list is given, TLS verification is full, and features are disabled until
+ * switched on.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=config.types.js.map

package/dist/context.types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Per-request context (PLAN.md §18).
+ *
+ * The legacy `ClsStore` was declared but never populated. Here the context is
+ * the carrier for the correlation id that must appear in every log line, every
+ * response envelope, and every queue job spawned from a request.
+ */
+import type { Id } from './common.types.js';
+import type { AuthUser, RoleName } from './auth.types.js';
+/** Correlation id accepted from `X-Request-Id` or generated with a CSPRNG. */
+export type RequestId = string;
+export interface RequestContext<TRole extends string = RoleName> {
+    readonly requestId: RequestId;
+    /** Upstream trace id when the caller is another service. */
+    readonly correlationId?: RequestId;
+    readonly user?: AuthUser<TRole>;
+    readonly tenantId?: Id;
+    readonly ip?: string;
+    readonly userAgent?: string;
+    /** Value of the `x-application-version` header (PLAN.md §16.2). */
+    readonly apiVersion?: number;
+    readonly locale?: string;
+    /** `Date.now()` at the start of the request; used for duration logging. */
+    readonly startedAt: number;
+}
+/** Read/write accessor over the ambient context, implemented in `@nage-api/core`. */
+export interface ContextStore<TRole extends string = RoleName> {
+    get(): RequestContext<TRole> | undefined;
+    /** Throws `INTERNAL_ERROR` when called outside a request scope. */
+    require(): RequestContext<TRole>;
+    run<TResult>(context: RequestContext<TRole>, fn: () => TResult): TResult;
+    set<TKey extends keyof RequestContext<TRole>>(key: TKey, value: RequestContext<TRole>[TKey]): void;
+}
+//# sourceMappingURL=context.types.d.ts.map

package/dist/context.types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Per-request context (PLAN.md §18).
+ *
+ * The legacy `ClsStore` was declared but never populated. Here the context is
+ * the carrier for the correlation id that must appear in every log line, every
+ * response envelope, and every queue job spawned from a request.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=context.types.js.map

package/dist/entity.types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Base entity shape (PLAN.md §14.2).
+ *
+ * Audit columns are populated from the request context (CLS) automatically, so
+ * services never set them by hand. Soft-delete semantics are unified across
+ * drivers: `deleted_at` is the single source of truth, `deleted` is derived.
+ */
+import type { Id, IsoDateString } from './common.types.js';
+/** Who/when a record was created and last changed. */
+export interface AuditFields {
+    readonly created_at: IsoDateString;
+    readonly updated_at: IsoDateString;
+    readonly created_by?: Id | null;
+    readonly updated_by?: Id | null;
+}
+/** Soft-delete marker. A driver must exclude these rows unless `withDeleted`. */
+export interface SoftDeleteFields {
+    readonly deleted_at?: IsoDateString | null;
+    readonly deleted_by?: Id | null;
+}
+/** Optimistic locking (opt-in per model). */
+export interface VersionFields {
+    readonly version: number;
+}
+/** Every framework-managed entity carries an id plus audit and delete markers. */
+export interface BaseEntity extends AuditFields, SoftDeleteFields {
+    readonly id: Id;
+}
+/** Fields the framework owns; project code must never write them directly. */
+export type ManagedFields = keyof AuditFields | keyof SoftDeleteFields | 'id' | 'version';
+/** The writable surface of an entity — what a create/update DTO may contain. */
+export type Writable<TEntity> = Omit<TEntity, ManagedFields & keyof TEntity>;
+/** Soft vs hard delete (PLAN.md §14.1). */
+export type DeleteMode = 'soft' | 'hard';
+/** Model-level metadata a repository needs at runtime. */
+export interface ModelDescriptor<TEntity> {
+    readonly name: string;
+    readonly primaryKey: Extract<keyof TEntity, string>;
+    readonly softDelete: boolean;
+    readonly timestamps: boolean;
+    readonly versioned: boolean;
+}
+//# sourceMappingURL=entity.types.d.ts.map

package/dist/entity.types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Base entity shape (PLAN.md §14.2).
+ *
+ * Audit columns are populated from the request context (CLS) automatically, so
+ * services never set them by hand. Soft-delete semantics are unified across
+ * drivers: `deleted_at` is the single source of truth, `deleted` is derived.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=entity.types.js.map

package/dist/error.types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Stable, machine-readable error codes (PLAN.md §17).
+ *
+ * Clients program against the **code**, never the message. Messages are
+ * client-safe strings; internal detail (stack, SQL, upstream body) is logged
+ * against the request id and never serialized to the client.
+ */
+import type { UnknownRecord } from './common.types.js';
+/** Input the caller sent is malformed or fails validation. */
+export type ValidationErrorCode = 'VALIDATION_FAILED' | 'INVALID_QUERY' | 'QUERY_LIMIT_EXCEEDED'
+/** The request body exceeded `http.bodyLimit`. */
+ | 'PAYLOAD_TOO_LARGE';
+/** The caller could not be identified. */
+export type AuthenticationErrorCode = 'AUTH_INVALID_CREDENTIALS' | 'AUTH_TOKEN_EXPIRED' | 'AUTH_TOKEN_INVALID' | 'AUTH_TOKEN_REUSED' | 'AUTH_SESSION_REVOKED' | 'AUTH_ACCOUNT_LOCKED' | 'AUTH_OTP_INVALID' | 'AUTH_OTP_EXPIRED' | 'AUTH_REQUIRED';
+/** The caller is known but not allowed. */
+export type AuthorizationErrorCode = 'FORBIDDEN' | 'INSUFFICIENT_ROLE' | 'INSUFFICIENT_PERMISSION' | 'POLICY_DENIED';
+/** Resource lifecycle problems. */
+export type ResourceErrorCode = 'RESOURCE_NOT_FOUND' | 'RESOURCE_CONFLICT' | 'RESOURCE_GONE' | 'OPTIMISTIC_LOCK_CONFLICT';
+/** Infrastructure and upstream failures. */
+export type InfrastructureErrorCode = 'RATE_LIMIT_EXCEEDED' | 'REQUEST_TIMEOUT' | 'EXTERNAL_SERVICE_ERROR' | 'DATABASE_ERROR' | 'TRANSACTION_FAILED' | 'CONFIGURATION_INVALID' | 'UNSUPPORTED_OPERATION' | 'INTERNAL_ERROR';
+/** Business-rule violations raised by application code. */
+export type DomainErrorCode = 'DOMAIN_RULE_VIOLATED' | 'PRECONDITION_FAILED';
+/** The complete, closed catalog of error codes the framework can emit. */
+export type ErrorCode = ValidationErrorCode | AuthenticationErrorCode | AuthorizationErrorCode | ResourceErrorCode | InfrastructureErrorCode | DomainErrorCode;
+/** Per-field validation feedback, mirroring `class-validator` constraint maps. */
+export interface ErrorDetail {
+    /** Dot-path of the offending field, e.g. `address.postcode`. */
+    readonly field?: string;
+    /** Constraint name → human-readable message. */
+    readonly constraints?: Readonly<Record<string, string>>;
+    /** Free-form message when the problem is not field-scoped. */
+    readonly message?: string;
+}
+/** The `error` member of an error envelope (PLAN.md §16.1). */
+export interface ErrorPayload {
+    readonly code: ErrorCode;
+    /** Client-safe message. Never contains stack traces, SQL or upstream bodies. */
+    readonly message: string;
+    readonly details?: readonly ErrorDetail[];
+}
+/**
+ * Server-side-only error metadata. Logged with the correlation id;
+ * **never** serialized into a response.
+ */
+export interface ErrorMetadata extends UnknownRecord {
+    readonly cause?: unknown;
+}
+/** Shape every framework error class satisfies (implemented in `@nage-api/core`). */
+export interface NageErrorLike {
+    readonly code: ErrorCode;
+    readonly httpStatus: number;
+    readonly safeMessage: string;
+    readonly meta?: ErrorMetadata;
+}
+//# sourceMappingURL=error.types.d.ts.map

package/dist/error.types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Stable, machine-readable error codes (PLAN.md §17).
+ *
+ * Clients program against the **code**, never the message. Messages are
+ * client-safe strings; internal detail (stack, SQL, upstream body) is logged
+ * against the request id and never serialized to the client.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=error.types.js.map

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@nage-api/contracts` — the bottom of the dependency graph (PLAN.md §7.2).
+ *
+ * Types only: no runtime code, no NestJS, no validation libraries. Every other
+ * `@nage-api/*` package and every generated app may import this; it imports nothing.
+ */
+export type * from './common.types.js';
+export type * from './config.types.js';
+export type * from './error.types.js';
+export type * from './pagination.types.js';
+export type * from './query.types.js';
+export type * from './entity.types.js';
+export type * from './auth.types.js';
+export type * from './context.types.js';
+export type * from './logger.types.js';
+export type * from './response.types.js';
+export type * from './security.types.js';
+export type * from './job.types.js';
+export type * from './repository.types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * `@nage-api/contracts` — the bottom of the dependency graph (PLAN.md §7.2).
+ *
+ * Types only: no runtime code, no NestJS, no validation libraries. Every other
+ * `@nage-api/*` package and every generated app may import this; it imports nothing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/job.types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The `Job` work unit (PLAN.md §13, §14.1).
+ *
+ * The legacy `Job` was the framework's best idea and its worst type: `body: any`,
+ * `records: any[]`, `payload: any` defeated the generic `ModelService<M>`.
+ * Here every member is typed against the entity it operates on.
+ */
+import type { DeepPartial, Id, UnknownRecord } from './common.types.js';
+import type { AuthUser, RoleName } from './auth.types.js';
+import type { Query } from './query.types.js';
+import type { RequestContext } from './context.types.js';
+import type { DeleteMode } from './entity.types.js';
+/** The lifecycle operation a job represents. */
+export type JobAction = 'findAll' | 'findOne' | 'findById' | 'count' | 'create' | 'update' | 'delete' | 'restore' | 'bulkCreate' | 'bulkUpdate' | 'bulkDelete';
+/**
+ * A unit of work handed to `ModelService` lifecycle hooks
+ * (`doBeforeCreate`, `doAfterFindAll`, …).
+ *
+ * @typeParam TEntity  the model the job operates on
+ * @typeParam TBody    the write payload (defaults to a partial entity)
+ * @typeParam TParams  route/DSL parameters supplied by the caller
+ */
+export interface Job<TEntity, TBody = DeepPartial<TEntity>, TParams extends UnknownRecord = UnknownRecord, TRole extends string = RoleName> {
+    readonly action: JobAction;
+    /** Route/path parameters and any non-DSL inputs. */
+    readonly params: TParams;
+    /** Parsed, validated and allow-listed query DSL. */
+    query: Query<TEntity>;
+    /** Validated request body for write actions. */
+    body: TBody;
+    /** Target record id for single-record actions. */
+    readonly id?: Id;
+    /** The authenticated caller; used by ownership-scoping hooks. */
+    readonly owner?: AuthUser<TRole>;
+    readonly context: RequestContext<TRole>;
+    readonly deleteMode?: DeleteMode;
+    /** Populated by the service after the data layer runs. */
+    record?: TEntity;
+    records?: TEntity[];
+    /** Total matching rows for list actions. */
+    count?: number;
+}
+/** A job whose result set is known to be loaded (post-hook narrowing). */
+export interface CompletedJob<TEntity, TBody = DeepPartial<TEntity>> extends Job<TEntity, TBody> {
+    readonly records: TEntity[];
+    readonly count: number;
+}
+/**
+ * Typed background-job contract for `@nage-api/queue` (PLAN.md §8).
+ * Publisher and consumer share this type, so payloads cannot drift.
+ */
+export interface QueueJob<TName extends string, TPayload> {
+    readonly name: TName;
+    readonly payload: TPayload;
+    /** Correlation id propagated from the request that enqueued the job. */
+    readonly requestId?: string;
+    readonly attempts?: number;
+    readonly scheduledAt?: number;
+}
+/** Registry mapping job names to payload types; consumers index into it. */
+export type QueueJobMap = Record<string, unknown>;
+/** Handler for one entry of a `QueueJobMap`. */
+export type QueueJobHandler<TMap extends QueueJobMap, TName extends keyof TMap & string> = (job: QueueJob<TName, TMap[TName]>) => Promise<void>;
+//# sourceMappingURL=job.types.d.ts.map

package/dist/job.types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * The `Job` work unit (PLAN.md §13, §14.1).
+ *
+ * The legacy `Job` was the framework's best idea and its worst type: `body: any`,
+ * `records: any[]`, `payload: any` defeated the generic `ModelService<M>`.
+ * Here every member is typed against the entity it operates on.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=job.types.js.map

package/dist/logger.types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Structured-logging port (PLAN.md §18).
+ *
+ * `@nage-api/core` ships a minimal JSON implementation so correlation ids reach
+ * stdout from day one; `@nage-api/observability` swaps in pino/OTel behind the same
+ * port without any caller changing.
+ */
+import type { UnknownRecord } from './common.types.js';
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/**
+ * Structured fields attached to a log line. The request id is added by the
+ * logger itself, so callers never have to remember it.
+ */
+export type LogFields = UnknownRecord;
+export interface LoggerPort {
+    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;
+    /** Derive a logger that adds `bindings` to every line (e.g. a module name). */
+    child(bindings: LogFields): LoggerPort;
+}
+//# sourceMappingURL=logger.types.d.ts.map

package/dist/logger.types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Structured-logging port (PLAN.md §18).
+ *
+ * `@nage-api/core` ships a minimal JSON implementation so correlation ids reach
+ * stdout from day one; `@nage-api/observability` swaps in pino/OTel behind the same
+ * port without any caller changing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=logger.types.js.map