@graphrefly/graphrefly 0.44.0 → 0.46.0

package/dist/{index-CasX6Pfq.d.cts → utils/process/index.d.ts}

@@ -1,8 +1,9 @@
-import { B as BaseAuditRecord } from './index-D0aciIex.cjs';
-import { a as ReactiveLogBundle } from './reactive-log-DIGdYqQ6.cjs';
-import { NodeInput } from './extra/sources.cjs';
-import { AppendLogStorageTier, KvStorageTier } from './extra/storage-tiers.cjs';
-import { C as CqrsEventMap, a as CqrsEvent, b as CqrsGraph } from './index-B-_tFaqV.cjs';
+import { Node } from '@graphrefly/pure-ts/core';
+import { NodeInput, AppendLogStorageTier, KvStorageTier, ReactiveLogBundle } from '@graphrefly/pure-ts/extra';
+import { BaseAuditRecord } from '../../base/mutation/index.js';
+import { S as StatusValue } from '../../status-U-rUI79b.js';
+import { CqrsEventMap, CqrsEvent, CqrsGraph } from '../cqrs/index.js';
+import '@graphrefly/pure-ts/graph';
 
 /**
  * Process Manager pattern (Phase 7 — roadmap §4.6, Audit 3 — locked 2026-04-24).
@@ -38,9 +39,9 @@ import { C as CqrsEventMap, a as CqrsEvent, b as CqrsGraph } from './index-B-_tF
  * - `"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"`.
+ * - `"terminate"` — workflow complete; instance moves to `"completed"`.
  *   Process-specific extension to the canonical outcome enum.
- * - `"failure"` — triggers compensation; instance moves to `"compensated"` /
+ * - `"failure"` — triggers compensation; instance moves to `"cancelled"` /
  *   `"errored"`.
  *
  * Field name is `outcome` (matching `cqrs.DispatchRecord.outcome` and the
@@ -98,7 +99,7 @@ type ProcessCompensate<TState> = (state: TState, error: unknown) => NodeInput<vo
 /**
  * Audit record for a single process instance state transition.
  *
- * Every status change (start → running → terminated / errored / compensated)
+ * 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` /
@@ -110,7 +111,7 @@ interface ProcessInstance<TState> extends BaseAuditRecord {
     /** Most-recent instance state at this transition. */
     readonly state: TState;
     /** Current lifecycle status after this transition. */
-    readonly status: "running" | "terminated" | "errored" | "compensated";
+    readonly status: "running" | "completed" | "errored" | "cancelled";
     /** Wall-clock nanoseconds when `start()` was called. */
     readonly startedAt: number;
     /** Wall-clock nanoseconds of this transition. */
@@ -120,7 +121,7 @@ interface ProcessInstance<TState> extends BaseAuditRecord {
         id: string;
         version: string | number;
     };
-    /** Optional human-readable reason for cancellation. Present only on `"compensated"` records produced by `cancel()`. */
+    /** Optional human-readable reason for cancellation. Present only on `"cancelled"` records produced by `cancel()`. */
     readonly reason?: string;
 }
 /**
@@ -134,14 +135,14 @@ declare const processInstanceKeyOf: <TState>(i: ProcessInstance<TState>) => stri
  * lifecycle metadata so a fresh `processManager` can resume in-flight
  * workflows after restart via {@link ProcessManagerResult.restore}.
  *
- * Terminal records (`status` ∈ `"terminated" | "errored" | "compensated"`)
+ * 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" | "terminated" | "errored" | "compensated";
+    readonly status: "running" | "completed" | "errored" | "cancelled";
     readonly startedAt: number;
     readonly updatedAt: number;
     readonly handlerVersion?: {
@@ -170,12 +171,12 @@ interface ProcessManagerOpts<TState, EM extends CqrsEventMap> {
     /**
      * 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"`.
+     * 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 `"terminated"` immediately without
+     * `true`, the instance is moved to `"completed"` immediately without
      * waiting for a `"terminate"` step result.
      */
     readonly isTerminal?: (state: TState) => boolean;
@@ -201,6 +202,33 @@ interface ProcessManagerOpts<TState, EM extends CqrsEventMap> {
         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?: {
         /**
@@ -212,7 +240,7 @@ interface ProcessManagerOpts<TState, EM extends CqrsEventMap> {
          * 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
+         * (`completed` / `errored` / `cancelled`) `delete` the key. After
          * restart, callers invoke {@link ProcessManagerResult.restore} to
          * reload running instances from the first tier.
          *
@@ -257,7 +285,7 @@ interface ProcessManagerResult<TState> {
      * 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
+     * instance as `"cancelled"`. If the instance is not running, this is
      * a no-op.
      *
      * @param correlationId - Instance to cancel.
@@ -270,26 +298,66 @@ interface ProcessManagerResult<TState> {
      */
     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.
+     * 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"`.
      *
-     * Idempotent — calling twice doesn't double-restore (existing entries
-     * are overwritten). Returns the count of running instances rehydrated.
+     * 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.
      *
-     * 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.
+     * **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<number>;
+    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;
 }
@@ -340,19 +408,4 @@ interface ProcessManagerResult<TState> {
  */
 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 };
+export { type ProcessCompensate, type ProcessInstance, type ProcessManagerOpts, type ProcessManagerResult, type ProcessSchedule, type ProcessStateSnapshot, type ProcessStep, type ProcessStepResult, processInstanceKeyOf, processManager, processStateKeyOf };

package/dist/utils/process/index.js

@@ -0,0 +1,14 @@
+import {
+  processInstanceKeyOf,
+  processManager,
+  processStateKeyOf
+} from "../../chunk-EVYY4X5A.js";
+import "../../chunk-BXGZFGZ4.js";
+import "../../chunk-O3MT7DYI.js";
+import "../../chunk-AZDQPQ3V.js";
+export {
+  processInstanceKeyOf,
+  processManager,
+  processStateKeyOf
+};
+//# sourceMappingURL=index.js.map

package/dist/utils/process/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}