@remnic/core 9.3.653 → 9.3.655

package/src/contradiction/contradiction.test.ts

@@ -91,6 +91,7 @@ function makeResolutionStorage(options: {
   failRollbackFor?: string;
   partialSupersedeBeforeFailureFor?: string;
   onSupersede?: (oldId: string, newId: string) => void;
+  dir?: string;
 } = {}) {
   const memories = new Map<string, MemoryFile>([
     ["mem-a-001", makeMemory("mem-a-001")],
@@ -111,6 +112,7 @@ function makeResolutionStorage(options: {
     supersedeCalls,
     frontmatterWrites,
     removedFactHashIds,
+    dir: options.dir ?? "/tmp/contradiction-namespace-storage",
     async getMemoryById(id: string) {
       const memory = memories.get(id);
       return memory ? cloneMemory(memory) : null;
@@ -1819,6 +1821,213 @@ test("executeResolution rolls back memory changes when pair resolution persisten
   }
 });
 
+// ── Catalog-write touch ordering (NH1dX, rule #25) ──────────────────────────────
+// The merge catalog touch (onMergedMemoryWritten) must fire ONLY after the
+// resolution durably commits past the rollback point. If resolvePair fails and
+// the merge rolls back, NO catalog write may be recorded for a write that did
+// not survive.
+
+test("executeResolution merge records NO catalog write touch when resolution persistence fails and rolls back", async () => {
+  const { dir, cleanup } = await makeTempDir();
+  try {
+    const written = writePair(dir, makePair({ namespace: "work" }));
+    const pairFile = path.join(dir, ".review", "contradictions", `${written.pairId}.json`);
+    // Force resolvePair to fail by removing the pair file once supersession runs,
+    // mirroring the existing rollback test. This drives the rollback path.
+    const storage = makeResolutionStorage({
+      dir: "/tmp/work-namespace-storage",
+      onSupersede: () => {
+        fs.rmSync(pairFile, { force: true });
+      },
+    });
+    const catalogTouches: Array<{ namespace: string | undefined; storageDir: string }> = [];
+
+    const result = await executeResolution(dir, storage, written.pairId, "merge", {
+      mergedContent: "merged canonical fact",
+      storageForNamespace: () => storage,
+      onMergedMemoryWritten: (namespace, storageDir) => {
+        catalogTouches.push({ namespace, storageDir });
+      },
+    });
+
+    assert.match(result.message, /Resolution persistence failed; rolled back memory changes/);
+    assert.deepEqual(result.affectedIds, []);
+    // The merged memory was created then cleaned up by the rollback, and the
+    // resolution never persisted — so the catalog touch must NOT have fired.
+    assert.deepEqual(
+      catalogTouches,
+      [],
+      "no catalog write touch may be recorded for a rolled-back merge",
+    );
+    assert.equal(readPair(dir, written.pairId), null);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("executeResolution merge records exactly one catalog write touch for the pair namespace on success", async () => {
+  const { dir, cleanup } = await makeTempDir();
+  try {
+    const written = writePair(dir, makePair({ namespace: "work" }));
+    const storage = makeResolutionStorage({ dir: "/tmp/work-namespace-storage" });
+    const catalogTouches: Array<{ namespace: string | undefined; storageDir: string }> = [];
+
+    const result = await executeResolution(dir, storage, written.pairId, "merge", {
+      mergedContent: "merged canonical fact",
+      storageForNamespace: () => storage,
+      onMergedMemoryWritten: (namespace, storageDir) => {
+        catalogTouches.push({ namespace, storageDir });
+      },
+    });
+
+    assert.match(result.message, /Both memories superseded by merged/);
+    assert.deepEqual(result.affectedIds, ["mem-a-001", "mem-b-002"]);
+    assert.equal(readPair(dir, written.pairId)?.resolution, "merge");
+    // Exactly one touch, carrying the pair namespace and the routed storage dir.
+    assert.deepEqual(catalogTouches, [
+      { namespace: "work", storageDir: "/tmp/work-namespace-storage" },
+    ]);
+  } finally {
+    await cleanup();
+  }
+});
+
+// NH3X3: supersede-only resolutions (keep-a / keep-b) also mutate the namespace,
+// so they must record a catalog touch — post-commit, never on rollback.
+
+test("executeResolution keep-a records exactly one catalog write touch on success", async () => {
+  const { dir, cleanup } = await makeTempDir();
+  try {
+    const written = writePair(dir, makePair({ namespace: "work" }));
+    const storage = makeResolutionStorage({ dir: "/tmp/work-namespace-storage" });
+    const catalogTouches: Array<{ namespace: string | undefined; storageDir: string }> = [];
+
+    const result = await executeResolution(dir, storage, written.pairId, "keep-a", {
+      storageForNamespace: () => storage,
+      onMergedMemoryWritten: (namespace, storageDir) => {
+        catalogTouches.push({ namespace, storageDir });
+      },
+    });
+
+    assert.deepEqual(result.affectedIds, ["mem-b-002"]);
+    assert.equal(readPair(dir, written.pairId)?.resolution, "keep-a");
+    assert.deepEqual(catalogTouches, [
+      { namespace: "work", storageDir: "/tmp/work-namespace-storage" },
+    ]);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("executeResolution keep-b records exactly one catalog write touch on success", async () => {
+  const { dir, cleanup } = await makeTempDir();
+  try {
+    const written = writePair(dir, makePair({ namespace: "work" }));
+    const storage = makeResolutionStorage({ dir: "/tmp/work-namespace-storage" });
+    const catalogTouches: Array<{ namespace: string | undefined; storageDir: string }> = [];
+
+    const result = await executeResolution(dir, storage, written.pairId, "keep-b", {
+      storageForNamespace: () => storage,
+      onMergedMemoryWritten: (namespace, storageDir) => {
+        catalogTouches.push({ namespace, storageDir });
+      },
+    });
+
+    assert.deepEqual(result.affectedIds, ["mem-a-001"]);
+    assert.equal(readPair(dir, written.pairId)?.resolution, "keep-b");
+    assert.deepEqual(catalogTouches, [
+      { namespace: "work", storageDir: "/tmp/work-namespace-storage" },
+    ]);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("executeResolution keep-a records NO catalog write touch when resolution persistence fails and rolls back", async () => {
+  const { dir, cleanup } = await makeTempDir();
+  try {
+    const written = writePair(dir, makePair({ namespace: "work" }));
+    const pairFile = path.join(dir, ".review", "contradictions", `${written.pairId}.json`);
+    const storage = makeResolutionStorage({
+      dir: "/tmp/work-namespace-storage",
+      onSupersede: () => {
+        fs.rmSync(pairFile, { force: true });
+      },
+    });
+    const catalogTouches: Array<{ namespace: string | undefined; storageDir: string }> = [];
+
+    const result = await executeResolution(dir, storage, written.pairId, "keep-a", {
+      storageForNamespace: () => storage,
+      onMergedMemoryWritten: (namespace, storageDir) => {
+        catalogTouches.push({ namespace, storageDir });
+      },
+    });
+
+    assert.match(result.message, /Resolution persistence failed; rolled back memory changes/);
+    assert.deepEqual(result.affectedIds, []);
+    assert.deepEqual(catalogTouches, [], "a rolled-back keep-a must not record a catalog write touch");
+    assert.equal(readPair(dir, written.pairId), null);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("executeResolution keep-a records a catalog write touch when resolution persistence fails and rollback is incomplete", async () => {
+  const { dir, cleanup } = await makeTempDir();
+  try {
+    const written = writePair(dir, makePair({ namespace: "work" }));
+    const pairFile = path.join(dir, ".review", "contradictions", `${written.pairId}.json`);
+    const storage = makeResolutionStorage({
+      dir: "/tmp/work-namespace-storage",
+      failRollbackFor: "mem-b-002",
+      onSupersede: () => {
+        fs.rmSync(pairFile, { force: true });
+      },
+    });
+    const catalogTouches: Array<{ namespace: string | undefined; storageDir: string }> = [];
+
+    const result = await executeResolution(dir, storage, written.pairId, "keep-a", {
+      storageForNamespace: () => storage,
+      onMergedMemoryWritten: (namespace, storageDir) => {
+        catalogTouches.push({ namespace, storageDir });
+      },
+    });
+
+    assert.match(result.message, /Resolution persistence failed; rollback incomplete/);
+    assert.equal(storage.memories.get("mem-b-002")?.frontmatter.status, "superseded");
+    assert.equal(storage.memories.get("mem-b-002")?.frontmatter.supersededBy, "mem-a-001");
+    assert.deepEqual(catalogTouches, [
+      { namespace: "work", storageDir: "/tmp/work-namespace-storage" },
+    ]);
+    assert.equal(readPair(dir, written.pairId), null);
+  } finally {
+    await cleanup();
+  }
+});
+
+// Non-mutating verbs never touch the catalog (no namespace memory changed).
+test("executeResolution both-valid records no catalog write touch", async () => {
+  const { dir, cleanup } = await makeTempDir();
+  try {
+    const written = writePair(dir, makePair({ namespace: "work" }));
+    const storage = makeResolutionStorage({ dir: "/tmp/work-namespace-storage" });
+    const catalogTouches: Array<{ namespace: string | undefined; storageDir: string }> = [];
+
+    const result = await executeResolution(dir, storage, written.pairId, "both-valid", {
+      storageForNamespace: () => storage,
+      onMergedMemoryWritten: (namespace, storageDir) => {
+        catalogTouches.push({ namespace, storageDir });
+      },
+    });
+
+    assert.deepEqual(result.affectedIds, []);
+    assert.equal(readPair(dir, written.pairId)?.resolution, "both-valid");
+    assert.deepEqual(catalogTouches, [], "both-valid mutates no namespace memory — no catalog touch");
+  } finally {
+    await cleanup();
+  }
+});
+
 test("executeResolution merge rolls back the first supersession when the second fails", async () => {
   const { dir, cleanup } = await makeTempDir();
   try {
@@ -1948,9 +2157,13 @@ test("executeResolution merge keeps created replacement when rollback fails", as
       failSupersedeFor: "mem-b-002",
       failRollbackFor: "mem-a-001",
     });
+    const catalogTouches: Array<{ namespace: string | undefined; storageDir: string }> = [];
 
     const result = await executeResolution(dir, storage, written.pairId, "merge", {
       mergedContent: "merged canonical fact",
+      onMergedMemoryWritten: (namespace, storageDir) => {
+        catalogTouches.push({ namespace, storageDir });
+      },
     });
 
     const mergedId = storage.supersedeCalls[0]?.newId;
@@ -1960,6 +2173,9 @@ test("executeResolution merge keeps created replacement when rollback fails", as
     assert.equal(storage.memories.get("mem-a-001")?.frontmatter.supersededBy, mergedId);
     assert.equal(storage.memories.get(mergedId)?.content, "merged canonical fact");
     assert.deepEqual(storage.removedFactHashIds, []);
+    assert.deepEqual(catalogTouches, [
+      { namespace: undefined, storageDir: "/tmp/contradiction-namespace-storage" },
+    ]);
     assert.equal(readPair(dir, written.pairId)?.resolution, undefined);
   } finally {
     await cleanup();
@@ -2489,3 +2705,71 @@ test("readPair returns null for non-object JSON", async () => {
     await cleanup();
   }
 });
+
+// ── issue #1499 sweep: a contradiction merge that CREATES a new merged memory
+// writes durable data to the pair's (possibly dynamic) namespace storage,
+// bypassing the extraction write path. executeResolution must invoke
+// onMergedMemoryWritten(namespace, storageDir) so the caller records the catalog
+// write — otherwise a dynamic namespace whose only durable mutation is a merge
+// stays invisible to QMD maintenance / writtenSince.
+test("executeResolution merge fires onMergedMemoryWritten with the pair namespace when a new memory is created", async () => {
+  const { dir, cleanup } = await makeTempDir();
+  try {
+    const written = writePair(dir, makePair({ namespace: "project-origin-dynamic" }));
+    const storage = makeResolutionStorage();
+    (storage as { dir?: string }).dir = "/memory/namespaces/project-origin-dynamic-token";
+
+    const touches: Array<{ namespace?: string; storageDir: string }> = [];
+
+    const result = await executeResolution(dir, storage, written.pairId, "merge", {
+      mergedContent: "merged canonical fact for dynamic namespace",
+      storageForNamespace: () => storage,
+      onMergedMemoryWritten: (namespace, storageDir) => {
+        touches.push({ namespace, storageDir });
+      },
+    });
+
+    assert.deepEqual(result.affectedIds, ["mem-a-001", "mem-b-002"]);
+    assert.equal(touches.length, 1, "exactly one catalog write touch for a created merge memory");
+    assert.equal(
+      touches[0]!.namespace,
+      "project-origin-dynamic",
+      "the catalog touch carries the pair's (dynamic) namespace",
+    );
+    assert.equal(
+      touches[0]!.storageDir,
+      "/memory/namespaces/project-origin-dynamic-token",
+      "the catalog touch carries the resolved namespace storage dir",
+    );
+  } finally {
+    await cleanup();
+  }
+});
+
+// Reusing an EXISTING merged memory id still supersedes BOTH sources — a durable
+// namespace mutation — so the catalog touch MUST fire so `lastWriteAt` refreshes
+// (NH3X3). It fires exactly once, post-commit.
+test("executeResolution merge fires onMergedMemoryWritten exactly once when reusing an existing merged id", async () => {
+  const { dir, cleanup } = await makeTempDir();
+  try {
+    const written = writePair(dir, makePair({ namespace: "project-origin-dynamic" }));
+    const storage = makeResolutionStorage();
+    (storage as { dir?: string }).dir = "/memory/namespaces/project-origin-dynamic-token";
+
+    let touchCount = 0;
+
+    const result = await executeResolution(dir, storage, written.pairId, "merge", {
+      mergedMemoryId: "mem-merged-003", // pre-existing merged memory, sources still superseded
+      storageForNamespace: () => storage,
+      onMergedMemoryWritten: () => {
+        touchCount += 1;
+      },
+    });
+
+    assert.deepEqual(result.affectedIds, ["mem-a-001", "mem-b-002"]);
+    assert.equal(touchCount, 1, "reusing an existing merged memory still supersedes both sources — record one touch");
+    assert.equal(readPair(dir, written.pairId)?.resolution, "merge");
+  } finally {
+    await cleanup();
+  }
+});

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)