@mettlecast/domain-runtime 0.2.21 → 0.2.23

package/dist/primitives/api.d.ts

@@ -35,7 +35,8 @@ export interface ApiDefinition extends ApiConfig {
 }
 /**
  * Register an API primitive with versioned handlers.
- * Validates that deprecated versions have a sunset date.
+ * Validates that deprecated versions have a sunset date and that input/output
+ * schemas are wrapped with `.default(...)` (the Zod v4 example-data pattern).
  * @throws {ZodError} if config is invalid
  */
 export declare function defineApi(config: ApiConfig): ApiDefinition;

package/dist/primitives/api.js

@@ -1,20 +1,40 @@
 import { z } from 'zod';
+// Native enum objects — Zod v4's recommended pattern over `z.enum([...])`.
+// Each `as const` object becomes the source of truth; `z.nativeEnum(...)`
+// derives the inferred string-literal union from the keys.
+const TenancyModeLiteral = { required: 'required', none: 'none', system: 'system' };
+const VersionStatusLiteral = { preview: 'preview', stable: 'stable', deprecated: 'deprecated', sunset: 'sunset' };
+const AuthTypeLiteral = { jwt: 'jwt', 'api-key': 'api-key', none: 'none' };
+const DeploymentTargetLiteral = { single: 'single', split: 'split' };
+/**
+ * Returns true when a Zod schema has been wrapped with `.default(...)` (Zod v4
+ * pattern). The wrapped schema exposes a `_def.typeName` of `ZodDefault`.
+ * `defineApi` requires every version's `input` and `output` to be wrapped this
+ * way so that the runtime has a concrete example payload for documentation and
+ * schema-publish tooling.
+ */
+const hasDefault = (schema) => {
+    if (typeof schema !== 'object' || schema === null)
+        return false;
+    const def = schema._def;
+    return def?.typeName === 'ZodDefault';
+};
 const ApiConfigSchema = z.object({
     id: z.string().min(1),
     path: z.string().startsWith('/'),
     method: z.string().optional(),
-    tenancy: z.enum(['required', 'none', 'system']),
+    tenancy: z.nativeEnum(TenancyModeLiteral),
     versions: z.record(z.string(), z.object({
-        status: z.enum(['preview', 'stable', 'deprecated', 'sunset']),
+        status: z.nativeEnum(VersionStatusLiteral),
         sunset: z.string().optional(),
-        input: z.unknown(),
-        output: z.unknown(),
+        input: z.unknown().refine(hasDefault, { message: 'input schema must have .default()' }),
+        output: z.unknown().refine(hasDefault, { message: 'output schema must have .default()' }),
         handler: z.function(),
-    }).refine(v => v.status !== 'deprecated' || v.sunset !== undefined, {
+    }).refine(v => v.status !== VersionStatusLiteral.deprecated || v.sunset !== undefined, {
         message: 'sunset date is required when status is deprecated',
     })),
     auth: z.object({
-        type: z.enum(['jwt', 'api-key', 'none']),
+        type: z.nativeEnum(AuthTypeLiteral),
         roles: z.array(z.string()).optional(),
     }).optional(),
     rateLimit: z.object({
@@ -22,7 +42,7 @@ const ApiConfigSchema = z.object({
         perApiKey: z.string().optional(),
         perIp: z.string().optional(),
     }).optional(),
-    deployment: z.object({ target: z.enum(['single', 'split']) }).passthrough().optional(),
+    deployment: z.object({ target: z.nativeEnum(DeploymentTargetLiteral) }).passthrough().optional(),
     observability: z.object({
         sloP99Ms: z.number().positive().optional(),
         alertOnErrorRate: z.number().min(0).max(1).optional(),
@@ -30,7 +50,8 @@ const ApiConfigSchema = z.object({
 }).refine(c => Object.keys(c.versions).length > 0, { message: 'at least one version required' });
 /**
  * Register an API primitive with versioned handlers.
- * Validates that deprecated versions have a sunset date.
+ * Validates that deprecated versions have a sunset date and that input/output
+ * schemas are wrapped with `.default(...)` (the Zod v4 example-data pattern).
  * @throws {ZodError} if config is invalid
  */
 export function defineApi(config) {

package/dist/runtime/fetch.d.ts

@@ -1,26 +1,14 @@
-import type { TibFetch } from '../ctx/comms.js';
-/** Options for the TibFetch factory. */
-export interface TibFetchOptions {
-    /** Maximum number of retry attempts on 5xx or network errors. Defaults to 3. */
-    maxRetries?: number;
-    /** Initial backoff delay in milliseconds. Doubles each retry. Defaults to 100. */
-    initialBackoffMs?: number;
-    /**
-     * Number of consecutive failures before the circuit opens (blocks requests).
-     * Defaults to 5.
-     */
-    circuitBreakerThreshold?: number;
-    /**
-     * How long the circuit stays open (ms) before allowing a probe request.
-     * Defaults to 30_000 (30 seconds).
-     */
-    circuitBreakerResetMs?: number;
-}
 /**
- * Creates an HTTP client with automatic retry (exponential backoff) and per-host
- * circuit breaker. Uses the Node.js 18+ global fetch API.
- * Retries on 5xx responses and network errors. Does not retry 4xx responses.
- * @param options - Configuration for retry and circuit breaker behaviour.
- * @returns A TibFetch instance.
+ * @deprecated Use `createKyClient` from './ky-client.js' instead.
+ *
+ * This module is preserved for backward compatibility with code that
+ * imported `createFetch` from the runtime barrel. The underlying
+ * implementation is now backed by `ky`; the hand-rolled retry and
+ * circuit breaker have been removed.
+ *
+ * Callers passing the legacy `TibFetchOptions` fields
+ * (`initialBackoffMs`, `circuitBreakerThreshold`, `circuitBreakerResetMs`)
+ * must drop those options — they are no longer supported.
  */
-export declare function createFetch(options?: TibFetchOptions): TibFetch;
+export { createKyClient as createFetch } from './ky-client.js';
+export type { KyFetchOptions as TibFetchOptions } from './ky-client.js';

package/dist/runtime/fetch.js

@@ -1,84 +1,13 @@
 /**
- * Creates an HTTP client with automatic retry (exponential backoff) and per-host
- * circuit breaker. Uses the Node.js 18+ global fetch API.
- * Retries on 5xx responses and network errors. Does not retry 4xx responses.
- * @param options - Configuration for retry and circuit breaker behaviour.
- * @returns A TibFetch instance.
+ * @deprecated Use `createKyClient` from './ky-client.js' instead.
+ *
+ * This module is preserved for backward compatibility with code that
+ * imported `createFetch` from the runtime barrel. The underlying
+ * implementation is now backed by `ky`; the hand-rolled retry and
+ * circuit breaker have been removed.
+ *
+ * Callers passing the legacy `TibFetchOptions` fields
+ * (`initialBackoffMs`, `circuitBreakerThreshold`, `circuitBreakerResetMs`)
+ * must drop those options — they are no longer supported.
  */
-export function createFetch(options = {}) {
-    const { maxRetries = 3, initialBackoffMs = 100, circuitBreakerThreshold = 5, circuitBreakerResetMs = 30_000, } = options;
-    const circuits = new Map();
-    function getHost(url) {
-        try {
-            return new URL(url).host;
-        }
-        catch {
-            return url;
-        }
-    }
-    function getCircuit(host) {
-        let c = circuits.get(host);
-        if (!c) {
-            c = { failures: 0, openedAt: null };
-            circuits.set(host, c);
-        }
-        return c;
-    }
-    function isOpen(circuit) {
-        if (circuit.openedAt === null)
-            return false;
-        // Half-open: allow probe after reset window.
-        if (Date.now() - circuit.openedAt >= circuitBreakerResetMs) {
-            circuit.openedAt = null; // Reset to half-open probe.
-            return false;
-        }
-        return true;
-    }
-    function recordSuccess(circuit) {
-        circuit.failures = 0;
-        circuit.openedAt = null;
-    }
-    function recordFailure(circuit) {
-        circuit.failures += 1;
-        if (circuit.failures >= circuitBreakerThreshold) {
-            circuit.openedAt = Date.now();
-        }
-    }
-    async function sleep(ms) {
-        return new Promise(resolve => setTimeout(resolve, ms));
-    }
-    return {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        async fetch(url, init) {
-            const host = getHost(url);
-            const circuit = getCircuit(host);
-            if (isOpen(circuit)) {
-                throw new Error(`Circuit open for host ${host} — too many consecutive failures`);
-            }
-            let lastErr;
-            for (let attempt = 0; attempt <= maxRetries; attempt++) {
-                try {
-                    const res = await globalThis.fetch(url, init);
-                    if (res.status >= 500) {
-                        recordFailure(circuit);
-                        if (attempt < maxRetries) {
-                            await sleep(initialBackoffMs * Math.pow(2, attempt));
-                            continue;
-                        }
-                        return res; // Return the 5xx response after exhausting retries.
-                    }
-                    recordSuccess(circuit);
-                    return res;
-                }
-                catch (err) {
-                    lastErr = err;
-                    recordFailure(circuit);
-                    if (attempt < maxRetries) {
-                        await sleep(initialBackoffMs * Math.pow(2, attempt));
-                    }
-                }
-            }
-            throw lastErr;
-        },
-    };
-}
+export { createKyClient as createFetch } from './ky-client.js';

package/dist/runtime/index.d.ts

@@ -1,9 +1,20 @@
 export { createLogger } from './logger.js';
-export { createTracer, noopTracer } from './tracer.js';
+export { createTracer, noopTracer, initOtel } from './tracer.js';
 export { createCache } from './cache.js';
+/**
+ * @deprecated Use `createKyClient` instead. The `createFetch` name is kept
+ * as a backward-compatible alias for callers that imported it before the
+ * migration to `ky`. New code should use `createKyClient` directly.
+ */
 export { createFetch } from './fetch.js';
 export type { TibFetchOptions } from './fetch.js';
+export { createKyClient } from './ky-client.js';
+export type { KyFetchOptions } from './ky-client.js';
 export { checkRateLimit, clearRateLimitBuckets } from './rate-limiter.js';
+export { ok, err, notFound } from '../types/result.js';
+export type { AppError, Result } from '../types/result.js';
+export { safeFetch, safeDb, wrapHandler, captureStack } from './typed-errors.js';
+export type { SafeResult } from './typed-errors.js';
 export { createSecrets, createEmptySecrets } from './secrets.js';
 export type { SecretsOptions } from './secrets.js';
 export { createIdempotency, createNoopIdempotency } from './idempotency.js';

package/dist/runtime/index.js

@@ -1,9 +1,20 @@
 // No-dep implementations
 export { createLogger } from './logger.js';
-export { createTracer, noopTracer } from './tracer.js';
+export { createTracer, noopTracer, initOtel } from './tracer.js';
 export { createCache } from './cache.js';
+/**
+ * @deprecated Use `createKyClient` instead. The `createFetch` name is kept
+ * as a backward-compatible alias for callers that imported it before the
+ * migration to `ky`. New code should use `createKyClient` directly.
+ */
 export { createFetch } from './fetch.js';
+export { createKyClient } from './ky-client.js';
 export { checkRateLimit, clearRateLimitBuckets } from './rate-limiter.js';
+// ── Typed error handling ────────────────────────────────────────────────────
+// Re-export Result types + adapters so domain handlers can import them from a
+// single barrel.  The full type definitions live in `../types/result.js`.
+export { ok, err, notFound } from '../types/result.js';
+export { safeFetch, safeDb, wrapHandler, captureStack } from './typed-errors.js';
 // AWS SDK implementations
 export { createSecrets, createEmptySecrets } from './secrets.js';
 export { createIdempotency, createNoopIdempotency } from './idempotency.js';

package/dist/runtime/ky-client.d.ts

@@ -0,0 +1,18 @@
+import type { TibFetch } from '../ctx/comms.js';
+/** Options for the ky-backed TibFetch factory. */
+export interface KyFetchOptions {
+    /** Maximum number of retry attempts on retriable status codes. Defaults to 3. */
+    maxRetries?: number;
+}
+/**
+ * Creates an HTTP client backed by ky with built-in retry on 503 and 429
+ * status codes. Replaces the hand-rolled retry + circuit breaker previously
+ * implemented in `createFetch`.
+ *
+ * Retries use ky's exponential backoff. The `beforeRetry` hook is wired up
+ * to allow future logging/metrics extensions without modifying the call site.
+ *
+ * @param options - Configuration for retry behaviour.
+ * @returns A TibFetch instance backed by ky.
+ */
+export declare function createKyClient(options?: KyFetchOptions): TibFetch;

package/dist/runtime/ky-client.js

@@ -0,0 +1,41 @@
+import ky from 'ky';
+/**
+ * Creates an HTTP client backed by ky with built-in retry on 503 and 429
+ * status codes. Replaces the hand-rolled retry + circuit breaker previously
+ * implemented in `createFetch`.
+ *
+ * Retries use ky's exponential backoff. The `beforeRetry` hook is wired up
+ * to allow future logging/metrics extensions without modifying the call site.
+ *
+ * @param options - Configuration for retry behaviour.
+ * @returns A TibFetch instance backed by ky.
+ */
+export function createKyClient(options = {}) {
+    const { maxRetries = 3 } = options;
+    const instance = ky.create({
+        retry: {
+            limit: maxRetries,
+            methods: ['get', 'post', 'put', 'patch', 'delete'],
+            statusCodes: [503, 429],
+        },
+        hooks: {
+            beforeRetry: [
+                async () => {
+                    // Placeholder hook for future logging/metrics. Ky performs the retry.
+                },
+            ],
+        },
+    });
+    return {
+        async fetch(url, init) {
+            // `RequestInit` (the public TibFetch signature) is a strict subset of
+            // ky's `Options`. The double-cast `as unknown as KyOptions` is the
+            // canonical TypeScript pattern for "I know these types are related but
+            // TS doesn't" — it forces a deliberate acknowledgement that the
+            // fields on `init` are a subset of what ky accepts, and is safer than
+            // a direct `as KyOptions` cast (which TS allows without the
+            // intermediate acknowledgement).
+            return instance(url, init);
+        },
+    };
+}

package/dist/runtime/query-parser.d.ts

@@ -6,32 +6,13 @@ export declare const ParsedQuerySchema: z.ZodObject<{
     limit: z.ZodDefault<z.ZodNumber>;
     sort: z.ZodDefault<z.ZodArray<z.ZodObject<{
         field: z.ZodString;
-        direction: z.ZodEnum<["asc", "desc"]>;
-    }, "strip", z.ZodTypeAny, {
-        field: string;
-        direction: "asc" | "desc";
-    }, {
-        field: string;
-        direction: "asc" | "desc";
-    }>, "many">>;
+        direction: z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>;
+    }, z.core.$strip>>>;
     filter: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
-}, "strip", z.ZodTypeAny, {
-    sort: {
-        field: string;
-        direction: "asc" | "desc";
-    }[];
-    filter: Record<string, string>;
-    limit: number;
-    cursor?: string | undefined;
-}, {
-    sort?: {
-        field: string;
-        direction: "asc" | "desc";
-    }[] | undefined;
-    filter?: Record<string, string> | undefined;
-    cursor?: string | undefined;
-    limit?: number | undefined;
-}>;
+}, z.core.$strip>;
 export type ParsedQuery = z.infer<typeof ParsedQuerySchema>;
 /**
  * Parses standard TIB list query parameters from a raw query string map.

package/dist/runtime/tracer.d.ts

@@ -11,3 +11,38 @@ export declare function createTracer(segmentName: string): Tracer;
  * `startSegment` calls `fn()` directly. `putAnnotation` is a no-op.
  */
 export declare const noopTracer: Tracer;
+/**
+ * Initialises OpenTelemetry tracing for the process.
+ *
+ * **Idempotent** — safe to call at module scope (top of a Lambda handler
+ * file) and safe to call repeatedly. The module-level `initialised` flag
+ * ensures only the first call has any effect.
+ *
+ * **Opt-in by design.** This function is NOT called automatically by the
+ * runtime; domain handler templates must call `initOtel()` at module
+ * scope if they want OTel-exported spans. The `tib doctor` gate
+ * (`checkOtelInitInLambdas`) enforces this convention by scanning
+ * `domains/.../api/-.ts` for an `initOtel(...)` call.
+ *
+ * Behaviour:
+ *  - When `OTEL_EXPORTER_OTLP_ENDPOINT` is set, attaches a
+ *    `BatchSpanProcessor` with an `OTLPTraceExporter` pointed at that
+ *    URL.
+ *  - Otherwise (no endpoint configured), attaches a `SimpleSpanProcessor`
+ *    with a `ConsoleSpanExporter` so spans are visible during local
+ *    development.
+ *  - Sampling is `TraceIdRatioBasedSampler` driven by
+ *    `OTEL TRACES_SAMPLER_ARG` (default `0.01` = 1%). Invalid values
+ *    fall back to the 1% default.
+ *  - The provider is registered globally via `provider.register()`,
+ *    which sets up the global tracer, context propagation, and (when
+ *    instrumentations are added) auto-instrumentation.
+ *
+ * **Auto-instrumentation caveat**: this initialiser does NOT install
+ * auto-instrumentations (HTTP, Express, etc.). If you need
+ * auto-instrumentation, add the relevant `@opentelemetry/instrumentation-*`
+ * packages and call `registerInstrumentations({ instrumentations: [...] })`
+ * after `initOtel()`. The basic tracer + context-propagation setup
+ * provided here works for manually-created spans.
+ */
+export declare function initOtel(): void;

package/dist/runtime/tracer.js

@@ -1,4 +1,11 @@
 import { Tracer as PowertoolsTracer } from '@aws-lambda-powertools/tracer';
+// OTel deps (`@opentelemetry/*`) are in packages/domain-runtime/package.json
+// (added in Wave 2 of the scaffolder modernization, issue #3831).
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { registerInstrumentations } from '@opentelemetry/instrumentation';
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { BatchSpanProcessor, ConsoleSpanExporter, SimpleSpanProcessor, TraceIdRatioBasedSampler, } from '@opentelemetry/sdk-trace-node';
 /**
  * Creates an AWS X-Ray compatible Tracer using Powertools Tracer.
  * Degrades gracefully when called outside a Lambda context (no active segment).
@@ -51,3 +58,71 @@ export const noopTracer = {
         // no-op
     },
 };
+let initialised = false;
+/**
+ * Initialises OpenTelemetry tracing for the process.
+ *
+ * **Idempotent** — safe to call at module scope (top of a Lambda handler
+ * file) and safe to call repeatedly. The module-level `initialised` flag
+ * ensures only the first call has any effect.
+ *
+ * **Opt-in by design.** This function is NOT called automatically by the
+ * runtime; domain handler templates must call `initOtel()` at module
+ * scope if they want OTel-exported spans. The `tib doctor` gate
+ * (`checkOtelInitInLambdas`) enforces this convention by scanning
+ * `domains/.../api/-.ts` for an `initOtel(...)` call.
+ *
+ * Behaviour:
+ *  - When `OTEL_EXPORTER_OTLP_ENDPOINT` is set, attaches a
+ *    `BatchSpanProcessor` with an `OTLPTraceExporter` pointed at that
+ *    URL.
+ *  - Otherwise (no endpoint configured), attaches a `SimpleSpanProcessor`
+ *    with a `ConsoleSpanExporter` so spans are visible during local
+ *    development.
+ *  - Sampling is `TraceIdRatioBasedSampler` driven by
+ *    `OTEL TRACES_SAMPLER_ARG` (default `0.01` = 1%). Invalid values
+ *    fall back to the 1% default.
+ *  - The provider is registered globally via `provider.register()`,
+ *    which sets up the global tracer, context propagation, and (when
+ *    instrumentations are added) auto-instrumentation.
+ *
+ * **Auto-instrumentation caveat**: this initialiser does NOT install
+ * auto-instrumentations (HTTP, Express, etc.). If you need
+ * auto-instrumentation, add the relevant `@opentelemetry/instrumentation-*`
+ * packages and call `registerInstrumentations({ instrumentations: [...] })`
+ * after `initOtel()`. The basic tracer + context-propagation setup
+ * provided here works for manually-created spans.
+ */
+export function initOtel() {
+    if (initialised)
+        return;
+    initialised = true;
+    const endpoint = process.env['OTEL_EXPORTER_OTLP_ENDPOINT'];
+    const samplerArg = process.env['OTEL_TRACES_SAMPLER_ARG'] ?? '0.01';
+    const parsed = Number.parseFloat(samplerArg);
+    const ratio = Number.isNaN(parsed) ? 0.01 : parsed;
+    const sampler = new TraceIdRatioBasedSampler(ratio);
+    const provider = new NodeTracerProvider({ sampler });
+    if (endpoint) {
+        provider.addSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter({ url: endpoint })));
+    }
+    else {
+        provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
+    }
+    // Use provider.register() rather than trace.setGlobalTracerProvider() so
+    // that context propagation is set up correctly and any future
+    // auto-instrumentation (HTTP, Express, etc.) will work without additional
+    // wiring. The two calls are equivalent for the simple case of "set the
+    // global provider" but `register()` also installs the W3C TraceContext
+    // propagators and registers the provider with the metrics + context
+    // managers — the recommended OTel SDK pattern.
+    provider.register();
+    // Register auto-instrumentation for outbound HTTP calls. Every
+    // `ctx.fetch()` (which uses Node's `http`/`https` modules under ky)
+    // will produce a child span automatically. Inbound HTTP is handled by
+    // API Gateway (which creates its own span), so this instrumentation
+    // only covers the outbound (service-to-service) call path.
+    registerInstrumentations({
+        instrumentations: [new HttpInstrumentation()],
+    });
+}

package/dist/runtime/typed-errors.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Runtime adapters that convert throw-able operations into typed
+ * `Result<T, AppError>` values.  Domain handlers import these (or the
+ * lower-level `ok`/`err` constructors) and return `Result` instead of
+ * throwing, so every error path is explicit in the handler's return type.
+ */
+import { createKyClient } from './ky-client.js';
+import type { AppError, InternalError, Result } from '../types/result.js';
+export type { AppError, Result } from '../types/result.js';
+export type SafeResult<T> = Result<T, AppError>;
+/**
+ * Create an `internal` error from a caught throwable.  Extracts a
+ * best-effort message and stack trace; the caller should already have
+ * logged the full error before returning the Result to the API gateway.
+ */
+export declare function captureStack(err: unknown, traceId: string): InternalError;
+/**
+ * Wraps a `TibFetch` instance so that every `fetch()` call returns a
+ * `Result<Response, AppError>` instead of throwing.  Network errors,
+ * unexpected status codes, and JSON parse failures are all converted to
+ * typed errors.
+ *
+ * ```ts
+ * const http = safeFetch(ctx.fetch);
+ * const res = await http.get('https://api.example.com/users');
+ * if (!res.ok) return res;        // res.error is typed AppError
+ * const users = await res.json(); // res.value.json()
+ * ```
+ */
+export interface SafeFetch {
+    fetch(url: string, init?: RequestInit): Promise<SafeResult<Response>>;
+}
+export declare function safeFetch(client: ReturnType<typeof createKyClient>): SafeFetch;
+/**
+ * Stub — wraps the existing db client so that common query errors are
+ * converted to typed errors.  This is a skeleton for future expansion;
+ * the current version only catches unexpected throws.
+ */
+export interface SafeDb {
+    query(domainId: string, sql: string, params?: unknown[]): Promise<SafeResult<unknown[]>>;
+}
+export declare function safeDb(db: {
+    query: (domainId: string, sql: string, params?: unknown[]) => Promise<unknown[]>;
+}): SafeDb;
+/**
+ * Wraps a domain handler that returns `Result<T, AppError>` in a
+ * standard API Gateway lambda wrapper.  Success results become 2xx
+ * responses; failure results become the appropriate HTTP status code
+ * (4xx/5xx) with structured error bodies.
+ *
+ * Any *unexpected* throw inside the handler is caught and converted to
+ * a 500 with the trace ID — the page never crashes.
+ */
+export declare function wrapHandler<T>(handler: (input: unknown, ctx: unknown) => Promise<Result<T, AppError>>): (input: unknown, ctx: unknown) => Promise<unknown>;

package/dist/runtime/typed-errors.js

@@ -0,0 +1,106 @@
+/**
+ * Runtime adapters that convert throw-able operations into typed
+ * `Result<T, AppError>` values.  Domain handlers import these (or the
+ * lower-level `ok`/`err` constructors) and return `Result` instead of
+ * throwing, so every error path is explicit in the handler's return type.
+ */
+import { ok, err } from '../types/result.js';
+// ── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Create an `internal` error from a caught throwable.  Extracts a
+ * best-effort message and stack trace; the caller should already have
+ * logged the full error before returning the Result to the API gateway.
+ */
+export function captureStack(err, traceId) {
+    if (err instanceof Error) {
+        return {
+            kind: 'internal',
+            traceId,
+            message: err.message,
+        };
+    }
+    return {
+        kind: 'internal',
+        traceId,
+        message: String(err),
+    };
+}
+export function safeFetch(client) {
+    return {
+        async fetch(url, init) {
+            try {
+                const response = await client.fetch(url, init);
+                return ok(response);
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                return err({
+                    kind: 'external_service',
+                    service: url,
+                    status: 0,
+                    body: message,
+                });
+            }
+        },
+    };
+}
+export function safeDb(db) {
+    return {
+        async query(domainId, sql, params) {
+            try {
+                const rows = await db.query(domainId, sql, params);
+                return ok(rows);
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                return err({
+                    kind: 'external_service',
+                    service: 'database',
+                    status: 0,
+                    body: message,
+                });
+            }
+        },
+    };
+}
+// ── wrapHandler ─────────────────────────────────────────────────────────────
+/**
+ * Wraps a domain handler that returns `Result<T, AppError>` in a
+ * standard API Gateway lambda wrapper.  Success results become 2xx
+ * responses; failure results become the appropriate HTTP status code
+ * (4xx/5xx) with structured error bodies.
+ *
+ * Any *unexpected* throw inside the handler is caught and converted to
+ * a 500 with the trace ID — the page never crashes.
+ */
+export function wrapHandler(handler) {
+    return async (input, ctx) => {
+        try {
+            const result = await handler(input, ctx);
+            if (result.ok)
+                return { statusCode: 200, body: JSON.stringify(result.value) };
+            return errorToResponse(result.error);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return errorToResponse({ kind: 'internal', traceId: '', message });
+        }
+    };
+}
+// ── HTTP mapping ────────────────────────────────────────────────────────────
+function errorToResponse(error) {
+    const statusMap = {
+        not_found: 404,
+        validation: 400,
+        conflict: 409,
+        unauthorized: 401,
+        forbidden: 403,
+        rate_limited: 429,
+        external_service: 502,
+        internal: 500,
+    };
+    return {
+        statusCode: statusMap[error.kind],
+        body: JSON.stringify({ error }),
+    };
+}

package/dist/schema/helpers.d.ts

@@ -1,8 +1,8 @@
 import { z } from 'zod';
 /** UUID v4/v7 string schema. */
-export declare const uuid: () => z.ZodString;
+export declare const uuid: () => z.ZodUUID;
 /** ISO 8601 date-time string schema. */
-export declare const isoDate: () => z.ZodString;
+export declare const isoDate: () => z.ZodISODateTime;
 /**
  * Semver version string schema (e.g. "1.2.3", "^1.0.0", "~2.1").
  * Accepts a loose superset sufficient for package version ranges.
@@ -14,4 +14,4 @@ export declare const semver: () => z.ZodString;
  */
 export declare const cronExpression: () => z.ZodString;
 /** UUID v7 tenant-id string schema (same shape as uuid but named for clarity). */
-export declare const tenantId: () => z.ZodString;
+export declare const tenantId: () => z.ZodUUID;

package/dist/schema/helpers.js

@@ -1,8 +1,8 @@
 import { z } from 'zod';
 /** UUID v4/v7 string schema. */
-export const uuid = () => z.string().uuid();
+export const uuid = () => z.uuid();
 /** ISO 8601 date-time string schema. */
-export const isoDate = () => z.string().datetime({ offset: true });
+export const isoDate = () => z.iso.datetime({ offset: true });
 /**
  * Semver version string schema (e.g. "1.2.3", "^1.0.0", "~2.1").
  * Accepts a loose superset sufficient for package version ranges.
@@ -14,4 +14,4 @@ export const semver = () => z.string().regex(/^[\^~]?\d+\.\d+\.\d+(?:-[\w.]+)?(?
  */
 export const cronExpression = () => z.string().regex(/^(?:cron\([^)]+\)|rate\(\d+ (?:minute|minutes|hour|hours|day|days)\))$/, 'Must be a valid cron(…) or rate(…) expression');
 /** UUID v7 tenant-id string schema (same shape as uuid but named for clarity). */
-export const tenantId = () => z.string().uuid();
+export const tenantId = () => z.uuid();

package/dist/types/enforcement.d.ts

@@ -25,12 +25,10 @@ export interface DomainModuleConfig {
  * Used by the CLI config loader to validate `.mc/domain-module.config.ts` exports.
  */
 export declare const DomainModuleConfigSchema: z.ZodObject<{
-    mode: z.ZodEnum<["optional", "enforced", "strict"]>;
-    legacyAllowlist: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-}, "strip", z.ZodTypeAny, {
-    mode: "optional" | "enforced" | "strict";
-    legacyAllowlist?: string[] | undefined;
-}, {
-    mode: "optional" | "enforced" | "strict";
-    legacyAllowlist?: string[] | undefined;
-}>;
+    mode: z.ZodEnum<{
+        optional: "optional";
+        enforced: "enforced";
+        strict: "strict";
+    }>;
+    legacyAllowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;

package/dist/types/index.d.ts

@@ -4,3 +4,5 @@ export type { AuthConfig, RateLimitConfig, TenancyMode } from './auth.js';
 export type { DeploymentConfig, ObservabilityConfig, EnforcementMode } from './deployment.js';
 export type { DomainModuleConfig } from './enforcement.js';
 export { DomainModuleConfigSchema } from './enforcement.js';
+export type { AppError, Result, NotFoundError, ValidationError, ConflictError, UnauthorizedError, ForbiddenError, RateLimitedError, ExternalServiceError, InternalError } from './result.js';
+export { ok, err, notFound } from './result.js';

package/dist/types/index.js

@@ -1 +1,2 @@
 export { DomainModuleConfigSchema } from './enforcement.js';
+export { ok, err, notFound } from './result.js';

package/dist/types/result.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Typed error handling for domain handlers.
+ *
+ * The `AppError` union replaces bare `throw` statements with structured,
+ * categorised errors that every handler can match against. Result<T>
+ * encodes the success-or-failure outcome so callers are forced to check
+ * before using the value — no unhandled promise rejections, no catch-all
+ * "Internal Server Error" pages.
+ *
+ * Usage:
+ *
+ * ```ts
+ * function getTenant(id: string): Result<Tenant, AppError> {
+ *   const row = await db.query(...);
+ *   if (!row) return err({ kind: 'not_found', resource: 'tenant', id });
+ *   return ok(row);
+ * }
+ * ```
+ */
+/** Every possible error kind a domain handler can return. */
+export type AppError = NotFoundError | ValidationError | ConflictError | UnauthorizedError | ForbiddenError | RateLimitedError | ExternalServiceError | InternalError;
+/** The requested resource does not exist. */
+export interface NotFoundError {
+    kind: 'not_found';
+    resource: string;
+    id: string;
+}
+/** Input validation failed. Field-level errors for form highlighting. */
+export interface ValidationError {
+    kind: 'validation';
+    fieldErrors: Record<string, string[]>;
+    message: string;
+}
+/** The operation conflicts with the current state (e.g. duplicate). */
+export interface ConflictError {
+    kind: 'conflict';
+    message: string;
+}
+/** The caller must authenticate first. */
+export interface UnauthorizedError {
+    kind: 'unauthorized';
+    message: string;
+}
+/** The caller is authenticated but lacks permission. */
+export interface ForbiddenError {
+    kind: 'forbidden';
+    message: string;
+}
+/** Rate limit exceeded. The caller should retry after the specified
+ *  number of seconds. */
+export interface RateLimitedError {
+    kind: 'rate_limited';
+    retryAfterSeconds: number;
+}
+/** An external service returned an error. The handler should surface
+ *  the original status and a sanitised summary — do NOT log raw
+ *  response bodies from third-party APIs. */
+export interface ExternalServiceError {
+    kind: 'external_service';
+    service: string;
+    status: number;
+    body: unknown;
+}
+/** Something unexpected happened. The `traceId` is a correlation
+ *  identifier for the current request — include it in user-facing
+ *  error messages so support can look up the details in CloudWatch. */
+export interface InternalError {
+    kind: 'internal';
+    traceId: string;
+    message: string;
+}
+/** Discriminated union: either `ok` with a value, or not-ok with an error. */
+export type Result<T, E = AppError> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+/** Create a success Result. */
+export declare function ok<T>(value: T): Result<T, never>;
+/** Create a failure Result. */
+export declare function err<E extends AppError>(error: E): Result<never, E>;
+/**
+ * Convenience: return a pre-built 404-style error for a missing resource.
+ *
+ * ```ts
+ * if (!row) return notFound('tenant', id);
+ * ```
+ */
+export declare function notFound(resource: string, id: string): Result<never, AppError>;

package/dist/types/result.js

@@ -0,0 +1,38 @@
+/**
+ * Typed error handling for domain handlers.
+ *
+ * The `AppError` union replaces bare `throw` statements with structured,
+ * categorised errors that every handler can match against. Result<T>
+ * encodes the success-or-failure outcome so callers are forced to check
+ * before using the value — no unhandled promise rejections, no catch-all
+ * "Internal Server Error" pages.
+ *
+ * Usage:
+ *
+ * ```ts
+ * function getTenant(id: string): Result<Tenant, AppError> {
+ *   const row = await db.query(...);
+ *   if (!row) return err({ kind: 'not_found', resource: 'tenant', id });
+ *   return ok(row);
+ * }
+ * ```
+ */
+// ── Constructors ────────────────────────────────────────────────────────────
+/** Create a success Result. */
+export function ok(value) {
+    return { ok: true, value };
+}
+/** Create a failure Result. */
+export function err(error) {
+    return { ok: false, error };
+}
+/**
+ * Convenience: return a pre-built 404-style error for a missing resource.
+ *
+ * ```ts
+ * if (!row) return notFound('tenant', id);
+ * ```
+ */
+export function notFound(resource, id) {
+    return err({ kind: 'not_found', resource, id });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mettlecast/domain-runtime",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -58,10 +58,19 @@
     "@aws-lambda-powertools/logger": "^2.0.0",
     "@aws-lambda-powertools/metrics": "^2.0.0",
     "@aws-lambda-powertools/tracer": "^2.0.0",
+    "@opentelemetry/api": "~1.8.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.50.0",
+    "@opentelemetry/instrumentation": "^0.50.0",
+    "@opentelemetry/instrumentation-http": "^0.50.0",
+    "@opentelemetry/sdk-trace-node": "^1.0.0",
     "drizzle-orm": "*",
+    "ky": "^1.7.0",
     "pg": "^8.0.0",
     "semver": "^7.0.0",
-    "zod": "^3.0.0"
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "@types/aws-lambda": "^8.10.0",