@remnic/core 9.50.3 → 9.51.1

package/src/graph-path-scoring.test.ts

@@ -0,0 +1,238 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import type { ActivationPath } from "./graph.js";
+import { scoreEvidencePath, type PathNodeState, type PathScoringOptions } from "./graph-path-scoring.js";
+
+const activationPath = (nodeIds: string[], edgeConfidences: number[]): ActivationPath => ({
+  nodeIds,
+  edgeConfidences,
+  graphTypes: edgeConfidences.map(() => "entity"),
+});
+
+const state = (
+  id: string,
+  status: PathNodeState["status"] = "active",
+  invalidAt: string | null = null,
+  temporal: Record<string, string | null | undefined> = {},
+): PathNodeState => ({
+  id,
+  status,
+  created: "2025-01-01T00:00:00.000Z",
+  ...(invalidAt !== null ? { invalid_at: invalidAt } : {}),
+  ...temporal,
+});
+
+const score = (
+  evidencePath: ActivationPath | null,
+  states: ReadonlyMap<string, PathNodeState>,
+  options: Partial<PathScoringOptions> = {},
+): number =>
+  scoreEvidencePath(evidencePath, states, {
+    asOf: "2026-01-01T00:00:00.000Z",
+    invalidNodePenalty: 0.2,
+    ...options,
+  });
+
+test("scores the edge confidence product across a clean path", () => {
+  assert.equal(score(activationPath(["seed", "mid", "candidate"], [0.8, 0.5]), new Map()), 0.4);
+});
+
+test("penalizes one invalid intermediate memory", () => {
+  const states = new Map([["mid", state("mid", "superseded")]]);
+  assert.equal(
+    score(activationPath(["seed", "mid", "candidate"], [0.8, 0.5]), states),
+    0.8 * 0.5 * 0.2,
+  );
+});
+
+test("squares the penalty for two invalid intermediate memories", () => {
+  const states = new Map([
+    ["mid", state("mid", "superseded")],
+    ["mid-2", state("mid-2", "active", "2025-01-01T00:00:00.000Z")],
+  ]);
+  assert.equal(
+    score(activationPath(["seed", "mid", "mid-2", "candidate"], [0.8, 0.5, 0.25]), states),
+    0.8 * 0.5 * 0.25 * 0.2 * 0.2,
+  );
+});
+
+test("ignores seed and candidate state", () => {
+  const states = new Map([
+    ["seed", state("seed", "rejected", "2025-01-01T00:00:00.000Z")],
+    ["candidate", state("candidate", "archived", "2025-01-01T00:00:00.000Z")],
+  ]);
+  assert.equal(score(activationPath(["seed", "candidate"], [0.7]), states), 0.7);
+});
+
+test("treats null status as neutral even with invalidAt", () => {
+ const states = new Map([
+ ["entity-mid", state("entity-mid", null, "2020-01-01T00:00:00.000Z")],
+ ]);
+ assert.equal(
+ score(activationPath(["seed", "entity-mid", "candidate"], [0.7, 0.6]), states),
+ 0.7 * 0.6,
+ );
+});
+test("treats malformed invalidAt as neutral", () => {
+  const states = new Map([
+    ["entity-mid", state("entity-mid", "superseded", "not-a-date")],
+  ]);
+  assert.equal(
+    score(activationPath(["seed", "entity-mid", "candidate"], [0.7, 0.6]), states),
+    0.7 * 0.6,
+  );
+});
+
+test("treats an unknown intermediate id as neutral", () => {
+  assert.equal(
+    score(activationPath(["seed", "unknown", "candidate"], [0.7, 0.6]), new Map()),
+    0.7 * 0.6,
+  );
+});
+
+test("treats invalidAt equal to asOf as invalid", () => {
+  const states = new Map([
+    ["boundary", state("boundary", "active", "2026-01-01T00:00:00.000Z")],
+  ]);
+  assert.equal(
+    score(activationPath(["seed", "boundary", "candidate"], [1, 1]), states),
+    0.2,
+  );
+});
+
+test("treats a future invalidAt as valid", () => {
+  const states = new Map([
+    ["future", state("future", "active", "2026-01-02T00:00:00.000Z")],
+  ]);
+  assert.equal(
+    score(activationPath(["seed", "future", "candidate"], [1, 1]), states),
+    1,
+  );
+});
+test("penalizes inactive intermediate nodes with a future invalidAt", () => {
+  for (const status of ["rejected", "quarantined", "pending_review", "archived", "forgotten"] as const) {
+    const states = new Map([
+      [status, state(status, status, "2026-01-02T00:00:00.000Z")],
+    ]);
+    assert.equal(
+      score(activationPath(["seed", status, "candidate"], [1, 1]), states),
+      0.2,
+      `${status} intermediate node must remain invalid before invalidAt`,
+    );
+  }
+});
+
+test("keeps penalty one as a no-op", () => {
+  const states = new Map([["mid", state("mid", "rejected")]]);
+  assert.equal(
+    score(activationPath(["seed", "mid", "candidate"], [0.8, 0.5]), states, {
+      invalidNodePenalty: 1,
+    }),
+    0.8 * 0.5,
+  );
+});
+
+test("returns one for a missing path", () => {
+  assert.equal(score(null, new Map()), 1);
+});
+test("reports path penalty only for invalid intermediate state", async () => {
+  const { scoreEvidencePathDetail } = await import("./graph-path-scoring.js");
+  const validDetail = scoreEvidencePathDetail(
+    activationPath(["seed", "mid", "candidate"], [0.2, 0.3]),
+    new Map([["mid", state("mid", "active")]]),
+    {
+      asOf: "2026-01-01T00:00:00.000Z",
+      invalidNodePenalty: 0.2,
+    },
+  );
+  assert.equal(validDetail.score, 0.2 * 0.3);
+  assert.equal(validDetail.pathPenaltyApplied, false);
+
+  const invalidDetail = scoreEvidencePathDetail(
+    activationPath(["seed", "mid", "candidate"], [1, 1]),
+    new Map([["mid", state("mid", "superseded")]]),
+    {
+      asOf: "2026-01-01T00:00:00.000Z",
+      invalidNodePenalty: 0.2,
+    },
+  );
+  assert.equal(invalidDetail.pathPenaltyApplied, true);
+});
+
+test("uses invalidAt for historical supersession validity", () => {
+  const states = new Map([
+    ["mid", state("mid", "superseded", "2026-02-01T00:00:00.000Z")],
+  ]);
+  assert.equal(
+    score(
+      activationPath(["seed", "mid", "candidate"], [1, 1]),
+      states,
+      { asOf: "2026-01-01T00:00:00.000Z" },
+    ),
+    1,
+  );
+  assert.equal(
+    score(
+      activationPath(["seed", "mid", "candidate"], [1, 1]),
+      states,
+      { asOf: "2026-03-01T00:00:00.000Z" },
+    ),
+    0.2,
+  );
+});
+
+test("penalizes an active intermediate that begins after historical asOf", () => {
+  const states = new Map([
+    [
+      "mid",
+      state("mid", "active", null, {
+        valid_at: "2026-02-01T00:00:00.000Z",
+        created: "2026-02-01T00:00:00.000Z",
+      }),
+    ],
+  ]);
+  assert.equal(
+    score(
+      activationPath(["seed", "mid", "candidate"], [1, 1]),
+      states,
+      { asOf: "2026-01-01T00:00:00.000Z" },
+    ),
+    0.2,
+  );
+});
+
+test("uses legacy supersededAt as the historical end bound", () => {
+  const states = new Map([
+    [
+      "mid",
+      state("mid", "superseded", null, {
+        created: "2025-01-01T00:00:00.000Z",
+        supersededAt: "2026-02-01T00:00:00.000Z",
+      }),
+    ],
+  ]);
+  const path = activationPath(["seed", "mid", "candidate"], [1, 1]);
+  assert.equal(score(path, states, { asOf: "2026-01-01T00:00:00.000Z" }), 1);
+  assert.equal(score(path, states, { asOf: "2026-03-01T00:00:00.000Z" }), 0.2);
+});
+
+test("rejects a non-finite asOf", () => {
+  assert.throws(
+    () =>
+      score(
+        activationPath(["seed", "mid", "candidate"], [1, 1]),
+        new Map(),
+        { asOf: "not-a-date" },
+      ),
+    /asOf must be a finite timestamp/,
+  );
+  assert.throws(
+    () =>
+      scoreEvidencePath(
+        null,
+        new Map(),
+        { asOf: "not-a-date", invalidNodePenalty: 0.2 },
+      ),
+    /asOf must be a finite timestamp/,
+  );
+});

package/src/graph-path-scoring.ts

@@ -0,0 +1,77 @@
+import type { ActivationPath } from "./graph.js";
+import type { MemoryFrontmatter, MemoryStatus } from "./types.js";
+import { isValidAsOf } from "./temporal-validity.js";
+
+/** Memory state used to score an intermediate path node. */
+export interface PathNodeState
+  extends Pick<
+    MemoryFrontmatter,
+    "valid_at" | "invalid_at" | "created" | "supersededAt" | "eventTimeSource"
+  > {
+  id: string;
+  status: MemoryStatus | null;
+}
+
+/** Configuration for graph-path evidence scoring. */
+export interface PathScoringOptions {
+  asOf: string;
+  invalidNodePenalty: number;
+}
+
+function isInvalidIntermediate(state: PathNodeState | undefined, asOfMs: number): boolean {
+  if (!state || state.status === null) return false;
+  if (!isValidAsOf({ ...state, status: state.status }, asOfMs)) return true;
+
+  const hasSupersessionEnd =
+    state.status === "superseded" &&
+    ((state.invalid_at?.trim().length ?? 0) > 0 ||
+      (state.supersededAt?.trim().length ?? 0) > 0);
+  return state.status !== "active" && !hasSupersessionEnd;
+}
+
+export interface PathScoreDetail {
+  score: number;
+  pathPenaltyApplied: boolean;
+}
+
+export function scoreEvidencePathDetail(
+  evidencePath: ActivationPath | null,
+  nodeStates: ReadonlyMap<string, PathNodeState>,
+  options: PathScoringOptions,
+): PathScoreDetail {
+  const asOfMs = Date.parse(options.asOf);
+  if (!Number.isFinite(asOfMs)) {
+    throw new Error("asOf must be a finite timestamp");
+  }
+  if (!evidencePath) return { score: 1, pathPenaltyApplied: false };
+  let multiplier = evidencePath.edgeConfidences.reduce(
+    (product, confidence) => product * confidence,
+    1,
+  );
+  let invalidIntermediateCount = 0;
+  for (const nodeId of evidencePath.nodeIds.slice(1, -1)) {
+    if (isInvalidIntermediate(nodeStates.get(nodeId), asOfMs)) {
+      invalidIntermediateCount += 1;
+      multiplier *= options.invalidNodePenalty;
+    }
+  }
+  return {
+    score: multiplier,
+    pathPenaltyApplied: invalidIntermediateCount > 0 && options.invalidNodePenalty !== 1,
+  };
+}
+
+/**
+ * Return the multiplicative evidence factor for one graph activation path.
+ *
+ * Edge confidence is multiplied for every hop. Invalid intermediate memories
+ * receive the configured penalty once each. Seed and candidate states do not
+ * affect the result because the caller already scored those memories.
+ */
+export function scoreEvidencePath(
+  evidencePath: ActivationPath | null,
+  nodeStates: ReadonlyMap<string, PathNodeState>,
+  options: PathScoringOptions,
+): number {
+  return scoreEvidencePathDetail(evidencePath, nodeStates, options).score;
+}

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.