@remnic/core 9.69.39 → 9.69.40

package/src/index.ts

@@ -1224,6 +1224,7 @@ export {
 
 export {
   FallbackLlmClient,
+  FallbackLlmClient as TaskLlmClient,
   type FallbackLlmOptions,
   type FallbackLlmResponse,
   type FallbackLlmRuntimeContext,

package/src/local-llm-config.ts

@@ -2,7 +2,7 @@ import { coerceNumber } from "./connectors/coerce.js";
 import { parseBackgroundGeneration } from "./background-generation-config.js";
 import type { BackgroundGenerationConfig } from "./background-generation-config.js";
 import { readEnvVar } from "./runtime/env.js";
-
+import { parseTaskLlmConfig } from "./task-llm-config.js";
 export interface LocalLlmConfig {
   // Local LLM Provider (v2.1)
   localLlmEnabled: boolean;
@@ -17,14 +17,17 @@ export interface LocalLlmConfig {
   /** If false, do not send Authorization header even when localLlmApiKey is set. */
   localLlmAuthHeader: boolean;
   localLlmFallback: boolean;
+  taskLlmFallback?: boolean;
   /** Optional home directory override for local LLM helpers (LM Studio settings, CLI PATH). */
   localLlmHomeDir?: string;
   /** Optional absolute path to LMS CLI binary (preferred over auto-detection). */
   localLmsCliPath?: string;
   /** Optional bin directory prepended to PATH for LMS CLI execution. */
   localLmsBinDir?: string;
-  /** Hard timeout for local LLM and gateway fallback requests (ms). */
+  /** Hard timeout for local LLM requests (ms). Legacy alias for the task-chain timeout when `taskLlmTimeoutMs` is absent. */
   localLlmTimeoutMs: number;
+  /** Timeout for the gateway/task LLM chain (ms). */
+  taskLlmTimeoutMs?: number;
   /** Max context window for local LLM (override auto-detection). Set lower if your LLM server defaults to smaller contexts. */
   localLlmMaxContext?: number;
 }
@@ -33,11 +36,6 @@ export type LocalLlmParseResult = LocalLlmConfig & {
   backgroundGeneration?: BackgroundGenerationConfig;
 };
 
-function parseLocalLlmTimeoutMs(value: unknown): number {
-  const coerced = coerceNumber(value);
-  if (coerced === undefined) return 180_000;
-  return Math.min(86_400_000, Math.max(1, Math.floor(coerced)));
-}
 
 function parseLocalLlmMaxContext(value: unknown): number | undefined {
   if (value === undefined || value === null) return undefined;
@@ -70,8 +68,9 @@ export function parseLocalLlmConfig(
   localLlmApiKeyEnv: string | undefined,
   resolveEnvVars: (value: string) => string,
 ): LocalLlmParseResult {
+  const taskLlm = parseTaskLlmConfig(cfg);
   return {
-    backgroundGeneration: parseBackgroundGeneration(cfg),
+    backgroundGeneration: parseBackgroundGeneration(cfg, resolveEnvVars),
     localLlmEnabled: cfg.localLlmEnabled === true || cfg.localLlmEnabled === "true",
     localLlmUrl:
       typeof cfg.localLlmUrl === "string" && cfg.localLlmUrl.length > 0
@@ -90,7 +89,8 @@ export function parseLocalLlmConfig(
     localLlmApiKeyEnv,
     localLlmHeaders: copyStringRecord(cfg.localLlmHeaders),
     localLlmAuthHeader: cfg.localLlmAuthHeader !== false,
-    localLlmFallback: cfg.localLlmFallback !== false,
+    localLlmFallback: taskLlm.fallback,
+    taskLlmFallback: taskLlm.fallback,
     localLlmHomeDir:
       typeof cfg.localLlmHomeDir === "string" && cfg.localLlmHomeDir.length > 0
         ? cfg.localLlmHomeDir
@@ -103,7 +103,8 @@ export function parseLocalLlmConfig(
       typeof cfg.localLmsBinDir === "string" && cfg.localLmsBinDir.length > 0
         ? cfg.localLmsBinDir
         : undefined,
-    localLlmTimeoutMs: parseLocalLlmTimeoutMs(cfg.localLlmTimeoutMs),
+    localLlmTimeoutMs: taskLlm.localTimeoutMs,
+    taskLlmTimeoutMs: taskLlm.timeoutMs,
     localLlmMaxContext: parseLocalLlmMaxContext(cfg.localLlmMaxContext),
   };
 }

package/src/local-llm-headers-timeout.test.ts

@@ -12,6 +12,7 @@ import {
 } from "undici";
 
 import { LocalLlmClient } from "./local-llm.js";
+import { classifyAnalysisProviderError } from "./activity/timeline/analysis-provider.js";
 import { ChatTransport } from "./local-llm-transport.js";
 import { initLogger, resetLogger } from "./logger.js";
 import type { PluginConfig } from "./types.js";
@@ -553,3 +554,32 @@ test("sensitive local requests do not log provider error bodies", { concurrency:
     await dispatcherOf(client).close();
   }
 });
+
+test("failureDiag preserves a 429 rate-limit failure cause (issue #2891)", { concurrency: false }, async () => {
+  const original = globalThis.fetch;
+  globalThis.fetch = (async () =>
+    new Response(JSON.stringify({ error: { message: "rate limit exceeded" } }), {
+      status: 429,
+      headers: { "content-type": "application/json" },
+    })) as typeof fetch;
+  const client = new LocalLlmClient(createConfig());
+
+  try {
+    primeClient(client);
+    const failureDiag: { lastError?: unknown } = {};
+    assert.equal(
+      await client.chatCompletion(
+        [{ role: "user", content: "test" }],
+        { redactProviderErrors: true, failureDiag },
+      ),
+      null,
+    );
+    const lastError = failureDiag.lastError;
+    assert.ok(lastError instanceof Error, "expected the terminal provider error to survive the request");
+    assert.equal("status" in lastError ? lastError.status : undefined, 429);
+    assert.equal(classifyAnalysisProviderError(lastError), "rate_limited");
+  } finally {
+    globalThis.fetch = original;
+    await dispatcherOf(client).close();
+  }
+});

package/src/local-llm-helpers.ts

@@ -1,4 +1,32 @@
 import { log } from "./logger.js";
+import type { LocalLlmRequestPriority } from "./local-llm.js";
+
+export interface LocalLlmChatCompletionOptions {
+  temperature?: number;
+  maxTokens?: number;
+  responseFormat?: { type: string };
+  timeoutMs?: number;
+  operation?: string;
+  forceDisableThinking?: boolean;
+  disableThinking?: boolean;
+  priority?: LocalLlmRequestPriority;
+  signal?: AbortSignal;
+  redactProviderErrors?: boolean;
+  /** Per-request model; defaults to config.localLlmModel. */
+  model?: string;
+  /**
+   * Optional out-box for the terminal failure cause (issue #2891): on a
+   * failed request the client records the last provider error here so
+   * callers can classify it (e.g. HTTP 429 → rate-limited) in memory
+   * instead of seeing only null. Never logged.
+   */
+  failureDiag?: { lastError?: unknown };
+}
+
+export interface LocalLlmChatCompletionResult {
+  content: string;
+  usage?: { promptTokens: number; completionTokens: number; totalTokens: number };
+}
 export function isAbortError(err: unknown): boolean {
   if (!err || typeof err !== "object") return false;
   const maybe = err as { name?: string; message?: string };

package/src/local-llm.ts

@@ -19,6 +19,8 @@ import {
   normalizeBackendTripReason,
   waitForRetryBackoff,
   SingleFlightProbe,
+  type LocalLlmChatCompletionOptions,
+  type LocalLlmChatCompletionResult,
 } from "./local-llm-helpers.js";
 
 /** Trim trailing slash characters without backtracking regex. */
@@ -226,20 +228,8 @@ export interface LocalModelInfo {
 
 export type LocalLlmRequestPriority = "recall-critical" | "background";
 
-interface LocalLlmChatCompletionOptions {
-  temperature?: number;
-  maxTokens?: number;
-  responseFormat?: { type: string };
-  timeoutMs?: number;
-  operation?: string;
-  forceDisableThinking?: boolean;
-  disableThinking?: boolean;
-  priority?: LocalLlmRequestPriority;
-  signal?: AbortSignal;
-  redactProviderErrors?: boolean;
-  /** Per-request model; defaults to config.localLlmModel. */
-  model?: string;
-}
+// LocalLlmChatCompletionOptions and LocalLlmChatCompletionResult live in
+// local-llm-helpers.ts so this file stays under its size ceiling (#1995).
 interface LocalLlmQueuedRequest {
   messages: Array<{ role: string; content: string }>;
   options: LocalLlmChatCompletionOptions;
@@ -248,11 +238,6 @@ interface LocalLlmQueuedRequest {
   resolve: (value: LocalLlmChatCompletionResult | null) => void;
 }
 
-interface LocalLlmChatCompletionResult {
-  content: string;
-  usage?: { promptTokens: number; completionTokens: number; totalTokens: number };
-}
-
 const LOCAL_LLM_GLOBAL_BACKEND_STATE = "__openclawEngramLocalLlmBackendState";
 
 type LocalLlmBackendState = {
@@ -1165,6 +1150,10 @@ export class LocalLlmClient {
         } else {
           this.consecutive400s = 0;
         }
+        if (options.failureDiag)
+          options.failureDiag.lastError = Object.assign(new Error("local LLM http failure"), {
+            status: response.status,
+          });
         return null;
       }
       this.consecutive400s = 0;

package/src/namespaces/search.test.ts

@@ -21,6 +21,7 @@ class FakeBackend implements SearchBackend {
   strictEmbeds = 0;
   strictCollectionEmbeds: string[] = [];
   disposed = 0;
+  disposeWait: Promise<void> | null = null;
   available = true;
   calls: Array<{
     method: string;
@@ -28,6 +29,7 @@ class FakeBackend implements SearchBackend {
     maxResults: number | undefined;
   }> = [];
   availabilitySignals: Array<AbortSignal | undefined> = [];
+  probeSignals: Array<AbortSignal | undefined> = [];
   probeCalls = 0;
   ensureSignals: Array<AbortSignal | undefined> = [];
   ensureCollections: Array<string | undefined> = [];
@@ -54,8 +56,9 @@ class FakeBackend implements SearchBackend {
       : this.results;
   }
 
-  async probe(): Promise<boolean> {
+  async probe(execution?: SearchExecutionOptions): Promise<boolean> {
     this.probeCalls += 1;
+    this.probeSignals.push(execution?.signal);
     return this.available;
   }
 
@@ -89,6 +92,7 @@ class FakeBackend implements SearchBackend {
 
   async dispose(): Promise<void> {
     this.disposed += 1;
+    await this.disposeWait;
   }
 
   async search(
@@ -470,10 +474,56 @@ test("ensureNamespaceCollection forwards abort signals to backend collection che
   });
 
   assert.equal(state, "present");
+  assert.deepEqual(backend.probeSignals, [controller.signal]);
   assert.deepEqual(backend.ensureSignals, [controller.signal]);
   assert.deepEqual(backend.ensureCollections, ["openclaw-engram--ns-6d61696e"]);
 });
 
+test("disableSearchBackends releases cached namespace backends without recreating search", async () => {
+  const backend = new FakeBackend(false);
+  const router = new NamespaceSearchRouter(
+    config(),
+    { storageFor: async (namespace: string) => ({ dir: `/tmp/remnic/${namespace}` }) },
+    () => backend,
+  );
+
+  assert.equal(await router.ensureNamespaceCollection("main"), "present");
+  await router.disableSearchBackends();
+
+  await router.disableSearchBackends();
+
+  assert.equal(backend.disposed, 1, "repeated runtime disable must not double-dispose the same backend");
+  assert.equal(await router.backendForNamespace("main"), null);
+  assert.equal(await router.ensureNamespaceCollection("main"), "missing");
+  assert.equal(backend.probeCalls, 1, "disabled records must not recreate a concrete backend");
+});
+
+test("clearCache releases evicted namespace backend handles before recreation", async () => {
+  const oldBackend = new FakeBackend(false);
+  const newBackend = new FakeBackend(false);
+  let releaseOldDispose: (() => void) | undefined;
+  oldBackend.disposeWait = new Promise<void>((resolve) => { releaseOldDispose = resolve; });
+  let createCalls = 0;
+  const router = new NamespaceSearchRouter(
+    config(),
+    { storageFor: async (namespace: string) => ({ dir: `/tmp/remnic/${namespace}` }) },
+    () => {
+      createCalls += 1;
+      return createCalls === 1 ? oldBackend : newBackend;
+    },
+  );
+
+  await router.ensureNamespaceCollection("main");
+  router.clearCache();
+  const recreation = router.ensureNamespaceCollection("main");
+  await Promise.resolve();
+  assert.equal(createCalls, 1, "recreation must wait for the evicted handle disposal barrier");
+  releaseOldDispose?.();
+  assert.equal(await recreation, "present");
+  assert.equal(oldBackend.disposed, 1);
+  assert.equal(createCalls, 2);
+});
+
 test("legacy default namespace root auto-creates its base collection (broad root, #1929)", async () => {
   const backend = new FakeBackend(false);
   const router = new NamespaceSearchRouter(

package/src/namespaces/search.ts

@@ -45,6 +45,7 @@ type NamespaceBackendRecord = {
   available: boolean;
   collectionState: CollectionState;
   filtersNestedNamespaces: boolean;
+  disposed: boolean;
 };
 
 export interface NamespaceUpdateResult {
@@ -83,6 +84,7 @@ type BackendRecordOptions = {
 
 export class NamespaceSearchRouter {
   private readonly cache = new Map<string, Promise<NamespaceBackendRecord>>();
+  private readonly pendingDisposals = new Set<Promise<void>>();
 
   constructor(
     private readonly config: PluginConfig,
@@ -344,21 +346,62 @@ export class NamespaceSearchRouter {
     return cachedRecord;
   }
 
+  private trackDisposal(promise: Promise<void>): void {
+    this.pendingDisposals.add(promise);
+    void promise.finally(() => this.pendingDisposals.delete(promise));
+  }
+
+  private async drainPendingDisposals(): Promise<void> {
+    if (this.pendingDisposals.size === 0) return;
+    await Promise.allSettled(this.pendingDisposals);
+  }
+
   /** Clear cached backend records so the next access re-probes availability. */
   clearCache(): void {
+    const pendingRecords = Array.from(this.cache.values());
     this.cache.clear();
+    const disposal = Promise.allSettled(pendingRecords).then(async (settled) => {
+      await Promise.allSettled(
+        settled.flatMap((entry) =>
+          entry.status === "fulfilled" ? [this.disposeRecord(entry.value)] : []),
+      );
+    });
+    this.trackDisposal(disposal);
+  }
+
+  private async disposeRecord(record: NamespaceBackendRecord): Promise<void> {
+    if (record.disposed) return;
+    record.disposed = true;
+    const dispose = (record.backend as { dispose?: () => void | Promise<void> }).dispose;
+    await dispose?.call(record.backend);
   }
 
   /** Release any per-namespace backend handles held by cached records. */
   async dispose(): Promise<void> {
+    await this.drainPendingDisposals();
     const pendingRecords = Array.from(this.cache.values());
     this.cache.clear();
     const settled = await Promise.allSettled(pendingRecords);
+    await Promise.allSettled(
+      settled.flatMap((entry) =>
+        entry.status === "fulfilled" ? [this.disposeRecord(entry.value)] : []),
+    );
+  }
+
+  /**
+   * Disable namespace search for this runtime while retaining the resolved
+   * records as unavailable/missing. This releases concrete QMD/daemon handles
+   * without letting later reads recreate a search backend after the root path
+   * has been switched to NoopSearchBackend for a missing collection.
+   */
+  async disableSearchBackends(): Promise<void> {
+    const settled = await Promise.allSettled(this.cache.values());
     await Promise.allSettled(
       settled.flatMap((entry) => {
         if (entry.status !== "fulfilled") return [];
-        const dispose = (entry.value.backend as { dispose?: () => void | Promise<void> }).dispose;
-        return dispose ? [dispose.call(entry.value.backend)] : [];
+        entry.value.available = false;
+        entry.value.collectionState = "missing";
+        return [this.disposeRecord(entry.value)];
       }),
     );
   }
@@ -367,6 +410,7 @@ export class NamespaceSearchRouter {
     namespace: string,
     execution?: SearchExecutionOptions,
   ): Promise<NamespaceBackendRecord> {
+    await this.drainPendingDisposals();
     const key = namespace.trim() || this.config.defaultNamespace;
     const existing = this.cache.get(key);
     if (existing) return await existing;
@@ -412,7 +456,7 @@ export class NamespaceSearchRouter {
     try {
       const availabilityProbe =
         options.autoCreateCollection || typeof backend.checkAvailability !== "function"
-          ? backend.probe()
+          ? backend.probe(execution)
           : backend.checkAvailability({ signal: execution?.signal });
       const available = await awaitWithAbort(availabilityProbe, execution?.signal).catch((error) => {
         if (error instanceof NamespaceSearchAbortError && !options.abortAsUnavailable) {
@@ -453,6 +497,7 @@ export class NamespaceSearchRouter {
         available,
         collectionState,
         filtersNestedNamespaces,
+        disposed: false,
       };
     } catch (error) {
       const dispose = (backend as { dispose?: () => void | Promise<void> }).dispose;

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

@@ -757,7 +757,229 @@ test("buildMergedTargetPromotionPayload and promotion refuse when interleaving w
   );
 });
 
-test("buildMergedTargetPromotionPayload: unavailable snapshot digest refuses when a committed digest exists (#2813 P1)", async () => {
+// ── #2870: access-only telemetry vs semantic metadata in the promotion binding ──
+
+type RawFileMutator = (raw: string) => string;
+
+const withFrontmatterLine = (line: string): RawFileMutator => (raw) =>
+  raw.replace("\n---\n", `\n${line}\n---\n`);
+
+/** Rewrite the durable file directly — a writer that changes semantics
+ * WITHOUT minting a CAS receipt (hand edit, legacy tool). Exactly the
+ * writer class the semantic-fingerprint clause must catch. */
+async function rewriteDurableWithoutReceipt(
+  storage: StorageManager,
+  memoryId: string,
+  mutate: RawFileMutator,
+): Promise<void> {
+  const row = await storage.getMemoryByIdIncludingArchived(memoryId);
+  assert.ok(row);
+  const before = await readFile(row.path, "utf8");
+  await writeFile(row.path, mutate(before), "utf8");
+}
+async function flushAccess(
+  storage: StorageManager,
+  memoryId: string,
+  newCount: number,
+): Promise<number> {
+  return await storage.flushAccessTracking([
+    { memoryId, newCount, lastAccessed: "2026-08-23T00:00:00.000Z" },
+  ]);
+}
+
+async function runPromotion(
+  s: { source: StorageManager; router: { storageFor: (namespace: string) => Promise<StorageManager> } },
+  payload: MergedTargetPromotionPayload | null,
+  sourceMemoryId: string,
+): Promise<number> {
+  let promotions = 0;
+  await promoteAndReconcileMergedTarget({
+    promote: async () => {
+      promotions += 1;
+      return `copy-${promotions}`;
+    },
+    config: parseConfig({ memoryDir: s.source.dir, sharedNamespace: "shared" }),
+    getStorageRouter: () => s.router,
+    scopeProfileWritePlan: null,
+    sourceStorage: s.source,
+    sourceMemoryId,
+    mergedPromotion: payload,
+    normalize: (content: string) => content,
+  });
+  return promotions;
+}
+
+test("access flush between merge commit and payload build still promotes (#2870)", async () => {
+  const s = await makeStorages();
+  const target = await s.source.writeMemory("fact", PRE_MERGE_BODY, {
+    source: "test",
+    confidence: 0.5,
+  });
+  await commitWriterMerge(s.source, target.id, A_MERGED_BODY);
+  const committed = await s.source.getMemoryByIdIncludingArchived(target.id);
+  assert.ok(committed);
+  const shardPath = casShardPath(s.source.dir, committed.path);
+  const receiptBefore = JSON.parse(await readFile(shardPath, "utf8")) as { revision: string };
+  const bytesBefore = await readFile(committed.path, "utf8");
+
+  assert.equal(await flushAccess(s.source, target.id, 3), 1, "the access flush landed");
+
+  // Prove the interleaving is real: bytes changed, receipt did not re-mint.
+  assert.notEqual(await readFile(committed.path, "utf8"), bytesBefore, "the flush rewrote the durable file");
+  const receiptAfter = JSON.parse(await readFile(shardPath, "utf8")) as { revision: string };
+  assert.equal(receiptAfter.revision, receiptBefore.revision, "an access flush mints no receipt");
+
+  const { payload, readFailed } = await buildMergedTargetPromotionPayload(s.source, {
+    targetId: target.id,
+    mergedContent: A_MERGED_BODY,
+    provenancePatched: true,
+  });
+  assert.equal(readFailed, false);
+  assert.ok(payload, "an access-only flush must not refuse the payload");
+  assert.ok(payload?.committedSemanticFingerprint, "the payload carries the semantic binding");
+
+  assert.equal(await runPromotion(s, payload, target.id), 1, "the flushed-but-unchanged semantics still promote");
+});
+
+test("access flush between payload build and promotion still promotes (#2870)", async () => {
+  const s = await makeStorages();
+  const target = await s.source.writeMemory("fact", PRE_MERGE_BODY, {
+    source: "test",
+    confidence: 0.5,
+  });
+  await commitWriterMerge(s.source, target.id, A_MERGED_BODY);
+  const { payload } = await buildMergedTargetPromotionPayload(s.source, {
+    targetId: target.id,
+    mergedContent: A_MERGED_BODY,
+    provenancePatched: true,
+  });
+  assert.ok(payload);
+  assert.equal(await flushAccess(s.source, target.id, 7), 1, "the access flush lands after the build");
+
+  assert.equal(await runPromotion(s, payload, target.id), 1, "the final guard confirms the flushed record's semantics");
+});
+
+test("payload build refuses a semantic mutation that minted no receipt (#2870)", async () => {
+  const s = await makeStorages();
+  const target = await s.source.writeMemory("fact", PRE_MERGE_BODY, {
+    source: "test",
+    confidence: 0.5,
+  });
+  await commitWriterMerge(s.source, target.id, A_MERGED_BODY);
+  await rewriteDurableWithoutReceipt(
+    s.source,
+    target.id,
+    (raw) => raw.replace(/^confidence: .*$/m, "confidence: 0.99"),
+  );
+  const { payload, readFailed } = await buildMergedTargetPromotionPayload(s.source, {
+    targetId: target.id,
+    mergedContent: A_MERGED_BODY,
+    provenancePatched: true,
+  });
+  assert.equal(payload, null, "a same-body confidence change must refuse the payload");
+  assert.equal(readFailed, true, "the refusal is an unknown outcome, not a no-promotion verdict");
+});
+
+test("final guard refuses each semantic field mutation that minted no receipt (#2870)", async () => {
+  const mutations: Array<[label: string, mutate: RawFileMutator]> = [
+    ["confidence", (raw) => raw.replace(/^confidence: .*$/m, "confidence: 0.99")],
+    ["tags", (raw) => raw.replace(/^tags: .*$/m, 'tags: ["mutated"]')],
+    ["status", withFrontmatterLine("status: superseded")],
+    ["provenance", withFrontmatterLine("provenance: unverified")],
+    ["tool scope", withFrontmatterLine("toolScoped: true")],
+    ["body", (raw) => `${raw}\nmutated body suffix`],
+  ];
+  for (const [label, mutate] of mutations) {
+    const s = await makeStorages();
+    const target = await s.source.writeMemory("fact", PRE_MERGE_BODY, {
+      source: "test",
+      confidence: 0.5,
+    });
+    await commitWriterMerge(s.source, target.id, A_MERGED_BODY);
+    const { payload } = await buildMergedTargetPromotionPayload(s.source, {
+      targetId: target.id,
+      mergedContent: A_MERGED_BODY,
+      provenancePatched: true,
+    });
+    assert.ok(payload, `payload builds before the ${label} mutation`);
+    await rewriteDurableWithoutReceipt(s.source, target.id, mutate);
+
+    assert.equal(
+      await runPromotion(s, payload, target.id),
+      0,
+      `a ${label} mutation without a receipt must refuse promotion`,
+    );
+  }
+});
+
+test("a PENDING receipt marker between build and promotion abandons it (#2870)", async () => {
+  const s = await makeStorages();
+  const target = await s.source.writeMemory("fact", PRE_MERGE_BODY, {
+    source: "test",
+    confidence: 0.5,
+  });
+  await commitWriterMerge(s.source, target.id, A_MERGED_BODY);
+  const { payload } = await buildMergedTargetPromotionPayload(s.source, {
+    targetId: target.id,
+    mergedContent: A_MERGED_BODY,
+    provenancePatched: true,
+  });
+  assert.ok(payload);
+  const committed = await s.source.getMemoryByIdIncludingArchived(target.id);
+  assert.ok(committed);
+  const shardPath = casShardPath(s.source.dir, committed.path);
+  const relative = path.relative(s.source.dir, committed.path).split(path.sep).join("/");
+  // A pending marker whose expected digest matches nothing: lazy recovery
+  // cannot decide it, so the receipt reads UNAVAILABLE and the promotion
+  // must refuse rather than confirm against an unknown identity.
+  await writeFile(
+    shardPath,
+    `${JSON.stringify({
+      version: 1,
+      path: relative,
+      revision: "2026-08-23T00:00:00.001Z",
+      state: "pending",
+      previous: payload.committedRevision ?? "2026-08-23T00:00:00.000Z",
+      baselineDigest: "0".repeat(64),
+      expectedDigest: "1".repeat(64),
+    })}\n`,
+    "utf8",
+  );
+
+  assert.equal(
+    await runPromotion(s, payload, target.id),
+    0,
+    "a pending (recovery-needed) receipt must not confirm the payload",
+  );
+});
+
+test("a legacy shard without a stored semantic fingerprint keeps the conservative digest refusal (#2870)", async () => {
+  const s = await makeStorages();
+  const target = await s.source.writeMemory("fact", PRE_MERGE_BODY, {
+    source: "test",
+    confidence: 0.5,
+  });
+  await commitWriterMerge(s.source, target.id, A_MERGED_BODY);
+  const committed = await s.source.getMemoryByIdIncludingArchived(target.id);
+  assert.ok(committed);
+  // Downgrade the shard to its pre-#2870 shape: committed digest, no
+  // semantic fingerprint.
+  const shardPath = casShardPath(s.source.dir, committed.path);
+  const shard = JSON.parse(await readFile(shardPath, "utf8")) as Record<string, unknown>;
+  delete shard.committedSemanticFingerprint;
+  await writeFile(shardPath, `${JSON.stringify(shard)}\n`, "utf8");
+
+  assert.equal(await flushAccess(s.source, target.id, 4), 1, "the access flush lands on the legacy shard");
+  const { payload, readFailed } = await buildMergedTargetPromotionPayload(s.source, {
+    targetId: target.id,
+    mergedContent: A_MERGED_BODY,
+    provenancePatched: true,
+  });
+  assert.equal(payload, null, "legacy shards keep the full-digest binding until the next semantic write");
+  assert.equal(readFailed, true);
+});
+
+test("legacy receipt with unavailable snapshot digest refuses promotion (#2813 P1, #2870)", async () => {
   const s = await makeStorages();
   const target = await s.source.writeMemory("fact", PRE_MERGE_BODY, { source: "test" });
   await commitWriterMerge(s.source, target.id, A_MERGED_BODY);
@@ -769,6 +991,10 @@ test("buildMergedTargetPromotionPayload: unavailable snapshot digest refuses whe
     status.status === "present" && status.committedDigest,
     "the standing receipt carries a committed digest",
   );
+  const shardPath = casShardPath(s.source.dir, committedRow.path);
+  const shard = JSON.parse(await readFile(shardPath, "utf8")) as Record<string, unknown>;
+  delete shard.committedSemanticFingerprint;
+  await writeFile(shardPath, `${JSON.stringify(shard)}\n`, "utf8");
 
   s.source.readDurableFileDigest = async () => null;
   const built = await buildMergedTargetPromotionPayload(s.source, {
@@ -776,7 +1002,7 @@ test("buildMergedTargetPromotionPayload: unavailable snapshot digest refuses whe
     mergedContent: A_MERGED_BODY,
     provenancePatched: true,
   });
-  assert.equal(built.payload, null, "an unreadable snapshot digest must refuse the promotion");
+  assert.equal(built.payload, null, "an unreadable snapshot digest must refuse the legacy receipt");
   assert.equal(built.readFailed, true, "unavailable snapshot is unknown, not an absent revision");
 
   const legacyStore = await makeStorages();