@remnic/core 9.50.3 → 9.51.0

package/src/orchestration/extraction-anchor-snapshot.ts

@@ -0,0 +1,83 @@
+import path from "node:path";
+
+import type { StorageManager } from "../index.js";
+import type { MemoryCategory, MemoryFile } from "../types.js";
+import { resolvePersistedMemoryRelativePath } from "../orchestrator.js";
+import { mergeMemorySnapshots } from "./update-localization.js";
+
+type AnchorSnapshotOptions = {
+  enabled?: boolean;
+  candidateLimit?: number;
+  onRefreshError?: (error: unknown) => void;
+};
+
+/** Maintains one hot+cold anchor snapshot per storage during a persistence pass. */
+export class ExtractionAnchorSnapshot {
+  private readonly snapshots = new WeakMap<StorageManager, Promise<MemoryFile[]>>();
+  private readonly refreshFailed = new WeakSet<StorageManager>();
+  private failOpenRead(
+    storage: StorageManager,
+    snapshot: Promise<MemoryFile[]>,
+  ): Promise<MemoryFile[] | undefined> {
+    return snapshot.catch((error) => {
+      this.refreshFailed.add(storage);
+      if (this.snapshots.get(storage) === snapshot) this.snapshots.delete(storage);
+      this.options.onRefreshError?.(error);
+      return [];
+    });
+  }
+  constructor(private readonly options: AnchorSnapshotOptions = {}) {}
+
+  get(storage: StorageManager, entityRef: unknown): Promise<MemoryFile[] | undefined> {
+    const candidateLimit = this.options.candidateLimit ?? 5;
+    if (
+      this.options.enabled === false ||
+      !Number.isInteger(candidateLimit) ||
+      candidateLimit <= 0 ||
+      typeof entityRef !== "string" ||
+      entityRef.trim().length === 0
+    ) {
+      return Promise.resolve(undefined);
+    }
+    if (this.refreshFailed.has(storage)) return Promise.resolve([]);
+    const cached = this.snapshots.get(storage);
+    if (cached) return this.failOpenRead(storage, cached);
+    const snapshot = Promise.all([
+      storage.readAllMemories(),
+      storage.readAllColdMemories(),
+    ]).then(([hot, cold]) => mergeMemorySnapshots(hot, cold, storage.dir));
+    this.snapshots.set(storage, snapshot);
+    return this.failOpenRead(storage, snapshot);
+  }
+
+  async replace(
+    storage: StorageManager,
+    memoryId: string,
+    category: MemoryCategory,
+    pathById: Map<string, string>,
+  ): Promise<void> {
+    if (this.refreshFailed.has(storage)) return;
+    try {
+      const cached = this.snapshots.get(storage);
+      if (!cached) return;
+      const snapshot = await cached;
+      const relativePath = resolvePersistedMemoryRelativePath({ memoryId, pathById, category });
+      const memory = await storage.readMemoryByPath(path.join(storage.dir, relativePath));
+      if (!memory) return;
+      const existingIndex = snapshot.findIndex((entry) => entry.frontmatter.id === memoryId);
+      if (existingIndex >= 0) snapshot.splice(existingIndex, 1);
+      snapshot.push(memory);
+    } catch (error) {
+      this.refreshFailed.add(storage);
+      this.options.onRefreshError?.(error);
+    }
+  }
+
+  async remove(storage: StorageManager, memoryId: string): Promise<void> {
+    const cached = this.snapshots.get(storage);
+    if (!cached) return;
+    const snapshot = await cached;
+    const index = snapshot.findIndex((entry) => entry.frontmatter.id === memoryId);
+    if (index >= 0) snapshot.splice(index, 1);
+  }
+}

package/src/orchestration/extraction-persist-deps.ts

@@ -1,3 +1,4 @@
+import type { ContradictionResolveOutcome } from "./contradiction-linking-coordinator.js";
 import type { GraphConstructionCapabilitySet } from "../capabilities.js";
 import type { SemanticDedupHit } from "../dedup/semantic.js";
 import type { EmbeddingFallback } from "../embedding-fallback.js";
@@ -49,7 +50,12 @@ export interface ExtractionPersistDeps {
   checkForContradiction: (
     content: string,
     category: string,
-    namespaceScope: string
+    namespaceScope: string,
+    anchor?: {
+      entityRef?: string;
+      structuredAttributes?: Record<string, string>;
+      storageSnapshot?: MemoryFile[];
+    }
   ) => Promise<{
     supersededId: string;
     confidence: number;
@@ -72,7 +78,7 @@ export interface ExtractionPersistDeps {
     storage: StorageManager,
     newMemoryId: string,
     postWriteGuard: boolean
-  ) => Promise<void>;
+  ) => Promise<ContradictionResolveOutcome>;
   suggestLinksForMemory: (content: string, category: string, namespaceScope: string) => Promise<MemoryLink[]>;
   storageDirNamespace: (storageDir: string) => string;
   indexPersistedMemory: (storage: StorageManager, memoryId: string) => Promise<void>;

package/src/orchestration/extraction-persist.ts

@@ -1,22 +1,8 @@
 /**
- * Extraction-persist coordinator — extracted from the orchestrator
- * (issue #1526, seam 16).
+ * Extraction persistence coordinator (issue #1526, seam 16).
  *
- * Owns the `persistExtraction` pipeline: the ~2.5k-LOC method that turns
- * an ExtractionResult into durable memory writes. Hosts:
- *   - pre-judge multi-namespace redaction gate
- *   - extraction-judge gating
- *   - scope routing
- *   - tombstone postWriteGuard
- *   - dedup + bitemporal backfill (3 paths)
- *   - contradiction auto-resolve deferral
- *   - promotion paths
- *   - post-persist content-hash indexing
- *   - catalog write-recording
- *
- * Behavior-preserving move from orchestrator.ts. No logic changes — the
- * orchestrator keeps a thin delegating method so existing call sites and
- * tests continue to work.
+ * It owns the extraction-to-memory write pipeline, including redaction,
+ * judging, scope routing, deduplication, lifecycle updates, and indexing.
  */
 
 import { isMemoryCategory } from "../write-envelope.js";
@@ -25,12 +11,7 @@ import {
   probeSalvageSurvivingFields,
   withReservedMarkerTag,
 } from "./extraction-envelope.js";
-import path from "node:path";
-import {
-  StorageManager,
-  ContentHashIndex,
-  normalizeAttributePairs,
-} from "../index.js";
+import { ContentHashIndex, normalizeAttributePairs, type StorageManager } from "../index.js";
 import { log } from "../logger.js";
 import { chunkContent, type ChunkingConfig } from "../chunking.js";
 import { semanticChunkContent, type SemanticChunkResult } from "../semantic-chunking.js";
@@ -50,6 +31,7 @@ import {
   type GraphConstructionCapabilitySet,
   type MemoryLifecycleCapabilitySet,
 } from "../capabilities.js";
+import { coerceBool } from "../connectors/coerce.js";
 import {
   applyTemporalSupersession,
   normalizeSupersessionKey,
@@ -129,6 +111,8 @@ import {
 } from "../orchestrator.js";
 import type { HarmonicConstructionInput } from "../harmonic-construction.js";
 import { persistConstructedHarmonicRecords } from "./harmonic-construction-persist.js";
+import { ExtractionAnchorSnapshot } from "./extraction-anchor-snapshot.js";
+
 
 
 
@@ -219,6 +203,11 @@ export class ExtractionPersistCoordinator {
     };
     const persistedIds: string[] = [];
     const memoryPathById = new Map<string, string>();
+    const anchorSnapshots = new ExtractionAnchorSnapshot({
+      enabled: coerceBool(this.deps.config.contradictionLocalization?.anchorEnabled) ?? true,
+      candidateLimit: this.deps.config.contradictionLocalization?.anchorCandidates,
+      onRefreshError: (error) => log.warn(`anchor snapshot update failed; using empty snapshot: ${error}`),
+    });
     const supersessionOrderingAt = (validAt?: string): string =>
       validAt && validAt.length > 0 ? validAt : new Date().toISOString();
     // #1635: pending_review persisted ids, excluded from the thread episode set below.
@@ -2045,14 +2034,20 @@ export class ExtractionPersistCoordinator {
       // must not trigger auto-resolve and retire an existing active memory.
       if (
         resolveRecallEnhancementCapabilities(this.deps.config).contradictionDetection &&
-        this.deps.getQmd().isAvailable() &&
         faithfulnessEnforceStatus !== "pending_review"
       ) {
         const targetNamespace = this.deps.storageDirNamespace(targetStorage.dir);
+        const candidateEntityRef: unknown = fact.entityRef;
+        const factEntityRef = typeof candidateEntityRef === "string" ? candidateEntityRef : undefined;
         contradiction = await this.deps.checkForContradiction(
           fact.content,
           writeCategory,
           targetNamespace,
+          {
+            entityRef: factEntityRef,
+            structuredAttributes: fact.structuredAttributes,
+            storageSnapshot: await anchorSnapshots.get(targetStorage, factEntityRef),
+          },
         );
         if (contradiction) {
           contradictionDetected = true;
@@ -2225,18 +2220,20 @@ export class ExtractionPersistCoordinator {
           });
           const parentId = parentWrite.id;
           // #1645: surface the tombstone block and gate active post-write paths
-          // (chunks, supersession, shared promotion, graph/artifact) like #1576.
           const tombstoneBlocked = parentWrite.tombstoneBlocked;
           const postWriteGuard =
             faithfulnessEnforceStatus === "pending_review" || tombstoneBlocked;
           // #1645: defer contradiction auto-resolve until tombstone status is
           // known (see applyDeferredContradictionResolve).
-          await this.deps.applyDeferredContradictionResolve(
+          const contradictionOutcome = await this.deps.applyDeferredContradictionResolve(
             contradiction,
             targetStorage,
             parentId,
             postWriteGuard,
           );
+          if (contradictionOutcome === "resolved" || contradictionOutcome === "lost_race") {
+            await anchorSnapshots.remove(targetStorage, contradiction!.supersededId);
+          }
           try {
             // #2014 round 3: chunks inherit the PARENT ENVELOPE's surviving
             // tags (minus the parent-only "chunked" marker) and entityRef —
@@ -2330,6 +2327,7 @@ export class ExtractionPersistCoordinator {
             category: writeCategory,
             harmonicFact,
           });
+          await anchorSnapshots.replace(targetStorage, parentId, writeCategory, memoryPathById);
           // #1576 (cursor Medium): keep pending_review ids out of threadEpisodeIdsForGraph — else later active facts build thread-predecessor edges to an unfaithful memory.
           if (
             !postWriteGuard &&
@@ -2353,7 +2351,7 @@ export class ExtractionPersistCoordinator {
             try {
               // #2014 round 2: same envelope-surviving key rule as the
               // non-chunked path.
-              await applyTemporalSupersession({
+              const temporalSupersession = await applyTemporalSupersession({
                 storage: targetStorage,
                 newMemoryId: parentId,
                 entityRef: parentWriteEnvelope.entityRef,
@@ -2370,6 +2368,9 @@ export class ExtractionPersistCoordinator {
                 config: this.config,
                 namespaceScope: this.deps.storageDirNamespace(targetStorage.dir),
               });
+              for (const supersededId of temporalSupersession.supersededIds) {
+                await anchorSnapshots.remove(targetStorage, supersededId);
+              }
             } catch (err) {
               log.warn(`temporal-supersession (chunked): unexpected error: ${err}`);
             }
@@ -2606,12 +2607,19 @@ export class ExtractionPersistCoordinator {
       // #1645: surface the tombstone block; gate active post-write paths like #1576
       // so a blocked fact creates no active shared copy / supersession / graph entry.
       const tombstoneBlocked = factWrite.tombstoneBlocked;
-      const postWriteGuard =
-        faithfulnessEnforceStatus === "pending_review" || tombstoneBlocked;
+      const postWriteGuard = faithfulnessEnforceStatus === "pending_review" || tombstoneBlocked;
       // #1645: defer contradiction auto-resolve until tombstone status is
       // known (see applyDeferredContradictionResolve).
       try {
-        await this.deps.applyDeferredContradictionResolve(contradiction, targetStorage, memoryId, postWriteGuard);
+        const contradictionOutcome = await this.deps.applyDeferredContradictionResolve(
+          contradiction,
+          targetStorage,
+          memoryId,
+          postWriteGuard,
+        );
+        if (contradictionOutcome === "resolved" || contradictionOutcome === "lost_race") {
+          await anchorSnapshots.remove(targetStorage, contradiction!.supersededId);
+        }
       } catch (err) {
         await flushDeferredFactHashOnFailure(() => this.deps.saveContentHashIndexes(), factDedupEnabled);
         throw err;
@@ -2628,10 +2636,7 @@ export class ExtractionPersistCoordinator {
       // the review queue must NOT retire older active memories.
       if (!postWriteGuard) {
         try {
-          // #2014 round 2: key supersession on the envelope's SURVIVING
-          // fields — salvage may have dropped attributes that must not
-          // retire older facts the persisted copy does not actually contest.
-          await applyTemporalSupersession({
+          const temporalSupersession = await applyTemporalSupersession({
             storage: targetStorage,
             newMemoryId: memoryId,
             entityRef: factWriteEnvelope.entityRef,
@@ -2645,6 +2650,9 @@ export class ExtractionPersistCoordinator {
             config: this.config,
             namespaceScope: this.deps.storageDirNamespace(targetStorage.dir),
           });
+          for (const supersededId of temporalSupersession.supersededIds) {
+            await anchorSnapshots.remove(targetStorage, supersededId);
+          }
         } catch (err) {
           log.warn(`temporal-supersession: unexpected error: ${err}`);
         }
@@ -2666,6 +2674,7 @@ export class ExtractionPersistCoordinator {
           category: writeCategory,
           harmonicFact,
         });
+        await anchorSnapshots.replace(targetStorage, memoryId, writeCategory, memoryPathById);
         if (
           !postWriteGuard &&
           threadEpisodeIdsForGraph &&