@remnic/core 9.50.2 → 9.51.0

package/src/graph.test.ts

@@ -4,7 +4,15 @@ import os from "node:os";
 import path from "node:path";
 import test from "node:test";
 
-import { type GraphConfig, type GraphEdge, GraphIndex, graphFilePath, readEdges } from "./graph.js";
+import {
+  type ActivationPredecessor,
+  type GraphConfig,
+  type GraphEdge,
+  GraphIndex,
+  graphFilePath,
+  readEdges,
+  reconstructActivationPath,
+} from "./graph.js";
 
 function makeGraphConfig(): GraphConfig {
   return {
@@ -116,24 +124,236 @@ test("spreadingActivation propagates same-depth alternate path activation", asyn
     await rm(memoryDir, { recursive: true, force: true });
   }
 });
+test("spreadingActivation records seed-first paths with aligned edge metadata", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-graph-path-order-"));
+  try {
+    await writeGraphEdges(memoryDir, [makeEdge("seed", "middle", "entity", 0.8)]);
+    await writeGraphEdges(memoryDir, [makeEdge("middle", "candidate", "causal", 0.7)], "causal");
+
+    const graph = new GraphIndex(memoryDir, {
+      ...makeGraphConfig(),
+      causalGraphEnabled: true,
+      maxGraphTraversalSteps: 2,
+    });
+    const activated = await graph.spreadingActivation(["seed"], undefined, { recordPaths: true });
+
+    assert.deepEqual(activated.find((candidate) => candidate.path === "candidate")?.activationPath, {
+      nodeIds: ["seed", "middle", "candidate"],
+      edgeConfidences: [0.8, 0.7],
+      graphTypes: ["entity", "causal"],
+    });
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("spreadingActivation keeps the first shortest predecessor path", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-graph-path-shortest-"));
+  try {
+    await writeGraphEdges(memoryDir, [
+      makeEdge("seed", "long"),
+      makeEdge("seed", "short"),
+      makeEdge("long", "candidate"),
+      makeEdge("short", "candidate"),
+    ]);
+
+    const graph = new GraphIndex(memoryDir, { ...makeGraphConfig(), maxGraphTraversalSteps: 2 });
+    const activated = await graph.spreadingActivation(["seed"], undefined, { recordPaths: true });
+
+    assert.deepEqual(activated.find((candidate) => candidate.path === "candidate")?.activationPath, {
+      nodeIds: ["seed", "long", "candidate"],
+      edgeConfidences: [1, 1],
+      graphTypes: ["entity", "entity"],
+    });
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+test("spreadingActivation records the stronger equal-hop predecessor", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-graph-path-strength-"));
+  try {
+    await writeGraphEdges(memoryDir, [
+      makeEdge("seed", "weak"),
+      makeEdge("seed", "strong"),
+      makeEdge("weak", "candidate", "entity", 0.4),
+      makeEdge("strong", "candidate", "entity", 0.9),
+    ]);
+
+    const graph = new GraphIndex(memoryDir, { ...makeGraphConfig(), maxGraphTraversalSteps: 2 });
+    const activated = await graph.spreadingActivation(["seed"], undefined, { recordPaths: true });
+
+    assert.deepEqual(activated.find((candidate) => candidate.path === "candidate")?.activationPath, {
+      nodeIds: ["seed", "strong", "candidate"],
+      edgeConfidences: [1, 0.9],
+      graphTypes: ["entity", "entity"],
+    });
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("spreadingActivation uses a lexical predecessor tie-break", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-graph-path-lexical-"));
+  try {
+    await writeGraphEdges(memoryDir, [
+      makeEdge("seed", "zulu"),
+      makeEdge("seed", "alpha"),
+      makeEdge("zulu", "candidate"),
+      makeEdge("alpha", "candidate"),
+    ]);
+
+    const graph = new GraphIndex(memoryDir, { ...makeGraphConfig(), maxGraphTraversalSteps: 2 });
+    const activated = await graph.spreadingActivation(["seed"], undefined, { recordPaths: true });
+
+    assert.deepEqual(activated.find((candidate) => candidate.path === "candidate")?.activationPath, {
+      nodeIds: ["seed", "alpha", "candidate"],
+      edgeConfidences: [1, 1],
+      graphTypes: ["entity", "entity"],
+    });
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
 
-function makeEdge(from: string, to: string): GraphEdge {
+test("spreadingActivation keeps predecessor paths isolated per seed", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-graph-path-seeds-"));
+  try {
+    await writeGraphEdges(memoryDir, [
+      makeEdge("seed-a", "middle-a"),
+      makeEdge("seed-b", "middle-b"),
+      makeEdge("middle-a", "shared"),
+      makeEdge("middle-b", "shared"),
+    ]);
+
+    const graph = new GraphIndex(memoryDir, { ...makeGraphConfig(), maxGraphTraversalSteps: 2 });
+    const activated = await graph.spreadingActivation(["seed-a", "seed-b"], undefined, { recordPaths: true });
+
+    assert.deepEqual(activated.find((candidate) => candidate.path === "shared")?.activationPath, {
+      nodeIds: ["seed-a", "middle-a", "shared"],
+      edgeConfidences: [1, 1],
+      graphTypes: ["entity", "entity"],
+    });
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("spreadingActivation reconstructs bounded paths through cycles without looping", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-graph-path-cycle-"));
+  try {
+    await writeGraphEdges(memoryDir, [
+      makeEdge("seed", "a"),
+      makeEdge("a", "b"),
+      makeEdge("b", "a"),
+      makeEdge("b", "candidate"),
+    ]);
+
+    const graph = new GraphIndex(memoryDir, { ...makeGraphConfig(), maxGraphTraversalSteps: 3 });
+    const activated = await graph.spreadingActivation(["seed"], undefined, { recordPaths: true });
+    const candidatePath = activated.find((candidate) => candidate.path === "candidate")?.activationPath;
+
+    assert.deepEqual(candidatePath, {
+      nodeIds: ["seed", "a", "b", "candidate"],
+      edgeConfidences: [1, 1, 1],
+      graphTypes: ["entity", "entity", "entity"],
+    });
+    assert.ok(activated.every((candidate) => (candidate.activationPath?.nodeIds.length ?? 0) <= 4));
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("spreadingActivation path recording is deterministic and opt-in output stays unchanged", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-graph-path-determinism-"));
+  try {
+    await writeGraphEdges(memoryDir, [
+      makeEdge("seed", "left"),
+      makeEdge("seed", "right"),
+      makeEdge("left", "candidate"),
+      makeEdge("right", "candidate"),
+    ]);
+
+    const graph = new GraphIndex(memoryDir, { ...makeGraphConfig(), maxGraphTraversalSteps: 2 });
+    const baseline = await graph.spreadingActivation(["seed"]);
+    const explicitDisabled = await graph.spreadingActivation(["seed"], undefined, { recordPaths: false });
+    const first = await graph.spreadingActivation(["seed"], undefined, { recordPaths: true });
+    const second = await graph.spreadingActivation(["seed"], undefined, { recordPaths: true });
+
+    assert.deepEqual(explicitDisabled, baseline);
+    assert.ok(baseline.every((candidate) => !("activationPath" in candidate)));
+    assert.deepEqual(second, first);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("reconstructActivationPath returns a zero-hop path for a seed candidate", () => {
+  assert.deepEqual(reconstructActivationPath("seed", "seed", new Map(), 0), {
+    nodeIds: ["seed"],
+    edgeConfidences: [],
+    graphTypes: [],
+  });
+});
+
+test("reconstructActivationPath fails closed when a predecessor is missing", () => {
+  const predecessors = new Map<string, ActivationPredecessor>([
+    [
+      "seed\0candidate",
+      { prev: "middle", edgeConfidence: 0.8, graphType: "entity" },
+    ],
+  ]);
+
+  assert.equal(reconstructActivationPath("seed", "candidate", predecessors, 2), null);
+});
+
+test("reconstructActivationPath fails closed on a cycle beyond the step cap", () => {
+  const predecessors = new Map<string, ActivationPredecessor>([
+    [
+      "seed\0candidate",
+      { prev: "cycle-a", edgeConfidence: 0.8, graphType: "entity" },
+    ],
+    [
+      "seed\0cycle-a",
+      { prev: "cycle-b", edgeConfidence: 0.7, graphType: "time" },
+    ],
+    [
+      "seed\0cycle-b",
+      { prev: "cycle-a", edgeConfidence: 0.6, graphType: "causal" },
+    ],
+  ]);
+
+  assert.equal(reconstructActivationPath("seed", "candidate", predecessors, 4), null);
+});
+
+function makeEdge(
+  from: string,
+  to: string,
+  type: GraphEdge["type"] = "entity",
+  confidence?: number,
+): GraphEdge {
   return {
     from,
     to,
-    type: "entity",
+    type,
     weight: 1,
+    ...(confidence === undefined ? {} : { confidence }),
     label: "test",
     ts: "2026-01-01T00:00:00.000Z",
   };
 }
 
-async function writeGraphEdges(memoryDir: string, edges: GraphEdge[]): Promise<void> {
-  const filePath = graphFilePath(memoryDir, "entity");
+async function writeGraphEdges(
+  memoryDir: string,
+  edges: GraphEdge[],
+  type: GraphEdge["type"] = "entity",
+): Promise<void> {
+  const filePath = graphFilePath(memoryDir, type);
   await mkdir(path.dirname(filePath), { recursive: true });
   await writeFile(filePath, `${edges.map((edge) => JSON.stringify(edge)).join("\n")}\n`, "utf-8");
 }
 
+
 // ---------------------------------------------------------------------------
 // Incremental edge cache (issue #1904). onMemoryWritten pushes single-writer
 // appends into the warm cache in place and reloads only on a peer append.

package/src/graph.ts

@@ -16,9 +16,26 @@ import * as path from "node:path";
 import { readEdgeConfidence } from "./graph-edge-reinforcement.js";
 import { emitGraphEvent } from "./graph-events.js";
 import type { GraphConstructionCapabilitySet } from "./capabilities.js";
+import {
+  ActivationPathTracker,
+  compareActivationPathCandidates,
+  reconstructActivationPath,
+  type ActivationPathCandidate,
+  type ActivationPredecessor,
+} from "./graph-path-reconstruction.js";
+export { reconstructActivationPath, type ActivationPredecessor };
 
 export type GraphType = "entity" | "time" | "causal";
 
+export interface ActivationPath {
+  /** Node ids from the seed (inclusive) to the reached node (inclusive). */
+  nodeIds: string[];
+  /** Edge confidences, parallel to the hops in {@link nodeIds}. */
+  edgeConfidences: number[];
+  /** Graph types, parallel to the hops in {@link nodeIds}. */
+  graphTypes: GraphType[];
+}
+
 export interface GraphEdge {
   from: string; // relative memory path (e.g. "facts/2026-02-22/abc.md")
   to: string; // relative memory path
@@ -791,6 +808,8 @@ export class GraphIndex {
        * Default `false` (floor from config is applied).
        */
       includeLowConfidence?: boolean;
+      /** Record one shortest seed-to-candidate path in each result. */
+      recordPaths?: boolean;
       /** Absolute deadline in ms-since-epoch for post-retrieval assembly. */
       deadlineAtMs?: number;
     }
@@ -808,6 +827,7 @@ export class GraphIndex {
        * In `[0, 1]`. Legacy edges without `confidence` surface as 1.0.
        */
       edgeConfidence: number;
+      activationPath?: ActivationPath | null;
     }>
   > {
     if (!this.cfg.multiGraphMemoryEnabled) return [];
@@ -821,6 +841,7 @@ export class GraphIndex {
     const floor =
       opts?.includeLowConfidence === true ? 0 : clampConfidenceFloor(this.cfg.graphTraversalConfidenceFloor);
     const iterations = clampPageRankIterations(this.cfg.graphTraversalPageRankIterations);
+    const recordPaths = opts?.recordPaths === true;
     const deadlineAtMs = opts?.deadlineAtMs;
     const deadlineExpired = (): boolean =>
       typeof deadlineAtMs === "number" && Date.now() >= deadlineAtMs;
@@ -847,9 +868,9 @@ export class GraphIndex {
           adj.get(edge.to)!.push({ ...edge, from: edge.to, to: edge.from });
         }
       }
-
       const seedSet = new Set(seeds);
       const scores = new Map<string, number>(); // candidate path → accumulated activation score
+
       const provenance = new Map<
         string,
         {
@@ -858,16 +879,19 @@ export class GraphIndex {
           decayedWeight: number;
           graphType: "entity" | "time" | "causal";
           edgeConfidence: number;
+          pathKey: string;
         }
       >();
       let frontier = new Map<string, { node: string; seed: string; activation: number }>();
       const reachedBySeed = new Map<string, Set<string>>();
+      const pathTracker = recordPaths ? new ActivationPathTracker(seeds) : null;
+      const predecessors = pathTracker?.predecessors ?? null;
       for (const seed of seeds) {
         frontier.set(`${seed}\0${seed}`, { node: seed, seed, activation: 1 });
         reachedBySeed.set(seed, new Set([seed]));
       }
-      const finalizeScores = () =>
-        Array.from(scores.entries())
+      const finalizeScores = () => {
+        const results = Array.from(scores.entries())
           .map(([p, score]) => ({
             path: p,
             score,
@@ -877,7 +901,21 @@ export class GraphIndex {
             graphType: provenance.get(p)?.graphType ?? "entity",
             edgeConfidence: provenance.get(p)?.edgeConfidence ?? 1,
           }))
-          .sort((a, b) => b.score - a.score);
+          .sort((a, b) => {
+            const scoreDelta = b.score - a.score;
+            if (scoreDelta !== 0 || !recordPaths) return scoreDelta;
+            return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+          });
+        if (!recordPaths || !predecessors) return results;
+        return results.map((result) => {
+          const seed = provenance.get(result.path)?.seed;
+          return {
+            ...result,
+            activationPath:
+              seed === undefined ? null : reconstructActivationPath(seed, result.path, predecessors, steps),
+          };
+        });
+      };
 
       for (let hop = 0; hop < steps && frontier.size > 0; hop++) {
         if (deadlineExpired()) return finalizeScores();
@@ -899,22 +937,51 @@ export class GraphIndex {
             if (reachedForSeed?.has(neighbor)) {
               continue;
             }
+            const candidatePathKey =
+              pathTracker && !seedSet.has(neighbor)
+                ? pathTracker.consider(
+                    sourceSeed,
+                    node,
+                    neighbor,
+                    hop + 1,
+                    score,
+                    conf,
+                    edge.type,
+                  )
+                : "";
 
             if (!seedSet.has(neighbor)) {
               const existing = scores.get(neighbor) ?? 0;
               scores.set(neighbor, existing + score);
 
               const prev = provenance.get(neighbor);
-              if (!prev || hop + 1 < prev.hopDepth || (hop + 1 === prev.hopDepth && score > prev.decayedWeight)) {
+              const candidateWinner: ActivationPathCandidate = {
+                hopDepth: hop + 1,
+                landingStrength: score,
+                pathKey: candidatePathKey,
+              };
+              const shouldReplace =
+                !prev ||
+                (recordPaths
+                  ? compareActivationPathCandidates(candidateWinner, {
+                      hopDepth: prev.hopDepth,
+                      landingStrength: prev.decayedWeight,
+                      pathKey: prev.pathKey,
+                    }) > 0
+                  : hop + 1 < prev.hopDepth ||
+                    (hop + 1 === prev.hopDepth && score > prev.decayedWeight));
+              if (shouldReplace) {
                 provenance.set(neighbor, {
                   seed: sourceSeed,
                   hopDepth: hop + 1,
                   decayedWeight: score,
                   graphType: edge.type,
                   edgeConfidence: conf,
+                  pathKey: candidatePathKey,
                 });
               }
 
+
               if (hop + 1 < steps) {
                 const frontierKey = `${sourceSeed}\0${neighbor}`;
                 const existingFrontier = nextFrontier.get(frontierKey);