@remnic/core 10.0.50 → 10.0.52

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

@@ -23,6 +23,11 @@ import {
 import type { MemoryFile, PluginConfig } from "../types.js";
 import type { ResolvedScopeProfilePlan } from "../namespaces/scope-profiles.js";
 import { readDurableSemanticFingerprint, readPromotionReceiptStatus, type MergedTargetPromotionPayload } from "./semantic-merge-promotion-payload.js";
+import type { BehaviorSignalEvent, ExtractionResult } from "../types.js";
+import type { HarmonicConstructionInput } from "../harmonic-construction.js";
+import { dedupeBehaviorSignalsByMemoryAndHash } from "../behavior-signals.js";
+import { persistConstructedHarmonicRecords } from "./harmonic-construction-persist.js";
+
 
 export const confidenceTierOrder = [
   "explicit",
@@ -116,27 +121,110 @@ export async function readActiveMemoriesBothTiers(
   return coldMems.length === 0 ? hotMems : [...hotMems, ...coldMems];
 }
 
+
 /**
- * PR #2016: after `writeSealedMemory` has made a fact `.md` durable with its
- * fact-hash flush deferred (#1909 batching), a throw in the fallible post-write
- * work (contradiction resolve, indexing, shared promotion, artifact write)
- * would strand the deferred parent hash — the shared fact-hash index on disk
- * would be missing the parent until the next corpus rebuild, letting a peer
- * re-extract a duplicate. Flush the batch save before the error propagates so
- * the durable-hash invariant holds on every path. No-op when dedup is off
- * (`deferred=false` → the write already flushed and the batch saver is a no-op).
- * Best-effort: a flush failure is logged and never masks the original error.
+ * Batch-end finalization for facts already durable in this persist pass:
+ * content-hash save, behavior signals, harmonic construction, temporal/tag
+ * indexes. Shared by the success tail and every rethrow path so a partial
+ * batch (e.g. fact wrote, entity failed) still lands deferred side effects
+ * before the original error propagates (#3228 / #3231). Best-effort: each
+ * step logs and never masks `originalError` at the call site.
+ *
+ * `scheduleQmd` is failure-only. Success still schedules QMD from
+ * extraction-run after persist returns, so success passes false.
  */
-export async function flushDeferredFactHashOnFailure(
-  saveContentHashIndexes: () => Promise<void>,
-  deferred: boolean,
-): Promise<void> {
-  if (!deferred) return;
-  await saveContentHashIndexes().catch((err) =>
-    log.warn(`content-hash flush after post-write failure failed: ${err}`),
+export async function finalizeExtractionCommittedWrites(options: {
+  saveContentHashIndexes: () => Promise<void>;
+  behaviorSignalsByStorage: Iterable<{
+    storage: StorageManager;
+    events: BehaviorSignalEvent[];
+  }>;
+  harmonic?: {
+    enabled: boolean;
+    entries: Iterable<{
+      storage: StorageManager;
+      facts: HarmonicConstructionInput["persistedFacts"];
+    }>;
+    baseStorageDir: string;
+    abstractionNodeStoreDir?: string;
+    sessionKey?: string;
+    validAt?: string;
+    episodeTitle?: string;
+    anchorsEnabled: boolean;
+    entityMentions: ExtractionResult["entities"];
+  };
+  updateTemporalTagIndexes: (
+    storage: StorageManager,
+    persistedIds: string[],
+  ) => Promise<void>;
+  fallbackStorage: StorageManager;
+  persistedIdsByStorage: Map<string, { storage: StorageManager; ids: string[] }>;
+  requestQmdMaintenance?: () => void;
+  scheduleQmd: boolean;
+}): Promise<void> {
+  await options.saveContentHashIndexes().catch((err) => {
+    log.warn(`content-hash index save failed: ${err}`);
+  });
+
+  // Snapshot once — Map iterators are single-pass.
+  const behaviorEntries = [...options.behaviorSignalsByStorage];
+  for (const { storage: targetStorage, events } of behaviorEntries) {
+    const dedupedSignals = dedupeBehaviorSignalsByMemoryAndHash(events);
+    if (dedupedSignals.length === 0) continue;
+    await targetStorage
+      .appendBehaviorSignals(dedupedSignals)
+      .catch((err) =>
+        log.warn(`appendBehaviorSignals failed (non-fatal): ${err}`),
+      );
+  }
+
+  const harmonic = options.harmonic;
+  let harmonicEntryCount = 0;
+  if (harmonic?.enabled) {
+    const entries = [...harmonic.entries];
+    harmonicEntryCount = entries.length;
+    if (entries.length > 0) {
+      await persistConstructedHarmonicRecords({
+        entries,
+        baseStorageDir: harmonic.baseStorageDir,
+        abstractionNodeStoreDir: harmonic.abstractionNodeStoreDir,
+        sessionKey: harmonic.sessionKey,
+        validAt: harmonic.validAt,
+        episodeTitle: harmonic.episodeTitle,
+        anchorsEnabled: harmonic.anchorsEnabled,
+        entityMentions: harmonic.entityMentions,
+      });
+    }
+  }
+
+  void (async () => {
+    if (options.persistedIdsByStorage.size === 0) {
+      await options.updateTemporalTagIndexes(options.fallbackStorage, []);
+      return;
+    }
+    for (const entry of options.persistedIdsByStorage.values()) {
+      await options.updateTemporalTagIndexes(entry.storage, entry.ids);
+    }
+  })().catch((err) =>
+    log.debug(`temporal-index update error (non-fatal): ${err}`),
   );
+
+  if (!options.scheduleQmd || !options.requestQmdMaintenance) return;
+  const hasCommitted =
+    options.persistedIdsByStorage.size > 0 ||
+    behaviorEntries.length > 0 ||
+    harmonicEntryCount > 0;
+  if (!hasCommitted) return;
+  try {
+    options.requestQmdMaintenance();
+  } catch (err) {
+    log.warn(
+      `QMD maintenance schedule after partial persist failed (non-fatal): ${err}`,
+    );
+  }
 }
 
+
 /**
  * Merged-target promotion scope gate (PR #2771 finding A). A committed
  * record stamped `toolScoped: true` must keep its promoted copy withheld

package/src/orchestration/extraction-persist.ts

@@ -68,10 +68,7 @@ import {
 } from "../source-attribution.js";
 import { classifyMemoryKind } from "../himem.js";
 import { shouldPromoteGlobalFactToShared, withholdToolScopedFromSharedNamespace } from "../tool-scoped-memory.js";
-import {
-  buildBehaviorSignalsForMemory,
-  dedupeBehaviorSignalsByMemoryAndHash,
-} from "../behavior-signals.js";
+import { buildBehaviorSignalsForMemory } from "../behavior-signals.js";
 import { buildProcedurePersistBody } from "../procedural/procedure-types.js";
 import { stripAttributesSuffix } from "../structured-attributes.js";
 import { resolveWriteSubject } from "../memory-subject.js";
@@ -103,7 +100,7 @@ import type {
 } from "../types.js";
 import {
   createBatchPromotedCopyProbe,
-  flushDeferredFactHashOnFailure,
+  finalizeExtractionCommittedWrites,
   makeSubjectGuardAllows,
   profileAutoPromotionAllows,
   readActiveMemoriesBothTiers,
@@ -120,7 +117,7 @@ import {
   resolvePersistedMemoryRelativePath,
 } from "../orchestrator.js";
 import type { HarmonicConstructionInput } from "../harmonic-construction.js";
-import { enqueueMergedTargetForHarmonicConstruction, persistConstructedHarmonicRecords } from "./harmonic-construction-persist.js";
+import { enqueueMergedTargetForHarmonicConstruction } from "./harmonic-construction-persist.js";
 import { applySemanticMergeAtPersist, runMergedTargetPostEffects, writeMergedVerbatimArtifact } from "./semantic-merge-persist.js";
 import { buildMergedTargetPromotionPayload } from "./semantic-merge-promotion-payload.js";
 import { persistMergedTargetThreadEpisode } from "./semantic-merge-commit-effects.js";
@@ -291,6 +288,7 @@ export class ExtractionPersistCoordinator {
         events: [...events],
       });
     };
+
     const sharedProfileLayer = scopeProfileWritePlan?.layers.find(
       (layer) =>
         layer.id === "serverShared" &&
@@ -1106,6 +1104,32 @@ export class ExtractionPersistCoordinator {
       0,
       this.deps.config.extractionMaxProfileUpdatesPerRun,
     );
+    const finalizeCommittedWrites = async (scheduleQmd: boolean): Promise<void> => {
+      await finalizeExtractionCommittedWrites({
+        saveContentHashIndexes: () => this.deps.saveContentHashIndexes(),
+        behaviorSignalsByStorage: behaviorSignalsByStorage.values(),
+        harmonic: {
+          enabled: harmonicConstructionEnabled,
+          entries: harmonicFactsByStorage.values(),
+          baseStorageDir: storage.dir,
+          abstractionNodeStoreDir:
+            !scopeProfileWritePlan && harmonicBaseNamespace === this.deps.config.defaultNamespace
+              ? this.deps.config.abstractionNodeStoreDir
+              : undefined,
+          sessionKey: sourceContext?.sessionKey,
+          validAt: sourceContext?.validAt,
+          episodeTitle: result.episodeTitle,
+          anchorsEnabled: harmonicAnchorsEnabled,
+          entityMentions: entities,
+        },
+        updateTemporalTagIndexes: (target, ids) =>
+          this.deps.updateTemporalTagIndexes(target, ids),
+        fallbackStorage: storage,
+        persistedIdsByStorage,
+        requestQmdMaintenance: () => this.deps.requestQmdMaintenance(),
+        scheduleQmd,
+      });
+    };
 
     if (
       facts.length < result.facts.length ||
@@ -2583,6 +2607,25 @@ export class ExtractionPersistCoordinator {
       // so a blocked fact creates no active shared copy / supersession / graph entry.
       const tombstoneBlocked = factWrite.tombstoneBlocked;
       const postWriteGuard = faithfulnessEnforceStatus === "pending_review" || tombstoneBlocked;
+      // #3231: the fact is durable now. Track it before any post-write step
+      // that can throw, so the batch-end finalization on a failure path still
+      // covers it (a retry exact-dedupes the fact and would not re-queue it).
+      trackBehaviorSignals(
+        targetStorage,
+        buildBehaviorSignalsForMemory({
+          memoryId,
+          category: writeCategory,
+          content: fact.content,
+          namespace: this.deps.storageDirNamespace(targetStorage.dir),
+          confidence: fact.confidence,
+          source: "extraction",
+        }),
+      );
+      trackPersistedId(targetStorage, memoryId, {
+        pendingReview: postWriteGuard,
+        category: writeCategory,
+        harmonicFact,
+      });
       // #1645: defer contradiction auto-resolve until tombstone status is
       // known (see applyDeferredContradictionResolve).
       try {
@@ -2596,7 +2639,9 @@ export class ExtractionPersistCoordinator {
           await anchorSnapshots.remove(targetStorage, contradiction!.supersededId);
         }
       } catch (err) {
-        await flushDeferredFactHashOnFailure(() => this.deps.saveContentHashIndexes(), factDedupEnabled);
+        await finalizeCommittedWrites(true).catch((finalizeErr) =>
+          log.warn(`committed-write finalization after post-write failure failed: ${finalizeErr}`),
+        );
         throw err;
       }
       if (routedRuleId) {
@@ -2632,22 +2677,6 @@ export class ExtractionPersistCoordinator {
         }
       }
       try {
-        trackBehaviorSignals(
-          targetStorage,
-          buildBehaviorSignalsForMemory({
-            memoryId,
-            category: writeCategory,
-            content: fact.content,
-            namespace: this.deps.storageDirNamespace(targetStorage.dir),
-            confidence: fact.confidence,
-            source: "extraction",
-          }),
-        );
-        trackPersistedId(targetStorage, memoryId, {
-          pendingReview: postWriteGuard,
-          category: writeCategory,
-          harmonicFact,
-        });
         await anchorSnapshots.replace(targetStorage, memoryId, writeCategory, memoryPathById);
         if (
           !postWriteGuard &&
@@ -2782,9 +2811,12 @@ export class ExtractionPersistCoordinator {
           );
         }
       } catch (err) {
-        // PR #2016: flush the deferred fact-hash before propagating so a durable
-        // .md never outlives a missing shared fact-hash index entry.
-        await flushDeferredFactHashOnFailure(() => this.deps.saveContentHashIndexes(), factDedupEnabled);
+        // PR #2016 / #3231: finalize deferred side effects for facts already
+        // durable before propagating so hash/behavior/harmonic/temporal/QMD
+        // still land on a partial batch.
+        await finalizeCommittedWrites(true).catch((finalizeErr) =>
+          log.warn(`committed-write finalization after post-write failure failed: ${finalizeErr}`),
+        );
         throw err;
       }
     }
@@ -2807,7 +2839,6 @@ export class ExtractionPersistCoordinator {
       durableNonFactTouchRecorded = true;
       touchBaseNonFactNamespace();
     };
-    // #1955 review: entity fields are screened before entering the index (screenEntityForIndex).
     const entityScreenOn = resolveSecurityCapabilities(this.deps.config).injectionScreen;
     const entityScreenProfile = resolveSecurityCapabilities(this.deps.config).injectionScreenProfile;
     for (const entity of entities) {
@@ -2829,7 +2860,10 @@ export class ExtractionPersistCoordinator {
           recordDurableNonFactWrite();
         }
       } catch (err) {
-        log.warn(`persistExtraction: entity write failed: ${err}`);
+        await finalizeCommittedWrites(true).catch((finalizeErr) =>
+          log.warn(`committed-write finalization after entity failure failed: ${finalizeErr}`),
+        );
+        throw err;
       }
     }
     // Persist entity relationships (v7.0). #1955 review: source/label/target are screened.
@@ -2929,28 +2963,9 @@ export class ExtractionPersistCoordinator {
       touchBaseNonFactNamespace();
     }
 
-    // Save any content-hash indexes touched during the batch via the removal-
-    // aware, lock-held reconciling save (issue #1909). Round 11: the fact-hash
-    // index is rebuilt from the corpus on every restart (no ready marker), so
-    // this on-disk write is the in-process persisted view — never a cross-restart
-    // trust anchor. A deferred write whose addContentHashDedup threw is still
-    // safe: the fact .md is durable and the next restart's rebuild includes it.
-    await this.deps.saveContentHashIndexes().catch((err) => {
-      log.warn(`content-hash index save failed: ${err}`);
-    });
-
-    for (const {
-      storage: targetStorage,
-      events,
-    } of behaviorSignalsByStorage.values()) {
-      const dedupedSignals = dedupeBehaviorSignalsByMemoryAndHash(events);
-      if (dedupedSignals.length === 0) continue;
-      await targetStorage
-        .appendBehaviorSignals(dedupedSignals)
-        .catch((err) =>
-          log.warn(`appendBehaviorSignals failed (non-fatal): ${err}`),
-        );
-    }
+    // Shared batch-end finalization (hash, behavior, harmonic, temporal).
+    // Failure paths call the same helper with scheduleQmd=true (#3231).
+    await finalizeCommittedWrites(false);
 
     const dedupSuffix = `${dedupedCount > 0 ? ` (${dedupedCount} deduped)` : ""}${semanticMergedCount > 0 ? ` (${semanticMergedCount} merged)` : ""}`;
     const gatedSuffix =
@@ -2962,33 +2977,7 @@ export class ExtractionPersistCoordinator {
     log.info(
       `persisted: ${facts.length - dedupedCount - importanceGatedCount - judgeGatedCount - redactionGatedCount - semanticMergedCount} facts${dedupSuffix}${gatedSuffix}${judgeSuffix}${redactionSuffix}, ${entities.length} entities, ${questions.length} questions, ${profileUpdates.length} profile updates`,
     );
-    if (harmonicConstructionEnabled && harmonicFactsByStorage.size > 0) {
-      await persistConstructedHarmonicRecords({
-        entries: harmonicFactsByStorage.values(),
-        baseStorageDir: storage.dir,
-        abstractionNodeStoreDir:
-          !scopeProfileWritePlan && harmonicBaseNamespace === this.deps.config.defaultNamespace
-            ? this.deps.config.abstractionNodeStoreDir
-            : undefined,
-        sessionKey: sourceContext?.sessionKey,
-        validAt: sourceContext?.validAt,
-        episodeTitle: result.episodeTitle,
-        anchorsEnabled: harmonicAnchorsEnabled,
-        entityMentions: entities,
-      });
-    }
-    // Update temporal + tag indexes (v8.1) — fire-and-forget, fail-open
-    void (async () => {
-      if (persistedIdsByStorage.size === 0) {
-        await this.deps.updateTemporalTagIndexes(storage, []);
-        return;
-      }
-      for (const entry of persistedIdsByStorage.values()) {
-        await this.deps.updateTemporalTagIndexes(entry.storage, entry.ids);
-      }
-    })().catch((err) =>
-      log.debug(`temporal-index update error (non-fatal): ${err}`),
-    );
+
     // #1635: surface pending_review ids so the thread episode set excludes them.
     this.deps.setLastPersistExtractionPendingReviewIds(pendingReviewPersistedIds);
     // Return the persisted fact IDs for threading