@nodii/saga 0.0.1 → 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,260 @@
+/** D33-locked status enum (§ 5.5 + comm doctrine § 3.3). */
+export type SagaStatus = "active" | "paused" | "compensating" | "compensated" | "compensation_failed" | "compensated_with_errors" | "compensated_manual" | "technical_failure" | "completed" | "cancelled";
+/** § 5.5 column shape — full 21-col schema including reaper hooks. */
+export interface SagaStateRow {
+    id: string;
+    tenant_id: string | null;
+    type: string;
+    status: SagaStatus;
+    current_step: string | null;
+    step_outputs: Record<string, unknown>;
+    episode: number;
+    trigger_trace_id: string;
+    trigger_span_id: string;
+    trigger_request_id: string;
+    parent_saga_id: string | null;
+    parent_relationship: "child" | "compensation_of";
+    children: string[];
+    started_at: string;
+    completed_at: string | null;
+    /** Reaper hook — § 5.8. When status='paused', the reaper compares
+     *  `next_resume_at + grace_period` to now() and finalizes if elapsed. */
+    next_resume_at: string | null;
+    failure_reason: string | null;
+    failure_step: string | null;
+    compensation_log: CompensationLogEntry[];
+    last_admin_action: string | null;
+    last_admin_actor_id: string | null;
+    last_admin_at: string | null;
+    input: unknown;
+    cancel_reason: string | null;
+}
+export interface CompensationLogEntry {
+    step_name: string;
+    outcome: "undone" | "undo_failed" | "skipped_no_undo";
+    error?: string;
+    ts: string;
+}
+/** § 5.4 — saga owns inputs only; @nodii/idempotency computes the key. */
+export interface IdempotencyShim {
+    /**
+     * Spec § 5.4 — saga supplies (saga_id, step_name, serialized_input);
+     * idempotency lib (or shim) computes the hash + runs the contract +
+     * caches the result. v0.1.0 ships `NoopIdempotency` that simply runs
+     * the handler.
+     */
+    wrapForSagaStep<O>(args: {
+        sagaId: string;
+        stepName: string;
+        serializedInput: string;
+        handler: () => Promise<O>;
+    }): Promise<O>;
+}
+/** Filter applied by `SagaStateStore.list` — surfaced via the admin
+ *  `ListSagas` RPC. All fields are optional; undefined means "no filter". */
+export interface ListSagasFilter {
+    tenantId?: string;
+    status?: string;
+    type?: string;
+}
+/** § 5.5 — pluggable saga_state store.
+ *
+ * `list` is optional + async (Promise-returning) to match the Python +
+ * Go ports. Implementations that omit `list` are honored by the admin
+ * server as "no enumerable rows" (it returns []).
+ */
+export interface SagaStateStore {
+    createSaga(row: SagaStateRow): Promise<void>;
+    getSaga(sagaId: string): Promise<SagaStateRow | null>;
+    updateSagaStatus(sagaId: string, update: Partial<Pick<SagaStateRow, "status" | "current_step" | "completed_at" | "failure_reason" | "failure_step" | "last_admin_action" | "last_admin_actor_id" | "last_admin_at" | "cancel_reason" | "next_resume_at">>): Promise<void>;
+    appendStepOutput(sagaId: string, stepName: string, output: unknown): Promise<void>;
+    appendCompensationLog(sagaId: string, entry: CompensationLogEntry): Promise<void>;
+    /** Optional enumeration — production-bound stores (Postgres) MUST
+     *  implement this; tests can omit. Returns a defensive snapshot. */
+    list?(filter?: ListSagasFilter): Promise<SagaStateRow[]>;
+    /** Reaper-side scan (§ 5.8) — production-bound stores MUST implement
+     *  this. Returns paused sagas whose `next_resume_at < cutoffIso`. */
+    listStalePaused?(cutoffIso: string): Promise<SagaStateRow[]>;
+    /** Pattern 2 outbox writer (§ 5.6). Optional on test doubles. */
+    writeOutboxBegin?(args: {
+        sagaId: string;
+        stepName: string;
+        eventType: string;
+        payload: unknown;
+        tenantId: string | null;
+    }): Promise<void>;
+    /** Pattern 2 outbox reader — used by tests + reaper. Optional. */
+    readOutboxForSaga?(sagaId: string): Promise<{
+        stepName: string;
+        eventType: string;
+        payload: unknown;
+        createdAt: string;
+    }[]>;
+}
+/** § 5.9 — pluggable saga signal bus (Redis stream in production, in-memory
+ *  in tests). All implementations carry an optional `close()` so wired
+ *  services can release connections cleanly at shutdown. */
+export interface SagaSignalBus {
+    emit(args: {
+        sagaId: string;
+        eventType: string;
+        payload: unknown;
+        scope?: "siblings" | "global";
+        to?: string;
+    }): Promise<void>;
+    /**
+     * Polled by `awaitSagaSignal`. Returns a matching signal payload if
+     * one is available, otherwise null. The in-memory bus immediately
+     * resolves; the Redis-stream bus blocks for `blockMs` per call.
+     */
+    consume(args: {
+        sagaId: string;
+        eventType: string;
+        from?: string;
+        predicate?: (payload: unknown) => boolean;
+    }): Promise<unknown | null>;
+    list(args: {
+        sagaId: string;
+        eventType?: string;
+    }): Promise<{
+        sagaId: string;
+        eventType: string;
+        payload: unknown;
+    }[]>;
+    close?(): Promise<void>;
+}
+/** Telemetry audit emitter — matches `@nodii/telemetry.audit.emit` signature. */
+export interface TelemetryAuditEmitter {
+    emit(event: {
+        action: string;
+        target_kind: string;
+        target_id: string | null;
+        payload?: Record<string, unknown>;
+    }): Promise<void>;
+}
+/** § 5.7 — six-tag schema attached by `@sagaCallable`. */
+export interface SagaCallableConfig {
+    require_saga_context: boolean;
+    compensable: boolean;
+    compensators?: readonly string[];
+    idempotent: boolean;
+    on_finalize_safe: boolean;
+    persistFields?: readonly string[];
+}
+/** § 5.2 step options. */
+export interface StepOpts<O> {
+    do: () => Promise<O>;
+    undo?: ((output: O) => Promise<void>) | {
+        fn: (output: O) => Promise<void>;
+        mode: "best-effort";
+    };
+    /** Pattern 2 marker — throws at runtime in v0.1.0 (see Non-goals). */
+    async?: boolean;
+    /** Override idempotency key — opaque to saga, passed straight to idempotency lib. */
+    idempotencyKey?: string;
+    /** Runtime input to the step. Folded into the idempotency-key serialization
+     *  (alongside step name + persistFields) so two calls with the same `name`
+     *  but distinct `input` resolve to distinct cache keys. Spec § 5.4 keys
+     *  off serialized_input, NOT serialized_opts. */
+    input?: unknown;
+    /** Field allow-list for step_outputs persistence (level 1 of D166 resolution). */
+    persistFields?: readonly string[];
+    /** Per-step compensation mode override. */
+    mode?: "strict" | "best-effort";
+}
+/** § 5.2 createSaga options. */
+export interface CreateSagaOpts {
+    type: string;
+    input: unknown;
+    tenantId?: string;
+    triggerTraceId?: string;
+    triggerSpanId?: string;
+    triggerRequestId?: string;
+    parent?: {
+        sagaId: string;
+        traceId: string;
+    } | null;
+    parentRelationship?: "child" | "compensation_of";
+    /** Override for testing — defaults to library uuidv7 generator. */
+    sagaId?: string;
+}
+/** § 5.8 — ResumeContext synthesized at withSaga boundary. */
+export interface ResumeContext {
+    isResume: boolean;
+    sagaId: string;
+}
+/** Public-facing saga handle (returned by createSaga). */
+export interface SagaHandle {
+    readonly id: string;
+    readonly type: string;
+    readonly tenantId: string | null;
+    cancel(reason: string): Promise<void>;
+}
+/** § 5.7 sagaContext interceptor config. */
+export interface SagaContextInterceptorOpts {
+    /** Set of method names tagged `require_saga_context: true`. */
+    requireSagaContextMethods: ReadonlySet<string>;
+    /** D165 'warn' lets the call through; 'reject' returns FAILED_PRECONDITION. */
+    enforce?: "warn" | "reject";
+    /** Optional logger override; defaults to console.warn. */
+    logger?: {
+        warn(msg: string, fields?: Record<string, unknown>): void;
+    };
+}
+/** Minimal call shape the sagaContext interceptor reads. */
+export interface SagaInterceptorCall {
+    metadata: {
+        get(key: string): readonly unknown[];
+    };
+    request: unknown;
+}
+/** SagaAdminService factory opts. */
+export interface SagaAdminServiceOpts {
+    stateStore: SagaStateStore;
+    audit?: TelemetryAuditEmitter;
+}
+/** § 5.10 — minimum justification length per D164. */
+export declare const MIN_JUSTIFICATION_CHARS = 20;
+/** Locked global saga admin permission strings (§ 5.10). */
+export declare const SAGA_ADMIN_PERMISSIONS: {
+    readonly READ: "saga:admin:read";
+    readonly RETRY: "saga:admin:retry";
+    readonly SKIP: "saga:admin:skip";
+    readonly COMPENSATE: "saga:admin:compensate";
+    readonly MANUAL_RESOLVE: "saga:admin:manual_resolve";
+};
+export type SagaAdminPermission = (typeof SAGA_ADMIN_PERMISSIONS)[keyof typeof SAGA_ADMIN_PERMISSIONS];
+export declare class SagaError extends Error {
+    constructor(message: string);
+}
+export declare class SagaNotInitialized extends SagaError {
+    constructor();
+}
+export declare class SagaContextRequired extends SagaError {
+    readonly methodName: string;
+    constructor(methodName: string);
+}
+export declare class SagaStepFailed extends SagaError {
+    readonly stepName: string;
+    readonly cause: unknown;
+    constructor(stepName: string, cause: unknown);
+}
+export declare class SagaCompensationFailed extends SagaError {
+    readonly stepName: string;
+    readonly cause: unknown;
+    constructor(stepName: string, cause: unknown);
+}
+export declare class JustificationRequired extends SagaError {
+    constructor(actual: number);
+}
+export declare class SagaTypeNotRegistered extends SagaError {
+    readonly sagaType: string;
+    constructor(sagaType: string);
+}
+export declare class NoActiveSaga extends SagaError {
+    constructor(api: string);
+}
+export declare class NotImplementedError extends SagaError {
+    constructor(message: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,103 @@
+// Core type surface for @nodii/saga v0.1.0.
+//
+// Spec: planning hub feature_doc serviceId=nodii-libs docKey=saga
+// (D158–D169 + comm doctrine §§ 3–9, 12.3–12.4, 13.1).
+//
+// v0.1.0 ships:
+//   - Public lifecycle (createSaga / step / stepParallel / withSaga / registerSaga)
+//   - Cross-saga primitives (emitSagaSignal / awaitSagaSignal / awaitChildren /
+//     awaitAnySibling / getSiblings) over a pluggable SagaSignalBus
+//   - Discipline tag (@sagaCallable + class registry; D165 six-tag schema)
+//   - sagaContext interceptor (enforces x-nodii-saga-id; D33 violation event)
+//   - SagaAdminService 7-RPC factory (stubs throw NotImplementedError; mandatory
+//     justification validation runs FIRST so audit shapes stay correct)
+//   - Typed-error hierarchy rooted at SagaError
+//   - Pluggable I/O: SagaStateStore, SagaSignalBus, IdempotencyShim, TelemetryAudit
+//
+// Deferred (`// TODO saga-v0.1.x:`):
+//   - Real Drizzle saga_state schema + migrations + RLS fragments
+//   - Real Redis-stream SagaSignalBus
+//   - Reaper / resume-grace-period orchestration
+//   - Real gRPC SagaAdminService wiring + proto generation
+//   - Codegen of sagas.generated.json + lint plugin
+//   - Pattern 2 async-via-outbox (`step({ async: true })`) — throws at runtime
+//   - Cross-saga compensation walking (compensation as library-spawned child saga)
+/** § 5.10 — minimum justification length per D164. */
+export const MIN_JUSTIFICATION_CHARS = 20;
+/** Locked global saga admin permission strings (§ 5.10). */
+export const SAGA_ADMIN_PERMISSIONS = {
+    READ: "saga:admin:read",
+    RETRY: "saga:admin:retry",
+    SKIP: "saga:admin:skip",
+    COMPENSATE: "saga:admin:compensate",
+    MANUAL_RESOLVE: "saga:admin:manual_resolve",
+};
+// ----------------------------------------------------------------------------
+// Typed-error hierarchy.
+export class SagaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SagaError";
+    }
+}
+export class SagaNotInitialized extends SagaError {
+    constructor() {
+        super("@nodii/saga is not initialized — call initSaga({ stateStore, signalBus, idempotency }) at process start.");
+        this.name = "SagaNotInitialized";
+    }
+}
+export class SagaContextRequired extends SagaError {
+    methodName;
+    constructor(methodName) {
+        super(`saga_context_required: method ${methodName} requires x-nodii-saga-id header.`);
+        this.name = "SagaContextRequired";
+        this.methodName = methodName;
+    }
+}
+export class SagaStepFailed extends SagaError {
+    stepName;
+    cause;
+    constructor(stepName, cause) {
+        super(`saga step '${stepName}' failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = "SagaStepFailed";
+        this.stepName = stepName;
+        this.cause = cause;
+    }
+}
+export class SagaCompensationFailed extends SagaError {
+    stepName;
+    cause;
+    constructor(stepName, cause) {
+        super(`saga compensation for step '${stepName}' failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = "SagaCompensationFailed";
+        this.stepName = stepName;
+        this.cause = cause;
+    }
+}
+export class JustificationRequired extends SagaError {
+    constructor(actual) {
+        super(`justification_required: SagaAdminService write RPCs require a justification of at least ${MIN_JUSTIFICATION_CHARS} chars (got ${actual}).`);
+        this.name = "JustificationRequired";
+    }
+}
+export class SagaTypeNotRegistered extends SagaError {
+    sagaType;
+    constructor(sagaType) {
+        super(`saga_type_not_registered: ${sagaType}`);
+        this.name = "SagaTypeNotRegistered";
+        this.sagaType = sagaType;
+    }
+}
+export class NoActiveSaga extends SagaError {
+    constructor(api) {
+        super(`no_active_saga: ${api} must be called inside createSaga/withSaga.`);
+        this.name = "NoActiveSaga";
+    }
+}
+export class NotImplementedError extends SagaError {
+    constructor(message) {
+        super(message);
+        this.name = "NotImplementedError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/uuid.d.ts

@@ -0,0 +1,3 @@
+export declare function uuidv7(now?: number): string;
+export declare function isUuidv7(value: string): boolean;
+//# sourceMappingURL=uuid.d.ts.map

package/dist/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":"AA6CA,wBAAgB,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAwB3C;AAKD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE/C"}

package/dist/uuid.js

@@ -0,0 +1,62 @@
+// UUIDv7 generator — matches @nodii/telemetry's uuid.ts surface (D158 saga_id
+// shape). RFC 9562 §5.7: 48-bit Unix-millisecond timestamp + 12-bit subsec
+// rand + 62-bit rand. Random bits sourced from a CSPRNG (matches Python's
+// `secrets` + Go's `crypto/rand`) — saga ids flow into trigger_trace_id and
+// audit correlation, so they MUST be unpredictable.
+//
+// Uses Node's `crypto.randomFillSync` when available; falls back to the
+// Web Crypto `crypto.getRandomValues` for non-Node runtimes (Bun/Deno/
+// browsers). Math.random() is intentionally NOT used.
+// We resolve the random source lazily on first call so importing this module
+// in an environment without crypto (extremely rare) still loads — the call
+// site will then throw a clear error.
+let _fillRandom = null;
+function fillRandom(buf) {
+    if (_fillRandom == null) {
+        // Prefer Web Crypto (cross-runtime). Node ≥ 19 + Bun + Deno + browsers
+        // all expose globalThis.crypto.getRandomValues.
+        const g = globalThis;
+        if (g.crypto && typeof g.crypto.getRandomValues === "function") {
+            const wc = g.crypto;
+            _fillRandom = (b) => {
+                wc.getRandomValues?.(b);
+            };
+        }
+        else {
+            // Node-only fallback (older Node). require() is intentionally avoided —
+            // a dynamic require would break ESM bundlers. If neither is present,
+            // throw a loud error rather than silently degrade to Math.random().
+            throw new Error("uuidv7: no CSPRNG available — globalThis.crypto.getRandomValues missing");
+        }
+    }
+    _fillRandom(buf);
+}
+function rand16() {
+    const buf = new Uint8Array(2);
+    fillRandom(buf);
+    return ((buf[0] ?? 0) << 8) | (buf[1] ?? 0);
+}
+export function uuidv7(now) {
+    const ms = now ?? Date.now();
+    // 48-bit timestamp.
+    const tsHex = ms.toString(16).padStart(12, "0");
+    // 12-bit rand_a — placed in lower 12 bits of the time_hi_and_version field.
+    const randA = rand16() & 0x0fff;
+    const versionHex = (0x7000 | randA).toString(16).padStart(4, "0");
+    // 2-bit variant (10) + 14-bit rand_b (high half) packed into clock_seq_hi+lo.
+    const rb1 = rand16() & 0x3fff;
+    const variantHex = (0x8000 | rb1).toString(16).padStart(4, "0");
+    // 48-bit rand_b (remainder) for the node id field.
+    const rb2 = rand16();
+    const rb3 = rand16();
+    const rb4 = rand16();
+    const nodeHex = (rb2.toString(16).padStart(4, "0") +
+        rb3.toString(16).padStart(4, "0") +
+        rb4.toString(16).padStart(4, "0")).slice(0, 12);
+    return `${tsHex.slice(0, 8)}-${tsHex.slice(8, 12)}-${versionHex}-${variantHex}-${nodeHex}`;
+}
+const UUIDV7_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export function isUuidv7(value) {
+    return UUIDV7_REGEX.test(value);
+}
+//# sourceMappingURL=uuid.js.map

package/dist/uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.js","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nodii/saga",
-  "version": "0.0.1",
-  "description": "Placeholder for @nodii/saga — implementation lands at v0.1.0",
+  "version": "0.2.0",
+  "description": "Saga orchestration library for the Nodii microservice stack — createSaga + step + stepParallel + cross-saga signals + sagaContext interceptor + SagaAdminService factory + @sagaCallable discipline tag + real PostgresSagaStateStore + RedisSignalBus + Pattern 2 async-step + reaper. Polyglot per D159 (TS + Python + Go).",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,24 +10,50 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./test-doubles": {
+      "types": "./dist/test-doubles/index.d.ts",
+      "default": "./dist/test-doubles/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist",
+    "README.md",
+    "src/migrations/001-saga-state.sql"
+  ],
   "publishConfig": {
-    "access": "public",
-    "provenance": true
+    "access": "public"
   },
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit",
-    "test": "echo 'no tests yet; placeholder package'"
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "@nodii/grpc-auth": "workspace:*",
+    "@nodii/telemetry": "workspace:*",
+    "ioredis": "^5.4.0",
+    "postgres": "^3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    },
+    "postgres": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@nodii/grpc-auth": "workspace:*",
+    "@nodii/telemetry": "workspace:*",
+    "@types/bun": "^1.3.13",
+    "ioredis": "^5.4.0",
+    "postgres": "^3.4.0",
     "typescript": "^5.9.3"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/cognion-nucleus/nodii-libs.git",
+    "url": "git+https://github.com/cognion-nucleus/nodii-libs.git",
     "directory": "ts/saga"
   }
 }

package/src/migrations/001-saga-state.sql

@@ -0,0 +1,79 @@
+-- @nodii/saga v0.1.x — saga_state schema + outbox + indexes.
+--
+-- Spec § 5.5 — 21 user-facing columns (we add next_resume_at since spec §
+-- 5.5 lists it under "lifecycle" alongside completed_at). Plus a small
+-- saga_outbox for Pattern 2 begin/completion events.
+--
+-- This file is the canonical source for the per-service migration; the
+-- `migrate-gen` helper (`src/migrate-gen.ts`) copies the contents into a
+-- service's migrations folder verbatim.
+
+CREATE TABLE IF NOT EXISTS saga_state (
+  id                          TEXT PRIMARY KEY,
+  tenant_id                   TEXT,
+  type                        TEXT NOT NULL,
+  status                      TEXT NOT NULL,
+  current_step                TEXT,
+  step_outputs                JSONB NOT NULL DEFAULT '{}'::jsonb,
+  episode                     INT  NOT NULL DEFAULT 1,
+
+  -- D7 trace coupling
+  trigger_trace_id            TEXT NOT NULL,
+  trigger_span_id             TEXT NOT NULL,
+  trigger_request_id          TEXT NOT NULL,
+
+  -- Cross-saga (D168)
+  parent_saga_id              TEXT,
+  parent_relationship         TEXT NOT NULL DEFAULT 'child',
+  children                    JSONB NOT NULL DEFAULT '[]'::jsonb,
+
+  -- Lifecycle
+  started_at                  TIMESTAMPTZ NOT NULL DEFAULT now(),
+  completed_at                TIMESTAMPTZ,
+  next_resume_at              TIMESTAMPTZ,
+  failure_reason              TEXT,
+  failure_step                TEXT,
+
+  -- Compensation
+  compensation_log            JSONB NOT NULL DEFAULT '[]'::jsonb,
+
+  -- Admin recovery (D164)
+  last_admin_action           TEXT,
+  last_admin_actor_id         TEXT,
+  last_admin_at               TIMESTAMPTZ,
+
+  -- Retroactive amendments
+  input                       JSONB NOT NULL,
+  cancel_reason               TEXT
+);
+
+-- Spec § 5.5 — four indexes.
+CREATE UNIQUE INDEX IF NOT EXISTS saga_state_trigger_trace_id_uniq
+  ON saga_state (trigger_trace_id);
+CREATE INDEX IF NOT EXISTS saga_state_dead_letter_idx
+  ON saga_state (tenant_id, status, started_at);
+CREATE INDEX IF NOT EXISTS saga_state_reaper_idx
+  ON saga_state (next_resume_at)
+  WHERE next_resume_at IS NOT NULL;
+CREATE INDEX IF NOT EXISTS saga_state_parent_idx
+  ON saga_state (parent_saga_id)
+  WHERE parent_saga_id IS NOT NULL;
+
+-- Pattern 2 outbox table. Persisted in the same DB tx as saga_state advance
+-- per § 5.6. The orchestrator consumer worker reads + relays into the
+-- service's broker; the reaper falls back on this table when a
+-- next_resume_at expires.
+CREATE TABLE IF NOT EXISTS saga_outbox (
+  id            UUID PRIMARY KEY,
+  saga_id       TEXT NOT NULL,
+  step_name     TEXT NOT NULL,
+  event_type    TEXT NOT NULL,
+  payload       JSONB NOT NULL,
+  tenant_id     TEXT,
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+  delivered_at  TIMESTAMPTZ
+);
+
+CREATE INDEX IF NOT EXISTS saga_outbox_saga_idx ON saga_outbox (saga_id, created_at);
+CREATE INDEX IF NOT EXISTS saga_outbox_undelivered_idx ON saga_outbox (delivered_at)
+  WHERE delivered_at IS NULL;