@remnic/core 10.0.51 → 10.0.53

package/src/orchestration/maintenance.ts

@@ -22,7 +22,7 @@
 import { resolveNamespaceCapabilities,
   resolveQmdCapabilities,resolveConsolidationCapabilities, resolveRecallAuxiliaryCapabilities } from "../capabilities.js";
 import { existsSync, type Dirent } from "node:fs";
-import { appendFile, lstat, mkdir, readFile, readdir, realpath, stat, writeFile } from "node:fs/promises";
+import { lstat, readdir, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 
 import type { PluginConfig } from "../types.js";
@@ -57,11 +57,8 @@ import {
   maybeRebuildMemoryProjectionScheduled,
   terminateScheduledProjectionRebuilds,
 } from "./projection-rebuild-schedule.js";
-import {
-  drainPendingLifecycleLedgerIfAny,
-  pendingLifecycleLedgerDir,
-  type LifecyclePendingIo,
-} from "../storage/memory-lifecycle-ledger-access.js";
+import { drainPendingLifecycleAppendsForPath } from "./lifecycle-pending-fallback-drain.js";
+import { QmdMaintenanceCompletion } from "./qmd-maintenance-completion.js";
 import { STATE_FILE_MAX_DECRYPT_BYTES } from "../storage/secure-line-reader.js";
 import { createCompoundingWeeklyCron, type CompoundingWeeklySchedulerHandle } from "../compounding/weekly-scheduler.js";
 import { startLocationAutoSync, type LocationAutoSyncHandle } from "../location/scheduler.js";
@@ -70,7 +67,7 @@ import type { ActivitySyncRunSummary } from "../activity/runner.js";
 import { resolveHomeDir } from "../runtime/env.js";
 import { log } from "../logger.js";
 import { isErrnoCode } from "../utils/errno.js";
-import { assertPathInsideRoot, listContainedSpillFiles } from "../utils/path-containment.js";
+import { assertPathInsideRoot } from "../utils/path-containment.js";
 import {
   probeEncryptedRegularFileHeader,
   SECURE_STORE_ENVELOPE_OVERHEAD_BYTES,
@@ -137,6 +134,9 @@ export class MaintenanceScheduler {
   private qmdMaintenanceTimer: NodeJS.Timeout | null = null;
   private qmdMaintenancePending = false;
   private qmdMaintenanceInFlight = false;
+  private readonly qmdCompletion = new QmdMaintenanceCompletion();
+  /** Namespaces that ran in passes of the request still waiting for full coverage. */
+  private readonly qmdCoveredNamespaces = new Set<string>();
   private lastQmdEmbedAtMs = 0;
   private lastQmdEmbedAtMsByNamespace = new Map<string, number>();
 
@@ -476,13 +476,13 @@ export class MaintenanceScheduler {
   // QMD maintenance scheduling (debounced + singleflight)
   // ───────────────────────────────────────────────────────────────────────
 
-  /** Internal: queue a debounced QMD maintenance pass. */
-  private requestQmdMaintenance(): void {
-    if (!this.deps.getQmd().isAvailable()) return;
-    if (!resolveQmdCapabilities(this.deps.config).qmdMaintenance) return;
+  /** Internal: queue a debounced QMD maintenance pass; false when nothing could be armed. */
+  private requestQmdMaintenance(): boolean {
+    if (!this.deps.getQmd().isAvailable()) return false;
+    if (!resolveQmdCapabilities(this.deps.config).qmdMaintenance) return false;
 
     this.qmdMaintenancePending = true;
-    if (this.qmdMaintenanceTimer) return;
+    if (this.qmdMaintenanceTimer) return true;
 
     this.qmdMaintenanceTimer = setTimeout(() => {
       this.qmdMaintenanceTimer = null;
@@ -490,6 +490,18 @@ export class MaintenanceScheduler {
         log.debug(`background qmd maintenance failed: ${err}`),
       );
     }, this.deps.config.qmdMaintenanceDebounceMs);
+    return true;
+  }
+
+  /**
+   * Like a maintenance request, but resolves true only once a pass that started
+   * after it completed successfully. False when nothing could be armed (QMD
+   * unavailable or maintenance off), the pass failed, or dispose() abandoned it,
+   * so a caller that must not lose the re-index keeps owing it.
+   */
+  requestQmdMaintenanceCompletion(): Promise<boolean> {
+    if (this.disposed || !this.requestQmdMaintenance()) return Promise.resolve(false);
+    return this.qmdCompletion.wait();
   }
 
   /**
@@ -530,6 +542,10 @@ export class MaintenanceScheduler {
     if (!this.qmdMaintenancePending) return;
     this.qmdMaintenanceInFlight = true;
     this.qmdMaintenancePending = false;
+    // Waiters claimed here are served by THIS pass; later requests wait for the next.
+    const settle = this.qmdCompletion.claim();
+    let served = false;
+    let deferred = false;
 
     try {
       if (resolveNamespaceCapabilities(this.deps.config).namespaces) {
@@ -555,7 +571,7 @@ export class MaintenanceScheduler {
           }
           this.lastQmdEmbedAtMs = now;
         };
-        await runNamespaceMaintenanceBatchPlan(
+        const summary = await runNamespaceMaintenanceBatchPlan(
           this.deps.config,
           plan,
           async (candidates) => {
@@ -605,8 +621,46 @@ export class MaintenanceScheduler {
             skipReasonForError: qmdMaintenanceSkipReasonForError,
           },
         );
+        // Namespaces skipped for a TRANSIENT reason (budget_exhausted, lock_held) were not covered
+        // by this pass. They are covered once they ran in this or an earlier pass of the same
+        // request, so a deployment with more namespaces than the cycle budget still converges.
+        // Permanent skip reasons describe namespaces this deployment never re-indexes.
+        const covered = this.qmdCoveredNamespaces;
+        const before = covered.size;
+        for (const status of summary.statuses) {
+          if (status.state === "ran") covered.add(status.namespace);
+        }
+        const uncovered = summary.statuses.some(
+          (status) =>
+            status.state === "skipped" &&
+            (status.reason === "budget_exhausted" || status.reason === "lock_held") &&
+            !covered.has(status.namespace),
+        );
+        served = summary.ran > 0 && summary.failed === 0 && !uncovered;
+        // Partial progress keeps the waiters for another pass; no progress (or a failure) ends the
+        // request unserved so a stuck namespace cannot re-arm passes forever.
+        deferred = !served && summary.failed === 0 && covered.size > before && !this.disposed;
       } else {
-        await this.deps.getQmd().update();
+        const qmd = this.deps.getQmd();
+        // Plain update() is fail-open on every backend: it resolves when the min-interval gate,
+        // failure backoff or an early exit suppressed it, and when it errored. Only the variants
+        // that report whether an update ran count (updateCompleted, else QMD's updateStrict).
+        if (qmd.updateCompleted) {
+          try {
+            served = await qmd.updateCompleted();
+          } catch (err) {
+            log.debug(`qmd maintenance update did not run: ${err}`);
+          }
+        } else if (qmd.updateStrict) {
+          try {
+            await qmd.updateStrict();
+            served = true;
+          } catch (err) {
+            log.debug(`qmd maintenance update did not run: ${err}`);
+          }
+        } else {
+          await qmd.update();
+        }
         const now = Date.now();
         if (
           resolveQmdCapabilities(this.deps.config).qmdAutoEmbed &&
@@ -624,7 +678,10 @@ export class MaintenanceScheduler {
       // backoff) does not advance lastUpdateRanAtMs, so it leaves caches warm
       // (#1904, Codex/Cursor).
     } finally {
+      settle(served, deferred);
+      if (!deferred) this.qmdCoveredNamespaces.clear();
       this.qmdMaintenanceInFlight = false;
+      if (deferred) this.qmdMaintenancePending = true;
       if (this.qmdMaintenancePending) {
         this.requestQmdMaintenance();
       }
@@ -772,7 +829,7 @@ export class MaintenanceScheduler {
     if (target.storage) {
       await this.drainPendingLifecycleAppends(target.storage);
     } else {
-      await this.drainPendingLifecycleAppendsForPath(target.memoryDir);
+      await drainPendingLifecycleAppendsForPath(target.memoryDir);
     }
   }
 
@@ -787,86 +844,6 @@ export class MaintenanceScheduler {
     }
   }
 
-  /**
-   * Drain a filesystem-fallback target's pending lifecycle-append spill when no
-   * secure StorageManager is available (catalog-disabled namespace; issue
-   * #2033). Uses the safe path-scoped PLAINTEXT context this fallback already
-   * operates in: a keyless drain can only fold plaintext spills into a plaintext
-   * ledger, so it refuses when the ledger or ANY spill is encrypted at rest,
-   * leaving those pending for a keyed (catalog-path) drain — exactly mirroring
-   * the fallback compaction's encrypted-ledger deferral. Non-fatal; a fast
-   * no-op when nothing is pending. The shared spill lister enforces the symlink/
-   * containment guard on every spill file it reads or deletes.
-   */
-  private async drainPendingLifecycleAppendsForPath(memoryDir: string): Promise<void> {
-    const ledgerPath = path.join(memoryDir, "state", "memory-lifecycle-ledger.jsonl");
-    const spillDir = pendingLifecycleLedgerDir(ledgerPath);
-    // Enumerate spills through the SAME guarded lister the actual drain uses
-    // (listContainedSpillFiles): it rejects a symlinked/non-directory spill dir
-    // and skips any symlink/FIFO/device/escaping entry, returning only regular
-    // files contained in the dir. Never raw-readdir + open() an untrusted name:
-    // opening a FIFO would block until a writer appears and a symlink would
-    // redirect the probe outside the dir (#2033). Enumerate BOTH live `*.jsonl`
-    // spills and crash-orphaned `*.jsonl.claimed` files: a drain that died
-    // between claiming a spill (rename to `.claimed`) and committing it leaves
-    // the ONLY copy of those rows as a claimed orphan. Gating solely on live
-    // spills would early-return here whenever the pending dir holds nothing but
-    // orphans, stranding those rows forever; proceeding lets
-    // drainPendingLifecycleLedgerIfAny -> recoverOrphanedClaims restore and
-    // re-commit them under the ledger lock (#2033).
-    let spillFiles: string[];
-    let claimedOrphans: string[];
-    try {
-      spillFiles = await listContainedSpillFiles(spillDir);
-      claimedOrphans = await listContainedSpillFiles(spillDir, ".jsonl.claimed");
-    } catch (err) {
-      log.debug(`fallback lifecycle pending scan failed (non-fatal) for ${memoryDir}: ${err}`);
-      return;
-    }
-    if (spillFiles.length === 0 && claimedOrphans.length === 0) return;
-    // The pending encryption state is authoritative only UNDER the ledger lock:
-    // drainPendingLifecycleLedgerIfAny waits for the lock and re-enumerates the
-    // pending dir, so a secure-store writer that spills an encrypted file — or a
-    // keyed compaction that rewrites the ledger encrypted — while this fallback
-    // waits would defeat any pre-lock probe (#2033). Probe each file at the
-    // moment of use inside the held lock instead: readSecure refuses an
-    // encrypted spill (the fold reads each spill lazily and propagates the throw
-    // BEFORE claiming that spill, leaving it intact) and the append refuses a
-    // ledger that became encrypted (the fold rolls the claims back). Either way
-    // the plaintext IO
-    // never reads or writes ciphertext; the keyed catalog-path drain handles the
-    // deferred rows.
-    const io: LifecyclePendingIo = {
-      writeSecure: async (filePath, payload) => {
-        await mkdir(path.dirname(filePath), { recursive: true });
-        await writeFile(filePath, payload, "utf-8");
-      },
-      readSecure: async (filePath) => {
-        if (await probeEncryptedRegularFileHeader(filePath)) {
-          throw new Error(`fallback lifecycle drain deferred: encrypted spill at ${filePath}`);
-        }
-        return readFile(filePath, "utf-8");
-      },
-    };
-    try {
-      await drainPendingLifecycleLedgerIfAny(
-        ledgerPath,
-        io,
-        async (payload) => {
-          if (await probeEncryptedRegularFileHeader(ledgerPath)) {
-            throw new Error(`fallback lifecycle drain deferred: ledger became encrypted at ${ledgerPath}`);
-          }
-          await appendFile(ledgerPath, payload, "utf-8");
-        },
-        async () => {
-          await mkdir(path.dirname(ledgerPath), { recursive: true });
-        },
-      );
-    } catch (err) {
-      log.debug(`fallback lifecycle pending drain failed (non-fatal) for ${memoryDir}: ${err}`);
-    }
-  }
-
   /**
    * Enumerate the lifecycle ledgers to consider for compaction: the root
    * (through the secure-configured root storage when available) plus every
@@ -1186,6 +1163,7 @@ export class MaintenanceScheduler {
       this.qmdMaintenanceTimer = null;
     }
     this.qmdMaintenancePending = false;
+    this.qmdCompletion.abandon();
     await activityDrain;
     await locationDrain; await weeklyDrain;
     // Belt-and-suspenders: clear anything a late tick armed before the latch.

package/src/orchestration/qmd-maintenance-completion.ts

@@ -0,0 +1,32 @@
+/**
+ * Callers that must know the re-index actually ran (the entity-migration
+ * pending marker, issue #3286) cannot rely on arming the debounced timer: a
+ * crash or dispose() inside the debounce window would lose the request. They
+ * wait here instead; the scheduler claims the waiters when a pass starts and
+ * settles them with the pass outcome, and abandons them on dispose().
+ */
+export class QmdMaintenanceCompletion {
+  private waiters: Array<(served: boolean) => void> = [];
+
+  /** Resolves true when a pass that started after this call completed successfully. */
+  wait(): Promise<boolean> {
+    return new Promise((resolve) => this.waiters.push(resolve));
+  }
+
+  /**
+   * A pass is starting: take every waiter it will serve and return their settle function.
+   * `defer` keeps them waiting for a later pass (a pass that covered only part of the selection).
+   */
+  claim(): (served: boolean, defer?: boolean) => void {
+    const claimed = this.waiters.splice(0);
+    return (served, defer = false) => {
+      if (defer) this.waiters.unshift(...claimed);
+      else claimed.forEach((resolve) => resolve(served));
+    };
+  }
+
+  /** The scheduler stopped: nothing will serve the waiters. */
+  abandon(): void {
+    this.claim()(false);
+  }
+}

package/src/orchestrator-entity-write-failure.test.ts

@@ -0,0 +1,370 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+
+import { SmartBuffer } from "./buffer.js";
+import { resetExtractionLlmHealthForTests } from "./extraction-llm-health.js";
+import { Orchestrator } from "./orchestrator.js";
+import { ContentHashIndex } from "./storage.js";
+import {
+  cleanupDir,
+  harmonicNodeStoreStatus,
+  makeHarmonicLifecycleConfig,
+  makeLifecycleConfig,
+  mkTempMemoryDir,
+  stubExtraction,
+} from "./testing/orchestrator-lite.js";
+import type { ExtractionResult } from "./types.js";
+
+/** Owner contract for the private Orchestrator temporal/tag batch hook. */
+const FACT = "Project Alpha uses a queue for background processing.";
+
+for (const includeFact of [false, true]) {
+  test(`#3228: entity write failure retains input${includeFact ? " after a committed fact" : ""}`, async () => {
+    const memoryDir = await mkTempMemoryDir("entity-write-failure");
+    const config = makeLifecycleConfig(memoryDir, {
+      chunkingEnabled: false,
+      multiGraphMemoryEnabled: false,
+      factDeduplicationEnabled: true,
+      extractionMinImportanceLevel: "trivial",
+      entityActivityLogEnabled: false,
+    });
+    const orchestrator = new Orchestrator(config);
+    const storage = await orchestrator.getStorageForNamespace();
+    const writeEntity = storage.writeEntity.bind(storage);
+    try {
+      await storage.ensureDirectories();
+      const entityName = storage.normalizeEntityName("Alpha", "project");
+      await orchestrator.buffer.load();
+      const bufferKey = "entity-write-failure";
+      await orchestrator.buffer.addTurn(bufferKey, {
+        role: "user",
+        content: FACT,
+        sessionKey: bufferKey,
+        timestamp: "2026-10-01T12:00:00.000Z",
+        sourceValidAt: "2026-10-01T12:00:00.000Z",
+        persistProcessedFingerprint: true,
+      });
+      await orchestrator.buffer.flushPendingSave({ throwOnFailure: true });
+      const turns = orchestrator.buffer.getTurns(bufferKey);
+      assert.equal(turns.length, 1, "the source turn must be durably buffered before extraction");
+      const before = await storage.loadMeta();
+      const extractionCalls = stubExtraction(orchestrator, (): ExtractionResult => ({
+        facts: includeFact
+          ? [{ content: FACT, category: "fact", confidence: 0.9, tags: [] }]
+          : [],
+        entities: [{ name: "Alpha", type: "project", facts: ["Uses a queue"] }],
+        questions: [],
+        profileUpdates: [],
+      }));
+      const writeFailure = Object.assign(new Error("synthetic entity write denied"), { code: "EACCES" });
+      let entityWriteAttempts = 0;
+      storage.writeEntity = async (...args: Parameters<typeof writeEntity>) => {
+        entityWriteAttempts += 1;
+        assert.deepEqual(args.slice(0, 3), ["Alpha", "project", ["Uses a queue"]]);
+        throw writeFailure;
+      };
+      let commits = 0;
+      const options = { bufferKey, onDurableCommit: () => { commits += 1; } };
+
+      await assert.rejects(
+        orchestrator.runExtraction(turns, options),
+        (error: Error) => error === writeFailure,
+        "the original entity I/O failure must reach the caller",
+      );
+      assert.equal(entityWriteAttempts, 1, "the failure must come from the real entity persistence path");
+      assert.equal(commits, 0, "a failed batch must not signal durable completion");
+      assert.deepEqual(orchestrator.buffer.getTurns(bufferKey), turns);
+      const retainedBuffer = new SmartBuffer(config, storage);
+      await retainedBuffer.load();
+      assert.deepEqual(retainedBuffer.getTurns(bufferKey), turns, "source turns must remain on disk too");
+      const failedMeta = await storage.loadMeta();
+      assert.equal(failedMeta.processedExtractionFingerprints?.length ?? 0, 0);
+      assert.equal(failedMeta.extractionCount, before.extractionCount);
+      assert.equal(await storage.readEntity(entityName), "", "the failed entity was not written");
+
+      const factsBeforeRetry = (await storage.readAllMemories()).filter((m) => m.frontmatter.category === "fact");
+      assert.equal(factsBeforeRetry.length, includeFact ? 1 : 0);
+      if (includeFact) {
+        const hashes = new ContentHashIndex(path.join(storage.dir, "state"));
+        await hashes.load();
+        assert.equal(hashes.has(FACT), true, "the earlier fact's deferred hash must be durable before rejection");
+      }
+
+      storage.writeEntity = writeEntity;
+      const retried = await orchestrator.runExtraction(turns, options);
+      assert.equal(retried.status, "completed");
+      assert.equal(retried.persistedCount, 1, "retry writes the entity, not another copy of an earlier fact");
+      assert.equal(commits, 1);
+      assert.match(await storage.readEntity(entityName), /Uses a queue/);
+      assert.equal((await storage.listEntityNames()).length, 1);
+      const factsAfterRetry = (await storage.readAllMemories()).filter((m) => m.frontmatter.category === "fact");
+      assert.deepEqual(
+        factsAfterRetry.map((m) => m.frontmatter.id),
+        factsBeforeRetry.map((m) => m.frontmatter.id),
+        "retry must preserve the already committed fact without duplicating it",
+      );
+      assert.equal((await storage.loadMeta()).processedExtractionFingerprints?.length, 1);
+      assert.equal(orchestrator.buffer.getTurns(bufferKey).length, 0);
+      const clearedBuffer = new SmartBuffer(config, storage);
+      await clearedBuffer.load();
+      assert.equal(clearedBuffer.getTurns(bufferKey).length, 0);
+      assert.equal((await orchestrator.runExtraction(turns, options)).reason, "processed_fingerprint");
+      assert.equal(extractionCalls.length, 2, "only the failed attempt and successful retry call the extractor");
+      assert.equal(commits, 1, "processed replay must not emit a second commit");
+    } finally {
+      storage.writeEntity = writeEntity;
+      try {
+        await orchestrator.destroy();
+      } finally {
+        resetExtractionLlmHealthForTests();
+        await cleanupDir(memoryDir);
+      }
+    }
+  });
+}
+
+test("#3231: entity failure after a committed fact still runs deferred post-write maintenance", async () => {
+  // Partial-success path: fact (preference) is durable, later writeEntity throws.
+  // Batch-end finalization in persistExtraction (hash flush, behavior ledger,
+  // harmonic construction, temporal/tag index) and runExtraction's
+  // requestQmdMaintenance must still cover the earlier durable write. Retry
+  // exact-dedupes the fact (`continue`), so those effects are not re-queued.
+  const memoryDir = await mkTempMemoryDir("entity-write-failure-maintenance");
+  const preference =
+    "Prefers terse queue names for background jobs in Project Alpha.";
+  const config = makeHarmonicLifecycleConfig(memoryDir, {
+    chunkingEnabled: false,
+    multiGraphMemoryEnabled: false,
+    factDeduplicationEnabled: true,
+    extractionMinImportanceLevel: "trivial",
+    entityActivityLogEnabled: false,
+    queryAwareIndexingEnabled: true,
+  });
+  const orchestrator = new Orchestrator(config);
+  const storage = await orchestrator.getStorageForNamespace();
+  const writeEntity = storage.writeEntity.bind(storage);
+  const temporalIdBatches: string[][] = [];
+  // Bracket access is TypeScript's typed escape hatch for the private method; the spy only wraps and restores it.
+  const originalTemporal = orchestrator["updateTemporalTagIndexes"].bind(orchestrator);
+  orchestrator["updateTemporalTagIndexes"] = async (target, persistedIds) => {
+    temporalIdBatches.push([...persistedIds]);
+    return originalTemporal(target, persistedIds);
+  };
+  let qmdMaintenanceCalls = 0;
+  const originalQmd = orchestrator.requestQmdMaintenance.bind(orchestrator);
+  orchestrator.requestQmdMaintenance = () => {
+    qmdMaintenanceCalls += 1;
+    originalQmd();
+  };
+  try {
+    await storage.ensureDirectories();
+    await orchestrator.buffer.load();
+    const bufferKey = "entity-write-failure-maintenance";
+    await orchestrator.buffer.addTurn(bufferKey, {
+      role: "user",
+      content: preference,
+      sessionKey: bufferKey,
+      timestamp: "2026-10-01T12:00:00.000Z",
+      sourceValidAt: "2026-10-01T12:00:00.000Z",
+      persistProcessedFingerprint: true,
+    });
+    await orchestrator.buffer.flushPendingSave({ throwOnFailure: true });
+    const turns = orchestrator.buffer.getTurns(bufferKey);
+    assert.equal(turns.length, 1);
+    stubExtraction(orchestrator, (): ExtractionResult => ({
+      facts: [
+        {
+          content: preference,
+          category: "preference",
+          confidence: 0.95,
+          tags: ["queue-naming"],
+        },
+      ],
+      entities: [{ name: "Alpha", type: "project", facts: ["Uses a queue"] }],
+      questions: [],
+      profileUpdates: [],
+    }));
+    const writeFailure = Object.assign(new Error("synthetic entity write denied"), {
+      code: "EACCES",
+    });
+    storage.writeEntity = async () => {
+      throw writeFailure;
+    };
+
+    await assert.rejects(
+      orchestrator.runExtraction(turns, { bufferKey }),
+      (error: Error) => error === writeFailure,
+      "entity I/O failure must still reach the caller",
+    );
+
+    const facts = (await storage.readAllMemories()).filter(
+      (m) => m.frontmatter.category === "preference",
+    );
+    assert.equal(facts.length, 1, "the preference fact must remain durable");
+    const factId = facts[0]!.frontmatter.id;
+    const hashes = new ContentHashIndex(path.join(storage.dir, "state"));
+    await hashes.load();
+    assert.equal(hashes.has(preference), true, "deferred fact hash must flush before rejection");
+
+    const signals = await storage.readBehaviorSignals(50);
+    assert.ok(
+      signals.some(
+        (s) => s.memoryId === factId && s.signalType === "preference_affinity",
+      ),
+      "batch-end behavior-signal append must cover the committed preference before rethrow",
+    );
+
+    const harmonic = await harmonicNodeStoreStatus(memoryDir);
+    assert.equal(harmonic.nodes.invalid, 0);
+    assert.ok(
+      harmonic.nodes.valid > 0 && (harmonic.latestNode?.sourceMemoryIds ?? []).includes(factId),
+      "batch-end harmonic construction must cover the committed fact before rethrow",
+    );
+
+    assert.ok(
+      temporalIdBatches.some((ids) => ids.includes(factId)),
+      "batch-end temporal/tag index update must include the committed fact before rethrow",
+    );
+    assert.ok(
+      qmdMaintenanceCalls > 0,
+      "partial durable writes must still schedule QMD reindex before the entity error propagates",
+    );
+
+    // Retry exact-dedupes the preference (`continue`), so missing deferred
+    // effects are not re-queued. Prove the failure-path finalization is the
+    // only chance they have to land.
+    storage.writeEntity = writeEntity;
+    const retried = await orchestrator.runExtraction(turns, { bufferKey });
+    assert.equal(retried.status, "completed");
+    assert.equal(
+      (await storage.readAllMemories()).filter((m) => m.frontmatter.category === "preference").length,
+      1,
+      "retry must not duplicate the already-committed preference",
+    );
+    assert.ok(
+      (await storage.readBehaviorSignals(50)).some(
+        (s) => s.memoryId === factId && s.signalType === "preference_affinity",
+      ),
+      "behavior signals must survive retry without relying on re-queue from the deduped fact",
+    );
+    assert.ok(
+      ((await harmonicNodeStoreStatus(memoryDir)).latestNode?.sourceMemoryIds ?? []).includes(factId),
+      "harmonic records must survive retry without relying on re-queue from the deduped fact",
+    );
+  } finally {
+    storage.writeEntity = writeEntity;
+    orchestrator.requestQmdMaintenance = originalQmd;
+    orchestrator["updateTemporalTagIndexes"] = originalTemporal;
+    try {
+      await orchestrator.destroy();
+    } finally {
+      resetExtractionLlmHealthForTests();
+      await cleanupDir(memoryDir);
+    }
+  }
+});
+
+test("#3231 P2: a post-write contradiction-resolve failure still finalizes the durable fact", async () => {
+  // The fact is durable (writeSealedMemory returned) when
+  // applyDeferredContradictionResolve rejects. Its behavior signal, harmonic
+  // node, temporal/tag index entry and QMD request must not depend on code
+  // that runs after that catch; retry exact-dedupes the fact.
+  const memoryDir = await mkTempMemoryDir("contradiction-resolve-failure-maintenance");
+  const preference = "Prefers terse queue names for background jobs in Project Beta.";
+  const config = makeHarmonicLifecycleConfig(memoryDir, {
+    chunkingEnabled: false,
+    multiGraphMemoryEnabled: false,
+    factDeduplicationEnabled: true,
+    extractionMinImportanceLevel: "trivial",
+    entityActivityLogEnabled: false,
+    queryAwareIndexingEnabled: true,
+  });
+  const orchestrator = new Orchestrator(config);
+  const storage = await orchestrator.getStorageForNamespace();
+  const temporalIdBatches: string[][] = [];
+  const originalTemporal = orchestrator["updateTemporalTagIndexes"].bind(orchestrator);
+  orchestrator["updateTemporalTagIndexes"] = async (target, persistedIds) => {
+    temporalIdBatches.push([...persistedIds]);
+    return originalTemporal(target, persistedIds);
+  };
+  let qmdMaintenanceCalls = 0;
+  const originalQmd = orchestrator.requestQmdMaintenance.bind(orchestrator);
+  orchestrator.requestQmdMaintenance = () => {
+    qmdMaintenanceCalls += 1;
+    originalQmd();
+  };
+  const originalResolve = orchestrator["applyDeferredContradictionResolve"].bind(orchestrator);
+  const resolveFailure = new Error("synthetic contradiction resolve failure");
+  orchestrator["applyDeferredContradictionResolve"] = async () => {
+    throw resolveFailure;
+  };
+  try {
+    await storage.ensureDirectories();
+    await orchestrator.buffer.load();
+    const bufferKey = "contradiction-resolve-failure-maintenance";
+    await orchestrator.buffer.addTurn(bufferKey, {
+      role: "user",
+      content: preference,
+      sessionKey: bufferKey,
+      timestamp: "2026-10-01T12:00:00.000Z",
+      sourceValidAt: "2026-10-01T12:00:00.000Z",
+      persistProcessedFingerprint: true,
+    });
+    await orchestrator.buffer.flushPendingSave({ throwOnFailure: true });
+    const turns = orchestrator.buffer.getTurns(bufferKey);
+    stubExtraction(orchestrator, (): ExtractionResult => ({
+      facts: [
+        {
+          content: preference,
+          category: "preference",
+          confidence: 0.95,
+          tags: ["queue-naming"],
+        },
+      ],
+      entities: [],
+      questions: [],
+      profileUpdates: [],
+    }));
+
+    await assert.rejects(
+      orchestrator.runExtraction(turns, { bufferKey }),
+      (error: Error) => error === resolveFailure,
+      "the post-write failure must still reach the caller",
+    );
+
+    const facts = (await storage.readAllMemories()).filter(
+      (m) => m.frontmatter.category === "preference",
+    );
+    assert.equal(facts.length, 1, "the preference fact must remain durable");
+    const factId = facts[0]!.frontmatter.id;
+    assert.ok(
+      (await storage.readBehaviorSignals(50)).some(
+        (s) => s.memoryId === factId && s.signalType === "preference_affinity",
+      ),
+      "the durable fact's behavior signal must land before the rethrow",
+    );
+    assert.ok(
+      ((await harmonicNodeStoreStatus(memoryDir)).latestNode?.sourceMemoryIds ?? []).includes(factId),
+      "the durable fact's harmonic node must land before the rethrow",
+    );
+    assert.ok(
+      temporalIdBatches.some((ids) => ids.includes(factId)),
+      "the durable fact's temporal/tag index update must run before the rethrow",
+    );
+    assert.ok(
+      qmdMaintenanceCalls > 0,
+      "a durable fact that is the only write must still schedule QMD reindex",
+    );
+  } finally {
+    orchestrator["applyDeferredContradictionResolve"] = originalResolve;
+    orchestrator.requestQmdMaintenance = originalQmd;
+    orchestrator["updateTemporalTagIndexes"] = originalTemporal;
+    try {
+      await orchestrator.destroy();
+    } finally {
+      resetExtractionLlmHealthForTests();
+      await cleanupDir(memoryDir);
+    }
+  }
+});