@graphrefly/graphrefly 0.47.2 → 0.48.0

package/dist/utils/memory/index.cjs

@@ -20,6 +20,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/utils/memory/index.ts
 var memory_exports = {};
 __export(memory_exports, {
+  DEFAULT_DECAY_HALF_LIFE_NS: () => DEFAULT_DECAY_HALF_LIFE_NS,
+  DEFAULT_DECAY_PERIOD_MS: () => DEFAULT_DECAY_PERIOD_MS,
+  ReactiveFactStoreGraph: () => ReactiveFactStoreGraph,
   admissionLlmJudge: () => admissionLlmJudge,
   bitemporalQuery: () => bitemporalQuery,
   collection: () => collection,
@@ -33,10 +36,11 @@ __export(memory_exports, {
   reactiveFactStore: () => reactiveFactStore,
   scoringByOutcome: () => scoringByOutcome,
   shardByTenant: () => shardByTenant,
+  simpleFactStore: () => simpleFactStore,
   vectorIndex: () => vectorIndex
 });
 module.exports = __toCommonJS(memory_exports);
-var import_core10 = require("@graphrefly/pure-ts/core");
+var import_core11 = require("@graphrefly/pure-ts/core");
 var import_extra8 = require("@graphrefly/pure-ts/extra");
 var import_graph3 = require("@graphrefly/pure-ts/graph");
 
@@ -242,479 +246,534 @@ function currentlyValid(f, asOf) {
 function lastOf(batch2, prev) {
   return batch2 != null && batch2.length > 0 ? batch2.at(-1) : prev;
 }
-function reactiveFactStore(config) {
-  const shardCount = Math.max(1, config.shardCount ?? 4);
-  const maxIterations = Math.max(1, config.cascadeMaxIterations ?? 8);
-  const reviewThreshold = config.reviewThreshold ?? 0.3;
-  const shardBy = config.shardBy ?? ((f) => fnv1a(String(f.id)) % shardCount);
-  let cascadeIteration = 0;
-  const processedRoots = /* @__PURE__ */ new Set();
-  const graph = new import_graph2.Graph("reactive_fact_store");
-  const events = createAuditLog({
-    name: "events",
-    retainedLimit: 1024,
-    graph
-  });
-  const seqCursor = registerCursor(graph, "seq", 0);
-  const ingestLog = config.recordIngest ? (0, import_extra2.reactiveLog)([], { name: "ingest_log" }) : void 0;
-  if (ingestLog) graph.addDisposer(() => ingestLog.dispose());
-  const emptyStore = () => ({ byId: /* @__PURE__ */ new Map() });
-  const shards = [];
-  for (let s = 0; s < shardCount; s += 1) {
-    const shard = (0, import_core2.node)([], {
-      initial: emptyStore(),
-      name: `shard_${s}`,
-      describeKind: "state",
-      meta: factMeta("factstore", { shard: s })
+var ReactiveFactStoreGraph = class extends import_graph2.Graph {
+  // ④ Topic outputs (caller subscribes for custom processing).
+  /** Per-shard `state<FactStore<T>>` nodes (length = shard count). */
+  shards;
+  /** Unified read view across all shards (derived). */
+  factStore;
+  dependentsIndex;
+  answer;
+  cascade;
+  cascadeOverflow;
+  review;
+  consolidated;
+  events;
+  /**
+   * Payload-carrying, replayable log of every committed fragment. Present iff
+   * {@link ReactiveFactStoreConfig.recordIngest} is `true`. Unlike
+   * {@link ReactiveFactStoreGraph.events} (action-only audit), each entry is
+   * the full {@link MemoryFragment} — `attachStorage` it for a durable,
+   * replayable projection source (see `recordIngest` docs for the recipe).
+   */
+  ingestLog;
+  constructor(config) {
+    const shardCount = Math.max(1, config.shardCount ?? 4);
+    const maxIterations = Math.max(1, config.cascadeMaxIterations ?? 8);
+    const reviewThreshold = config.reviewThreshold ?? 0.3;
+    const shardBy = config.shardBy ?? ((f) => fnv1a(String(f.id)) % shardCount);
+    let cascadeIteration = 0;
+    const processedRoots = /* @__PURE__ */ new Set();
+    super("reactive_fact_store");
+    const events = createAuditLog({
+      name: "events",
+      retainedLimit: 1024,
+      graph: this
     });
-    graph.add(shard, { name: `shard_${s}` });
-    graph.addDisposer((0, import_extra2.keepalive)(shard));
-    shards.push(shard);
-  }
-  const shardIndexFor = (f) => {
-    const key = shardBy(f);
-    const n = typeof key === "number" ? key : fnv1a(String(key));
-    const idx = (n % shardCount + shardCount) % shardCount;
-    return idx;
-  };
-  const findShardOf = (id) => {
+    const seqCursor = registerCursor(this, "seq", 0);
+    const ingestLog = config.recordIngest ? (0, import_extra2.reactiveLog)([], { name: "ingest_log" }) : void 0;
+    if (ingestLog) this.addDisposer(() => ingestLog.dispose());
+    const emptyStore = () => ({ byId: /* @__PURE__ */ new Map() });
+    const shards = [];
     for (let s = 0; s < shardCount; s += 1) {
-      const fs = shards[s].cache;
-      if (fs?.byId.has(id)) return s;
-    }
-    return -1;
-  };
-  const allFacts = () => {
-    const out2 = /* @__PURE__ */ new Map();
-    for (const sh of shards) {
-      const fs = sh.cache;
-      if (!fs) continue;
-      for (const [k, v] of fs.byId) out2.set(k, v);
-    }
-    return out2;
-  };
-  const commitFragment = (f) => {
-    const idx = shardIndexFor(f);
-    const cur = shards[idx].cache ?? emptyStore();
-    const next = new Map(cur.byId);
-    next.set(f.id, f);
-    shards[idx].emit({ byId: next });
-  };
-  const replaceFragment = (id, mut) => {
-    const idx = findShardOf(id);
-    if (idx < 0) return false;
-    const cur = shards[idx].cache;
-    const prev = cur.byId.get(id);
-    if (!prev) return false;
-    const next = new Map(cur.byId);
-    next.set(id, mut(prev));
-    shards[idx].emit({ byId: next });
-    return true;
-  };
-  const dependentsIndex = (0, import_core2.node)([], {
-    initial: /* @__PURE__ */ new Map(),
-    name: "dependents_index",
-    describeKind: "state",
-    meta: factMeta("factstore", { role: "dependents_index" })
-  });
-  graph.add(dependentsIndex, { name: "dependents_index" });
-  graph.addDisposer((0, import_extra2.keepalive)(dependentsIndex));
-  const indexFragment = (f, deps) => {
-    const cur = dependentsIndex.cache;
-    const next = /* @__PURE__ */ new Map();
-    for (const [k, v] of cur) next.set(k, [...v]);
-    for (const src of deps) {
-      const bucket = next.get(src) ?? [];
-      if (!bucket.includes(f.id)) bucket.push(f.id);
-      next.set(src, bucket);
+      const shard = (0, import_core2.node)([], {
+        initial: emptyStore(),
+        name: `shard_${s}`,
+        describeKind: "state",
+        meta: factMeta("factstore", { shard: s })
+      });
+      this.add(shard, { name: `shard_${s}` });
+      this.addDisposer((0, import_extra2.keepalive)(shard));
+      shards.push(shard);
     }
-    dependentsIndex.emit(next);
-  };
-  const factStore = (0, import_core2.node)(
-    shards,
-    (batchData, actions, ctx) => {
-      void batchData;
-      void ctx;
-      actions.emit({ byId: allFacts() });
-    },
-    {
-      name: "fact_store",
-      describeKind: "derived",
-      initial: emptyStore(),
-      meta: factMeta("factstore", { role: "read_view" }),
-      // F10a: `allFacts()` builds a fresh Map every detector retrigger.
-      // Fragments are immutable (replaced wholesale on mutation), so a
-      // same-size + per-key-identity check is a sound structural equality
-      // that stops `factStore` (and its `review` dependent) from re-firing
-      // every cascade wave when nothing actually changed.
-      equals: (a, b) => {
-        if (a === b) return true;
-        if (a.byId.size !== b.byId.size) return false;
-        for (const [k, v] of a.byId) {
-          if (b.byId.get(k) !== v) return false;
-        }
-        return true;
+    const shardIndexFor = (f) => {
+      const key = shardBy(f);
+      const n = typeof key === "number" ? key : fnv1a(String(key));
+      const idx = (n % shardCount + shardCount) % shardCount;
+      return idx;
+    };
+    const findShardOf = (id) => {
+      for (let s = 0; s < shardCount; s += 1) {
+        const fs = shards[s].cache;
+        if (fs?.byId.has(id)) return s;
       }
-    }
-  );
-  graph.add(factStore, { name: "fact_store" });
-  graph.addDisposer((0, import_extra2.keepalive)(factStore));
-  const extractOp = (0, import_core2.node)(
-    config.admissionFilter ? [config.ingest, config.admissionFilter] : [config.ingest],
-    (batchData, actions, ctx) => {
-      const f = lastOf(batchData[0], ctx.prevData[0]);
-      if (f == null) {
-        actions.emit(null);
-        return;
+      return -1;
+    };
+    const allFacts = () => {
+      const out = /* @__PURE__ */ new Map();
+      for (const sh of shards) {
+        const fs = sh.cache;
+        if (!fs) continue;
+        for (const [k, v] of fs.byId) out.set(k, v);
       }
-      if (config.admissionFilter) {
-        const filter = lastOf(batchData[1], ctx.prevData[1]);
-        if (filter && !filter(f)) {
+      return out;
+    };
+    const commitFragment = (f) => {
+      const idx = shardIndexFor(f);
+      const cur = shards[idx].cache ?? emptyStore();
+      const next = new Map(cur.byId);
+      next.set(f.id, f);
+      shards[idx].emit({ byId: next });
+    };
+    const replaceFragment = (id, mut) => {
+      const idx = findShardOf(id);
+      if (idx < 0) return false;
+      const cur = shards[idx].cache;
+      const prev = cur.byId.get(id);
+      if (!prev) return false;
+      const next = new Map(cur.byId);
+      next.set(id, mut(prev));
+      shards[idx].emit({ byId: next });
+      return true;
+    };
+    const dependentsIndex = (0, import_core2.node)([], {
+      initial: /* @__PURE__ */ new Map(),
+      name: "dependents_index",
+      describeKind: "state",
+      meta: factMeta("factstore", { role: "dependents_index" })
+    });
+    this.add(dependentsIndex, { name: "dependents_index" });
+    this.addDisposer((0, import_extra2.keepalive)(dependentsIndex));
+    const indexFragment = (f, deps) => {
+      const cur = dependentsIndex.cache;
+      const next = /* @__PURE__ */ new Map();
+      for (const [k, v] of cur) next.set(k, [...v]);
+      for (const src of deps) {
+        const bucket = next.get(src) ?? [];
+        if (!bucket.includes(f.id)) bucket.push(f.id);
+        next.set(src, bucket);
+      }
+      dependentsIndex.emit(next);
+    };
+    const factStore = (0, import_core2.node)(
+      shards,
+      (batchData, actions, ctx) => {
+        void batchData;
+        void ctx;
+        actions.emit({ byId: allFacts() });
+      },
+      {
+        name: "fact_store",
+        describeKind: "derived",
+        initial: emptyStore(),
+        meta: factMeta("factstore", { role: "read_view" }),
+        // F10a: `allFacts()` builds a fresh Map every detector retrigger.
+        // Fragments are immutable (replaced wholesale on mutation), so a
+        // same-size + per-key-identity check is a sound structural equality
+        // that stops `factStore` (and its `review` dependent) from re-firing
+        // every cascade wave when nothing actually changed.
+        equals: (a, b) => {
+          if (a === b) return true;
+          if (a.byId.size !== b.byId.size) return false;
+          for (const [k, v] of a.byId) {
+            if (b.byId.get(k) !== v) return false;
+          }
+          return true;
+        }
+      }
+    );
+    this.add(factStore, { name: "fact_store" });
+    this.addDisposer((0, import_extra2.keepalive)(factStore));
+    const extractOp = (0, import_core2.node)(
+      config.admissionFilter ? [config.ingest, config.admissionFilter] : [config.ingest],
+      (batchData, actions, ctx) => {
+        const f = lastOf(batchData[0], ctx.prevData[0]);
+        if (f == null) {
           actions.emit(null);
           return;
         }
-      }
-      const deps = config.extractDependencies(f);
-      cascadeIteration = 0;
-      processedRoots.delete(f.id);
-      commitFragment(f);
-      indexFragment(f, deps);
-      actions.emit(f);
-    },
-    {
-      name: "extract_op",
-      describeKind: "derived",
-      meta: factMeta("extract")
-    }
-  );
-  graph.add(extractOp, { name: "extract_op" });
-  graph.addDisposer((0, import_extra2.keepalive)(extractOp));
-  const invalidationDetector = (0, import_core2.node)(
-    [...shards],
-    (batchData, actions, ctx) => {
-      void batchData;
-      void ctx;
-      const facts = allFacts();
-      const index = dependentsIndex.cache;
-      const out2 = [];
-      const seen = /* @__PURE__ */ new Set();
-      for (const f of facts.values()) {
-        const obsolete = f.validTo !== void 0;
-        if (!obsolete) continue;
-        if (processedRoots.has(f.id)) continue;
-        const dependents = index.get(f.id) ?? [];
-        for (const dep of dependents) {
-          const depFact = facts.get(dep);
-          if (!depFact || depFact.validTo !== void 0) continue;
-          const k = `${f.id}->${dep}`;
-          if (seen.has(k)) continue;
-          seen.add(k);
-          out2.push({
-            factId: dep,
-            rootFactId: f.id,
-            reason: "obsolete",
-            // `obsolete` guard above guarantees `f.validTo` is set.
-            rootValidTo: f.validTo,
-            iteration: cascadeIteration + 1,
-            causalReason: `dependentsIndex[${f.id}] \u2192 ${dep} (obsolete: validTo set)`
-          });
+        if (config.admissionFilter) {
+          const filter = lastOf(batchData[1], ctx.prevData[1]);
+          if (filter && !filter(f)) {
+            actions.emit(null);
+            return;
+          }
         }
-        processedRoots.add(f.id);
-      }
-      if (out2.length === 0) {
+        const deps = config.extractDependencies(f);
         cascadeIteration = 0;
+        processedRoots.delete(f.id);
+        commitFragment(f);
+        indexFragment(f, deps);
+        actions.emit(f);
+      },
+      {
+        name: "extract_op",
+        describeKind: "derived",
+        meta: factMeta("extract")
       }
-      actions.emit(out2);
-    },
-    {
-      name: "invalidation_detector",
-      describeKind: "derived",
-      initial: [],
-      meta: factMeta("invalidation", { cycle: "cascade" })
-    }
-  );
-  graph.add(invalidationDetector, { name: "invalidation_detector" });
-  graph.addDisposer((0, import_extra2.keepalive)(invalidationDetector));
-  const cascade = (0, import_core2.node)(
-    [invalidationDetector],
-    (batchData, actions, ctx) => {
-      const evts = lastOf(batchData[0], ctx.prevData[0]) ?? [];
-      actions.emit(evts);
-    },
-    {
-      name: "cascade",
-      describeKind: "derived",
-      initial: [],
-      meta: factMeta("cascade_topic", { cycle: "cascade" })
-    }
-  );
-  graph.add(cascade, { name: "cascade" });
-  graph.addDisposer((0, import_extra2.keepalive)(cascade));
-  const cascadeOverflow = (0, import_core2.node)([], {
-    initial: null,
-    name: "cascade_overflow",
-    describeKind: "state",
-    meta: factMeta("cascade_overflow")
-  });
-  graph.add(cascadeOverflow, { name: "cascade_overflow" });
-  graph.addDisposer((0, import_extra2.keepalive)(cascadeOverflow));
-  const cascadeProcessor = (0, import_core2.node)(
-    [cascade],
-    (batchData, actions, ctx) => {
-      const evts = lastOf(batchData[0], ctx.prevData[0]) ?? [];
-      if (evts.length === 0) {
-        actions.emit([]);
-        return;
-      }
-      const byId = /* @__PURE__ */ new Map();
-      for (const e of evts) if (!byId.has(e.factId)) byId.set(e.factId, e);
-      cascadeIteration += 1;
-      if (cascadeIteration > maxIterations) {
-        const sample = [...byId.keys()].slice(0, OVERFLOW_SAMPLE_SIZE);
-        const rootFactId = evts[0]?.rootFactId ?? "";
-        cascadeOverflow.emit({
-          droppedCount: byId.size,
-          sample,
-          rootFactId
-        });
-        events.append({
-          action: "overflow",
-          reason: "cascade",
-          id: rootFactId,
-          t_ns: (0, import_core2.wallClockNs)(),
-          seq: bumpCursor(seqCursor)
-        });
-        actions.emit([]);
-        return;
-      }
-      for (const [id, e] of byId) {
-        replaceFragment(
-          id,
-          (prev) => prev.validTo !== void 0 ? prev : { ...prev, validTo: e.rootValidTo }
-        );
+    );
+    this.add(extractOp, { name: "extract_op" });
+    this.addDisposer((0, import_extra2.keepalive)(extractOp));
+    const invalidationDetector = (0, import_core2.node)(
+      [...shards],
+      (batchData, actions, ctx) => {
+        void batchData;
+        void ctx;
+        const facts = allFacts();
+        const index = dependentsIndex.cache;
+        const out = [];
+        const seen = /* @__PURE__ */ new Set();
+        for (const f of facts.values()) {
+          const obsolete = f.validTo !== void 0;
+          if (!obsolete) continue;
+          if (processedRoots.has(f.id)) continue;
+          const dependents = index.get(f.id) ?? [];
+          for (const dep of dependents) {
+            const depFact = facts.get(dep);
+            if (!depFact || depFact.validTo !== void 0) continue;
+            const k = `${f.id}->${dep}`;
+            if (seen.has(k)) continue;
+            seen.add(k);
+            out.push({
+              factId: dep,
+              rootFactId: f.id,
+              reason: "obsolete",
+              // `obsolete` guard above guarantees `f.validTo` is set.
+              rootValidTo: f.validTo,
+              iteration: cascadeIteration + 1,
+              causalReason: `dependentsIndex[${f.id}] \u2192 ${dep} (obsolete: validTo set)`
+            });
+          }
+          processedRoots.add(f.id);
+        }
+        if (out.length === 0) {
+          cascadeIteration = 0;
+        }
+        actions.emit(out);
+      },
+      {
+        name: "invalidation_detector",
+        describeKind: "derived",
+        initial: [],
+        meta: factMeta("invalidation", { cycle: "cascade" })
       }
-      actions.emit([...byId.values()]);
-    },
-    {
-      name: "cascade_processor",
-      describeKind: "derived",
-      initial: [],
-      meta: factMeta("cascade_processor", { cycle: "cascade" })
-    }
-  );
-  graph.add(cascadeProcessor, { name: "cascade_processor" });
-  graph.addDisposer((0, import_extra2.keepalive)(cascadeProcessor));
-  const review = (0, import_core2.node)(
-    [factStore],
-    (batchData, actions, ctx) => {
-      const fs = lastOf(batchData[0], ctx.prevData[0]);
-      if (fs == null) {
-        actions.emit(null);
-        return;
+    );
+    this.add(invalidationDetector, { name: "invalidation_detector" });
+    this.addDisposer((0, import_extra2.keepalive)(invalidationDetector));
+    const cascade = (0, import_core2.node)(
+      [invalidationDetector],
+      (batchData, actions, ctx) => {
+        const evts = lastOf(batchData[0], ctx.prevData[0]) ?? [];
+        actions.emit(evts);
+      },
+      {
+        name: "cascade",
+        describeKind: "derived",
+        initial: [],
+        meta: factMeta("cascade_topic", { cycle: "cascade" })
       }
-      for (const f of fs.byId.values()) {
-        if (f.confidence < reviewThreshold && f.validTo === void 0) {
-          actions.emit({
-            factId: f.id,
-            confidence: f.confidence,
-            threshold: reviewThreshold
+    );
+    this.add(cascade, { name: "cascade" });
+    this.addDisposer((0, import_extra2.keepalive)(cascade));
+    const cascadeOverflow = (0, import_core2.node)([], {
+      initial: null,
+      name: "cascade_overflow",
+      describeKind: "state",
+      meta: factMeta("cascade_overflow")
+    });
+    this.add(cascadeOverflow, { name: "cascade_overflow" });
+    this.addDisposer((0, import_extra2.keepalive)(cascadeOverflow));
+    const cascadeProcessor = (0, import_core2.node)(
+      [cascade],
+      (batchData, actions, ctx) => {
+        const evts = lastOf(batchData[0], ctx.prevData[0]) ?? [];
+        if (evts.length === 0) {
+          actions.emit([]);
+          return;
+        }
+        const byId = /* @__PURE__ */ new Map();
+        for (const e of evts) if (!byId.has(e.factId)) byId.set(e.factId, e);
+        cascadeIteration += 1;
+        if (cascadeIteration > maxIterations) {
+          const sample = [...byId.keys()].slice(0, OVERFLOW_SAMPLE_SIZE);
+          const rootFactId = evts[0]?.rootFactId ?? "";
+          cascadeOverflow.emit({
+            droppedCount: byId.size,
+            sample,
+            rootFactId
           });
+          events.append({
+            action: "overflow",
+            reason: "cascade",
+            id: rootFactId,
+            t_ns: (0, import_core2.wallClockNs)(),
+            seq: bumpCursor(seqCursor)
+          });
+          actions.emit([]);
           return;
         }
+        for (const [id, e] of byId) {
+          replaceFragment(
+            id,
+            (prev) => prev.validTo !== void 0 ? prev : { ...prev, validTo: e.rootValidTo }
+          );
+        }
+        actions.emit([...byId.values()]);
+      },
+      {
+        name: "cascade_processor",
+        describeKind: "derived",
+        initial: [],
+        meta: factMeta("cascade_processor", { cycle: "cascade" })
       }
-      actions.emit(null);
-    },
-    {
-      name: "review",
-      describeKind: "derived",
-      initial: null,
-      meta: factMeta("review"),
-      // F10a: dedupe on the requested factId (null === no request) so a
-      // stable low-confidence fact does not re-emit a review every wave.
-      equals: (a, b) => (a?.factId ?? null) === (b?.factId ?? null)
-    }
-  );
-  graph.add(review, { name: "review" });
-  graph.addDisposer((0, import_extra2.keepalive)(review));
-  if (config.outcome) {
-    const outcomeProcessor = (0, import_core2.node)(
-      config.scoring ? [config.outcome, config.scoring] : [config.outcome],
+    );
+    this.add(cascadeProcessor, { name: "cascade_processor" });
+    this.addDisposer((0, import_extra2.keepalive)(cascadeProcessor));
+    const review = (0, import_core2.node)(
+      [factStore],
       (batchData, actions, ctx) => {
-        const sig = lastOf(batchData[0], ctx.prevData[0]);
-        if (sig == null) {
+        const fs = lastOf(batchData[0], ctx.prevData[0]);
+        if (fs == null) {
           actions.emit(null);
           return;
         }
-        replaceFragment(sig.factId, (prev) => {
-          let nextConf = prev.confidence;
-          if (config.scoring) {
-            const policy2 = lastOf(batchData[1], ctx.prevData[1]);
-            if (policy2) {
-              nextConf = policy2(prev, makeReadHandle(allFacts()));
-            }
-          } else {
-            nextConf = Math.max(0, Math.min(1, prev.confidence + sig.reward));
+        for (const f of fs.byId.values()) {
+          if (f.confidence < reviewThreshold && f.validTo === void 0) {
+            actions.emit({
+              factId: f.id,
+              confidence: f.confidence,
+              threshold: reviewThreshold
+            });
+            return;
           }
-          return { ...prev, confidence: nextConf };
-        });
-        actions.emit(sig);
+        }
+        actions.emit(null);
       },
       {
-        name: "outcome_processor",
+        name: "review",
         describeKind: "derived",
         initial: null,
-        meta: factMeta("outcome")
+        meta: factMeta("review"),
+        // F10a: dedupe on the requested factId (null === no request) so a
+        // stable low-confidence fact does not re-emit a review every wave.
+        equals: (a, b) => (a?.factId ?? null) === (b?.factId ?? null)
       }
     );
-    graph.add(outcomeProcessor, { name: "outcome_processor" });
-    graph.addDisposer((0, import_extra2.keepalive)(outcomeProcessor));
-  }
-  const answer = (0, import_core2.node)(
-    config.query ? [config.query, factStore] : [factStore],
-    (batchData, actions, ctx) => {
-      if (!config.query) {
-        actions.emit(null);
-        return;
-      }
-      const q = lastOf(batchData[0], ctx.prevData[0]);
-      const fs = lastOf(batchData[1], ctx.prevData[1]);
-      if (q == null) {
-        actions.emit(null);
-        return;
-      }
-      const store = fs ?? emptyStore();
-      let results = [...store.byId.values()].filter((f) => {
-        if (q.tags && q.tags.length > 0 && !q.tags.some((t) => f.tags.includes(t))) {
-          return false;
+    this.add(review, { name: "review" });
+    this.addDisposer((0, import_extra2.keepalive)(review));
+    if (config.outcome) {
+      const outcomeProcessor = (0, import_core2.node)(
+        config.scoring ? [config.outcome, config.scoring] : [config.outcome],
+        (batchData, actions, ctx) => {
+          const sig = lastOf(batchData[0], ctx.prevData[0]);
+          if (sig == null) {
+            actions.emit(null);
+            return;
+          }
+          replaceFragment(sig.factId, (prev) => {
+            let nextConf = prev.confidence;
+            if (config.scoring) {
+              const policy2 = lastOf(batchData[1], ctx.prevData[1]);
+              if (policy2) {
+                nextConf = policy2(prev, makeReadHandle(allFacts()));
+              }
+            } else {
+              nextConf = Math.max(0, Math.min(1, prev.confidence + sig.reward));
+            }
+            return { ...prev, confidence: nextConf };
+          });
+          actions.emit(sig);
+        },
+        {
+          name: "outcome_processor",
+          describeKind: "derived",
+          initial: null,
+          meta: factMeta("outcome")
         }
-        if (q.minConfidence !== void 0 && f.confidence < q.minConfidence) return false;
-        if (!currentlyValid(f, q.asOf)) return false;
-        return true;
-      });
-      results.sort((a, b) => b.confidence - a.confidence || Number(b.t_ns - a.t_ns));
-      if (q.limit !== void 0) results = results.slice(0, Math.max(0, q.limit));
-      actions.emit({ query: q, results });
-    },
-    {
-      name: "answer",
-      describeKind: "derived",
-      initial: null,
-      meta: factMeta("query", { role: "output" })
+      );
+      this.add(outcomeProcessor, { name: "outcome_processor" });
+      this.addDisposer((0, import_extra2.keepalive)(outcomeProcessor));
     }
-  );
-  graph.add(answer, { name: "answer" });
-  graph.addDisposer((0, import_extra2.keepalive)(answer));
-  const consolidated = (0, import_core2.node)(
-    config.consolidateTrigger ? [config.consolidateTrigger] : [],
-    (batchData, actions, ctx) => {
-      void batchData;
-      void ctx;
-      if (!config.consolidateTrigger || !config.consolidate) {
-        actions.emit([]);
-        return;
-      }
-      const fragments = config.consolidate(makeReadHandle(allFacts()));
-      for (const f of fragments) {
-        const deps = config.extractDependencies(f);
-        processedRoots.delete(f.id);
-        commitFragment(f);
-        indexFragment(f, deps);
-        events.append({
-          action: "consolidate",
-          id: f.id,
-          t_ns: (0, import_core2.wallClockNs)(),
-          seq: bumpCursor(seqCursor)
+    const answer = (0, import_core2.node)(
+      config.query ? [config.query, factStore] : [factStore],
+      (batchData, actions, ctx) => {
+        if (!config.query) {
+          actions.emit(null);
+          return;
+        }
+        const q = lastOf(batchData[0], ctx.prevData[0]);
+        const fs = lastOf(batchData[1], ctx.prevData[1]);
+        if (q == null) {
+          actions.emit(null);
+          return;
+        }
+        const store = fs ?? emptyStore();
+        let results = [...store.byId.values()].filter((f) => {
+          if (q.tags && q.tags.length > 0 && !q.tags.some((t) => f.tags.includes(t))) {
+            return false;
+          }
+          if (q.minConfidence !== void 0 && f.confidence < q.minConfidence) return false;
+          if (!currentlyValid(f, q.asOf)) return false;
+          return true;
         });
+        results.sort((a, b) => b.confidence - a.confidence || Number(b.t_ns - a.t_ns));
+        if (q.limit !== void 0) results = results.slice(0, Math.max(0, q.limit));
+        actions.emit({ query: q, results });
+      },
+      {
+        name: "answer",
+        describeKind: "derived",
+        initial: null,
+        meta: factMeta("query", { role: "output" })
       }
-      actions.emit(fragments);
-    },
-    {
-      name: "consolidated",
-      describeKind: "derived",
-      initial: [],
-      meta: factMeta("consolidator")
-    }
-  );
-  graph.add(consolidated, { name: "consolidated" });
-  graph.addDisposer((0, import_extra2.keepalive)(consolidated));
-  if (config.decayTrigger) {
-    const decayProcessor = (0, import_core2.node)(
-      config.decay ? [config.decayTrigger, config.decay] : [config.decayTrigger],
+    );
+    this.add(answer, { name: "answer" });
+    this.addDisposer((0, import_extra2.keepalive)(answer));
+    const consolidated = (0, import_core2.node)(
+      config.consolidateTrigger ? [config.consolidateTrigger] : [],
       (batchData, actions, ctx) => {
-        const policy2 = config.decay ? lastOf(batchData[1], ctx.prevData[1]) : void 0;
-        if (!policy2) {
+        void batchData;
+        void ctx;
+        if (!config.consolidateTrigger || !config.consolidate) {
           actions.emit([]);
           return;
         }
-        const now = BigInt((0, import_core2.monotonicNs)());
-        const changes = [];
-        for (const f of allFacts().values()) {
-          if (f.validTo !== void 0) continue;
-          const ageNs = now - f.t_ns;
-          const raw = policy2(f.confidence, ageNs);
-          if (!Number.isFinite(raw)) continue;
-          const next = raw < 0 ? 0 : raw > 1 ? 1 : raw;
-          if (next === f.confidence) continue;
-          changes.push({ id: f.id, next });
+        const fragments = config.consolidate(makeReadHandle(allFacts()));
+        for (const f of fragments) {
+          const deps = config.extractDependencies(f);
+          processedRoots.delete(f.id);
+          commitFragment(f);
+          indexFragment(f, deps);
+          events.append({
+            action: "consolidate",
+            id: f.id,
+            t_ns: (0, import_core2.wallClockNs)(),
+            seq: bumpCursor(seqCursor)
+          });
         }
-        const decayed = [];
-        for (const { id, next } of changes) {
-          const idx = findShardOf(id);
-          const fs = idx < 0 ? void 0 : shards[idx].cache;
-          const live = fs?.byId.get(id);
-          if (!live || live.validTo !== void 0) continue;
-          replaceFragment(
-            id,
-            (prev) => prev.validTo !== void 0 ? prev : { ...prev, confidence: next }
-          );
-          decayed.push({ ...live, confidence: next });
+        actions.emit(fragments);
+      },
+      {
+        name: "consolidated",
+        describeKind: "derived",
+        initial: [],
+        // Inspection completeness (COMPOSITION-GUIDE §24 "make the
+        // invisible edge visible"): `consolidated` write-backs feed the
+        // bounded cascade store (commit → shard emit →
+        // `invalidationDetector`) exactly like `cascadeProcessor`, but
+        // is NOT a cascade-cycle node. `feeds:"cascade"` surfaces it as
+        // a cascade-store mutator in `describe()`/`explain()`;
+        // `drivesRoot:false` — by the consolidator contract successors
+        // are fresh live facts (no `validTo`), so on the contract path
+        // they do not root the cascade. (An out-of-contract `consolidate`
+        // that emits a `validTo`-set fragment WOULD root it via the
+        // detector — the tag reflects the documented contract, not a
+        // structural impossibility. Contrast `decay_processor` below,
+        // whose `drivesRoot:false` IS structurally provable.)
+        meta: factMeta("consolidator", { feeds: "cascade", drivesRoot: false })
+      }
+    );
+    this.add(consolidated, { name: "consolidated" });
+    this.addDisposer((0, import_extra2.keepalive)(consolidated));
+    if (config.decayTrigger) {
+      const decayProcessor = (0, import_core2.node)(
+        config.decay ? [config.decayTrigger, config.decay] : [config.decayTrigger],
+        (batchData, actions, ctx) => {
+          const policy2 = config.decay ? lastOf(batchData[1], ctx.prevData[1]) : void 0;
+          if (!policy2) {
+            actions.emit([]);
+            return;
+          }
+          const now = BigInt((0, import_core2.monotonicNs)());
+          const changes = [];
+          for (const f of allFacts().values()) {
+            if (f.validTo !== void 0) continue;
+            const ageNs = now - f.t_ns;
+            const raw = policy2(f.confidence, ageNs);
+            if (!Number.isFinite(raw)) continue;
+            const next = raw < 0 ? 0 : raw > 1 ? 1 : raw;
+            if (next === f.confidence) continue;
+            changes.push({ id: f.id, next });
+          }
+          const decayed = [];
+          for (const { id, next } of changes) {
+            const idx = findShardOf(id);
+            const fs = idx < 0 ? void 0 : shards[idx].cache;
+            const live = fs?.byId.get(id);
+            if (!live || live.validTo !== void 0) continue;
+            replaceFragment(
+              id,
+              (prev) => prev.validTo !== void 0 ? prev : { ...prev, confidence: next }
+            );
+            decayed.push({ ...live, confidence: next });
+          }
+          if (decayed.length > 0) {
+            events.append({
+              action: "decay",
+              t_ns: (0, import_core2.wallClockNs)(),
+              seq: bumpCursor(seqCursor),
+              count: decayed.length
+            });
+          }
+          actions.emit(decayed);
+        },
+        {
+          name: "decay_processor",
+          describeKind: "derived",
+          initial: [],
+          // Inspection completeness (same convention as `consolidated`
+          // above — kept uniform): `decay_processor` write-backs feed
+          // the cascade store via `replaceFragment` → shard emit →
+          // `invalidationDetector`. `feeds:"cascade"` surfaces it as a
+          // cascade-store mutator; `drivesRoot:false` — decay only
+          // mutates `confidence`, never `validTo`, and the detector
+          // roots on `validTo` only, so it provably cannot root.
+          meta: factMeta("decay", { feeds: "cascade", drivesRoot: false })
         }
-        if (decayed.length > 0) {
+      );
+      this.add(decayProcessor, { name: "decay_processor" });
+      this.addDisposer((0, import_extra2.keepalive)(decayProcessor));
+    }
+    const ingestAudit = (0, import_core2.node)(
+      [extractOp],
+      (batchData, actions, ctx) => {
+        const f = lastOf(batchData[0], ctx.prevData[0]);
+        if (f != null) {
           events.append({
-            action: "decay",
+            action: "ingest",
+            id: f.id,
             t_ns: (0, import_core2.wallClockNs)(),
             seq: bumpCursor(seqCursor)
           });
+          ingestLog?.append(f);
         }
-        actions.emit(decayed);
+        actions.emit(f ?? null);
       },
       {
-        name: "decay_processor",
+        name: "_ingest_audit",
         describeKind: "derived",
-        initial: [],
-        meta: factMeta("decay")
+        initial: null,
+        meta: factMeta("audit")
       }
     );
-    graph.add(decayProcessor, { name: "decay_processor" });
-    graph.addDisposer((0, import_extra2.keepalive)(decayProcessor));
+    this.add(ingestAudit, { name: "_ingest_audit" });
+    this.addDisposer((0, import_extra2.keepalive)(ingestAudit));
+    this.shards = shards;
+    this.factStore = factStore;
+    this.dependentsIndex = dependentsIndex;
+    this.answer = answer;
+    this.cascade = cascade;
+    this.cascadeOverflow = cascadeOverflow;
+    this.review = review;
+    this.consolidated = consolidated;
+    this.events = events;
+    if (ingestLog) this.ingestLog = ingestLog;
   }
-  const ingestAudit = (0, import_core2.node)(
-    [extractOp],
-    (batchData, actions, ctx) => {
-      const f = lastOf(batchData[0], ctx.prevData[0]);
-      if (f != null) {
-        events.append({
-          action: "ingest",
-          id: f.id,
-          t_ns: (0, import_core2.wallClockNs)(),
-          seq: bumpCursor(seqCursor)
-        });
-        ingestLog?.append(f);
-      }
-      actions.emit(f ?? null);
-    },
-    {
-      name: "_ingest_audit",
-      describeKind: "derived",
-      initial: null,
-      meta: factMeta("audit")
-    }
-  );
-  graph.add(ingestAudit, { name: "_ingest_audit" });
-  graph.addDisposer((0, import_extra2.keepalive)(ingestAudit));
-  function itemNode(id) {
+  // ── itemNode reactive read ───────────────────────────────────────────
+  /** Reactive read: a single fact by id (SENTINEL until the fact exists). */
+  itemNode(id) {
     return (0, import_core2.node)(
-      [factStore],
+      [this.factStore],
       (batchData, actions, ctx) => {
         const fs = lastOf(batchData[0], ctx.prevData[0]);
         actions.emit(fs?.byId.get(id));
@@ -726,20 +785,9 @@ function reactiveFactStore(config) {
       }
     );
   }
-  const out = Object.assign(graph, {
-    shards,
-    factStore,
-    dependentsIndex,
-    answer,
-    cascade,
-    cascadeOverflow,
-    review,
-    consolidated,
-    events,
-    ...ingestLog ? { ingestLog } : {},
-    itemNode
-  });
-  return out;
+};
+function reactiveFactStore(config) {
+  return new ReactiveFactStoreGraph(config);
 }
 
 // src/utils/memory/persistent-fact-store.ts
@@ -1158,14 +1206,60 @@ function shardByTenant(tenantOf, opts = {}) {
   return { shardBy: (f) => tenantOf(f), shardCount };
 }
 
+// src/utils/memory/simple-fact-store.ts
+var import_core10 = require("@graphrefly/pure-ts/core");
+var DEFAULT_DECAY_HALF_LIFE_NS = 604800000000000n;
+var DEFAULT_DECAY_PERIOD_MS = 36e5;
+function simpleFactStore(opts = {}) {
+  const ingest = (0, import_core10.node)([], { initial: void 0 });
+  const extractDependencies = opts.extractDependencies ?? (() => []);
+  const consolidationCfg = opts.consolidate ? consolidationRem(opts.consolidate) : void 0;
+  const baseCfg = {
+    ingest,
+    extractDependencies,
+    ...consolidationCfg ?? {}
+  };
+  const mem = opts.storage ? persistentReactiveFactStore({
+    ...baseCfg,
+    storage: opts.storage,
+    ...opts.persistName !== void 0 ? { persistName: opts.persistName } : {},
+    ...opts.codec !== void 0 ? { codec: opts.codec } : {}
+  }) : reactiveFactStore(baseCfg);
+  if (opts.decay !== false) {
+    const d = opts.decay ?? {};
+    decayExponential(mem, ingest, {
+      ...d,
+      halfLifeNs: d.halfLifeNs ?? DEFAULT_DECAY_HALF_LIFE_NS,
+      periodMs: d.periodMs ?? DEFAULT_DECAY_PERIOD_MS
+    });
+  }
+  const remember = (id, payload, ro) => {
+    const fragment = {
+      id,
+      payload,
+      t_ns: BigInt((0, import_core10.monotonicNs)()),
+      confidence: ro?.confidence ?? 1,
+      tags: ro?.tags ?? [],
+      sources: ro?.sources ?? [],
+      ...ro?.validTo !== void 0 ? { validTo: ro.validTo } : {},
+      ...ro?.validFrom !== void 0 ? { validFrom: ro.validFrom } : {},
+      ...ro?.provenance !== void 0 ? { provenance: ro.provenance } : {}
+    };
+    ingest.emit(fragment);
+  };
+  const out = mem;
+  out.remember = remember;
+  return out;
+}
+
 // src/utils/memory/index.ts
 var NS_PER_SEC = 1e9;
 function memoryMeta(kind, extra) {
   return domainMeta("memory", kind, extra);
 }
 function toNode(v, name) {
-  if (v instanceof import_core10.NodeImpl) return v;
-  return (0, import_core10.node)([], { initial: v, ...name ? { name } : void 0 });
+  if (v instanceof import_core11.NodeImpl) return v;
+  return (0, import_core11.node)([], { initial: v, ...name ? { name } : void 0 });
 }
 function ageSeconds(now, lastNs) {
   return (now - lastNs) / NS_PER_SEC;
@@ -1219,13 +1313,13 @@ function collection(name, opts = {}) {
   }
   const scoreFnDefault = () => ranked ? 1 : 0;
   const scoreInput = opts.score ?? scoreFnDefault;
-  const scoreNode = ranked && scoreInput instanceof import_core10.NodeImpl ? scoreInput : void 0;
+  const scoreNode = ranked && scoreInput instanceof import_core11.NodeImpl ? scoreInput : void 0;
   const readScoreFn = () => {
     if (scoreNode) return scoreNode.cache ?? scoreFnDefault;
     return scoreInput;
   };
   const graph = new import_graph3.Graph(name);
-  const retentionScore = (_k, v) => ranked ? decay(v.baseScore, ageSeconds((0, import_core10.monotonicNs)(), v.lastAccessNs), decayRate, minScore) : v.lastAccessNs;
+  const retentionScore = (_k, v) => ranked ? decay(v.baseScore, ageSeconds((0, import_core11.monotonicNs)(), v.lastAccessNs), decayRate, minScore) : v.lastAccessNs;
   const items = (0, import_extra8.reactiveMap)({
     name: "items",
     ...maxSize !== void 0 ? { retention: { score: retentionScore, maxSize } } : {}
@@ -1235,15 +1329,15 @@ function collection(name, opts = {}) {
   if (ranked && decayRate > 0) {
     const intervalMs = opts.refreshIntervalMs ?? Math.max(1, 1e3 * Math.LN2 / (10 * decayRate));
     const tickCounter = (0, import_extra8.fromTimer)(intervalMs, { period: intervalMs });
-    refreshTick = (0, import_core10.node)(
+    refreshTick = (0, import_core11.node)(
       [tickCounter],
       (_batchData, actions) => {
-        actions.emit((0, import_core10.monotonicNs)());
+        actions.emit((0, import_core11.monotonicNs)());
       },
       {
         name: "refresh_tick_ns",
         describeKind: "derived",
-        initial: (0, import_core10.monotonicNs)(),
+        initial: (0, import_core11.monotonicNs)(),
         meta: memoryMeta("clock")
       }
     );
@@ -1254,7 +1348,7 @@ function collection(name, opts = {}) {
     const rankedDeps = [items.entries];
     if (refreshTick) rankedDeps.push(refreshTick);
     if (scoreNode) rankedDeps.push(scoreNode);
-    rankedNode = (0, import_core10.node)(
+    rankedNode = (0, import_core11.node)(
       rankedDeps,
       (batchData, actions, ctx) => {
         const values = batchData.map(
@@ -1264,9 +1358,9 @@ function collection(name, opts = {}) {
         let now;
         if (refreshTick) {
           const tickValue = values[1];
-          now = typeof tickValue === "number" ? tickValue : (0, import_core10.monotonicNs)();
+          now = typeof tickValue === "number" ? tickValue : (0, import_core11.monotonicNs)();
         } else {
-          now = (0, import_core10.monotonicNs)();
+          now = (0, import_core11.monotonicNs)();
         }
         if (!snapshot || snapshot.size === 0) {
           actions.emit([]);
@@ -1291,7 +1385,7 @@ function collection(name, opts = {}) {
     );
     graph.add(rankedNode, { name: "ranked" });
   } else {
-    rankedNode = (0, import_core10.node)([], {
+    rankedNode = (0, import_core11.node)([], {
       initial: [],
       name: "ranked",
       describeKind: "state",
@@ -1299,7 +1393,7 @@ function collection(name, opts = {}) {
     });
     graph.add(rankedNode, { name: "ranked" });
   }
-  const size = (0, import_core10.node)(
+  const size = (0, import_core11.node)(
     [items.entries],
     (batchData, actions, ctx) => {
       const data = batchData.map(
@@ -1324,7 +1418,7 @@ function collection(name, opts = {}) {
   });
   const seqCursor = registerCursor(graph, "seq", 0);
   const upsertImpl = (id, value, _opts) => {
-    const now = (0, import_core10.monotonicNs)();
+    const now = (0, import_core11.monotonicNs)();
     const prev = items.get(id);
     const baseScore = _opts?.score ?? readScoreFn()(value);
     items.set(id, {
@@ -1380,7 +1474,7 @@ function collection(name, opts = {}) {
   });
   function itemNode(id) {
     const idN = toNode(id, "id");
-    return (0, import_core10.node)(
+    return (0, import_core11.node)(
       [items.entries, idN],
       (batchData, actions, ctx) => {
         const data = batchData.map(
@@ -1398,7 +1492,7 @@ function collection(name, opts = {}) {
   }
   function hasNode(id) {
     const idN = toNode(id, "id");
-    return (0, import_core10.node)(
+    return (0, import_core11.node)(
       [items.entries, idN],
       (batchData, actions, ctx) => {
         const data = batchData.map(
@@ -1485,7 +1579,7 @@ function vectorIndex(opts = {}) {
           events.append({
             action: "evict",
             id: key,
-            t_ns: (0, import_core10.wallClockNs)(),
+            t_ns: (0, import_core11.wallClockNs)(),
             seq: bumpCursor(seqCursor)
           });
         }
@@ -1510,7 +1604,7 @@ function vectorIndex(opts = {}) {
       id,
       vector: [...vector],
       ...copiedMeta !== void 0 ? { meta: copiedMeta } : {},
-      upsertedAtNs: (0, import_core10.monotonicNs)()
+      upsertedAtNs: (0, import_core11.monotonicNs)()
     };
     entries.set(id, record);
   };
@@ -1566,7 +1660,7 @@ function vectorIndex(opts = {}) {
   });
   function searchNode(query, k = 5) {
     const kN = toNode(k, "k");
-    return (0, import_core10.node)(
+    return (0, import_core11.node)(
       [entries.entries, query, kN],
       (batchData, actions, ctx) => {
         const values = batchData.map(
@@ -1682,7 +1776,7 @@ function knowledgeGraph(name, opts = {}) {
   });
   graph.add(entitiesMap.entries, { name: "entities" });
   graph.add(edgesMap.entries, { name: "edges" });
-  const adjacencyOut = (0, import_core10.node)(
+  const adjacencyOut = (0, import_core11.node)(
     [edgesMap.entries],
     (batchData, actions, ctx) => {
       const data = batchData.map(
@@ -1699,7 +1793,7 @@ function knowledgeGraph(name, opts = {}) {
       meta: memoryMeta("adjacency_out")
     }
   );
-  const adjacencyIn = (0, import_core10.node)(
+  const adjacencyIn = (0, import_core11.node)(
     [edgesMap.entries],
     (batchData, actions, ctx) => {
       const data = batchData.map(
@@ -1720,7 +1814,7 @@ function knowledgeGraph(name, opts = {}) {
   graph.add(adjacencyIn, { name: "adjacencyIn" });
   graph.addDisposer((0, import_extra8.keepalive)(adjacencyOut));
   graph.addDisposer((0, import_extra8.keepalive)(adjacencyIn));
-  const entityCount = (0, import_core10.node)(
+  const entityCount = (0, import_core11.node)(
     [entitiesMap.entries],
     (batchData, actions, ctx) => {
       const data = batchData.map(
@@ -1731,7 +1825,7 @@ function knowledgeGraph(name, opts = {}) {
     },
     { name: "entityCount", describeKind: "derived", initial: 0, meta: memoryMeta("entity_count") }
   );
-  const edgeCount = (0, import_core10.node)(
+  const edgeCount = (0, import_core11.node)(
     [edgesMap.entries],
     (batchData, actions, ctx) => {
       const data = batchData.map(
@@ -1768,7 +1862,7 @@ function knowledgeGraph(name, opts = {}) {
       events.append({
         action: "orphanRemove",
         id: candidate,
-        t_ns: (0, import_core10.wallClockNs)(),
+        t_ns: (0, import_core11.wallClockNs)(),
         seq: bumpCursor(seqCursor)
       });
     }
@@ -1863,7 +1957,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 (0, import_core10.node)(
+    return (0, import_core11.node)(
       deps,
       (batchData, actions, ctx) => {
         const values = batchData.map(