@remnic/core 9.50.3 → 9.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.50.3",
+  "version": "9.51.0",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3126,7 +3126,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.50.3"
+    "@remnic/coding-graph": "^9.51.0"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/archive-mutation-version.ts

@@ -0,0 +1,59 @@
+import { appendFileSync, mkdirSync, statSync } from "node:fs";
+import path from "node:path";
+
+const ARCHIVE_MUTATION_VERSION_SENTINEL = ".archive-mutation-version.log";
+const fallbackVersionByDir = new Map<string, number>();
+
+export function getArchiveMutationVersionForDir(memoryDir: string): number {
+  try {
+    return statSync(path.join(memoryDir, "state", ARCHIVE_MUTATION_VERSION_SENTINEL)).size;
+  } catch {
+    return fallbackVersionByDir.get(memoryDir) ?? 0;
+  }
+}
+
+export function bumpArchiveMutationVersionForDir(memoryDir: string): void {
+  const filePath = path.join(memoryDir, "state", ARCHIVE_MUTATION_VERSION_SENTINEL);
+  try {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    appendFileSync(filePath, "x");
+    fallbackVersionByDir.set(memoryDir, statSync(filePath).size);
+  } catch {
+    fallbackVersionByDir.set(memoryDir, (fallbackVersionByDir.get(memoryDir) ?? 0) + 1);
+  }
+}
+
+export function bumpArchiveMutationIfChanged(memoryDir: string, changed: boolean): void {
+  if (changed) bumpArchiveMutationVersionForDir(memoryDir);
+}
+export function bumpArchiveMutationForPath(memoryDir: string, changed: boolean, filePath: string): void {
+  if (!changed) return;
+  const relative = path.relative(memoryDir, filePath);
+  if (relative === "archive" || relative.startsWith(`archive${path.sep}`)) {
+    bumpArchiveMutationVersionForDir(memoryDir);
+  }
+}
+export async function recordArchiveMutation<T>(
+  memoryDir: string,
+  filePath: string,
+  mutation: () => Promise<T>,
+): Promise<T> {
+  const result = await mutation();
+  if (result !== false) bumpArchiveMutationForPath(memoryDir, true, filePath);
+  return result;
+}
+export function recordArchiveDelete(
+  memoryDir: string,
+  filePath: string,
+  remove: () => Promise<boolean>,
+): Promise<boolean> {
+  return recordArchiveMutation(memoryDir, filePath, remove);
+}
+
+export async function recordArchiveWrite(
+  memoryDir: string,
+  filePath: string,
+  write: () => Promise<void>,
+): Promise<void> {
+  await recordArchiveMutation(memoryDir, filePath, write);
+}

package/src/config.test.ts

@@ -2549,3 +2549,48 @@ test("parseConfig validates converge conflict policy and defaults to newest-wins
     /converge contains unknown key "conflictPolciy"/,
   );
 });
+test("parseConfig parses contradictionLocalization defaults, string booleans, and integer caps", () => {
+  const defaults = parseConfig({}).contradictionLocalization;
+  assert.deepEqual(defaults, {
+    anchorEnabled: true,
+    anchorCandidates: 5,
+    searchCandidates: 5,
+    maxCandidates: 8,
+  });
+  assert.deepEqual(
+    parseConfig({
+      contradictionLocalization: {
+        anchorEnabled: "false",
+        anchorCandidates: "0",
+        searchCandidates: "2",
+        maxCandidates: 12,
+      },
+    }).contradictionLocalization,
+    {
+      anchorEnabled: false,
+      anchorCandidates: 0,
+      searchCandidates: 2,
+      maxCandidates: 12,
+    },
+  );
+  assert.throws(
+    () =>
+      parseConfig({
+        contradictionLocalization: { anchorCandidates: "not-an-integer" },
+      }),
+    /contradictionLocalization\.anchorCandidates/,
+  );
+  assert.throws(
+    () =>
+      parseConfig({
+        contradictionLocalization: { maxCandidates: 1.5 },
+      }),
+    /contradictionLocalization\.maxCandidates/,
+  );
+});
+test("parseConfig rejects array contradictionLocalization values", () => {
+  assert.throws(
+    () => parseConfig({ contradictionLocalization: [] }),
+    /contradictionLocalization must be an object/,
+  );
+});

package/src/config.ts

@@ -2,7 +2,6 @@ import path from "node:path";
 import type {
   CodexCompactionFlushMode,
   CodingModeConfig,
-  ContradictionScanConfig,
   CodexCompatConfig,
   DreamingConfig,
   DreamsLightSleepConfig,
@@ -42,6 +41,11 @@ import { parseRecallConcurrencyConfig } from "./recall-concurrency-config.js";
 import { parseExtractionLivenessConfig } from "./extraction-liveness.js";
 import { parseReplicaPeersConfig } from "./replica-peers-config.js";
 import { parseDependencyPropagationConfig } from "./dependency-propagation-config.js";
+import {
+  parseContradictionLocalizationConfig,
+  parseContradictionScanConfig,
+} from "./contradiction-config.js";
+import { parseGraphPathScoringConfig } from "./graph-path-scoring-config.js";
 import { hasLegacyConnectorEntries } from "./connectors/paths.js";
 import {
   parseQmdChunkStrategy,
@@ -352,6 +356,7 @@ function resolveBooleanConfig(
   return coerced;
 }
 
+
 function resolvePositiveIntegerConfig(
   value: unknown,
   defaultValue: number,
@@ -506,35 +511,6 @@ function normalizeMemoryRelativeDir(raw: unknown, fallback: string): string {
   return normalized.length > 0 ? normalized : fallback;
 }
 
-/**
- * Parse and validate the semanticChunkingConfig sub-object.
- * Returns only recognized numeric/boolean fields with their correct types.
- */
-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,
-  };
-}
 
 function parseSemanticChunkingConfig(
   raw: unknown,
@@ -1806,6 +1782,7 @@ export function parseConfig(
       typeof cfg.contradictionSimilarityThreshold === "number" ? cfg.contradictionSimilarityThreshold : 0.7,
     contradictionMinConfidence:
       typeof cfg.contradictionMinConfidence === "number" ? cfg.contradictionMinConfidence : 0.9,
+    contradictionLocalization: parseContradictionLocalizationConfig(cfg.contradictionLocalization),
     contradictionAutoResolve: cfg.contradictionAutoResolve !== false,
     // Contradiction Scan cron (issue #520)
     contradictionScan: parseContradictionScanConfig(cfg.contradictionScan),
@@ -3500,6 +3477,9 @@ export function parseConfig(
       typeof cfg.graphActivationDecay === "number"
         ? Math.min(1, Math.max(0, cfg.graphActivationDecay))
         : 0.7,
+    graphPathScoring: parseGraphPathScoringConfig(
+      cfg.graphPathScoring as Record<string, unknown> | undefined,
+    ),
     graphExpansionActivationWeight:
       typeof cfg.graphExpansionActivationWeight === "number"
         ? Math.min(1, Math.max(0, cfg.graphExpansionActivationWeight))

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",
+    ),
+  };
+}