@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/chunk-OO5BM6CJ.js

@@ -0,0 +1,1153 @@
+import {
+  collection,
+  cosineSimilarity,
+  knowledgeGraph,
+  vectorIndex
+} from "./chunk-FR6RGA3B.js";
+import {
+  DEFAULT_DECAY_RATE,
+  decay
+} from "./chunk-QMBYUVRL.js";
+import {
+  domainMeta
+} from "./chunk-FMPF42Q4.js";
+import {
+  distill
+} from "./chunk-A7KV5UK4.js";
+import {
+  nodeSignal
+} from "./chunk-O3MT7DYI.js";
+import {
+  retry
+} from "./chunk-Z4YXAUDN.js";
+
+// src/utils/ai/agents/chat-stream.ts
+import { node as node2, RESOLVED } from "@graphrefly/pure-ts/core";
+import { keepalive, reactiveLog } from "@graphrefly/pure-ts/extra";
+import { Graph } from "@graphrefly/pure-ts/graph";
+
+// src/utils/ai/_internal.ts
+import {
+  COMPLETE,
+  DATA,
+  ERROR,
+  node,
+  ResettableTimer
+} from "@graphrefly/pure-ts/core";
+import { fromAny } from "@graphrefly/pure-ts/extra";
+function aiMeta(kind, extra) {
+  return domainMeta("ai", kind, extra);
+}
+function isPromiseLike(x) {
+  return x != null && typeof x.then === "function";
+}
+function isNodeLike(x) {
+  return typeof x === "object" && x !== null && "subscribe" in x && typeof x.subscribe === "function" && "cache" in x;
+}
+function isAsyncIterableLike(x) {
+  return x != null && typeof x === "object" && Symbol.asyncIterator in x && typeof x[Symbol.asyncIterator] === "function";
+}
+var DEFAULT_TIMEOUT_MS = 3e4;
+function firstDataFromNode(resolved, opts) {
+  if (resolved.status === "settled") {
+    const immediate = resolved.cache;
+    if (immediate !== void 0) {
+      return Promise.resolve(immediate);
+    }
+  }
+  const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  return new Promise((resolve, reject) => {
+    const timer = new ResettableTimer();
+    const unsub = resolved.subscribe((messages) => {
+      for (const msg of messages) {
+        if (msg[0] === DATA) {
+          timer.cancel();
+          unsub();
+          resolve(msg[1]);
+          return;
+        }
+        if (msg[0] === ERROR) {
+          timer.cancel();
+          unsub();
+          reject(msg[1]);
+          return;
+        }
+        if (msg[0] === COMPLETE) {
+          timer.cancel();
+          unsub();
+          reject(new Error("firstDataFromNode: completed without producing a value"));
+          return;
+        }
+      }
+    });
+    timer.start(timeoutMs, () => {
+      unsub();
+      reject(new Error(`firstDataFromNode: timed out after ${timeoutMs}ms`));
+    });
+  });
+}
+async function resolveToolHandlerResult(value) {
+  if (isPromiseLike(value)) {
+    return resolveToolHandlerResult(await value);
+  }
+  if (isNodeLike(value)) {
+    return firstDataFromNode(value);
+  }
+  if (isAsyncIterableLike(value)) {
+    return firstDataFromNode(fromAny(value));
+  }
+  return value;
+}
+function stripFences(text) {
+  const match = text.match(/^```(?:json)?\s*([\s\S]*?)\s*```[\s\S]*$/);
+  return match ? match[1] : text;
+}
+function _oneShotLlmCall(adapter, messages, config) {
+  return node(
+    (_data, actions) => {
+      const ac = new AbortController();
+      const parentSignal = config.parentSignal;
+      let unlinkParent = () => void 0;
+      if (parentSignal) {
+        if (parentSignal.aborted) {
+          ac.abort();
+        } else {
+          const onParentAbort = () => ac.abort();
+          parentSignal.addEventListener("abort", onParentAbort, { once: true });
+          unlinkParent = () => parentSignal.removeEventListener("abort", onParentAbort);
+        }
+      }
+      let captured = false;
+      let unsub = null;
+      const emitOnce = (value) => {
+        if (captured) return;
+        captured = true;
+        actions.down([[DATA, value], [COMPLETE]]);
+        unsub?.();
+        unsub = null;
+      };
+      let invokeResult;
+      try {
+        invokeResult = adapter.invoke(messages, { ...config.invokeOpts, signal: ac.signal });
+      } catch (err) {
+        emitOnce(config.onFailure("throw", err));
+        return () => {
+          unlinkParent();
+          ac.abort();
+        };
+      }
+      const callNode = fromAny(invokeResult, { signal: ac.signal });
+      unsub = callNode.subscribe((batch2) => {
+        for (const m of batch2) {
+          if (captured) return;
+          if (m[0] === DATA) {
+            try {
+              emitOnce(config.onSuccess(m[1]));
+            } catch (err) {
+              emitOnce(config.onFailure("onSuccess-threw", err));
+            }
+            return;
+          }
+          if (m[0] === ERROR) {
+            emitOnce(config.onFailure("error", m[1]));
+            return;
+          }
+          if (m[0] === COMPLETE) {
+            emitOnce(config.onFailure("complete", void 0));
+            return;
+          }
+        }
+      });
+      if (captured && unsub) {
+        unsub();
+        unsub = null;
+      }
+      return () => {
+        unlinkParent();
+        ac.abort();
+        unsub?.();
+        unsub = null;
+      };
+    },
+    { describeKind: "producer" }
+  );
+}
+
+// src/utils/ai/agents/chat-stream.ts
+var ChatStreamGraph = class extends Graph {
+  _log;
+  messages;
+  /**
+   * Most recently appended message. Stays in the protocol SENTINEL state
+   * (`cache === undefined`, no DATA emitted) until the first append, then
+   * tracks the latest entry. Per COMPOSITION-GUIDE §1a, the SENTINEL is
+   * the canonical "no value yet" signal — consumers detect empty via
+   * `data[i] === undefined` inside reactive fns or `latest.cache === undefined`
+   * outside. No `T | null` placeholder, no `hasLatest` companion.
+   */
+  latest;
+  messageCount;
+  constructor(name, opts = {}) {
+    super(name, opts.graph);
+    this._log = reactiveLog([], {
+      name: "messages",
+      maxSize: opts.maxMessages
+    });
+    this.messages = this._log.entries;
+    this.add(this.messages, { name: "messages" });
+    this.latest = node2(
+      [this.messages],
+      (batchData, actions, ctx) => {
+        const data = batchData.map(
+          (batch2, i) => batch2 != null && batch2.length > 0 ? batch2.at(-1) : ctx.prevData[i]
+        );
+        const entries = data[0];
+        if (entries.length === 0) {
+          actions.down([[RESOLVED]]);
+          return;
+        }
+        actions.emit(entries[entries.length - 1]);
+      },
+      {
+        name: "latest",
+        describeKind: "derived",
+        meta: aiMeta("chat_latest")
+      }
+    );
+    this.add(this.latest, { name: "latest" });
+    this.addDisposer(keepalive(this.latest));
+    this.messageCount = node2(
+      [this.messages],
+      (batchData, actions, ctx) => {
+        const data = batchData.map(
+          (batch2, i) => batch2 != null && batch2.length > 0 ? batch2.at(-1) : ctx.prevData[i]
+        );
+        actions.emit(data[0].length);
+      },
+      {
+        name: "messageCount",
+        describeKind: "derived",
+        meta: aiMeta("chat_message_count"),
+        initial: 0
+      }
+    );
+    this.add(this.messageCount, { name: "messageCount" });
+    this.addDisposer(keepalive(this.messageCount));
+  }
+  append(role, content, extra) {
+    this._log.append({ role, content, ...extra });
+  }
+  appendToolResult(callId, content) {
+    this._log.append({ role: "tool", content, toolCallId: callId });
+  }
+  clear() {
+    this._log.clear();
+  }
+  allMessages() {
+    return this.messages.cache;
+  }
+};
+function chatStream(name, opts) {
+  return new ChatStreamGraph(name, opts);
+}
+
+// src/utils/ai/agents/tool-execution.ts
+import { node as node3 } from "@graphrefly/pure-ts/core";
+import { rescue, switchMap } from "@graphrefly/pure-ts/extra";
+function toolExecution(opts) {
+  const { toolCalls, tools } = opts;
+  const retryCount = opts.retryCount ?? 1;
+  const onError = opts.onError ?? "rescue";
+  const batchEquals = (a, b) => {
+    if (a === b) return true;
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      const ai = a[i];
+      const bi = b[i];
+      if (ai?.id !== bi?.id) return false;
+      if (ai?.content !== bi?.content) return false;
+    }
+    return true;
+  };
+  return switchMap(toolCalls, (calls) => {
+    if (calls == null || calls.length === 0) {
+      throw new Error(
+        "toolExecution: received an empty tool-call batch as DATA \u2014 callers must upstream-filter empty batches (emit RESOLVED) so switchMap is only dispatched for non-empty batches."
+      );
+    }
+    const perCall = calls.map((call) => executeOne(call, tools, retryCount, onError));
+    return node3(
+      perCall,
+      (batchData, actions, ctx) => {
+        const data = batchData.map(
+          (batch2, i) => batch2 != null && batch2.length > 0 ? batch2.at(-1) : ctx.prevData[i]
+        );
+        actions.emit(data);
+      },
+      { describeKind: "derived", name: "toolExecution::batch", equals: batchEquals }
+    );
+  });
+}
+function executeOne(call, tools, retryCount, onError) {
+  const attempted = retry(() => tools.executeReactive(call.name, call.arguments), {
+    count: retryCount
+  }).node;
+  const onSuccess = node3(
+    [attempted],
+    (batchData, actions, ctx) => {
+      const data = batchData.map(
+        (batch2, i) => batch2 != null && batch2.length > 0 ? batch2.at(-1) : ctx.prevData[i]
+      );
+      const val = data[0];
+      actions.emit({
+        id: call.id,
+        content: typeof val === "string" ? val : JSON.stringify(val)
+      });
+    },
+    { describeKind: "derived" }
+  );
+  if (onError === "propagate") return onSuccess;
+  return rescue(onSuccess, (err) => ({
+    id: call.id,
+    content: JSON.stringify({ error: String(err) })
+  }));
+}
+
+// src/utils/ai/agents/tool-registry.ts
+import { ERROR as ERROR2, node as node4 } from "@graphrefly/pure-ts/core";
+import { fromAsyncIter, fromPromise, keepalive as keepalive2, reactiveMap } from "@graphrefly/pure-ts/extra";
+import { Graph as Graph2 } from "@graphrefly/pure-ts/graph";
+var ToolRegistryGraph = class extends Graph2 {
+  definitions;
+  schemas;
+  _bundle;
+  constructor(name, opts = {}) {
+    super(name, opts.graph);
+    this._bundle = reactiveMap({
+      name: "definitions"
+    });
+    this.definitions = this._bundle.entries;
+    this.add(this.definitions, { name: "definitions" });
+    this.schemas = node4(
+      [this.definitions],
+      (batchData, actions, ctx) => {
+        const data = batchData.map(
+          (batch2, i) => batch2 != null && batch2.length > 0 ? batch2.at(-1) : ctx.prevData[i]
+        );
+        const defs = data[0];
+        actions.emit([...(defs ?? /* @__PURE__ */ new Map()).values()]);
+      },
+      {
+        name: "schemas",
+        describeKind: "derived",
+        meta: aiMeta("tool_schemas"),
+        initial: []
+      }
+    );
+    this.add(this.schemas, { name: "schemas" });
+    this.addDisposer(keepalive2(this.schemas));
+  }
+  register(tool) {
+    this._bundle.set(tool.name, tool);
+  }
+  unregister(name) {
+    this._bundle.delete(name);
+  }
+  /**
+   * Reactive execution — returns a `Node<unknown>` that emits the handler
+   * result. The returned node is a `producer` that:
+   *
+   * 1. Mints a per-call `AbortController` whose `signal` is threaded into
+   *    the handler call AND into `fromAny` (so a `fromPromise` /
+   *    `fromAsyncIter` inner abandons cleanly when the consumer
+   *    unsubscribes).
+   * 2. Runs `tool.handler(args, {signal})` inside a try/catch — a
+   *    synchronous throw surfaces as `[[ERROR, err]]` downstream instead
+   *    of escaping the producer.
+   * 3. Forwards every message from the inner `fromAny` chain to the
+   *    producer's outputs.
+   * 4. On teardown (subscriber count drops to zero, e.g. `switchMap`
+   *    supersede) calls `ac.abort()` and unsubscribes the inner.
+   *    Signal-aware handlers (e.g. `fetch(url, {signal})`) actually stop.
+   *
+   * Each call mints a fresh node tied to a fresh `handler(args, ...)`
+   * invocation — call `executeReactive` again for repeated invocations.
+   *
+   * @throws `Error` synchronously when `name` is not registered (no node is
+   *   constructed — the caller gets a pre-wiring failure rather than a
+   *   silent ERROR wave on an empty graph).
+   */
+  executeReactive(name, args) {
+    const tool = this._bundle.get(name);
+    if (!tool) throw new Error(`toolRegistry: unknown tool "${name}"`);
+    return node4(
+      [],
+      (_data, actions) => {
+        const ac = new AbortController();
+        let inner;
+        try {
+          const raw = tool.handler(args, { signal: ac.signal });
+          inner = handlerResultToNode(raw, ac.signal);
+        } catch (err) {
+          actions.down([[ERROR2, err]]);
+          return () => {
+            ac.abort();
+          };
+        }
+        const unsub = inner.subscribe((batch2) => {
+          actions.down(batch2);
+        });
+        return () => {
+          ac.abort();
+          unsub();
+        };
+      },
+      {
+        name: `executeReactive::${name}`,
+        describeKind: "producer",
+        meta: aiMeta("tool_execute_reactive")
+      }
+    );
+  }
+  getDefinition(name) {
+    return this._bundle.entries.cache?.get(name);
+  }
+};
+function toolRegistry(name, opts) {
+  return new ToolRegistryGraph(name, opts);
+}
+function handlerResultToNode(raw, signal) {
+  if (isNodeLike(raw)) {
+    return raw;
+  }
+  if (raw != null && typeof raw.then === "function") {
+    return fromPromise(raw, { signal });
+  }
+  if (raw != null && typeof raw === "object" && Symbol.asyncIterator in raw) {
+    return fromAsyncIter(raw, { signal });
+  }
+  return fromPromise(Promise.resolve(raw), { signal });
+}
+
+// src/utils/ai/memory/memory-composers.ts
+import { batch, DATA as DATA2, monotonicNs, node as node5 } from "@graphrefly/pure-ts/core";
+import {
+  fromAny as fromAny2,
+  keepalive as keepalive3,
+  reactiveMap as reactiveMap2
+} from "@graphrefly/pure-ts/extra";
+import { Graph as Graph3 } from "@graphrefly/pure-ts/graph";
+var MemoryWithVectorsGraph = class extends Graph3 {
+  vectors;
+  constructor(opts) {
+    super(opts.name ?? "memory-vectors", opts.graph);
+    this.vectors = vectorIndex({ dimension: opts.dimension });
+    this.mount("vectorIndex", this.vectors);
+    const embedFn = opts.embedFn;
+    const vectorsRef = this.vectors;
+    const indexer = node5(
+      [opts.store.store.entries],
+      (batchData, _actions, ctx) => {
+        const data = batchData.map(
+          (b, i) => b != null && b.length > 0 ? b.at(-1) : ctx.prevData[i]
+        );
+        const storeMap = data[0] ?? /* @__PURE__ */ new Map();
+        for (const [key, mem] of storeMap) {
+          const vec = embedFn(mem);
+          if (vec) vectorsRef.upsert(key, vec, mem);
+        }
+      },
+      { name: "indexer", describeKind: "effect" }
+    );
+    this.add(indexer, { name: "indexer" });
+    this.addDisposer(keepalive3(indexer));
+  }
+};
+function memoryWithVectors(opts) {
+  return new MemoryWithVectorsGraph(opts);
+}
+var MemoryWithKGGraph = class extends Graph3 {
+  kg;
+  constructor(opts) {
+    const name = opts.name ?? "memory-kg";
+    super(name, opts.graph);
+    const kgName = opts.kgName ?? `${name}-kg`;
+    const mountPath = opts.mountPath ?? "knowledge-kg";
+    this.kg = knowledgeGraph(kgName);
+    this.mount(mountPath, this.kg);
+    if (!opts.entityFn) return;
+    const entityFn = opts.entityFn;
+    const kgRef = this.kg;
+    const indexer = node5(
+      [opts.store.store.entries],
+      (batchData, _actions, ctx) => {
+        const data = batchData.map(
+          (b, i) => b != null && b.length > 0 ? b.at(-1) : ctx.prevData[i]
+        );
+        const storeMap = data[0] ?? /* @__PURE__ */ new Map();
+        for (const [key, mem] of storeMap) {
+          const extracted = entityFn(key, mem);
+          if (!extracted) continue;
+          for (const ent of extracted.entities ?? []) {
+            kgRef.upsertEntity(ent.id, ent.value);
+          }
+          for (const rel of extracted.relations ?? []) {
+            kgRef.link(rel.from, rel.to, rel.relation, rel.weight);
+          }
+        }
+      },
+      { name: "indexer", describeKind: "effect" }
+    );
+    this.add(indexer, { name: "indexer" });
+    this.addDisposer(keepalive3(indexer));
+  }
+};
+function memoryWithKG(opts) {
+  return new MemoryWithKGGraph(opts);
+}
+var MemoryWithTiersGraph = class extends Graph3 {
+  store;
+  tiers;
+  compact;
+  size;
+  permanent;
+  permanentKeys;
+  entryCreatedAtNs;
+  constructor(opts) {
+    super(opts.name ?? "memory-tiers", opts.graph);
+    const decayRate = opts.decayRate ?? DEFAULT_DECAY_RATE;
+    const maxActive = opts.maxActive ?? 1e3;
+    const archiveThreshold = opts.archiveThreshold ?? 0.1;
+    const permanentFilter = opts.permanentFilter ?? (() => false);
+    this.permanent = collection("permanent", { ranked: false });
+    this.mount("permanent", this.permanent);
+    this.permanentKeys = reactiveMap2({ name: "permanentKeys" });
+    this.add(this.permanentKeys.entries, { name: "permanentKeys" });
+    this.entryCreatedAtNs = reactiveMap2({ name: "entryCreatedAtNs" });
+    this.add(this.entryCreatedAtNs.entries, { name: "entryCreatedAtNs" });
+    let contextNode;
+    if (opts.context) {
+      contextNode = fromAny2(opts.context);
+    } else {
+      contextNode = node5([], { initial: null });
+      this.add(contextNode, { name: "context" });
+    }
+    let latestCtx = contextNode.cache;
+    const ctxUnsub = contextNode.subscribe((msgs) => {
+      for (const m of msgs) if (m[0] === DATA2) latestCtx = m[1];
+    });
+    this.addDisposer(ctxUnsub);
+    const permanentKeysRef = this.permanentKeys;
+    const entryCreatedAtNsRef = this.entryCreatedAtNs;
+    const score = opts.score;
+    const retention = {
+      score: (key, value) => {
+        if (permanentFilter(key, value)) return Number.POSITIVE_INFINITY;
+        if (permanentKeysRef.has(key)) return Number.POSITIVE_INFINITY;
+        const nowNs = monotonicNs();
+        const createdNs = entryCreatedAtNsRef.get(key) ?? nowNs;
+        const ageSeconds = Number(nowNs - createdNs) / 1e9;
+        return decay(score(value, latestCtx), ageSeconds, decayRate);
+      },
+      archiveThreshold,
+      maxSize: maxActive
+    };
+    this.store = distill(opts.source, opts.extractFn, {
+      score: opts.score,
+      cost: opts.cost,
+      ...opts.budget !== void 0 ? { budget: opts.budget } : {},
+      ...opts.evict !== void 0 ? { evict: opts.evict } : {},
+      ...opts.consolidate !== void 0 ? { consolidate: opts.consolidate } : {},
+      ...opts.consolidateTrigger !== void 0 ? { consolidateTrigger: opts.consolidateTrigger } : {},
+      ...opts.context !== void 0 ? { context: opts.context } : {},
+      mapOptions: { retention }
+    });
+    this.add(this.store.store.entries, { name: "store" });
+    this.compact = this.store.compact;
+    this.add(this.compact, { name: "compact" });
+    this.size = this.store.size;
+    this.add(this.size, { name: "size" });
+    const storeRef = this.store;
+    const tierOf = (key) => {
+      if (permanentKeysRef.has(key)) return "permanent";
+      const m = storeRef.store.entries.cache ?? /* @__PURE__ */ new Map();
+      if (m.has(key)) return "active";
+      return "archived";
+    };
+    const permanentRef = this.permanent;
+    const markPermanent = (key, value) => {
+      permanentKeysRef.set(key, true);
+      permanentRef.upsert(key, value);
+    };
+    const syncCreatedAt = node5(
+      [this.store.store.entries],
+      (batchData, _actions, ctx) => {
+        const data = batchData.map(
+          (b, i) => b != null && b.length > 0 ? b.at(-1) : ctx.prevData[i]
+        );
+        const map = data[0] ?? /* @__PURE__ */ new Map();
+        const nowNs = monotonicNs();
+        const toAdd = [];
+        for (const key of map.keys()) {
+          if (!entryCreatedAtNsRef.has(key)) toAdd.push(key);
+        }
+        if (toAdd.length > 0) {
+          batch(() => {
+            for (const key of toAdd) entryCreatedAtNsRef.set(key, nowNs);
+          });
+        }
+      },
+      { name: "entryCreatedAtNs/sync", describeKind: "effect" }
+    );
+    this.add(syncCreatedAt, { name: "entryCreatedAtNs/sync" });
+    this.addDisposer(keepalive3(syncCreatedAt));
+    const entriesUnsub = this.store.store.entries.subscribe((msgs) => {
+      for (const m of msgs) {
+        if (m[0] !== DATA2) continue;
+        const map = m[1];
+        const created = entryCreatedAtNsRef.entries.cache;
+        if (created == null) continue;
+        const toDelete = [];
+        for (const key of created.keys()) {
+          if (!map.has(key)) toDelete.push(key);
+        }
+        if (toDelete.length > 0) {
+          batch(() => {
+            for (const key of toDelete) entryCreatedAtNsRef.delete(key);
+          });
+        }
+      }
+    });
+    this.addDisposer(entriesUnsub);
+    const promoter = node5(
+      [this.store.store.entries],
+      (batchData, _actions, ctx) => {
+        const data = batchData.map(
+          (b, i) => b != null && b.length > 0 ? b.at(-1) : ctx.prevData[i]
+        );
+        const map = data[0] ?? /* @__PURE__ */ new Map();
+        for (const [key, mem] of map) {
+          if (permanentKeysRef.has(key)) continue;
+          if (permanentFilter(key, mem)) {
+            batch(() => {
+              markPermanent(key, mem);
+            });
+          }
+        }
+      },
+      { name: "promoter", describeKind: "effect" }
+    );
+    this.add(promoter, { name: "promoter" });
+    this.addDisposer(keepalive3(promoter));
+    let archiveHandle = null;
+    if (opts.archiveTier) {
+      archiveHandle = this.attachSnapshotStorage(
+        [{ snapshot: opts.archiveTier }],
+        opts.archiveStorageOptions ?? {}
+      );
+      this.addDisposer(() => archiveHandle?.dispose());
+    }
+    this.tiers = {
+      permanent: this.permanent,
+      activeEntries: this.store.store.entries,
+      archiveHandle,
+      tierOf,
+      markPermanent
+    };
+  }
+};
+function memoryWithTiers(opts) {
+  return new MemoryWithTiersGraph(opts);
+}
+function sharedPrefixDepth(q, e) {
+  if (!q || !e) return 0;
+  const n = Math.min(q.length, e.length);
+  let i = 0;
+  while (i < n && q[i] === e[i]) i++;
+  return i;
+}
+var packedEquals = (a, b) => {
+  if (a === b) return true;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+};
+var MemoryRetrievalGraph = class extends Graph3 {
+  _store;
+  _vectors;
+  _kg;
+  _opts;
+  _contextNode;
+  _topK;
+  _graphDepth;
+  _budget;
+  _contextWeight;
+  _retrieveSeq = 0;
+  constructor(opts) {
+    super(opts.name ?? "memory-retrieval", opts.graph);
+    this._store = opts.store;
+    this._vectors = opts.vectors ?? null;
+    this._kg = opts.kg ?? null;
+    this._opts = opts;
+    this._topK = opts.topK ?? 20;
+    this._graphDepth = opts.graphDepth ?? 1;
+    this._budget = opts.budget ?? 2e3;
+    this._contextWeight = opts.contextWeight ?? 0;
+    if (opts.context) {
+      this._contextNode = fromAny2(opts.context);
+    } else {
+      this._contextNode = this.state("_context", null);
+    }
+  }
+  _runRetrieval(storeMap, ctx, query) {
+    const opts = this._opts;
+    const candidateMap = /* @__PURE__ */ new Map();
+    let vectorCandidates = [];
+    if (this._vectors && query.vector) {
+      const q = query.vector;
+      const snapshot = this._vectors.entries.cache;
+      if (snapshot && snapshot.size > 0 && this._topK > 0) {
+        const scored = [...snapshot.values()].map(
+          (row) => ({
+            id: row.id,
+            score: cosineSimilarity(q, row.vector),
+            ...row.meta !== void 0 ? { meta: row.meta } : {}
+          })
+        ).sort((a, b) => b.score - a.score).slice(0, this._topK);
+        vectorCandidates = scored;
+        for (const vc of vectorCandidates) {
+          const mem = storeMap.get(vc.id);
+          if (mem) candidateMap.set(vc.id, { value: mem, sources: /* @__PURE__ */ new Set(["vector"]) });
+        }
+      }
+    }
+    const graphExpanded = [];
+    if (this._kg) {
+      const adjOut = this._kg.adjacencyOut.cache;
+      const adjIn = this._kg.adjacencyIn.cache;
+      const seedIds = [...query.entityIds ?? [], ...[...candidateMap.keys()]];
+      const visited = /* @__PURE__ */ new Set();
+      let frontier = seedIds;
+      for (let depth = 0; depth < this._graphDepth; depth++) {
+        const nextFrontier = [];
+        for (const id of frontier) {
+          if (visited.has(id)) continue;
+          visited.add(id);
+          const outEdges = adjOut?.get(id) ?? [];
+          const inEdges = adjIn?.get(id) ?? [];
+          for (const edge of outEdges) {
+            const targetId = edge.to;
+            if (!visited.has(targetId)) {
+              nextFrontier.push(targetId);
+              const mem = storeMap.get(targetId);
+              if (mem) {
+                const existing = candidateMap.get(targetId);
+                if (existing) existing.sources.add("graph");
+                else candidateMap.set(targetId, { value: mem, sources: /* @__PURE__ */ new Set(["graph"]) });
+                graphExpanded.push(targetId);
+              }
+            }
+          }
+          for (const edge of inEdges) {
+            const targetId = edge.from;
+            if (!visited.has(targetId)) {
+              nextFrontier.push(targetId);
+              const mem = storeMap.get(targetId);
+              if (mem) {
+                const existing = candidateMap.get(targetId);
+                if (existing) existing.sources.add("graph");
+                else candidateMap.set(targetId, { value: mem, sources: /* @__PURE__ */ new Set(["graph"]) });
+                graphExpanded.push(targetId);
+              }
+            }
+          }
+        }
+        frontier = nextFrontier;
+      }
+    }
+    for (const [key, mem] of storeMap) {
+      if (!candidateMap.has(key)) {
+        candidateMap.set(key, { value: mem, sources: /* @__PURE__ */ new Set(["store"]) });
+      }
+    }
+    const qDepth = query.context?.length ?? 0;
+    const ranked = [];
+    for (const [key, { value, sources }] of candidateMap) {
+      const entryContext = opts.contextOf ? opts.contextOf(value) : void 0;
+      let score = opts.score(value, ctx);
+      if (this._contextWeight > 0 && qDepth > 0) {
+        const shared = sharedPrefixDepth(query.context, entryContext);
+        if (shared > 0) score = score * (1 + this._contextWeight * shared / qDepth);
+      }
+      const entry = entryContext ? { key, value, score, sources: [...sources], context: entryContext } : { key, value, score, sources: [...sources] };
+      ranked.push(entry);
+    }
+    ranked.sort((a, b) => b.score - a.score);
+    const packed = [];
+    let usedBudget = 0;
+    for (const entry of ranked) {
+      const c = opts.cost(entry.value);
+      if (usedBudget + c > this._budget && packed.length > 0) break;
+      packed.push(entry);
+      usedBudget += c;
+    }
+    return { packed, trace: { vectorCandidates, graphExpanded, ranked, packed } };
+  }
+  /**
+   * Reactive consumer API — chain into the graph.
+   *
+   * Each call constructs its own per-input subgraph mounted at
+   * `retrieve_${id}` (auto-incrementing within this MemoryRetrievalGraph
+   * instance) with named nodes:
+   *
+   * - `context` — `fromAny(queryInput)` projection (so the input node is
+   *   visible to `describe()` even when callers pass a raw value).
+   * - `result` — pure derived `{ packed, trace }`.
+   * - `projection` — the packed-array node returned to the caller.
+   *
+   * `result` declares the substrate's `store.entries`, the optional
+   * `context` Node, the local `context` projection, and (when configured)
+   * `vectors.entries` / `kg.adjacencyOut` / `kg.adjacencyIn` as deps —
+   * so vector upserts and KG mutations re-trigger retrieval even when
+   * the input is unchanged.
+   *
+   * **Lifecycle contract (DS-13.5.C, 2026-05-01).** The per-call subgraph
+   * stays mounted while the returned `projection` has at least one
+   * subscriber. When the last subscriber unsubscribes, projection's
+   * `deactivate` cleanup hook fires (canonical "last unsubscribe" signal
+   * via the existing `NodeFnCleanup.onDeactivation` protocol), which calls
+   * `parent.remove(retrieve_${id})` and tears the per-call topology
+   * down via TEARDOWN cascade (post-DS-13.5.A Q16, COMPLETE auto-precedes).
+   *
+   * **Single-shot lifecycle.** This auto-unmount is keyed to the FIRST
+   * last-unsubscribe event — projection is non-resubscribable from the
+   * caller's perspective. Callers who need to subscribe / unsubscribe /
+   * re-subscribe should hold a long-lived subscription externally (e.g.
+   * `keepalive(projection)`) or call `retrieveReactive(...)` again to
+   * mount a fresh per-call subgraph.
+   *
+   * **Caller obligation.** Either subscribe to `projection` (and
+   * eventually unsubscribe to trigger cleanup) OR drop the returned
+   * reference without subscribing — in the no-subscribe case the
+   * subgraph is dormant (no compute fires) and a parent `destroy()`
+   * cascade reclaims it. Holding `projection` without subscribing AND
+   * without ever destroying the parent is the leak case the JSDoc above
+   * the C1 rework covers.
+   *
+   * One-shot callers use `awaitSettled(retrieveReactive(input))`.
+   */
+  retrieveReactive(queryInput) {
+    const id = ++this._retrieveSeq;
+    const segment = `retrieve_${id}`;
+    const sub = new Graph3(segment);
+    const inputNode = fromAny2(queryInput);
+    const localContext = sub.derived(
+      "context",
+      [inputNode],
+      (batchData, ctx) => {
+        const data = batchData.map(
+          (b, i) => b != null && b.length > 0 ? b.at(-1) : ctx.prevData[i]
+        );
+        return [data[0] ?? null];
+      },
+      {
+        meta: aiMeta("retrieval_query_input"),
+        initial: null
+      }
+    );
+    const resultDeps = [
+      this._store.store.entries,
+      this._contextNode,
+      localContext
+    ];
+    if (this._vectors) resultDeps.push(this._vectors.entries);
+    if (this._kg) {
+      resultDeps.push(this._kg.adjacencyOut);
+      resultDeps.push(this._kg.adjacencyIn);
+    }
+    const result = sub.derived(
+      "result",
+      resultDeps,
+      (batchData, ctx) => {
+        const data = batchData.map(
+          (b, i) => b != null && b.length > 0 ? b.at(-1) : ctx.prevData[i]
+        );
+        const query = data[2];
+        if (query == null) {
+          return [{ packed: [], trace: null }];
+        }
+        const storeMap = data[0] ?? /* @__PURE__ */ new Map();
+        const { packed, trace } = this._runRetrieval(storeMap, data[1], query);
+        return [{ packed, trace }];
+      },
+      {
+        meta: aiMeta("retrieval_reactive_result"),
+        initial: { packed: [], trace: null }
+      }
+    );
+    const projection = node5(
+      [result],
+      (batchData, actions, ctx) => {
+        const data = batchData.map(
+          (b, i) => b != null && b.length > 0 ? b.at(-1) : ctx.prevData[i]
+        );
+        actions.emit(data[0].packed);
+        return {
+          onDeactivation: () => {
+            try {
+              this.remove(segment);
+            } catch {
+            }
+          }
+        };
+      },
+      {
+        name: "projection",
+        describeKind: "derived",
+        meta: aiMeta("retrieval_reactive"),
+        initial: [],
+        equals: packedEquals
+      }
+    );
+    sub.add(projection, { name: "projection" });
+    this.mount(segment, sub);
+    return projection;
+  }
+};
+function memoryRetrieval(opts) {
+  return new MemoryRetrievalGraph(opts);
+}
+
+// src/utils/ai/prompts/prompt-node.ts
+import { COMPLETE as COMPLETE2, DATA as DATA3, ERROR as ERROR3, node as node6 } from "@graphrefly/pure-ts/core";
+import { fromAny as fromAny3, switchMap as switchMap2 } from "@graphrefly/pure-ts/extra";
+function extractContent(resp) {
+  if (resp != null && typeof resp === "object" && "content" in resp) {
+    return String(resp.content);
+  }
+  if (typeof resp === "string") return resp;
+  return String(resp);
+}
+function previewContent(text, max = 200) {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}\u2026`;
+}
+function promptNode(adapter, deps, prompt, opts) {
+  const format = opts?.format ?? "text";
+  const baseName = opts?.name ?? "prompt_node";
+  if (opts?.tools !== void 0 && format !== "raw") {
+    console.warn(
+      "promptNode: `tools` is set but `format !== 'raw'`. Tool calls in the response will be silently dropped \u2014 set `format: 'raw'` to receive the full LLMResponse with `toolCalls`."
+    );
+  }
+  const userDepsLength = deps.length;
+  const allDeps = opts?.tools !== void 0 ? [...deps, opts.tools] : deps;
+  const messagesNode = node6(
+    allDeps,
+    (batchData, actions, ctx) => {
+      const data = batchData.map(
+        (batch2, i) => batch2 != null && batch2.length > 0 ? batch2.at(-1) : ctx.prevData[i]
+      );
+      const userValues = data.slice(0, userDepsLength);
+      const toolsValue = opts?.tools !== void 0 ? data[userDepsLength] : void 0;
+      if (userValues.some((v) => v == null)) {
+        actions.emit({ messages: [], tools: toolsValue });
+        return;
+      }
+      const text = typeof prompt === "string" ? prompt : prompt(...userValues);
+      if (!text) {
+        actions.emit({ messages: [], tools: toolsValue });
+        return;
+      }
+      actions.emit({
+        messages: [{ role: "user", content: text }],
+        tools: toolsValue
+      });
+    },
+    {
+      name: `${baseName}::messages`,
+      meta: aiMeta("prompt_node::messages")
+    }
+  );
+  const result = switchMap2(
+    messagesNode,
+    (envelope) => {
+      const { messages: msgs, tools } = envelope;
+      if (!msgs || msgs.length === 0) {
+        return node6([], { initial: null });
+      }
+      return node6(
+        (_data, actions) => {
+          let done = false;
+          let cancelled = false;
+          let abortDispose;
+          const invokeOpts = {
+            model: opts?.model,
+            temperature: opts?.temperature,
+            maxTokens: opts?.maxTokens,
+            systemPrompt: opts?.systemPrompt,
+            ...tools !== void 0 ? { tools } : {}
+          };
+          if (opts?.abort) {
+            const sig = nodeSignal(opts.abort);
+            invokeOpts.signal = sig.signal;
+            abortDispose = sig.dispose;
+          }
+          let invokeResult;
+          try {
+            invokeResult = adapter.invoke(msgs, invokeOpts);
+          } catch (err) {
+            done = true;
+            actions.down([[ERROR3, err]]);
+            return () => {
+              abortDispose?.();
+            };
+          }
+          const callNode = fromAny3(invokeResult);
+          const sub = callNode.subscribe((batch2) => {
+            if (cancelled || done) return;
+            for (const msg of batch2) {
+              if (cancelled || done) return;
+              if (msg[0] === DATA3) {
+                const resp = msg[1];
+                if (format === "raw") {
+                  actions.emit(resp);
+                } else {
+                  let content;
+                  try {
+                    content = extractContent(resp);
+                  } catch (err) {
+                    const wrapped = new Error(
+                      `promptNode: failed to extract content from LLM response: ${err.message}`
+                    );
+                    abortDispose?.();
+                    abortDispose = void 0;
+                    done = true;
+                    actions.down([[ERROR3, wrapped]]);
+                    return;
+                  }
+                  try {
+                    const parsed = format === "json" ? JSON.parse(stripFences(content)) : content;
+                    actions.emit(parsed);
+                  } catch (err) {
+                    const wrapped = new Error(
+                      `promptNode: failed to parse LLM response as JSON: ${err.message}
+  Raw content (first 200 chars): ${previewContent(content)}`
+                    );
+                    abortDispose?.();
+                    abortDispose = void 0;
+                    done = true;
+                    actions.down([[ERROR3, wrapped]]);
+                    return;
+                  }
+                }
+              } else if (msg[0] === ERROR3) {
+                abortDispose?.();
+                abortDispose = void 0;
+                done = true;
+                actions.down([[ERROR3, msg[1]]]);
+                return;
+              } else if (msg[0] === COMPLETE2) {
+                abortDispose?.();
+                abortDispose = void 0;
+                done = true;
+                actions.down([[COMPLETE2]]);
+                return;
+              } else {
+                actions.down([msg]);
+              }
+            }
+          });
+          return () => {
+            cancelled = true;
+            sub();
+            abortDispose?.();
+            abortDispose = void 0;
+          };
+        },
+        {
+          describeKind: "producer",
+          name: `${baseName}::response`,
+          meta: aiMeta("prompt_node::response")
+        }
+      );
+    },
+    {
+      name: `${baseName}::output`,
+      meta: opts?.meta ? { ...aiMeta("prompt_node::output"), ...opts.meta } : aiMeta("prompt_node::output")
+    }
+  );
+  return result;
+}
+
+// src/utils/ai/prompts/prompt-call.ts
+import { node as node7 } from "@graphrefly/pure-ts/core";
+function promptCall(systemPrompt, buildUserContent, opts, defaultName) {
+  const name = opts.name ?? defaultName;
+  return (input) => {
+    const inputState = node7([], { initial: input });
+    return promptNode(
+      opts.adapter,
+      [inputState],
+      (value) => buildUserContent(value),
+      {
+        name,
+        format: "json",
+        systemPrompt,
+        model: opts.model,
+        temperature: opts.temperature ?? 0,
+        maxTokens: opts.maxTokens
+      }
+    );
+  };
+}
+function llmExtractor(systemPrompt, opts) {
+  const cap = opts.maxExistingKeys ?? 100;
+  const call = promptCall(
+    systemPrompt,
+    (input) => JSON.stringify({ input: input.raw, existingKeys: input.existingKeys }),
+    opts,
+    "llmExtractor"
+  );
+  return (raw, existing) => {
+    const existingKeys = cap === Number.POSITIVE_INFINITY ? [...existing.keys()] : [...existing.keys()].slice(0, cap);
+    return call({ raw, existingKeys });
+  };
+}
+function llmConsolidator(systemPrompt, opts) {
+  const call = promptCall(
+    systemPrompt,
+    (memories) => JSON.stringify({ memories }),
+    opts,
+    "llmConsolidator"
+  );
+  return (entries) => {
+    const memories = [...entries.entries()].map(([key, value]) => ({ key, value }));
+    return call(memories);
+  };
+}
+
+export {
+  aiMeta,
+  resolveToolHandlerResult,
+  stripFences,
+  _oneShotLlmCall,
+  ChatStreamGraph,
+  chatStream,
+  toolExecution,
+  ToolRegistryGraph,
+  toolRegistry,
+  MemoryWithVectorsGraph,
+  memoryWithVectors,
+  MemoryWithKGGraph,
+  memoryWithKG,
+  MemoryWithTiersGraph,
+  memoryWithTiers,
+  MemoryRetrievalGraph,
+  memoryRetrieval,
+  promptNode,
+  promptCall,
+  llmExtractor,
+  llmConsolidator
+};
+//# sourceMappingURL=chunk-OO5BM6CJ.js.map