@remnic/core 9.69.44 → 9.69.46

package/src/dedup/merge.test.ts

@@ -769,7 +769,6 @@ async function harness(
     registerFactContentHash: async (id: string, hash: string, _expectedContent: string) => {
       calls.hashRegistrations.push({ id, hash });
     },
-    readCasRevision: async (p: string) => (p === targetPath ? casRevision : undefined),
     readCasRevisionStatus: async (p: string): Promise<CasRevisionReadStatus> => {
       if (p !== targetPath) return { status: "absent" };
       if (overrides.receiptStatus === "unavailable") {
@@ -3460,7 +3459,10 @@ async function postEffectsHarness(options: {
         : null,
     // #2807: static token — these fixtures drive the rollback paths, not
     // ownership attribution.
-    readCasRevision: async () => "2026-08-20T00:00:00.000Z",
+    readCasRevisionStatus: async (): Promise<CasRevisionReadStatus> => ({
+      status: "present",
+      revision: "2026-08-20T00:00:00.000Z",
+    }),
   } as unknown as StorageManager;
   const deps = {
     config: parseConfig({ memoryDir: dir }),
@@ -3729,6 +3731,12 @@ test("runMergedTargetPostEffects: a writer committing mid-rebuild keeps its edge
             content: buildGraphEdgeCalls > 0 ? NEWER_BODY : MERGED,
           }
         : null,
+    // #2807: B's mid-rebuild commit mints a NEW token — the identity the
+    // revision guard compares (public `updated` no longer carries it).
+    readCasRevisionStatus: async (): Promise<CasRevisionReadStatus> =>
+      buildGraphEdgeCalls > 0
+        ? { status: "present", revision: "2026-08-22T01:00:00.001Z" }
+        : { status: "present", revision: "2026-08-20T00:00:00.000Z" },
   } as unknown as StorageManager;
   const deps = {
     ...h.deps,
@@ -3800,8 +3808,10 @@ test("runMergedTargetPostEffects: a stale writer's rollback preserves the newer
         : null,
     // #2807: B's mid-rebuild commit mints a NEW token — the identity the
     // revision guard compares (public `updated` no longer carries it).
-    readCasRevision: async () =>
-      buildStarted ? "2026-08-22T01:00:00.001Z" : "2026-08-20T00:00:00.000Z",
+    readCasRevisionStatus: async (): Promise<CasRevisionReadStatus> =>
+      buildStarted
+        ? { status: "present", revision: "2026-08-22T01:00:00.001Z" }
+        : { status: "present", revision: "2026-08-20T00:00:00.000Z" },
   } as unknown as StorageManager;
   const graphConfig = parseConfig({ memoryDir: h.dir });
   const graphIndex = new GraphIndex(h.dir, graphConfig);
@@ -3849,6 +3859,170 @@ test("runMergedTargetPostEffects: a stale writer's rollback preserves the newer
   );
 });
 
+// ── #2837: the revision guard must FAIL CLOSED. The old guard read the
+// receipt fail-open (readCasRevision), so a rewrite whose BOTH sidecar reads
+// were unavailable compared undefined against undefined, passed, and
+// installed replacement edges no receipt ever verified. ────────────────────
+
+test("runMergedTargetPostEffects: both receipt reads unavailable skips the graph rewrite instead of installing unchecked (#2837)", async () => {
+  const h = await postEffectsHarness();
+  const OTHER = "facts/2026-08-19/other.md";
+  const priorEntity: GraphEdge = { from: h.targetRelPath, to: OTHER, type: "entity", weight: 1, label: "entity-billing-service", ts: "2026-08-19T00:00:00.000Z" };
+  await seedGraphFile(h.dir, "entity", [priorEntity]);
+  let built = false;
+  const storage = {
+    dir: h.dir,
+    getMemoryByIdIncludingArchived: async (id: string) =>
+      id === "fact-target"
+        ? {
+            path: path.join(h.dir, h.targetRelPath),
+            frontmatter: { id, category: "fact", entityRef: "entity-billing-service" },
+            content: MERGED,
+          }
+        : null,
+    // The fail-open collapse the OLD guard trusted: an unreadable sidecar
+    // reads as undefined on both sides of the remove-and-rebuild.
+    readCasRevision: async () => undefined,
+    readCasRevisionStatus: async (): Promise<CasRevisionReadStatus> => ({
+      status: "unavailable",
+      reason: "simulated sidecar outage",
+    }),
+  } as unknown as StorageManager;
+  const deps = {
+    ...h.deps,
+    buildGraphEdge: async () => {
+      built = true;
+    },
+  } as unknown as ExtractionPersistDeps;
+  const graphContext = { allMemsForGraph: [], memoryPathById: new Map(), previousPersistedRelPath: "facts/2026-08-18/prev.md" };
+  await runMergedTargetPostEffects(
+    deps,
+    storage,
+    { targetId: "fact-target", mergedContent: MERGED },
+    {
+      category: "fact",
+      incomingContent: INCOMING,
+      incomingConfidence: 0.9,
+      namespace: "default",
+      graphCaps: ALL_GRAPH_CAPS,
+      graphContext,
+      threadIdForEdge: undefined,
+      threadEpisodeIdsForGraph: undefined,
+    },
+  );
+  assert.equal(built, false, "the graph effect must be SKIPPED while receipt identity is unavailable");
+  assert.deepEqual(
+    await readGraphFile(h.dir, "entity"),
+    [priorEntity],
+    "the prior edges survive untouched — nothing was removed for an install that could never be verified",
+  );
+  assert.equal(graphContext.previousPersistedRelPath, "facts/2026-08-18/prev.md", "a skipped rewrite must not advance the adjacency chain");
+});
+
+test("runMergedTargetPostEffects: a receipt that becomes unavailable mid-rebuild rolls the install back (#2837)", async () => {
+  const h = await postEffectsHarness();
+  const OTHER = "facts/2026-08-19/other.md";
+  const priorEntity: GraphEdge = { from: h.targetRelPath, to: OTHER, type: "entity", weight: 1, label: "entity-billing-service", ts: "2026-08-19T00:00:00.000Z" };
+  await seedGraphFile(h.dir, "entity", [priorEntity]);
+  let buildStarted = false;
+  const storage = {
+    dir: h.dir,
+    getMemoryByIdIncludingArchived: async (id: string) =>
+      id === "fact-target"
+        ? {
+            path: path.join(h.dir, h.targetRelPath),
+            frontmatter: { id, category: "fact", entityRef: "entity-billing-service" },
+            content: MERGED,
+          }
+        : null,
+    readCasRevision: async () => undefined,
+    readCasRevisionStatus: async (): Promise<CasRevisionReadStatus> =>
+      buildStarted
+        ? { status: "unavailable", reason: "simulated transient sidecar read failure" }
+        : { status: "present", revision: "2026-08-20T00:00:00.000Z" },
+  } as unknown as StorageManager;
+  const rebuilt: GraphEdge = { from: h.targetRelPath, to: OTHER, type: "entity", weight: 1, label: "entity-billing-service-v3", ts: "2026-08-23T00:00:00.000Z" };
+  const deps = {
+    ...h.deps,
+    buildGraphEdge: async () => {
+      buildStarted = true;
+      await appendEdge(h.dir, { ...rebuilt });
+      return [{ ...rebuilt }];
+    },
+  } as unknown as ExtractionPersistDeps;
+  const graphContext = { allMemsForGraph: [], memoryPathById: new Map(), previousPersistedRelPath: "facts/2026-08-18/prev.md" };
+  await runMergedTargetPostEffects(
+    deps,
+    storage,
+    { targetId: "fact-target", mergedContent: MERGED },
+    {
+      category: "fact",
+      incomingContent: INCOMING,
+      incomingConfidence: 0.9,
+      namespace: "default",
+      graphCaps: ALL_GRAPH_CAPS,
+      graphContext,
+      threadIdForEdge: undefined,
+      threadEpisodeIdsForGraph: undefined,
+    },
+  );
+  assert.deepEqual(
+    await readGraphFile(h.dir, "entity"),
+    [priorEntity],
+    "an unverifiable post-build receipt must roll the remove-and-rebuild back to the prior edges",
+  );
+  assert.equal(graphContext.previousPersistedRelPath, "facts/2026-08-18/prev.md", "a rolled-back rewrite must not advance the adjacency chain");
+});
+test("runMergedTargetPostEffects: a genuinely absent receipt on both reads still installs (#2837)", async () => {
+  const h = await postEffectsHarness();
+  const OTHER = "facts/2026-08-19/other.md";
+  const priorEntity: GraphEdge = { from: h.targetRelPath, to: OTHER, type: "entity", weight: 1, label: "entity-billing-service", ts: "2026-08-19T00:00:00.000Z" };
+  await seedGraphFile(h.dir, "entity", [priorEntity]);
+  const storage = {
+    dir: h.dir,
+    getMemoryByIdIncludingArchived: async (id: string) =>
+      id === "fact-target"
+        ? {
+            path: path.join(h.dir, h.targetRelPath),
+            frontmatter: { id, category: "fact", entityRef: "entity-billing-service" },
+            content: MERGED,
+          }
+        : null,
+    readCasRevision: async () => undefined,
+    readCasRevisionStatus: async (): Promise<CasRevisionReadStatus> => ({ status: "absent" }),
+  } as unknown as StorageManager;
+  const rebuilt: GraphEdge = { from: h.targetRelPath, to: OTHER, type: "entity", weight: 1, label: "entity-billing-service-v3", ts: "2026-08-23T00:00:00.000Z" };
+  const deps = {
+    ...h.deps,
+    buildGraphEdge: async () => {
+      await appendEdge(h.dir, { ...rebuilt });
+      return [{ ...rebuilt }];
+    },
+  } as unknown as ExtractionPersistDeps;
+  const graphContext = { allMemsForGraph: [], memoryPathById: new Map(), previousPersistedRelPath: "facts/2026-08-18/prev.md" };
+  await runMergedTargetPostEffects(
+    deps,
+    storage,
+    { targetId: "fact-target", mergedContent: MERGED },
+    {
+      category: "fact",
+      incomingContent: INCOMING,
+      incomingConfidence: 0.9,
+      namespace: "default",
+      graphCaps: ALL_GRAPH_CAPS,
+      graphContext,
+      threadIdForEdge: undefined,
+      threadEpisodeIdsForGraph: undefined,
+    },
+  );
+  assert.deepEqual(
+    await readGraphFile(h.dir, "entity"),
+    [rebuilt],
+    "a target that never minted a receipt (pre-sidecar legacy) still installs its rebuilt edges",
+  );
+  assert.equal(graphContext.previousPersistedRelPath, h.targetRelPath, "the verified install advances the batch's adjacency chain");
+});
+
 // ── Round N+16 (A): the N+14 surgical rollback leaned on build()'s RETURN
 // value. A build that THROWS mid-append (the entity rows landed, a later
 // append failed) loses that return, and the rollback fell back to the
@@ -4194,11 +4368,12 @@ test("applySemanticMergeAtPersist: a timestamp-less retirement between the conte
   // identity the rollback compares.
   const receipt = h.calls.commitRevisions[0];
   assert.ok(receipt, "the content CAS stamped a receipt");
-  const standingToken = await h.storage.readCasRevision(h.target.path);
-  assert.ok(standingToken, "the retirement minted a new token");
+  const standingStatus = await h.storage.readCasRevisionStatus(h.target.path);
+  assert.ok(standingStatus.status === "present", "the retirement minted a standing receipt");
+  const standingToken = standingStatus.status === "present" ? standingStatus.revision : undefined;
   assert.notEqual(standingToken, receipt, "the timestamp-less retirement retired the CAS's receipt token");
   assert.ok(
-    new Date(standingToken).getTime() > new Date(receipt).getTime(),
+    standingToken !== undefined && new Date(standingToken).getTime() > new Date(receipt).getTime(),
     "the timestamp-less retirement advanced the token strictly past the CAS receipt",
   );
   assert.deepEqual(
@@ -4324,7 +4499,9 @@ test("applySemanticMergeAtPersist: the monotonic receipt survives the metadata p
     T.toISOString(),
     "#2807: the metadata patch stamps business time (mergePatch.updated) verbatim — never a revision",
   );
-  const standingToken = await h.storage.readCasRevision(h.target.path);
+  const standingRead = await h.storage.readCasRevisionStatus(h.target.path);
+  assert.equal(standingRead.status, "present", "the standing receipt is readable after the metadata patches");
+  const standingToken = standingRead.status === "present" ? standingRead.revision : undefined;
   const [aReceipt, bReceipt, cReceipt2] = h.calls.commitRevisions;
   assert.ok(aReceipt && bReceipt && cReceipt2);
   assert.ok(aReceipt < bReceipt && bReceipt < cReceipt2, "A, B, C receipts are unique and strictly increasing");

package/src/extraction-span-wire.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { applySpanMode } from "./extraction-span-wire.js";
+import { applySpanMode, extractionProviderJsonSchema } from "./extraction-span-wire.js";
 
 const TEXT = "Alice moved to Seattle";
 
@@ -18,3 +18,19 @@ test("applySpanMode: enabled slices half-open [start, end)", () => {
     end: 11,
   });
 });
+
+function factProperties(spanMode: "off" | "shadow" | "on") {
+  const schema = extractionProviderJsonSchema(spanMode);
+  const properties = schema.properties as
+    | Record<string, { items?: { properties?: Record<string, unknown> } }>
+    | undefined;
+  return properties?.facts?.items?.properties ?? {};
+}
+
+test("provider schema omits span in off mode and keeps it in on/shadow (issue #2952)", () => {
+  assert.equal("span" in factProperties("off"), false);
+  assert.equal("span" in factProperties("on"), true);
+  assert.equal("span" in factProperties("shadow"), true);
+  assert.deepEqual(extractionProviderJsonSchema("on"), extractionProviderJsonSchema("shadow"));
+  assert.notEqual(extractionProviderJsonSchema("off"), extractionProviderJsonSchema("on"));
+});

package/src/extraction-span-wire.ts

@@ -1,11 +1,14 @@
 /**
- * Extraction seam for span mode (issue #2333 leftover slice).
+ * Extraction seam for span mode (issue #2333 leftover slice + #2952).
  *
- * Default off. Callers pass `enabled`. This module does not touch
- * extraction.ts; Phase A still gates production wiring.
+ * Default off. Callers pass `enabled` to `applySpanMode`. The provider JSON
+ * schema is mode-aware so off-mode structured output cannot advertise `span`.
  */
 
+import { zodToJsonSchema } from "zod-to-json-schema";
+import type { ExtractionSpanConfig } from "./extraction-span-config.js";
 import { parseSpanOffsets, type ParsedSpan } from "./extraction-span.js";
+import { ExtractionProviderOutputSchema } from "./schemas.js";
 
 export function applySpanMode(opts: {
   enabled?: boolean | 0 | 1;
@@ -15,3 +18,43 @@ export function applySpanMode(opts: {
 }): ParsedSpan {
   return parseSpanOffsets(opts.text, { start: opts.start, end: opts.end }, opts.enabled);
 }
+
+const JSON_SCHEMA_OPTS = { $refStrategy: "none" as const, effectStrategy: "input" as const };
+
+const EXTRACTION_PROVIDER_JSON_SCHEMA_WITH_SPAN = zodToJsonSchema(
+  ExtractionProviderOutputSchema,
+  JSON_SCHEMA_OPTS,
+) as Record<string, unknown>;
+
+type FactItems = {
+  properties?: Record<string, unknown>;
+  required?: string[];
+};
+
+function omitFactSpan(schema: Record<string, unknown>): Record<string, unknown> {
+  const clone = structuredClone(schema) as {
+    properties?: { facts?: { items?: FactItems } };
+  };
+  const items = clone.properties?.facts?.items;
+  if (!items?.properties || !("span" in items.properties)) {
+    throw new Error("extraction provider schema is missing facts.items.properties.span");
+  }
+  delete items.properties.span;
+  if (Array.isArray(items.required)) {
+    items.required = items.required.filter((key) => key !== "span");
+  }
+  return clone as Record<string, unknown>;
+}
+
+const EXTRACTION_PROVIDER_JSON_SCHEMA_WITHOUT_SPAN = omitFactSpan(
+  EXTRACTION_PROVIDER_JSON_SCHEMA_WITH_SPAN,
+);
+
+/** Provider JSON schema: `span` is present in on/shadow, absent in off. */
+export function extractionProviderJsonSchema(
+  spanMode: ExtractionSpanConfig["spanMode"] = "off",
+): Record<string, unknown> {
+  return spanMode === "off"
+    ? EXTRACTION_PROVIDER_JSON_SCHEMA_WITHOUT_SPAN
+    : EXTRACTION_PROVIDER_JSON_SCHEMA_WITH_SPAN;
+}

package/src/extraction.ts

@@ -7,7 +7,6 @@ import { shouldRunProactivePass } from "./proactive-contention.js";
 import { FallbackLlmClient, fallbackLlmRuntimeContextFromConfig, gatewayTaskChainOptions } from "./fallback-llm.js";
 import { revalidateDependentsViaLlm, type RevalidationFastChatCompletion } from "./orchestration/dependency-revalidation.js";
 import {
-  ExtractionProviderOutputSchema,
   ExtractionResultSchema,
   ConsolidationResultSchema,
   IdentityConsolidationResultSchema,
@@ -53,9 +52,9 @@ import {
   eventTimePromptInstruction,
   spanModePromptSection,
 } from "./extraction-prompt.js";
-import { zodToJsonSchema } from "zod-to-json-schema";
 import { containsExtractionPlaceholder, extractionAttributes, extractionCueAnchors, extractionText, isPlainRecord } from "./extraction-normalization.js";
 import { applyExtractionSpanMaterialization, bindLocalExtractionPrompt, buildSpanMaterializeTurns, stripUntrustedFactSpans, truncateLocalExtractionConversation, type SpanMaterializeTurn } from "./extraction-span-materialize.js";
+import { extractionProviderJsonSchema } from "./extraction-span-wire.js";
 import { resolveLocalLlmCapabilities, resolveMemoryLifecycleCapabilities, resolvePipelineProcessingCapabilities, resolveRecallAuxiliaryCapabilities } from "./capabilities.js";
 type ExtractionQuestion = ExtractionResult["questions"][number];
 type ExtractedFactResult = ExtractionResult["facts"][number];
@@ -64,14 +63,6 @@ type ExtractedRelationshipResult = NonNullable<ExtractionResult["relationships"]
 
 const PROACTIVE_MIN_CONFIDENCE = 0.8;
 
-const EXTRACTION_PROVIDER_JSON_SCHEMA = zodToJsonSchema(
-  ExtractionProviderOutputSchema,
-  {
-    $refStrategy: "none",
-    effectStrategy: "input",
-  },
-) as Record<string, unknown>;
-
 function extractionEntityType(value: unknown): ExtractedEntityResult["type"] | undefined {
   const type = extractionText(value);
   if (
@@ -1353,7 +1344,7 @@ export class ExtractionEngine {
           timeoutMs: this.config.taskLlmTimeoutMs ?? this.config.localLlmTimeoutMs,
           jsonSchema: {
             name: "extraction_result",
-            schema: EXTRACTION_PROVIDER_JSON_SCHEMA,
+            schema: extractionProviderJsonSchema(this.config.extraction?.spanMode ?? "off"),
             strict: false,
           },
           signal,

package/src/memory-age.test.ts

@@ -0,0 +1,106 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  applyRecencyBoost,
+  assessMtimeTrust,
+  collectMtimeFallbackContext,
+  resolveMemoryAge,
+  utcDayKey,
+} from "./memory-age.js";
+
+const DAY_MS = 86_400_000;
+const NOW = Date.parse("2026-08-25T12:00:00.000Z");
+
+function spreadDays(count: number, startMs = NOW): number[] {
+  return Array.from({ length: count }, (_unused, i) => startMs + i * DAY_MS);
+}
+
+test("resolveMemoryAge: content dates win over a fresh mtime (#2976)", () => {
+  const created = new Date(NOW - 40 * DAY_MS).toISOString();
+  const resolved = resolveMemoryAge({ created });
+  assert.equal(resolved.source, "content");
+  assert.equal(resolved.referenceMs, Date.parse(created), "ages by the content date, not the fresh mtime");
+});
+
+test("resolveMemoryAge: created wins over updated; updated backs a missing created", () => {
+  const created = new Date(NOW - 90 * DAY_MS).toISOString();
+  const updated = new Date(NOW - 1 * DAY_MS).toISOString();
+  assert.equal(resolveMemoryAge({ created, updated }).referenceMs, Date.parse(created));
+  assert.equal(resolveMemoryAge({ created: undefined, updated }).referenceMs, Date.parse(updated));
+});
+
+test("resolveMemoryAge: unparsable content dates never produce a reference", () => {
+  for (const bad of ["not-a-date", "", "2026-13-45"] as const) {
+    const resolved = resolveMemoryAge({ created: bad, updated: bad });
+    assert.equal(resolved.referenceMs, null, `unparsable date ${JSON.stringify(bad)} must not resolve`);
+    assert.equal(resolved.source, "unknown");
+  }
+});
+
+test("resolveMemoryAge: mtime backs age only when trusted and no content date exists", () => {
+  const mtimeMs = NOW - 2 * DAY_MS;
+  const trusted = assessMtimeTrust([mtimeMs, NOW - 9 * DAY_MS]);
+  assert.equal(resolveMemoryAge({}, mtimeMs, trusted).source, "mtime");
+  assert.equal(resolveMemoryAge({ created: "garbage" }, mtimeMs, trusted).source, "mtime");
+  assert.equal(resolveMemoryAge({ created: new Date(NOW).toISOString() }, mtimeMs, trusted).source, "content");
+  const distrusted = assessMtimeTrust([mtimeMs, mtimeMs, NOW - 9 * DAY_MS, NOW - 11 * DAY_MS]);
+  assert.equal(distrusted.bulkTouchDays.has(utcDayKey(mtimeMs)), true, "two of four same-day files cluster");
+  const refused = resolveMemoryAge({}, mtimeMs, distrusted);
+  assert.equal(refused.source, "unknown", "an untrusted mtime is unknown age, never fresh");
+  assert.equal(refused.referenceMs, null);
+});
+
+test("assessMtimeTrust: the measured distill-kura shape (50 of 214 files on one day) is a bulk touch", () => {
+  const bulkDay = NOW - 400 * DAY_MS;
+  const sample = [...Array<number>(50).fill(bulkDay), ...spreadDays(164, NOW - 200 * DAY_MS)];
+  const trust = assessMtimeTrust(sample);
+  assert.equal(trust.bulkTouchDays.size, 1);
+  assert.equal(trust.bulkTouchDays.has(utcDayKey(bulkDay)), true);
+  assert.equal(trust.isTrusted(bulkDay), false);
+  assert.equal(trust.isTrusted(sample[sample.length - 1]!), true);
+});
+
+test("assessMtimeTrust: the 20% boundary is inclusive", () => {
+  // 43 of 214 = 20.09% -> flagged; 42 of 214 = 19.6% -> not flagged.
+  const flagged = assessMtimeTrust([...Array<number>(43).fill(NOW), ...spreadDays(171, NOW - 400 * DAY_MS)]);
+  assert.equal(flagged.bulkTouchDays.has(utcDayKey(NOW)), true, "43/214 on one day is >= 20%");
+  const clear = assessMtimeTrust([...Array<number>(42).fill(NOW), ...spreadDays(172, NOW - 400 * DAY_MS)]);
+  assert.equal(clear.bulkTouchDays.has(utcDayKey(NOW)), false, "42/214 on one day is < 20%");
+});
+
+test("assessMtimeTrust: a single file never forms a cluster (min 2)", () => {
+  const trust = assessMtimeTrust([NOW]);
+  assert.equal(trust.bulkTouchDays.size, 0);
+  assert.equal(trust.isTrusted(NOW), true);
+  const pair = assessMtimeTrust([NOW, NOW]);
+  assert.equal(pair.bulkTouchDays.size, 1, "two files on one day meet the min-2 rule");
+});
+
+test("applyRecencyBoost: exact blend, unknown age untouched, weight 0 untouched, future clamped", () => {
+  const memory = {
+    path: "facts/a.md",
+    frontmatter: { created: new Date(NOW - 14 * DAY_MS).toISOString() },
+  };
+  const expected = 1 * 0.5 + Math.pow(0.5, 14 / 7) * 0.5;
+  assert.ok(Math.abs(applyRecencyBoost(1, memory, 0.5, NOW) - expected) < 1e-12);
+  // Unknown age (no dates, no trusted mtime) leaves the score alone.
+  assert.equal(applyRecencyBoost(0.7, { path: "facts/b.md", frontmatter: {} }, 0.5, NOW), 0.7);
+  assert.equal(applyRecencyBoost(0.7, memory, 0, NOW), 0.7);
+  // A corrupt future date clamps to age zero instead of boosting past 1.
+  const future = {
+    path: "facts/c.md",
+    frontmatter: { created: new Date(NOW + 30 * DAY_MS).toISOString() },
+  };
+  assert.equal(applyRecencyBoost(1, future, 0.5, NOW), 1);
+});
+
+test("collectMtimeFallbackContext: fully dated memories skip it entirely (no stats)", async () => {
+  // The paths do not exist: any stat would surface below as a null mtime
+  // instead of the documented null short-circuit.
+  const context = await collectMtimeFallbackContext([
+    { path: "/nonexistent/facts/a.md", created: new Date(NOW).toISOString() },
+    { path: "/nonexistent/facts/b.md", updated: new Date(NOW).toISOString() },
+  ]);
+  assert.equal(context, null);
+});

package/src/memory-age.ts

@@ -0,0 +1,196 @@
+/**
+ * Shared memory-age resolution (issue #2976).
+ *
+ * "Age is not mtime" (distill-kura `weave.py` `age_days`): `cp -r`, a
+ * restore, a checkout, or a bulk import resets file mtimes, so any freshness
+ * mechanism keyed on mtime either switches itself off or boosts everything
+ * equally. Remnic therefore resolves a memory's age from dates written
+ * INSIDE the memory first:
+ *
+ *   1. frontmatter `created` — the recall ranking reference before #2976,
+ *      kept first so every dated memory scores exactly as it did;
+ *   2. frontmatter `updated` — the content-revision date;
+ *   3. file mtime — only when no content date exists AND the caller's trust
+ *      assessment accepts it (see `assessMtimeTrust`);
+ *   4. otherwise UNKNOWN: no reference instant, and downstream scoring must
+ *      treat unknown age as never-fresh (no recency boost), never as
+ *      "just written".
+ *
+ * Bi-temporal `valid_at`/`observedAt` are deliberately NOT in the ladder:
+ * they date when the fact was true, not when the memory was written, so a
+ * fresh correction about an old event would be misaged by them.
+ *
+ * Bulk-touch heuristic (distill-kura measured 50/214 files sharing one
+ * bulk-touch day, mtime understating true age by a median of 11 days, worst
+ * case 425): a UTC calendar day shared by >= max(BULK_TOUCH_MIN_FILES,
+ * BULK_TOUCH_STORE_FRACTION of the sampled files) is a bulk-touch day, and
+ * mtimes falling on a bulk-touch day are untrusted — those ages are unknown,
+ * not fresh. The sample is the scored result set of the calling pipeline
+ * (bounded I/O), which observes a bulk-touched store as a same-day cluster.
+ */
+
+import { stat } from "node:fs/promises";
+
+/** Minimum files sharing one calendar day before that day is bulk-touched. */
+export const BULK_TOUCH_MIN_FILES = 2;
+/** Fraction of the sampled files on one day that marks a bulk touch. */
+export const BULK_TOUCH_STORE_FRACTION = 0.2;
+
+/** Recency half-life (days) used by `applyRecencyBoost`. */
+export const RECENCY_HALF_LIFE_DAYS = 7;
+
+/** How the resolved age reference was obtained. */
+export type MemoryAgeSource = "content" | "mtime" | "unknown";
+
+export interface ResolvedMemoryAge {
+  /** Reference instant for age computations, or null when age is unknown. */
+  referenceMs: number | null;
+  source: MemoryAgeSource;
+}
+
+/** Content dates written inside the memory (frontmatter). */
+export interface MemoryAgeDates {
+  created?: string | null;
+  updated?: string | null;
+}
+
+/** Minimal memory shape the resolver needs; `path` keys the mtime fallback. */
+export interface MemoryAgeSubject extends MemoryAgeDates {
+  path: string;
+}
+
+/** MemoryFile slice `applyRecencyBoost` reads; dates live in frontmatter. */
+export interface RecencyBoostSubject {
+  path: string;
+  frontmatter: MemoryAgeDates;
+}
+
+/** Result of assessing a sample of mtimes for bulk-touch clustering. */
+export interface MtimeTrust {
+  /** UTC day keys ("YYYY-MM-DD") whose mtime counts mark a bulk touch. */
+  bulkTouchDays: ReadonlySet<string>;
+  isTrusted(mtimeMs: number): boolean;
+}
+
+/** Per-recall mtime fallback context (null when no scored memory needs it). */
+export interface MtimeFallbackContext {
+  mtimeMsByPath: Map<string, number | null>;
+  trust: MtimeTrust;
+}
+
+function finiteMs(value: string | null | undefined): number | null {
+  if (typeof value !== "string") return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/**
+ * Resolve the reference instant for a memory's age. Content dates win over
+ * mtime; an mtime is consulted only when no content date parses and the
+ * trust assessment (when provided) accepts it; otherwise age is unknown.
+ */
+export function resolveMemoryAge(
+  subject: MemoryAgeDates,
+  mtimeMs?: number | null,
+  trust?: MtimeTrust | null,
+): ResolvedMemoryAge {
+  const contentMs = finiteMs(subject.created) ?? finiteMs(subject.updated);
+  if (contentMs !== null) return { referenceMs: contentMs, source: "content" };
+  if (
+    typeof mtimeMs === "number" &&
+    Number.isFinite(mtimeMs) &&
+    trust?.isTrusted(mtimeMs) !== false
+  ) {
+    return { referenceMs: mtimeMs, source: "mtime" };
+  }
+  return { referenceMs: null, source: "unknown" };
+}
+
+/** UTC calendar-day key ("YYYY-MM-DD") for a millisecond instant. */
+export function utcDayKey(ms: number): string {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+/**
+ * Assess a sample of mtimes: days shared by >= max(BULK_TOUCH_MIN_FILES,
+ * BULK_TOUCH_STORE_FRACTION of the sample) are bulk-touch days, and their
+ * mtimes are untrusted for age. An empty or scattered sample trusts nothing
+ * less than it did before — only clustering changes anything.
+ */
+export function assessMtimeTrust(sampleMtimesMs: readonly number[]): MtimeTrust {
+  const counts = new Map<string, number>();
+  for (const ms of sampleMtimesMs) {
+    if (!Number.isFinite(ms)) continue;
+    const key = utcDayKey(ms);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  const threshold = Math.max(
+    BULK_TOUCH_MIN_FILES,
+    sampleMtimesMs.length * BULK_TOUCH_STORE_FRACTION,
+  );
+  const bulkTouchDays = new Set<string>();
+  for (const [day, count] of counts) {
+    if (count >= threshold) bulkTouchDays.add(day);
+  }
+  return {
+    bulkTouchDays,
+    isTrusted: (mtimeMs: number) => Number.isFinite(mtimeMs) && !bulkTouchDays.has(utcDayKey(mtimeMs)),
+  };
+}
+
+/**
+ * Build the mtime fallback context for a recall boost pass. Returns null —
+ * with zero stat calls — when every scored memory already has a content
+ * date, so the common path pays nothing. Otherwise stats the scored files
+ * (bounded by the result count) and assesses their mtimes for bulk-touch
+ * clustering. Unreadable files map to null mtimes (unknown age, never fresh).
+ */
+export async function collectMtimeFallbackContext(
+  memories: ReadonlyArray<MemoryAgeSubject>,
+): Promise<MtimeFallbackContext | null> {
+  const needsFallback = memories.some(
+    (m) => finiteMs(m.created) === null && finiteMs(m.updated) === null,
+  );
+  if (!needsFallback) return null;
+  const stats = await Promise.all(
+    memories.map(async (m) => {
+      try {
+        return (await stat(m.path)).mtimeMs;
+      } catch {
+        return null;
+      }
+    }),
+  );
+  const mtimeMsByPath = new Map<string, number | null>(
+    memories.map((m, i) => [m.path, stats[i] ?? null]),
+  );
+  const trust = assessMtimeTrust(
+    stats.filter((ms): ms is number => ms !== null && Number.isFinite(ms)),
+  );
+  return { mtimeMsByPath, trust };
+}
+
+/**
+ * Apply the exponential recency blend to one score. Age resolves per
+ * `resolveMemoryAge`; unknown age leaves the score untouched (never fresh).
+ * A future reference instant clamps to age zero rather than boosting above
+ * the recency ceiling (corrupt dates are not super-fresh).
+ */
+export function applyRecencyBoost(
+  score: number,
+  memory: RecencyBoostSubject,
+  recencyWeight: number,
+  nowMs: number,
+  fallback?: MtimeFallbackContext | null,
+): number {
+  if (recencyWeight <= 0) return score;
+  const resolved = resolveMemoryAge(
+    memory.frontmatter,
+    fallback?.mtimeMsByPath.get(memory.path) ?? null,
+    fallback?.trust,
+  );
+  if (resolved.referenceMs === null) return score;
+  const ageDays = Math.max(0, (nowMs - resolved.referenceMs) / 86_400_000);
+  const recencyScore = Math.pow(0.5, ageDays / RECENCY_HALF_LIFE_DAYS);
+  return score * (1 - recencyWeight) + recencyScore * recencyWeight;
+}