@nodii/saga 0.0.1 → 0.2.0

package/dist/idempotency.js

@@ -0,0 +1,44 @@
+// Idempotency shim.
+//
+// `@nodii/saga` v0.1.0 does NOT compute idempotency keys itself — per § 5.4 +
+// Q7 resolution the canonical key form `sha256(saga_id + step_name +
+// serialized_input)` lives in `@nodii/idempotency`. Until that library lands
+// at v0.1.0 (next implementation slot in the DAG), this module ships two
+// in-process shims that exercise the same contract:
+//
+//   - `NoopIdempotency` — always runs the handler; no caching.
+//   - `InMemoryIdempotency` — caches by the locked key form (sha256 hex).
+//     Cached result is returned for subsequent calls with the same key.
+import { createHash } from "node:crypto";
+export class NoopIdempotency {
+    async wrapForSagaStep(args) {
+        return args.handler();
+    }
+}
+export class InMemoryIdempotency {
+    cache = new Map();
+    async wrapForSagaStep(args) {
+        const key = computeKey(args.sagaId, args.stepName, args.serializedInput);
+        if (this.cache.has(key)) {
+            return this.cache.get(key);
+        }
+        const result = await args.handler();
+        this.cache.set(key, result);
+        return result;
+    }
+    /** Test-only — used by the parity-fence fixtures to assert byte equality. */
+    static debugComputeKey(sagaId, stepName, serializedInput) {
+        return computeKey(sagaId, stepName, serializedInput);
+    }
+    reset() {
+        this.cache.clear();
+    }
+}
+function computeKey(sagaId, stepName, serializedInput) {
+    return createHash("sha256")
+        .update(sagaId)
+        .update(stepName)
+        .update(serializedInput)
+        .digest("hex");
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB,EAAE;AACF,8EAA8E;AAC9E,qEAAqE;AACrE,6EAA6E;AAC7E,yEAAyE;AACzE,oDAAoD;AACpD,EAAE;AACF,+DAA+D;AAC/D,0EAA0E;AAC1E,wEAAwE;AAExE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,MAAM,OAAO,eAAe;IAC1B,KAAK,CAAC,eAAe,CAAI,IAKxB;QACC,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;IACxB,CAAC;CACF;AAED,MAAM,OAAO,mBAAmB;IACtB,KAAK,GAAG,IAAI,GAAG,EAAmB,CAAC;IAE3C,KAAK,CAAC,eAAe,CAAI,IAKxB;QACC,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;QACzE,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAM,CAAC;QAClC,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACpC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC5B,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,6EAA6E;IAC7E,MAAM,CAAC,eAAe,CACpB,MAAc,EACd,QAAgB,EAChB,eAAuB;QAEvB,OAAO,UAAU,CAAC,MAAM,EAAE,QAAQ,EAAE,eAAe,CAAC,CAAC;IACvD,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF;AAED,SAAS,UAAU,CACjB,MAAc,EACd,QAAgB,EAChB,eAAuB;IAEvB,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,MAAM,CAAC;SACd,MAAM,CAAC,QAAQ,CAAC;SAChB,MAAM,CAAC,eAAe,CAAC;SACvB,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC"}

package/dist/index.d.ts

@@ -1,3 +1,22 @@
 export declare const LIB_NAME = "saga";
-export declare const VERSION = "0.0.1";
+export declare const VERSION = "0.1.1";
+export { initSaga, getSagaOrNull, _resetForTests } from "./init";
+export type { InitSagaConfig, ResolvedSagaConfig } from "./init";
+export { createSaga, withSaga, step, stepParallel, cancel, currentSaga, } from "./saga";
+export { registerSaga, getRegisteredSaga, hasRegisteredSaga, _resetRegistryForTests, } from "./registry";
+export { emitSagaSignal, awaitSagaSignal, awaitChildren, awaitAnySibling, getSiblings, } from "./signals";
+export { sagaCallable, SAGA_CALLABLE_METADATA, readSagaCallableConfig, readSagaCallableRegistry, _resetDecoratorRegistryForTests, } from "./decorator";
+export type { SagaCallableMethod } from "./decorator";
+export { sagaContext } from "./interceptor";
+export { createSagaAdminServer } from "./admin-service";
+export type { CancelSagaRequest, ForceCompensateRequest, GetSagaRequest, ListSagasRequest, MarkManuallyCompensatedRequest, RetryStepRequest, SagaAdminServer, SkipStepRequest, WriteRpcRequest, } from "./admin-service";
+export { PostgresSagaStateStore, type PostgresSagaStateStoreOpts, } from "./state-store/postgres";
+export { RedisSignalBus, type RedisSignalBusOpts, } from "./signal-bus/redis-stream";
+export { beginAsyncStep, completeAsyncStep, getCompletedAsyncOutput, SagaPausedSentinel, } from "./async-step";
+export { startSagaReaper } from "./reaper";
+export type { SagaReaperOpts, SagaReaperHandle } from "./reaper";
+export { applySagaMigrations, getSagaStateMigrationSQL } from "./migrations";
+export { uuidv7, isUuidv7 } from "./uuid";
+export { MIN_JUSTIFICATION_CHARS, SAGA_ADMIN_PERMISSIONS, SagaError, SagaNotInitialized, SagaContextRequired, SagaStepFailed, SagaCompensationFailed, JustificationRequired, SagaTypeNotRegistered, NoActiveSaga, NotImplementedError, } from "./types";
+export type { CompensationLogEntry, CreateSagaOpts, IdempotencyShim, ResumeContext, SagaAdminPermission, SagaAdminServiceOpts, SagaCallableConfig, SagaContextInterceptorOpts, SagaHandle, SagaInterceptorCall, SagaSignalBus, SagaStateRow, SagaStateStore, SagaStatus, StepOpts, TelemetryAuditEmitter, } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,QAAQ,SAAS,CAAC;AAC/B,eAAO,MAAM,OAAO,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,QAAQ,SAAS,CAAC;AAC/B,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AACjE,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAEjE,OAAO,EACL,UAAU,EACV,QAAQ,EACR,IAAI,EACJ,YAAY,EACZ,MAAM,EACN,WAAW,GACZ,MAAM,QAAQ,CAAC;AAEhB,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,eAAe,EACf,aAAa,EACb,eAAe,EACf,WAAW,GACZ,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,+BAA+B,GAChC,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,YAAY,EACV,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACd,gBAAgB,EAChB,8BAA8B,EAC9B,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,sBAAsB,EACtB,KAAK,0BAA0B,GAChC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,cAAc,EACd,KAAK,kBAAkB,GACxB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAGjE,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAE7E,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAE1C,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EAEtB,SAAS,EACT,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,EACZ,mBAAmB,GACpB,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,0BAA0B,EAC1B,UAAU,EACV,mBAAmB,EACnB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,UAAU,EACV,QAAQ,EACR,qBAAqB,GACtB,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -1,7 +1,37 @@
-// @nodii/saga — placeholder at v0.0.1.
-// Implementation lands at v0.1.0 per the locked feature_doc.
+// @nodii/saga — v0.1.1 public barrel.
 //
-// Spec: https://planning.dev.nucleus-cloud.in/api/v1/feature-docs?serviceId=nodii-libs&docKey=saga
+// Spec: planning hub feature_doc serviceId=nodii-libs docKey=saga.
+// Polyglot ship: TS + Python + Go in parity.
+//
+// REAL implementations land at v0.1.1 for:
+//   - PostgresSagaStateStore (default when `db` is passed to initSaga)
+//   - RedisSignalBus           (default when `redis` + `serviceId` are passed)
+//   - Pattern 2 step({ async: true }) via saga_outbox
+//   - SagaReaper (startSagaReaper)
+//   - applySagaMigrations + getSagaStateMigrationSQL (per-service runner)
+//   - completeAsyncStep / getCompletedAsyncOutput (Pattern 2 consumer side)
+//
+// Test doubles (InMemorySagaStateStore / NoopSignalBus / InMemorySignalBus
+// / NoopIdempotency / InMemoryIdempotency) MOVED to `@nodii/saga/test-doubles`.
 export const LIB_NAME = "saga";
-export const VERSION = "0.0.1";
+export const VERSION = "0.1.1";
+export { initSaga, getSagaOrNull, _resetForTests } from "./init";
+export { createSaga, withSaga, step, stepParallel, cancel, currentSaga, } from "./saga";
+export { registerSaga, getRegisteredSaga, hasRegisteredSaga, _resetRegistryForTests, } from "./registry";
+export { emitSagaSignal, awaitSagaSignal, awaitChildren, awaitAnySibling, getSiblings, } from "./signals";
+export { sagaCallable, SAGA_CALLABLE_METADATA, readSagaCallableConfig, readSagaCallableRegistry, _resetDecoratorRegistryForTests, } from "./decorator";
+export { sagaContext } from "./interceptor";
+export { createSagaAdminServer } from "./admin-service";
+// Production-bound state-store + signal-bus.
+export { PostgresSagaStateStore, } from "./state-store/postgres";
+export { RedisSignalBus, } from "./signal-bus/redis-stream";
+// Pattern 2 async-step + reaper.
+export { beginAsyncStep, completeAsyncStep, getCompletedAsyncOutput, SagaPausedSentinel, } from "./async-step";
+export { startSagaReaper } from "./reaper";
+// Migrations.
+export { applySagaMigrations, getSagaStateMigrationSQL } from "./migrations";
+export { uuidv7, isUuidv7 } from "./uuid";
+export { MIN_JUSTIFICATION_CHARS, SAGA_ADMIN_PERMISSIONS, 
+// Typed-error hierarchy.
+SagaError, SagaNotInitialized, SagaContextRequired, SagaStepFailed, SagaCompensationFailed, JustificationRequired, SagaTypeNotRegistered, NoActiveSaga, NotImplementedError, } from "./types";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,6DAA6D;AAC7D,EAAE;AACF,mGAAmG;AAEnG,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC;AAC/B,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,mEAAmE;AACnE,6CAA6C;AAC7C,EAAE;AACF,2CAA2C;AAC3C,uEAAuE;AACvE,+EAA+E;AAC/E,sDAAsD;AACtD,mCAAmC;AACnC,0EAA0E;AAC1E,4EAA4E;AAC5E,EAAE;AACF,2EAA2E;AAC3E,gFAAgF;AAEhF,MAAM,CAAC,MAAM,QAAQ,GAAG,MAAM,CAAC;AAC/B,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAGjE,OAAO,EACL,UAAU,EACV,QAAQ,EACR,IAAI,EACJ,YAAY,EACZ,MAAM,EACN,WAAW,GACZ,MAAM,QAAQ,CAAC;AAEhB,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,eAAe,EACf,aAAa,EACb,eAAe,EACf,WAAW,GACZ,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,YAAY,EACZ,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,+BAA+B,GAChC,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAaxD,6CAA6C;AAC7C,OAAO,EACL,sBAAsB,GAEvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,cAAc,GAEf,MAAM,2BAA2B,CAAC;AAEnC,iCAAiC;AACjC,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG3C,cAAc;AACd,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAE7E,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAE1C,OAAO,EACL,uBAAuB,EACvB,sBAAsB;AACtB,yBAAyB;AACzB,SAAS,EACT,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,YAAY,EACZ,mBAAmB,GACpB,MAAM,SAAS,CAAC"}

package/dist/init.d.ts

@@ -0,0 +1,45 @@
+import { type IdempotencyShim, type SagaSignalBus, type SagaStateStore, type TelemetryAuditEmitter } from "./types";
+type SqlClient = {
+    unsafe: (sql: string, args?: unknown[]) => Promise<any>;
+};
+type RedisLike = import("ioredis").Redis;
+export interface InitSagaConfig {
+    /** Explicit state store override; if omitted, `db` must be provided. */
+    stateStore?: SagaStateStore;
+    /** Explicit signal bus override; if omitted, `redis` + `serviceId` are
+     *  required to construct the default RedisSignalBus. */
+    signalBus?: SagaSignalBus;
+    /** Postgres client (postgres.js shape). Required unless `stateStore`. */
+    db?: SqlClient;
+    /** ioredis client. Required unless `signalBus`. */
+    redis?: RedisLike;
+    /** Used to namespace the Redis stream + idempotency keys. Required
+     *  unless `signalBus` is provided. */
+    serviceId?: string;
+    /** Idempotency shim; defaults to in-process InMemoryIdempotency until
+     *  @nodii/idempotency v0.1.0 publishes. */
+    idempotency?: IdempotencyShim;
+    /** D33 audit emitter; optional. */
+    telemetryAudit?: TelemetryAuditEmitter;
+    /** Logger used by the sagaContext interceptor + async-step warn path. */
+    logger?: {
+        warn(msg: string, fields?: Record<string, unknown>): void;
+    };
+}
+export interface ResolvedSagaConfig {
+    stateStore: SagaStateStore;
+    signalBus: SagaSignalBus;
+    idempotency: IdempotencyShim;
+    telemetryAudit: TelemetryAuditEmitter | null;
+    logger: {
+        warn(msg: string, fields?: Record<string, unknown>): void;
+    };
+    serviceId: string | null;
+}
+export declare function initSaga(config?: InitSagaConfig): void;
+export declare function requireSaga(): ResolvedSagaConfig;
+export declare function getSagaOrNull(): ResolvedSagaConfig | null;
+/** Test-only reset; NOT exported through the public barrel. */
+export declare function _resetForTests(): void;
+export {};
+//# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAgBA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAE3B,MAAM,SAAS,CAAC;AAEjB,KAAK,SAAS,GAAG;IAEf,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CACzD,CAAC;AAEF,KAAK,SAAS,GAAG,OAAO,SAAS,EAAE,KAAK,CAAC;AAEzC,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B;4DACwD;IACxD,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,yEAAyE;IACzE,EAAE,CAAC,EAAE,SAAS,CAAC;IACf,mDAAmD;IACnD,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;0CACsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;+CAC2C;IAC3C,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,mCAAmC;IACnC,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACvC,yEAAyE;IACzE,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;KAAE,CAAC;CACxE;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,cAAc,CAAC;IAC3B,SAAS,EAAE,aAAa,CAAC;IACzB,WAAW,EAAE,eAAe,CAAC;IAC7B,cAAc,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC7C,MAAM,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;KAAE,CAAC;IACtE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAID,wBAAgB,QAAQ,CAAC,MAAM,GAAE,cAAmB,GAAG,IAAI,CA0D1D;AAED,wBAAgB,WAAW,IAAI,kBAAkB,CAKhD;AAED,wBAAgB,aAAa,IAAI,kBAAkB,GAAG,IAAI,CAEzD;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,IAAI,IAAI,CAErC"}

package/dist/init.js

@@ -0,0 +1,86 @@
+// initSaga — process-local bootstrap.
+//
+// Spec § 5.15. Real production posture (v0.1.1+):
+//   - Default state store: `PostgresSagaStateStore` (requires `db`).
+//   - Default signal bus: `RedisSignalBus` (requires `redis` + `serviceId`).
+//   - Default idempotency: `InMemoryIdempotency` (until @nodii/idempotency
+//     lands — this remains a temporary shim that exercises the contract).
+//
+// Test doubles (`InMemorySagaStateStore`, `NoopSignalBus`,
+// `InMemorySignalBus`) live under `./test-doubles` and must be wired
+// explicitly — they are NOT defaults.
+import { InMemoryIdempotency } from "./idempotency";
+import { PostgresSagaStateStore } from "./state-store/postgres";
+import { RedisSignalBus } from "./signal-bus/redis-stream";
+import { NoopSignalBus } from "./test-doubles/in-memory-signal-bus";
+import { SagaNotInitialized, } from "./types";
+let resolved = null;
+export function initSaga(config = {}) {
+    if (resolved) {
+        // eslint-disable-next-line no-console
+        console.warn("[@nodii/saga] initSaga() called more than once; ignoring subsequent call.");
+        return;
+    }
+    // Resolve state store.
+    let stateStore;
+    if (config.stateStore) {
+        stateStore = config.stateStore;
+    }
+    else if (config.db) {
+        stateStore = new PostgresSagaStateStore({ sql: config.db });
+    }
+    else {
+        throw new Error("@nodii/saga: initSaga requires either { stateStore } or { db }. " +
+            "For unit tests, import `InMemorySagaStateStore` from '@nodii/saga/test-doubles' and pass it explicitly.");
+    }
+    // Resolve signal bus.
+    let signalBus;
+    if (config.signalBus) {
+        signalBus = config.signalBus;
+    }
+    else if (config.redis && config.serviceId) {
+        signalBus = new RedisSignalBus({
+            redis: config.redis,
+            serviceId: config.serviceId,
+        });
+    }
+    else if (config.stateStore && !config.db) {
+        // Test-only ergonomics — when a caller passes an explicit stateStore
+        // (clearly opting out of the Postgres default) we tolerate an
+        // implicit NoopSignalBus so unit tests that don't exercise signals
+        // don't need to wire one. Production wiring (`db` set) MUST supply a
+        // real signal bus.
+        signalBus = new NoopSignalBus();
+    }
+    else {
+        throw new Error("@nodii/saga: initSaga requires either { signalBus } or { redis, serviceId }. " +
+            "For unit tests, import `NoopSignalBus`/`InMemorySignalBus` from '@nodii/saga/test-doubles' and pass it explicitly.");
+    }
+    resolved = {
+        stateStore,
+        signalBus,
+        idempotency: config.idempotency ?? new InMemoryIdempotency(),
+        telemetryAudit: config.telemetryAudit ?? null,
+        serviceId: config.serviceId ?? null,
+        logger: config.logger ?? {
+            warn(msg, fields) {
+                // eslint-disable-next-line no-console
+                console.warn(`[@nodii/saga] ${msg}`, fields ?? {});
+            },
+        },
+    };
+}
+export function requireSaga() {
+    if (!resolved) {
+        throw new SagaNotInitialized();
+    }
+    return resolved;
+}
+export function getSagaOrNull() {
+    return resolved;
+}
+/** Test-only reset; NOT exported through the public barrel. */
+export function _resetForTests() {
+    resolved = null;
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,kDAAkD;AAClD,qEAAqE;AACrE,6EAA6E;AAC7E,2EAA2E;AAC3E,0EAA0E;AAC1E,EAAE;AACF,2DAA2D;AAC3D,qEAAqE;AACrE,sCAAsC;AAEtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACpE,OAAO,EAKL,kBAAkB,GACnB,MAAM,SAAS,CAAC;AAwCjB,IAAI,QAAQ,GAA8B,IAAI,CAAC;AAE/C,MAAM,UAAU,QAAQ,CAAC,SAAyB,EAAE;IAClD,IAAI,QAAQ,EAAE,CAAC;QACb,sCAAsC;QACtC,OAAO,CAAC,IAAI,CACV,2EAA2E,CAC5E,CAAC;QACF,OAAO;IACT,CAAC;IAED,uBAAuB;IACvB,IAAI,UAA0B,CAAC;IAC/B,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACtB,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IACjC,CAAC;SAAM,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;QACrB,UAAU,GAAG,IAAI,sBAAsB,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;IAC9D,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CACb,kEAAkE;YAChE,yGAAyG,CAC5G,CAAC;IACJ,CAAC;IAED,sBAAsB;IACtB,IAAI,SAAwB,CAAC;IAC7B,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACrB,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;IAC/B,CAAC;SAAM,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QAC5C,SAAS,GAAG,IAAI,cAAc,CAAC;YAC7B,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC,CAAC;IACL,CAAC;SAAM,IAAI,MAAM,CAAC,UAAU,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QAC3C,qEAAqE;QACrE,8DAA8D;QAC9D,mEAAmE;QACnE,qEAAqE;QACrE,mBAAmB;QACnB,SAAS,GAAG,IAAI,aAAa,EAAE,CAAC;IAClC,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CACb,+EAA+E;YAC7E,oHAAoH,CACvH,CAAC;IACJ,CAAC;IAED,QAAQ,GAAG;QACT,UAAU;QACV,SAAS;QACT,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,IAAI,mBAAmB,EAAE;QAC5D,cAAc,EAAE,MAAM,CAAC,cAAc,IAAI,IAAI;QAC7C,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,IAAI;QACnC,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI;YACvB,IAAI,CAAC,GAAG,EAAE,MAAM;gBACd,sCAAsC;gBACtC,OAAO,CAAC,IAAI,CAAC,iBAAiB,GAAG,EAAE,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC;YACrD,CAAC;SACF;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,kBAAkB,EAAE,CAAC;IACjC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,cAAc;IAC5B,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC"}

package/dist/interceptor.d.ts

@@ -0,0 +1,5 @@
+import { type SagaContextInterceptorOpts, type SagaInterceptorCall } from "./types";
+type Handler = (call: SagaInterceptorCall) => Promise<unknown>;
+export declare function sagaContext(opts: SagaContextInterceptorOpts): (methodName: string, next: Handler) => Handler;
+export {};
+//# sourceMappingURL=interceptor.d.ts.map

package/dist/interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptor.d.ts","sourceRoot":"","sources":["../src/interceptor.ts"],"names":[],"mappings":"AAUA,OAAO,EACL,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,EAEzB,MAAM,SAAS,CAAC;AAEjB,KAAK,OAAO,GAAG,CAAC,IAAI,EAAE,mBAAmB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE/D,wBAAgB,WAAW,CAAC,IAAI,EAAE,0BAA0B,IAExD,YAAY,MAAM,EAClB,MAAM,OAAO,KACZ,OAAO,CAwBX"}

package/dist/interceptor.js

@@ -0,0 +1,34 @@
+// sagaContext interceptor — § 5.7 + comm doctrine § 13.3.
+//
+// Server-side. Composed inside the auth wrapper:
+//   withLoggingUnary > withAuditUnary > withAuthUnary > sagaContext > handler
+//
+// Reads x-nodii-saga-id; if absent and the method is tagged
+// `require_saga_context: true`, emits a D33 `saga_context_required_violation`
+// audit row and either warns (default) or rejects depending on `enforce`.
+import { requireSaga } from "./init";
+import { SagaContextRequired, } from "./types";
+export function sagaContext(opts) {
+    return function interceptorFactory(methodName, next) {
+        return async (call) => {
+            const sagaIdValues = call.metadata.get("x-nodii-saga-id");
+            const sagaId = sagaIdValues[0] ?? "";
+            if (!sagaId && opts.requireSagaContextMethods.has(methodName)) {
+                const cfg = requireSaga();
+                await cfg.telemetryAudit?.emit({
+                    action: "saga_context_required_violation",
+                    target_kind: "grpc_method",
+                    target_id: methodName,
+                    payload: { method: methodName },
+                });
+                const enforce = opts.enforce ?? "warn";
+                if (enforce === "reject") {
+                    throw new SagaContextRequired(methodName);
+                }
+                (opts.logger ?? cfg.logger).warn(`saga_context_required: ${methodName} called without x-nodii-saga-id (warn mode)`, { method: methodName });
+            }
+            return next(call);
+        };
+    };
+}
+//# sourceMappingURL=interceptor.js.map

package/dist/interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptor.js","sourceRoot":"","sources":["../src/interceptor.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,EAAE;AACF,iDAAiD;AACjD,8EAA8E;AAC9E,EAAE;AACF,4DAA4D;AAC5D,8EAA8E;AAC9E,0EAA0E;AAE1E,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAGL,mBAAmB,GACpB,MAAM,SAAS,CAAC;AAIjB,MAAM,UAAU,WAAW,CAAC,IAAgC;IAC1D,OAAO,SAAS,kBAAkB,CAChC,UAAkB,EAClB,IAAa;QAEb,OAAO,KAAK,EAAE,IAAyB,EAAoB,EAAE;YAC3D,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;YAC1D,MAAM,MAAM,GAAI,YAAY,CAAC,CAAC,CAAwB,IAAI,EAAE,CAAC;YAC7D,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,yBAAyB,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC9D,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;gBAC1B,MAAM,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC;oBAC7B,MAAM,EAAE,iCAAiC;oBACzC,WAAW,EAAE,aAAa;oBAC1B,SAAS,EAAE,UAAU;oBACrB,OAAO,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE;iBAChC,CAAC,CAAC;gBACH,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,MAAM,CAAC;gBACvC,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;oBACzB,MAAM,IAAI,mBAAmB,CAAC,UAAU,CAAC,CAAC;gBAC5C,CAAC;gBACD,CAAC,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAC9B,0BAA0B,UAAU,6CAA6C,EACjF,EAAE,MAAM,EAAE,UAAU,EAAE,CACvB,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,19 @@
+type SqlClient = {
+    unsafe: (sql: string, args?: unknown[]) => Promise<any>;
+};
+export declare function getSagaStateMigrationSQL(): string;
+/**
+ * Apply the saga_state + saga_outbox migrations idempotently. Safe to call
+ * at every service boot — the DDL uses `IF NOT EXISTS` throughout.
+ *
+ * postgres.js refuses to send multi-statement queries through the
+ * extended-query protocol — even with no args — so we split on the
+ * literal semicolon-followed-by-newline boundaries we control in the
+ * shipped `.sql` file. Comments (lines starting `--`) and pure
+ * whitespace blocks are skipped.
+ */
+export declare function applySagaMigrations(sql: SqlClient): Promise<void>;
+/** Internal — exported only for unit-test coverage on the splitter. */
+export declare function splitStatements(ddl: string): string[];
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/migrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAOA,KAAK,SAAS,GAAG;IAEf,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CACzD,CAAC;AA8DF,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvE;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAerD"}

package/dist/migrations/index.js

@@ -0,0 +1,106 @@
+// Migration helper — applies the saga_state + saga_outbox DDL idempotently.
+//
+// Services consume this via `applySagaMigrations(sql)` at boot or via the
+// per-service migration runner. The SQL is shipped alongside this module
+// as `001-saga-state.sql` so a service that uses a different runner
+// (Flyway, golang-migrate, alembic, etc.) can copy it directly.
+/**
+ * Canonical saga_state + saga_outbox migration. Kept inline here (NOT
+ * read from disk at runtime) so the published artifact + the synthetic-
+ * consumer's `file:` install both work without a side-channel for the
+ * .sql file. The source-of-truth copy lives at
+ * `src/migrations/001-saga-state.sql` for downstream services that
+ * prefer running it via Flyway / sqlx-cli / golang-migrate / alembic.
+ */
+const SAGA_STATE_MIGRATION_SQL = `
+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,
+  trigger_trace_id            TEXT NOT NULL,
+  trigger_span_id             TEXT NOT NULL,
+  trigger_request_id          TEXT NOT NULL,
+  parent_saga_id              TEXT,
+  parent_relationship         TEXT NOT NULL DEFAULT 'child',
+  children                    JSONB NOT NULL DEFAULT '[]'::jsonb,
+  started_at                  TIMESTAMPTZ NOT NULL DEFAULT now(),
+  completed_at                TIMESTAMPTZ,
+  next_resume_at              TIMESTAMPTZ,
+  failure_reason              TEXT,
+  failure_step                TEXT,
+  compensation_log            JSONB NOT NULL DEFAULT '[]'::jsonb,
+  last_admin_action           TEXT,
+  last_admin_actor_id         TEXT,
+  last_admin_at               TIMESTAMPTZ,
+  input                       JSONB NOT NULL,
+  cancel_reason               TEXT
+);
+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;
+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;
+`.trim();
+export function getSagaStateMigrationSQL() {
+    return SAGA_STATE_MIGRATION_SQL;
+}
+/**
+ * Apply the saga_state + saga_outbox migrations idempotently. Safe to call
+ * at every service boot — the DDL uses `IF NOT EXISTS` throughout.
+ *
+ * postgres.js refuses to send multi-statement queries through the
+ * extended-query protocol — even with no args — so we split on the
+ * literal semicolon-followed-by-newline boundaries we control in the
+ * shipped `.sql` file. Comments (lines starting `--`) and pure
+ * whitespace blocks are skipped.
+ */
+export async function applySagaMigrations(sql) {
+    const ddl = getSagaStateMigrationSQL();
+    const statements = splitStatements(ddl);
+    for (const stmt of statements) {
+        await sql.unsafe(stmt);
+    }
+}
+/** Internal — exported only for unit-test coverage on the splitter. */
+export function splitStatements(ddl) {
+    const out = [];
+    let buf = "";
+    for (const rawLine of ddl.split("\n")) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("--"))
+            continue;
+        buf = buf ? `${buf}\n${rawLine}` : rawLine;
+        if (line.endsWith(";")) {
+            const cleaned = buf.trim();
+            if (cleaned)
+                out.push(cleaned);
+            buf = "";
+        }
+    }
+    if (buf.trim())
+        out.push(buf.trim());
+    return out;
+}
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,oEAAoE;AACpE,gEAAgE;AAOhE;;;;;;;GAOG;AACH,MAAM,wBAAwB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkDhC,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,UAAU,wBAAwB;IACtC,OAAO,wBAAwB,CAAC;AAClC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,GAAc;IACtD,MAAM,GAAG,GAAG,wBAAwB,EAAE,CAAC;IACvC,MAAM,UAAU,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACxC,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;AACH,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS;QAC7C,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;QAC3C,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;YAC3B,IAAI,OAAO;gBAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC/B,GAAG,GAAG,EAAE,CAAC;QACX,CAAC;IACH,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,EAAE;QAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;IACrC,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/reaper.d.ts

@@ -0,0 +1,27 @@
+import type { SagaStateRow } from "./types";
+export interface SagaReaperOpts {
+    /** How often to scan; spec default = 5 * 60_000 ms (5 min). */
+    intervalMs?: number;
+    /** Grace period past `next_resume_at` before finalizing. Spec default
+     *  = 24 * 60 * 60_000 (24h). For tests, set to a small value. */
+    gracePeriodMs?: number;
+    /** Test hook — replaces setInterval/clearInterval for deterministic
+     *  per-iteration control. */
+    scheduler?: {
+        setInterval(handler: () => void, ms: number): unknown;
+        clearInterval(token: unknown): void;
+    };
+    /** Test hook — fires on every transition so tests can assert. */
+    onTransition?: (saga: SagaStateRow) => void;
+}
+export interface SagaReaperHandle {
+    /** Run one iteration synchronously (for tests + manual triggers). */
+    runOnce(): Promise<{
+        scanned: number;
+        reaped: number;
+    }>;
+    /** Stop the periodic loop. */
+    stop(): void;
+}
+export declare function startSagaReaper(opts?: SagaReaperOpts): SagaReaperHandle;
+//# sourceMappingURL=reaper.d.ts.map

package/dist/reaper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reaper.d.ts","sourceRoot":"","sources":["../src/reaper.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;qEACiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;iCAC6B;IAC7B,SAAS,CAAC,EAAE;QACV,WAAW,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QACtD,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;KACrC,CAAC;IACF,iEAAiE;IACjE,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,OAAO,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,8BAA8B;IAC9B,IAAI,IAAI,IAAI,CAAC;CACd;AAED,wBAAgB,eAAe,CAAC,IAAI,GAAE,cAAmB,GAAG,gBAAgB,CAuE3E"}

package/dist/reaper.js

@@ -0,0 +1,79 @@
+// Saga reaper — § 5.8 + comm doctrine § 4.2.
+//
+// A per-service scheduled task that scans for `status='paused' AND
+// next_resume_at < now() - grace` and finalizes to `technical_failure`
+// with `failure_reason='resume_signal_timeout'`. M17 alerting metric
+// fires once per transition.
+//
+// `startSagaReaper` returns a `stop()` handle. Tests use a tight
+// `intervalMs` (e.g. 50) so the loop runs deterministically; production
+// uses the spec default of 5 min.
+import { requireSaga } from "./init";
+export function startSagaReaper(opts = {}) {
+    const intervalMs = opts.intervalMs ?? 5 * 60_000;
+    const gracePeriodMs = opts.gracePeriodMs ?? 24 * 60 * 60_000;
+    const scheduler = opts.scheduler ??
+        {
+            setInterval(h, ms) {
+                return setInterval(h, ms);
+            },
+            clearInterval(token) {
+                clearInterval(token);
+            },
+        };
+    let running = false;
+    const runOnce = async () => {
+        if (running)
+            return { scanned: 0, reaped: 0 };
+        running = true;
+        try {
+            const cfg = requireSaga();
+            if (!cfg.stateStore.listStalePaused) {
+                cfg.logger.warn("saga reaper: configured state store does not implement listStalePaused; reaper is a no-op", {});
+                return { scanned: 0, reaped: 0 };
+            }
+            const cutoffIso = new Date(Date.now() - gracePeriodMs).toISOString();
+            const stale = await cfg.stateStore.listStalePaused(cutoffIso);
+            let reaped = 0;
+            for (const row of stale) {
+                try {
+                    await cfg.stateStore.updateSagaStatus(row.id, {
+                        status: "technical_failure",
+                        failure_reason: "resume_signal_timeout",
+                        completed_at: new Date().toISOString(),
+                    });
+                    if (cfg.telemetryAudit) {
+                        await cfg.telemetryAudit.emit({
+                            action: "saga_reaper_grace_expired",
+                            target_kind: "saga",
+                            target_id: row.id,
+                            payload: { type: row.type, grace_ms: gracePeriodMs },
+                        });
+                    }
+                    opts.onTransition?.(row);
+                    reaped += 1;
+                }
+                catch (err) {
+                    cfg.logger.warn("saga reaper: failed to finalize paused saga", {
+                        saga_id: row.id,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            return { scanned: stale.length, reaped };
+        }
+        finally {
+            running = false;
+        }
+    };
+    const token = scheduler.setInterval(() => {
+        void runOnce();
+    }, intervalMs);
+    return {
+        runOnce,
+        stop() {
+            scheduler.clearInterval(token);
+        },
+    };
+}
+//# sourceMappingURL=reaper.js.map

package/dist/reaper.js.map

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

package/dist/registry.d.ts

@@ -0,0 +1,7 @@
+type SagaFn = (input: unknown) => Promise<unknown>;
+export declare function registerSaga<I, O>(type: string, fn: (input: I) => Promise<O>): void;
+export declare function getRegisteredSaga(type: string): SagaFn;
+export declare function hasRegisteredSaga(type: string): boolean;
+export declare function _resetRegistryForTests(): void;
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAQA,KAAK,MAAM,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAInD,wBAAgB,YAAY,CAAC,CAAC,EAAE,CAAC,EAC/B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3B,IAAI,CAEN;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAItD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/registry.js

@@ -0,0 +1,23 @@
+// registerSaga — process-local registry per § 5.8 (D167).
+//
+// Used by the resume primitive (registry lookup keyed by saga.type) and by
+// adversarial test paths that need to look up a missing entry to assert
+// SagaTypeNotRegistered.
+import { SagaTypeNotRegistered } from "./types";
+const registry = new Map();
+export function registerSaga(type, fn) {
+    registry.set(type, fn);
+}
+export function getRegisteredSaga(type) {
+    const fn = registry.get(type);
+    if (!fn)
+        throw new SagaTypeNotRegistered(type);
+    return fn;
+}
+export function hasRegisteredSaga(type) {
+    return registry.has(type);
+}
+export function _resetRegistryForTests() {
+    registry.clear();
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,EAAE;AACF,2EAA2E;AAC3E,wEAAwE;AACxE,yBAAyB;AAEzB,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAIhD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;AAE3C,MAAM,UAAU,YAAY,CAC1B,IAAY,EACZ,EAA4B;IAE5B,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,EAAY,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,EAAE;QAAE,MAAM,IAAI,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,QAAQ,CAAC,KAAK,EAAE,CAAC;AACnB,CAAC"}