@graphrefly/graphrefly 0.34.0 → 0.35.0

package/dist/index-Qq-G9B6g.d.cts

@@ -0,0 +1,171 @@
+import { a as Node } from './node-fSc-hCv8.cjs';
+import { R as ReactiveLogBundle } from './reactive-log-CgbNqksB.cjs';
+import { NodeInput } from './extra/sources.cjs';
+import { AppendLogStorageTier } from './extra/storage-tiers.cjs';
+import { G as Graph, a as GraphOptions } from './graph-kTltt95s.cjs';
+import { B as BaseAuditRecord } from './imperative-audit-ahAE65a9.cjs';
+
+/**
+ * Job queue patterns (roadmap §4.2).
+ *
+ * Queue / flow primitives modeled as graph factories:
+ * - `jobQueue()` — claim/ack/nack workflow with reactive depth.
+ * - `jobFlow()` — multi-stage queue chain.
+ *
+ * Topic / subscription / hub primitives live in `patterns/messaging`.
+ */
+
+type JobState = "queued" | "inflight";
+type JobEnvelope<T> = {
+    id: string;
+    payload: T;
+    attempts: number;
+    metadata: Readonly<Record<string, unknown>>;
+    state: JobState;
+};
+/** Audit record for a job-queue mutation (Audit 2 cross-cutting). */
+type JobEventAction = "enqueue" | "claim" | "ack" | "nack" | "remove";
+interface JobEvent<T = unknown> extends BaseAuditRecord {
+    readonly action: JobEventAction;
+    readonly id: string;
+    readonly attempts?: number;
+    readonly payload?: T;
+}
+/** Recommended `keyOf` for keyed-storage adapters (Audit 2 #7). */
+declare const jobEventKeyOf: <T>(e: JobEvent<T>) => string;
+type JobQueueOptions = {
+    graph?: GraphOptions;
+};
+declare class JobQueueGraph<T> extends Graph {
+    private readonly _pending;
+    private readonly _jobs;
+    private readonly _seqCursor;
+    readonly pending: Node<readonly string[]>;
+    readonly jobs: Node<ReadonlyMap<string, JobEnvelope<T>>>;
+    readonly depth: Node<number>;
+    /** Audit log of every queue mutation (Audit 2). */
+    readonly events: ReactiveLogBundle<JobEvent<T>>;
+    /** Alias for {@link JobQueueGraph.events} — Audit 2 `.audit` duplication. */
+    readonly audit: ReactiveLogBundle<JobEvent<T>>;
+    constructor(name: string, opts?: JobQueueOptions);
+    private _bumpSeq;
+    /**
+     * Wire append-log storage tiers (Audit 4). Returns a disposer.
+     *
+     * Named `attachEventStorage` to avoid colliding with {@link Graph.attachSnapshotStorage}.
+     */
+    attachEventStorage(tiers: readonly AppendLogStorageTier<JobEvent<T>>[]): () => void;
+    enqueue(payload: T, opts?: {
+        id?: string;
+        metadata?: Record<string, unknown>;
+    }): string;
+    claim(limit?: number): readonly JobEnvelope<T>[];
+    ack(id: string): boolean;
+    nack(id: string, opts?: {
+        requeue?: boolean;
+    }): boolean;
+    /**
+     * Remove a job by id regardless of its current state. Returns `true` if
+     * the job existed and was removed, `false` if no job has this id.
+     *
+     * `ack` only works on inflight; `nack` only works on inflight.
+     * `removeById` is the state-agnostic escape hatch — useful for
+     * audit/observability layers that enqueue but never claim, and need to
+     * finalize a job when an external decision (e.g. harness verify
+     * outcome) resolves it. Distinct name from the inherited
+     * {@link Graph.remove}, which removes a mounted child subgraph by path.
+     *
+     * When the job is in `queued` state, its id is also pulled from the
+     * `pending` list — depth + pending snapshot stay consistent.
+     */
+    removeById(id: string): boolean;
+    /**
+     * Subscribe to a Node and enqueue each DATA payload into this queue.
+     * Returns a disposer that stops consuming when called.
+     *
+     * Used internally by {@link JobFlowGraph} for stage-to-stage wiring but
+     * also useful for users wiring an external source into a job queue.
+     *
+     * @param source - Node whose DATA values are enqueued.
+     * @param opts - Optional enqueue options (id generator, metadata prefix).
+     */
+    consumeFrom(source: Node<T>, opts?: {
+        metadata?: Record<string, unknown>;
+    }): () => void;
+}
+/**
+ * Work function for a job flow stage. Receives the full job envelope,
+ * returns a `NodeInput<T>` — raw value (sync), Promise (async), or Node
+ * (composed pipeline). `fromAny` coerces any of these shapes.
+ *
+ * On error / rejection: the stage nacks the job (no requeue by default).
+ */
+type WorkFn<T> = (job: JobEnvelope<T>) => NodeInput<T>;
+/**
+ * Stage definition for {@link JobFlowGraph}. Either a bare name string
+ * (no work hook, pure pass-through) or a full definition object.
+ */
+type StageDef<T> = string | {
+    name: string;
+    work?: WorkFn<T>;
+    handlerVersion?: {
+        id: string;
+        version: string | number;
+    };
+};
+type JobFlowOptions<T = unknown> = {
+    graph?: GraphOptions;
+    /**
+     * Stage definitions. Each stage is either a bare name string (pure
+     * pass-through) or a `{ name, work?, handlerVersion? }` object.
+     *
+     * For back-compat, `string[]` values behave as stages with no work hook.
+     */
+    stages?: readonly StageDef<T>[];
+    maxPerPump?: number;
+};
+declare class JobFlowGraph<T> extends Graph {
+    private readonly _stageNames;
+    private readonly _stageWorkFns;
+    private readonly _queues;
+    private readonly _completed;
+    readonly completed: Node<readonly JobEnvelope<T>[]>;
+    readonly completedCount: Node<number>;
+    constructor(name: string, opts?: JobFlowOptions<T>);
+    stages(): readonly string[];
+    queue(stage: string): JobQueueGraph<T>;
+    enqueue(payload: T, opts?: {
+        id?: string;
+        metadata?: Record<string, unknown>;
+    }): string;
+    retainedCompleted(): readonly JobEnvelope<T>[];
+}
+/**
+ * Creates a Pulsar-inspired job queue graph with claim/ack/nack workflow.
+ */
+declare function jobQueue<T>(name: string, opts?: JobQueueOptions): JobQueueGraph<T>;
+/**
+ * Creates an autonomous multi-stage queue chain graph.
+ */
+declare function jobFlow<T>(name: string, opts?: JobFlowOptions<T>): JobFlowGraph<T>;
+
+type index_JobEnvelope<T> = JobEnvelope<T>;
+type index_JobEvent<T = unknown> = JobEvent<T>;
+type index_JobEventAction = JobEventAction;
+type index_JobFlowGraph<T> = JobFlowGraph<T>;
+declare const index_JobFlowGraph: typeof JobFlowGraph;
+type index_JobFlowOptions<T = unknown> = JobFlowOptions<T>;
+type index_JobQueueGraph<T> = JobQueueGraph<T>;
+declare const index_JobQueueGraph: typeof JobQueueGraph;
+type index_JobQueueOptions = JobQueueOptions;
+type index_JobState = JobState;
+type index_StageDef<T> = StageDef<T>;
+type index_WorkFn<T> = WorkFn<T>;
+declare const index_jobEventKeyOf: typeof jobEventKeyOf;
+declare const index_jobFlow: typeof jobFlow;
+declare const index_jobQueue: typeof jobQueue;
+declare namespace index {
+  export { type index_JobEnvelope as JobEnvelope, type index_JobEvent as JobEvent, type index_JobEventAction as JobEventAction, index_JobFlowGraph as JobFlowGraph, type index_JobFlowOptions as JobFlowOptions, index_JobQueueGraph as JobQueueGraph, type index_JobQueueOptions as JobQueueOptions, type index_JobState as JobState, type index_StageDef as StageDef, type index_WorkFn as WorkFn, index_jobEventKeyOf as jobEventKeyOf, index_jobFlow as jobFlow, index_jobQueue as jobQueue };
+}
+
+export { JobQueueGraph as J, type StageDef as S, type WorkFn as W, type JobEnvelope as a, type JobEvent as b, type JobEventAction as c, JobFlowGraph as d, type JobFlowOptions as e, type JobQueueOptions as f, type JobState as g, jobFlow as h, index as i, jobEventKeyOf as j, jobQueue as k };

package/dist/{index-yJY9thRY.d.cts → index-XxSeddWP.d.cts}

@@ -1,5 +1,5 @@
-import { a as Node, N as NodeOptions } from './node-8qx0kgYt.cjs';
-import { a as GraphOptions, G as Graph } from './graph-DaoydJ_u.cjs';
+import { a as Node, N as NodeOptions } from './node-fSc-hCv8.cjs';
+import { a as GraphOptions, G as Graph } from './graph-kTltt95s.cjs';
 
 /**
  * Reduction primitives (roadmap §8.1).

package/dist/{index-C8_bnDBZ.d.cts → index-ZhKyR8co.d.cts}

@@ -1,6 +1,6 @@
-import { M as MeasurementAdapter, P as PreparedSegment, L as LineBreaksResult, C as CharPosition, a as LayoutCursor, I as Interval, b as LayoutLine, c as LayoutNextLineContext, d as LayoutNextLineResult, R as ReactiveLayoutBundle, e as ReactiveLayoutOptions, S as SegmentBreakKind, f as SegmentMeasureStats, g as analyzeAndMeasure, h as carveTextLineSlots, i as computeCharPositions, j as computeLineBreaks, l as layoutNextLine, r as reactiveLayout } from './reactive-layout-Dk9AOQb_.cjs';
-import { a as Node } from './node-8qx0kgYt.cjs';
-import { G as Graph } from './graph-DaoydJ_u.cjs';
+import { M as MeasurementAdapter, P as PreparedSegment, L as LineBreaksResult, C as CharPosition, a as LayoutCursor, I as Interval, b as LayoutLine, c as LayoutNextLineContext, d as LayoutNextLineResult, R as ReactiveLayoutBundle, e as ReactiveLayoutOptions, S as SegmentBreakKind, f as SegmentMeasureStats, g as analyzeAndMeasure, h as carveTextLineSlots, i as computeCharPositions, j as computeLineBreaks, l as layoutNextLine, r as reactiveLayout } from './reactive-layout-D9zqqaqK.cjs';
+import { a as Node } from './node-fSc-hCv8.cjs';
+import { G as Graph } from './graph-kTltt95s.cjs';
 
 /**
  * MeasurementAdapter implementations (roadmap §7.1 — pluggable backends).

package/dist/index-hXKhbfh-.d.ts

@@ -0,0 +1,287 @@
+import { R as ReactiveLogBundle } from './reactive-log-ByBb8g6A.js';
+import { NodeInput } from './extra/sources.js';
+import { AppendLogStorageTier } from './extra/storage-tiers.js';
+import { B as BaseAuditRecord } from './imperative-audit-ahAE65a9.js';
+import { C as CqrsEventMap, a as CqrsEvent, b as CqrsGraph } from './index-DBmBtqAN.js';
+
+/**
+ * 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),
+ *   optionally event-sourced via synthetic `_process_<name>_state` events that
+ *   use `correlationId` as `aggregateId`.
+ * - 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 synthetic
+ *   event-type names (`_process_<name>_started`, `_process_<name>_state`).
+ * @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 };