@graphrefly/graphrefly 0.21.0 → 0.23.0

package/README.md

@@ -200,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" }));
@@ -211,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-263BEJJO.js

@@ -0,0 +1,115 @@
+import {
+  resolveDescribeFields
+} from "./chunk-HVBX5KIW.js";
+import {
+  COMPLETE,
+  COMPLETE_MSG,
+  COMPLETE_ONLY_BATCH,
+  DATA,
+  DEFAULT_ACTOR,
+  DIRTY,
+  DIRTY_MSG,
+  DIRTY_ONLY_BATCH,
+  ERROR,
+  GraphReFlyConfig,
+  GuardDenied,
+  INVALIDATE,
+  INVALIDATE_MSG,
+  INVALIDATE_ONLY_BATCH,
+  NodeImpl,
+  PAUSE,
+  RESOLVED,
+  RESOLVED_MSG,
+  RESOLVED_ONLY_BATCH,
+  RESUME,
+  START,
+  START_MSG,
+  TEARDOWN,
+  TEARDOWN_MSG,
+  TEARDOWN_ONLY_BATCH,
+  __export,
+  accessHintForGuard,
+  advanceVersion,
+  autoTrackNode,
+  batch,
+  configure,
+  createVersioning,
+  defaultConfig,
+  defaultHash,
+  derived,
+  downWithBatch,
+  dynamicNode,
+  effect,
+  isBatching,
+  isV1,
+  monotonicNs,
+  node,
+  normalizeActor,
+  pipe,
+  policy,
+  policyFromRules,
+  producer,
+  registerBuiltins,
+  state,
+  wallClockNs
+} from "./chunk-NZMBRXQV.js";
+
+// src/core/index.ts
+var core_exports = {};
+__export(core_exports, {
+  COMPLETE: () => COMPLETE,
+  COMPLETE_MSG: () => COMPLETE_MSG,
+  COMPLETE_ONLY_BATCH: () => COMPLETE_ONLY_BATCH,
+  DATA: () => DATA,
+  DEFAULT_ACTOR: () => DEFAULT_ACTOR,
+  DIRTY: () => DIRTY,
+  DIRTY_MSG: () => DIRTY_MSG,
+  DIRTY_ONLY_BATCH: () => DIRTY_ONLY_BATCH,
+  ERROR: () => ERROR,
+  GraphReFlyConfig: () => GraphReFlyConfig,
+  GuardDenied: () => GuardDenied,
+  INVALIDATE: () => INVALIDATE,
+  INVALIDATE_MSG: () => INVALIDATE_MSG,
+  INVALIDATE_ONLY_BATCH: () => INVALIDATE_ONLY_BATCH,
+  NodeImpl: () => NodeImpl,
+  PAUSE: () => PAUSE,
+  RESOLVED: () => RESOLVED,
+  RESOLVED_MSG: () => RESOLVED_MSG,
+  RESOLVED_ONLY_BATCH: () => RESOLVED_ONLY_BATCH,
+  RESUME: () => RESUME,
+  START: () => START,
+  START_MSG: () => START_MSG,
+  TEARDOWN: () => TEARDOWN,
+  TEARDOWN_MSG: () => TEARDOWN_MSG,
+  TEARDOWN_ONLY_BATCH: () => TEARDOWN_ONLY_BATCH,
+  accessHintForGuard: () => accessHintForGuard,
+  advanceVersion: () => advanceVersion,
+  autoTrackNode: () => autoTrackNode,
+  batch: () => batch,
+  configure: () => configure,
+  createVersioning: () => createVersioning,
+  defaultConfig: () => defaultConfig,
+  defaultHash: () => defaultHash,
+  derived: () => derived,
+  downWithBatch: () => downWithBatch,
+  dynamicNode: () => dynamicNode,
+  effect: () => effect,
+  isBatching: () => isBatching,
+  isV1: () => isV1,
+  monotonicNs: () => monotonicNs,
+  node: () => node,
+  normalizeActor: () => normalizeActor,
+  pipe: () => pipe,
+  policy: () => policy,
+  policyFromRules: () => policyFromRules,
+  producer: () => producer,
+  registerBuiltins: () => registerBuiltins,
+  resolveDescribeFields: () => resolveDescribeFields,
+  state: () => state,
+  wallClockNs: () => wallClockNs
+});
+
+export {
+  core_exports
+};
+//# sourceMappingURL=chunk-263BEJJO.js.map

package/dist/chunk-263BEJJO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/index.ts"],"sourcesContent":["/**\n * Core layer: message protocol, node primitive, lifecycle (Phase 0).\n */\nexport * from \"./actor.js\";\nexport { batch, downWithBatch, isBatching } from \"./batch.js\";\nexport { monotonicNs, wallClockNs } from \"./clock.js\";\nexport {\n\ttype GlobalInspectorEvent,\n\ttype GlobalInspectorHook,\n\tGraphReFlyConfig,\n\ttype MessageContext,\n\ttype NodeActions,\n\ttype NodeCtx,\n\ttype OnMessageHandler,\n\ttype OnSubscribeHandler,\n\tregisterBuiltins,\n\ttype SubscribeContext,\n} from \"./config.js\";\nexport * from \"./guard.js\";\nexport {\n\tCOMPLETE,\n\tCOMPLETE_MSG,\n\tCOMPLETE_ONLY_BATCH,\n\tDATA,\n\tDIRTY,\n\tDIRTY_MSG,\n\tDIRTY_ONLY_BATCH,\n\tERROR,\n\tINVALIDATE,\n\tINVALIDATE_MSG,\n\tINVALIDATE_ONLY_BATCH,\n\ttype Message,\n\ttype Messages,\n\ttype MessageTypeRegistration,\n\ttype MessageTypeRegistrationInput,\n\tPAUSE,\n\tRESOLVED,\n\tRESOLVED_MSG,\n\tRESOLVED_ONLY_BATCH,\n\tRESUME,\n\tSTART,\n\tSTART_MSG,\n\tTEARDOWN,\n\tTEARDOWN_MSG,\n\tTEARDOWN_ONLY_BATCH,\n} from \"./messages.js\";\nexport {\n\ttype DescribeDetail,\n\ttype DescribeField,\n\ttype DescribeNodeOutput,\n\tresolveDescribeFields,\n} from \"./meta.js\";\nexport {\n\tconfigure,\n\ttype DepRecord,\n\tdefaultConfig,\n\ttype FnCtx,\n\ttype Node,\n\ttype NodeDescribeKind,\n\ttype NodeFn,\n\ttype NodeFnCleanup,\n\tNodeImpl,\n\ttype NodeInspectorHook,\n\ttype NodeInspectorHookEvent,\n\ttype NodeOptions,\n\ttype NodeSink,\n\ttype NodeStatus,\n\ttype NodeTransportOptions,\n\tnode,\n} from \"./node.js\";\nexport {\n\ttype AutoTrackOptions,\n\tautoTrackNode,\n\ttype DerivedFn,\n\ttype DynamicFn,\n\tderived,\n\tdynamicNode,\n\ttype EffectFn,\n\teffect,\n\ttype PipeOperator,\n\ttype ProducerFn,\n\tpipe,\n\tproducer,\n\tstate,\n\ttype TrackFn,\n} from \"./sugar.js\";\nexport {\n\tadvanceVersion,\n\tcreateVersioning,\n\tdefaultHash,\n\ttype HashFn,\n\tisV1,\n\ttype NodeVersionInfo,\n\ttype V0,\n\ttype V1,\n\ttype VersioningLevel,\n\ttype VersioningOptions,\n} from \"./versioning.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;","names":[]}

package/dist/chunk-2GQLMQVJ.js

@@ -0,0 +1,47 @@
+import {
+  GRAPH_META_SEGMENT,
+  Graph,
+  OVERHEAD,
+  SIZEOF_SYMBOL,
+  diffForWAL,
+  graphProfile,
+  reachable,
+  sizeof
+} from "./chunk-XRFJJ2IU.js";
+import {
+  ENVELOPE_VERSION,
+  JsonCodec,
+  __export,
+  createDagCborCodec,
+  createDagCborZstdCodec,
+  decodeEnvelope,
+  encodeEnvelope,
+  registerBuiltinCodecs,
+  replayWAL
+} from "./chunk-NZMBRXQV.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-2GQLMQVJ.js.map

package/dist/chunk-2GQLMQVJ.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-32N5A454.js

@@ -0,0 +1,36 @@
+import {
+  DATA,
+  DIRTY,
+  defaultConfig,
+  downWithBatch
+} from "./chunk-NZMBRXQV.js";
+
+// src/patterns/_internal.ts
+function emitToMeta(metaNode, value) {
+  if (metaNode == null) return;
+  downWithBatch((msgs) => metaNode.down(msgs), [[DATA, value]], defaultConfig.tierOf);
+}
+function tryIncrementBounded(counter, cap) {
+  const cur = counter.cache ?? 0;
+  if (cur >= cap) return false;
+  counter.down([[DIRTY], [DATA, cur + 1]]);
+  return true;
+}
+function domainMeta(domain, kind, extra) {
+  return {
+    [domain]: true,
+    [`${domain}_type`]: kind,
+    ...extra ?? {}
+  };
+}
+function trackingKey(item) {
+  return item.relatedTo?.[0] ?? item.summary;
+}
+
+export {
+  emitToMeta,
+  tryIncrementBounded,
+  domainMeta,
+  trackingKey
+};
+//# sourceMappingURL=chunk-32N5A454.js.map

package/dist/chunk-32N5A454.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/patterns/_internal.ts"],"sourcesContent":["/**\n * Shared internal utilities for the patterns layer.\n *\n * These are private helpers used across multiple pattern modules. They are NOT\n * part of the public API — import from `./patterns/index.js` for public exports.\n *\n * General-purpose reactive utilities (`keepalive`, `reactiveCounter`) live in\n * `extra/sources.ts` and are re-exported here for convenience.\n *\n * @internal\n * @module\n */\n\nimport { downWithBatch } from \"../core/batch.js\";\nimport { DATA, DIRTY } from \"../core/messages.js\";\nimport type { Node } from \"../core/node.js\";\nimport { defaultConfig } from \"../core/node.js\";\n\n// Re-export general-purpose utilities from extra (canonical home).\nexport { keepalive, reactiveCounter } from \"../extra/sources.js\";\n\n// ---------------------------------------------------------------------------\n// emitToMeta\n// ---------------------------------------------------------------------------\n\n/**\n * Forward a single `[DATA, value]` to a meta companion node via tier-3\n * deferral, tolerating absent companions. Used by patterns that publish\n * per-wave statistics alongside their main output (cache-hit-rate,\n * segment-count, layout-time-ns, etc.) — subscribers see the parent's\n * DATA first because phase-2 completes before phase-3 during drain.\n *\n * Equivalent to the expanded form:\n * ```ts\n * downWithBatch((msgs) => metaNode?.down(msgs), [[DATA, value]], tierOf);\n * ```\n * but captures the \"meta may not be mounted\" null guard and the\n * `defaultConfig.tierOf` boilerplate in one name.\n *\n * @internal\n */\nexport function emitToMeta<T>(metaNode: Node<T> | undefined, value: T): void {\n\tif (metaNode == null) return;\n\tdownWithBatch((msgs) => metaNode.down(msgs), [[DATA, value]], defaultConfig.tierOf);\n}\n\n// ---------------------------------------------------------------------------\n// tryIncrementBounded\n// ---------------------------------------------------------------------------\n\n/**\n * Bounded increment for a self-owned counter state node.\n *\n * Reads `counter.cache`, bumps by 1 if under `cap`, writes back. Returns\n * `false` when the cap is reached. Documented P3 exception: the counter is\n * not a declared dep of the caller — it's a private budget read+written from\n * a single call site. This helper keeps the `.cache` access in one named\n * place.\n *\n * **Safety today:**\n *   1. Single-threaded JS runner never invokes the caller concurrently.\n *   2. `counter.down` writes the cache synchronously before returning, so\n *      synchronous re-entry through a downstream publish reads the\n *      freshly-incremented value — no double-count.\n *\n * **Future risk:** under a free-threaded runner (PY no-GIL or hypothetical\n * concurrent TS runner), two concurrent firings could still race. Revisit\n * when that surfaces.\n *\n * @internal\n */\nexport function tryIncrementBounded(counter: Node<number>, cap: number): boolean {\n\tconst cur = (counter.cache as number | undefined) ?? 0;\n\tif (cur >= cap) return false;\n\tcounter.down([[DIRTY], [DATA, cur + 1]]);\n\treturn true;\n}\n\n// ---------------------------------------------------------------------------\n// domainMeta\n// ---------------------------------------------------------------------------\n\n/**\n * Build a domain metadata object for pattern-layer nodes.\n *\n * Each domain (orchestration, messaging, reduction, ai, cqrs, domain_template)\n * follows the same shape: `{ [domain]: true, [domain]_type: kind, ...extra }`.\n *\n * @param domain - The domain tag (e.g. `\"orchestration\"`, `\"ai\"`, `\"cqrs\"`).\n * @param kind - The specific type within the domain (e.g. `\"gate\"`, `\"prompt\"`).\n * @param extra - Additional metadata to merge.\n * @returns Metadata object.\n *\n * @internal\n */\nexport function domainMeta(\n\tdomain: string,\n\tkind: string,\n\textra?: Record<string, unknown>,\n): Record<string, unknown> {\n\treturn {\n\t\t[domain]: true,\n\t\t[`${domain}_type`]: kind,\n\t\t...(extra ?? {}),\n\t};\n}\n\n// ---------------------------------------------------------------------------\n// trackingKey\n// ---------------------------------------------------------------------------\n\n/**\n * Stable tracking key for an item with retry/reingestion decoration.\n *\n * Uses `relatedTo[0]` if present (carries the original key forward through\n * retries and reingestions). Falls back to `summary` for first-time items.\n *\n * This avoids deriving keys from mutated summary strings — retries decorate\n * the summary with `[RETRY N/M]` and failure context, so regex-stripping\n * would be fragile and any new decoration pattern would risk infinite loops\n * by generating novel keys.\n *\n * @internal\n */\nexport function trackingKey(item: { summary: string; relatedTo?: string[] }): string {\n\treturn item.relatedTo?.[0] ?? item.summary;\n}\n"],"mappings":";;;;;;;;AAyCO,SAAS,WAAc,UAA+B,OAAgB;AAC5E,MAAI,YAAY,KAAM;AACtB,gBAAc,CAAC,SAAS,SAAS,KAAK,IAAI,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,GAAG,cAAc,MAAM;AACnF;AA2BO,SAAS,oBAAoB,SAAuB,KAAsB;AAChF,QAAM,MAAO,QAAQ,SAAgC;AACrD,MAAI,OAAO,IAAK,QAAO;AACvB,UAAQ,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC,CAAC;AACvC,SAAO;AACR;AAmBO,SAAS,WACf,QACA,MACA,OAC0B;AAC1B,SAAO;AAAA,IACN,CAAC,MAAM,GAAG;AAAA,IACV,CAAC,GAAG,MAAM,OAAO,GAAG;AAAA,IACpB,GAAI,SAAS,CAAC;AAAA,EACf;AACD;AAmBO,SAAS,YAAY,MAAyD;AACpF,SAAO,KAAK,YAAY,CAAC,KAAK,KAAK;AACpC;","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":[]}