@remnic/core 9.48.1 → 9.49.1

package/src/orchestration/consolidation-run.ts

@@ -32,7 +32,9 @@ import { applyCommitmentLedgerLifecycle } from "../commitment-ledger.js";
 import { recordDreamsPhaseRun } from "../maintenance/dreams-ledger.js";
 import { deindexMemoriesBatchAsync } from "../temporal-index-batch.js";
 import { isActiveMemoryStatus } from "../memory-lifecycle-ledger-utils.js";
+import { propagateInvalidation } from "./dependency-propagation.js";
 import {
+  resolveCapabilities,
   resolveConsolidationCapabilities,
   resolveCreationMemoryCapabilities,
   resolveIndexingCapabilities,
@@ -42,6 +44,7 @@ import {
   resolveRecallEnhancementCapabilities,
   type MemoryLifecycleCapabilitySet,
 } from "../capabilities.js";
+import { pruneOrphanCueAnchors } from "../cue-anchors.js";
 import type { LifecyclePolicyCoordinator } from "./lifecycle-policy-coordinator.js";
 import type { CompressionGuidelineCoordinator } from "./compression-guideline-coordinator.js";
 import type { SemanticConsolidationCoordinator } from "./semantic-consolidation-coordinator.js";
@@ -49,6 +52,7 @@ import type { EntitySynthesisCoordinator } from "./entity-synthesis-coordinator.
 import type { RecallSectionCoordinator } from "./recall-section-coordinator.js";
 import type { TierMigrationCoordinator } from "./tier-migration-coordinator.js";
 import type { StorageManager } from "../index.js";
+import type { NamespaceCatalog } from "../namespaces/catalog.js";
 import type { NamespaceStorageRouter } from "../namespaces/storage.js";
 import type { ExtractionEngine } from "../extraction.js";
 import type { EmbeddingFallback } from "../embedding-fallback.js";
@@ -67,6 +71,7 @@ export interface ConsolidationRunCoordinatorDeps {
   config: PluginConfig;
   getStorage: () => StorageManager;
   getStorageRouter: () => NamespaceStorageRouter;
+  getNamespaceCatalog?: () => NamespaceCatalog;
   getExtraction: () => ExtractionEngine;
   embeddingFallback: EmbeddingFallback;
   tmtBuilder: TmtBuilder;
@@ -100,9 +105,142 @@ export interface ConsolidationRunCoordinatorDeps {
   ) => Promise<{ content: string } | null>;
 }
 
+const MAX_HARMONIC_NAMESPACE_STORES = 50;
+const HARMONIC_CATALOG_CURSOR_FILE = "harmonic-catalog-cursor.json";
+
+type HarmonicStore = {
+  memoryDir: string;
+  abstractionNodeStoreDir?: string;
+};
+
+type HarmonicCatalogCursor = {
+  nextStorageDir?: string;
+};
+
 export class ConsolidationRunCoordinator {
   constructor(private readonly deps: ConsolidationRunCoordinatorDeps) {}
 
+  private async readHarmonicCatalogCursor(defaultDir: string): Promise<string | undefined> {
+    const cursorPath = path.join(defaultDir, "state", HARMONIC_CATALOG_CURSOR_FILE);
+    try {
+      const raw = await readFile(cursorPath, "utf-8");
+      const parsed = JSON.parse(raw) as HarmonicCatalogCursor;
+      return typeof parsed.nextStorageDir === "string" && parsed.nextStorageDir.length > 0
+        ? path.resolve(parsed.nextStorageDir)
+        : undefined;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        log.warn(
+          `harmonic namespace catalog cursor read failed open: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+      return undefined;
+    }
+  }
+
+  private async writeHarmonicCatalogCursor(
+    defaultDir: string,
+    nextStorageDir: string,
+  ): Promise<void> {
+    const stateDir = path.join(defaultDir, "state");
+    await mkdir(stateDir, { recursive: true });
+    await writeFile(
+      path.join(stateDir, HARMONIC_CATALOG_CURSOR_FILE),
+      JSON.stringify({ nextStorageDir }, null, 2),
+      "utf-8",
+    );
+  }
+
+  private async pruneHarmonicStores(storage: StorageManager): Promise<void> {
+    const config = this.deps.config;
+    if (
+      !resolveCapabilities(config).harmonicRetrieval ||
+      !resolveConsolidationCapabilities(config).abstractionAnchors
+    ) {
+      return;
+    }
+
+    const stores = new Map<string, HarmonicStore>();
+    const defaultDir = path.resolve(storage.dir);
+    stores.set(defaultDir, {
+      memoryDir: storage.dir,
+      abstractionNodeStoreDir: config.abstractionNodeStoreDir,
+    });
+
+    try {
+      const catalog = this.deps.getNamespaceCatalog?.();
+      if (catalog?.enabled) {
+        const records = await catalog.listNamespaces({ discoveredBy: "write" });
+        const catalogStores = new Map<string, HarmonicStore>();
+        for (const record of records) {
+          const storageDir = path.resolve(record.storageDir);
+          if (!stores.has(storageDir) && !catalogStores.has(storageDir)) {
+            catalogStores.set(storageDir, { memoryDir: record.storageDir });
+          }
+        }
+
+        const candidates = [...catalogStores.entries()];
+        if (candidates.length > 0) {
+          const cursor = await this.readHarmonicCatalogCursor(defaultDir);
+          const cursorIndex = cursor
+            ? candidates.findIndex(([storageDir]) => storageDir === cursor)
+            : -1;
+          const startIndex = cursorIndex >= 0 ? cursorIndex : 0;
+          const selectedCount = Math.min(
+            candidates.length,
+            MAX_HARMONIC_NAMESPACE_STORES - 1,
+          );
+
+          for (let offset = 0; offset < selectedCount; offset += 1) {
+            const index = (startIndex + offset) % candidates.length;
+            const [storageDir, store] = candidates[index];
+            stores.set(storageDir, store);
+          }
+
+          const nextIndex = (startIndex + selectedCount) % candidates.length;
+          const nextStorageDir = candidates[nextIndex][0];
+          try {
+            await this.writeHarmonicCatalogCursor(defaultDir, nextStorageDir);
+          } catch (error) {
+            log.warn(
+              `harmonic namespace catalog cursor write failed open: ${
+                error instanceof Error ? error.message : String(error)
+              }`,
+            );
+          }
+
+          if (selectedCount < candidates.length) {
+            log.warn(
+              `harmonic namespace catalog truncated at ${MAX_HARMONIC_NAMESPACE_STORES} stores; ` +
+                `skipped ${candidates.length - selectedCount} store(s)`,
+            );
+          }
+        }
+      }
+    } catch (error) {
+      log.warn(
+        `harmonic namespace catalog read failed open: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+
+    for (const store of stores.values()) {
+      try {
+        const removed = await pruneOrphanCueAnchors(store);
+        if (removed > 0) {
+          log.info(`harmonic anchor prune removed ${removed} orphan(s) from ${store.memoryDir}`);
+        }
+      } catch (error) {
+        log.warn(
+          `harmonic anchor prune failed open for ${store.memoryDir}: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    }
+  }
+
   async run(): Promise<{
     memoriesProcessed: number;
     merged: number;
@@ -124,6 +262,7 @@ export class ConsolidationRunCoordinator {
     if (this.deps.getAccessTrackingBuffer().size > 0) {
       await this.deps.flushAccessTracking();
     }
+    await this.pruneHarmonicStores(storage);
 
     let allMemories = await storage.readAllMemories();
     if (allMemories.length < 5) {
@@ -170,10 +309,36 @@ export class ConsolidationRunCoordinator {
             const toInvalidate = resolveIndexingCapabilities(config).queryAwareIndexing
               ? (memoryLookup?.get(item.existingId) ?? null)
               : null;
+            // Always capture the full pre-delete snapshot for propagation.
+            const propagationOld = allMemories.find(
+              (memory) => memory.frontmatter.id === item.existingId,
+            );
             if (await storage.invalidateMemory(item.existingId)) {
               invalidated += 1;
               memoryItemMutated = true;
               await this.deps.embeddingFallback.removeFromIndex(item.existingId);
+              if (propagationOld) {
+                try {
+                  await propagateInvalidation(
+                    {
+                      storage,
+                      extraction: this.deps.getExtraction(),
+                      config,
+                    },
+                    {
+                      oldMemory: propagationOld,
+                      replacementId: null,
+                      replacementContent: null,
+                      cause: "consolidation_invalidate",
+                      namespaceScope: config.defaultNamespace,
+                    },
+                  );
+                } catch (propagationErr) {
+                  log.warn(
+                    `consolidation dependency propagation failed for ${item.existingId}: ${propagationErr}`,
+                  );
+                }
+              }
               if (toInvalidate?.path && toInvalidate.frontmatter?.created) {
                 itemsDeindexBatch.push({
                   path: toInvalidate.path,
@@ -217,10 +382,37 @@ export class ConsolidationRunCoordinator {
               const toMergeInvalidate = resolveIndexingCapabilities(config).queryAwareIndexing
                 ? (memoryLookup?.get(item.mergeWith) ?? null)
                 : null;
+              // Capture the doomed memory before invalidation, independent of
+              // queryAwareIndexing and its optional lookup map.
+              const propagationOld = allMemories.find(
+                (memory) => memory.frontmatter.id === item.mergeWith,
+              );
               if (await storage.invalidateMemory(item.mergeWith)) {
                 invalidated += 1;
                 merged += 1;
                 await this.deps.embeddingFallback.removeFromIndex(item.mergeWith);
+                if (propagationOld) {
+                  try {
+                    await propagateInvalidation(
+                      {
+                        storage,
+                        extraction: this.deps.getExtraction(),
+                        config,
+                      },
+                      {
+                        oldMemory: propagationOld,
+                        replacementId: item.existingId,
+                        replacementContent: item.updatedContent,
+                        cause: "consolidation_merge",
+                        namespaceScope: config.defaultNamespace,
+                      },
+                    );
+                  } catch (propagationErr) {
+                    log.warn(
+                      `consolidation dependency propagation failed for ${item.mergeWith}: ${propagationErr}`,
+                    );
+                  }
+                }
                 if (
                   toMergeInvalidate?.path &&
                   toMergeInvalidate.frontmatter?.created

package/src/orchestration/contradiction-linking-coordinator.ts

@@ -17,6 +17,7 @@
  */
 
 import type {
+  MemoryFile,
   MemoryLink,
   PluginConfig,
   QmdSearchResult,
@@ -28,6 +29,7 @@ import type { ExtractionEngine } from "../extraction.js";
 import { log } from "../logger.js";
 import { resolveIndexingCapabilities } from "../capabilities.js";
 import { deindexMemoryAsync } from "../temporal-index.js";
+import { propagateInvalidation } from "./dependency-propagation.js";
 
 /** Result type of {@link ContradictionLinkingCoordinator.checkForContradiction}. */
 export interface ContradictionResult {
@@ -243,12 +245,44 @@ export class ContradictionLinkingCoordinator {
     ) {
       return;
     }
+
+    // Capture links before the primary supersession. The propagation hook is
+    // orchestration-owned, so its own supersessions cannot recurse.
+    let oldMemory: MemoryFile | null = null;
+    try {
+      oldMemory = await storage.getMemoryById(contradiction.supersededId);
+    } catch (err) {
+      log.warn(`contradiction propagation snapshot failed for ${contradiction.supersededId}: ${err}`);
+    }
+
     try {
-      await storage.supersedeMemory(
+      const superseded = await storage.supersedeMemory(
         contradiction.supersededId,
         newMemoryId,
         contradiction.reason,
       );
+      if (!superseded) return;
+      if (oldMemory) {
+        try {
+          await propagateInvalidation(
+            {
+              storage,
+              extraction: this.getExtraction(),
+              config,
+            },
+            {
+              oldMemory,
+              replacementId: newMemoryId,
+              replacementContent: (await storage.getMemoryById(newMemoryId))?.content ?? null,
+              cause: "contradiction",
+              namespaceScope: this.namespaceFromPath(storage.dir),
+            },
+          );
+        } catch (err) {
+          log.warn(`contradiction dependency propagation failed for ${contradiction.supersededId}: ${err}`);
+        }
+      }
+
       if (
         resolveIndexingCapabilities(config).queryAwareIndexing &&
         contradiction.supersededPath

package/src/orchestration/dependency-propagation-triggers.test.ts

@@ -0,0 +1,286 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { applyTemporalSupersession } from "../temporal-supersession.js";
+import { ContradictionLinkingCoordinator } from "./contradiction-linking-coordinator.js";
+import { ConsolidationRunCoordinator } from "./consolidation-run.js";
+import type { ExtractionEngine } from "../extraction.js";
+import type { MemoryFile, PluginConfig } from "../types.js";
+import type { StorageManager } from "../storage.js";
+
+const NOW = "2026-08-08T00:00:00.000Z";
+
+function makeMemory(
+  id: string,
+  options: {
+    links?: Array<{ targetId: string; linkType: "supports" | "follows" }>;
+    status?: string;
+    content?: string;
+    entityRef?: string;
+    structuredAttributes?: Record<string, string>;
+  } = {},
+): MemoryFile {
+  return {
+    path: `/synthetic/${id}.md`,
+    content: options.content ?? `claim for ${id}`,
+    frontmatter: {
+      id,
+      category: "fact",
+      created: NOW,
+      updated: NOW,
+      source: "synthetic-trigger-test",
+      confidence: 0.9,
+      confidenceTier: "explicit",
+      tags: [],
+      status: (options.status ?? "active") as MemoryFile["frontmatter"]["status"],
+      links: options.links?.map((link) => ({ ...link, strength: 0.9 })),
+      entityRef: options.entityRef,
+      structuredAttributes: options.structuredAttributes,
+    },
+  } as unknown as MemoryFile;
+}
+
+function propagationConfig(): PluginConfig {
+  return {
+    memoryDir: "/synthetic/remnic-trigger-tests",
+    queryAwareIndexingEnabled: false,
+    contradictionAutoResolve: true,
+    contradictionSimilarityThreshold: 0.7,
+    contradictionMinConfidence: 0.8,
+    dependencyPropagation: {
+      enabled: true,
+      linkTypes: ["supports", "follows"],
+      maxDependents: 10,
+      timeoutMs: 50,
+      dryRun: false,
+    },
+  } as unknown as PluginConfig;
+}
+
+type TriggerStorage = {
+  memories: Map<string, MemoryFile>;
+  supersedeCalls: Array<{ id: string; replacementId: string; reason: string }>;
+  frontmatterCalls: Array<{ id: string; patch: Record<string, unknown> }>;
+  invalidateCalls: string[];
+  storage: StorageManager;
+};
+
+function makeStorage(initial: MemoryFile[]): TriggerStorage {
+  const memories = new Map(initial.map((item) => [item.frontmatter.id, item]));
+  const supersedeCalls: TriggerStorage["supersedeCalls"] = [];
+  const frontmatterCalls: TriggerStorage["frontmatterCalls"] = [];
+  const invalidateCalls: string[] = [];
+  const storage = {
+    memories,
+    supersedeCalls,
+    frontmatterCalls,
+    invalidateCalls,
+    async getMemoryById(id: string): Promise<MemoryFile | null> {
+      return memories.get(id) ?? null;
+    },
+    async readAllMemories(): Promise<MemoryFile[]> {
+      return [...memories.values()];
+    },
+    async readAllColdMemories(): Promise<MemoryFile[]> {
+      return [];
+    },
+    async readMemoryByPath(path: string): Promise<MemoryFile | null> {
+      return [...memories.values()].find((memory) => memory.path === path) ?? null;
+    },
+    async readProfile(): Promise<string> {
+      return "";
+    },
+    async appendTombstone(): Promise<void> {},
+    async mergeFragmentedEntities(): Promise<number> {
+      return 0;
+    },
+    async cleanExpiredCommitments(): Promise<MemoryFile[]> {
+      return [];
+    },
+    async cleanExpiredTTL(): Promise<MemoryFile[]> {
+      return [];
+    },
+    async profileNeedsConsolidation(): Promise<boolean> {
+      return false;
+    },
+    async loadMeta(): Promise<Record<string, unknown>> {
+      return {};
+    },
+    async saveMeta(): Promise<void> {},
+    async supersedeMemory(id: string, replacementId: string, reason: string): Promise<boolean> {
+      supersedeCalls.push({ id, replacementId, reason });
+      const current = memories.get(id);
+      if (!current) return false;
+      current.frontmatter.status = "superseded";
+      current.frontmatter.supersededBy = replacementId;
+      return true;
+    },
+    async writeMemoryFrontmatter(current: MemoryFile, patch: Record<string, unknown>): Promise<boolean> {
+      frontmatterCalls.push({ id: current.frontmatter.id, patch });
+      const stored = memories.get(current.frontmatter.id);
+      if (!stored) return false;
+      Object.assign(stored.frontmatter, patch);
+      return true;
+    },
+    async invalidateMemory(id: string): Promise<boolean> {
+      invalidateCalls.push(id);
+      return memories.delete(id);
+    },
+  } as unknown as StorageManager;
+  return { memories, supersedeCalls, frontmatterCalls, invalidateCalls, storage };
+}
+
+function makeRevalidationExtraction(
+  revalidateCalls: Array<unknown>,
+): ExtractionEngine {
+  return {
+    async revalidateDependents(
+      superseded: { id: string; content: string },
+      replacement: { id: string; content: string } | null,
+      dependents: Array<{ id: string; category: string; content: string }>,
+      signal?: AbortSignal,
+    ) {
+      revalidateCalls.push({ superseded, replacement, dependents, signal });
+      return {
+        verdicts: dependents.map((dependent) => ({
+          memoryId: dependent.id,
+          verdict: "invalidated",
+          reason: "supporting claim changed",
+        })),
+      };
+    },
+  } as unknown as ExtractionEngine;
+}
+
+test("contradiction resolve propagates after superseding the captured old memory", async () => {
+  const old = makeMemory("old", { links: [{ targetId: "dependent", linkType: "supports" }] });
+  const replacement = makeMemory("replacement", { content: "new claim" });
+  const dependent = makeMemory("dependent");
+  const fixture = makeStorage([old, replacement, dependent]);
+  const revalidateCalls: unknown[] = [];
+  const extraction = makeRevalidationExtraction(revalidateCalls);
+  const config = propagationConfig();
+  const coordinator = new ContradictionLinkingCoordinator({
+    getConfig: () => config,
+    isSearchAvailable: () => false,
+    searchAcrossNamespaces: async () => [],
+    extractMemoryIdsFromResults: () => [],
+    namespaceFromPath: () => "namespace-a",
+    storageForNamespace: async () => fixture.storage,
+    getExtraction: () => extraction,
+  });
+
+  await coordinator.applyDeferredContradictionResolve(
+    {
+      supersededId: "old",
+      reason: "newer contradiction",
+      supersededPath: old.path,
+      supersededCreated: old.frontmatter.created,
+      supersededTags: [],
+    },
+    fixture.storage,
+    "replacement",
+    false,
+  );
+
+  assert.deepEqual(fixture.supersedeCalls, [
+    { id: "old", replacementId: "replacement", reason: "newer contradiction" },
+    { id: "dependent", replacementId: "replacement", reason: "dependency_propagation:contradiction" },
+  ]);
+  assert.equal(fixture.memories.get("dependent")?.frontmatter.supersessionCause, "dependency");
+  assert.equal(fixture.memories.get("dependent")?.frontmatter.invalidatedBy, "old");
+  assert.equal(revalidateCalls.length, 1);
+});
+
+test("temporal supersession propagates to a dependent after the old fact is retired", async () => {
+  const old = makeMemory("old", {
+    entityRef: "project-a",
+    structuredAttributes: { city: "Austin" },
+    links: [{ targetId: "dependent", linkType: "supports" }],
+  });
+  const replacement = makeMemory("replacement", {
+    entityRef: "project-a",
+    structuredAttributes: { city: "Boston" },
+    content: "project-a moved to Boston",
+  });
+  replacement.frontmatter.created = "2026-08-09T00:00:00.000Z";
+  const dependent = makeMemory("dependent");
+  const fixture = makeStorage([old, replacement, dependent]);
+  const revalidateCalls: unknown[] = [];
+  const extraction = makeRevalidationExtraction(revalidateCalls);
+  const temporalArgs = {
+    storage: fixture.storage,
+    newMemoryId: "replacement",
+    entityRef: "project-a",
+    structuredAttributes: { city: "Boston" },
+    createdAt: "2026-08-09T00:00:00.000Z",
+    enabled: true,
+    extraction,
+    config: propagationConfig(),
+    namespaceScope: "namespace-a",
+  };
+
+  const result = await (applyTemporalSupersession as unknown as (args: typeof temporalArgs) => Promise<{
+    supersededIds: string[];
+  }>)(temporalArgs);
+
+  assert.deepEqual(result.supersededIds, ["old"]);
+  assert.equal(fixture.memories.get("dependent")?.frontmatter.invalidatedBy, "old");
+  assert.equal(revalidateCalls.length, 1);
+});
+
+test("consolidation INVALIDATE captures links before deletion with query-aware indexing disabled", async () => {
+  const doomed = makeMemory("doomed", { links: [{ targetId: "dependent", linkType: "supports" }] });
+  const dependent = makeMemory("dependent");
+  const fillers = ["filler-a", "filler-b", "filler-c"].map((id) => makeMemory(id));
+  const fixture = makeStorage([doomed, dependent, ...fillers]);
+  const revalidateCalls: unknown[] = [];
+  const extraction = {
+    ...makeRevalidationExtraction(revalidateCalls),
+    async consolidate() {
+      return {
+        items: [{ existingId: "doomed", action: "INVALIDATE", reason: "duplicate" }],
+        profileUpdates: [],
+        entityUpdates: [],
+      };
+    },
+  } as unknown as ExtractionEngine;
+  const config = propagationConfig();
+  const coordinator = new ConsolidationRunCoordinator({
+    config,
+    getStorage: () => fixture.storage,
+    getStorageRouter: () => ({ recordWrite: async () => {} }) as never,
+    getExtraction: () => extraction,
+    embeddingFallback: { removeFromIndex: async () => {} } as never,
+    tmtBuilder: { maybeRebuildNodes: async () => {} } as never,
+    consolidationObservers: new Set(),
+    getAccessTrackingBuffer: () => new Map(),
+    lifecyclePolicyCoordinator: {
+      runFactArchival: async () => 0,
+      runSummarization: async () => {},
+      runTopicExtraction: async () => {},
+    } as never,
+    compressionGuidelineCoordinator: {
+      runCompressionGuidelineLearningPass: async () => {},
+    } as never,
+    semanticConsolidationCoordinator: {} as never,
+    entitySynthesisCoordinator: {} as never,
+    recallSectionCoordinator: {
+      getRecallSectionEntry: () => undefined,
+    } as never,
+    tierMigrationCoordinator: {
+      runCycle: async () => ({ migrated: 0 }),
+    } as never,
+    flushAccessTracking: async () => {},
+    indexPersistedMemory: async () => {},
+    autoConsolidateIdentity: async () => {},
+    fastChatCompletion: async () => null,
+  });
+
+  await coordinator.run();
+
+  assert.deepEqual(fixture.invalidateCalls, ["doomed"]);
+  assert.equal(fixture.memories.has("doomed"), false);
+  assert.equal(fixture.memories.get("dependent")?.frontmatter.status, "superseded");
+  assert.equal(fixture.memories.get("dependent")?.frontmatter.invalidatedBy, "doomed");
+  assert.equal(revalidateCalls.length, 1);
+});