@remnic/core 9.69.45 → 9.69.46

package/src/orchestration/recall-search-pipeline.test.ts

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import os from "node:os";
 import path from "node:path";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, utimes, writeFile } from "node:fs/promises";
 import test from "node:test";
 
 import { parseConfig } from "../config.js";
@@ -565,3 +565,209 @@ test("QMD stops after an underfilled archive-only page", async () => {
   assert.deepEqual(out, []);
   assert.equal(searchCalls, 1, "an underfilled raw page must not trigger widening");
 });
+
+// ─── #2976: memory age from content dates; bulk-touch mtime distrust ─────────
+
+const AGE_DAY_MS = 86_400_000;
+
+function scoredResult(namespace: string, p: string, score: number): QmdSearchResult {
+  return { docid: `${namespace}:${p}`, namespace, path: p, score, snippet: p };
+}
+
+function ageMemory(absPath: string, frontmatter: Record<string, unknown>): MemoryFile {
+  return {
+    path: absPath,
+    content: absPath,
+    frontmatter: { status: "active", memoryKind: "fact", ...frontmatter } as unknown as MemoryFile["frontmatter"],
+  };
+}
+
+function boostCoordinator(
+  memoryDir: string,
+  recencyWeight: number,
+): RecallSearchPipelineCoordinator {
+  const config = parseConfig({
+    openaiApiKey: "sk-test",
+    memoryDir,
+    workspaceDir: path.join(memoryDir, "workspace"),
+  });
+  const deps = {
+    config,
+    effectiveRecencyWeight: () => recencyWeight,
+    filterSearchResultsForRecall: async (
+      results: QmdSearchResult[],
+      preloaded?: Map<string, MemoryFile>,
+    ) => ({ results, memoryByPath: preloaded ?? new Map() }),
+  } as unknown as RecallSearchPipelineDeps;
+  return new RecallSearchPipelineCoordinator(deps);
+}
+
+async function writeDatedFile(filePath: string, mtimeMs: number): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, "fixture\n");
+  await utimes(filePath, mtimeMs / 1000, mtimeMs / 1000);
+}
+
+function isoAgo(now: number, days: number): string {
+  return new Date(now - days * AGE_DAY_MS).toISOString();
+}
+
+test("#2976 content dates age a memory even when its mtime is fresh (updated backs a missing created)", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-age-content-"));
+  try {
+    const now = Date.now();
+    const fileA = path.join(memoryDir, "facts", "a.md");
+    const fileB = path.join(memoryDir, "facts", "b.md");
+    // Both files carry today's mtime — the bulk import / cp -r shape. A has
+    // no created, only a 40-day-old updated; B carries a 40-day-old created.
+    await writeDatedFile(fileA, now);
+    await writeDatedFile(fileB, now);
+    const memoryByPath = new Map<string, MemoryFile>([
+      ["default\0facts/a.md", ageMemory(fileA, { updated: isoAgo(now, 40) })],
+      ["default\0facts/b.md", ageMemory(fileB, { created: isoAgo(now, 40), updated: isoAgo(now, 40) })],
+    ]);
+
+    const boosted = await boostCoordinator(memoryDir, 0.5).boostSearchResults(
+      [scoredResult("default", "facts/a.md", 1), scoredResult("default", "facts/b.md", 1)],
+      ["default"],
+      undefined,
+      memoryByPath,
+    );
+
+    const [a, b] = boosted;
+    const expected = 1 * 0.5 + Math.pow(0.5, 40 / 7) * 0.5;
+    assert.ok(a && Number.isFinite(a.score), "a memory without created must not score NaN");
+    assert.ok(b && Number.isFinite(b.score));
+    assert.ok(Math.abs(a.score - expected) < 1e-9, `ages by the 40-day-old content date (${a?.score}), not the fresh mtime (1.0)`);
+    assert.equal(a.score, b.score, "updated and created of the same age produce the same score");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("#2976 a bulk-touch mtime cluster never inflates freshness (ranking unchanged vs pre-touch base order)", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-age-bulk-"));
+  try {
+    const now = Date.now();
+    const files = ["facts/x.md", "facts/y.md", "facts/z.md"];
+    const baseScores = [0.9, 0.8, 0.7];
+    const mtimes = [now - 10 * AGE_DAY_MS, now - 30 * AGE_DAY_MS, now - 90 * AGE_DAY_MS];
+    // Undated memories: only mtime can say how old they are.
+    const buildMap = () =>
+      new Map<string, MemoryFile>(
+        files.map((rel) => ["default\0" + rel, ageMemory(path.join(memoryDir, rel), {})]),
+      );
+    for (let i = 0; i < files.length; i += 1) {
+      await writeDatedFile(path.join(memoryDir, files[i]!), mtimes[i]!);
+    }
+    const results = () => files.map((rel, i) => scoredResult("default", rel, baseScores[i]!));
+
+    // Pre-touch: mtimes are scattered, so each trusted mtime ages its memory.
+    const preTouch = await boostCoordinator(memoryDir, 0.5).boostSearchResults(
+      results(),
+      ["default"],
+      undefined,
+      buildMap(),
+    );
+    for (const r of preTouch) {
+      assert.ok(Number.isFinite(r.score), "an undated memory with a trusted mtime must not score NaN");
+    }
+    assert.deepEqual(
+      preTouch.map((r) => r.path),
+      ["facts/x.md", "facts/y.md", "facts/z.md"],
+      "pre-touch, the scattered trusted mtimes preserve the base ranking",
+    );
+
+    // Bulk touch: every mtime reset to one calendar day (cp -r / restore).
+    const bulkDay = now - 1 * AGE_DAY_MS;
+    for (const rel of files) {
+      await writeDatedFile(path.join(memoryDir, rel), bulkDay);
+    }
+    const postTouch = await boostCoordinator(memoryDir, 0.5).boostSearchResults(
+      results(),
+      ["default"],
+      undefined,
+      buildMap(),
+    );
+    assert.deepEqual(
+      postTouch.map((r) => r.score),
+      baseScores,
+      "a same-day mtime cluster is distrusted: no recency boost, scores stay at base",
+    );
+    assert.deepEqual(
+      postTouch.map((r) => r.path),
+      ["facts/x.md", "facts/y.md", "facts/z.md"],
+      "ranking is unchanged versus the pre-touch base order",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("#2976 an undated memory falls back to a trusted scattered mtime; a dated sibling keeps its content age", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-age-fallback-"));
+  try {
+    const now = Date.now();
+    const fileA = path.join(memoryDir, "facts", "undated.md");
+    const fileB = path.join(memoryDir, "facts", "dated.md");
+    // A: no dates, mtime 2 days ago. B: created 2 days ago, mtime 5 days ago
+    // (different days, one file each — no cluster, mtime stays trusted).
+    await writeDatedFile(fileA, now - 2 * AGE_DAY_MS);
+    await writeDatedFile(fileB, now - 5 * AGE_DAY_MS);
+    const memoryByPath = new Map<string, MemoryFile>([
+      ["default\0facts/undated.md", ageMemory(fileA, {})],
+      ["default\0facts/dated.md", ageMemory(fileB, { created: isoAgo(now, 2), updated: isoAgo(now, 2) })],
+    ]);
+
+    const boosted = await boostCoordinator(memoryDir, 0.5).boostSearchResults(
+      [scoredResult("default", "facts/undated.md", 1), scoredResult("default", "facts/dated.md", 1)],
+      ["default"],
+      undefined,
+      memoryByPath,
+    );
+
+    const [undated, dated] = boosted;
+    // 1e-6 (not 1e-9): the pipeline stamps its own Date.now() after this
+    // test's fixture writes, so a few ms of clock drift shifts the 2-day
+    // blend in the 8th decimal.
+    const expected = 1 * 0.5 + Math.pow(0.5, 2 / 7) * 0.5;
+    assert.ok(undated && Number.isFinite(undated.score), "the undated memory must not score NaN");
+    assert.ok(
+      undated && Math.abs(undated.score - expected) < 1e-6,
+      `an undated memory ages by its trusted mtime (2 days): got ${undated?.score}, want ~${expected}`,
+    );
+    assert.ok(
+      undated && dated && Math.abs(undated.score - dated.score) < 1e-6,
+      "mtime fallback and a same-aged content date score identically",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("#2976 guard: a memory whose content date is older than its fresh mtime ages by the content date", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-age-guard-"));
+  try {
+    const now = Date.now();
+    const filePath = path.join(memoryDir, "facts", "old.md");
+    await writeDatedFile(filePath, now); // fresh mtime, 90-day-old content
+    const memoryByPath = new Map<string, MemoryFile>([
+      ["default\0facts/old.md", ageMemory(filePath, { created: isoAgo(now, 90), updated: isoAgo(now, 90) })],
+    ]);
+
+    const boosted = await boostCoordinator(memoryDir, 0.5).boostSearchResults(
+      [scoredResult("default", "facts/old.md", 1)],
+      ["default"],
+      undefined,
+      memoryByPath,
+    );
+
+    const expected = 1 * 0.5 + Math.pow(0.5, 90 / 7) * 0.5;
+    assert.ok(
+      boosted[0] && Math.abs(boosted[0].score - expected) < 1e-9,
+      "ages by the 90-day-old created date, not the fresh mtime",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/orchestration/recall-search-pipeline.ts

@@ -34,6 +34,7 @@ import { RerankCache, rerankLocalOrNoop, reorderByRankedKeys } from "../rerank.j
 import type { SearchBackend, SearchDegradation, SearchExecutionOptions, SearchQueryOptions } from "../search/port.js";
 import { SecureStoreLockedError } from "../secure-store/index.js";
 import { isPathInsideStorageRoot } from "../storage-paths.js";
+import { applyRecencyBoost, collectMtimeFallbackContext } from "../memory-age.js";
 import type { CorpusReadOptions } from "../corpus-read-cancellation.js";
 import { extractTagsFromPrompt, isTemporalQuery, queryByDateRangeAsync, queryByTagsAsync, readIndexSnapshotAsync, recencyWindowFromPrompt } from "../temporal-index.js";
 import {
@@ -1558,20 +1559,23 @@ export class RecallSearchPipelineCoordinator {
 
     const boosted: QmdSearchResult[] = [];
     const recencyWeight = this.deps.effectiveRecencyWeight();
+    // #2976: mtime backs age only for memories without content dates, and a
+    // same-day mtime cluster (bulk import / restore / cp -r) is distrusted.
+    const mtimeFallback =
+      recencyWeight > 0
+        ? await collectMtimeFallbackContext(
+            safeResults.flatMap((r) => { const m = memoryForResult(memoryByPath, r); return m ? [m] : []; }),
+          )
+        : null;
     for (const r of safeResults) {
       const memory = memoryForResult(memoryByPath, r);
       let score = r.score;
 
       if (memory) {
-        // Recency boost: exponential decay over 7 days
-        if (recencyWeight > 0) {
-          const createdAt = new Date(memory.frontmatter.created).getTime();
-          const ageMs = now - createdAt;
-          const ageDays = ageMs / (1000 * 60 * 60 * 24);
-          const halfLifeDays = 7;
-          const recencyScore = Math.pow(0.5, ageDays / halfLifeDays);
-          score = score * (1 - recencyWeight) + recencyScore * recencyWeight;
-        }
+        // Recency boost: 7-day exponential decay over the shared age resolver
+        // (#2976): content dates first, trusted mtime as fallback, unknown
+        // age never fresh. See memory-age.ts.
+        score = applyRecencyBoost(score, memory, recencyWeight, now, mtimeFallback);
 
         // Access count boost: log scale, capped
         if (this.deps.config.boostAccessCount && memory.frontmatter.accessCount) {

package/src/orchestration/semantic-merge-commit-effects.ts

@@ -13,6 +13,7 @@
  */
 
 import { GraphEdgeAppendError } from "../graph-append-error.js";
+import type { CasRevisionReadStatus } from "../storage/cas-revision-store.js";
 import type { GraphEdge, GraphType } from "../graph.js";
 import { readFile } from "node:fs/promises";
 import { removeNodeEdgesForRewrite, rollbackNodeEdgeRewrite } from "../graph-jsonl.js";
@@ -259,8 +260,8 @@ export async function persistMergedTargetThreadEpisode(
 }
 
 /**
- * Round N+12 (C) + N+14: replace a merged target's generated graph edges
- * with the rebuild's rows, revision-guarded end to end. The caller's
+ * Round N+12 (C) + N+14 + #2837: replace a merged target's generated graph
+ * edges with the rebuild's rows, revision-guarded end to end. The caller's
  * committed-body check can pass, writer B can then commit a NEWER merge and
  * finish rebuilding edges for it, and writer A would resume to remove B's
  * edges and install edges derived from A's older body. The revision observed
@@ -271,6 +272,15 @@ export async function persistMergedTargetThreadEpisode(
  * chain only then). A build failure rolls back the same way (round N+10 C)
  * and rethrows — fail-open stays the caller's decision.
  *
+ * #2837: the post-build guard reads the truthful receipt STATUS, never the
+ * fail-open token. The old guard collapsed an unreadable sidecar into
+ * undefined on both reads, so an unavailable-vs-unavailable rewrite compared
+ * undefined against undefined, passed, and installed replacement edges no
+ * receipt ever verified. An `unavailable` post-build status now aborts the
+ * install (rollback, false) so the next merge retries; only a PROVEN match —
+ * present-and-equal, or absent-against-absent for a pre-sidecar target —
+ * may install.
+ *
  * Round N+14 makes the ROLLBACK surgical: `build` returns the exact rows it
  * appended (by identity), and the rollback removes only those — never a
  * node-wide sweep — so rows a newer writer appended after this writer's
@@ -283,13 +293,14 @@ export async function rewriteMergedTargetGraphEdges(
   storage: {
     dir: string;
     getMemoryByIdIncludingArchived: (id: string) => Promise<MemoryFile | null>;
-    readCasRevision: (filePath: string) => Promise<string | undefined>;
+    readCasRevisionStatus: (filePath: string) => Promise<CasRevisionReadStatus>;
   },
   input: {
     targetId: string;
     memoryRelPath: string;
     mergedContent: string;
-    /** The CAS revision token the committed-body check observed. */
+    /** The CAS revision token the committed-body check observed (undefined
+     * only when the check PROVED the receipt absent — #2837). */
     revisionChecked: string | undefined;
     rewriteTypes: readonly GraphType[];
     build: () => Promise<GraphEdge[] | void>;
@@ -306,15 +317,26 @@ export async function rewriteMergedTargetGraphEdges(
   try {
     appended = (await input.build()) ?? undefined;
     const committedNow = await storage.getMemoryByIdIncludingArchived(input.targetId);
-    const committedRevision = committedNow === null ? undefined : await storage.readCasRevision(committedNow.path).catch((err) => {
-      log.warn(`rewriteMergedTargetGraphEdges: failed to read CAS revision for ${committedNow.path}: ${err}`);
-      return undefined;
-    });
+    let standing: CasRevisionReadStatus;
+    if (committedNow === null) {
+      standing = { status: "absent" };
+    } else {
+      standing = await storage.readCasRevisionStatus(committedNow.path).catch((err: unknown) => ({
+        status: "unavailable" as const,
+        reason: err instanceof Error ? err.message : String(err),
+      }));
+    }
     if (
       !committedNow ||
       committedNow.content !== input.mergedContent ||
-      committedRevision !== input.revisionChecked
+      standing.status === "unavailable" ||
+      (standing.status === "present" ? standing.revision : undefined) !== input.revisionChecked
     ) {
+      if (standing.status === "unavailable") {
+        log.warn(
+          `rewriteMergedTargetGraphEdges: CAS revision status for ${input.memoryRelPath} is unavailable (${standing.reason}); aborting the install — an unverified replacement must not install (#2837)`,
+        );
+      }
       await rollbackNodeEdgeRewrite(storage.dir, input.memoryRelPath, input.rewriteTypes, removedEdges, input.targetId, appended);
       return false;
     }

package/src/orchestration/semantic-merge-persist.ts

@@ -1144,15 +1144,26 @@ export async function runMergedTargetPostEffects(
     if (input.graphCaps.entityGraph) rewriteTypes.push("entity");
     if (input.graphCaps.timeGraph) rewriteTypes.push("time");
     if (input.graphCaps.causalGraph) rewriteTypes.push("causal");
-    // Round N+12 (C): the remove-and-rebuild is revision-guarded end to end
-    // (see rewriteMergedTargetGraphEdges) — a writer committing a newer body
-    // mid-rebuild aborts this install instead of clobbering its edges.
+    // Round N+12 (C) + #2837: the remove-and-rebuild is revision-guarded
+    // end to end (see rewriteMergedTargetGraphEdges) — a writer committing
+    // a newer body mid-rebuild aborts this install instead of clobbering
+    // its edges. The guard compares the truthful receipt STATUS (#2807:
+    // the dedicated CAS revision token, never public `updated`), and an
+    // UNAVAILABLE sidecar SKIPS the effect entirely: passing a fail-open
+    // undefined into the install is what let an unchecked replacement
+    // install when both sidecar reads failed.
+    const receiptStatus = await storage.readCasRevisionStatus(committed.path);
+    if (receiptStatus.status === "unavailable") {
+      log.warn(
+        `runMergedTargetPostEffects: CAS revision status for ${committed.path} is unavailable (${receiptStatus.reason}); skipping the graph rewrite — the next merge retries it (#2837)`,
+      );
+      return signals;
+    }
     rewriteInstalled = await rewriteMergedTargetGraphEdges(storage, {
       targetId: merge.targetId,
       memoryRelPath,
       mergedContent: merge.mergedContent,
-      // #2807: the dedicated CAS revision token, not public `updated`.
-      revisionChecked: await storage.readCasRevision(committed.path),
+      revisionChecked: receiptStatus.status === "present" ? receiptStatus.revision : undefined,
       rewriteTypes,
       build: () =>
         deps.buildGraphEdge(

package/src/storage/cas-revision-host.ts

@@ -72,4 +72,26 @@ export class CasRevisionHost extends CasRevisionStore {
     await this.recoverPendingRevision(pathname);
     return await this.beginRevisionTransaction(pathname, expectedContent);
   }
+
+  /** #2837: best-effort post-deletion sweep of the target's receipt shard.
+   * The durable memory file is already gone, so a failed sweep must never
+   * fail the deletion itself — it logs instead. A PENDING shard (crash
+   * recovery evidence) and a foreign shard (another target's receipt) are
+   * kept, with a warning naming the recovery path. */
+  async sweepShardAfterDeletion(filePath: string): Promise<void> {
+    try {
+      const outcome = await this.removeRevisionShard(filePath);
+      if (outcome === "pending") {
+        log.warn(
+          `CAS revision shard for ${filePath} kept after memory deletion: a pending reservation stands — run recovery before the path is reused`,
+        );
+      } else if (outcome === "foreign") {
+        log.warn(
+          `CAS revision shard for ${filePath} kept after memory deletion: the shard names another target`,
+        );
+      }
+    } catch (err) {
+      log.warn(`failed to sweep CAS revision shard for deleted memory ${filePath}: ${err}`);
+    }
+  }
 }

package/src/storage/cas-revision-store.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { createHash } from "node:crypto";
-import { mkdir, mkdtemp, readFile, readdir, rm, symlink, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, readdir, rm, stat, symlink, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -461,3 +461,46 @@ test("legacy landed pending whose file no longer matches expectedDigest is ambig
     assert.equal((await store.readRevisionStatus(target)).status, "unavailable");
   });
 });
+
+test("removeRevisionShard sweeps a committed shard, keeps pending evidence, never touches a foreign shard (#2837)", async () => {
+  await withStore(async (store, root) => {
+    const target = path.join(root, "memories", "fact-deleted.md");
+    const shard = shardPathFor(root, target);
+    const shardExists = async () =>
+      stat(shard).then(
+        () => true,
+        () => false,
+      );
+
+    // No receipt was ever minted: the sweep reports absence, not an error.
+    assert.equal(await store.removeRevisionShard(target), "absent");
+
+    const a = await store.beginRevisionTransaction(target);
+    await a.commit();
+    assert.equal(await shardExists(), true);
+    assert.equal(await store.removeRevisionShard(target), "removed");
+    assert.equal(await shardExists(), false, "the committed shard is gone once its memory is deleted");
+    assert.equal((await store.readRevisionStatus(target)).status, "absent");
+
+    // A PENDING marker is crash-recovery evidence: the sweep must keep it.
+    const b = await store.beginRevisionTransaction(target);
+    assert.equal(await store.removeRevisionShard(target), "pending");
+    assert.equal(await shardExists(), true, "the pending marker survives the deletion sweep");
+    await b.abort();
+
+    // A shard naming another target is never destroyed by this target's sweep.
+    await mkdir(path.dirname(shard), { recursive: true });
+    await writeFile(
+      shard,
+      `${JSON.stringify({
+        version: 1,
+        path: "memories/someone-else.md",
+        revision: "2026-08-01T00:00:00.000Z",
+        state: "committed",
+      })}\n`,
+      "utf8",
+    );
+    assert.equal(await store.removeRevisionShard(target), "foreign");
+    assert.equal(await shardExists(), true, "a foreign shard is kept — it names another target");
+  });
+});

package/src/storage/cas-revision-store.ts

@@ -641,6 +641,29 @@ export class CasRevisionStore {
     });
   }
 
+  /** #2837: remove the target's receipt shard once its durable memory file
+   * has been deleted, so orphan shards cannot accumulate. Under the shard
+   * lock: a PENDING marker is crash-recovery evidence for
+   * {@link recoverPendingRevision} and is KEPT ("pending"); a shard naming
+   * another target is KEPT ("foreign") — never destroy a receipt you cannot
+   * attribute. Never touches the durable memory file or the legacy global
+   * metadata: a stale legacy entry keeps per-path monotonicity if the path
+   * is ever reused. */
+  async removeRevisionShard(
+    filePath: string,
+  ): Promise<"removed" | "absent" | "pending" | "foreign"> {
+    const relativePath = await this.resolveRelativePath(filePath);
+    return await this.withShardLock(relativePath, async () => {
+      const { shardPath } = await this.getSafeShardInfo(relativePath);
+      const view = await this.readShardView(shardPath, relativePath);
+      if (view.kind === "missing") return "absent";
+      if (view.kind === "pending") return view.foreign ? "foreign" : "pending";
+      if (view.kind === "foreign" || view.foreign) return "foreign";
+      await unlink(shardPath);
+      return "removed";
+    });
+  }
+
   /** #2813 (P1 C): recovery for a reservation left PENDING by a crash or a
    * failed publication. The caller supplies the KNOWN outcome of the
    * durable memory write: `fileWriteLanded` publishes the pending token as

package/src/storage/tombstone-blocked-capture-sync.ts

@@ -10,6 +10,7 @@ import { withRawEntityPageMutation } from "./entity-canonical-id-lock.js";
 import { readMaybeEncryptedFileFromChunks, writeMaybeEncryptedFileFromChunks } from "../secure-store/secure-fs.js";
 import * as archiveMutation from "../archive-mutation-version.js";
 import { invalidationCommitFingerprint, isSemanticFrontmatterChange } from "./deletion-revision-store.js";
+import { CasRevisionHost } from "./cas-revision-host.js";
 import type { CasRevisionTransaction } from "./cas-revision-store.js";
 import {
   buildExplicitCaptureDedupKey,
@@ -208,7 +209,11 @@ export abstract class TombstoneBlockedCaptureIndexHost {
   protected abstract bumpMemoryStatusVersion(): void;
   protected abstract bumpMemoryCorpusVersion(): void;
   protected abstract markFactHashIndexNotAuthoritative(): void;
-  protected abstract deleteManagedStorageFile(filePath: string, deletionMtimeMs?: number | null): Promise<boolean>;
+  /** #2837: durable unlink plus deletion-revision record, WITHOUT the CAS
+   * shard sweep — the concrete {@link deleteManagedStorageFile} composes the
+   * two so every deletion funnel (invalidation, maintenance purge, archive
+   * move, offline sync) sweeps. */
+  protected abstract deleteManagedStorageFileDurable(filePath: string, deletionMtimeMs?: number | null): Promise<boolean>;
   protected abstract writeManagedStorageFile(filePath: string, write: () => Promise<void>): Promise<void>;
 
   /** #2813 (P1 C, #2807): reserve the target's next durable CAS revision
@@ -221,6 +226,26 @@ export abstract class TombstoneBlockedCaptureIndexHost {
     return undefined;
   }
 
+  /** #2837 (shard cleanup): after a managed memory file is durably deleted,
+   * sweep its per-target CAS receipt shard so orphan shards cannot grow
+   * forever. The sweep runs under the shard's own lock and is best-effort —
+   * the memory file is already gone, so a sweep failure logs and never
+   * fails the delete. The sweeper is a second CasRevisionHost over the same
+   * memory dir; the host is stateless and every mutation serializes through
+   * the sidecar's file locks, so it shares the same shard files
+   * StorageManager's own host operates on. */
+  private deletedMemoryShardSweeper: CasRevisionHost | null = null;
+
+  protected async deleteManagedStorageFile(filePath: string, deletionMtimeMs?: number | null): Promise<boolean> {
+    const deleted = await this.deleteManagedStorageFileDurable(filePath, deletionMtimeMs);
+    if (!deleted) return false;
+    if (this.deletedMemoryShardSweeper === null) {
+      this.deletedMemoryShardSweeper = new CasRevisionHost(this.tombstoneBlockedCaptureIndexOptions().memoryDir);
+    }
+    await this.deletedMemoryShardSweeper.sweepShardAfterDeletion(filePath);
+    return true;
+  }
+
   private async writeStorageSecureFileChunks(filePath: string, chunks: AsyncIterable<Buffer>): Promise<void> {
     const options = this.tombstoneBlockedCaptureIndexOptions();
     await writeMaybeEncryptedFileFromChunks(

package/src/storage-frontmatter-cas.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { mkdir, mkdtemp, readdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, readFile, rm, stat, symlink, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
@@ -838,3 +838,51 @@ test("crash after memory write before writeLanded recovers from host-forwarded e
     );
   });
 });
+
+test("deleting a memory sweeps its CAS revision shard (#2837)", async () => {
+  await withStorageDir(async (dir) => {
+    const storage = new StorageManager(dir);
+    const created = await storage.writeMemory("fact", "Deletion shard sweep content.", { source: "test" });
+    const memory = await storage.getMemoryById(created.id);
+    assert.ok(memory);
+
+    // Mint a standing receipt, then delete the memory through the public
+    // invalidation funnel (the same funnel maintenance purge and archive
+    // moves use underneath).
+    assert.equal(await storage.writeMemoryFrontmatter(memory, { tags: ["sweep"] }), true);
+    const shard = casShardPath(dir, memory.path);
+    assert.equal((await storage.readCasRevisionStatus(memory.path)).status, "present");
+    await stat(shard);
+
+    assert.equal(await storage.invalidateMemory(created.id), true);
+    assert.equal(await stat(shard).then(() => true, () => false), false, "the deleted memory's shard is swept");
+    assert.equal(
+      (await storage.readCasRevisionStatus(memory.path)).status,
+      "absent",
+      "no standing receipt survives the memory",
+    );
+  });
+});
+
+test("a pending shard survives memory deletion as recovery evidence, and the delete still succeeds (#2837)", async () => {
+  await withStorageDir(async (dir) => {
+    const storage = new StorageManager(dir);
+    const created = await storage.writeMemory("fact", "Pending shard kept on delete.", { source: "test" });
+    const memory = await storage.getMemoryById(created.id);
+    assert.ok(memory);
+
+    // Crash simulation: a reservation left PENDING for this target.
+    const seams = storage as unknown as { casRevisions: CasRevisionStore };
+    await seams.casRevisions.beginRevisionTransaction(memory.path);
+    const shard = casShardPath(dir, memory.path);
+    await stat(shard);
+
+    assert.equal(await storage.invalidateMemory(created.id), true, "the deletion itself never fails on the sweep");
+    assert.equal(
+      await stat(shard).then(() => true, () => false),
+      true,
+      "a PENDING marker is crash-recovery evidence and is kept",
+    );
+    assert.equal((await storage.readCasRevisionStatus(memory.path)).status, "unavailable");
+  });
+});

package/src/storage.ts

@@ -2732,7 +2732,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
   protected async writeManagedStorageFile(filePath: string, write: () => Promise<void>): Promise<void> {
     return this.deletionRevisionStore.writeManagedStorageFile(filePath, write);
   }
-  protected async deleteManagedStorageFile(filePath: string, deletionMtimeMs?: number | null): Promise<boolean> {
+  protected async deleteManagedStorageFileDurable(filePath: string, deletionMtimeMs?: number | null): Promise<boolean> {
     return this.deletionRevisionStore.deleteManagedStorageFile(filePath, deletionMtimeMs);
   }