@graphrefly/graphrefly 0.34.0 → 0.36.0

package/dist/index-DzCQt2FJ.d.cts

@@ -0,0 +1,292 @@
+import { R as ReactiveLogBundle } from './reactive-log-ScpWyqny.cjs';
+import { NodeInput } from './extra/sources.cjs';
+import { AppendLogStorageTier } from './extra/storage-tiers.cjs';
+import { B as BaseAuditRecord } from './imperative-audit-ahAE65a9.cjs';
+import { C as CqrsEventMap, a as CqrsEvent, b as CqrsGraph } from './index-2URa-V4S.cjs';
+
+/**
+ * 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`.
+ *   Future state-snapshot persistence (`_process_<name>_state`) is reserved
+ *   under the same `_process_<name>_*` namespace but not yet implemented;
+ *   see `docs/optimizations.md` "Deferred follow-ups".
+ * - 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.
+ *
+ * - `"continue"` — update state, optionally emit side-effect events and
+ *   schedule a future synthetic event.
+ * - `"terminate"` — workflow complete; instance moves to `"terminated"`.
+ * - `"fail"` — triggers compensation; instance moves to `"compensated"` /
+ *   `"failed"`.
+ */
+type ProcessStepResult<TState> = {
+    kind: "continue";
+    state: TState;
+    emit?: readonly {
+        type: string;
+        payload: unknown;
+    }[];
+    schedule?: ProcessSchedule;
+} | {
+    kind: "terminate";
+    state: TState;
+    emit?: readonly {
+        type: string;
+        payload: unknown;
+    }[];
+    reason?: string;
+} | {
+    kind: "fail";
+    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 `kind: "fail"`, 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: "failed"` 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 → terminated / failed / compensated)
+ * 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" | "terminated" | "failed" | "compensated";
+    /** 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 `"compensated"` 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;
+/**
+ * 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 `kind: "fail"` / step throw
+     * and on explicit `cancel()`. If omitted, instances fail silently with
+     * status `"failed"` instead of `"compensated"`.
+     */
+    readonly compensate?: ProcessCompensate<TState>;
+    /**
+     * Optional predicate called after each `"continue"` step. When it returns
+     * `true`, the instance is moved to `"terminated"` 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;
+    };
+    /** 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>[];
+    };
+}
+/**
+ * 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 `"compensated"`. 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;
+    /**
+     * 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.
+     */
+    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 { kind: "continue", state: { ...state, orderId: event.payload.orderId } };
+ *     },
+ *     paymentReceived(state, event) {
+ *       return { kind: "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>;
+
+type index_ProcessCompensate<TState> = ProcessCompensate<TState>;
+type index_ProcessInstance<TState> = ProcessInstance<TState>;
+type index_ProcessManagerOpts<TState, EM extends CqrsEventMap> = ProcessManagerOpts<TState, EM>;
+type index_ProcessManagerResult<TState> = ProcessManagerResult<TState>;
+type index_ProcessSchedule = ProcessSchedule;
+type index_ProcessStep<TState, EM extends CqrsEventMap, K extends keyof EM & string> = ProcessStep<TState, EM, K>;
+type index_ProcessStepResult<TState> = ProcessStepResult<TState>;
+declare const index_processInstanceKeyOf: typeof processInstanceKeyOf;
+declare const index_processManager: typeof processManager;
+declare namespace index {
+  export { type index_ProcessCompensate as ProcessCompensate, type index_ProcessInstance as ProcessInstance, type index_ProcessManagerOpts as ProcessManagerOpts, type index_ProcessManagerResult as ProcessManagerResult, type index_ProcessSchedule as ProcessSchedule, type index_ProcessStep as ProcessStep, type index_ProcessStepResult as ProcessStepResult, index_processInstanceKeyOf as processInstanceKeyOf, index_processManager as processManager };
+}
+
+export { type ProcessCompensate as P, type ProcessInstance as a, type ProcessManagerOpts as b, type ProcessManagerResult as c, type ProcessSchedule as d, type ProcessStep as e, type ProcessStepResult as f, processManager as g, index as i, processInstanceKeyOf as p };

package/dist/{index-D80nGRb9.d.ts → index-DzYTXMBz.d.ts}

@@ -1,6 +1,6 @@
-import { a as Node } from './node-8qx0kgYt.js';
-import { S as StatusValue, C as CircuitState, R as RateLimiterOptions, a as CircuitBreakerOptions, b as RetryOptions, F as FallbackInput, N as NS_PER_MS, c as NS_PER_SEC } from './resilience-RjDIHZNZ.js';
-import { B as BudgetConstraint } from './index-DheNs40A.js';
+import { a as Node } from './node-fSc-hCv8.js';
+import { S as StatusValue, C as CircuitState, R as RateLimiterOptions, a as CircuitBreakerOptions, b as RetryOptions, F as FallbackInput, N as NS_PER_MS, c as NS_PER_SEC } from './resilience-Bys63Cpd.js';
+import { B as BudgetConstraint } from './index-DXSLMoma.js';
 
 /**
  * Resilience composition with correct nesting order (roadmap §9.0b).

package/dist/index-EfPb77rT.d.cts

@@ -0,0 +1,26 @@
+import { C as CatchOptions, a as ClassifyResult, D as Decision, b as DecisionAction, G as GateController, c as GateOptions, P as PipelineGraph, S as StepRef, T as TerminalCause, d as decisionKeyOf, p as pipelineGraph } from './pipeline-graph-BlLBWSZ2.cjs';
+
+/**
+ * Orchestration patterns (roadmap §4.1).
+ *
+ * Domain-layer helpers that build workflow shapes on top of core + extra primitives.
+ * Exported under the `patterns.orchestration` namespace to avoid collisions with
+ * Phase 2 operator names (for example `gate`, `forEach`).
+ */
+
+declare const index_CatchOptions: typeof CatchOptions;
+declare const index_ClassifyResult: typeof ClassifyResult;
+declare const index_Decision: typeof Decision;
+declare const index_DecisionAction: typeof DecisionAction;
+declare const index_GateController: typeof GateController;
+declare const index_GateOptions: typeof GateOptions;
+declare const index_PipelineGraph: typeof PipelineGraph;
+declare const index_StepRef: typeof StepRef;
+declare const index_TerminalCause: typeof TerminalCause;
+declare const index_decisionKeyOf: typeof decisionKeyOf;
+declare const index_pipelineGraph: typeof pipelineGraph;
+declare namespace index {
+  export { index_CatchOptions as CatchOptions, index_ClassifyResult as ClassifyResult, index_Decision as Decision, index_DecisionAction as DecisionAction, index_GateController as GateController, index_GateOptions as GateOptions, index_PipelineGraph as PipelineGraph, index_StepRef as StepRef, index_TerminalCause as TerminalCause, index_decisionKeyOf as decisionKeyOf, index_pipelineGraph as pipelineGraph };
+}
+
+export { index as i };

package/dist/{index-B-KCkW4M.d.cts → index-GaW6Welt.d.cts}

@@ -1,7 +1,7 @@
-import { a as Node } from './node-8qx0kgYt.cjs';
-import { R as ReactiveMapBundle } from './reactive-map-Cm89Hk0c.cjs';
-import { a as GraphOptions, G as Graph, C as CausalChain } from './graph-DaoydJ_u.cjs';
-import { w as watchTopologyTree } from './topology-tree-BB6oJxMz.cjs';
+import { a as Node } from './node-fSc-hCv8.cjs';
+import { R as ReactiveMapBundle } from './reactive-map-DmgeADH8.cjs';
+import { a as GraphOptions, G as Graph, C as CausalChain } from './graph-kTltt95s.cjs';
+import { w as watchTopologyTree } from './topology-tree-C50l9ARE.cjs';
 
 /** Aggregate topology stats emitted by {@link LensGraph.stats}. */
 interface TopologyStats {

package/dist/{index-D23g00HE.d.cts → index-HCp5ua_i.d.cts}

@@ -1,7 +1,7 @@
-import { P as PolicyRuleData, a as Node, A as Actor } from './node-8qx0kgYt.cjs';
-import { G as Graph, a as GraphOptions, b as GraphDescribeOptions, c as GraphDescribeOutput, D as DescribeFilter } from './graph-DaoydJ_u.cjs';
-import { P as PolicyEnforcerGraph, a as PolicyViolation } from './index-p0bkNfby.cjs';
-import { T as TopicGraph } from './index-Ccv_61jG.cjs';
+import { P as PolicyRuleData, a as Node, A as Actor } from './node-fSc-hCv8.cjs';
+import { G as Graph, a as GraphOptions, c as GraphDescribeOptions, d as GraphDescribeOutput, D as DescribeFilter } from './graph-kTltt95s.cjs';
+import { P as PolicyEnforcerGraph, a as PolicyViolation } from './index-C4ig7whw.cjs';
+import { T as TopicGraph } from './index-33mF4XyU.cjs';
 
 /**
  * Composable safety layer (roadmap §9.0b).

package/dist/{index-DupIl9wI.d.ts → index-JYtN9uqM.d.ts}

@@ -1,4 +1,4 @@
-import { a as Node } from './node-8qx0kgYt.js';
+import { a as Node } from './node-fSc-hCv8.js';
 
 /**
  * Options for creating an atom.