@remnic/core 9.3.704 → 9.3.706

package/src/orchestrator.ts

@@ -121,6 +121,7 @@ import {
   shouldFilterSupersededFromRecall,
 } from "./temporal-supersession.js";
 import { isValidAsOf, isValidityExpiredNow } from "./temporal-validity.js";
+import { resolveFactEventTime } from "./event-time.js";
 import { RelevanceStore } from "./relevance.js";
 import { NegativeExampleStore } from "./negative.js";
 import {
@@ -12150,10 +12151,16 @@ export class Orchestrator {
         : typeof sessionKey === "string" && sessionKey.length > 0
           ? sessionKey
           : "default";
+    const captureTimestamp = new Date().toISOString();
     const turn: BufferTurn = {
       role,
       content,
-      timestamp: new Date().toISOString(),
+      timestamp: captureTimestamp,
+      // #1578: anchor live-capture turns to wall-clock when bi-temporal is on;
+      // replay/import turns carry sourceValidAt explicitly (codex P1).
+      ...(this.config.temporalBiTemporal
+        ? { sourceValidAt: captureTimestamp }
+        : {}),
       sessionKey,
       logicalSessionKey: options.logicalSessionKey ?? bufferKey,
       providerThreadId: options.providerThreadId ?? null,
@@ -13922,6 +13929,11 @@ export class Orchestrator {
       intentEntityTypes?: string[];
       memoryKind?: MemoryFrontmatter["memoryKind"];
       validAt?: string;
+      // #1578 — bi-temporal bounds + ingestion provenance forwarded to profile-
+      // target copies (same defect class as shared promotion; cursor bugbot).
+      invalidAt?: string;
+      observedAt?: string;
+      eventTimeSource?: "extracted" | "assumed";
       source: string;
       sources?: ProvenanceSource[];
       provenance?: "verified" | "unverified" | "none";
@@ -13980,6 +13992,10 @@ export class Orchestrator {
               intentEntityTypes: options.intentEntityTypes,
               memoryKind: options.memoryKind,
               validAt: options.validAt,
+              // #1578 — forward bi-temporal bounds + ingestion provenance.
+              ...(options.invalidAt ? { invalidAt: options.invalidAt } : {}),
+              ...(options.observedAt ? { observedAt: options.observedAt } : {}),
+              ...(options.eventTimeSource ? { eventTimeSource: options.eventTimeSource } : {}),
               contentHashSource: options.category === "fact" ? dedupContent : rawContent,
               ...(options.sources && options.sources.length > 0 ? { sources: options.sources } : {}),
               ...(options.provenance ? { provenance: options.provenance } : {}),
@@ -13999,7 +14015,7 @@ export class Orchestrator {
                 entityRef: options.entityRef,
                 structuredAttributes: options.structuredAttributes,
                 createdAt: supersessionOrderingAt(options.validAt),
-                enabled: true,
+                enabled: !(options.eventTimeSource === "extracted" && !options.validAt),
               });
             } catch (profileSupersessionErr) {
               log.warn(
@@ -14042,6 +14058,12 @@ export class Orchestrator {
       intentEntityTypes?: string[];
       memoryKind?: MemoryFrontmatter["memoryKind"];
       validAt?: string;
+      // #1578 — bi-temporal bounds + ingestion provenance forwarded to the
+      // shared-namespace copy so shared recall honours the same invalid_at
+      // window as the source fact (cursor bugbot).
+      invalidAt?: string;
+      observedAt?: string;
+      eventTimeSource?: "extracted" | "assumed";
       source: string;
       /** Claim-level provenance spans (issue #1575 PR 2). */
       sources?: ProvenanceSource[];
@@ -14196,7 +14218,7 @@ export class Orchestrator {
                   entityRef: options.entityRef,
                   structuredAttributes: options.structuredAttributes,
                   createdAt: supersessionOrderingAt(options.validAt),
-                  enabled: true,
+                  enabled: !(options.eventTimeSource === "extracted" && !options.validAt),
                   useCallerTimestamp: true,
                 });
                 // Catalog touch (issue #1499 — codex P2 NElSf): this dedup branch
@@ -14271,6 +14293,10 @@ export class Orchestrator {
             intentEntityTypes: options.intentEntityTypes,
             memoryKind: options.memoryKind,
             validAt: options.validAt,
+            // #1578 — forward bi-temporal bounds + ingestion provenance.
+            ...(options.invalidAt ? { invalidAt: options.invalidAt } : {}),
+            ...(options.observedAt ? { observedAt: options.observedAt } : {}),
+            ...(options.eventTimeSource ? { eventTimeSource: options.eventTimeSource } : {}),
             contentHashSource: options.category === "fact" ? dedupContent : rawContent,
             // Claim-level provenance spans (issue #1575 PR 2).
             ...(options.sources && options.sources.length > 0 ? { sources: options.sources } : {}),
@@ -14296,7 +14322,7 @@ export class Orchestrator {
               entityRef: options.entityRef,
               structuredAttributes: options.structuredAttributes,
               createdAt: supersessionOrderingAt(options.validAt),
-              enabled: true,
+              enabled: !(options.eventTimeSource === "extracted" && !options.validAt),
             });
           } catch (sharedSupersessionErr) {
             log.warn(
@@ -14677,7 +14703,7 @@ export class Orchestrator {
         typeof (fact as any).confidence === "number"
           ? (fact as any).confidence
           : 0.7;
-
+      const biTemporal = this.config.temporalBiTemporal && sourceContext?.validAt ? resolveFactEventTime(fact.eventTime, sourceContext.validAt) : undefined;
       // Content-hash dedup check (v6.0)
       //
       // Canonicalize pre-tagged facts before hashing (Codex P2 — issue #369).
@@ -15159,7 +15185,6 @@ export class Orchestrator {
           // back, leaving a dangling deindex with no replacement reference.
           // Child chunks intentionally do NOT carry supersedes; only the
           // parent represents the logical memory unit.
-          //
           // Canonicalize contentHashSource before writing (Thread 3 — Codex P2,
           // issue #369). If fact.content already carries an inline citation
           // (e.g. re-processed or relayed fact), strip it so contentHashSource
@@ -15187,7 +15212,8 @@ export class Orchestrator {
               intentEntityTypes: inferredIntent?.entityTypes,
               memoryKind,
               structuredAttributes: fact.structuredAttributes,
-              validAt: sourceContext?.validAt,
+              validAt: biTemporal ? biTemporal.validFrom : sourceContext?.validAt,
+              ...(biTemporal ? { observedAt: biTemporal.observedAt, eventTimeSource: biTemporal.eventTimeSource, ...(biTemporal.validUntil ? { invalidAt: biTemporal.validUntil } : {}) } : {}),
               contentHashSource: rawChunkedContent,
               // Faithfulness gate (issue #1576).
               ...(faithfulnessFm ? { faithfulness: faithfulnessFm } : {}),
@@ -15229,7 +15255,17 @@ export class Orchestrator {
                   intentActionType: inferredIntent?.actionType,
                   intentEntityTypes: inferredIntent?.entityTypes,
                   memoryKind,
-                  validAt: sourceContext?.validAt,
+                  validAt: biTemporal ? biTemporal.validFrom : sourceContext?.validAt,
+                  // #1578: propagate end bound + provenance to chunks (cursor bugbot).
+                  ...(biTemporal
+                    ? {
+                        observedAt: biTemporal.observedAt,
+                        eventTimeSource: biTemporal.eventTimeSource,
+                        ...(biTemporal.validUntil
+                          ? { invalidAt: biTemporal.validUntil }
+                          : {}),
+                      }
+                    : {}),
                   // Faithfulness gate (issue #1576): propagate the parent
                   // fact's verdict + enforce status so a pending_review fact
                   // is not indexed as active through its chunks (chatgpt P2).
@@ -15287,8 +15323,12 @@ export class Orchestrator {
                 newMemoryId: parentId,
                 entityRef: supersessionEntityRef,
                 structuredAttributes: fact.structuredAttributes,
-                createdAt: supersessionOrderingAt(sourceContext?.validAt),
-                enabled: this.config.temporalSupersessionEnabled,
+                createdAt: supersessionOrderingAt(biTemporal?.validFrom ?? sourceContext?.validAt),
+                // #1578 r3: an extracted end-only bound (validFrom absent) is
+                // historical, not a new authoritative state — never let it
+                // supersede a later active fact (codex P1 on :15534).
+                enabled: this.config.temporalSupersessionEnabled &&
+                  !(biTemporal && !biTemporal.validFrom),
               });
             } catch (err) {
               log.warn(`temporal-supersession (chunked): unexpected error: ${err}`);
@@ -15311,7 +15351,14 @@ export class Orchestrator {
             intentActionType: inferredIntent?.actionType,
             intentEntityTypes: inferredIntent?.entityTypes,
             memoryKind,
-            validAt: sourceContext?.validAt,
+            validAt: biTemporal ? biTemporal.validFrom : sourceContext?.validAt,
+            ...(biTemporal
+              ? {
+                  observedAt: biTemporal.observedAt,
+                  eventTimeSource: biTemporal.eventTimeSource,
+                  ...(biTemporal.validUntil ? { invalidAt: biTemporal.validUntil } : {}),
+                }
+              : {}),
             source: extractionWriteSource,
             ...(fact.sources && fact.sources.length > 0 ? { sources: fact.sources } : {}),
             ...(fact.provenance ? { provenance: fact.provenance } : {}),
@@ -15444,13 +15491,11 @@ export class Orchestrator {
             : undefined;
 
       // Normal write (no chunking)
-      //
       // Compute the cited content once so that writeMemory and writeArtifact
       // (when verbatim artifacts are enabled) share the same citation timestamp.
       // Calling applyInlineCitation twice on the same raw content would produce
       // two different timestamps, creating duplicate citations with divergent
       // provenance metadata on the memory and artifact copies of the same fact.
-      //
       // Pass the RAW (pre-citation) fact as `contentHashSource` so the
       // fact-content hash index records the hash of the canonical fact text
       // rather than the citation-annotated variant. When inline attribution is
@@ -15483,7 +15528,8 @@ export class Orchestrator {
           intentEntityTypes: inferredIntent?.entityTypes,
           memoryKind,
           structuredAttributes: fact.structuredAttributes,
-          validAt: sourceContext?.validAt,
+          validAt: biTemporal ? biTemporal.validFrom : sourceContext?.validAt,
+          ...(biTemporal ? { observedAt: biTemporal.observedAt, eventTimeSource: biTemporal.eventTimeSource, ...(biTemporal.validUntil ? { invalidAt: biTemporal.validUntil } : {}) } : {}),
           contentHashSource: writeCategory === "fact" ? fact.content : undefined,
           // Faithfulness gate (issue #1576).
           ...(faithfulnessFm ? { faithfulness: faithfulnessFm } : {}),
@@ -15516,8 +15562,9 @@ export class Orchestrator {
             newMemoryId: memoryId,
             entityRef: supersessionEntityRef,
             structuredAttributes: fact.structuredAttributes,
-            createdAt: supersessionOrderingAt(sourceContext?.validAt),
-            enabled: this.config.temporalSupersessionEnabled,
+            createdAt: supersessionOrderingAt(biTemporal?.validFrom ?? sourceContext?.validAt),
+            enabled: this.config.temporalSupersessionEnabled &&
+              !(biTemporal && !biTemporal.validFrom),
           });
         } catch (err) {
           log.warn(`temporal-supersession: unexpected error: ${err}`);
@@ -15564,7 +15611,14 @@ export class Orchestrator {
           intentActionType: inferredIntent?.actionType,
           intentEntityTypes: inferredIntent?.entityTypes,
           memoryKind,
-          validAt: sourceContext?.validAt,
+          validAt: biTemporal ? biTemporal.validFrom : sourceContext?.validAt,
+          ...(biTemporal
+            ? {
+                observedAt: biTemporal.observedAt,
+                eventTimeSource: biTemporal.eventTimeSource,
+                ...(biTemporal.validUntil ? { invalidAt: biTemporal.validUntil } : {}),
+              }
+            : {}),
           source: extractionWriteSource,
           ...(fact.sources && fact.sources.length > 0 ? { sources: fact.sources } : {}),
           ...(fact.provenance ? { provenance: fact.provenance } : {}),

package/src/schemas.ts

@@ -166,6 +166,18 @@ export const ExtractedFactSchema = z.object({
     .describe(
       'For category "reasoning_trace" only: a stored solution chain with ordered steps, a final answer, and an optional observed outcome. Require at least two steps.',
     ),
+  eventTime: z
+    .string()
+    .optional()
+    .nullable()
+    .describe(
+      'Optional event-time expression for bi-temporal validity (#1578). An ISO date ("2025-03-01") or a relative expression verbatim ("last March", "yesterday", "since 2024", "until 2025-06-01"). Resolved against the source turn timestamp at write time — NOT wall-clock. Omit when the fact has no explicit temporal anchor.',
+    ),
+  event_time: z
+    .string()
+    .optional()
+    .nullable()
+    .describe("Alias for eventTime (snake_case). Gateway-tolerance shim (#1578)."),
 }).superRefine((value, ctx) => {
   if (value.category === "procedure" && (!Array.isArray(value.procedureSteps) || value.procedureSteps.length < 2)) {
     ctx.addIssue({

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();
+  }
+});