@mettlecast/domain-runtime 0.2.59 → 0.2.61

package/dist/runtime/action-handler.js

@@ -1,29 +1,129 @@
 import { hydrateCtx } from './hydrate.js';
+import { executeAction } from './action-executor.js';
 /**
  * Creates the Lambda handler for an action-class Lambda.
- * Receives cross-domain invocations via Lambda invoke and runs the action handler.
+ *
+ * Receives cross-domain invocations via Lambda invoke and routes the
+ * action through the shared `executeAction` pipeline so the full set of
+ * checks (input validation, auth/tenancy, backendAccess, idempotency,
+ * audit, output validation) applies uniformly with API-exposed actions.
+ *
+ * Behaviour:
+ * - Hydrates `ctx` from the structured envelope (`actor` block takes
+ *   precedence over the legacy `actorId` fallback).
+ * - Looks up the registered action by `domainId + actionId`.
+ * - If the registered entry is an `ActionDefinition`, runs it through
+ *   `executeAction` with an `InternalActionSource` carrying the caller
+ *   domain. This enables backendAccess enforcement on every cross-domain
+ *   invocation.
+ * - If only the legacy handler-function form is registered, calls it
+ *   directly — preserves migration compatibility for callers that have
+ *   not yet supplied full definitions. The narrow migration-compatible
+ *   path skips the executor pipeline (no Zod validation, no idempotency,
+ *   no audit log) so legacy callers keep working while Wave 3 rolls out.
+ *   New callers should register `ActionDefinition` instances.
+ *
+ * @param registry - Map of `domainId → actionId → ActionDefinition | handler`.
+ * @param options - Domain identification and runtime options.
+ * @returns AWS Lambda handler for the action-class Lambda.
  */
 export function createActionLambdaHandler(registry, options) {
     return async (event) => {
         const { input, envelope } = event;
-        const ctx = await hydrateCtx({
-            tenant: { id: envelope.tenantId, workspaceId: envelope.tenantId, orgId: envelope.orgId },
-            actor: { type: 'action', sub: envelope.actorId, tenantId: envelope.tenantId },
+        // ── Hydrate actor from structured envelope (with legacy fallback) ──
+        const actor = envelope.actor.sub
+            ? envelope.actor
+            : (envelope.actorId
+                ? { ...envelope.actor, sub: envelope.actorId }
+                : envelope.actor);
+        // `hydrateCtx(event, options)` — pass `undefined` for the unused event
+        // slot and the structured envelope-derived payload as the second arg.
+        // Passing the options as the first arg (the previous implementation)
+        // made `hydrateCtx` fall back to its empty-options defaults, so cross-
+        // domain Lambda handlers ended up with `tenant.id = 'unknown'` and a
+        // system actor — silently bypassing the tenant/auth checks in
+        // `executeAction`. The smoke test in
+        // `__tests__/auth-tenant-smoke.test.ts` pins this contract.
+        const ctx = await hydrateCtx(undefined, {
+            tenant: {
+                id: envelope.tenantId,
+                workspaceId: envelope.tenantId,
+                ...(envelope.orgId !== undefined ? { orgId: envelope.orgId } : {}),
+            },
+            actor: {
+                type: actor.type,
+                ...(actor.sub !== undefined ? { sub: actor.sub } : {}),
+                ...(actor.email !== undefined ? { email: actor.email } : {}),
+                ...(actor.roles !== undefined ? { roles: actor.roles } : {}),
+                ...(actor.scopes !== undefined ? { scopes: actor.scopes } : {}),
+                tenantId: envelope.tenantId,
+            },
             domainId: options.domainId,
             traceId: envelope.traceId,
-            eventBusName: options.eventBusName,
-            databaseUrl: options.databaseUrl,
-            idempotencyTable: options.idempotencyTableName,
+            ...(options.eventBusName !== undefined ? { eventBusName: options.eventBusName } : {}),
+            ...(options.databaseUrl !== undefined ? { databaseUrl: options.databaseUrl } : {}),
+            ...(options.idempotencyTableName !== undefined ? { idempotencyTable: options.idempotencyTableName } : {}),
             actionRegistry: registry,
         });
         const domainActions = registry[options.domainId];
         if (!domainActions) {
             throw new Error(`No actions registered for domain: ${options.domainId}`);
         }
-        const handler = domainActions[envelope.actionId];
-        if (!handler) {
+        const entry = domainActions[envelope.actionId];
+        if (!entry) {
             throw new Error(`Action not found: ${options.domainId}.${envelope.actionId}`);
         }
-        return handler(input, ctx);
+        // ── Route through executeAction when a full definition is available ──
+        // `isActionDefinition` discriminates the new shape (definition object)
+        // from the legacy handler-function form. See `ActionRegistry` for the
+        // rationale and migration guidance.
+        if (isActionDefinition(entry)) {
+            const result = await executeAction(entry, input, ctx, { type: 'internal', callerDomain: envelope.callerDomain }, {
+                definingDomain: options.domainId,
+                traceId: envelope.traceId,
+            });
+            return encodeExecuteResult(result);
+        }
+        // ── Migration-compatible legacy path: call the handler directly ──
+        // When callers have not yet supplied a full ActionDefinition we still
+        // honour the invocation so the upgrade is non-breaking. This path skips
+        // the executor pipeline intentionally — older handler signatures cannot
+        // be expected to pass Zod schemas that may not exist. A WARN is logged
+        // so operators can spot callers that need to migrate.
+        ctx.logger.warn('Action invoked without ActionDefinition; legacy handler path used', {
+            domainId: options.domainId,
+            actionId: envelope.actionId,
+            callerDomain: envelope.callerDomain,
+            traceId: envelope.traceId,
+        });
+        return entry(input, ctx);
     };
 }
+/**
+ * Encodes an {@link ExecuteActionResult} as a Lambda-friendly return value.
+ * Successful results pass through the validated output; failed results
+ * surface the structured `TibError` code so callers can branch on it
+ * without parsing messages.
+ */
+function encodeExecuteResult(result) {
+    if (result.ok) {
+        return result.value;
+    }
+    throw result.error;
+}
+/**
+ * Type-guard: is the registry entry a full `ActionDefinition`?
+ *
+ * Definition entries carry the `_kind: 'action'` discriminant produced by
+ * `defineAction`. Bare handler functions lack it. When `_kind` is missing
+ * we fall back to checking for `backendAccess` — `defineAction` requires
+ * this field on every definition, so its presence is a reliable marker
+ * even if `_kind` were stripped (e.g. by a non-runtime serializer).
+ */
+function isActionDefinition(entry) {
+    if (typeof entry === 'function')
+        return false;
+    if (entry._kind === 'action')
+        return true;
+    return typeof entry.backendAccess === 'string' && typeof entry.input !== 'undefined';
+}

package/dist/runtime/actions.d.ts

@@ -1,14 +1,41 @@
 import type { ActionsProxy } from '../ctx/proxies.js';
+import type { ActionInvocationEnvelope } from './action-handler.js';
+import type { ActionDefinition } from '../primitives/action.js';
 /**
  * A registry of action handlers keyed by domain ID then action ID.
- * Each handler receives `(input, ctx)` — ctx is injected by the caller.
+ *
+ * Each value may be either:
+ * - a full {@link ActionDefinition} (preferred — produced by `defineAction`).
+ *   Routes through `executeAction` so backendAccess, idempotency, audit,
+ *   and output validation all apply.
+ * - a bare handler function `(input, ctx) => Promise<unknown>`. Kept for
+ *   migration compatibility with callers that registered before Wave 3 of
+ *   #4619. NOT routed through `executeAction` — receives `ctx` directly.
+ *
+ * Re-exports the discriminating types from `action-handler.ts` so consumers
+ * only need to import from this module to type their registries.
+ */
+export type ActionRegistry = Record<string, Record<string, ActionDefinition | ActionHandlerFn>>;
+/**
+ * Legacy handler-function registration form. Re-exported so callers can
+ * type legacy entries explicitly.
+ */
+export type ActionHandlerFn = (input: unknown, ctx: any) => Promise<unknown>;
+/**
+ * Options for the ActionsProxy factory.
+ *
+ * Wave 7 Task 7.1 (#4619): `definingDomains` carries the canonical
+ * domain-id for every action registered in-process so `executeAction`
+ * can enforce `backendAccess: 'private'` against cross-domain callers.
+ * When omitted, each registered entry is treated as defined by the
+ * caller domain (the conservative default for tests/legacy callers —
+ * see `invokeInProcess` for the exact contract).
  */
-export type ActionRegistry = Record<string, Record<string, (input: unknown, ctx: any) => Promise<unknown>>>;
-/** Options for the ActionsProxy factory. */
 export interface ActionsProxyOptions {
     /**
      * Registry of domain action handlers. Keys are domain IDs; values are
-     * maps of action ID to handler functions.
+     * maps of action ID to `ActionDefinition` (preferred) or legacy handler
+     * function.
      */
     registry: ActionRegistry;
     /**
@@ -24,16 +51,49 @@ export interface ActionsProxyOptions {
      * This domain's ID (used in the invocation envelope).
      */
     callerDomainId?: string;
+    /**
+     * Optional override mapping `${domainId}.${actionId}` → defining domain
+     * id. When provided, the runtime can enforce `backendAccess: 'private'`
+     * against cross-domain in-process calls. When omitted, the default is
+     * "every registered action is owned by its own domain" — same-domain
+     * calls still succeed and cross-domain calls route through the
+     * executor's `isCallerAllowed` (which fails closed for `private`
+     * actions when defining domain metadata is missing).
+     */
+    definingDomains?: Record<string, string>;
 }
 /**
  * Creates an ActionsProxy from a pre-built action registry.
+ *
  * Access pattern: `ctx.actions[domainId][actionId](input)`.
- * V1 is in-process only. V2 adds Lambda invoke for cross-domain calls.
+ *
+ * - In-process: registered entries run inside this Lambda. Definitions
+ *   are routed through `executeAction(..., { type: 'internal', callerDomain })`
+ *   so the full auth/tenancy/backendAccess pipeline applies. Legacy handler
+ *   functions are invoked directly.
+ * - Cross-domain: when a `lambdaArn` is provided for a domain not in the
+ *   in-process registry, a Lambda `InvokeCommand` is dispatched with the
+ *   structured {@link ActionInvocationEnvelope}. The receiving handler
+ *   (`createActionLambdaHandler`) hydrates `ctx` from that envelope.
+ *
  * @param options - ActionsProxyOptions with registry and ctx reference.
  * @returns An ActionsProxy object conforming to the domain-runtime type.
  * @throws At call time if the domain or action is not found in the registry.
  */
 export declare function createActionsProxy(options: ActionsProxyOptions): ActionsProxy;
+/**
+ * Builds a structured {@link ActionInvocationEnvelope} payload from the
+ * caller-side `ctx`. Always emits the new structured `actor` block;
+ * never the legacy flat `actorId` field (that field is consumed only on
+ * the receive side as a fallback).
+ */
+export declare function buildEnvelope(opts: {
+    input: unknown;
+    ctx: any;
+    callerDomainId?: string;
+    targetDomain?: string;
+    actionId: string;
+}): ActionInvocationEnvelope['envelope'];
 /**
  * Creates an empty ActionsProxy for unit tests or environments with no registered actions.
  * @returns An empty ActionsProxy (no domains, no actions).

package/dist/runtime/actions.js

@@ -1,20 +1,38 @@
 import { LambdaClient, InvokeCommand } from '@aws-sdk/client-lambda';
+import { executeAction } from './action-executor.js';
 /**
  * Creates an ActionsProxy from a pre-built action registry.
+ *
  * Access pattern: `ctx.actions[domainId][actionId](input)`.
- * V1 is in-process only. V2 adds Lambda invoke for cross-domain calls.
+ *
+ * - In-process: registered entries run inside this Lambda. Definitions
+ *   are routed through `executeAction(..., { type: 'internal', callerDomain })`
+ *   so the full auth/tenancy/backendAccess pipeline applies. Legacy handler
+ *   functions are invoked directly.
+ * - Cross-domain: when a `lambdaArn` is provided for a domain not in the
+ *   in-process registry, a Lambda `InvokeCommand` is dispatched with the
+ *   structured {@link ActionInvocationEnvelope}. The receiving handler
+ *   (`createActionLambdaHandler`) hydrates `ctx` from that envelope.
+ *
  * @param options - ActionsProxyOptions with registry and ctx reference.
  * @returns An ActionsProxy object conforming to the domain-runtime type.
  * @throws At call time if the domain or action is not found in the registry.
  */
 export function createActionsProxy(options) {
-    const { registry, ctx, lambdaArns = {}, callerDomainId } = options;
+    const { registry, ctx, lambdaArns = {}, callerDomainId, definingDomains = {} } = options;
     const proxy = {};
-    // Build in-process proxy for domains in the registry
+    // Build in-process proxy for domains in the registry. We resolve the
+    // defining domain for each (domainId, actionId) entry up front so the
+    // in-process path can plumb it into `executeAction`'s meta. The default
+    // when no entry exists in `definingDomains` is the `domainId` of the
+    // registry key — i.e. "this entry is defined by the domain it lives
+    // under", which is the conservative same-domain default and the
+    // convention used by generated dedicated Lambda wrappers.
     for (const [domainId, actions] of Object.entries(registry)) {
         proxy[domainId] = {};
-        for (const [actionId, handler] of Object.entries(actions)) {
-            proxy[domainId][actionId] = (...args) => handler(args[0], ctx);
+        for (const [actionId, entry] of Object.entries(actions)) {
+            const definingDomain = definingDomains[`${domainId}.${actionId}`] ?? domainId;
+            proxy[domainId][actionId] = (...args) => invokeInProcess(entry, args[0], ctx, callerDomainId, definingDomain);
         }
     }
     // For cross-domain calls, create Lambda invoke proxies
@@ -30,14 +48,13 @@ export function createActionsProxy(options) {
                 return async (input) => {
                     const payload = {
                         input,
-                        envelope: {
-                            tenantId: ctx.tenant?.id ?? 'unknown',
-                            orgId: ctx.tenant?.orgId,
-                            actorId: ctx.actor?.sub ?? 'system',
-                            traceId: ctx.traceId ?? 'unknown',
-                            callerDomain: callerDomainId ?? 'unknown',
-                            actionId,
-                        },
+                        envelope: buildEnvelope({
+                            input,
+                            ctx,
+                            callerDomainId,
+                            targetDomain: domainId,
+                            actionId: String(actionId),
+                        }),
                     };
                     const response = await lambdaClient.send(new InvokeCommand({
                         FunctionName: arn,
@@ -55,6 +72,94 @@ export function createActionsProxy(options) {
     }
     return proxy;
 }
+/**
+ * Builds a structured {@link ActionInvocationEnvelope} payload from the
+ * caller-side `ctx`. Always emits the new structured `actor` block;
+ * never the legacy flat `actorId` field (that field is consumed only on
+ * the receive side as a fallback).
+ */
+export function buildEnvelope(opts) {
+    const actorEnvelope = toActorEnvelope(opts.ctx?.actor);
+    const envelope = {
+        tenantId: opts.ctx?.tenant?.id ?? 'unknown',
+        actor: actorEnvelope,
+        callerDomain: opts.callerDomainId ?? 'unknown',
+        actionId: opts.actionId,
+        traceId: opts.ctx?.traceId ?? 'unknown',
+    };
+    if (opts.ctx?.tenant?.orgId !== undefined) {
+        envelope.orgId = opts.ctx.tenant.orgId;
+    }
+    if (opts.targetDomain !== undefined) {
+        envelope.targetDomain = opts.targetDomain;
+    }
+    return envelope;
+}
+/**
+ * Project the runtime `Actor` shape onto the wire-format
+ * {@link ActionActorEnvelope}. Fields that are not present on the source
+ * `Actor` are omitted entirely (not coerced to `undefined`) so the JSON
+ * payload stays compact.
+ */
+function toActorEnvelope(actor) {
+    if (!actor) {
+        return { type: 'system' };
+    }
+    const env = { type: actor.type };
+    if (actor.sub !== undefined)
+        env.sub = actor.sub;
+    if (actor.email !== undefined)
+        env.email = actor.email;
+    if (actor.roles !== undefined)
+        env.roles = actor.roles;
+    if (actor.scopes !== undefined)
+        env.scopes = actor.scopes;
+    return env;
+}
+/**
+ * Invoke a registry entry in-process.
+ *
+ * - If the entry is an `ActionDefinition`, route through `executeAction`
+ *   with an `InternalActionSource` so backendAccess enforcement, input
+ *   validation, idempotency, audit, and output validation all apply.
+ * - Otherwise treat it as a legacy handler function and invoke directly.
+ *   A WARN is logged so operators can spot legacy registrations.
+ *
+ * `definingDomain` is the domain that owns the registered action. It is
+ * forwarded to `executeAction`'s `meta` so `isCallerAllowed` can enforce
+ * `backendAccess: 'private'` against cross-domain in-process callers.
+ */
+async function invokeInProcess(entry, input, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ctx, callerDomainId, definingDomain) {
+    if (isActionDefinition(entry)) {
+        const result = await executeAction(entry, input, ctx, { type: 'internal', callerDomain: callerDomainId }, { definingDomain, traceId: ctx?.traceId });
+        if (!result.ok)
+            throw result.error;
+        return result.value;
+    }
+    // Legacy handler-function path
+    if (ctx?.logger?.warn) {
+        ctx.logger.warn('Action invoked without ActionDefinition; legacy handler path used', {
+            callerDomain: callerDomainId,
+            definingDomain,
+        });
+    }
+    return entry(input, ctx);
+}
+/**
+ * Type-guard mirroring the one in `action-handler.ts`. Defined locally so
+ * this module does not need to depend on the handler implementation file.
+ */
+function isActionDefinition(entry) {
+    if (typeof entry !== 'function') {
+        const candidate = entry;
+        if (candidate._kind === 'action')
+            return true;
+        return typeof candidate.backendAccess === 'string' && typeof candidate.input !== 'undefined';
+    }
+    return false;
+}
 /**
  * Creates an empty ActionsProxy for unit tests or environments with no registered actions.
  * @returns An empty ActionsProxy (no domains, no actions).

package/dist/runtime/audit.d.ts

@@ -1,4 +1,5 @@
 import type { PublishFn } from '../ctx/comms.js';
+import type { ObservabilityBindings } from './observability-bindings.js';
 export interface AuditEntry {
     action: string;
     target: string;
@@ -8,9 +9,20 @@ export interface AuditContext {
     log(action: string, target: string, metadata?: Record<string, unknown>): Promise<void>;
 }
 /**
- * Creates an audit context that auto-injects tenantId, actorId, traceId, timestamp
- * and publishes a {domain}.audit.event to EventBridge.
- * SOC2 / forensics baseline — per-domain hand-rolling forbidden by ESLint rule.
+ * Creates an audit context that auto-injects the canonical
+ * observability bindings (#4662 Task D — tenant/actor/action identity)
+ * alongside the legacy flat fields, then publishes a
+ * `{domain}.audit.event` to EventBridge.
+ *
+ * SOC2 / forensics baseline — per-domain hand-rolling is forbidden by
+ * the ESLint rule `no-raw-audit-publish`. New callers should consume
+ * `ctx.audit.log(...)` so the bindings stay consistent across
+ * domains.
+ *
+ * The bindings object is shallow-merged into the audit envelope so
+ * downstream consumers (CloudWatch Logs Insights, the audit replay
+ * pipeline, the SOC2 report generator) can rely on a stable field
+ * shape regardless of which domain emitted the event.
  */
 export declare function createAudit(opts: {
     domainId: string;
@@ -18,4 +30,12 @@ export declare function createAudit(opts: {
     actorId: string | undefined;
     traceId: string;
     publish: PublishFn;
+    /**
+     * Optional canonical observability bindings. When supplied the audit
+     * envelope carries the full structured shape (`actorSub`, `orgId`,
+     * `callerDomain`, etc.) in addition to the legacy flat fields so
+     * older consumers keep working while new consumers can filter by
+     * any of the canonical fields.
+     */
+    bindings?: ObservabilityBindings;
 }): AuditContext;

package/dist/runtime/audit.js

@@ -1,18 +1,35 @@
 /**
- * Creates an audit context that auto-injects tenantId, actorId, traceId, timestamp
- * and publishes a {domain}.audit.event to EventBridge.
- * SOC2 / forensics baseline — per-domain hand-rolling forbidden by ESLint rule.
+ * Creates an audit context that auto-injects the canonical
+ * observability bindings (#4662 Task D — tenant/actor/action identity)
+ * alongside the legacy flat fields, then publishes a
+ * `{domain}.audit.event` to EventBridge.
+ *
+ * SOC2 / forensics baseline — per-domain hand-rolling is forbidden by
+ * the ESLint rule `no-raw-audit-publish`. New callers should consume
+ * `ctx.audit.log(...)` so the bindings stay consistent across
+ * domains.
+ *
+ * The bindings object is shallow-merged into the audit envelope so
+ * downstream consumers (CloudWatch Logs Insights, the audit replay
+ * pipeline, the SOC2 report generator) can rely on a stable field
+ * shape regardless of which domain emitted the event.
  */
 export function createAudit(opts) {
+    const bindings = opts.bindings ?? {};
     return {
         async log(action, target, metadata) {
             await opts.publish(`${opts.domainId}.audit.event`, {
                 action,
                 target,
                 metadata: metadata ?? {},
+                // Legacy flat fields (kept stable for downstream consumers).
                 tenantId: opts.tenantId,
                 actorId: opts.actorId ?? 'system',
                 traceId: opts.traceId,
+                // New structured bindings (#4662 Task D). Spread AFTER the flat
+                // fields so an empty bindings object doesn't overwrite the
+                // legacy keys with `undefined`.
+                ...bindings,
                 timestamp: new Date().toISOString(),
             });
         },

package/dist/runtime/db.d.ts

@@ -16,6 +16,12 @@ export interface DbOptions {
      * Optional; only set if present.
      */
     orgId?: string;
+    /**
+     * Actor subject (`Actor.sub`) to bind as the PostgreSQL session variable
+     * `app.actor_id`. Optional; only set if present. Useful for DB-side audit
+     * triggers and `current_setting('app.actor_id', true)` reads.
+     */
+    actorId?: string;
     /**
      * Optional schema name passed to drizzle. Defaults to undefined (uses search_path).
      */
@@ -24,10 +30,23 @@ export interface DbOptions {
 /**
  * Create a DrizzleORM postgres DbContext bound to a tenant-scoped client.
  *
- * The implementation checks out a single client from the pool and runs
- * `SET app.current_tenant = $1` on it. The same client is reused for every
- * query made through this DbContext. The caller must invoke `release()`
- * after the handler completes to return the client to the pool.
+ * The implementation checks out a single client from the pool and binds the
+ * per-request identity onto the PostgreSQL session via `SELECT set_config(...)`.
+ * The same client is reused for every query made through this DbContext.
+ * The caller must invoke `release()` after the handler completes to return
+ * the client to the pool.
+ *
+ * Why `SELECT set_config(..., is_local := false)` rather than `SET`?
+ *
+ * - `SET app.current_tenant = $1` only accepts a literal value and cannot be
+ *   parameterised via the extended query protocol, which means it cannot be
+ *   used in a prepared-statement-aware path or with binary parameters.
+ * - `set_config('app.current_tenant', $1, false)` runs as a regular parameterised
+ *   statement, works in the prepared-statement pipeline, and — with `is_local := false` —
+ *   binds the value for the rest of the **session** (i.e. the checked-out client).
+ * - `is_local := true` would scope the setting to the current transaction only
+ *   and the value would not survive subsequent queries on the same client,
+ *   which is exactly the failure mode we want to avoid in long-running handlers.
  *
  * Connection resolution order:
  * 1. `options.connectionString`

package/dist/runtime/db.js

@@ -28,10 +28,23 @@ async function connectionStringFromSecret(secretArn) {
 /**
  * Create a DrizzleORM postgres DbContext bound to a tenant-scoped client.
  *
- * The implementation checks out a single client from the pool and runs
- * `SET app.current_tenant = $1` on it. The same client is reused for every
- * query made through this DbContext. The caller must invoke `release()`
- * after the handler completes to return the client to the pool.
+ * The implementation checks out a single client from the pool and binds the
+ * per-request identity onto the PostgreSQL session via `SELECT set_config(...)`.
+ * The same client is reused for every query made through this DbContext.
+ * The caller must invoke `release()` after the handler completes to return
+ * the client to the pool.
+ *
+ * Why `SELECT set_config(..., is_local := false)` rather than `SET`?
+ *
+ * - `SET app.current_tenant = $1` only accepts a literal value and cannot be
+ *   parameterised via the extended query protocol, which means it cannot be
+ *   used in a prepared-statement-aware path or with binary parameters.
+ * - `set_config('app.current_tenant', $1, false)` runs as a regular parameterised
+ *   statement, works in the prepared-statement pipeline, and — with `is_local := false` —
+ *   binds the value for the rest of the **session** (i.e. the checked-out client).
+ * - `is_local := true` would scope the setting to the current transaction only
+ *   and the value would not survive subsequent queries on the same client,
+ *   which is exactly the failure mode we want to avoid in long-running handlers.
  *
  * Connection resolution order:
  * 1. `options.connectionString`
@@ -63,9 +76,17 @@ export async function createDb(options) {
     const pool = new Pool({ connectionString });
     const client = await pool.connect();
     try {
-        await client.query('SET app.current_tenant = $1', [options.tenantId]);
+        // Bind session-scoped identity onto the checked-out client.
+        // `false` keeps the setting for the lifetime of the session (the client).
+        // Using `SELECT set_config(...)` instead of `SET` lets us pass the value
+        // as a parameterised query argument, which keeps the prepared-statement
+        // path hot and protects against accidental string interpolation.
+        await client.query("SELECT set_config('app.current_tenant', $1, false)", [options.tenantId]);
         if (options.orgId) {
-            await client.query('SET app.org_id = $1', [options.orgId]);
+            await client.query("SELECT set_config('app.org_id', $1, false)", [options.orgId]);
+        }
+        if (options.actorId) {
+            await client.query("SELECT set_config('app.actor_id', $1, false)", [options.actorId]);
         }
     }
     catch (err) {

package/dist/runtime/error-formatter.d.ts

@@ -9,16 +9,79 @@ export interface StandardError {
         code: string;
     }>;
 }
+/**
+ * Stable error codes that domain handlers can throw via `TibError`. The
+ * exposed-action API adapter (`createExposedActionApiHandler`) maps each
+ * of these to a fixed HTTP status — adding a new code without updating
+ * the map will fall through to 500.
+ *
+ * The set is intentionally small: every code here resolves to exactly one
+ * HTTP status, so the contract between runtime and frontend is one-to-one.
+ */
+export declare const TIB_ERROR_CODES: readonly ["VALIDATION_ERROR", "AUTH_REQUIRED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "GONE", "UNPROCESSABLE_ENTITY", "INTERNAL_ERROR", "TENANT_REQUIRED", "TENANT_MISMATCH", "NOT_EXPOSED", "OUTPUT_VALIDATION_ERROR"];
+/**
+ * Canonical TypeScript union of {@link TIB_ERROR_CODES}. Use as the
+ * `code` argument type when building a `TibError` so misspelled codes
+ * fail at compile time instead of silently falling through to 500.
+ */
+export type TibErrorCode = (typeof TIB_ERROR_CODES)[number];
 /**
  * Formats any caught error into the standard TIB error envelope.
  * Contract locked with frontend scaffolder (#1975).
  */
 export declare function formatError(err: unknown, traceId: string, logger?: Logger): StandardError;
+/**
+ * Domain error thrown by action handlers and adapter internals. Carries a
+ * stable `code` so adapters can render it to a deterministic HTTP status
+ * without parsing the message.
+ *
+ * Handlers should construct one via `domainError(...)` instead of the raw
+ * constructor so the compiler enforces the allowed-code union.
+ *
+ * The previous action-handler pattern — `throw Object.assign(new Error(),
+ * { status: 404 })` — survives end-to-end as long as the throwing code
+ * passes through `executeAction`, which translates `TibError` into an
+ * `ExecuteActionResult` carrying the same code. See
+ * `runtime/action-executor.ts` for the conversion point.
+ */
 export declare class TibError extends Error {
     readonly code: string;
+    readonly status: number | undefined;
     constructor(message: string, code: string);
 }
+/**
+ * Optional `status` carried by handlers that still author their own
+ * HTTP-style numeric code. Read by the adapter's outer try/catch as a
+ * fallback when the thrown error is not a `TibError` — kept for the
+ * migration window only.
+ *
+ * @deprecated Use {@link domainError} with a `TibErrorCode` instead.
+ */
+export interface HttpStatusCarrier {
+    status?: number;
+}
+/**
+ * Build a {@link TibError} with a stable, typed code. Domain handlers
+ * import this instead of `new TibError(...)` so the compiler refuses
+ * unknown codes.
+ *
+ * ```ts
+ * throw domainError('User not found', 'NOT_FOUND');
+ * ```
+ */
+export declare function domainError(message: string, code: TibErrorCode): TibError;
 /**
  * Extracts a trace ID from X-Ray header or X-Request-Id, or generates a fallback.
  */
 export declare function extractTraceId(headers: Record<string, string | undefined>): string;
+/**
+ * Best-effort detector for an error object that carries a numeric
+ * `status` property (the legacy pattern that pre-dates {@link TibError}).
+ *
+ * Used by the exposed-action API adapter's outer try/catch to render a
+ * domain-meaningful HTTP status for callers that have not migrated to
+ * {@link domainError} yet. Once all built-in handlers are migrated this
+ * function becomes dead code; until then it acts as the migration safety
+ * net so a runtime upgrade does not regress behaviour.
+ */
+export declare function readLegacyHttpStatus(err: unknown): number | undefined;