@graphrefly/graphrefly 0.44.0 → 0.45.0

package/dist/index-p09KSrTN.d.ts

@@ -1,358 +0,0 @@
-import { B as BaseAuditRecord } from './index-Yq60JP3s.js';
-import { a as ReactiveLogBundle } from './reactive-log-BKALbfal.js';
-import { NodeInput } from './extra/sources.js';
-import { AppendLogStorageTier, KvStorageTier } from './extra/storage-tiers.js';
-import { C as CqrsEventMap, a as CqrsEvent, b as CqrsGraph } from './index-CeFiHtAg.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).
- *   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 `"terminated"`.
- *   Process-specific extension to the canonical outcome enum.
- * - `"failure"` — triggers compensation; instance moves to `"compensated"` /
- *   `"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 → terminated / errored / 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" | "errored" | "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;
-/**
- * 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` ∈ `"terminated" | "errored" | "compensated"`)
- * 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" | "terminated" | "errored" | "compensated";
-    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 `"compensated"`.
-     */
-    readonly compensate?: ProcessCompensate<TState>;
-    /**
-     * Optional predicate called after each `"success"` 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>[];
-        /**
-         * 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
-         * (`terminated` / `errored` / `compensated`) `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 `"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;
-    /**
-     * Restore running instances from the first {@link
-     * ProcessManagerOpts.persistence.stateStorage} tier (Tier 6.5 3.5,
-     * 2026-04-29). Loads every record in the tier and re-hydrates
-     * `instanceStates` / `activeInstances` / `startedAt` for any record
-     * whose `status === "running"`. Terminal records, if any persisted
-     * before delete fired, are silently skipped.
-     *
-     * Idempotent — calling twice doesn't double-restore (existing entries
-     * are overwritten). Returns the count of running instances rehydrated.
-     *
-     * No-op when no `stateStorage` tier is configured OR the first tier
-     * lacks a `list?` method (returns 0). Async because kv tier `load` /
-     * `list` may be async.
-     */
-    restore(): Promise<number>;
-    /**
-     * 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 { 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>;
-
-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_ProcessStateSnapshot<TState> = ProcessStateSnapshot<TState>;
-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 const index_processStateKeyOf: typeof processStateKeyOf;
-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_ProcessStateSnapshot as ProcessStateSnapshot, type index_ProcessStep as ProcessStep, type index_ProcessStepResult as ProcessStepResult, index_processInstanceKeyOf as processInstanceKeyOf, index_processManager as processManager, index_processStateKeyOf as processStateKeyOf };
-}
-
-export { type ProcessCompensate as P, type ProcessInstance as a, type ProcessManagerOpts as b, type ProcessManagerResult as c, type ProcessSchedule as d, type ProcessStateSnapshot as e, type ProcessStep as f, type ProcessStepResult as g, processManager as h, index as i, processStateKeyOf as j, processInstanceKeyOf as p };

package/dist/index-sqkqlb1p.d.ts

@@ -1,37 +0,0 @@
-import { G as Graph } from './graph-D9LFnda9.js';
-
-/** Zustand-compatible Store API. */
-interface StoreApi<T> {
-    getState: () => T;
-    setState: (partial: T | Partial<T> | ((state: T) => T | Partial<T>), replace?: boolean) => void;
-    getInitialState: () => T;
-    subscribe: (listener: (state: T, prevState: T) => void) => () => void;
-    destroy: () => void;
-}
-/** Function type for initializing the store. */
-type StateCreator<T> = (set: StoreApi<T>["setState"], get: StoreApi<T>["getState"], api: StoreApi<T>) => T;
-/**
- * Creates a Zustand-compatible store backed by a GraphReFly state node.
- * returns an object that is both a Graph and a StoreApi.
- *
- * @example
- * ```ts
- * const store = create((set) => ({
- *   count: 0,
- *   inc: () => set((s) => ({ count: s.count + 1 }))
- * }));
- * store.getState().inc();
- * ```
- *
- * @category compat
- */
-declare function create<T extends object>(initializer: StateCreator<T>): Graph & StoreApi<T>;
-
-type index_StateCreator<T> = StateCreator<T>;
-type index_StoreApi<T> = StoreApi<T>;
-declare const index_create: typeof create;
-declare namespace index {
-  export { type index_StateCreator as StateCreator, type index_StoreApi as StoreApi, index_create as create };
-}
-
-export { type StateCreator as S, type StoreApi as a, create as c, index as i };

package/dist/index-tRCxuAXF.d.cts

@@ -1,113 +0,0 @@
-import { N as Node, a as NodeOptions } from './node-kK3CvTrR.cjs';
-import { a as GraphOptions, G as Graph } from './graph-CWvEUQAq.cjs';
-
-/**
- * Reduction primitives (roadmap §8.1).
- *
- * Composable building blocks for taking heterogeneous massive inputs and producing
- * prioritized, auditable, human-actionable output. Each primitive is either a Graph
- * factory or a Node factory, built on top of core + extra primitives.
- *
- * @module
- */
-
-type StepRef = string | Node<unknown>;
-/** A named stage for {@link funnel}. */
-type FunnelStage = {
-    /** Stage name (mounted as subgraph). */
-    name: string;
-    /** Builder: receives a sub-graph, should add an `"input"` and `"output"` node. */
-    build: (sub: Graph) => void;
-};
-/** Options for {@link funnel}. */
-type FunnelOptions = GraphOptions & {
-    meta?: Record<string, unknown>;
-};
-/**
- * Multi-source merge with sequential reduction stages.
- *
- * Sources are merged into a single stream. Each stage is a named subgraph
- * (mounted via `graph.mount()`). Stages connect linearly:
- * `merged → stage[0].input → stage[0].output → stage[1].input → ...`
- *
- * @param name - Graph name.
- * @param sources - Input nodes to merge.
- * @param stages - Sequential reduction stages.
- * @param opts - Optional graph/meta options.
- * @returns Graph with `"merged"` and mounted stage subgraphs.
- *
- * @category patterns
- */
-declare function funnel<T>(name: string, sources: ReadonlyArray<Node<T>>, stages: ReadonlyArray<FunnelStage>, opts?: FunnelOptions): Graph;
-/** Options for {@link feedback}. */
-type FeedbackOptions = {
-    /** Maximum feedback iterations before stopping (default: 10). */
-    maxIterations?: number;
-    /** Optional budget gate node path for cost-bounded iteration. */
-    budgetNode?: StepRef;
-    meta?: Record<string, unknown>;
-};
-/**
- * Introduce a bounded reactive cycle into an existing graph.
- *
- * When `condition` emits a non-null DATA value, the feedback effect routes it
- * back to the `reentry` state node — creating a cycle. Bounded by
- * `maxIterations` (default 10). The counter node (`__feedback_<condition>`)
- * is the source of truth — reset it to 0 to allow more iterations.
- *
- * To remove the feedback cycle, call `graph.remove("__feedback_<condition>")`.
- *
- * @param graph - Existing graph to augment with a feedback cycle.
- * @param condition - Path to a node whose DATA triggers feedback.
- * @param reentry - Path to a state node that receives the feedback value.
- * @param opts - Iteration bounds and metadata.
- * @returns The same graph (mutated with feedback nodes added).
- *
- * @category patterns
- */
-declare function feedback(graph: Graph, condition: string, reentry: string, opts?: FeedbackOptions): Graph;
-/** A scored item with full breakdown. */
-type ScoredItem<T = unknown> = {
-    /** Original value. */
-    value: T;
-    /** Final weighted score. */
-    score: number;
-    /** Per-signal breakdown: signal index → weighted contribution. */
-    breakdown: number[];
-};
-/** Options for {@link scorer}. */
-type ScorerOptions = Omit<NodeOptions<unknown>, "describeKind" | "name" | "meta"> & {
-    meta?: Record<string, unknown>;
-    /** Custom scoring function per signal. Default: identity (signal value IS the score). */
-    scoreFns?: ReadonlyArray<(value: unknown) => number>;
-};
-/**
- * Reactive multi-signal scoring with live weights.
- *
- * Each source emits items to score. Weights are reactive state nodes that
- * LLM or human can adjust live. Output is sorted scored items with full
- * breakdown.
- *
- * @param sources - Signal nodes (each emits a numeric score dimension).
- * @param weights - Reactive weight nodes (one per source).
- * @param opts - Optional node/meta options.
- * @returns Node emitting scored output.
- *
- * @category patterns
- */
-declare function scorer(sources: ReadonlyArray<Node<number>>, weights: ReadonlyArray<Node<number>>, opts?: ScorerOptions): Node<ScoredItem<number[]>>;
-
-type index_FeedbackOptions = FeedbackOptions;
-type index_FunnelOptions = FunnelOptions;
-type index_FunnelStage = FunnelStage;
-type index_ScoredItem<T = unknown> = ScoredItem<T>;
-type index_ScorerOptions = ScorerOptions;
-type index_StepRef = StepRef;
-declare const index_feedback: typeof feedback;
-declare const index_funnel: typeof funnel;
-declare const index_scorer: typeof scorer;
-declare namespace index {
-  export { type index_FeedbackOptions as FeedbackOptions, type index_FunnelOptions as FunnelOptions, type index_FunnelStage as FunnelStage, type index_ScoredItem as ScoredItem, type index_ScorerOptions as ScorerOptions, type index_StepRef as StepRef, index_feedback as feedback, index_funnel as funnel, index_scorer as scorer };
-}
-
-export { type FeedbackOptions as F, type ScoredItem as S, type FunnelOptions as a, type FunnelStage as b, type ScorerOptions as c, type StepRef as d, funnel as e, feedback as f, index as i, scorer as s };