@graphrefly/graphrefly 0.43.0 → 0.44.0

package/dist/{index-CAC_rNzm.d.ts → index-DisjX8a-.d.ts}

@@ -1,9 +1,9 @@
-import { N as Node } from './node-ClS5yC-B.js';
-import { B as BaseAuditRecord } from './index-CZQXo5tH.js';
-import { a as ReactiveLogBundle } from './reactive-log-BezYsbA_.js';
+import { N as Node } from './node-kK3CvTrR.js';
+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 } from './extra/storage-tiers.js';
-import { G as Graph, a as GraphOptions } from './graph-7VguS7a4.js';
+import { G as Graph, a as GraphOptions } from './graph-D9LFnda9.js';
 
 /**
  * Job queue patterns (roadmap §4.2).
@@ -97,13 +97,30 @@ declare class JobQueueGraph<T> extends Graph {
     }): () => 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.
+ * Work function for a job flow stage. Receives the full job envelope and
+ * an optional per-claim options object carrying an `AbortSignal`; 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).
+ *
+ * **Per-claim signal (Tier 6.5 2.5b, 2026-04-29).** The pump mints an
+ * `AbortController` per claim and supplies its `signal` via `opts`. The
+ * signal aborts when (a) the result node settles (first DATA / first
+ * ERROR — auto-cleanup after the pump captures), OR (b) the pump itself
+ * tears down (e.g. parent Graph `destroy()`). User-supplied work fns that
+ * do long-running async (HTTP, LLM streams, evaluator subgraphs) can
+ * forward this signal into `fetch({ signal })`, `adapter.invoke({ signal
+ * })`, etc. for cooperative cancellation. Sync work fns ignore `opts` —
+ * the second arg is optional, no behavior change for legacy callers.
+ *
+ * Mirrors the `LLMInvokeOptions.signal` / `apply(item, { signal })` /
+ * tool-handler `(args, { signal })` precedents — same shape across the
+ * library's user-callback boundaries.
  */
-type WorkFn<T> = (job: JobEnvelope<T>) => NodeInput<T>;
+type WorkFn<T> = (job: JobEnvelope<T>, opts?: {
+    signal: AbortSignal;
+}) => NodeInput<T>;
 /**
  * Stage definition for {@link JobFlowGraph}. Either a bare name string
  * (no work hook, pure pass-through) or a full definition object.
@@ -125,6 +142,21 @@ type StageDef<T> = string | {
      * turn falls back to `DEFAULT_MAX_PER_PUMP` (256).
      */
     maxPerPump?: number;
+    /**
+     * Per-stage cap on TOTAL concurrent inflight claims (Tier 6.5 3.1,
+     * 2026-04-29). Distinct from {@link maxPerPump}: `maxPerPump` caps
+     * claims per pump tick, while `maxInflight` caps the number of
+     * unsettled in-flight claims at any moment across all ticks. Use
+     * for rigorous LLM cost ceilings (e.g. "no more than 4 concurrent
+     * adapter.invoke calls regardless of pending depth").
+     *
+     * When set, the stage mounts an internal `state(0)` counter as a
+     * pump dep so the pump re-fires on each settle — pending items
+     * resume claiming as soon as inflight drops below the cap.
+     *
+     * Unset (default): unbounded inflight, gated only by `maxPerPump`.
+     */
+    maxInflight?: number;
 };
 type JobFlowOptions<T = unknown> = {
     graph?: GraphOptions;

package/dist/{index-B5iz82A3.d.cts → index-UPSiS-X7.d.cts}

@@ -1,18 +1,18 @@
-import { T as TokenUsage, L as LLMAdapter, P as PricingFn, C as ChatMessage, a as LLMInvokeOptions, d as ToolDefinition, b as LLMResponse, S as StreamDelta, c as ToolCall, e as CapabilitiesRegistry, M as ModelCapabilities, f as ModelFeatures, g as ModelLimits, h as ModelPricing, i as PriceBreakdown, j as PricingRegistry, R as Rate, k as TieredRate, l as composePricing, m as computePrice, n as createCapabilitiesRegistry, o as createPricingRegistry, p as pricingFor, r as registryPricing, z as zeroPrice } from './types-B1jDWVsM.cjs';
-import { a as CascadeExhaustionReport, A as AdapterProvider, b as AdapterTier, d as AllTiersExhaustedError, C as CascadingLlmAdapterOptions, e as CreateAdapterOptions, O as OpenAICompatAdapterOptions, f as OpenAICompatPreset, g as OpenAISdkLike, h as cascadingLlmAdapter, c as createAdapter, o as openAICompatAdapter, t as tier } from './cascading-CH-_VwG9.cjs';
-import { N as Node, A as Actor } from './node-ClS5yC-B.cjs';
-import { a as ReactiveLogBundle } from './reactive-log-B00laMSQ.cjs';
-import { b as CircuitBreakerOptions, C as CircuitBreaker, c as CircuitOpenError } from './index-BoLv_OfD.cjs';
+import { T as TokenUsage, L as LLMAdapter, P as PricingFn, C as ChatMessage, a as LLMInvokeOptions, d as ToolDefinition, b as LLMResponse, S as StreamDelta, c as ToolCall, e as CapabilitiesRegistry, M as ModelCapabilities, f as ModelFeatures, g as ModelLimits, h as ModelPricing, i as PriceBreakdown, j as PricingRegistry, R as Rate, k as TieredRate, l as composePricing, m as computePrice, n as createCapabilitiesRegistry, o as createPricingRegistry, p as pricingFor, r as registryPricing, z as zeroPrice } from './types-C0_yquda.cjs';
+import { a as CascadeExhaustionReport, A as AdapterProvider, b as AdapterTier, d as AllTiersExhaustedError, C as CascadingLlmAdapterOptions, e as CreateAdapterOptions, O as OpenAICompatAdapterOptions, f as OpenAICompatPreset, g as OpenAISdkLike, h as cascadingLlmAdapter, c as createAdapter, o as openAICompatAdapter, t as tier } from './cascading-BglDkMdX.cjs';
+import { N as Node, A as Actor } from './node-kK3CvTrR.cjs';
+import { a as ReactiveLogBundle } from './reactive-log-DIGdYqQ6.cjs';
+import { b as CircuitBreakerOptions, C as CircuitBreaker, c as CircuitOpenError } from './index-C1T3d7V-.cjs';
 import { NodeInput } from './extra/sources.cjs';
-import { W as WithReplayCacheOptions, F as FallbackAdapterOptions, a as FallbackFixture, b as FallbackMissError, c as FallbackMissPolicy, R as ReplayCacheKeyContext, d as ReplayCacheMissError, e as ReplayCacheMode, f as canonicalJson, g as fallbackAdapter, w as withReplayCache } from './fallback-Ctlj2tMY.cjs';
-import { E as Extraction, D as DistillBundle, f as DEFAULT_DECAY_RATE } from './decay-2ZukgQ4o.cjs';
-import { G as Graph, a as GraphOptions, i as GraphCheckpointRecord, h as GraphAttachStorageOptions } from './graph-C4SHb3Ly.cjs';
-import { T as TopicGraph } from './index-BTQtTb_H.cjs';
-import { G as GateController, c as GateOptions } from './pipeline-graph-DPqKDk59.cjs';
-import { V as VectorSearchResult, C as CollectionGraph, a as VectorIndexGraph, K as KnowledgeGraph } from './index-CLon-IWF.cjs';
+import { W as WithReplayCacheOptions, F as FallbackAdapterOptions, a as FallbackFixture, b as FallbackMissError, c as FallbackMissPolicy, R as ReplayCacheKeyContext, d as ReplayCacheMissError, e as ReplayCacheMode, f as canonicalJson, g as fallbackAdapter, w as withReplayCache } from './fallback-74oxi34l.cjs';
+import { E as Extraction, a as DistillOptions, D as DistillBundle, f as DEFAULT_DECAY_RATE } from './decay-CFlLvXUT.cjs';
+import { G as Graph, a as GraphOptions, i as GraphCheckpointRecord, h as GraphAttachStorageOptions } from './graph-CWvEUQAq.cjs';
+import { T as TopicGraph } from './index-C5ri2Axc.cjs';
+import { G as GateController, c as GateOptions } from './pipeline-graph-CIKhynsF.cjs';
+import { V as VectorSearchResult, C as CollectionGraph, a as VectorIndexGraph, K as KnowledgeGraph } from './index-B17QddL1.cjs';
 import { StorageHandle } from './extra/storage-core.cjs';
 import { SnapshotStorageTier } from './extra/storage-tiers.cjs';
-import { c as GraphSpecCatalog } from './index-Du7u1lSf.cjs';
+import { c as GraphSpecCatalog } from './index-CS0LTlB8.cjs';
 
 /**
  * Observable adapter wrapper — the "inverted statistics" surface.
@@ -1902,24 +1902,49 @@ declare function memoryWithKG<TMem>(graph: Graph, store: DistillBundle<TMem>, na
     kg: KnowledgeGraph<unknown, string>;
     dispose: () => void;
 };
-type MemoryWithTiersOptions<TMem> = MemoryTiersOptions<TMem> & {
+/**
+ * Full options for {@link memoryWithTiers} (Tier 4.1 B + 4.3 B refactor,
+ * 2026-04-29). Combines tier-policy options with the distill-side options
+ * needed to construct the underlying store — `memoryWithTiers` is now the
+ * **construction site** for the distill bundle so it can wire
+ * `reactiveMap.retention` into the store at construction (eliminating the
+ * §7 feedback cycle the previous `tierClassifier` effect carried).
+ *
+ * The retention config built internally maps tier policy to the substrate:
+ * - `archiveThreshold` → `retention.archiveThreshold`
+ * - `maxActive` → `retention.maxSize`
+ * - per-entry `decay(score(mem, ctx), age, decayRate)` → `retention.score`
+ *   (capturing `latestCtx` + `entryCreatedAtNs` via closure-mirror; permanent
+ *   entries score `Infinity` to bypass eviction).
+ */
+type MemoryWithTiersOptions<TMem> = MemoryTiersOptions<TMem> & Omit<DistillOptions<TMem>, "mapOptions" | "score" | "context"> & {
     /** Score function — same signature as `agentMemory.score`. */
     score: (mem: TMem, context: unknown) => number;
     /** Optional reactive context node (passed to `score`). */
     context?: NodeInput<unknown>;
 };
 /**
- * Attach 3-tier storage (active / archived / permanent) to a `DistillBundle`.
- * Wires a `tierClassifier` effect that:
- * - Promotes entries matching `permanentFilter` into the permanent tier.
- * - Archives entries whose decayed score falls below `archiveThreshold`.
- * - Caps the active tier at `maxActive`, evicting lowest-scored on overflow.
- *
- * **Closure state caveat (Unit 7 Q3 deferred):** `permanentKeys` +
- * `entryCreatedAtNs` are still closure-held for now; promotion to reactive
- * nodes is tracked in `docs/optimizations.md`.
- */
-declare function memoryWithTiers<TMem>(graph: Graph, store: DistillBundle<TMem>, opts: MemoryWithTiersOptions<TMem>): {
+ * Attach 3-tier storage (active / archived / permanent) to a fresh distill
+ * store, wiring `reactiveMap.retention` at construction so archival happens
+ * synchronously inside the substrate's mutation pipeline (no §7 feedback
+ * cycle). Promotes `permanentKeys` and `entryCreatedAtNs` to reactive maps
+ * mounted on the graph (Tier 4.3 B — Unit 7 Q3) so `describe()`/`explain()`
+ * can walk to "why was X archived?".
+ *
+ * **API shape** (Tier 4.1 B, 2026-04-29 — breaking change vs. pre-refactor):
+ * `memoryWithTiers` constructs the distill bundle internally rather than
+ * accepting a pre-built one. Callers pass `(graph, source, extractFn,
+ * opts)`. The bundle is exposed as `result.store` for downstream composers
+ * (vectors / KG / retrieval).
+ *
+ * - `permanentFilter`-matching entries score `Infinity` in retention →
+ *   never archived. Independent permanent-promotion effect upserts them
+ *   into the `permanent` collection.
+ * - Below-threshold entries → retention archives synchronously.
+ * - Over-`maxActive` entries → retention's `maxSize` evicts lowest-scored.
+ */
+declare function memoryWithTiers<TRaw, TMem>(graph: Graph, source: NodeInput<TRaw>, extractFn: (raw: Node<TRaw>, existing: Node<ReadonlyMap<string, TMem>>) => NodeInput<Extraction<TMem>>, opts: MemoryWithTiersOptions<TMem>): {
+    store: DistillBundle<TMem>;
     tiers: MemoryTiersBundle<TMem>;
     dispose: () => void;
 };

package/dist/{index-CZQXo5tH.d.ts → index-Yq60JP3s.d.ts}

@@ -1,6 +1,6 @@
-import { b as NodeGuard, N as Node } from './node-ClS5yC-B.js';
-import { G as Graph } from './graph-7VguS7a4.js';
-import { R as ReactiveLogOptions, a as ReactiveLogBundle } from './reactive-log-BezYsbA_.js';
+import { b as NodeGuard, N as Node } from './node-kK3CvTrR.js';
+import { G as Graph } from './graph-D9LFnda9.js';
+import { R as ReactiveLogOptions, a as ReactiveLogBundle } from './reactive-log-BKALbfal.js';
 
 /**
  * Audited-mutation framework (Audit 2 — locked 2026-04-24; promoted to

package/dist/{index-f5IivDUX.d.cts → index-ZVQhLa2i.d.cts}

@@ -1,4 +1,4 @@
-import { G as Graph } from './graph-C4SHb3Ly.cjs';
+import { G as Graph } from './graph-CWvEUQAq.cjs';
 
 /** Zustand-compatible Store API. */
 interface StoreApi<T> {

package/dist/{index-hHcaFlJX.d.cts → index-_6ODbuOu.d.cts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-ClS5yC-B.cjs';
+import { N as Node } from './node-kK3CvTrR.cjs';
 
 /** Svelte store contract — implements the minimal `subscribe` method. */
 interface SvelteReadable<T> {

package/dist/{index-BVpm6noz.d.cts → index-hcDJ8PSI.d.cts}

@@ -1,4 +1,4 @@
-import { N as Node } from './node-ClS5yC-B.cjs';
+import { N as Node } from './node-kK3CvTrR.cjs';
 
 /** Solid accessor function — returns current value when called. */
 type Accessor<T> = () => T;

package/dist/{index-DBHK8O6H.d.ts → index-nozs3fFC.d.ts}

@@ -1,6 +1,6 @@
-import { N as Node } from './node-ClS5yC-B.js';
-import { G as Graph, a as GraphOptions } from './graph-7VguS7a4.js';
-import { a as ReactiveLogBundle } from './reactive-log-BezYsbA_.js';
+import { N as Node } from './node-kK3CvTrR.js';
+import { G as Graph, a as GraphOptions } from './graph-D9LFnda9.js';
+import { a as ReactiveLogBundle } from './reactive-log-BKALbfal.js';
 import { AppendLogStorageTier } from './extra/storage-tiers.js';
 
 type TopicOptions = {

package/dist/{index-Dh_HJ82K.d.ts → index-p09KSrTN.d.ts}

@@ -1,8 +1,8 @@
-import { B as BaseAuditRecord } from './index-CZQXo5tH.js';
-import { a as ReactiveLogBundle } from './reactive-log-BezYsbA_.js';
+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 } from './extra/storage-tiers.js';
-import { C as CqrsEventMap, a as CqrsEvent, b as CqrsGraph } from './index-CQG3D1cp.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).
@@ -16,9 +16,9 @@ import { C as CqrsEventMap, a as CqrsEvent, b as CqrsGraph } from './index-CQG3D
  * - 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".
+ *   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
@@ -127,6 +127,30 @@ interface ProcessInstance<TState> extends BaseAuditRecord {
  * 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}.
  */
@@ -184,6 +208,23 @@ interface ProcessManagerOpts<TState, EM extends CqrsEventMap> {
          * 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>>[];
     };
 }
 /**
@@ -228,6 +269,22 @@ interface ProcessManagerResult<TState> {
      * 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.
      *
@@ -288,12 +345,14 @@ 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_ProcessStep as ProcessStep, type index_ProcessStepResult as ProcessStepResult, index_processInstanceKeyOf as processInstanceKeyOf, index_processManager as processManager };
+  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 ProcessStep as e, type ProcessStepResult as f, processManager as g, index as i, processInstanceKeyOf as p };
+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-C7O6r5fV.d.ts → index-sqkqlb1p.d.ts}

@@ -1,4 +1,4 @@
-import { G as Graph } from './graph-7VguS7a4.js';
+import { G as Graph } from './graph-D9LFnda9.js';
 
 /** Zustand-compatible Store API. */
 interface StoreApi<T> {

package/dist/{index-CZjOhcBy.d.cts → index-tRCxuAXF.d.cts}

@@ -1,5 +1,5 @@
-import { N as Node, a as NodeOptions } from './node-ClS5yC-B.cjs';
-import { a as GraphOptions, G as Graph } from './graph-C4SHb3Ly.cjs';
+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).