@remnic/core 9.50.2 → 9.51.0

package/src/contradiction/contradiction.test.ts

@@ -24,7 +24,7 @@ import { _pairKey, _contentHash } from "./contradiction-judge.js";
 import { executeResolution, isValidResolutionVerb } from "./resolution.js";
 import { ACTIVE_STATUSES, runContradictionScan } from "./contradiction-scan.js";
 import { parseConfig } from "../config.js";
-import type { StorageManager } from "../storage.js";
+import { StorageManager } from "../storage.js";
 import { sealedWriteToLegacyArgs, type SealedMemoryEnvelope } from "../write-envelope.js";
 import type { MemoryCategory, MemoryFile, MemoryFrontmatter } from "../types.js";
 
@@ -1780,6 +1780,91 @@ test("executeResolution merge supersedes both sources to a verified merged memor
   }
 });
 
+test("supersedeMemory chooses the canonically active cold duplicate over an archived hot duplicate", async () => {
+  const { dir, cleanup } = await makeTempDir("contradiction-storage-");
+  try {
+    const hotPath = path.join(dir, "facts", "duplicate-hot.md");
+    const coldPath = path.join(dir, "cold", "facts", "duplicate-cold.md");
+    const hotContent = `---
+id: duplicate-memory
+category: fact
+created: 2026-05-17T00:00:00.000Z
+updated: 2026-05-17T00:00:00.000Z
+status: active
+archivedAt: 2026-05-17T00:01:00.000Z
+---
+
+duplicate content
+`;
+    const coldContent = hotContent.replace("archivedAt: 2026-05-17T00:01:00.000Z\n", "");
+    await mkdir(path.dirname(hotPath), { recursive: true });
+    await mkdir(path.dirname(coldPath), { recursive: true });
+    await writeFile(hotPath, hotContent, "utf8");
+    await writeFile(coldPath, coldContent, "utf8");
+
+    const storage = new StorageManager(dir);
+    assert.equal(await storage.supersedeMemory("duplicate-memory", "replacement-memory", "regression"), true);
+
+    const hot = await storage.readMemoryByPath(hotPath);
+    const cold = await storage.readMemoryByPath(coldPath);
+    assert.equal(hot?.frontmatter.status, "active");
+    assert.equal(hot?.frontmatter.supersededBy, undefined);
+    assert.equal(cold?.frontmatter.status, "superseded");
+    assert.equal(cold?.frontmatter.supersededBy, "replacement-memory");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("supersedeMemory refuses a target that becomes archived before the locked write", async () => {
+  const { dir, cleanup } = await makeTempDir("contradiction-storage-race-");
+  try {
+    const memoryPath = path.join(dir, "facts", "race-memory.md");
+    const activeContent = `---
+id: race-memory
+category: fact
+created: 2026-05-17T00:00:00.000Z
+updated: 2026-05-17T00:00:00.000Z
+status: active
+---
+
+race content
+`;
+    const archivedContent = activeContent.replace(
+      "status: active\n",
+      "status: active\narchivedAt: 2026-05-17T00:01:00.000Z\n",
+    );
+    await mkdir(path.dirname(memoryPath), { recursive: true });
+    await writeFile(memoryPath, activeContent, "utf8");
+
+    const storage = new StorageManager(dir);
+    const privateStorage = storage as unknown as {
+      withTombstoneBlockedMemoryPathLock: <T>(
+        pathname: string,
+        task: (current: MemoryFile | null) => Promise<T>,
+      ) => Promise<T>;
+    };
+    const originalLock = privateStorage.withTombstoneBlockedMemoryPathLock;
+    privateStorage.withTombstoneBlockedMemoryPathLock = async (pathname, task) => {
+      await writeFile(pathname, archivedContent, "utf8");
+      return task(await storage.readMemoryByPath(pathname));
+    };
+
+    try {
+      assert.equal(await storage.supersedeMemory("race-memory", "replacement-memory", "race"), false);
+    } finally {
+      privateStorage.withTombstoneBlockedMemoryPathLock = originalLock;
+    }
+
+    const raced = await storage.readMemoryByPath(memoryPath);
+    assert.equal(raced?.frontmatter.status, "active");
+    assert.equal(raced?.frontmatter.archivedAt, "2026-05-17T00:01:00.000Z");
+    assert.equal(raced?.frontmatter.supersededBy, undefined);
+  } finally {
+    await cleanup();
+  }
+});
+
 test("executeResolution merge can create and verify a merged memory from content", async () => {
   const { dir, cleanup } = await makeTempDir();
   try {

package/src/contradiction-config.ts

@@ -0,0 +1,92 @@
+import { coerceBool, coerceNumber } from "./connectors/coerce.js";
+
+/** Configuration for the nightly contradiction-scan cron (issue #520). */
+export interface ContradictionScanConfig {
+  /** Master switch for the contradiction scan cron. Default true. */
+  enabled: boolean;
+  /** Embedding cosine similarity floor for candidate pair generation. Default 0.82. */
+  similarityFloor: number;
+  /** Minimum topic-token Jaccard overlap for unstructured pairs. Default 0.4. */
+  topicOverlapFloor: number;
+  /** Cap on candidate pairs evaluated per cron run. Default 500. */
+  maxPairsPerRun: number;
+  /** Cooldown in days before re-evaluating a pair judged independent/both-valid. Default 14. */
+  cooldownDays: number;
+  /** When true, pairs judged "duplicates" are auto-flagged for dedup (still need user approval). Default false. */
+  autoMergeDuplicates: boolean;
+}
+
+export interface ContradictionLocalizationConfig {
+  /** Enable the entity/category anchor pass before QMD search. */
+  anchorEnabled: boolean;
+  /** Maximum anchor candidates. Zero disables the anchor pass. */
+  anchorCandidates: number;
+  /** Maximum QMD search candidates. Zero disables text search. */
+  searchCandidates: number;
+  /** Maximum merged candidates passed to contradiction verification. */
+  maxCandidates: number;
+}
+
+export function parseContradictionScanConfig(raw: unknown): ContradictionScanConfig {
+  if (!raw || typeof raw !== "object") {
+    return {
+      enabled: false,
+      similarityFloor: 0.82,
+      topicOverlapFloor: 0.4,
+      maxPairsPerRun: 500,
+      cooldownDays: 14,
+      autoMergeDuplicates: false,
+    };
+  }
+  const src = raw as Record<string, unknown>;
+  const simFloor = coerceNumber(src.similarityFloor) ?? 0.82;
+  const topicFloor = coerceNumber(src.topicOverlapFloor) ?? 0.4;
+  const maxPairs = coerceNumber(src.maxPairsPerRun) ?? 500;
+  const cooldown = coerceNumber(src.cooldownDays) ?? 14;
+  return {
+    enabled: coerceBool(src.enabled) === true,
+    similarityFloor: Math.min(1, Math.max(0, simFloor)),
+    topicOverlapFloor: Math.min(1, Math.max(0, topicFloor)),
+    maxPairsPerRun: Math.max(1, maxPairs),
+    cooldownDays: Math.max(0, cooldown),
+    autoMergeDuplicates: coerceBool(src.autoMergeDuplicates) === true,
+  };
+}
+
+export function parseContradictionLocalizationConfig(raw: unknown): ContradictionLocalizationConfig {
+  const defaults: ContradictionLocalizationConfig = {
+    anchorEnabled: true,
+    anchorCandidates: 5,
+    searchCandidates: 5,
+    maxCandidates: 8,
+  };
+  if (raw === undefined || raw === null) return defaults;
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("contradictionLocalization must be an object");
+  }
+  const src = raw as Record<string, unknown>;
+  const rawEnabled = src.anchorEnabled;
+  const anchorEnabled = rawEnabled === undefined || rawEnabled === null ? true : coerceBool(rawEnabled);
+  if (anchorEnabled === undefined) {
+    throw new Error("contradictionLocalization.anchorEnabled must be a boolean-like value");
+  }
+
+  const parseCap = (
+    key: keyof Pick<ContradictionLocalizationConfig, "anchorCandidates" | "searchCandidates" | "maxCandidates">,
+  ): number => {
+    const rawValue = src[key];
+    if (rawValue === undefined) return defaults[key];
+    const parsed = coerceNumber(rawValue);
+    if (parsed === undefined || !Number.isInteger(parsed) || parsed < 0) {
+      throw new Error(`contradictionLocalization.${key} must be an integer >= 0`);
+    }
+    return parsed;
+  };
+
+  return {
+    anchorEnabled,
+    anchorCandidates: parseCap("anchorCandidates"),
+    searchCandidates: parseCap("searchCandidates"),
+    maxCandidates: parseCap("maxCandidates"),
+  };
+}

package/src/graph-path-reconstruction.ts

@@ -0,0 +1,91 @@
+import type { ActivationPath, GraphType } from "./graph.js";
+
+export interface ActivationPredecessor {
+  prev: string;
+  edgeConfidence: number;
+  graphType: GraphType;
+}
+
+export interface ActivationPathCandidate {
+  hopDepth: number;
+  landingStrength: number;
+  pathKey: string;
+}
+
+/** Compare path winners: fewer hops, stronger landing, then lexical path order. */
+export function compareActivationPathCandidates(
+  left: ActivationPathCandidate,
+  right: ActivationPathCandidate,
+): number {
+  if (left.hopDepth !== right.hopDepth) return right.hopDepth - left.hopDepth;
+  if (left.landingStrength !== right.landingStrength) return left.landingStrength - right.landingStrength;
+  if (left.pathKey === right.pathKey) return 0;
+  return left.pathKey < right.pathKey ? 1 : -1;
+}
+
+export class ActivationPathTracker {
+  readonly predecessors = new Map<string, ActivationPredecessor>();
+  private readonly winners = new Map<string, ActivationPathCandidate>();
+  private readonly pathKeys = new Map<string, string>();
+
+  constructor(seeds: Iterable<string>) {
+    for (const seed of seeds) {
+      this.pathKeys.set(`${seed}\0${seed}`, seed);
+    }
+  }
+
+  consider(
+    seed: string,
+    node: string,
+    neighbor: string,
+    hopDepth: number,
+    landingStrength: number,
+    edgeConfidence: number,
+    graphType: GraphType,
+  ): string {
+    const sourcePathKey = this.pathKeys.get(`${seed}\0${node}`);
+    if (!sourcePathKey) return "";
+
+    const key = `${seed}\0${neighbor}`;
+    const pathKey = `${sourcePathKey}\0${neighbor}`;
+    const candidate: ActivationPathCandidate = { hopDepth, landingStrength, pathKey };
+    const previous = this.winners.get(key);
+    if (!previous || compareActivationPathCandidates(candidate, previous) > 0) {
+      this.winners.set(key, candidate);
+      this.pathKeys.set(key, pathKey);
+      this.predecessors.set(key, { prev: node, edgeConfidence, graphType });
+    }
+    return pathKey;
+  }
+}
+export function reconstructActivationPath(
+  seed: string,
+  candidate: string,
+  predecessors: Map<string, ActivationPredecessor>,
+  maxSteps: number,
+): ActivationPath | null {
+  const nodeIds = [candidate];
+  const edgeConfidences: number[] = [];
+  const graphTypes: GraphType[] = [];
+  let current = candidate;
+  const stepCap = Number.isFinite(maxSteps)
+    ? Math.max(0, Math.ceil(maxSteps))
+    : predecessors.size + 1;
+  for (let step = 0; step < stepCap && current !== seed; step += 1) {
+    const predecessor = predecessors.get(`${seed}\0${current}`);
+    if (!predecessor) return null;
+    nodeIds.push(predecessor.prev);
+    edgeConfidences.push(predecessor.edgeConfidence);
+    graphTypes.push(predecessor.graphType);
+    current = predecessor.prev;
+  }
+
+  if (current !== seed) return null;
+  nodeIds.reverse();
+  edgeConfidences.reverse();
+  graphTypes.reverse();
+  if (edgeConfidences.length !== nodeIds.length - 1 || graphTypes.length !== nodeIds.length - 1) {
+    return null;
+  }
+  return { nodeIds, edgeConfidences, graphTypes };
+}

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

@@ -0,0 +1,55 @@
+import { coerceBool, coerceNumber } from "./connectors/coerce.js";
+
+export interface GraphPathScoringConfig {
+  enabled: boolean;
+  invalidNodePenalty: number;
+  includePathInProvenance: boolean;
+}
+
+function resolveBooleanConfig(value: unknown, defaultValue: boolean, keyName: string): boolean {
+  if (value === undefined || value === null) return defaultValue;
+  const coerced = coerceBool(value);
+  if (coerced === undefined) {
+    throw new Error(
+      `${keyName} must be a boolean-like value (true/false/1/0/yes/no/on/off); got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
+export function parseGraphPathScoringConfig(
+  cfg: Record<string, unknown> | undefined,
+): GraphPathScoringConfig {
+  if (cfg !== undefined && (typeof cfg !== "object" || Array.isArray(cfg))) {
+    throw new Error("graphPathScoring must be a plain object");
+  }
+  const block = cfg ?? {};
+  const invalidNodePenalty = coerceNumber(block.invalidNodePenalty);
+  if (
+    invalidNodePenalty === undefined ||
+    !Number.isFinite(invalidNodePenalty) ||
+    invalidNodePenalty <= 0 ||
+    invalidNodePenalty > 1
+  ) {
+    if (block.invalidNodePenalty !== undefined && block.invalidNodePenalty !== null) {
+      throw new Error(
+        `graphPathScoring.invalidNodePenalty must be a number in (0,1]; got ${JSON.stringify(block.invalidNodePenalty)}`,
+      );
+    }
+  }
+  return {
+    enabled: resolveBooleanConfig(block.enabled, false, "graphPathScoring.enabled"),
+    invalidNodePenalty:
+      invalidNodePenalty !== undefined &&
+      Number.isFinite(invalidNodePenalty) &&
+      invalidNodePenalty > 0 &&
+      invalidNodePenalty <= 1
+        ? invalidNodePenalty
+        : 0.2,
+    includePathInProvenance: resolveBooleanConfig(
+      block.includePathInProvenance,
+      true,
+      "graphPathScoring.includePathInProvenance",
+    ),
+  };
+}

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;
+}