@remnic/core 9.3.704 → 9.3.705

package/src/access-operations.ts

@@ -549,6 +549,10 @@ export const codegraphIngestTracesOperation = defineOperation<
   },
 });
 
+// Batch-migrated operations (issue #1525): registers all remaining
+// handlers through the boundary as a side effect of importing this module.
+import "./access-operations-batch.js";
+
 export const REGISTERED_OPERATIONS = [
   memoryGetOperation.spec.name,
   memorySearchOperation.spec.name,

package/src/access-surface-catalog.test.ts

@@ -44,7 +44,7 @@ import {
 // catalog-completeness correction: adding routes that were always live but
 // omitted from the catalog (review-caught). Such a bump MUST be accompanied
 // by the newly-cataloged entries; the higher count is the honest baseline.
-const UNMIGRATED_HANDLER_BASELINE = 134;
+const UNMIGRATED_HANDLER_BASELINE = 80;
 
 // Keep the import live — `getOperation` is the call surfaces use at dispatch
 // time; referencing it here pins the registry's lookup contract.
@@ -187,6 +187,7 @@ function extractHttpRouteDispatchMap(): Map<string, Set<string>> {
   const lines = source.split("\n");
   const routeOps = new Map<string, Set<string>>();
   let currentKey: string | null = null;
+  let lastSeenPathname: string | null = null;
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i]!;
@@ -217,6 +218,7 @@ function extractHttpRouteDispatchMap(): Map<string, Set<string>> {
     }
 
     if (pathname) {
+      lastSeenPathname = pathname;
       // Determine the HTTP method: same line first, then backward for
       // exact-match routes, forward for dynamic routes. Check both positive
       // (===) and negated (!==) method patterns — `req.method !== "GET"` as
@@ -253,6 +255,20 @@ function extractHttpRouteDispatchMap(): Map<string, Set<string>> {
       continue;
     }
 
+    // Detect method changes within a shared route block (e.g. a single
+    // regex match with GET/PUT/DELETE branches). When a new method check
+    // appears after a route pattern was already detected, update currentKey
+    // to the new method + the same pathname so per-method getOperation
+    // calls are tracked against the right route key.
+    const methodChange = line.match(/req\.method\s*===\s*"(\w+)"/);
+    if (methodChange && lastSeenPathname) {
+      const newKey = methodChange[1]! + " " + lastSeenPathname;
+      if (!routeOps.has(newKey)) {
+        routeOps.set(newKey, new Set<string>());
+      }
+      currentKey = newKey;
+    }
+
     // Collect getOperation calls within the current route block.
     if (currentKey) {
       const opMatch = line.match(/getOperation\("(\w+)"\)/);

package/src/access-surface-catalog.ts

@@ -160,65 +160,68 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
 // (health, adapters, the /mcp delegate, admin console, SSE-only endpoints)
 // carry no user request envelope and are intentionally excluded.
 export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
-  { method: "POST", pathname: "/engram/v1/recall", operation: null },
-  { method: "POST", pathname: "/engram/v1/coding-context", operation: null },
-  { method: "POST", pathname: "/engram/v1/capsules/export", operation: null },
-  { method: "POST", pathname: "/engram/v1/capsules/import", operation: null },
-  { method: "GET", pathname: "/engram/v1/offline-sync/snapshot", operation: null },
-  { method: "GET", pathname: "/engram/v1/offline-sync/snapshot-stream", operation: null },
-  { method: "POST", pathname: "/engram/v1/offline-sync/snapshot", operation: null },
-  { method: "POST", pathname: "/engram/v1/offline-sync/files", operation: null },
-  { method: "POST", pathname: "/engram/v1/offline-sync/file-content", operation: null },
-  { method: "POST", pathname: "/engram/v1/offline-sync/apply-file-content", operation: null },
-  { method: "POST", pathname: "/engram/v1/offline-sync/apply", operation: null },
-  { method: "POST", pathname: "/engram/v1/recall/explain", operation: null },
-  { method: "POST", pathname: "/engram/v1/action-confidence", operation: null },
-  { method: "GET", pathname: "/engram/v1/recall/tier-explain", operation: null },
-  { method: "GET", pathname: "/engram/v1/recall/xray", operation: null },
-  { method: "GET", pathname: "/engram/v1/wearables/status", operation: null },
-  { method: "POST", pathname: "/engram/v1/wearables/sync", operation: null },
-  { method: "GET", pathname: "/engram/v1/wearables/transcript", operation: null },
-  { method: "GET", pathname: "/engram/v1/wearables/transcripts/search", operation: null },
-  { method: "GET", pathname: "/engram/v1/wearables/memories", operation: null },
-  { method: "POST", pathname: "/engram/v1/observe", operation: null },
-  { method: "POST", pathname: "/engram/v1/lcm/search", operation: null },
-  { method: "POST", pathname: "/engram/v1/lcm/compaction/flush", operation: null },
-  { method: "POST", pathname: "/engram/v1/lcm/compaction/record", operation: null },
-  { method: "GET", pathname: "/engram/v1/lcm/status", operation: null },
+  { method: "POST", pathname: "/engram/v1/recall", operation: "recall" },
+  { method: "POST", pathname: "/engram/v1/coding-context", operation: "set_coding_context" },
+  { method: "POST", pathname: "/engram/v1/capsules/export", operation: "capsule_export" },
+  { method: "POST", pathname: "/engram/v1/capsules/import", operation: "capsule_import" },
+  { method: "GET", pathname: "/engram/v1/offline-sync/snapshot", operation: "offline_sync_snapshot" },
+    { method: "POST", pathname: "/engram/v1/offline-sync/snapshot", operation: "offline_sync_snapshot" },
+  { method: "POST", pathname: "/engram/v1/offline-sync/files", operation: "offline_sync_files" },
+  { method: "POST", pathname: "/engram/v1/offline-sync/file-content", operation: "offline_sync_file_content" },
+  { method: "POST", pathname: "/engram/v1/offline-sync/apply-file-content", operation: "offline_sync_apply_file_content" },
+  { method: "POST", pathname: "/engram/v1/offline-sync/apply", operation: "offline_sync_apply" },
+  { method: "POST", pathname: "/engram/v1/recall/explain", operation: "recall_explain" },
+  { method: "POST", pathname: "/engram/v1/action-confidence", operation: "action_confidence" },
+  { method: "GET", pathname: "/engram/v1/recall/tier-explain", operation: "recall_tier_explain" },
+  { method: "GET", pathname: "/engram/v1/recall/xray", operation: "recall_xray" },
+  { method: "GET", pathname: "/engram/v1/wearables/status", operation: "wearables_status" },
+  { method: "POST", pathname: "/engram/v1/wearables/sync", operation: "wearables_sync" },
+  { method: "GET", pathname: "/engram/v1/wearables/transcript", operation: "transcript_day" },
+  { method: "GET", pathname: "/engram/v1/wearables/transcripts/search", operation: "transcript_search" },
+  { method: "GET", pathname: "/engram/v1/wearables/memories", operation: "transcript_memories" },
+  { method: "POST", pathname: "/engram/v1/observe", operation: "observe" },
+  { method: "POST", pathname: "/engram/v1/lcm/search", operation: "lcm_search" },
+  { method: "POST", pathname: "/engram/v1/lcm/compaction/flush", operation: "lcm_compaction_flush" },
+  { method: "POST", pathname: "/engram/v1/lcm/compaction/record", operation: "lcm_compaction_record" },
+  { method: "GET", pathname: "/engram/v1/lcm/status", operation: "lcm_status" },
   { method: "POST", pathname: "/engram/v1/memories", operation: "memory_store" },
   { method: "POST", pathname: "/engram/v1/coding/decisions", operation: "coding_decision" },
   { method: "POST", pathname: "/engram/v1/coding/architecture", operation: "coding_architecture" },
   { method: "POST", pathname: "/engram/v1/coding/delta", operation: "coding_delta" },
-  { method: "POST", pathname: "/engram/v1/suggestions", operation: null },
-  { method: "GET", pathname: "/engram/v1/memories", operation: null },
+  { method: "POST", pathname: "/engram/v1/suggestions", operation: "suggestion_submit" },
+  { method: "GET", pathname: "/engram/v1/memories", operation: "memory_list" },
   { method: "GET", pathname: "/engram/v1/memories/:id", operation: "memory_get" },
-  { method: "GET", pathname: "/engram/v1/memories/:id/timeline", operation: null },
-  { method: "GET", pathname: "/engram/v1/entities", operation: null },
-  { method: "GET", pathname: "/engram/v1/entities/:id", operation: null },
-  { method: "GET", pathname: "/engram/v1/review-queue", operation: null },
-  { method: "GET", pathname: "/engram/v1/maintenance", operation: null },
-  { method: "GET", pathname: "/engram/v1/quality", operation: null },
-  { method: "GET", pathname: "/engram/v1/trust-zones/status", operation: null },
-  { method: "GET", pathname: "/engram/v1/procedural/stats", operation: null },
-  { method: "GET", pathname: "/engram/v1/trust-zones/records", operation: null },
-  { method: "POST", pathname: "/engram/v1/review-disposition", operation: null },
-  { method: "POST", pathname: "/engram/v1/trust-zones/promote", operation: null },
-  { method: "POST", pathname: "/engram/v1/trust-zones/demo-seed", operation: null },
-  { method: "POST", pathname: "/v1/citations/observed", operation: null },
-  { method: "GET", pathname: "/engram/v1/review/contradictions", operation: null },
-  { method: "GET", pathname: "/engram/v1/review/contradictions/:id", operation: null },
-  { method: "POST", pathname: "/engram/v1/review/resolve", operation: null },
-  { method: "GET", pathname: "/engram/v1/graph/snapshot", operation: null },
-  { method: "POST", pathname: "/engram/v1/contradiction-scan", operation: null },
-  { method: "GET", pathname: "/engram/v1/graph/events", operation: null },
-  { method: "GET", pathname: "/engram/v1/console/state", operation: null },
-  { method: "GET", pathname: "/engram/v1/peers", operation: null },
-  { method: "GET", pathname: "/engram/v1/peers/:id/profile", operation: null },
-  { method: "GET", pathname: "/engram/v1/peers/:id", operation: null },
-  { method: "PUT", pathname: "/engram/v1/peers/:id", operation: null },
-  { method: "DELETE", pathname: "/engram/v1/peers/:id", operation: null },
-  { method: "GET", pathname: "/engram/v1/dreams/status", operation: null },
-  { method: "POST", pathname: "/engram/v1/dreams/run", operation: null },
+  { method: "GET", pathname: "/engram/v1/memories/:id/timeline", operation: "memory_timeline" },
+  { method: "GET", pathname: "/engram/v1/entities", operation: "entity_list" },
+  { method: "GET", pathname: "/engram/v1/entities/:id", operation: "entity_get" },
+  { method: "GET", pathname: "/engram/v1/review-queue", operation: "review_queue_list" },
+  { method: "GET", pathname: "/engram/v1/maintenance", operation: "maintenance_status" },
+  { method: "GET", pathname: "/engram/v1/quality", operation: "quality_status" },
+  { method: "GET", pathname: "/engram/v1/trust-zones/status", operation: "trust_zones_status" },
+  { method: "GET", pathname: "/engram/v1/procedural/stats", operation: "procedural_stats" },
+  { method: "GET", pathname: "/engram/v1/trust-zones/records", operation: "trust_zones_records" },
+  { method: "POST", pathname: "/engram/v1/review-disposition", operation: "review_disposition" },
+  { method: "POST", pathname: "/engram/v1/trust-zones/promote", operation: "trust_zones_promote" },
+  { method: "POST", pathname: "/engram/v1/trust-zones/demo-seed", operation: "trust_zones_demo_seed" },
+  { method: "POST", pathname: "/v1/citations/observed", operation: "citations_observed" },
+  { method: "GET", pathname: "/engram/v1/review/contradictions", operation: "review_list" },
+  { method: "GET", pathname: "/engram/v1/review/contradictions/:id", operation: "contradiction_detail" },
+  { method: "POST", pathname: "/engram/v1/review/resolve", operation: "review_resolve" },
+  { method: "GET", pathname: "/engram/v1/graph/snapshot", operation: "graph_snapshot" },
+  { method: "POST", pathname: "/engram/v1/contradiction-scan", operation: "contradiction_scan_run" },
+    { method: "GET", pathname: "/engram/v1/console/state", operation: "console_state" },
+  { method: "GET", pathname: "/engram/v1/peers", operation: "peer_list" },
+  { method: "GET", pathname: "/engram/v1/peers/:id/profile", operation: "peer_profile_get" },
+  { method: "GET", pathname: "/engram/v1/peers/:id", operation: "peer_get" },
+  { method: "PUT", pathname: "/engram/v1/peers/:id", operation: "peer_set" },
+  { method: "DELETE", pathname: "/engram/v1/peers/:id", operation: "peer_delete" },
+  { method: "GET", pathname: "/engram/v1/dreams/status", operation: "dreams_status" },
+  { method: "POST", pathname: "/engram/v1/dreams/run", operation: "dreams_run" },
+  // SSE-only endpoints: carried in the catalog for completeness tracking.
+  // The operation registration makes them visible to the boundary; the
+  // streaming lifecycle is owned by the HTTP transport (handleGraphEventsSSE).
+  { method: "GET", pathname: "/engram/v1/offline-sync/snapshot-stream", operation: "offline_sync_snapshot_stream" },
+  { method: "GET", pathname: "/engram/v1/graph/events", operation: "graph_events" },
 ];
 
 /**

package/src/storage-contract/atomicity.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Issue #1533 — Phase A contract test: atomic write semantics.
+ *
+ * Rule 54 (CLAUDE.md): replace operations MUST write temp-then-rename, NEVER
+ * delete-before-write. This test pins that invariant by making rename fail
+ * (read-only target directory) and asserting the original file survives the
+ * failed overwrite.
+ *
+ * The atomic write primitive lives in secure-fs (`writeMaybeEncryptedFile`)
+ * and is consumed by StorageManager via `writeStorageSecureFile`. We test the
+ * primitive directly here because it is the single atomicity seam every write
+ * entry point depends on.
+ */
+
+import assert from "node:assert/strict";
+import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { writeMaybeEncryptedFile, readMaybeEncryptedFile } from "../secure-store/secure-fs.js";
+
+test("atomicity: writeMaybeEncryptedFile writes temp-then-rename (no temp files left behind on success)", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-atomic-"));
+  try {
+    const target = path.join(dir, "target.md");
+    await writeMaybeEncryptedFile(target, "first content", null, {}, dir);
+
+    // No temp files left behind
+    const { readdir } = await import("node:fs/promises");
+    const entries = await readdir(dir);
+    assert.deepEqual(entries.sort(), ["target.md"]);
+
+    // Overwrite — still only the target, no leftover temp
+    await writeMaybeEncryptedFile(target, "second content", null, {}, dir);
+    const entries2 = await readdir(dir);
+    assert.deepEqual(entries2.sort(), ["target.md"]);
+
+    const read = await readMaybeEncryptedFile(target, null, dir);
+    assert.equal(read, "second content");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("atomicity: a failed rename leaves the original file intact (never delete-before-write)", async (t) => {
+  // Skip on root — chmod restrictions don't apply.
+  if (process.getuid && process.getuid() === 0) {
+    t.skip("chmod-based test is unreliable when running as root");
+    return;
+  }
+
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-atomic-fail-"));
+  try {
+    const target = path.join(dir, "survivor.md");
+    await writeMaybeEncryptedFile(target, "original", null, {}, dir);
+
+    // Make the directory read-only so the rename into place fails.
+    await chmod(dir, 0o500);
+    try {
+      await assert.rejects(
+        () => writeMaybeEncryptedFile(target, "would-be-replacement", null, {}, dir),
+        // rename (or temp write) fails — the exact error varies by platform
+      );
+
+      // THE CONTRACT: the original file must still be readable with its
+      // original content. Delete-before-write would have destroyed it before
+      // the failed rename.
+      const survived = await readMaybeEncryptedFile(target, null, dir);
+      assert.equal(survived, "original", "original file must survive a failed atomic replace");
+    } finally {
+      // Restore perms so cleanup works.
+      await chmod(dir, 0o700);
+    }
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("atomicity: StorageManager.updateMemory preserves the original on overwrite success", async (t) => {
+  const { StorageManager } = await import("../storage.js");
+  const { makeStorage } = await import("./harness.js");
+  const { storage, cleanup } = await makeStorage();
+  try {
+    const id = await storage.writeMemory("fact", "version one");
+    const before = await storage.getMemoryById(id);
+    assert.ok(before);
+    assert.equal(before!.content, "version one");
+
+    const updated = await storage.updateMemory(id, "version two");
+    assert.equal(updated, true);
+
+    const after = await storage.getMemoryById(id);
+    assert.ok(after);
+    assert.equal(after!.content, "version two");
+    // The id is stable across the update (same file path, not a new memory)
+    assert.equal(after!.frontmatter.id, id);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("atomicity: mkdir is implicit — writeMaybeEncryptedFile creates parent dirs", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-atomic-mkdir-"));
+  try {
+    const target = path.join(dir, "nested", "deep", "file.md");
+    await writeMaybeEncryptedFile(target, "content", null, {}, dir);
+    const read = await readMaybeEncryptedFile(target, null, dir);
+    assert.equal(read, "content");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,100 @@
+/**
+ * Issue #1533 — Phase A contract test: cache coherence across instances.
+ *
+ * Rule 37 (memory-cache): write via instance A, read via a FRESH instance B
+ * over the same dir → B sees the write. The module-level caches
+ * (readAllMemories in-flight, version sentinels) are keyed by baseDir and
+ * shared/static — this test pins that a write invalidates correctly so a
+ * second instance never serves stale data.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { StorageManager } from "../storage.js";
+import { resetStaticCaches } from "./harness.js";
+
+test("cache-coherence: write via instance A, read via fresh instance B → B sees the write", async () => {
+  const { mkdtemp, rm } = await import("node:fs/promises");
+  const os = await import("node:os");
+  const path = await import("node:path");
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-cache-coherence-"));
+  try {
+    resetStaticCaches();
+    const smA = new StorageManager(dir);
+    await smA.ensureDirectories();
+
+    const id = await smA.writeMemory("fact", "written by A");
+
+    // Fresh instance over the same dir
+    const smB = new StorageManager(dir);
+    await smB.ensureDirectories();
+    const found = await smB.getMemoryById(id);
+    assert.ok(found, "instance B must see the memory written by instance A");
+    assert.equal(found!.content, "written by A");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("cache-coherence: delete via instance A is reflected in fresh instance B", async () => {
+  const { mkdtemp, rm } = await import("node:fs/promises");
+  const os = await import("node:os");
+  const path = await import("node:path");
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-cache-del-"));
+  try {
+    resetStaticCaches();
+    const smA = new StorageManager(dir);
+    await smA.ensureDirectories();
+    const id = await smA.writeMemory("fact", "to be deleted");
+
+    // Confirm B sees it
+    const smB = new StorageManager(dir);
+    await smB.ensureDirectories();
+    assert.ok(await smB.getMemoryById(id));
+
+    // A deletes
+    await smA.invalidateMemory(id);
+
+    // Fresh instance C must NOT see it
+    const smC = new StorageManager(dir);
+    await smC.ensureDirectories();
+    const found = await smC.getMemoryById(id);
+    assert.equal(found, null, "fresh instance must not see a deleted memory");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("cache-coherence: readAllMemories reflects writes across instances after invalidation", async () => {
+  const { mkdtemp, rm } = await import("node:fs/promises");
+  const os = await import("node:os");
+  const path = await import("node:path");
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-cache-list-"));
+  try {
+    resetStaticCaches();
+    const smA = new StorageManager(dir);
+    await smA.ensureDirectories();
+    await smA.writeMemory("fact", "first");
+    await smA.writeMemory("decision", "second");
+
+    const smB = new StorageManager(dir);
+    await smB.ensureDirectories();
+    const all = await smB.readAllMemories();
+    assert.ok(all.length >= 2, "fresh instance must list all written memories");
+
+    // Write more via A
+    await smA.writeMemory("principle", "third");
+
+    const smC = new StorageManager(dir);
+    await smC.ensureDirectories();
+    const allAfter = await smC.readAllMemories();
+    assert.ok(allAfter.length >= 3, "fresh instance must see the additional write");
+    assert.ok(allAfter.some((m) => m.content === "third"));
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/storage-contract/content-hash.test.ts

@@ -0,0 +1,102 @@
+/**
+ * Issue #1533 — Phase A contract test: content hash identity.
+ *
+ * Rule 23: the write-side and dedup-side MUST hash the same `rawContent`,
+ * never the timestamped/cited form. `writeMemory` persists a `contentHash` on
+ * the frontmatter for facts; `hasFactContentHash` queries the dedup index.
+ * This test pins that the two sides agree so subsequent extractions of the
+ * same logical fact are deduped correctly even when citation timestamps differ.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { ContentHashIndex } from "../storage.js";
+import { makeStorage } from "./harness.js";
+
+test("content-hash: ContentHashIndex.computeHash is deterministic for the same input", () => {
+  const a = ContentHashIndex.computeHash("the sky is blue");
+  const b = ContentHashIndex.computeHash("the sky is blue");
+  assert.equal(a, b);
+  assert.notEqual(
+    ContentHashIndex.computeHash("the sky is blue"),
+    ContentHashIndex.computeHash("the sky is green"),
+  );
+});
+
+test("content-hash: writeMemory for fact registers the hash so hasFactContentHash returns true", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    const rawFact = "PostgreSQL is our primary database";
+    await storage.writeMemory("fact", rawFact);
+
+    const has = await storage.hasFactContentHash(rawFact);
+    assert.equal(has, true, "hasFactContentHash must return true for a just-written fact");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("content-hash: contentHashSource overrides the persisted body for dedup (rule 23)", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    const rawFact = "We migrated to MySQL in March";
+    // Persist a citation-annotated body, but index the RAW fact text
+    await storage.writeMemory("fact", `${rawFact} [cited 2026-01-01]`, {
+      contentHashSource: rawFact,
+    });
+
+    // Querying with the RAW fact (not the cited form) must hit
+    assert.equal(
+      await storage.hasFactContentHash(rawFact),
+      true,
+      "hasFactContentHash must match on the raw fact, not the cited body",
+    );
+    // The cited form should NOT be separately indexed (it has the citation suffix)
+    assert.equal(
+      await storage.hasFactContentHash(`${rawFact} [cited 2026-01-01]`),
+      false,
+      "the cited/timestamped form must not be the indexed hash",
+    );
+  } finally {
+    await cleanup();
+  }
+});
+
+test("content-hash: non-fact categories do not register a content hash", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    await storage.writeMemory("decision", "we chose option B");
+    assert.equal(
+      await storage.hasFactContentHash("we chose option B"),
+      false,
+      "non-fact categories must not enter the fact dedup index",
+    );
+  } finally {
+    await cleanup();
+  }
+});
+
+test("content-hash: normalizeContent produces stable text for equivalent inputs", () => {
+  const a = ContentHashIndex.normalizeContent("  Hello   World  ");
+  const b = ContentHashIndex.normalizeContent("Hello World");
+  assert.equal(a, b, "normalizeContent must collapse whitespace consistently");
+});
+
+test("content-hash: the frontmatter contentHash matches computeHash of the raw content", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    const rawFact = "deterministic hash check";
+    const id = await storage.writeMemory("fact", rawFact);
+    const memory = await storage.getMemoryById(id);
+    assert.ok(memory);
+    assert.ok(memory!.frontmatter.contentHash, "frontmatter must carry a contentHash for facts");
+    assert.equal(
+      memory!.frontmatter.contentHash,
+      ContentHashIndex.computeHash(rawFact),
+      "frontmatter contentHash must equal computeHash of the raw content",
+    );
+  } finally {
+    await cleanup();
+  }
+});

package/src/storage-contract/failure-semantics.test.ts

@@ -0,0 +1,108 @@
+/**
+ * Issue #1533 — Phase A contract test: failure semantics.
+ *
+ * Rule 34: reads distinguish empty-dir from unreadable-dir — `{ok:false}` vs
+ * `[]`. Where the current surface already does this, we pin it; where it
+ * doesn't, we record the gap (for the silent-failures issue) rather than
+ * change behavior here.
+ *
+ * Also pins containment: a FILE where a directory is expected is skipped via
+ * lstat().isDirectory(), not existsSync() (rule 24).
+ */
+
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { StorageManager } from "../storage.js";
+import { makeStorage } from "./harness.js";
+
+test("failure-semantics: readAllMemories on a fresh (empty) dir returns [] not null", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    const result = await storage.readAllMemories();
+    assert.ok(Array.isArray(result), "readAllMemories must return an array");
+    assert.equal(result.length, 0, "empty store must return an empty array");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("failure-semantics: getMemoryById on empty store returns null (not throw)", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    const result = await storage.getMemoryById("anything");
+    assert.equal(result, null);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("failure-semantics: readMemoryByPath on a non-existent file returns null (not throw)", async () => {
+  const { storage, baseDir, cleanup } = await makeStorage();
+  try {
+    const result = await storage.readMemoryByPath(path.join(baseDir, "facts", "2026-01-01", "nope.md"));
+    assert.equal(result, null);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("failure-semantics: readMemoryByPath on a malformed markdown file returns null", async () => {
+  const { storage, baseDir, cleanup } = await makeStorage();
+  try {
+    const dir = path.join(baseDir, "facts", "2026-01-01");
+    await mkdir(dir, { recursive: true });
+    const filePath = path.join(dir, "garbage.md");
+    await writeFile(filePath, "this has no frontmatter at all\njust random text", "utf-8");
+
+    const result = await storage.readMemoryByPath(filePath);
+    assert.equal(result, null, "malformed file (no frontmatter, not entity) must return null");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("failure-semantics: a FILE where a category directory is expected does not crash readAllMemories", async () => {
+  // Create a FILE named "facts" (not a directory) at the base dir, then scan.
+  // collectActiveMemoryPaths uses lstat().isDirectory() (not existsSync) so a
+  // file-as-directory entry is skipped without crashing (rule 24 containment).
+  // We do NOT call ensureDirectories — it would try to mkdir facts/<today> and
+  // fail on the file. The scan path must be robust independently of dir creation.
+  const baseDir = await mkdtemp(path.join(os.tmpdir(), "remnic-fail-file-as-dir-"));
+  try {
+    StorageManager.clearAllStaticCaches();
+    await writeFile(path.join(baseDir, "facts"), "I am a file not a directory", "utf-8");
+    const storage = new StorageManager(baseDir);
+
+    const result = await storage.readAllMemories();
+    assert.ok(Array.isArray(result));
+    assert.equal(result.length, 0, "a file-as-directory must not produce spurious memories");
+  } finally {
+    StorageManager.clearAllStaticCaches();
+    await rm(baseDir, { recursive: true, force: true });
+  }
+});
+
+test("failure-semantics: invalidateMemory on a missing memory returns false (not throw)", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    const result = await storage.invalidateMemory("totally-missing-id-99999");
+    assert.equal(result, false);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("failure-semantics: ensureDirectories is idempotent (safe to call multiple times)", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    await storage.ensureDirectories();
+    await storage.ensureDirectories();
+    await storage.ensureDirectories();
+  } finally {
+    await cleanup();
+  }
+});