@remnic/core 10.0.94 → 10.0.96

package/src/harmonic-retrieval.ts

@@ -2,6 +2,7 @@ import path from "node:path";
 import { realpath } from "node:fs/promises";
 import { listJsonFilesStrict, readJsonFile } from "./json-store.js";
 import { throwIfAborted } from "./abort-error.js";
+import { readHarmonicGraphStamp } from "./harmonic-graph-version.js";
 import { inferMemoryStatus, toMemoryPathRel } from "./memory-lifecycle-ledger-utils.js";
  import {
    HARMONIC_SOURCE_MEMORY_INSERTED_AT_KEY,
@@ -403,7 +404,7 @@ export interface ProjectedHarmonicGraph {
  *   one of that node's surviving active sources, and is dropped once no
  *   reference survives.
  */
-export async function readProjectedHarmonicGraph(options: {
+async function buildProjectedHarmonicGraph(options: {
   memoryDir: string;
   abstractionNodeStoreDir?: string;
   anchorsEnabled: boolean;
@@ -460,6 +461,90 @@ export async function readProjectedHarmonicGraph(options: {
   return { nodes: projectedNodes, anchors };
 }
 
+const GRAPH_CACHE_TTL_MS = 30_000;
+const GRAPH_CACHE_MAX_ENTRIES = 8;
+
+interface GraphCacheEntry {
+  stamp: string;
+  startedAtMs: number;
+  graph: ProjectedHarmonicGraph;
+}
+
+const graphCache = new Map<string, GraphCacheEntry>();
+/** Counters for tests and diagnostics. */
+export const harmonicGraphCacheStats = { hits: 0, misses: 0 };
+
+/** Freeze records and their nested arrays/objects so a caller cannot corrupt the shared cache. */
+function deepFreeze<T extends object>(value: T): T {
+  // isFrozen is true for primitives and null, and a frozen value is not revisited, so this ends on cycles too.
+  if (Object.isFrozen(value)) return value;
+  Object.freeze(value);
+  for (const child of Object.values(value)) deepFreeze(child);
+  return value;
+}
+
+export function clearHarmonicGraphCache(): void {
+  graphCache.clear();
+}
+
+/**
+ * `readProjectedHarmonicGraph` with an opt-in in-memory cache. Every recall used
+ * to re-read all nodes, anchors and source memories from disk (about 4.7 s on a
+ * 2107 node, 9199 anchor, 4105 source graph). With `useCache` a completed graph is
+ * reused while the stamp below is unchanged: the memory corpus, memory status and
+ * cold-write version sentinels (bumped by every memory write, in any process) and
+ * the graph version sentinel (bumped by node and anchor writes). A stamp read is
+ * four stats, not a scan of the memories. The TTL bounds the one input a sentinel
+ * cannot see, which is wall-clock validity expiry. An explicit `nowMs` bypasses the
+ * cache so tests stay deterministic. The cached arrays are frozen: callers must not
+ * mutate them.
+ */
+export async function readProjectedHarmonicGraph(options: {
+  memoryDir: string;
+  abstractionNodeStoreDir?: string;
+  anchorsEnabled: boolean;
+  abortSignal?: AbortSignal;
+  temporalExpiredInInjection?: boolean;
+  nowMs?: number;
+  useCache?: boolean;
+}): Promise<ProjectedHarmonicGraph> {
+  if (options.useCache !== true || options.nowMs !== undefined) return buildProjectedHarmonicGraph(options);
+  // Same cancellation contract as the builder: a cache hit must not mask an aborted signal.
+  throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
+  const nodeStoreDir = resolveAbstractionNodeStoreDir(options.memoryDir, options.abstractionNodeStoreDir);
+  const key = JSON.stringify([
+    options.memoryDir,
+    nodeStoreDir,
+    options.anchorsEnabled === true,
+    options.temporalExpiredInInjection === true,
+  ]);
+  // The stamp is read BEFORE the build, so a write that lands mid-build leaves the
+  // entry stale and the next call rebuilds.
+  const stamp = readHarmonicGraphStamp(options.memoryDir, nodeStoreDir);
+  const startedAtMs = Date.now();
+  const hit = graphCache.get(key);
+  if (hit && hit.stamp === stamp && startedAtMs - hit.startedAtMs < GRAPH_CACHE_TTL_MS) {
+    harmonicGraphCacheStats.hits++;
+    graphCache.delete(key);
+    graphCache.set(key, hit);
+    return hit.graph;
+  }
+  harmonicGraphCacheStats.misses++;
+  const built = await buildProjectedHarmonicGraph(options);
+  const graph = {
+    nodes: deepFreeze(built.nodes),
+    anchors: deepFreeze(built.anchors),
+  };
+  graphCache.delete(key);
+  graphCache.set(key, { stamp, startedAtMs, graph });
+  while (graphCache.size > GRAPH_CACHE_MAX_ENTRIES) {
+    const oldest = graphCache.keys().next().value;
+    if (oldest === undefined) break;
+    graphCache.delete(oldest);
+  }
+  return graph;
+}
+
 export async function searchHarmonicRetrieval(options: {
   memoryDir: string;
   abstractionNodeStoreDir?: string;
@@ -469,6 +554,8 @@ export async function searchHarmonicRetrieval(options: {
   anchorsEnabled: boolean;
   abortSignal?: AbortSignal;
   temporalExpiredInInjection?: boolean;
+  /** Share one projected graph between recalls until a write bumps a version sentinel (see readProjectedHarmonicGraph). */
+  useGraphCache?: boolean;
 }): Promise<HarmonicRetrievalResult[]> {
   throwIfAborted(options.abortSignal, "harmonic retrieval aborted");
   const queryTokens = new Set(normalizeRecallTokens(options.query, ["what", "which"]));
@@ -476,7 +563,10 @@ export async function searchHarmonicRetrieval(options: {
 
   // One projection for every graph reader: nodes and anchors both arrive
   // already narrowed to the namespace's current active memories.
-  const { nodes: eligibleNodes, anchors } = await readProjectedHarmonicGraph(options);
+  const { nodes: eligibleNodes, anchors } = await readProjectedHarmonicGraph({
+    ...options,
+    useCache: options.useGraphCache === true,
+  });
   const candidates = new Map<string, HarmonicCandidate>();
 
   for (const node of eligibleNodes) {

package/src/orchestration/extraction-persist-failure.test.ts

@@ -0,0 +1,90 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { CommittedWriteFinalization } from "./extraction-persist-failure.js";
+
+function recordingFinalizer() {
+  const calls: boolean[] = [];
+  return {
+    calls,
+    finalize: async (scheduleQmd: boolean) => {
+      calls.push(scheduleQmd);
+    },
+  };
+}
+
+test("#3288: the bound finalizer runs once across the success tail and catch sites", async () => {
+  const finalization = new CommittedWriteFinalization();
+  const { calls, finalize } = recordingFinalizer();
+  const once = finalization.bind(finalize);
+
+  const value = await finalization.run(async () => {
+    await once(true);
+    await once(false);
+    return "persisted";
+  });
+
+  assert.equal(value, "persisted");
+  assert.deepEqual(calls, [true], "a second caller reuses the first run instead of finalizing again");
+});
+
+test("#3288: the pass boundary finalizes with QMD scheduling, then rethrows the original error", async () => {
+  const finalization = new CommittedWriteFinalization();
+  const { calls, finalize } = recordingFinalizer();
+  const cause = new Error("branch without its own catch site");
+
+  await assert.rejects(
+    finalization.run(async () => {
+      finalization.bind(finalize);
+      throw cause;
+    }),
+    (error: Error) => error === cause,
+  );
+  assert.deepEqual(calls, [true]);
+});
+
+test("#3288: the pass boundary does not finalize again after a catch site already did", async () => {
+  const finalization = new CommittedWriteFinalization();
+  const { calls, finalize } = recordingFinalizer();
+  const cause = new Error("catch site rethrow");
+
+  await assert.rejects(
+    finalization.run(async () => {
+      const once = finalization.bind(finalize);
+      await once(true);
+      throw cause;
+    }),
+    (error: Error) => error === cause,
+  );
+  assert.deepEqual(calls, [true]);
+});
+
+test("#3288: a throw before the finalizer is bound propagates without finalizing", async () => {
+  const finalization = new CommittedWriteFinalization();
+  const cause = new Error("failed before any write");
+
+  await assert.rejects(
+    finalization.run(async () => {
+      throw cause;
+    }),
+    (error: Error) => error === cause,
+  );
+});
+
+test("#3288: a failing finalizer does not mask the original error", async () => {
+  const finalization = new CommittedWriteFinalization();
+  const cause = new Error("branch failure");
+  let attempts = 0;
+
+  await assert.rejects(
+    finalization.run(async () => {
+      finalization.bind(async () => {
+        attempts += 1;
+        throw new Error("finalization failure");
+      });
+      throw cause;
+    }),
+    (error: Error) => error === cause,
+  );
+  assert.equal(attempts, 1);
+});

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

@@ -1,5 +1,7 @@
 import { log } from "../logger.js";
 
+type FinalizeCommittedWrites = (scheduleQmd: boolean) => Promise<void>;
+
 /**
  * Fail a persistence pass after a durable write rejected (#3227, same
  * contract as the entity write path from #3228). Earlier writes in the batch
@@ -8,7 +10,7 @@ import { log } from "../logger.js";
  * instead of recording the fingerprint and clearing the source turns.
  */
 export async function rethrowAfterCommittedWriteFinalization(
-  finalizeCommittedWrites: (scheduleQmd: boolean) => Promise<void>,
+  finalizeCommittedWrites: FinalizeCommittedWrites,
   cause: unknown,
   outputKind: string,
 ): Promise<never> {
@@ -17,3 +19,39 @@ export async function rethrowAfterCommittedWriteFinalization(
   );
   throw cause;
 }
+
+/**
+ * Batch-end finalization for one persistExtraction pass (#3288).
+ *
+ * `bind` wraps the pass's finalizer so it runs at most once. The success
+ * tail, the per-branch catch sites and the pass boundary can all reach it,
+ * and a second run would append the same behavior signals again.
+ *
+ * `run` is the pass boundary. A throw from a branch with no catch site of its
+ * own (a chunked-parent post-write step, the semantic-merge post effects, the
+ * profile or question write) still finalizes the writes already committed
+ * before the original error propagates. When a catch site or the success tail
+ * already ran the finalizer, the boundary only rethrows. Nothing is durable
+ * before the finalizer is bound, so an earlier throw propagates as is.
+ */
+export class CommittedWriteFinalization {
+  private finalizer: FinalizeCommittedWrites | undefined;
+  private started: Promise<void> | undefined;
+
+  bind(finalize: FinalizeCommittedWrites): FinalizeCommittedWrites {
+    this.finalizer = (scheduleQmd) => (this.started ??= finalize(scheduleQmd));
+    return this.finalizer;
+  }
+
+  async run<T>(pass: () => Promise<T>): Promise<T> {
+    try {
+      return await pass();
+    } catch (err) {
+      if (!this.finalizer || this.started) throw err;
+      return rethrowAfterCommittedWriteFinalization(this.finalizer, err, "persist pass");
+    }
+  }
+}
+
+/** A pass method's parameter list without its leading CommittedWriteFinalization. */
+export type ArgsAfterFinalization<Params> = Params extends [CommittedWriteFinalization, ...infer Rest] ? Rest : never;

package/src/orchestration/extraction-persist.ts

@@ -1,7 +1,7 @@
 import { classifyExtractionOrigin, type ExtractionSourceContext } from "./extraction-origin-context.js";
 import { confirmActiveFactDuplicate, persistUnderFactDedupWindow } from "./fact-dedup-window.js";
 import { writePromotionUnderFactDedupWindow } from "./promotion-dedup-window.js";
-import { rethrowAfterCommittedWriteFinalization } from "./extraction-persist-failure.js";
+import { type ArgsAfterFinalization, CommittedWriteFinalization, rethrowAfterCommittedWriteFinalization } from "./extraction-persist-failure.js";
 import { evaluateInjectionScreen, screenEntityForIndex, screenPersistStrings } from "./extraction-injection-gate.js";
 /**
  * Extraction persistence coordinator (issue #1526, seam 16).
@@ -152,7 +152,13 @@ export class ExtractionPersistCoordinator {
     return this.deps.getDependencyPropagationDelivery();
   }
 
-  async persistExtraction(
+  persistExtraction(...args: ArgsAfterFinalization<Parameters<ExtractionPersistCoordinator["persistExtractionPass"]>>): Promise<ExtractionPersistResult> {
+    const finalization = new CommittedWriteFinalization(); // #3288: one batch-end finalization boundary per pass
+    return finalization.run(() => this.persistExtractionPass(finalization, ...args));
+  }
+
+  private async persistExtractionPass(
+    finalization: CommittedWriteFinalization,
     result: ExtractionResult,
     storage: StorageManager,
     threadIdForExtraction?: string | null,
@@ -1125,7 +1131,7 @@ export class ExtractionPersistCoordinator {
       0,
       this.deps.config.extractionMaxProfileUpdatesPerRun,
     );
-    const finalizeCommittedWrites = async (scheduleQmd: boolean): Promise<void> => {
+    const finalizeCommittedWrites = finalization.bind(async (scheduleQmd: boolean): Promise<void> => {
       await finalizeExtractionCommittedWrites({
         saveContentHashIndexes: () => this.deps.saveContentHashIndexes(),
         behaviorSignalsByStorage: behaviorSignalsByStorage.values(),
@@ -1150,7 +1156,7 @@ export class ExtractionPersistCoordinator {
         requestQmdMaintenance: () => this.deps.requestQmdMaintenance(),
         scheduleQmd,
       });
-    };
+    });
 
     if (
       facts.length < result.facts.length ||
@@ -2211,6 +2217,24 @@ export class ExtractionPersistCoordinator {
           const tombstoneBlocked = parentWrite.tombstoneBlocked;
           const postWriteGuard =
             faithfulnessEnforceStatus === "pending_review" || tombstoneBlocked;
+          // #3288: the parent is durable now. Track it before any post-write step
+          // that can throw (non-chunked rule, #3231); a retry exact-dedupes it.
+          trackBehaviorSignals(
+            targetStorage,
+            buildBehaviorSignalsForMemory({
+              memoryId: parentId,
+              category: writeCategory,
+              content: fact.content,
+              namespace: this.deps.storageDirNamespace(targetStorage.dir),
+              confidence: fact.confidence,
+              source: "extraction",
+            }),
+          );
+          trackPersistedId(targetStorage, parentId, {
+            pendingReview: postWriteGuard,
+            category: writeCategory,
+            harmonicFact,
+          });
           // #1645: defer contradiction auto-resolve until tombstone status is
           // known (see applyDeferredContradictionResolve).
           const contradictionOutcome = await this.deps.applyDeferredContradictionResolve(
@@ -2306,11 +2330,6 @@ export class ExtractionPersistCoordinator {
           log.debug(
             `chunked memory ${parentId} into ${chunkResult.chunks.length} chunks`,
           );
-          trackPersistedId(targetStorage, parentId, {
-            pendingReview: postWriteGuard,
-            category: writeCategory,
-            harmonicFact,
-          });
           await anchorSnapshots.replace(targetStorage, parentId, writeCategory, memoryPathById);
           // #1576 (cursor Medium): keep pending_review ids out of threadEpisodeIdsForGraph — else later active facts build thread-predecessor edges to an unfaithful memory.
           if (
@@ -2490,17 +2509,6 @@ export class ExtractionPersistCoordinator {
           } finally {
             // #1522: the catalog write touch lives in the storage chokepoint.
           }
-          trackBehaviorSignals(
-            targetStorage,
-            buildBehaviorSignalsForMemory({
-              memoryId: parentId,
-              category: writeCategory,
-              content: fact.content,
-              namespace: this.deps.storageDirNamespace(targetStorage.dir),
-              confidence: fact.confidence,
-              source: "extraction",
-            }),
-          );
           continue; // Skip the normal write below
         }
       }
@@ -2967,7 +2975,7 @@ export class ExtractionPersistCoordinator {
     }
 
     // Shared batch-end finalization (hash, behavior, harmonic, temporal).
-    // Failure paths call the same helper with scheduleQmd=true (#3231).
+    // Failure paths call it with scheduleQmd=true (#3231); it runs once per pass (#3288).
     await finalizeCommittedWrites(false);
 
     const dedupSuffix = `${dedupedCount > 0 ? ` (${dedupedCount} deduped)` : ""}${semanticMergedCount > 0 ? ` (${semanticMergedCount} merged)` : ""}`;

package/src/orchestration/recall-internal.ts

@@ -1537,7 +1537,7 @@ export class RecallInternalCoordinator {
               sessionKey,
               anchorsEnabled: resolveConsolidationCapabilities(this.deps.config).abstractionAnchors,
               temporalExpiredInInjection: this.deps.config.temporalExpiredInInjection,
-              abortSignal: harmonicRetrievalAbort.signal,
+              abortSignal: harmonicRetrievalAbort.signal, useGraphCache: true,
             }),
           ),
         );

package/src/orchestrator-persist-branch-failure.test.ts

@@ -0,0 +1,271 @@
+import assert from "node:assert/strict";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import test from "node:test";
+
+import { resetExtractionLlmHealthForTests } from "./extraction-llm-health.js";
+import { Orchestrator } from "./orchestrator.js";
+import type { StorageManager } from "./storage.js";
+import {
+  cleanupDir,
+  harmonicNodeStoreStatus,
+  makeHarmonicLifecycleConfig,
+  mkTempMemoryDir,
+} from "./testing/orchestrator-lite.js";
+import type { ExtractionResult } from "./types.js";
+
+/**
+ * #3288: a branch that throws after an earlier fact in the same batch is
+ * durable must still land that fact's batch-end effects (behavior signal,
+ * harmonic node, temporal/tag index entry, QMD request) before the error
+ * reaches the caller. A retry exact-dedupes the earlier fact, so this failure
+ * path is the only chance those effects get.
+ */
+const EARLIER = "Prefers terse queue names for background jobs in Project Gamma.";
+
+type BranchCase = {
+  label: string;
+  config?: Parameters<typeof makeHarmonicLifecycleConfig>[1];
+  /** Outputs persisted after the EARLIER fact; one of them hits the injected failure. */
+  later: Partial<ExtractionResult>;
+  /** Installs the failure and returns the error the pass must rethrow. */
+  inject: (orchestrator: Orchestrator, storage: StorageManager, memoryDir: string) => Promise<Error>;
+  /**
+   * Proves the failing branch had already committed its own write when it
+   * threw and returns that write's id. It is durable too, so batch-end
+   * finalization must cover it as well as the earlier fact.
+   */
+  committedBeforeFailure?: (storage: StorageManager) => Promise<string>;
+};
+
+async function assertEarlierFactFinalized(branch: BranchCase): Promise<void> {
+  const memoryDir = await mkTempMemoryDir(`persist-branch-${branch.label}`);
+  const config = makeHarmonicLifecycleConfig(memoryDir, {
+    chunkingEnabled: false,
+    multiGraphMemoryEnabled: false,
+    factDeduplicationEnabled: true,
+    extractionMinImportanceLevel: "trivial",
+    entityActivityLogEnabled: false,
+    queryAwareIndexingEnabled: true,
+    ...branch.config,
+  });
+  const orchestrator = new Orchestrator(config);
+  const storage = await orchestrator.getStorageForNamespace();
+  const temporalIdBatches: string[][] = [];
+  // Finalization starts the temporal/tag update without awaiting it; cleanup
+  // waits for it so the temp dir is not removed under its lock.
+  const temporalUpdates: Promise<void>[] = [];
+  // Bracket access is TypeScript's typed escape hatch for the private method; the spy only wraps it.
+  const originalTemporal = orchestrator["updateTemporalTagIndexes"].bind(orchestrator);
+  orchestrator["updateTemporalTagIndexes"] = (target, persistedIds) => {
+    temporalIdBatches.push([...persistedIds]);
+    const update = originalTemporal(target, persistedIds);
+    temporalUpdates.push(update);
+    return update;
+  };
+  let qmdMaintenanceCalls = 0;
+  const originalQmd = orchestrator.requestQmdMaintenance.bind(orchestrator);
+  orchestrator.requestQmdMaintenance = () => {
+    qmdMaintenanceCalls += 1;
+    originalQmd();
+  };
+  try {
+    await storage.ensureDirectories();
+    const failure = await branch.inject(orchestrator, storage, memoryDir);
+    const result: ExtractionResult = {
+      entities: [],
+      questions: [],
+      profileUpdates: [],
+      ...branch.later,
+      facts: [
+        { content: EARLIER, category: "preference", confidence: 0.95, tags: ["queue-naming"] },
+        ...(branch.later.facts ?? []),
+      ],
+    };
+
+    await assert.rejects(
+      orchestrator.persistExtraction(result, storage, null, { sessionKey: `session:${branch.label}` }),
+      (error: Error) => error === failure,
+      "the branch failure must reach the caller unchanged",
+    );
+    const branchWriteId = await branch.committedBeforeFailure?.(storage);
+
+    const earlier = (await storage.readAllMemories()).filter((m) => m.frontmatter.category === "preference");
+    assert.equal(earlier.length, 1, "the earlier fact must stay durable");
+    const factId = earlier[0]!.frontmatter.id;
+    assert.ok(
+      (await storage.readBehaviorSignals(50)).some(
+        (s) => s.memoryId === factId && s.signalType === "preference_affinity",
+      ),
+      "the earlier fact's behavior signal must land before the rethrow",
+    );
+    const harmonicSources = (await harmonicNodeStoreStatus(memoryDir)).latestNode?.sourceMemoryIds ?? [];
+    for (const id of branchWriteId ? [factId, branchWriteId] : [factId]) {
+      assert.ok(harmonicSources.includes(id), `the harmonic node must cover durable write ${id} before the rethrow`);
+      assert.ok(
+        temporalIdBatches.some((ids) => ids.includes(id)),
+        `the temporal/tag index update must cover durable write ${id} before the rethrow`,
+      );
+    }
+    assert.ok(qmdMaintenanceCalls > 0, "the partial batch must still schedule QMD maintenance");
+  } finally {
+    await Promise.allSettled(temporalUpdates);
+    orchestrator.requestQmdMaintenance = originalQmd;
+    orchestrator["updateTemporalTagIndexes"] = originalTemporal;
+    try {
+      await orchestrator.destroy();
+    } finally {
+      resetExtractionLlmHealthForTests();
+      await cleanupDir(memoryDir);
+    }
+  }
+}
+
+test("#3288: a chunk write failure after the chunked parent is durable finalizes the earlier fact", async () => {
+  await assertEarlierFactFinalized({
+    label: "chunk-write",
+    config: {
+      chunkingEnabled: true,
+      chunkingTargetTokens: 12,
+      chunkingMinTokens: 10,
+      chunkingOverlapSentences: 0,
+    },
+    later: {
+      facts: [
+        {
+          content:
+            "Project Gamma runs its nightly export on a dedicated worker pool. " +
+            "The export writes compressed archives to the cold storage bucket. " +
+            "Each archive is verified against a checksum manifest before upload. " +
+            "Failed uploads are retried three times with exponential backoff.",
+          category: "fact",
+          confidence: 0.9,
+          tags: ["export"],
+        },
+      ],
+    },
+    inject: async (_orchestrator, storage) => {
+      const failure = new Error("synthetic chunk write failure");
+      storage.writeChunk = async () => {
+        throw failure;
+      };
+      return failure;
+    },
+    committedBeforeFailure: async (storage) => {
+      const parents = (await storage.readAllMemories()).filter((m) => m.frontmatter.tags?.includes("chunked"));
+      assert.equal(parents.length, 1, "the chunked parent must be durable before the chunk write throws");
+      return parents[0]!.frontmatter.id;
+    },
+  });
+});
+
+const MERGE_TARGET_ID = "merge-target-gamma";
+const MERGE_SEED = "The Project Gamma billing service deploys on a Tuesday cadence.";
+const MERGE_INCOMING = "The Project Gamma billing service deploys at 09:00 UTC sharp.";
+
+/** Seed an active merge target and a deterministic merge judge for MERGE_INCOMING only. */
+async function armSemanticMerge(orchestrator: Orchestrator, memoryDir: string): Promise<void> {
+  const created = new Date(Date.now() - 3600_000).toISOString();
+  const seededDir = path.join(memoryDir, "facts", created.slice(0, 10));
+  await mkdir(seededDir, { recursive: true });
+  await writeFile(
+    path.join(seededDir, `${MERGE_TARGET_ID}.md`),
+    [
+      "---",
+      `id: ${MERGE_TARGET_ID}`,
+      "category: fact",
+      `created: ${created}`,
+      `updated: ${created}`,
+      "source: extraction",
+      "confidence: 0.9",
+      "confidenceTier: explicit",
+      "status: active",
+      "importanceScore: 0.9",
+      "importanceLevel: high",
+      "---",
+      "",
+      MERGE_SEED,
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+  // Band neighbor for the incoming fact only ([minSimilarity, threshold)).
+  const embeddings = orchestrator.embeddingFallback;
+  embeddings.isAvailable = async () => true;
+  embeddings.search = async (query) => (query === MERGE_INCOMING ? [{ id: MERGE_TARGET_ID, score: 0.85, path: "" }] : []);
+  embeddings.indexFile = async () => {};
+  embeddings.removeFromIndex = async () => {};
+  // Deterministic merge judge; every other local-LLM prompt gets no answer.
+  orchestrator.localLlm.chatCompletion = async (messages) =>
+    messages[0]?.role === "system" && messages[0].content.startsWith("You maintain a long-term memory store")
+      ? {
+          content: JSON.stringify({
+            decision: "merge",
+            targetId: MERGE_TARGET_ID,
+            mergedContent: `${MERGE_SEED} ${MERGE_INCOMING}`,
+            reason: "deterministic judge for the merge-branch failure test",
+          }),
+        }
+      : null;
+}
+
+test("#3288: a semantic-merge post-effect failure after the merge commits finalizes the earlier fact", async () => {
+  await assertEarlierFactFinalized({
+    label: "semantic-merge",
+    config: {
+      embeddingFallbackEnabled: true,
+      versioningEnabled: true,
+      semanticMerge: { enabled: true },
+      multiGraphMemoryEnabled: true,
+    },
+    later: {
+      facts: [{ content: MERGE_INCOMING, category: "fact", confidence: 0.9, tags: [] }],
+    },
+    inject: async (orchestrator, _storage, memoryDir) => {
+      await armSemanticMerge(orchestrator, memoryDir);
+      // The merged-target graph rebuild fails open, but the edge-cache
+      // invalidation that follows it is not wrapped: an unavailable graph
+      // index escapes runMergedTargetPostEffects after the merge committed.
+      const failure = new Error("synthetic graph index failure");
+      orchestrator["graphIndexFor"] = () => {
+        throw failure;
+      };
+      return failure;
+    },
+    committedBeforeFailure: async (storage) => {
+      const target = await storage.getMemoryByIdIncludingArchived(MERGE_TARGET_ID);
+      assert.ok(target?.content.includes(MERGE_INCOMING), "the merge must be committed before the post effect throws");
+      return MERGE_TARGET_ID;
+    },
+  });
+});
+
+test("#3288: a profile append failure after an earlier fact is durable finalizes that fact", async () => {
+  await assertEarlierFactFinalized({
+    label: "profile-append",
+    later: { profileUpdates: ["Works mostly on the Project Gamma export pipeline."] },
+    inject: async (_orchestrator, storage) => {
+      const failure = new Error("synthetic profile append failure");
+      storage.appendToProfile = async () => {
+        throw failure;
+      };
+      return failure;
+    },
+  });
+});
+
+test("#3288: a question write failure after an earlier fact is durable finalizes that fact", async () => {
+  await assertEarlierFactFinalized({
+    label: "question-write",
+    later: {
+      questions: [{ question: "Which bucket holds the Project Gamma archives?", context: "export pipeline", priority: 0.5 }],
+    },
+    inject: async (_orchestrator, storage) => {
+      const failure = new Error("synthetic question write failure");
+      storage.writeQuestion = async () => {
+        throw failure;
+      };
+      return failure;
+    },
+  });
+});