@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/utils/process/index.d.cts

@@ -0,0 +1,411 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { NodeInput, AppendLogStorageTier, KvStorageTier, ReactiveLogBundle } from '@graphrefly/pure-ts/extra';
+import { BaseAuditRecord } from '../../base/mutation/index.cjs';
+import { S as StatusValue } from '../../status-U-rUI79b.cjs';
+import { CqrsEventMap, CqrsEvent, CqrsGraph } from '../cqrs/index.cjs';
+import '@graphrefly/pure-ts/graph';
+
+/**
+ * Process Manager pattern (Phase 7 — roadmap §4.6, Audit 3 — locked 2026-04-24).
+ *
+ * Reactive long-running workflow primitive over CQRS event nodes.
+ * Correlates events across aggregates, tracks per-instance state, supports
+ * retries with backoff, and runs compensation on failure or explicit cancel.
+ *
+ * ## Architecture
+ *
+ * - Per-instance state lives in a `Map<correlationId, TState>` closure (in-memory).
+ *   The `_process_<name>_started` synthetic event is dispatched per `start()`
+ *   for an event-sourced audit trail using `correlationId` as `aggregateId`.
+ *   Cross-restart state recovery is opt-in via
+ *   `opts.persistence.stateStorage` (kv-tier per-correlationId snapshot,
+ *   Tier 6.5 3.5) plus an explicit `restore()` call after construction.
+ * - Watched-event subscriptions are imperative (coordinator role) — each
+ *   watched CQRS event type is subscribed to via `entries.subscribe(...)`.
+ *   These are NOT reactive node edges; the process manager is intentionally
+ *   a coordinator that bridges reactive CQRS events into imperative instance logic.
+ * - Step execution uses `fromAny` to uniformly handle sync and async handlers.
+ * - Retry delays use `setTimeout` (same sanctioned pattern as `extra/resilience.ts`
+ *   retry helper — this primitive is a coordinator, not a reactive pipeline stage).
+ * - Timer scheduling uses `fromTimer` from `extra/sources.ts` per spec §5.8.
+ * - Audit log uses `createAuditLog` per Audit 2.
+ *
+ * @module
+ */
+
+/**
+ * Discriminated union returned by each step handler.
+ *
+ * - `"success"` — step ran cleanly; update state, optionally emit
+ *   side-effect events and schedule a future synthetic event. The process
+ *   instance stays `"running"`.
+ * - `"terminate"` — workflow complete; instance moves to `"completed"`.
+ *   Process-specific extension to the canonical outcome enum.
+ * - `"failure"` — triggers compensation; instance moves to `"cancelled"` /
+ *   `"errored"`.
+ *
+ * Field name is `outcome` (matching `cqrs.DispatchRecord.outcome` and the
+ * canonical Tier 1.6.2 / 2.3 enum). `"success"` and `"failure"` are the
+ * canonical values; `"terminate"` is the process-specific extension for
+ * "early-return success".
+ */
+type ProcessStepResult<TState> = {
+    outcome: "success";
+    state: TState;
+    emit?: readonly {
+        type: string;
+        payload: unknown;
+    }[];
+    schedule?: ProcessSchedule;
+} | {
+    outcome: "terminate";
+    state: TState;
+    emit?: readonly {
+        type: string;
+        payload: unknown;
+    }[];
+    reason?: string;
+} | {
+    outcome: "failure";
+    error: unknown;
+};
+/**
+ * Schedule a synthetic timer event after `afterMs` milliseconds.
+ * When the timer fires, the synthetic event of `eventType` is routed to the
+ * matching step (if one is registered) for this correlationId.
+ */
+type ProcessSchedule = {
+    afterMs: number;
+    eventType: string;
+};
+/**
+ * Step handler signature.
+ *
+ * Receives the current instance state and the triggering CQRS event.
+ * Returns a {@link ProcessStepResult} — sync value, Promise, or any
+ * {@link NodeInput} consumed via `fromAny`.
+ */
+type ProcessStep<TState, EM extends CqrsEventMap, K extends keyof EM & string> = (state: TState, event: CqrsEvent<EM[K]>) => NodeInput<ProcessStepResult<TState>>;
+/**
+ * Compensation handler. Runs when a step returns `outcome: "failure"`, throws, or
+ * when `cancel(correlationId)` is called on a running instance.
+ *
+ * Should undo any side effects performed by prior steps (refund, cancel
+ * reservation, etc.). Errors thrown inside compensate are swallowed and
+ * recorded in the audit log with `status: "errored"` to prevent cascading
+ * failure loops.
+ */
+type ProcessCompensate<TState> = (state: TState, error: unknown) => NodeInput<void>;
+/**
+ * Audit record for a single process instance state transition.
+ *
+ * Every status change (start → running → completed / errored / cancelled)
+ * appends one record. `correlationId` is the stable process key.
+ *
+ * Extends {@link BaseAuditRecord} so records carry `t_ns` / `seq` /
+ * `handlerVersion` from the cross-cutting Audit 2 schema.
+ */
+interface ProcessInstance<TState> extends BaseAuditRecord {
+    /** Stable correlation key that identifies this process instance. */
+    readonly correlationId: string;
+    /** Most-recent instance state at this transition. */
+    readonly state: TState;
+    /** Current lifecycle status after this transition. */
+    readonly status: "running" | "completed" | "errored" | "cancelled";
+    /** Wall-clock nanoseconds when `start()` was called. */
+    readonly startedAt: number;
+    /** Wall-clock nanoseconds of this transition. */
+    readonly updatedAt: number;
+    /** Handler version stamped at transition time (Audit 5). */
+    readonly handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+    /** Optional human-readable reason for cancellation. Present only on `"cancelled"` records produced by `cancel()`. */
+    readonly reason?: string;
+}
+/**
+ * Recommended `keyOf` for storage tiers keyed by correlationId (Audit 2).
+ */
+declare const processInstanceKeyOf: <TState>(i: ProcessInstance<TState>) => string;
+/**
+ * Per-correlationId state snapshot persisted via
+ * {@link ProcessManagerOpts.persistence.stateStorage} (Tier 6.5 3.5,
+ * 2026-04-29). Captures the running instance's current state plus
+ * lifecycle metadata so a fresh `processManager` can resume in-flight
+ * workflows after restart via {@link ProcessManagerResult.restore}.
+ *
+ * Terminal records (`status` ∈ `"completed" | "errored" | "cancelled"`)
+ * are deleted from the kv tier on transition — only running instances
+ * persist between restarts.
+ */
+interface ProcessStateSnapshot<TState> {
+    readonly correlationId: string;
+    readonly state: TState;
+    readonly status: "running" | "completed" | "errored" | "cancelled";
+    readonly startedAt: number;
+    readonly updatedAt: number;
+    readonly handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+}
+/** Recommended `keyOf` for `KvStorageTier<ProcessStateSnapshot<...>>`. */
+declare const processStateKeyOf: <TState>(s: ProcessStateSnapshot<TState>) => string;
+/**
+ * Options for {@link processManager}.
+ */
+interface ProcessManagerOpts<TState, EM extends CqrsEventMap> {
+    /** Initial state value for every new process instance. */
+    readonly initial: TState;
+    /** CQRS event types to watch for correlation routing. */
+    readonly watching: readonly (keyof EM & string)[];
+    /**
+     * Per-event-type step handlers. A step is invoked when a watched event's
+     * `correlationId` matches a running instance and the event type is in
+     * `steps`. Events with no matching step are silently ignored.
+     */
+    readonly steps: {
+        [K in keyof EM & string]?: ProcessStep<TState, EM, K>;
+    };
+    /**
+     * Optional compensation handler. Runs on step `outcome: "failure"` / step throw
+     * and on explicit `cancel()`. If omitted, instances fail silently with
+     * status `"errored"` instead of `"cancelled"`.
+     */
+    readonly compensate?: ProcessCompensate<TState>;
+    /**
+     * Optional predicate called after each `"success"` step. When it returns
+     * `true`, the instance is moved to `"completed"` immediately without
+     * waiting for a `"terminate"` step result.
+     */
+    readonly isTerminal?: (state: TState) => boolean;
+    /**
+     * Maximum number of retry attempts after a step throws (not counting the
+     * first attempt). Default: `0` (no retry — fail immediately on throw).
+     */
+    readonly retryMax?: number;
+    /**
+     * Per-retry backoff delays in milliseconds. `backoffMs[i]` is the delay
+     * before attempt `i + 1`. If fewer entries than `retryMax`, the last entry
+     * is repeated. Default: `[0]` (no delay).
+     *
+     * **Implementation note:** retry delays are implemented with `setTimeout`
+     * (same sanctioned exception as `extra/resilience.ts`). This is a
+     * coordinator-layer primitive — `fromTimer` would require subscribing to
+     * an additional node per attempt, which would leak timer nodes without a
+     * clear disposal scope.
+     */
+    readonly backoffMs?: readonly number[];
+    /** Handler version tag stamped onto audit records (Audit 5). */
+    readonly handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+    /**
+     * When `true`, do NOT auto-restore on construction. The caller must invoke
+     * {@link ProcessManagerResult.restore} explicitly to load persisted
+     * snapshots and arm watch dispatch.
+     *
+     * **Default `false`:** the factory kicks off restoration immediately so
+     * watch dispatch arms as soon as snapshots have loaded (or instantly when
+     * no `stateStorage` tier is configured). Until restoration completes,
+     * watched events accumulate at the source but are valve-blocked from
+     * reaching the per-instance step pipeline (B5 — locked 2026-05-01).
+     */
+    readonly deferRestore?: boolean;
+    /**
+     * Maximum number of concurrent `tier.load(key)` calls during restore.
+     *
+     * The restore pipeline streams keys from `tier.list()` through
+     * `mergeMap`, which by default subscribes to inner sources unbounded
+     * (parallel up to the number of keys). For storage tiers with large
+     * persisted-instance counts (10K+), unbounded concurrency can exhaust
+     * file handles, connection pools, or the backend's concurrent-request
+     * budget. This option caps the in-flight load count.
+     *
+     * **Default `8`** (D2 lock 2026-05-01). Set higher for backends with
+     * generous concurrency budgets; set to `Number.POSITIVE_INFINITY` for
+     * the prior unbounded behavior.
+     */
+    readonly restoreConcurrency?: number;
+    /** Optional persistence wiring (Audit 4). */
+    readonly persistence?: {
+        /**
+         * Wire the per-process synthetic state event stream to append-log tiers.
+         * Reuses `CqrsGraph.attachEventStorage` so events persist across restarts.
+         */
+        eventStorage?: readonly AppendLogStorageTier<CqrsEvent>[];
+        /**
+         * Wire per-correlationId state snapshots to kv tiers (Tier 6.5 3.5,
+         * 2026-04-29). Each `start()` and step transition writes the running
+         * instance's state under its `correlationId`; terminal transitions
+         * (`completed` / `errored` / `cancelled`) `delete` the key. After
+         * restart, callers invoke {@link ProcessManagerResult.restore} to
+         * reload running instances from the first tier.
+         *
+         * Uses {@link KvStorageTier} (not snapshot tier) because per-instance
+         * state is N records keyed by correlationId, not a single global
+         * snapshot. {@link processStateKeyOf} is the recommended `keyOf`
+         * (already aligned with the kv tier's `save(key, value)` shape).
+         *
+         * Terminal records are NOT preserved — historical lifecycle is the
+         * audit log's job. State persistence covers crash-recovery only.
+         */
+        stateStorage?: readonly KvStorageTier<ProcessStateSnapshot<TState>>[];
+    };
+}
+/**
+ * Result handle returned by {@link processManager}.
+ */
+interface ProcessManagerResult<TState> {
+    /**
+     * Reactive audit log of every process instance state transition.
+     * Every `start()`, step result, retry, cancellation, and compensation
+     * appends a {@link ProcessInstance} record.
+     */
+    readonly instances: ReactiveLogBundle<ProcessInstance<TState>>;
+    /**
+     * Alias for {@link instances} (Audit 2 `.audit` duplication convention).
+     */
+    readonly audit: ReactiveLogBundle<ProcessInstance<TState>>;
+    /**
+     * Start a new process instance identified by `correlationId`.
+     *
+     * Emits a synthetic `_process_<name>_started` event into the CQRS graph
+     * with `correlationId` as `aggregateId` so per-aggregate streams record
+     * the process lifecycle. If the correlationId already has an active
+     * (running) instance, this call is a no-op (idempotent).
+     *
+     * @param correlationId - Stable key for this workflow instance.
+     * @param initialPayload - Optional payload carried on the start event.
+     */
+    start(correlationId: string, initialPayload?: unknown): void;
+    /**
+     * Cancel a running instance by correlationId.
+     *
+     * Triggers the `compensate` handler (if configured), then marks the
+     * instance as `"cancelled"`. If the instance is not running, this is
+     * a no-op.
+     *
+     * @param correlationId - Instance to cancel.
+     * @param reason - Optional human-readable reason recorded in the audit log.
+     */
+    cancel(correlationId: string, reason?: string): void;
+    /**
+     * Synchronous read of the current in-memory state for a correlationId.
+     * Returns `undefined` if the instance does not exist or has terminated.
+     */
+    getState(correlationId: string): TState | undefined;
+    /**
+     * Reactive lifecycle of the restore pipeline. Typed as the central
+     * {@link StatusValue} enum (`"pending" | "running" | "completed" | "errored"`);
+     * the process-manager restore state machine currently emits the `"pending"`
+     * and `"completed"` literals only — `"running"` / `"errored"` reserved
+     * for future fine-grained restore observability. Starts at `"pending"`,
+     * flips to `"completed"` once snapshot loads complete (or immediately when
+     * no `stateStorage` is configured). On {@link dispose}, the node receives
+     * TEARDOWN via the standard subgraph teardown cascade — there is no
+     * `"disposed"` literal; consumers detect tear-down via subscription
+     * COMPLETE on {@link dispose}. Watched events are valve-gated on this
+     * node: dispatch is blocked while `restoreState !== "completed"`.
+     *
+     * Exposed for observability and tests. Subscribers can compose
+     * `derived([restoreState], …)` to build their own gates / readouts.
+     */
+    readonly restoreState: Node<StatusValue>;
+    /**
+     * Trigger restoration of running instances from the first
+     * {@link ProcessManagerOpts.persistence.stateStorage} tier (Tier 6.5
+     * 3.5, 2026-04-29). Loads every record in the tier reactively and
+     * re-hydrates `instanceStates` / `activeInstances` / `startedAt` for
+     * any record whose `status === "running"`. Terminal records, if any
+     * persisted before delete fired, are silently skipped.
+     *
+     * **Reactive composition (B5 — locked 2026-05-01):** internally,
+     * `tier.list()` and `tier.load()` are wrapped in `fromAny` sources
+     * (handles sync values, Promises, async iterables, and existing Nodes
+     * uniformly per `~/src/graphrefly/COMPOSITION-GUIDE.md` §3 source
+     * bridging); a `mergeMap` flattens per-key load results; an `effect`
+     * populates closure state and flips {@link restoreState} to
+     * `"completed"` on the `COMPLETE` boundary. No `await` inside the
+     * reactive interior — the single async boundary is the returned
+     * `Promise<void>`, which resolves when {@link restoreState} transitions
+     * to `"completed"` OR when {@link dispose} tears down the restore node
+     * (in which case `firstWhere`'s COMPLETE-rejection is swallowed and
+     * the promise resolves to `undefined`).
+     *
+     * Idempotent — calling twice subscribes to the same restore pipeline
+     * and resolves on the same gate flip. No-op when no `stateStorage`
+     * tier is configured OR the first tier lacks a `list?` method:
+     * `restoreState` flips to `"completed"` immediately so watches can arm.
+     *
+     * **Auto-restore default.** With `deferRestore: false` (the default),
+     * the factory invokes `restore()` once at construction so callers do
+     * not need to remember to wire it. Pass `deferRestore: true` to
+     * suppress auto-restore and call `restore()` manually.
+     */
+    restore(): Promise<void>;
+    /**
+     * Release all watched-event subscriptions and stop processing new events.
+     *
+     * After `dispose()`, subsequent `start()` and `cancel()` calls are no-ops.
+     * In-flight async steps complete naturally; no new steps are dispatched.
+     *
+     * Tears down the {@link restoreState} node via the standard subgraph
+     * teardown cascade. Any pending `restore()` Promise resolves (the
+     * COMPLETE-rejection from `firstWhere` is swallowed at the API edge);
+     * the watch valve closes via TEARDOWN propagation; no further dispatch
+     * even if a `fromAny(tier.load…)` would resolve later (the per-key
+     * load source's cleanup sets `settled = true`, dropping the late DATA).
+     */
+    dispose(): void;
+}
+/**
+ * Create a process manager that coordinates long-running reactive workflows
+ * over a {@link CqrsGraph}.
+ *
+ * Process instances are identified by `correlationId`. Events from the watched
+ * event types are routed to per-instance step handlers when the event's
+ * `correlationId` matches a running instance.
+ *
+ * ```ts
+ * const app = cqrs<{ orderPlaced: { orderId: string }; paymentReceived: { amount: number } }>("orders");
+ *
+ * const pm = processManager(app, "fulfillment", {
+ *   initial: { step: "awaiting-payment", total: 0 },
+ *   watching: ["orderPlaced", "paymentReceived"],
+ *   steps: {
+ *     orderPlaced(state, event) {
+ *       return { outcome: "success", state: { ...state, orderId: event.payload.orderId } };
+ *     },
+ *     paymentReceived(state, event) {
+ *       return { outcome: "terminate", state: { ...state, total: event.payload.amount } };
+ *     },
+ *   },
+ *   compensate(state, _error) {
+ *     // undo reservation, issue refund, etc.
+ *   },
+ *   retryMax: 2,
+ *   backoffMs: [100, 500],
+ * });
+ *
+ * pm.start("order-123");
+ * app.dispatch("orderPlaced", { orderId: "order-123" }, { correlationId: "order-123" });
+ * ```
+ *
+ * @param cqrsGraph - The CQRS graph whose event streams the manager watches.
+ * @param name - Stable identifier for this process type; used for the
+ *   synthetic event-type prefix `_process_<name>_*`. Currently emits
+ *   `_process_<name>_started` per `start()`; the prefix is reserved for
+ *   future `_state` / `_timer` channels.
+ * @param opts - Configuration: initial state, watched events, steps, retry,
+ *   compensation, and optional persistence.
+ * @returns {@link ProcessManagerResult} with `instances` audit log and
+ *   `start`, `cancel`, `getState` imperative controls.
+ *
+ * @category patterns
+ */
+declare function processManager<TState, EM extends CqrsEventMap = Record<string, unknown>>(cqrsGraph: CqrsGraph<EM>, name: string, opts: ProcessManagerOpts<TState, EM>): ProcessManagerResult<TState>;
+
+export { type ProcessCompensate, type ProcessInstance, type ProcessManagerOpts, type ProcessManagerResult, type ProcessSchedule, type ProcessStateSnapshot, type ProcessStep, type ProcessStepResult, processInstanceKeyOf, processManager, processStateKeyOf };