@graphrefly/graphrefly 0.47.0 → 0.47.1

package/dist/{chunk-ZVXXDWIB.js → chunk-U225SKB4.js}

@@ -12,8 +12,8 @@ import {
 } from "./chunk-BXGZFGZ4.js";
 
 // src/utils/memory/index.ts
-import { monotonicNs, NodeImpl, node as node2, wallClockNs as wallClockNs2 } from "@graphrefly/pure-ts/core";
-import { fromTimer, keepalive as keepalive2, reactiveMap } from "@graphrefly/pure-ts/extra";
+import { monotonicNs, NodeImpl, node as node9, wallClockNs as wallClockNs3 } from "@graphrefly/pure-ts/core";
+import { fromTimer as fromTimer3, keepalive as keepalive6, reactiveMap } from "@graphrefly/pure-ts/extra";
 import { Graph as Graph2 } from "@graphrefly/pure-ts/graph";
 
 // src/utils/memory/fact-store.ts
@@ -500,6 +500,427 @@ function reactiveFactStore(config) {
   return out;
 }
 
+// src/utils/memory/persistent-fact-store.ts
+import { COMPLETE, node as node2 } from "@graphrefly/pure-ts/core";
+import {
+  appendLogStorage,
+  bigintJsonCodecFor,
+  fromAny,
+  keepalive as keepalive2
+} from "@graphrefly/pure-ts/extra";
+function persistMeta(kind) {
+  return domainMeta("memory", kind);
+}
+function persistentReactiveFactStore(config) {
+  const persistName = config.persistName ?? "fact_store_ingest";
+  const codec = config.codec ?? bigintJsonCodecFor();
+  const tier = appendLogStorage(config.storage, {
+    name: persistName,
+    codec
+  });
+  const store = reactiveFactStore({ ...config, recordIngest: true });
+  const ingestLog = store.ingestLog;
+  async function* loadHistory() {
+    if (typeof tier.loadEntries !== "function") return;
+    const page = await tier.loadEntries();
+    for (const f of page.entries) yield f;
+  }
+  const replaySource = fromAny(loadHistory(), {
+    name: "_replay_source",
+    meta: persistMeta("persist_replay_source")
+  });
+  store.add(replaySource, { name: "_replay_source" });
+  let replayed = 0;
+  const replayPump = node2(
+    [replaySource],
+    (batchData, actions) => {
+      const b = batchData[0];
+      if (b != null && b.length > 0) {
+        for (const f of b) {
+          config.ingest.emit(f);
+          replayed += 1;
+        }
+        actions.emit(replayed);
+      }
+    },
+    {
+      name: "_replay_pump",
+      describeKind: "derived",
+      initial: 0,
+      meta: persistMeta("persist_replay_pump")
+    }
+  );
+  store.add(replayPump, { name: "_replay_pump" });
+  store.addDisposer(keepalive2(replayPump));
+  const attached = node2([], {
+    initial: false,
+    name: "_storage_attached",
+    describeKind: "state",
+    meta: persistMeta("persist_attached")
+  });
+  store.add(attached, { name: "_storage_attached" });
+  store.addDisposer(keepalive2(attached));
+  let detachStorage;
+  const replaySub = replaySource.subscribe((msgs) => {
+    for (const m of msgs) {
+      if (m[0] === COMPLETE && detachStorage === void 0) {
+        const sizeAtAttach = ingestLog.size;
+        detachStorage = ingestLog.attachStorage([tier]);
+        if (sizeAtAttach > replayed) {
+          const slice = [];
+          for (let i = replayed; i < sizeAtAttach; i += 1) {
+            const v = ingestLog.at(i);
+            if (v === void 0) {
+              throw new Error(
+                `persistentReactiveFactStore: ingestLog hole at index ${i} in reconciliation slice [${replayed}, ${sizeAtAttach}); pre-attach-live durability cannot be guaranteed.`
+              );
+            }
+            slice.push(v);
+          }
+          if (slice.length > 0) {
+            const r = tier.appendEntries(slice);
+            if (r instanceof Promise) r.catch(() => {
+            });
+          }
+        }
+        attached.emit(true);
+      }
+    }
+  });
+  store.addDisposer(() => {
+    replaySub();
+    detachStorage?.();
+  });
+  const position = node2(
+    [ingestLog.entries, attached],
+    (batchData, actions, ctx) => {
+      const eb = batchData[0];
+      const arr = eb != null && eb.length > 0 ? eb.at(-1) : ctx.prevData[0];
+      const ab = batchData[1];
+      const isAttached = ab != null && ab.length > 0 ? ab.at(-1) : ctx.prevData[1];
+      actions.emit(isAttached === true ? arr?.length ?? 0 : 0);
+    },
+    {
+      name: "_durable_position",
+      describeKind: "derived",
+      initial: 0,
+      meta: persistMeta("persist_position")
+    }
+  );
+  store.add(position, { name: "_durable_position" });
+  store.addDisposer(keepalive2(position));
+  const out = Object.assign(store, {
+    position,
+    replayedCount: replayPump,
+    tier,
+    async flush() {
+      await tier.flush?.();
+    }
+  });
+  return out;
+}
+
+// src/utils/memory/recipes/admission-llm-judge.ts
+import { node as node3 } from "@graphrefly/pure-ts/core";
+function admissionLlmJudge(verdicts, opts = {}) {
+  const dflt = opts.defaultVerdict ?? false;
+  const buildFilter = (m) => (f) => m.get(f.id) ?? dflt;
+  return node3(
+    [verdicts],
+    (batchData, actions, ctx) => {
+      const m = batchData[0]?.at(-1) ?? ctx.prevData[0] ?? /* @__PURE__ */ new Map();
+      actions.emit(buildFilter(m));
+    },
+    {
+      name: opts.name ?? "admission_llm_judge",
+      describeKind: "derived",
+      // Before any verdict arrives, apply the default policy.
+      initial: buildFilter(/* @__PURE__ */ new Map())
+    }
+  );
+}
+
+// src/utils/memory/recipes/bitemporal-query.ts
+import { node as node4 } from "@graphrefly/pure-ts/core";
+
+// src/utils/memory/recipes/_shared.ts
+function lastOf2(batch, prev) {
+  return batch != null && batch.length > 0 ? batch.at(-1) : prev;
+}
+function validAt(f, asOf) {
+  if (asOf === void 0) return f.validTo === void 0;
+  if (f.validFrom !== void 0 && asOf < f.validFrom) return false;
+  if (f.validTo !== void 0 && asOf >= f.validTo) return false;
+  return true;
+}
+
+// src/utils/memory/recipes/bitemporal-query.ts
+function bitemporalQuery(mem, asOf, opts = {}) {
+  const asOfOrNull = node4(
+    [asOf],
+    (b, a, c) => a.emit(lastOf2(b[0], c.prevData[0]) ?? null),
+    { name: `${opts.name ?? "bitemporal_query"}_asof`, describeKind: "derived", initial: null }
+  );
+  return node4(
+    [asOfOrNull, mem.factStore],
+    (batchData, actions, ctx) => {
+      const raw = lastOf2(batchData[0], ctx.prevData[0]);
+      const at = raw ?? void 0;
+      const fs = lastOf2(batchData[1], ctx.prevData[1]);
+      if (fs == null) {
+        actions.emit([]);
+        return;
+      }
+      const results = [...fs.byId.values()].filter((f) => {
+        if (!validAt(f, at)) return false;
+        if (opts.tags && opts.tags.length > 0 && !opts.tags.some((t) => f.tags.includes(t))) {
+          return false;
+        }
+        if (opts.minConfidence !== void 0 && f.confidence < opts.minConfidence) return false;
+        return true;
+      });
+      results.sort((a, b) => b.confidence - a.confidence || Number(b.t_ns - a.t_ns));
+      actions.emit(results);
+    },
+    {
+      name: opts.name ?? "bitemporal_query",
+      describeKind: "derived",
+      initial: []
+    }
+  );
+}
+
+// src/utils/memory/recipes/consolidation-rem.ts
+import { fromTimer } from "@graphrefly/pure-ts/extra";
+function consolidationRem(opts) {
+  const consolidateTrigger = fromTimer(opts.periodMs, { period: opts.periodMs });
+  const consolidate = (store) => {
+    const live = [...store.values()].filter((f) => f.validTo === void 0);
+    if (live.length === 0) return [];
+    let pool = live;
+    if (opts.recentWindowNs !== void 0) {
+      const newest = live.reduce((m, f) => f.t_ns > m ? f.t_ns : m, live[0].t_ns);
+      const cutoff = newest - opts.recentWindowNs;
+      pool = live.filter((f) => f.t_ns >= cutoff);
+    }
+    pool.sort((a, b) => b.confidence - a.confidence || Number(b.t_ns - a.t_ns));
+    const replayed = pool.slice(0, Math.max(0, opts.topK));
+    return replayed.length > 0 ? opts.summarize(replayed) : [];
+  };
+  return { consolidateTrigger, consolidate };
+}
+
+// src/utils/memory/recipes/decay-exponential.ts
+import { node as node5, wallClockNs as wallClockNs2 } from "@graphrefly/pure-ts/core";
+import { fromTimer as fromTimer2, keepalive as keepalive3 } from "@graphrefly/pure-ts/extra";
+function decayExponential(mem, ingest, opts) {
+  const floor = opts.floor ?? 0;
+  const epsilon = Math.max(opts.epsilon ?? 1e-4, Number.EPSILON);
+  const half = Number(opts.halfLifeNs);
+  const lastTick = /* @__PURE__ */ new Map();
+  const timer = fromTimer2(opts.periodMs, { period: opts.periodMs });
+  const driver = node5(
+    [timer],
+    (_batchData, actions) => {
+      const fs = mem.factStore.cache;
+      if (!fs) {
+        actions.emit([]);
+        return;
+      }
+      const now = BigInt(wallClockNs2());
+      const decayed = [];
+      const liveIds = /* @__PURE__ */ new Set();
+      for (const f of fs.byId.values()) {
+        liveIds.add(f.id);
+        if (f.validTo !== void 0) continue;
+        if (f.confidence <= floor) continue;
+        const lt = lastTick.get(f.id);
+        const since = lt !== void 0 && lt >= f.t_ns ? lt : f.t_ns;
+        const elapsed = Number(now - since);
+        if (elapsed <= 0) continue;
+        const factor = 0.5 ** (half > 0 ? elapsed / half : 0);
+        if (!Number.isFinite(factor)) continue;
+        let next = f.confidence * factor;
+        if (next < floor) next = floor;
+        if (f.confidence - next < epsilon) continue;
+        const liveNow = mem.factStore.cache?.byId.get(f.id);
+        if (liveNow && liveNow.validTo !== void 0) continue;
+        lastTick.set(f.id, now);
+        const drifted = { ...f, confidence: next };
+        decayed.push(drifted);
+        ingest.emit(drifted);
+      }
+      if (lastTick.size > liveIds.size) {
+        for (const id of lastTick.keys()) if (!liveIds.has(id)) lastTick.delete(id);
+      }
+      actions.emit(decayed);
+    },
+    {
+      name: opts.name ?? "decay_exponential",
+      describeKind: "derived",
+      initial: []
+    }
+  );
+  mem.add(driver, { name: opts.name ?? "decay_exponential" });
+  mem.addDisposer(keepalive3(timer));
+  mem.addDisposer(keepalive3(driver));
+  return driver;
+}
+
+// src/utils/memory/recipes/influence-analysis.ts
+import { node as node6 } from "@graphrefly/pure-ts/core";
+import { keepalive as keepalive4 } from "@graphrefly/pure-ts/extra";
+function closureOf(index, root) {
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [root];
+  while (queue.length > 0) {
+    const cur = queue.shift();
+    for (const dep of index.get(cur) ?? []) {
+      if (seen.has(dep) || dep === root) continue;
+      seen.add(dep);
+      queue.push(dep);
+    }
+  }
+  return [...seen];
+}
+function influenceAnalysis(mem, opts = {}) {
+  const prefix = opts.name ?? "influence";
+  const maxRanked = Math.max(1, opts.maxRanked ?? 64);
+  const ranked = node6(
+    [mem.dependentsIndex],
+    (batchData, actions, ctx) => {
+      const index = lastOf2(batchData[0], ctx.prevData[0]);
+      if (index == null) {
+        actions.emit([]);
+        return;
+      }
+      const rows = [];
+      for (const key of index.keys()) {
+        rows.push({ factId: key, influence: closureOf(index, key).length });
+      }
+      rows.sort((a, b) => b.influence - a.influence);
+      actions.emit(rows.slice(0, maxRanked));
+    },
+    {
+      name: `${prefix}_ranked`,
+      describeKind: "derived",
+      initial: []
+    }
+  );
+  mem.add(ranked, { name: `${prefix}_ranked` });
+  mem.addDisposer(keepalive4(ranked));
+  const builtFor = /* @__PURE__ */ new Map();
+  function influenceOf(rootId) {
+    const existing = builtFor.get(rootId);
+    if (existing) return existing;
+    const n = node6(
+      [mem.dependentsIndex],
+      (batchData, actions, ctx) => {
+        const index = lastOf2(batchData[0], ctx.prevData[0]);
+        actions.emit(index == null ? [] : closureOf(index, rootId));
+      },
+      {
+        name: `${prefix}_of_${rootId}`,
+        describeKind: "derived",
+        initial: []
+      }
+    );
+    mem.add(n, { name: `${prefix}_of_${rootId}` });
+    mem.addDisposer(keepalive4(n));
+    builtFor.set(rootId, n);
+    return n;
+  }
+  return { influenceOf, ranked };
+}
+
+// src/utils/memory/recipes/invalidation-tracer.ts
+import { node as node7 } from "@graphrefly/pure-ts/core";
+import { keepalive as keepalive5 } from "@graphrefly/pure-ts/extra";
+function invalidationTracer(mem, opts = {}) {
+  const limit = Math.max(1, opts.limit ?? 256);
+  const ring = [];
+  const push = (e) => {
+    ring.push(e);
+    if (ring.length > limit) ring.splice(0, ring.length - limit);
+  };
+  const tracer = node7(
+    [mem.cascade, mem.cascadeOverflow],
+    (batchData, actions) => {
+      const cascadeWaves = batchData[0] ?? [];
+      for (const wave of cascadeWaves) {
+        for (const ev of wave) {
+          push({
+            kind: "cascade",
+            factId: ev.factId,
+            rootFactId: ev.rootFactId,
+            reason: ev.reason,
+            iteration: ev.iteration,
+            causalReason: ev.causalReason
+          });
+        }
+      }
+      const overflows = batchData[1] ?? [];
+      for (const ov of overflows) {
+        if (ov == null) continue;
+        push({
+          kind: "overflow",
+          factId: ov.sample[0] ?? "",
+          rootFactId: ov.rootFactId,
+          reason: "overflow",
+          causalReason: `cascade overflow: ${ov.droppedCount} dropped (root ${ov.rootFactId})`
+        });
+      }
+      actions.emit([...ring]);
+    },
+    {
+      name: opts.name ?? "invalidation_tracer",
+      describeKind: "derived",
+      initial: []
+    }
+  );
+  mem.add(tracer, { name: opts.name ?? "invalidation_tracer" });
+  mem.addDisposer(keepalive5(tracer));
+  return tracer;
+}
+
+// src/utils/memory/recipes/scoring-by-outcome.ts
+import { node as node8 } from "@graphrefly/pure-ts/core";
+var clamp01 = (n) => n < 0 ? 0 : n > 1 ? 1 : n;
+function scoringByOutcome(outcomes, opts = {}) {
+  const base = opts.base ?? ((f) => f.confidence);
+  const learningRate = opts.learningRate ?? 1;
+  const acc = /* @__PURE__ */ new Map();
+  const buildPolicy = () => (fragment) => clamp01(base(fragment) + learningRate * (acc.get(fragment.id) ?? 0));
+  return node8(
+    [outcomes],
+    (batchData, actions) => {
+      const wave = batchData[0] ?? [];
+      for (const sig of wave) acc.set(sig.factId, (acc.get(sig.factId) ?? 0) + sig.reward);
+      actions.emit(buildPolicy());
+    },
+    {
+      name: opts.name ?? "scoring_by_outcome",
+      describeKind: "derived",
+      // Usable scorer before any outcome arrives (base-only).
+      initial: buildPolicy()
+    }
+  );
+}
+
+// src/utils/memory/recipes/shard-by-tenant.ts
+function shardByTenant(tenantOf, opts = {}) {
+  if (opts.tenants && opts.tenants.length > 0) {
+    const idx = new Map(opts.tenants.map((t, i) => [t, i]));
+    const overflow = opts.tenants.length;
+    return {
+      shardBy: (f) => idx.get(tenantOf(f)) ?? overflow,
+      shardCount: opts.tenants.length + 1
+    };
+  }
+  const shardCount = Math.max(1, opts.shardCount ?? 4);
+  return { shardBy: (f) => tenantOf(f), shardCount };
+}
+
 // src/utils/memory/index.ts
 var NS_PER_SEC = 1e9;
 function memoryMeta(kind, extra) {
@@ -507,7 +928,7 @@ function memoryMeta(kind, extra) {
 }
 function toNode(v, name) {
   if (v instanceof NodeImpl) return v;
-  return node2([], { initial: v, ...name ? { name } : void 0 });
+  return node9([], { initial: v, ...name ? { name } : void 0 });
 }
 function ageSeconds(now, lastNs) {
   return (now - lastNs) / NS_PER_SEC;
@@ -576,8 +997,8 @@ function collection(name, opts = {}) {
   let refreshTick;
   if (ranked && decayRate > 0) {
     const intervalMs = opts.refreshIntervalMs ?? Math.max(1, 1e3 * Math.LN2 / (10 * decayRate));
-    const tickCounter = fromTimer(intervalMs, { period: intervalMs });
-    refreshTick = node2(
+    const tickCounter = fromTimer3(intervalMs, { period: intervalMs });
+    refreshTick = node9(
       [tickCounter],
       (_batchData, actions) => {
         actions.emit(monotonicNs());
@@ -596,7 +1017,7 @@ function collection(name, opts = {}) {
     const rankedDeps = [items.entries];
     if (refreshTick) rankedDeps.push(refreshTick);
     if (scoreNode) rankedDeps.push(scoreNode);
-    rankedNode = node2(
+    rankedNode = node9(
       rankedDeps,
       (batchData, actions, ctx) => {
         const values = batchData.map(
@@ -633,7 +1054,7 @@ function collection(name, opts = {}) {
     );
     graph.add(rankedNode, { name: "ranked" });
   } else {
-    rankedNode = node2([], {
+    rankedNode = node9([], {
       initial: [],
       name: "ranked",
       describeKind: "state",
@@ -641,7 +1062,7 @@ function collection(name, opts = {}) {
     });
     graph.add(rankedNode, { name: "ranked" });
   }
-  const size = node2(
+  const size = node9(
     [items.entries],
     (batchData, actions, ctx) => {
       const data = batchData.map(
@@ -658,7 +1079,7 @@ function collection(name, opts = {}) {
     }
   );
   graph.add(size, { name: "size" });
-  graph.addDisposer(keepalive2(size));
+  graph.addDisposer(keepalive6(size));
   const events = createAuditLog({
     name: "events",
     retainedLimit: 1024,
@@ -722,7 +1143,7 @@ function collection(name, opts = {}) {
   });
   function itemNode(id) {
     const idN = toNode(id, "id");
-    return node2(
+    return node9(
       [items.entries, idN],
       (batchData, actions, ctx) => {
         const data = batchData.map(
@@ -740,7 +1161,7 @@ function collection(name, opts = {}) {
   }
   function hasNode(id) {
     const idN = toNode(id, "id");
-    return node2(
+    return node9(
       [items.entries, idN],
       (batchData, actions, ctx) => {
         const data = batchData.map(
@@ -827,7 +1248,7 @@ function vectorIndex(opts = {}) {
           events.append({
             action: "evict",
             id: key,
-            t_ns: wallClockNs2(),
+            t_ns: wallClockNs3(),
             seq: bumpCursor(seqCursor)
           });
         }
@@ -835,7 +1256,7 @@ function vectorIndex(opts = {}) {
     } : {}
   });
   graph.add(entries.entries, { name: "entries" });
-  graph.addDisposer(keepalive2(entries.entries));
+  graph.addDisposer(keepalive6(entries.entries));
   if (hnsw?.dispose) {
     const disposeAdapter = hnsw.dispose.bind(hnsw);
     graph.addDisposer(() => disposeAdapter());
@@ -908,7 +1329,7 @@ function vectorIndex(opts = {}) {
   });
   function searchNode(query, k = 5) {
     const kN = toNode(k, "k");
-    return node2(
+    return node9(
       [entries.entries, query, kN],
       (batchData, actions, ctx) => {
         const values = batchData.map(
@@ -1024,7 +1445,7 @@ function knowledgeGraph(name, opts = {}) {
   });
   graph.add(entitiesMap.entries, { name: "entities" });
   graph.add(edgesMap.entries, { name: "edges" });
-  const adjacencyOut = node2(
+  const adjacencyOut = node9(
     [edgesMap.entries],
     (batchData, actions, ctx) => {
       const data = batchData.map(
@@ -1041,7 +1462,7 @@ function knowledgeGraph(name, opts = {}) {
       meta: memoryMeta("adjacency_out")
     }
   );
-  const adjacencyIn = node2(
+  const adjacencyIn = node9(
     [edgesMap.entries],
     (batchData, actions, ctx) => {
       const data = batchData.map(
@@ -1060,9 +1481,9 @@ function knowledgeGraph(name, opts = {}) {
   );
   graph.add(adjacencyOut, { name: "adjacencyOut" });
   graph.add(adjacencyIn, { name: "adjacencyIn" });
-  graph.addDisposer(keepalive2(adjacencyOut));
-  graph.addDisposer(keepalive2(adjacencyIn));
-  const entityCount = node2(
+  graph.addDisposer(keepalive6(adjacencyOut));
+  graph.addDisposer(keepalive6(adjacencyIn));
+  const entityCount = node9(
     [entitiesMap.entries],
     (batchData, actions, ctx) => {
       const data = batchData.map(
@@ -1073,7 +1494,7 @@ function knowledgeGraph(name, opts = {}) {
     },
     { name: "entityCount", describeKind: "derived", initial: 0, meta: memoryMeta("entity_count") }
   );
-  const edgeCount = node2(
+  const edgeCount = node9(
     [edgesMap.entries],
     (batchData, actions, ctx) => {
       const data = batchData.map(
@@ -1086,8 +1507,8 @@ function knowledgeGraph(name, opts = {}) {
   );
   graph.add(entityCount, { name: "entityCount" });
   graph.add(edgeCount, { name: "edgeCount" });
-  graph.addDisposer(keepalive2(entityCount));
-  graph.addDisposer(keepalive2(edgeCount));
+  graph.addDisposer(keepalive6(entityCount));
+  graph.addDisposer(keepalive6(edgeCount));
   const events = createAuditLog({
     name: "events",
     retainedLimit: 1024,
@@ -1110,7 +1531,7 @@ function knowledgeGraph(name, opts = {}) {
       events.append({
         action: "orphanRemove",
         id: candidate,
-        t_ns: wallClockNs2(),
+        t_ns: wallClockNs3(),
         seq: bumpCursor(seqCursor)
       });
     }
@@ -1205,7 +1626,7 @@ function knowledgeGraph(name, opts = {}) {
     const idN = toNode(id, "id");
     const relN = relation !== void 0 ? toNode(relation, "relation") : void 0;
     const deps = relN ? [adjacencyOut, adjacencyIn, idN, relN] : [adjacencyOut, adjacencyIn, idN];
-    return node2(
+    return node9(
       deps,
       (batchData, actions, ctx) => {
         const values = batchData.map(
@@ -1274,9 +1695,18 @@ function knowledgeGraph(name, opts = {}) {
 
 export {
   reactiveFactStore,
+  persistentReactiveFactStore,
+  admissionLlmJudge,
+  bitemporalQuery,
+  consolidationRem,
+  decayExponential,
+  influenceAnalysis,
+  invalidationTracer,
+  scoringByOutcome,
+  shardByTenant,
   cosineSimilarity,
   collection,
   vectorIndex,
   knowledgeGraph
 };
-//# sourceMappingURL=chunk-ZVXXDWIB.js.map
+//# sourceMappingURL=chunk-U225SKB4.js.map