@remnic/core 9.3.653 → 9.3.654

package/src/contradiction/resolution.ts

@@ -5,11 +5,11 @@
  * reimplement supersession logic here (rule 22: deduplicate resolution).
  */
 
+import { log } from "../logger.js";
 import type { StorageManager } from "../storage.js";
 import type { MemoryCategory, MemoryFile } from "../types.js";
 import type { ResolutionVerb } from "./contradiction-review.js";
-import { resolvePair, readPair } from "./contradiction-review.js";
-import { log } from "../logger.js";
+import { readPair, resolvePair } from "./contradiction-review.js";
 
 export interface ResolutionResult {
   pairId: string;
@@ -29,6 +29,24 @@ export interface ExecuteResolutionOptions {
   mergedCategory?: MemoryCategory;
   /** Resolve storage for the pair namespace, or the default namespace for legacy unscoped pairs. */
   storageForNamespace?: (namespace: string | undefined) => StorageManager | Promise<StorageManager>;
+  /**
+   * Best-effort hook invoked after a contradiction resolution leaves a durable
+   * mutation in the namespace's memory files (issue #1499 sweep, NH1dX / NH3X3).
+   * Every mutating verb — `merge` (creates a new memory and supersedes both
+   * sources), `keep-a`, and `keep-b` (supersede the losing source + rewrite
+   * frontmatter) — writes directly to the pair's (possibly DYNAMIC) namespace
+   * storage, bypassing the extraction write path that records catalog writes. So
+   * without this the namespace's `lastWriteAt` stays stale and QMD maintenance /
+   * `writtenSince` can skip a namespace whose only post-write mutation is
+   * resolving a contradiction. It fires after the resolution commits, or after a
+   * failed resolution/rollback path when durable memory changes are still left on
+   * disk. If a failure rolls back cleanly, this is never called, so the catalog
+   * never records a write that did not survive (rule #25). Non-mutating verbs
+   * (`both-valid`, `needs-more-context`) never trigger it. Callers wire this to
+   * `Orchestrator.recordCatalogWrite(namespace, storageDir)`. Must be
+   * failure-tolerant: it is fire-and-forget and must never affect resolution.
+   */
+  onMergedMemoryWritten?: (namespace: string | undefined, storageDir: string) => void;
 }
 
 const VALID_VERBS: ResolutionVerb[] = ["keep-a", "keep-b", "merge", "both-valid", "needs-more-context"];
@@ -81,6 +99,48 @@ export async function executeResolution(
   let message = "";
   let supersedeFailed = false;
   let rollbackAfterResolveFailure: (() => Promise<boolean>) | null = null;
+  // Deferred catalog-write touch for any resolution that leaves durable namespace
+  // memory mutations (issue #1499 sweep, NH1dX / NH3X3). Rule #25: never record a
+  // catalog touch for a write that is fully rolled back. Successful mutating
+  // resolutions invoke it after `resolvePair` persists. Failed paths invoke it
+  // only when rollback inspection shows the namespace still differs from the
+  // pre-mutation snapshot.
+  let recordCatalogWriteTouch: (() => void) | null = null;
+  // Returns the deferred touch fn for a mutating verb (or null when the caller
+  // wired no catalog hook), so each branch assigns `recordCatalogWriteTouch`
+  // directly in the function body — keeping TS control-flow narrowing intact at
+  // the post-commit invocation below.
+  const buildCatalogTouch = (): (() => void) | null => {
+    if (!options.onMergedMemoryWritten) return null;
+    const onMergedMemoryWritten = options.onMergedMemoryWritten;
+    const namespace = pair.namespace;
+    const storageDir = resolutionStorage.dir;
+    return () => onMergedMemoryWritten(namespace, storageDir);
+  };
+  const catalogWriteTouch = buildCatalogTouch();
+  const recordCatalogWriteTouchSafely = (context: string, touch = catalogWriteTouch): void => {
+    if (!touch) return;
+    try {
+      touch();
+    } catch (err) {
+      log.warn(
+        "[contradiction-resolution] catalog write touch failed for pair=%s context=%s: %s",
+        pairId,
+        context,
+        err instanceof Error ? err.message : err,
+      );
+    }
+  };
+  const touchCatalogIfRollbackLeftChange = async (
+    context: string,
+    snapshots: MemoryFile[],
+    replacement?: Extract<MergeReplacement, { ok: true }>,
+  ): Promise<void> => {
+    if (!catalogWriteTouch) return;
+    if (await rollbackLeftDurableMutation(resolutionStorage, snapshots, replacement)) {
+      recordCatalogWriteTouchSafely(context);
+    }
+  };
 
   switch (verb) {
     case "keep-a": {
@@ -98,6 +158,9 @@ export async function executeResolution(
         affectedIds.push(idB);
         rollbackAfterResolveFailure = async () =>
           restoreMemorySnapshot(resolutionStorage, sourceB!, "contradiction-resolution:keep-a-rollback");
+        // keep-a superseded idB in this namespace — record a catalog touch once
+        // the resolution durably commits (NH3X3).
+        recordCatalogWriteTouch = catalogWriteTouch;
         message = `Kept ${idA}, superseded ${idB}`;
       }
       else {
@@ -105,6 +168,9 @@ export async function executeResolution(
         const rolledBack = sourceB
           ? await restoreMemorySnapshot(resolutionStorage, sourceB, "contradiction-resolution:keep-a-rollback")
           : false;
+        if (sourceB && !rolledBack) {
+          await touchCatalogIfRollbackLeftChange("keep-a-rollback-incomplete", [sourceB]);
+        }
         message = rolledBack
           ? `Supersede failed for ${idB}; restored ${idB} and did not resolve`
           : `Supersede failed for ${idB}; rollback incomplete for ${idB} and pair is not resolved`;
@@ -126,6 +192,9 @@ export async function executeResolution(
         affectedIds.push(idA);
         rollbackAfterResolveFailure = async () =>
           restoreMemorySnapshot(resolutionStorage, sourceA!, "contradiction-resolution:keep-b-rollback");
+        // keep-b superseded idA in this namespace — record a catalog touch once
+        // the resolution durably commits (NH3X3).
+        recordCatalogWriteTouch = catalogWriteTouch;
         message = `Kept ${idB}, superseded ${idA}`;
       }
       else {
@@ -133,6 +202,9 @@ export async function executeResolution(
         const rolledBack = sourceA
           ? await restoreMemorySnapshot(resolutionStorage, sourceA, "contradiction-resolution:keep-b-rollback")
           : false;
+        if (sourceA && !rolledBack) {
+          await touchCatalogIfRollbackLeftChange("keep-b-rollback-incomplete", [sourceA]);
+        }
         message = rolledBack
           ? `Supersede failed for ${idA}; restored ${idA} and did not resolve`
           : `Supersede failed for ${idA}; rollback incomplete for ${idA} and pair is not resolved`;
@@ -157,6 +229,9 @@ export async function executeResolution(
         if (rolledBackA) {
           await cleanupCreatedReplacement(resolutionStorage, replacement);
         }
+        else {
+          await touchCatalogIfRollbackLeftChange("merge-first-rollback-incomplete", [replacement.sourceA], replacement);
+        }
         break;
       }
 
@@ -174,6 +249,13 @@ export async function executeResolution(
         if (rolledBackA && rolledBackB) {
           await cleanupCreatedReplacement(resolutionStorage, replacement);
         }
+        else {
+          await touchCatalogIfRollbackLeftChange(
+            "merge-second-rollback-incomplete",
+            [replacement.sourceA, replacement.sourceB],
+            replacement,
+          );
+        }
         break;
       }
 
@@ -186,6 +268,17 @@ export async function executeResolution(
         }
         return rolledBackA && rolledBackB;
       };
+      // Catalog write touch (issue #1499 sweep): the merge supersedes BOTH sources
+      // (and, when created, writes a fresh merged memory) in the pair's (possibly
+      // dynamic) namespace storage — but the resolution is not durable yet
+      // (resolvePair persists below, and a failure rolls the merge back). Defer
+      // the touch so it fires ONLY after the resolution commits past the rollback
+      // point (NH1dX, rule #25). Arm it for EVERY successful merge — even reusing
+      // an existing merged-id still supersedes both sources, a namespace mutation
+      // that must refresh `lastWriteAt` (NH3X3). Otherwise a dynamic namespace
+      // whose only durable mutation is a contradiction merge stays invisible to
+      // QMD maintenance / `writtenSince`. Best-effort on the caller side.
+      recordCatalogWriteTouch = catalogWriteTouch;
       message = `Both memories superseded by merged ${replacement.mergedId}`;
       break;
     }
@@ -217,10 +310,20 @@ export async function executeResolution(
         affectedIds.length = 0;
         message = rolledBack
           ? `Resolution persistence failed; rolled back memory changes and did not resolve ${pairId}`
-          : `Resolution persistence failed; rollback incomplete and pair is not resolved`;
+          : "Resolution persistence failed; rollback incomplete and pair is not resolved";
+        if (!rolledBack && recordCatalogWriteTouch) {
+          recordCatalogWriteTouchSafely("resolve-persistence-rollback-incomplete", recordCatalogWriteTouch);
+        }
       } else {
-        message = `Resolution persistence failed; pair is not resolved`;
+        message = "Resolution persistence failed; pair is not resolved";
       }
+    } else if (recordCatalogWriteTouch) {
+      // The resolution durably committed (memory mutated AND the resolution
+      // persisted past the rollback point). Only now is it safe to record the
+      // catalog write for the namespace mutation (NH1dX / NH3X3, rule #25).
+      // Best-effort: the caller's callback swallows errors; guard here so a
+      // throwing callback never derails a successful resolution.
+      recordCatalogWriteTouchSafely("resolved", recordCatalogWriteTouch);
     }
   }
   log.info("[contradiction-resolution] pair=%s verb=%s affected=%d", pairId, verb, affectedIds.length);
@@ -376,6 +479,50 @@ async function restoreMemorySnapshot(
   }
 }
 
+async function rollbackLeftDurableMutation(
+  storage: StorageManager,
+  snapshots: MemoryFile[],
+  replacement?: Extract<MergeReplacement, { ok: true }>,
+): Promise<boolean> {
+  for (const snapshot of snapshots) {
+    try {
+      const current = await storage.getMemoryById(snapshot.frontmatter.id);
+      if (!current) return true;
+      if (supersessionStateChanged(current, snapshot)) return true;
+    } catch (err) {
+      log.warn(
+        "[contradiction-resolution] rollback inspection failed for %s: %s",
+        snapshot.frontmatter.id,
+        err instanceof Error ? err.message : err,
+      );
+      return true;
+    }
+  }
+
+  if (replacement?.created) {
+    try {
+      return (await storage.getMemoryById(replacement.mergedId)) !== null;
+    } catch (err) {
+      log.warn(
+        "[contradiction-resolution] rollback replacement inspection failed for %s: %s",
+        replacement.mergedId,
+        err instanceof Error ? err.message : err,
+      );
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function supersessionStateChanged(current: MemoryFile, snapshot: MemoryFile): boolean {
+  return (
+    current.frontmatter.status !== snapshot.frontmatter.status ||
+    current.frontmatter.supersededBy !== snapshot.frontmatter.supersededBy ||
+    current.frontmatter.supersededAt !== snapshot.frontmatter.supersededAt
+  );
+}
+
 async function cleanupCreatedReplacement(storage: StorageManager, replacement: Extract<MergeReplacement, { ok: true }>): Promise<void> {
   if (!replacement.created) return;
   await cleanupMemoryId(storage, replacement.mergedId);

package/src/explicit-capture.ts

@@ -435,6 +435,15 @@ export async function persistExplicitCapture(
     expiresAt: candidate.expiresAt,
     source: source === "inline" ? "explicit-inline" : "explicit",
   });
+  // Record the catalog write touch (issue #1499, round 5 codex P2). Explicit
+  // captures bypass the extraction write path, so without this their namespace
+  // never updates `lastWriteAt`. An undefined namespace means the DEFAULT root
+  // (round 6, codex P2), which recordCatalogWrite resolves. The method is an
+  // optional best-effort hook — guard so Orchestrator-like callers without it
+  // don't break (rule #33). Best-effort and failure-tolerant.
+  if (typeof orchestrator.recordCatalogWrite === "function") {
+    orchestrator.recordCatalogWrite(resolvedNamespace, storage.dir);
+  }
 
   const created = new Date().toISOString();
   const event: MemoryLifecycleEvent = {
@@ -531,16 +540,28 @@ export async function queueExplicitCaptureForReview(
     entityRef: sanitizeReviewMetadata(input.entityRef),
     source: source === "inline" ? "explicit-inline-review" : "explicit-review",
   });
-  const created = await storage.getMemoryById(id);
-  if (created) {
-    await storage.writeMemoryFrontmatter(created, {
-      status: "pending_review",
-      updated: new Date().toISOString(),
-    }, {
-      actor: explicitCaptureActor(source),
-      reasonCode: reason,
-      ruleVersion: "explicit-capture.v1",
-    });
+  try {
+    const created = await storage.getMemoryById(id);
+    if (created) {
+      await storage.writeMemoryFrontmatter(created, {
+        status: "pending_review",
+        updated: new Date().toISOString(),
+      }, {
+        actor: explicitCaptureActor(source),
+        reasonCode: reason,
+        ruleVersion: "explicit-capture.v1",
+      });
+    }
+  } finally {
+    // Record the catalog write touch (issue #1499, round 5/6 codex P2; NIhUg).
+    // A queued review capture writes memory to the namespace's root (the DEFAULT
+    // root when undefined), so its `lastWriteAt` must reflect the write once
+    // `writeMemory` returns an id. If the later pending-review frontmatter update
+    // fails, the memory file is still durable and must not disappear from
+    // writtenSince/maintenance scheduling. Guarded optional hook (rule #33).
+    if (typeof orchestrator.recordCatalogWrite === "function") {
+      orchestrator.recordCatalogWrite(queueNamespace, storage.dir);
+    }
   }
   const event: MemoryLifecycleEvent = {
     eventId: `mle-${randomUUID()}`,

package/src/index.ts

@@ -323,6 +323,16 @@ export { MeilisearchBackend } from "./search/meilisearch-backend.js";
 
 export { buildEntityRecallSection } from "./entity-retrieval.js";
 export { resolvePrincipal } from "./namespaces/principal.js";
+export {
+  NamespaceCatalog,
+  type NamespaceRecord,
+  type NamespaceKind,
+  type NamespaceDiscoverySource,
+  type NamespaceCatalogFilter,
+  type NamespaceTouchMetadata,
+  type NamespaceCatalogRebuildResult,
+  type NamespaceCatalogSkippedRoot,
+} from "./namespaces/catalog.js";
 
 // ---------------------------------------------------------------------------
 // Session identity / transcript pathing (issue #1496)