@remnic/core 9.45.4 → 9.45.5

package/src/access-http.ts

@@ -3424,63 +3424,6 @@ export class EngramAccessHttpServer {
     res.end(body);
   }
 
-  private async respondOfflineSnapshotStream(
-    res: ServerResponse,
-    snapshot: Awaited<ReturnType<EngramAccessService["offlineSyncSnapshotStream"]>>,
-  ): Promise<void> {
-    res.statusCode = 200;
-    res.setHeader("content-type", "application/x-ndjson; charset=utf-8");
-    res.setHeader("cache-control", "no-store");
-    const cid = correlationIdStore.getStore();
-    if (cid) {
-      res.setHeader("x-request-id", cid);
-    }
-    const waitForDrainOrClose = async (): Promise<boolean> => new Promise((resolve, reject) => {
-      const cleanup = () => {
-        res.off("drain", onDrain);
-        res.off("close", onClose);
-        res.off("error", onError);
-      };
-      const onDrain = () => {
-        cleanup();
-        resolve(true);
-      };
-      const onClose = () => {
-        cleanup();
-        resolve(false);
-      };
-      const onError = (error: Error) => {
-        cleanup();
-        reject(error);
-      };
-      res.once("drain", onDrain);
-      res.once("close", onClose);
-      res.once("error", onError);
-    });
-    const writeLine = async (payload: unknown): Promise<boolean> => {
-      if (res.destroyed || res.writableEnded) return false;
-      if (res.write(`${JSON.stringify(payload)}\n`)) return true;
-      if (res.destroyed || res.writableEnded) return false;
-      return waitForDrainOrClose();
-    };
-    if (!await writeLine({
-      type: "snapshot",
-      namespace: snapshot.namespace,
-      format: snapshot.format,
-      schemaVersion: snapshot.schemaVersion,
-      createdAt: snapshot.createdAt,
-      sourceId: snapshot.sourceId,
-      includeTranscripts: snapshot.includeTranscripts,
-      deletions: snapshot.deletions,
-    })) return;
-    for await (const file of snapshot.files) {
-      if (!await writeLine({ type: "file", file })) return;
-    }
-    if (!res.destroyed && !res.writableEnded) {
-      res.end();
-    }
-  }
-
   private respondBinary(
     res: ServerResponse,
     status: number,

package/src/access-operations-batch.ts

@@ -163,7 +163,7 @@ defineOperation({ name: "chatgpt_memory_inspector", description: "Memory inspect
     if (input.currentContextScopes !== undefined) ii.currentContextScopes = input.currentContextScopes as string[];
     if (input.allowUnverifiedPreview !== undefined) ii.allowUnverifiedPreview = input.allowUnverifiedPreview as boolean;
     const rsk = ii.sessionKey ?? (ctx.authenticatedPrincipal ? "remnic:chatgpt-memory-inspector:" + randomUUID() : undefined);
-    const xr = await ctx.service.recallXray({ query: ii.query, sessionKey: rsk, namespace: ii.namespace, currentContextScopes: ii.currentContextScopes, authenticatedPrincipal: ctx.authenticatedPrincipal, sourceConnector: ctx.sourceConnector, mode: "full", disclosure: "chunk", includeRecall: true, ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}) });
+    const xr = await ctx.service.recallXray({ query: ii.query, sessionKey: rsk, namespace: ii.namespace, currentContextScopes: ii.currentContextScopes, authenticatedPrincipal: ctx.authenticatedPrincipal, ...(ctx.sourceConnector ? { sourceConnector: ctx.sourceConnector } : {}), mode: "full", disclosure: "chunk", includeRecall: true, ...(ctx.abortSignal ? { abortSignal: ctx.abortSignal } : {}) });
     const x = xr.snapshotFound === true ? (xr.snapshot ?? null) : null;
     const r = xr.recall ?? { query: ii.query, namespace: ii.namespace ?? x?.namespace ?? "global", context: "", count: 0, memoryIds: [], results: [], fallbackUsed: false, sourcesUsed: [], disclosure: "chunk" as const };
     const ac = await ctx.service.actionConfidence(buildChatGptMemoryInspectorActionRequest(ii, r, x));

package/src/access-service-observe-lcm-parity.test.ts

@@ -910,19 +910,28 @@ test("#2128: post-flush retained cleanup is best effort and receives lifecycle g
   }]);
 });
 
-test("#2128: post-flush retained cleanup stops on abort or deadline", async () => {
+test("#2128: post-flush retained cleanup stops on abort or deadline", async (t) => {
   const probe = makeParityProbe(withSelfPolicyPrefix("pi-geek"));
-  (probe.orch as unknown as {
-    buffer: {
-      clearRetainedTurnsForSession(
+  let cleanupStarted: (() => void) | undefined;
+  const cleanupCalls: Array<{
+    sessionKey: string;
+    ownerPrincipal: string | undefined;
+    options: { abortSignal?: AbortSignal; deadlineMs?: number } | undefined;
+  }> = [];
+  Object.defineProperty(probe.orch, "buffer", {
+    configurable: true,
+    value: {
+      clearRetainedTurnsForSession: async (
         sessionKey: string,
         ownerPrincipal?: string,
         options?: { abortSignal?: AbortSignal; deadlineMs?: number },
-      ): Promise<void>;
-    };
-  }).buffer = {
-    clearRetainedTurnsForSession: async () => new Promise<void>(() => {}),
-  };
+      ) => {
+        cleanupCalls.push({ sessionKey, ownerPrincipal, options });
+        cleanupStarted?.();
+        return new Promise<void>(() => {});
+      },
+    },
+  });
   const service = new EngramAccessService(probe.orch);
   const abortController = new AbortController();
   setTimeout(() => abortController.abort(), 5).unref();
@@ -941,19 +950,35 @@ test("#2128: post-flush retained cleanup stops on abort or deadline", async () =
       ]),
     /extraction force-flush aborted/,
   );
+  assert.deepEqual(cleanupCalls[0], {
+    sessionKey: "pi-geek:cleanup-abort",
+    ownerPrincipal: "pi-geek",
+    options: { abortSignal: abortController.signal, deadlineMs: undefined },
+  });
 
+  const cleanupStartedPromise = new Promise<void>((resolve) => {
+    cleanupStarted = resolve;
+  });
+  t.mock.timers.enable({ apis: ["setTimeout", "Date"], now: 0 });
+  const deadlineFlush = service.extractionForceFlush({
+    sessionKey: "pi-geek:cleanup-deadline",
+    authenticatedPrincipal: "pi-geek",
+    deadlineMs: 5,
+  });
+  await Promise.race([
+    cleanupStartedPromise,
+    new Promise<never>((_resolve, reject) =>
+      setImmediate(() => reject(new Error("deadline cleanup did not start"))),
+    ),
+  ]);
+  assert.deepEqual(cleanupCalls[1], {
+    sessionKey: "pi-geek:cleanup-deadline",
+    ownerPrincipal: "pi-geek",
+    options: { abortSignal: undefined, deadlineMs: 5 },
+  });
+  t.mock.timers.tick(5);
   await assert.rejects(
-    () =>
-      Promise.race([
-        service.extractionForceFlush({
-          sessionKey: "pi-geek:cleanup-deadline",
-          authenticatedPrincipal: "pi-geek",
-          deadlineMs: Date.now() + 5,
-        }),
-        new Promise<never>((_resolve, reject) =>
-          setTimeout(() => reject(new Error("deadline cleanup test timed out")), 100),
-        ),
-      ]),
+    deadlineFlush,
     /replay extraction deadline exceeded \(retained_turn_cleanup\)/,
   );
 });

package/src/access-service.ts

@@ -2386,7 +2386,9 @@ export class EngramAccessService {
       } else if (extraction.degradedReason?.includes("buffer unreadable")) {
         scopedDegradedReason = "daemon extraction pipeline degraded; extraction buffer unreadable";
       } else {
-        scopedDegradedReason = "daemon extraction pipeline degraded; backlog pending extraction";
+        scopedDegradedReason =
+          `${extraction.bufferedSessionCount} buffered session(s), ` +
+          `${extraction.pendingTurnCount} turn(s) pending extraction`;
       }
     }
     const visibleExtraction =
@@ -2394,9 +2396,6 @@ export class EngramAccessService {
         ? {
             ...extraction,
             lastExtractionAt: null,
-            bufferedSessionCount: 0,
-            pendingTurnCount: 0,
-            oldestBufferedTurnAgeMs: null,
             degradedReason: scopedDegradedReason,
           }
         : extraction;

package/src/external-wiki-cli.ts

@@ -1,4 +1,4 @@
-import { type ExternalWikiRoot, searchExternalWikis } from "./external-wiki-search.js";
+import { type ExternalWikiRoot, type ExternalWikiSearchResult, searchExternalWikis } from "./external-wiki-search.js";
 
 interface ExternalWikiCliIo {
   readonly stdout: { write(chunk: string): unknown };
@@ -13,28 +13,25 @@ export async function runExternalWikiCliCommand(
   args: readonly string[],
   io: ExternalWikiCliIo
 ): Promise<number> {
-  if (args.length === 0 || args[0] === "help" || args[0] === "--help" || args[0] === "-h") {
+  if (args[0] === "help" || args[0] === "--help" || args[0] === "-h") {
     io.stdout.write(USAGE);
     return 0;
   }
-  if (args[0] !== "search") {
-    io.stderr.write(`external-wiki: unknown command '${args[0]}'\n${USAGE}`);
-    return 2;
-  }
+  const searchArgs = args[0] === "search" ? args.slice(1) : args;
 
   let limit: number | undefined;
   let wikiId: string | undefined;
   let maxCharsPerHit: number | undefined;
   let json = false;
   const queryParts: string[] = [];
-  for (let index = 1; index < args.length; index += 1) {
-    const argument = args[index];
+  for (let index = 0; index < searchArgs.length; index += 1) {
+    const argument = searchArgs[index];
     if (argument === "--json") {
       json = true;
       continue;
     }
     if (argument === "--limit" || argument === "--wiki-id" || argument === "--max-chars-per-hit") {
-      const value = args[index + 1];
+      const value = searchArgs[index + 1];
       if (value === undefined || value.startsWith("--")) {
         io.stderr.write(`external-wiki: ${argument} requires a value\n`);
         return 2;
@@ -68,25 +65,36 @@ export async function runExternalWikiCliCommand(
 
   const query = queryParts.join(" ").trim();
   if (query.length === 0) {
-    io.stderr.write(`external-wiki: query is required\n${USAGE}`);
-    return 2;
+    io.stderr.write("external-wiki: provide a search query\n");
+    return 1;
+  }
+  const enabled = roots.filter((root) => root.enabled !== false);
+  if (enabled.length === 0) {
+    io.stderr.write("external-wiki: no enabled wiki roots configured\n");
+    return 1;
   }
 
-  const result = await searchExternalWikis(roots, { query, limit, wikiId, maxCharsPerHit });
+  let result: ExternalWikiSearchResult;
+  try {
+    result = await searchExternalWikis(enabled, { query, limit, wikiId, maxCharsPerHit });
+  } catch (error) {
+    io.stderr.write(`external-wiki: ${error instanceof Error ? error.message : "search failed"}\n`);
+    return 1;
+  }
   if (json) {
     io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     return 0;
   }
 
-  io.stdout.write(`External wiki results for "${result.query}" (${result.count})\n`);
-  for (const hit of result.hits) {
-    const citation = hit.citations[0];
-    const location = citation ? `${citation.path}:${citation.lineStart}-${citation.lineEnd}` : hit.path;
-    io.stdout.write(`${hit.rank}. [${hit.wikiId}] ${hit.title} (${location})\n`);
-    io.stdout.write(`   ${hit.snippet.replace(/\s+/g, " ").trim()}\n`);
-  }
   if (result.degradedWikiIds.length > 0) {
-    io.stderr.write(`external-wiki: degraded roots: ${result.degradedWikiIds.join(", ")}\n`);
+    io.stderr.write(`Warning: degraded roots: ${result.degradedWikiIds.join(", ")}\n`);
+  }
+  if (result.hits.length === 0) {
+    io.stdout.write("No results.\n");
+    return 0;
+  }
+  for (const hit of result.hits) {
+    io.stdout.write(`[${hit.wikiId}] ${hit.path} (score ${hit.score})\n${hit.snippet}\n\n`);
   }
   return 0;
 }

package/src/external-wiki-search.test.ts

@@ -257,7 +257,7 @@ test("external wiki search fails open to filesystem candidates when a dedicated
   }
 });
 
-test("external wiki CLI searches multi-word queries and renders cited JSON or text", async () => {
+test("external wiki CLI preserves text contracts and supports cited JSON", async () => {
   const root = await createWiki("cli", {
     "INDEX.md": "- [[wiki/agents|Agent Planning]] - planner fan-out with citations\n",
     "wiki/agents.md": "# Agent Planning\n\nPlanner fan-out uses cited retrieval evidence.\n",
@@ -286,7 +286,7 @@ test("external wiki CLI searches multi-word queries and renders cited JSON or te
       stderr: { write: () => undefined },
     });
     assert.equal(textCode, 0);
-    assert.match(textOutput.join(""), /\[cli\] Agent Planning \(wiki\/agents\.md:\d+-\d+\)/);
+    assert.match(textOutput.join(""), /\[cli\] wiki\/agents\.md \(score [\d.]+\)/);
 
     const invalidErrors: string[] = [];
     const invalidCode = await runExternalWikiCliCommand([root], ["search", "--limit", "0", "query"], {
@@ -295,6 +295,72 @@ test("external wiki CLI searches multi-word queries and renders cited JSON or te
     });
     assert.equal(invalidCode, 2);
     assert.match(invalidErrors.join(""), /--limit must be an integer from 1 to 20/);
+
+    const noQueryErrors: string[] = [];
+    const noQueryCode = await runExternalWikiCliCommand([root], ["search"], {
+      stdout: { write: () => undefined },
+      stderr: { write: (chunk) => noQueryErrors.push(chunk) },
+    });
+    assert.equal(noQueryCode, 1);
+    assert.equal(noQueryErrors.join(""), "external-wiki: provide a search query\n");
+
+    const disabledErrors: string[] = [];
+    const disabledCode = await runExternalWikiCliCommand([{ ...root, enabled: false }], ["search", "planner"], {
+      stdout: { write: () => undefined },
+      stderr: { write: (chunk) => disabledErrors.push(chunk) },
+    });
+    assert.equal(disabledCode, 1);
+    assert.equal(disabledErrors.join(""), "external-wiki: no enabled wiki roots configured\n");
+
+    const emptyOutput: string[] = [];
+    const emptyCode = await runExternalWikiCliCommand([root], ["search", "unmatched-token"], {
+      stdout: { write: (chunk) => emptyOutput.push(chunk) },
+      stderr: { write: () => undefined },
+    });
+    assert.equal(emptyCode, 0);
+    assert.equal(emptyOutput.join(""), "No results.\n");
+
+    const searchErrors: string[] = [];
+    const searchErrorCode = await runExternalWikiCliCommand([root], ["search", "planner", "--wiki-id", "missing"], {
+      stdout: { write: () => undefined },
+      stderr: { write: (chunk) => searchErrors.push(chunk) },
+    });
+    assert.equal(searchErrorCode, 1);
+    assert.equal(searchErrors.join(""), "external-wiki: unknown external wiki: missing\n");
+
+    const legacyOutput: string[] = [];
+    const legacyCode = await runExternalWikiCliCommand([root], ["planner", "fan-out"], {
+      stdout: { write: (chunk) => legacyOutput.push(chunk) },
+      stderr: { write: () => undefined },
+    });
+    assert.equal(legacyCode, 0);
+    assert.match(legacyOutput.join(""), /^\[cli\] wiki\/agents\.md \(score [\d.]+\)/);
+
+    const degradedErrors: string[] = [];
+    const degradedCode = await runExternalWikiCliCommand(
+      [root, { ...root, id: "broken", rootDir: path.join(root.rootDir, "missing") }],
+      ["search", "planner"],
+      {
+        stdout: { write: () => undefined },
+        stderr: { write: (chunk) => degradedErrors.push(chunk) },
+      }
+    );
+    assert.equal(degradedCode, 0);
+    assert.equal(degradedErrors.join(""), "Warning: degraded roots: broken\n");
+
+    const allDegradedOutput: string[] = [];
+    const allDegradedErrors: string[] = [];
+    const allDegradedCode = await runExternalWikiCliCommand(
+      [{ ...root, id: "broken", rootDir: path.join(root.rootDir, "missing") }],
+      ["search", "planner"],
+      {
+        stdout: { write: (chunk) => allDegradedOutput.push(chunk) },
+        stderr: { write: (chunk) => allDegradedErrors.push(chunk) },
+      }
+    );
+    assert.equal(allDegradedCode, 0);
+    assert.equal(allDegradedOutput.join(""), "No results.\n");
+    assert.equal(allDegradedErrors.join(""), "Warning: degraded roots: broken\n");
   } finally {
     await removeWikis([root]);
   }

package/src/external-wiki.ts

@@ -170,9 +170,18 @@ function normalizeCatalogPath(target: string, config: ExternalWikiRoot, base: Ca
   }
 
   const pagesDir = path.posix.normalize(config.pagesDir);
-  const baseDir = base === "index" ? path.posix.dirname(config.indexFile) : pagesDir;
-  const rootRelativeTarget = path.posix.normalize(path.posix.join(baseDir, withoutFragment));
-  const relative = path.posix.relative(pagesDir, rootRelativeTarget);
+  let relative: string;
+  if (base === "index") {
+    const baseDir = path.posix.dirname(config.indexFile);
+    const rootRelativeTarget = path.posix.normalize(path.posix.join(baseDir, withoutFragment));
+    relative = path.posix.relative(pagesDir, rootRelativeTarget);
+  } else {
+    const pagesPrefix = pagesDir === "." ? "" : `${pagesDir}/`;
+    const stripped = pagesPrefix.length > 0 && withoutFragment.startsWith(pagesPrefix)
+      ? withoutFragment.slice(pagesPrefix.length)
+      : withoutFragment;
+    relative = path.posix.normalize(stripped);
+  }
   if (
     relative === ".." ||
     relative.startsWith("../") ||
@@ -416,38 +425,3 @@ export async function readExternalWikiPage(
     bytes: page.bytes,
   };
 }
-
-export async function runExternalWikiCliCommand(
-  roots: readonly ExternalWikiRoot[],
-  rest: readonly string[],
-  io: { stdout: NodeJS.WritableStream; stderr: NodeJS.WritableStream },
-): Promise<number> {
-  const { searchExternalWikis } = await import("./external-wiki-search.js");
-  const query = rest.filter((a) => !a.startsWith("-")).join(" ").trim();
-  if (!query) {
-    io.stderr.write("external-wiki: provide a search query\n");
-    return 1;
-  }
-  const enabled = roots.filter((r) => r.enabled !== false);
-  if (enabled.length === 0) {
-    io.stderr.write("external-wiki: no enabled wiki roots configured\n");
-    return 1;
-  }
-  try {
-    const result = await searchExternalWikis(enabled, { query });
-    if (result.hits.length === 0) {
-      io.stdout.write("No results.\n");
-      return 0;
-    }
-    for (const hit of result.hits) {
-      io.stdout.write(`[${hit.wikiId}] ${hit.path} (score ${hit.score})\n${hit.snippet}\n\n`);
-    }
-    if (result.degradedWikiIds.length > 0) {
-      io.stderr.write(`Warning: degraded roots: ${result.degradedWikiIds.join(", ")}\n`);
-    }
-    return 0;
-  } catch (error) {
-    io.stderr.write(`external-wiki: ${error instanceof Error ? error.message : "search failed"}\n`);
-    return 1;
-  }
-}

package/src/index.ts

@@ -9,11 +9,6 @@
  * This package has ZERO OpenClaw imports — it can be consumed by
  * any host adapter (CLI, HTTP server, MCP server, etc.).
  *
- * Usage:
- *   import { Orchestrator, parseConfig } from "@remnic/core";
- *   const config = parseConfig({ memoryDir: "/tmp/mem" });
- *   const orch = new Orchestrator(config);
- *   await orch.initialize();
  */
 
 // ---------------------------------------------------------------------------
@@ -29,6 +24,7 @@ export { resolvePluginEntry, type PluginEntryResolverOptions } from "./plugin-en
 export { parseConfig, isOpenaiApiKeyDisabled, resolveEnvVars } from "./config.js";
 export { resolveRemnicConfigRecord } from "./config-record.js";
 export * from "./external-wiki.js";
+export * from "./external-wiki-cli.js";
 export {
   parseFlexibleIsoTimestamp,
   parseIsoOffsetTimestamp,

package/src/maintenance/first-start-migration.ts

@@ -278,7 +278,7 @@ export async function runFirstStartMigration(
         qmd,
         hotCollection: options.hotCollection ?? config.qmdCollection ?? "openclaw-engram",
         coldCollection: options.coldCollection ?? config.qmdColdCollection ?? "openclaw-engram-cold",
-    })
+      })
     : null;
   const coldCollection = options.coldCollection ?? config.qmdColdCollection ?? "openclaw-engram-cold";
 
@@ -287,17 +287,17 @@ export async function runFirstStartMigration(
       return abortedResult(candidateCount, demotedCount, failureCount);
     }
     try {
-      if (executor) {
-        await executor.migrateMemory({
-          memory,
-          fromTier: "hot",
-          toTier: "cold",
-          reason: "first-start-lifecycle-migration",
-        });
-      } else {
-        await storage.migrateMemoryToTier(memory, "cold");
+      const result = executor
+        ? await executor.migrateMemory({
+            memory,
+            fromTier: "hot",
+            toTier: "cold",
+            reason: "first-start-lifecycle-migration",
+          })
+        : await storage.migrateMemoryToTier(memory, "cold");
+      if (result.changed) {
+        demotedCount += 1;
       }
-      demotedCount += 1;
     } catch {
       const targetPath = storage.buildTierMemoryPath(memory, "cold");
       const [targetExists, sourceExists] = await Promise.all([

package/src/memory-snapshot.ts

@@ -0,0 +1,15 @@
+import type { MemoryFile } from "./types.js";
+
+function sortSnapshotObject(_key: string, candidate: unknown): unknown {
+  if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) return candidate;
+  return Object.keys(candidate)
+    .sort()
+    .reduce<Record<string, unknown>>((sorted, key) => {
+      sorted[key] = (candidate as Record<string, unknown>)[key];
+      return sorted;
+    }, {});
+}
+
+export function createMemorySnapshot(memory: MemoryFile): string {
+  return JSON.stringify([memory.frontmatter, memory.content], sortSnapshotObject);
+}

package/src/storage-contract/cache-coherence.test.ts

@@ -435,3 +435,102 @@ test("citation path lookup resolves collection-prefixed QMD paths", async () =>
     await rm(dir, { recursive: true, force: true });
   }
 });
+test("memory snapshots ignore object key order", async () => {
+  const { createMemorySnapshot } = await import("../memory-snapshot.js");
+  type SnapshotInput = Parameters<typeof createMemorySnapshot>[0];
+  const first = {
+    content: "payload",
+    frontmatter: { z: 1, nested: { y: 2, x: 3 } },
+  } as unknown as SnapshotInput;
+  const second = {
+    frontmatter: { nested: { x: 3, y: 2 }, z: 1 },
+    content: "payload",
+  } as unknown as SnapshotInput;
+  assert.equal(createMemorySnapshot(first), createMemorySnapshot(second));
+});
+
+test("tier move: caller-only mutation is not persisted by moveMemoryToPath", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-caller-mut-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+
+    const { id } = await storage.writeMemory("fact", "original disk content");
+    const memories = await storage.readAllMemories();
+    const memory = memories.find((m) => m.frontmatter.id === id);
+    assert.ok(memory, "memory must exist");
+
+    memory.content = "caller mutated unpersisted content";
+
+    const targetPath = storage.buildTierMemoryPath(memory, "cold");
+    await storage.moveMemoryToPath(memory, targetPath);
+
+    const onDisk = await readFile(targetPath, "utf8");
+    assert.ok(onDisk.includes("original disk content"), "Moved file on disk must retain original content");
+    assert.ok(!onDisk.includes("caller mutated unpersisted content"), "Moved file on disk must not carry caller's unpersisted content mutation");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("tier move: stale on-disk mutation fails snapshot check during move", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-stale-disk-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+
+    const { id } = await storage.writeMemory("fact", "unmodified content");
+    const memories = await storage.readAllMemories();
+    const memory = memories.find((m) => m.frontmatter.id === id);
+    assert.ok(memory, "memory must exist");
+
+    const diskContent = await readFile(memory.path, "utf8");
+    await writeFile(memory.path, diskContent.replace("unmodified content", "external edit on disk"));
+
+    const targetPath = storage.buildTierMemoryPath(memory, "cold");
+    await assert.rejects(
+      async () => {
+        await storage.moveMemoryToPath(memory, targetPath);
+      },
+      (err: Error) => {
+        return err.message.includes("changed before its tier move");
+      }
+    );
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("tier move: cold-to-hot move invalidates cold cache and cannot remain in readAllColdMemories", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-cold-to-hot-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+
+    const { id } = await storage.writeMemory("fact", "demoted to cold then promoted");
+    const memories = await storage.readAllMemories();
+    const memory = memories.find((m) => m.frontmatter.id === id);
+    assert.ok(memory, "memory must exist");
+
+    const { targetPath: coldPath } = await storage.migrateMemoryToTier(memory, "cold");
+
+    const coldMemories = await storage.readAllColdMemories();
+    const coldMem = coldMemories.find((m) => m.frontmatter.id === id);
+    assert.ok(coldMem, "memory must be present in cold tier read");
+
+    const { changed } = await storage.migrateMemoryToTier(coldMem, "hot");
+    assert.equal(changed, true, "migration from cold to hot must succeed");
+
+    const coldMemoriesAfter = await storage.readAllColdMemories();
+    const foundInCold = coldMemoriesAfter.some((m) => m.frontmatter.id === id);
+    assert.equal(foundInCold, false, "promoted memory must not remain in readAllColdMemories cache");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});