@graphrefly/graphrefly 0.20.0 → 0.22.0

package/README.md

@@ -1,13 +1,13 @@
 # GraphReFly
 
-**Describe what matters. It watches, filters, and explains — persistently.**
+**The reactive harness layer for agent workflows.** Describe in plain language, review visually, run persistently, trace every decision.
 
-You're buried under emails, alerts, feeds, and messages. You can't process it all. GraphReFly lets you describe automations in plain language, review them visually, run them persistently, and trace every decision back to its source.
+GraphReFly makes long-running human + LLM co-operation reactive, resumable, and causally explainable. State pushes downstream on change (no re-reading), nodes have lifecycles (not infinite append), and every decision has a traceable causal chain — the substrate underneath tools, agents, and personal automations.
 
 [![npm](https://img.shields.io/npm/v/@graphrefly/graphrefly?color=blue)](https://www.npmjs.com/package/@graphrefly/graphrefly)
 [![license](https://img.shields.io/github/license/graphrefly/graphrefly-ts)](./LICENSE)
 
-[Docs](https://graphrefly.dev) | [Spec](https://graphrefly.dev/spec/) | [Python API](https://graphrefly.dev/py/api/) | [API Reference](https://graphrefly.dev/api/node/)
+[Docs](https://graphrefly.dev) | [Spec](https://graphrefly.dev/spec/) | [Python API](https://graphrefly.dev/py/api/) | [TS API Reference](https://graphrefly.dev/api/node/)
 
 ---
 
@@ -46,6 +46,23 @@ count.set(3);
 
 You describe what you need — an LLM composes a reactive graph (like SQL for data flows). The graph runs persistently, checkpoints its state, and traces every decision through a causal chain. Ask "why?" at any point and get a human-readable explanation from source to conclusion.
 
+## Harness engineering coverage
+
+The eight requirements of a production agent harness cluster into a handful of composed blocks that sit on top of the reactive graph primitives:
+
+| Need | GraphReFly |
+|---|---|
+| Context & state | `persistentState()` — `autoCheckpoint` + `snapshot` / `restore` + incremental diff |
+| Agent memory | `agentMemory()` — `distill` + vectors + knowledge graph + tiers, OpenViking decay |
+| Control flow & resilience | `resilientPipeline()` — `rateLimiter → breaker → retry → timeout → fallback`, correct ordering built in |
+| Execution & policy | `guardedExecution()` — Actor / Guard ABAC + `policy()` + `budgetGate` + scoped describe |
+| Observability & causality | `graphLens()` — reactive topology, health, flow, and `why(node)` causal chains as structured data |
+| Human governance | `gate` — reactive `pending` / `isOpen` with `approve` / `reject` / `modify(fn, n)` |
+| Verification | Multi-model eval harness with regression gates |
+| Continuous improvement | Strategy model: `rootCause × intervention → successRate` |
+
+The library computes structured facts reactively; LLMs and UIs render them. Natural language is never the library's job — which keeps the whole stack model-agnostic and testable.
+
 ## Why GraphReFly?
 
 |  | Zustand / Jotai | RxJS | XState | LangGraph | TC39 Signals | **GraphReFly** |
@@ -183,10 +200,10 @@ import { node, map, Graph } from "@graphrefly/graphrefly";
 
 ## Resilience & checkpoints
 
-Built-in retry, circuit breakers, rate limiters, and persistent checkpoints:
+Built-in retry, circuit breakers, rate limiters, and persistent storage:
 
 ```ts
-import { retry, circuitBreaker, saveGraphCheckpoint, FileCheckpointAdapter } from "@graphrefly/graphrefly";
+import { retry, circuitBreaker, fileStorage, memoryStorage } from "@graphrefly/graphrefly";
 
 // Retry with exponential backoff
 const resilient = pipe(source, retry({ strategy: "exponential" }));
@@ -194,9 +211,11 @@ const resilient = pipe(source, retry({ strategy: "exponential" }));
 // Circuit breaker
 const breaker = circuitBreaker({ threshold: 5, resetTimeout: 30_000 });
 
-// Checkpoint to file system
-const adapter = new FileCheckpointAdapter("./checkpoints");
-await saveGraphCheckpoint(graph, adapter);
+// Multi-tier storage with auto-restore: hot in-memory + warm on disk.
+graph.attachStorage(
+  [memoryStorage(), fileStorage("./checkpoints")],
+  { autoRestore: true },
+);
 ```
 
 ## Project layout

package/dist/chunk-44HD4BTA.js

@@ -0,0 +1,47 @@
+import {
+  GRAPH_META_SEGMENT,
+  Graph,
+  OVERHEAD,
+  SIZEOF_SYMBOL,
+  diffForWAL,
+  graphProfile,
+  reachable,
+  sizeof
+} from "./chunk-NXC35KC5.js";
+import {
+  ENVELOPE_VERSION,
+  JsonCodec,
+  __export,
+  createDagCborCodec,
+  createDagCborZstdCodec,
+  decodeEnvelope,
+  encodeEnvelope,
+  registerBuiltinCodecs,
+  replayWAL
+} from "./chunk-QA3RP5NH.js";
+
+// src/graph/index.ts
+var graph_exports = {};
+__export(graph_exports, {
+  ENVELOPE_VERSION: () => ENVELOPE_VERSION,
+  GRAPH_META_SEGMENT: () => GRAPH_META_SEGMENT,
+  Graph: () => Graph,
+  JsonCodec: () => JsonCodec,
+  SIZEOF_OVERHEAD: () => OVERHEAD,
+  SIZEOF_SYMBOL: () => SIZEOF_SYMBOL,
+  createDagCborCodec: () => createDagCborCodec,
+  createDagCborZstdCodec: () => createDagCborZstdCodec,
+  decodeEnvelope: () => decodeEnvelope,
+  diffForWAL: () => diffForWAL,
+  encodeEnvelope: () => encodeEnvelope,
+  graphProfile: () => graphProfile,
+  reachable: () => reachable,
+  registerBuiltinCodecs: () => registerBuiltinCodecs,
+  replayWAL: () => replayWAL,
+  sizeof: () => sizeof
+});
+
+export {
+  graph_exports
+};
+//# sourceMappingURL=chunk-44HD4BTA.js.map

package/dist/chunk-44HD4BTA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/graph/index.ts"],"sourcesContent":["/**\n * Graph container: registry, wiring, introspection (Phase 1).\n */\n\nexport { OVERHEAD as SIZEOF_OVERHEAD, SIZEOF_SYMBOL, sizeof } from \"../extra/utils/sizeof.js\";\nexport {\n\tcreateDagCborCodec,\n\tcreateDagCborZstdCodec,\n\tdecodeEnvelope,\n\tENVELOPE_VERSION,\n\ttype EvictedSubgraphInfo,\n\ttype EvictionPolicy,\n\tencodeEnvelope,\n\ttype GraphCodec,\n\tJsonCodec,\n\ttype LazyGraphCodec,\n\tregisterBuiltinCodecs,\n\treplayWAL,\n\ttype WALEntry,\n} from \"./codec.js\";\nexport {\n\ttype DescribeFilter,\n\tdiffForWAL,\n\tGRAPH_META_SEGMENT,\n\tGraph,\n\ttype GraphActorOptions,\n\ttype GraphAttachStorageOptions,\n\ttype GraphCheckpointRecord,\n\ttype GraphDescribeOptions,\n\ttype GraphDescribeOutput,\n\ttype GraphDiagramDirection,\n\ttype GraphDiagramOptions,\n\ttype GraphDiffChange,\n\ttype GraphDiffResult,\n\ttype GraphFactoryContext,\n\ttype GraphNodeFactory,\n\ttype GraphObserveAll,\n\ttype GraphObserveOne,\n\ttype GraphOptions,\n\ttype GraphPersistSnapshot,\n\ttype GraphVersionChange,\n\ttype GraphWALDiff,\n\ttype ObserveDetail,\n\ttype ObserveEvent,\n\ttype ObserveOptions,\n\ttype ObserveResult,\n\ttype ObserveTheme,\n\ttype ObserveThemeName,\n\ttype ReachableDirection,\n\ttype ReachableOptions,\n\treachable,\n\ttype TraceEntry,\n} from \"./graph.js\";\nexport {\n\ttype GraphProfileOptions,\n\ttype GraphProfileResult,\n\tgraphProfile,\n\ttype NodeProfile,\n} from \"./profile.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;","names":[]}

package/dist/chunk-7TAQJHQV.js

@@ -0,0 +1,103 @@
+// src/extra/timer.ts
+var ResettableTimer = class {
+  _timer;
+  _gen = 0;
+  /** Schedule callback after delayMs. Cancels any pending timer. */
+  start(delayMs, callback) {
+    this.cancel();
+    this._gen += 1;
+    const gen = this._gen;
+    this._timer = setTimeout(() => {
+      this._timer = void 0;
+      if (gen !== this._gen) return;
+      callback();
+    }, delayMs);
+  }
+  /** Cancel the pending timer (if any). */
+  cancel() {
+    if (this._timer !== void 0) {
+      clearTimeout(this._timer);
+      this._timer = void 0;
+    }
+  }
+  /** Whether a timer is currently pending. */
+  get pending() {
+    return this._timer !== void 0;
+  }
+};
+
+// src/extra/utils/ring-buffer.ts
+var RingBuffer = class {
+  constructor(capacity) {
+    this.capacity = capacity;
+    if (!Number.isInteger(capacity) || capacity <= 0) {
+      throw new Error(`RingBuffer capacity must be a positive integer (got ${capacity})`);
+    }
+    this.buf = new Array(capacity);
+  }
+  buf;
+  head = 0;
+  _size = 0;
+  /** Current number of stored entries. */
+  get size() {
+    return this._size;
+  }
+  /** Configured maximum before drop-oldest eviction fires. */
+  get maxSize() {
+    return this.capacity;
+  }
+  /**
+   * Append an item. If size equals capacity, drops the oldest entry and
+   * advances the head pointer.
+   */
+  push(item) {
+    const idx = (this.head + this._size) % this.capacity;
+    this.buf[idx] = item;
+    if (this._size < this.capacity) this._size++;
+    else this.head = (this.head + 1) % this.capacity;
+  }
+  /** Remove and return the oldest entry; `undefined` when empty. */
+  shift() {
+    if (this._size === 0) return void 0;
+    const item = this.buf[this.head];
+    this.buf[this.head] = void 0;
+    this.head = (this.head + 1) % this.capacity;
+    this._size--;
+    return item;
+  }
+  /**
+   * O(1) index lookup. Negative indices count from the tail (Python-style).
+   * Returns `undefined` for out-of-range.
+   */
+  at(i) {
+    if (this._size === 0) return void 0;
+    const n = i < 0 ? this._size + i : i;
+    if (n < 0 || n >= this._size) return void 0;
+    return this.buf[(this.head + n) % this.capacity];
+  }
+  /**
+   * Materialize the contents in insertion order (oldest → newest).
+   * Returns a new array each call.
+   */
+  toArray() {
+    const result = new Array(this._size);
+    for (let i = 0; i < this._size; i++) {
+      result[i] = this.buf[(this.head + i) % this.capacity];
+    }
+    return result;
+  }
+  /** Reset to empty. Storage slots are released so held refs can GC. */
+  clear() {
+    for (let i = 0; i < this._size; i++) {
+      this.buf[(this.head + i) % this.capacity] = void 0;
+    }
+    this.head = 0;
+    this._size = 0;
+  }
+};
+
+export {
+  ResettableTimer,
+  RingBuffer
+};
+//# sourceMappingURL=chunk-7TAQJHQV.js.map

package/dist/chunk-7TAQJHQV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/extra/timer.ts","../src/extra/utils/ring-buffer.ts"],"sourcesContent":["/**\n * Creates a resettable deadline timer for internal timeout, retry, and rate-limiting use.\n *\n * @remarks **Centralised primitive:** wraps `setTimeout`/`clearTimeout` with a generation guard\n * so that stale callbacks never fire after `cancel()` or a new `start()`.\n *\n * @remarks **Spec §5.10 exception:** resilience operators (`timeout`, `retry`, `rateLimiter`)\n * need raw timers — `fromTimer` creates a new Node per reset, which is too heavy here.\n * Lives in `src/extra/` (not `src/core/`) because it is a documented escape hatch from\n * the protocol-pure core layer.\n *\n * @example\n * ```ts\n * import { ResettableTimer } from \"@graphrefly/graphrefly-ts\";\n *\n * const timer = new ResettableTimer();\n * timer.start(1000, () => console.log(\"fired\"));\n * timer.cancel();          // cancels before firing\n * timer.start(500, () => console.log(\"new deadline\"));\n * console.log(timer.pending); // true\n * ```\n *\n * @category extra\n */\nexport class ResettableTimer {\n\tprivate _timer: ReturnType<typeof setTimeout> | undefined;\n\tprivate _gen = 0;\n\n\t/** Schedule callback after delayMs. Cancels any pending timer. */\n\tstart(delayMs: number, callback: () => void): void {\n\t\tthis.cancel();\n\t\tthis._gen += 1;\n\t\tconst gen = this._gen;\n\t\tthis._timer = setTimeout(() => {\n\t\t\tthis._timer = undefined;\n\t\t\tif (gen !== this._gen) return;\n\t\t\tcallback();\n\t\t}, delayMs);\n\t}\n\n\t/** Cancel the pending timer (if any). */\n\tcancel(): void {\n\t\tif (this._timer !== undefined) {\n\t\t\tclearTimeout(this._timer);\n\t\t\tthis._timer = undefined;\n\t\t}\n\t}\n\n\t/** Whether a timer is currently pending. */\n\tget pending(): boolean {\n\t\treturn this._timer !== undefined;\n\t}\n}\n","/**\n * Fixed-capacity ring buffer — O(1) push and drop-oldest eviction.\n *\n * Used by `Graph._traceRing` (reasoning trace), `reactiveLog` (append-only\n * log backend), and `reactiveSink` (drop-oldest backpressure buffer). One\n * implementation, three use sites.\n *\n * @module\n * @internal\n */\n\n/**\n * Fixed-capacity ring buffer. Once `capacity` entries are stored, subsequent\n * `push` calls evict the oldest entry (drop-oldest / FIFO eviction).\n *\n * Operations:\n * - `push(item)` — O(1).\n * - `shift()` — O(1) remove oldest (returns `undefined` when empty).\n * - `at(i)` — O(1) index lookup, with Python-style negative indexing.\n * - `toArray()` — O(n) materialize in insertion order.\n * - `clear()` — O(1) reset to empty.\n *\n * Not thread-safe; JS semantics assumed (single-threaded within a sync call).\n */\nexport class RingBuffer<T> {\n\tprivate buf: (T | undefined)[];\n\tprivate head = 0;\n\tprivate _size = 0;\n\n\tconstructor(private capacity: number) {\n\t\tif (!Number.isInteger(capacity) || capacity <= 0) {\n\t\t\tthrow new Error(`RingBuffer capacity must be a positive integer (got ${capacity})`);\n\t\t}\n\t\tthis.buf = new Array(capacity);\n\t}\n\n\t/** Current number of stored entries. */\n\tget size(): number {\n\t\treturn this._size;\n\t}\n\n\t/** Configured maximum before drop-oldest eviction fires. */\n\tget maxSize(): number {\n\t\treturn this.capacity;\n\t}\n\n\t/**\n\t * Append an item. If size equals capacity, drops the oldest entry and\n\t * advances the head pointer.\n\t */\n\tpush(item: T): void {\n\t\tconst idx = (this.head + this._size) % this.capacity;\n\t\tthis.buf[idx] = item;\n\t\tif (this._size < this.capacity) this._size++;\n\t\telse this.head = (this.head + 1) % this.capacity;\n\t}\n\n\t/** Remove and return the oldest entry; `undefined` when empty. */\n\tshift(): T | undefined {\n\t\tif (this._size === 0) return undefined;\n\t\tconst item = this.buf[this.head];\n\t\tthis.buf[this.head] = undefined;\n\t\tthis.head = (this.head + 1) % this.capacity;\n\t\tthis._size--;\n\t\treturn item;\n\t}\n\n\t/**\n\t * O(1) index lookup. Negative indices count from the tail (Python-style).\n\t * Returns `undefined` for out-of-range.\n\t */\n\tat(i: number): T | undefined {\n\t\tif (this._size === 0) return undefined;\n\t\tconst n = i < 0 ? this._size + i : i;\n\t\tif (n < 0 || n >= this._size) return undefined;\n\t\treturn this.buf[(this.head + n) % this.capacity];\n\t}\n\n\t/**\n\t * Materialize the contents in insertion order (oldest → newest).\n\t * Returns a new array each call.\n\t */\n\ttoArray(): T[] {\n\t\tconst result: T[] = new Array(this._size);\n\t\tfor (let i = 0; i < this._size; i++) {\n\t\t\tresult[i] = this.buf[(this.head + i) % this.capacity]!;\n\t\t}\n\t\treturn result;\n\t}\n\n\t/** Reset to empty. Storage slots are released so held refs can GC. */\n\tclear(): void {\n\t\tfor (let i = 0; i < this._size; i++) {\n\t\t\tthis.buf[(this.head + i) % this.capacity] = undefined;\n\t\t}\n\t\tthis.head = 0;\n\t\tthis._size = 0;\n\t}\n}\n"],"mappings":";AAwBO,IAAM,kBAAN,MAAsB;AAAA,EACpB;AAAA,EACA,OAAO;AAAA;AAAA,EAGf,MAAM,SAAiB,UAA4B;AAClD,SAAK,OAAO;AACZ,SAAK,QAAQ;AACb,UAAM,MAAM,KAAK;AACjB,SAAK,SAAS,WAAW,MAAM;AAC9B,WAAK,SAAS;AACd,UAAI,QAAQ,KAAK,KAAM;AACvB,eAAS;AAAA,IACV,GAAG,OAAO;AAAA,EACX;AAAA;AAAA,EAGA,SAAe;AACd,QAAI,KAAK,WAAW,QAAW;AAC9B,mBAAa,KAAK,MAAM;AACxB,WAAK,SAAS;AAAA,IACf;AAAA,EACD;AAAA;AAAA,EAGA,IAAI,UAAmB;AACtB,WAAO,KAAK,WAAW;AAAA,EACxB;AACD;;;AC5BO,IAAM,aAAN,MAAoB;AAAA,EAK1B,YAAoB,UAAkB;AAAlB;AACnB,QAAI,CAAC,OAAO,UAAU,QAAQ,KAAK,YAAY,GAAG;AACjD,YAAM,IAAI,MAAM,uDAAuD,QAAQ,GAAG;AAAA,IACnF;AACA,SAAK,MAAM,IAAI,MAAM,QAAQ;AAAA,EAC9B;AAAA,EATQ;AAAA,EACA,OAAO;AAAA,EACP,QAAQ;AAAA;AAAA,EAUhB,IAAI,OAAe;AAClB,WAAO,KAAK;AAAA,EACb;AAAA;AAAA,EAGA,IAAI,UAAkB;AACrB,WAAO,KAAK;AAAA,EACb;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,KAAK,MAAe;AACnB,UAAM,OAAO,KAAK,OAAO,KAAK,SAAS,KAAK;AAC5C,SAAK,IAAI,GAAG,IAAI;AAChB,QAAI,KAAK,QAAQ,KAAK,SAAU,MAAK;AAAA,QAChC,MAAK,QAAQ,KAAK,OAAO,KAAK,KAAK;AAAA,EACzC;AAAA;AAAA,EAGA,QAAuB;AACtB,QAAI,KAAK,UAAU,EAAG,QAAO;AAC7B,UAAM,OAAO,KAAK,IAAI,KAAK,IAAI;AAC/B,SAAK,IAAI,KAAK,IAAI,IAAI;AACtB,SAAK,QAAQ,KAAK,OAAO,KAAK,KAAK;AACnC,SAAK;AACL,WAAO;AAAA,EACR;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,GAAG,GAA0B;AAC5B,QAAI,KAAK,UAAU,EAAG,QAAO;AAC7B,UAAM,IAAI,IAAI,IAAI,KAAK,QAAQ,IAAI;AACnC,QAAI,IAAI,KAAK,KAAK,KAAK,MAAO,QAAO;AACrC,WAAO,KAAK,KAAK,KAAK,OAAO,KAAK,KAAK,QAAQ;AAAA,EAChD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,UAAe;AACd,UAAM,SAAc,IAAI,MAAM,KAAK,KAAK;AACxC,aAAS,IAAI,GAAG,IAAI,KAAK,OAAO,KAAK;AACpC,aAAO,CAAC,IAAI,KAAK,KAAK,KAAK,OAAO,KAAK,KAAK,QAAQ;AAAA,IACrD;AACA,WAAO;AAAA,EACR;AAAA;AAAA,EAGA,QAAc;AACb,aAAS,IAAI,GAAG,IAAI,KAAK,OAAO,KAAK;AACpC,WAAK,KAAK,KAAK,OAAO,KAAK,KAAK,QAAQ,IAAI;AAAA,IAC7C;AACA,SAAK,OAAO;AACZ,SAAK,QAAQ;AAAA,EACd;AACD;","names":[]}