@nodii/saga 0.0.1 → 0.2.0

package/dist/admin-service.d.ts

@@ -0,0 +1,55 @@
+import { type SagaAdminServiceOpts, type SagaStateRow } from "./types";
+export interface GetSagaRequest {
+    sagaId: string;
+}
+export interface ListSagasRequest {
+    tenantId?: string;
+    status?: string;
+    type?: string;
+    limit?: number;
+}
+export interface WriteRpcRequest {
+    sagaId: string;
+    justification: string;
+    actorId?: string;
+}
+export interface RetryStepRequest extends WriteRpcRequest {
+    stepName: string;
+}
+export interface SkipStepRequest extends WriteRpcRequest {
+    stepName: string;
+}
+export interface ForceCompensateRequest extends WriteRpcRequest {
+    fromStep?: string;
+}
+export interface MarkManuallyCompensatedRequest extends WriteRpcRequest {
+    resolutionRef?: string;
+}
+export interface CancelSagaRequest extends WriteRpcRequest {
+    reason: string;
+}
+export interface SagaAdminServer {
+    GetSaga(req: GetSagaRequest): Promise<{
+        saga: SagaStateRow | null;
+    }>;
+    ListSagas(req: ListSagasRequest): Promise<{
+        sagas: SagaStateRow[];
+    }>;
+    RetryStep(req: RetryStepRequest): Promise<{
+        ok: true;
+    }>;
+    SkipStep(req: SkipStepRequest): Promise<{
+        ok: true;
+    }>;
+    ForceCompensate(req: ForceCompensateRequest): Promise<{
+        ok: true;
+    }>;
+    MarkManuallyCompensated(req: MarkManuallyCompensatedRequest): Promise<{
+        ok: true;
+    }>;
+    CancelSaga(req: CancelSagaRequest): Promise<{
+        ok: true;
+    }>;
+}
+export declare function createSagaAdminServer(opts: SagaAdminServiceOpts): SagaAdminServer;
+//# sourceMappingURL=admin-service.d.ts.map

package/dist/admin-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-service.d.ts","sourceRoot":"","sources":["../src/admin-service.ts"],"names":[],"mappings":"AASA,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,YAAY,EAGlB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,8BAA+B,SAAQ,eAAe;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACrE,SAAS,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC,CAAC;IACrE,SAAS,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IACxD,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IACtD,eAAe,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IACpE,uBAAuB,CACrB,GAAG,EAAE,8BAA8B,GAClC,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;IACzB,UAAU,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC;CAC3D;AAED,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,oBAAoB,GACzB,eAAe,CAsKjB"}

package/dist/admin-service.js

@@ -0,0 +1,161 @@
+// SagaAdminService factory — § 5.10. v0.1.0 ships the JSON-RPC-style
+// surface; the real gRPC proto + codegen + Pane wiring lands in
+// saga-v0.1.x. Stubs for the 4 write RPCs throw NotImplementedError AFTER
+// validating `justification` — that keeps the audit shape correct in the
+// rejection path.
+//
+// Two read RPCs (`GetSaga`, `ListSagas`) are fully wired against the
+// pluggable SagaStateStore.
+import { JustificationRequired, MIN_JUSTIFICATION_CHARS, } from "./types";
+export function createSagaAdminServer(opts) {
+    const { stateStore, audit } = opts;
+    const validateJustification = (justification) => {
+        if (typeof justification !== "string" ||
+            justification.length < MIN_JUSTIFICATION_CHARS) {
+            throw new JustificationRequired(typeof justification === "string" ? justification.length : 0);
+        }
+    };
+    const emitAdminAudit = async (action, sagaId, payload) => {
+        if (!audit)
+            return;
+        await audit.emit({
+            action,
+            target_kind: "saga",
+            target_id: sagaId,
+            payload,
+        });
+    };
+    return {
+        async GetSaga(req) {
+            await emitAdminAudit("saga_admin_get_saga", req.sagaId);
+            const saga = await stateStore.getSaga(req.sagaId);
+            return { saga };
+        },
+        async ListSagas(req) {
+            await emitAdminAudit("saga_admin_list_sagas", req.tenantId ?? "*");
+            // Per § 5.5 list() is optional on SagaStateStore — stores that omit it
+            // return []. Production-bound stores (Drizzle) MUST implement it.
+            const rows = stateStore.list
+                ? await stateStore.list({
+                    tenantId: req.tenantId,
+                    status: req.status,
+                    type: req.type,
+                })
+                : [];
+            const limit = req.limit ?? 100;
+            return { sagas: rows.slice(0, limit) };
+        },
+        async RetryStep(req) {
+            validateJustification(req.justification);
+            await emitAdminAudit("saga_admin_retry_step", req.sagaId, {
+                step: req.stepName,
+                justification: req.justification,
+            });
+            const now = new Date().toISOString();
+            // Reset failure state + transition back to running. The next
+            // saga-runner tick on this row picks up at current_step.
+            await stateStore.updateSagaStatus(req.sagaId, {
+                status: "active",
+                current_step: req.stepName,
+                failure_reason: null,
+                failure_step: null,
+                last_admin_action: "retry_step",
+                last_admin_actor_id: req.actorId ?? null,
+                last_admin_at: now,
+            });
+            return { ok: true };
+        },
+        async SkipStep(req) {
+            validateJustification(req.justification);
+            await emitAdminAudit("saga_admin_skip_step", req.sagaId, {
+                step: req.stepName,
+                justification: req.justification,
+            });
+            const now = new Date().toISOString();
+            // Record the skip + transition back to running. The skipped step
+            // is marked in step_outputs so the saga handler can branch on it.
+            await stateStore.appendStepOutput(req.sagaId, req.stepName, {
+                admin_skipped: true,
+                skipped_at: now,
+                actor_id: req.actorId ?? null,
+                justification: req.justification,
+            });
+            await stateStore.updateSagaStatus(req.sagaId, {
+                status: "active",
+                current_step: req.stepName,
+                failure_reason: null,
+                failure_step: null,
+                last_admin_action: "skip_step",
+                last_admin_actor_id: req.actorId ?? null,
+                last_admin_at: now,
+            });
+            return { ok: true };
+        },
+        async ForceCompensate(req) {
+            validateJustification(req.justification);
+            await emitAdminAudit("saga_admin_force_compensate", req.sagaId, {
+                from_step: req.fromStep,
+                justification: req.justification,
+            });
+            const now = new Date().toISOString();
+            // Transition to compensating. The reaper picks up paused/running →
+            // compensating rows and runs undo() handlers in reverse step order
+            // from current_step (defaulting to fromStep when provided).
+            await stateStore.updateSagaStatus(req.sagaId, {
+                status: "compensating",
+                current_step: req.fromStep ?? null,
+                last_admin_action: "force_compensate",
+                last_admin_actor_id: req.actorId ?? null,
+                last_admin_at: now,
+            });
+            return { ok: true };
+        },
+        async MarkManuallyCompensated(req) {
+            validateJustification(req.justification);
+            await emitAdminAudit("saga_admin_mark_manually_compensated", req.sagaId, {
+                resolution_ref: req.resolutionRef,
+                justification: req.justification,
+            });
+            const now = new Date().toISOString();
+            // Terminal: operator confirms out-of-band remediation. Records
+            // resolution_ref in the compensation_log for audit traceability.
+            await stateStore.appendCompensationLog(req.sagaId, {
+                step_name: "<manual>",
+                // "undone" is the closest outcome semantic: out-of-band remediation
+                // by an operator counts as the compensation having succeeded; the
+                // resolution_ref + admin action audit trail provide the manual-
+                // override traceability.
+                outcome: "undone",
+                ts: now,
+                error: req.resolutionRef
+                    ? `manual_resolution_ref=${req.resolutionRef}`
+                    : "manual_resolution",
+            });
+            await stateStore.updateSagaStatus(req.sagaId, {
+                status: "compensated_manual",
+                completed_at: now,
+                last_admin_action: "mark_manually_compensated",
+                last_admin_actor_id: req.actorId ?? null,
+                last_admin_at: now,
+            });
+            return { ok: true };
+        },
+        async CancelSaga(req) {
+            validateJustification(req.justification);
+            await emitAdminAudit("saga_admin_cancel", req.sagaId, {
+                reason: req.reason,
+                justification: req.justification,
+            });
+            await stateStore.updateSagaStatus(req.sagaId, {
+                status: "cancelled",
+                cancel_reason: req.reason,
+                completed_at: new Date().toISOString(),
+                last_admin_action: "cancel",
+                last_admin_actor_id: req.actorId ?? null,
+                last_admin_at: new Date().toISOString(),
+            });
+            return { ok: true };
+        },
+    };
+}
+//# sourceMappingURL=admin-service.js.map

package/dist/admin-service.js.map

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

package/dist/async-step.d.ts

@@ -0,0 +1,43 @@
+import { SagaError, type StepOpts } from "./types";
+/** Internal sentinel — thrown to unwind a saga at the async-step boundary
+ *  without triggering compensation. `createSaga` catches and treats as
+ *  "saga paused, return current handle". */
+export declare class SagaPausedSentinel extends SagaError {
+    readonly sagaId: string;
+    readonly stepName: string;
+    constructor(sagaId: string, stepName: string);
+}
+/**
+ * Begin a Pattern 2 step. Called from `step()` when `opts.async === true`.
+ *
+ * Side effects:
+ *   - saga_state.status → 'paused', current_step = name, next_resume_at = now + grace.
+ *   - saga_outbox row written: { event_type: 'saga.step.<name>.begin', payload }
+ *   - SagaPausedSentinel thrown — control exits the saga's `fn`.
+ */
+export declare function beginAsyncStep<O>(name: string, opts: StepOpts<O>): Promise<O>;
+/**
+ * Mark an async (Pattern 2) step as completed. Consumer workers call this
+ * when the participant-side completion event arrives.
+ *
+ *   - Persists the step output to saga_state.step_outputs.
+ *   - Transitions saga_state.status='active' + clears next_resume_at.
+ *   - Emits `saga_resumed` audit event.
+ *
+ * The caller is responsible for invoking `withSaga(sagaId, ...)` + the
+ * registered saga function afterwards (the lifecycle pattern from § 5.8).
+ */
+export declare function completeAsyncStep(args: {
+    sagaId: string;
+    stepName: string;
+    output: unknown;
+}): Promise<void>;
+/**
+ * Read the persisted output of a previously-completed async step. Used by
+ * a re-entered saga function to retrieve the result inside its step body.
+ */
+export declare function getCompletedAsyncOutput(args: {
+    sagaId: string;
+    stepName: string;
+}): Promise<unknown | null>;
+//# sourceMappingURL=async-step.d.ts.map

package/dist/async-step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-step.d.ts","sourceRoot":"","sources":["../src/async-step.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,SAAS,CAAC;AAKnD;;4CAE4C;AAC5C,qBAAa,kBAAmB,SAAQ,SAAS;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBACd,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAQ7C;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAChB,OAAO,CAAC,CAAC,CAAC,CAuEZ;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BhB;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAK1B"}

package/dist/async-step.js

@@ -0,0 +1,166 @@
+// Pattern 2 (async-via-outbox) step impl.
+//
+// Spec § 5.6 + comm doctrine § 4.5. When a step is invoked with
+// `{ async: true }`, the library:
+//
+//   1. Pauses the saga (status='paused', next_resume_at=now+graceMs).
+//   2. Writes a `saga.step.<step_name>.begin` event to saga_outbox in
+//      the same DB tx as the saga_state advance.
+//   3. Throws `SagaPausedSentinel` which `createSaga` recognizes as a
+//      pause boundary — NOT a step failure. The saga exits cleanly with
+//      its handle reported as paused. The outer caller observes
+//      paused-state via `getSaga(id).status === 'paused'`.
+//
+// The completion path is driven by `completeAsyncStep(sagaId, stepName,
+// result)`. This is the function a consumer worker (per-service) calls
+// when the participant-side work finishes. It:
+//
+//   1. Persists the step output.
+//   2. Transitions saga_state.status='active'.
+//   3. Emits a `saga.step.<step_name>.completed` audit event.
+//   4. The next `withSaga(sagaId, ...)` invocation can then re-enter the
+//      saga and call the same step name; the step short-circuits on
+//      idempotency-cached output OR returns the persisted output via
+//      `getCompletedAsyncOutput`.
+//
+// For v0.1.0 we keep the implementation deterministic + observable
+// rather than fully transactional — Pattern 2's "same DB tx" mandate is
+// the orchestrator-of-truth's concern; the library writes the outbox row
+// in the same call but does not span participant boundaries.
+import { requireSagaContext } from "./context";
+import { requireSaga } from "./init";
+import { SagaError } from "./types";
+const ASYNC_OUTBOX_EVENT_PREFIX = "saga.step.";
+const PAUSE_DEFAULT_GRACE_MS = 24 * 60 * 60 * 1000; // 24h, per § 5.8
+/** Internal sentinel — thrown to unwind a saga at the async-step boundary
+ *  without triggering compensation. `createSaga` catches and treats as
+ *  "saga paused, return current handle". */
+export class SagaPausedSentinel extends SagaError {
+    sagaId;
+    stepName;
+    constructor(sagaId, stepName) {
+        super(`saga_paused: ${sagaId} paused at step '${stepName}' awaiting Pattern 2 completion`);
+        this.name = "SagaPausedSentinel";
+        this.sagaId = sagaId;
+        this.stepName = stepName;
+    }
+}
+/**
+ * Begin a Pattern 2 step. Called from `step()` when `opts.async === true`.
+ *
+ * Side effects:
+ *   - saga_state.status → 'paused', current_step = name, next_resume_at = now + grace.
+ *   - saga_outbox row written: { event_type: 'saga.step.<name>.begin', payload }
+ *   - SagaPausedSentinel thrown — control exits the saga's `fn`.
+ */
+export async function beginAsyncStep(name, opts) {
+    const cfg = requireSaga();
+    const sagaCtx = requireSagaContext("step(async)");
+    const row = sagaCtx.row;
+    // Compute the pause window. `opts` doesn't carry it for v0.1.0; we
+    // reuse the global default.
+    const nextResumeAt = new Date(Date.now() + PAUSE_DEFAULT_GRACE_MS).toISOString();
+    await cfg.stateStore.updateSagaStatus(row.id, {
+        status: "paused",
+        current_step: name,
+        next_resume_at: nextResumeAt,
+    });
+    row.status = "paused";
+    row.current_step = name;
+    row.next_resume_at = nextResumeAt;
+    // Idempotency-key payload mirrors step()'s deterministic serialization
+    // so a downstream completion event can correlate.
+    let serializedInput;
+    try {
+        const payload = {
+            name,
+            persist_fields: [...(opts.persistFields ?? [])].sort(),
+        };
+        if (opts.input !== undefined)
+            payload.input = opts.input;
+        serializedInput = JSON.stringify(payload, [
+            "input",
+            "name",
+            "persist_fields",
+        ]);
+    }
+    catch {
+        serializedInput = `${name}::nonserializable::${row.id}`;
+    }
+    // Write outbox row — same call as the state advance. Stores that don't
+    // implement outbox (in-memory) get a soft warning + no-op.
+    if (cfg.stateStore.writeOutboxBegin) {
+        await cfg.stateStore.writeOutboxBegin({
+            sagaId: row.id,
+            stepName: name,
+            eventType: `${ASYNC_OUTBOX_EVENT_PREFIX}${name}.begin`,
+            payload: {
+                saga_id: row.id,
+                step_name: name,
+                idempotency_serialized_input: serializedInput,
+                tenant_id: row.tenant_id,
+            },
+            tenantId: row.tenant_id,
+        });
+    }
+    else {
+        cfg.logger.warn("async-step: state store does not implement writeOutboxBegin; outbox event not persisted", { saga_id: row.id, step: name });
+    }
+    if (cfg.telemetryAudit) {
+        await cfg.telemetryAudit.emit({
+            action: "saga_paused",
+            target_kind: "saga",
+            target_id: row.id,
+            payload: { step: name, pattern: "2" },
+        });
+    }
+    throw new SagaPausedSentinel(row.id, name);
+}
+/**
+ * Mark an async (Pattern 2) step as completed. Consumer workers call this
+ * when the participant-side completion event arrives.
+ *
+ *   - Persists the step output to saga_state.step_outputs.
+ *   - Transitions saga_state.status='active' + clears next_resume_at.
+ *   - Emits `saga_resumed` audit event.
+ *
+ * The caller is responsible for invoking `withSaga(sagaId, ...)` + the
+ * registered saga function afterwards (the lifecycle pattern from § 5.8).
+ */
+export async function completeAsyncStep(args) {
+    const cfg = requireSaga();
+    const row = await cfg.stateStore.getSaga(args.sagaId);
+    if (!row) {
+        throw new Error(`completeAsyncStep: saga ${args.sagaId} not found`);
+    }
+    if (row.status !== "paused") {
+        // Per comm doctrine § 4.5 step 11: drop on duplicate / late arrivals.
+        cfg.logger.warn("completeAsyncStep: saga is not paused; treating completion event as duplicate", { saga_id: args.sagaId, current_status: row.status, step: args.stepName });
+        return;
+    }
+    await cfg.stateStore.appendStepOutput(args.sagaId, args.stepName, args.output);
+    await cfg.stateStore.updateSagaStatus(args.sagaId, {
+        status: "active",
+        next_resume_at: null,
+    });
+    if (cfg.telemetryAudit) {
+        await cfg.telemetryAudit.emit({
+            action: "saga_resumed",
+            target_kind: "saga",
+            target_id: args.sagaId,
+            payload: { step: args.stepName, pattern: "2" },
+        });
+    }
+}
+/**
+ * Read the persisted output of a previously-completed async step. Used by
+ * a re-entered saga function to retrieve the result inside its step body.
+ */
+export async function getCompletedAsyncOutput(args) {
+    const cfg = requireSaga();
+    const row = await cfg.stateStore.getSaga(args.sagaId);
+    if (!row)
+        return null;
+    return row.step_outputs?.[args.stepName] ?? null;
+}
+//# sourceMappingURL=async-step.js.map

package/dist/async-step.js.map

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

package/dist/context.d.ts

@@ -0,0 +1,18 @@
+import { type ResumeContext, type SagaHandle, type SagaStateRow } from "./types";
+interface SagaContextState {
+    handle: SagaHandle;
+    row: SagaStateRow;
+    resume?: ResumeContext;
+    /** Steps that completed in this episode (push-on-complete). */
+    completedSteps: {
+        name: string;
+        output: unknown;
+    }[];
+}
+export declare function runInSagaContext<T>(state: SagaContextState, fn: () => Promise<T>): Promise<T>;
+export declare function getSagaContext(): SagaContextState | undefined;
+export declare function requireSagaContext(api: string): SagaContextState;
+export declare function runWithResumeContext<T>(ctx: ResumeContext, fn: () => Promise<T>): Promise<T>;
+export declare function getResumeContext(): ResumeContext | undefined;
+export {};
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,YAAY,EAElB,MAAM,SAAS,CAAC;AAEjB,UAAU,gBAAgB;IACxB,MAAM,EAAE,UAAU,CAAC;IACnB,GAAG,EAAE,YAAY,CAAC;IAClB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,+DAA+D;IAC/D,cAAc,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CACrD;AAID,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,KAAK,EAAE,gBAAgB,EACvB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED,wBAAgB,cAAc,IAAI,gBAAgB,GAAG,SAAS,CAE7D;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAMhE;AAMD,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,GAAG,EAAE,aAAa,EAClB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,SAAS,CAE5D"}

package/dist/context.js

@@ -0,0 +1,28 @@
+// ALS-based saga context — primes (sagaId, resumeContext, siblings) for
+// `step`, `withSaga`, `emitSagaSignal`, etc.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { NoActiveSaga, } from "./types";
+const sagaStorage = new AsyncLocalStorage();
+export function runInSagaContext(state, fn) {
+    return sagaStorage.run(state, fn);
+}
+export function getSagaContext() {
+    return sagaStorage.getStore();
+}
+export function requireSagaContext(api) {
+    const ctx = sagaStorage.getStore();
+    if (!ctx) {
+        throw new NoActiveSaga(api);
+    }
+    return ctx;
+}
+// Resume context priming — `withSaga()` sets this so the next createSaga
+// detects "we're inside a resume episode" and reloads from the state store.
+const resumeStorage = new AsyncLocalStorage();
+export function runWithResumeContext(ctx, fn) {
+    return resumeStorage.run(ctx, fn);
+}
+export function getResumeContext() {
+    return resumeStorage.getStore();
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,6CAA6C;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAIL,YAAY,GACb,MAAM,SAAS,CAAC;AAUjB,MAAM,WAAW,GAAG,IAAI,iBAAiB,EAAoB,CAAC;AAE9D,MAAM,UAAU,gBAAgB,CAC9B,KAAuB,EACvB,EAAoB;IAEpB,OAAO,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,WAAW,CAAC,QAAQ,EAAE,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,MAAM,GAAG,GAAG,WAAW,CAAC,QAAQ,EAAE,CAAC;IACnC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,YAAY,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yEAAyE;AACzE,4EAA4E;AAC5E,MAAM,aAAa,GAAG,IAAI,iBAAiB,EAAiB,CAAC;AAE7D,MAAM,UAAU,oBAAoB,CAClC,GAAkB,EAClB,EAAoB;IAEpB,OAAO,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,aAAa,CAAC,QAAQ,EAAE,CAAC;AAClC,CAAC"}

package/dist/decorator.d.ts

@@ -0,0 +1,24 @@
+import type { SagaCallableConfig } from "./types";
+interface RegistryEntry {
+    className: string;
+    methodName: string;
+    config: SagaCallableConfig;
+}
+/** Symbol-keyed slot so consumers can read the tag off a method. */
+export declare const SAGA_CALLABLE_METADATA: unique symbol;
+export type SagaCallableMethod = {
+    [SAGA_CALLABLE_METADATA]: SagaCallableConfig;
+};
+/**
+ * Decorator factory — usable as `@sagaCallable({...})` (TC39 stage-3
+ * decorators) and also callable explicitly: `sagaCallable({...})(method)`.
+ *
+ * Legacy `experimentalDecorators` shape (3-arg) is supported so this works
+ * under bun's default tsconfig.
+ */
+export declare function sagaCallable(config: SagaCallableConfig): (target: unknown, propertyKeyOrContext?: unknown, descriptor?: PropertyDescriptor) => unknown;
+export declare function readSagaCallableConfig(fn: unknown): SagaCallableConfig | undefined;
+export declare function readSagaCallableRegistry(): readonly RegistryEntry[];
+export declare function _resetDecoratorRegistryForTests(): void;
+export {};
+//# sourceMappingURL=decorator.d.ts.map

package/dist/decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../src/decorator.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,UAAU,aAAa;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAID,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,EAAE,OAAO,MAE3C,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,CAAC,sBAAsB,CAAC,EAAE,kBAAkB,CAAC;CAC9C,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,IAEnD,QAAQ,OAAO,EACf,uBAAuB,OAAO,EAC9B,aAAa,kBAAkB,KAC9B,OAAO,CAgDX;AAWD,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,OAAO,GACV,kBAAkB,GAAG,SAAS,CAKhC;AAED,wBAAgB,wBAAwB,IAAI,SAAS,aAAa,EAAE,CAEnE;AAED,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD"}

package/dist/decorator.js

@@ -0,0 +1,69 @@
+// @sagaCallable — D165 six-tag schema with runtime metadata + class registry.
+//
+// Spec § 5.7. v0.1.0 attaches the tag to the method's prototype-bound function
+// and records (className, methodName, config) into a process-local registry
+// the lint plugin + codegen will read at build time (`// TODO saga-v0.1.x:`
+// for the build-time emitters).
+const registry = [];
+/** Symbol-keyed slot so consumers can read the tag off a method. */
+export const SAGA_CALLABLE_METADATA = Symbol.for("@nodii/saga.sagaCallableMetadata");
+/**
+ * Decorator factory — usable as `@sagaCallable({...})` (TC39 stage-3
+ * decorators) and also callable explicitly: `sagaCallable({...})(method)`.
+ *
+ * Legacy `experimentalDecorators` shape (3-arg) is supported so this works
+ * under bun's default tsconfig.
+ */
+export function sagaCallable(config) {
+    return function decorate(target, propertyKeyOrContext, descriptor) {
+        // Stage-3 decorator: (value, context) returning a replacement function.
+        if (typeof target === "function" &&
+            propertyKeyOrContext &&
+            typeof propertyKeyOrContext === "object" &&
+            "kind" in propertyKeyOrContext) {
+            const ctx = propertyKeyOrContext;
+            const fn = target;
+            attachMetadata(fn, config);
+            ctx.addInitializer?.(function () {
+                const className = this.constructor?.name ??
+                    "<anonymous>";
+                registry.push({ className, methodName: ctx.name, config });
+            });
+            return fn;
+        }
+        // Legacy decorator: (target, propertyKey, descriptor).
+        if (typeof propertyKeyOrContext === "string" ||
+            typeof propertyKeyOrContext === "symbol") {
+            const className = target?.constructor?.name ??
+                target.name ??
+                "<anonymous>";
+            const methodName = String(propertyKeyOrContext);
+            if (descriptor && typeof descriptor.value === "function") {
+                attachMetadata(descriptor.value, config);
+            }
+            registry.push({ className, methodName, config });
+            return descriptor;
+        }
+        // Explicit call: sagaCallable({...})(fn).
+        if (typeof target === "function") {
+            attachMetadata(target, config);
+            return target;
+        }
+        return target;
+    };
+}
+function attachMetadata(fn, config) {
+    fn[SAGA_CALLABLE_METADATA] = config;
+}
+export function readSagaCallableConfig(fn) {
+    if (typeof fn !== "function")
+        return undefined;
+    return fn[SAGA_CALLABLE_METADATA];
+}
+export function readSagaCallableRegistry() {
+    return [...registry];
+}
+export function _resetDecoratorRegistryForTests() {
+    registry.length = 0;
+}
+//# sourceMappingURL=decorator.js.map

package/dist/decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorator.js","sourceRoot":"","sources":["../src/decorator.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,EAAE;AACF,+EAA+E;AAC/E,4EAA4E;AAC5E,4EAA4E;AAC5E,gCAAgC;AAUhC,MAAM,QAAQ,GAAoB,EAAE,CAAC;AAErC,oEAAoE;AACpE,MAAM,CAAC,MAAM,sBAAsB,GAAkB,MAAM,CAAC,GAAG,CAC7D,kCAAkC,CACnC,CAAC;AAMF;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,MAA0B;IACrD,OAAO,SAAS,QAAQ,CACtB,MAAe,EACf,oBAA8B,EAC9B,UAA+B;QAE/B,wEAAwE;QACxE,IACE,OAAO,MAAM,KAAK,UAAU;YAC5B,oBAAoB;YACpB,OAAO,oBAAoB,KAAK,QAAQ;YACxC,MAAM,IAAK,oBAA+B,EAC1C,CAAC;YACD,MAAM,GAAG,GAAG,oBAIX,CAAC;YACF,MAAM,EAAE,GAAG,MAAyC,CAAC;YACrD,cAAc,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;YAC3B,GAAG,CAAC,cAAc,EAAE,CAAC;gBACnB,MAAM,SAAS,GACZ,IAA4C,CAAC,WAAW,EAAE,IAAI;oBAC/D,aAAa,CAAC;gBAChB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;YAC7D,CAAC,CAAC,CAAC;YACH,OAAO,EAAE,CAAC;QACZ,CAAC;QAED,uDAAuD;QACvD,IACE,OAAO,oBAAoB,KAAK,QAAQ;YACxC,OAAO,oBAAoB,KAAK,QAAQ,EACxC,CAAC;YACD,MAAM,SAAS,GACZ,MAA8C,EAAE,WAAW,EAAE,IAAI;gBACjE,MAA4B,CAAC,IAAI;gBAClC,aAAa,CAAC;YAChB,MAAM,UAAU,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;YAChD,IAAI,UAAU,IAAI,OAAO,UAAU,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;gBACzD,cAAc,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAC3C,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;YACjD,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,0CAA0C;QAC1C,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;YACjC,cAAc,CAAC,MAAyC,EAAE,MAAM,CAAC,CAAC;YAClE,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CACrB,EAAmC,EACnC,MAA0B;IAEzB,EAAkE,CACjE,sBAAsB,CACvB,GAAG,MAAM,CAAC;AACb,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,EAAW;IAEX,IAAI,OAAO,EAAE,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IAC/C,OAAQ,EAAwD,CAC9D,sBAAsB,CACvB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB;IACtC,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,+BAA+B;IAC7C,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;AACtB,CAAC"}

package/dist/idempotency.d.ts

@@ -0,0 +1,22 @@
+import type { IdempotencyShim } from "./types";
+export declare class NoopIdempotency implements IdempotencyShim {
+    wrapForSagaStep<O>(args: {
+        sagaId: string;
+        stepName: string;
+        serializedInput: string;
+        handler: () => Promise<O>;
+    }): Promise<O>;
+}
+export declare class InMemoryIdempotency implements IdempotencyShim {
+    private cache;
+    wrapForSagaStep<O>(args: {
+        sagaId: string;
+        stepName: string;
+        serializedInput: string;
+        handler: () => Promise<O>;
+    }): Promise<O>;
+    /** Test-only — used by the parity-fence fixtures to assert byte equality. */
+    static debugComputeKey(sagaId: string, stepName: string, serializedInput: string): string;
+    reset(): void;
+}
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,qBAAa,eAAgB,YAAW,eAAe;IAC/C,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE;QAC7B,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,EAAE,MAAM,CAAC;QACxB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;KAC3B,GAAG,OAAO,CAAC,CAAC,CAAC;CAGf;AAED,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,KAAK,CAA8B;IAErC,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE;QAC7B,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,EAAE,MAAM,CAAC;QACxB,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;KAC3B,GAAG,OAAO,CAAC,CAAC,CAAC;IAUd,6EAA6E;IAC7E,MAAM,CAAC,eAAe,CACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACtB,MAAM;IAIT,KAAK,IAAI,IAAI;CAGd"}