@remnic/core 9.3.703 → 9.3.705

package/src/storage-contract/round-trip.test.ts

@@ -0,0 +1,226 @@
+/**
+ * Issue #1533 — Phase A contract test: write/read/list/delete round-trips.
+ *
+ * For EVERY category directory (iterated from ALL_CATEGORY_DIRS, never hardcoded
+ * — rule 53's cousin), exercises the documented public surface end to end:
+ *
+ *   writeMemory → readMemoryByPath → getMemoryById → readAllMemories → invalidateMemory
+ *
+ * Asserts content fidelity, frontmatter integrity, hash identity, and that
+ * deleted memories disappear from every read path. This is the round-trip
+ * contract that the 51 importers depend on; Phase B moves MUST keep it green.
+ */
+
+import assert from "node:assert/strict";
+import type { MemoryCategory } from "../types.js";
+import test from "node:test";
+
+import { StorageManager } from "../storage.js";
+import {
+  ALL_CATEGORY_DIRS,
+  ALL_CATEGORY_KEYS,
+  CATEGORY_DIR_MAP,
+  RECALL_NON_MEMORY_DIRS,
+  categoryDirName,
+} from "../utils/category-dir.js";
+import { makeStorage } from "./harness.js";
+
+/**
+ * The singular category keys writeMemory accepts, minus "entity" (entities use
+ * a separate write path: writeEntity) and "question" (questions are a
+ * non-memory QUEUE dir — RECALL_NON_MEMORY_DIRS — surfaced through
+ * writeQuestion/readQuestions, NOT readAllMemories; see question-queue test).
+ */
+const ROUND_TRIP_CATEGORIES = ALL_CATEGORY_KEYS.filter(
+  (k) => k !== "entity" && k !== "question",
+) as MemoryCategory[];
+
+test("round-trip: writeMemory returns a stable id and persists to the category dir", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    const id = await storage.writeMemory("fact", "The sky is blue", {
+      tags: ["contract"],
+    });
+    assert.equal(typeof id, "string");
+    assert.match(id, /^fact-/);
+
+    const byId = await storage.getMemoryById(id);
+    assert.ok(byId, "getMemoryById must find the just-written memory");
+    assert.equal(byId!.frontmatter.id, id);
+    assert.equal(byId!.content, "The sky is blue");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("round-trip: readAllMemories returns written memories from every category dir", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    const written: string[] = [];
+    for (const category of ROUND_TRIP_CATEGORIES) {
+      const id = await storage.writeMemory(
+        category,
+        `content for ${category}`,
+        { confidence: 0.9 },
+      );
+      written.push(id);
+    }
+
+    const all = await storage.readAllMemories();
+    const ids = new Set(all.map((m) => m.frontmatter.id));
+    for (const id of written) {
+      assert.ok(ids.has(id), `readAllMemories missing memory ${id} (${ROUND_TRIP_CATEGORIES.find((c) => id.startsWith(c))})`);
+    }
+  } finally {
+    await cleanup();
+  }
+});
+
+for (const category of ROUND_TRIP_CATEGORIES) {
+  test(`round-trip [${category}]: write → read-by-path → read-by-id → list → delete`, async () => {
+    const { storage, cleanup } = await makeStorage();
+    try {
+      const content = `fact body for category ${category}`;
+      const id = await storage.writeMemory(category, content, {
+        tags: ["round-trip"],
+      });
+
+      // getMemoryById
+      const byId = await storage.getMemoryById(id);
+      assert.ok(byId, "getMemoryById returned null");
+      assert.equal(byId!.content, content);
+      assert.equal(byId!.frontmatter.category, category);
+
+      // readMemoryByPath — the path comes from the byId result
+      const byPath = await storage.readMemoryByPath(byId!.path);
+      assert.ok(byPath, "readMemoryByPath returned null");
+      assert.equal(byPath!.content, content);
+      assert.equal(byPath!.frontmatter.id, id);
+
+      // The file landed under the right category dir
+      const expectedDir = categoryDirName(category);
+      assert.ok(
+        byId!.path.includes(`/${expectedDir}/`),
+        `${category} memory landed in ${byId!.path}, expected under ${expectedDir}/`,
+      );
+
+      // list contains it
+      const all = await storage.readAllMemories();
+      assert.ok(
+        all.some((m) => m.frontmatter.id === id),
+        "readAllMemories did not include the written memory",
+      );
+
+      // delete (invalidate) removes it from every read path
+      const deleted = await storage.invalidateMemory(id);
+      assert.equal(deleted, true, "invalidateMemory should return true on success");
+
+      const afterDelete = await storage.getMemoryById(id);
+      assert.equal(afterDelete, null, "getMemoryById must return null after invalidateMemory");
+
+      const allAfter = await storage.readAllMemories();
+      assert.ok(
+        !allAfter.some((m) => m.frontmatter.id === id),
+        "readAllMemories must not include deleted memory",
+      );
+    } finally {
+      await cleanup();
+    }
+  });
+}
+
+test("round-trip: invalidateMemory returns false for a non-existent id (not a throw)", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    const result = await storage.invalidateMemory("does-not-exist-12345");
+    assert.equal(result, false);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("round-trip: getMemoryById returns null for a non-existent id", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    const result = await storage.getMemoryById("missing-id");
+    assert.equal(result, null);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("round-trip: readMemoryByPath returns null for a non-existent path", async () => {
+  const { storage, baseDir, cleanup } = await makeStorage();
+  try {
+    const result = await storage.readMemoryByPath(
+      `${baseDir}/facts/2026-01-01/nonexistent.md`,
+    );
+    assert.equal(result, null);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("round-trip: ALL_CATEGORY_DIRS is exactly facts + every CATEGORY_DIR_MAP value", () => {
+  // ALL_CATEGORY_DIRS must contain directory NAMES (facts, decisions, ...) not
+  // singular keys (fact, decision, ...). This guards the parity between
+  // categoryDirName() and the scan roots — a divergence would silently drop
+  // a category from recall.
+  const expected = new Set(["facts", ...Object.values(CATEGORY_DIR_MAP)]);
+  assert.deepEqual(new Set(ALL_CATEGORY_DIRS), expected);
+  // No singular keys leaked in
+  for (const dir of ALL_CATEGORY_DIRS) {
+    assert.ok(!Object.hasOwn(CATEGORY_DIR_MAP, dir),
+      `${dir} is a singular category key, not a directory name`);
+  }
+});
+
+test("round-trip: StorageManager.dir exposes the base directory", async () => {
+  const { storage, baseDir, cleanup } = await makeStorage();
+  try {
+    assert.equal(storage.dir, baseDir);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("question-queue: writeQuestion → readQuestions → resolveQuestion round-trip (questions are NOT in readAllMemories)", async () => {
+  const { storage, cleanup } = await makeStorage();
+  try {
+    const id = await storage.writeQuestion("What database are we on?", "infra context", 3);
+    assert.equal(typeof id, "string");
+    assert.match(id, /^q-/);
+
+    // readQuestions returns it
+    const questions = await storage.readQuestions();
+    const q = questions.find((x) => x.id === id);
+    assert.ok(q, "readQuestions must include the just-written question");
+    assert.equal(q!.question, "What database are we on?");
+    assert.equal(q!.resolved, false);
+
+    // questions/ is a RECALL_NON_MEMORY_DIRS entry — it must NOT appear in readAllMemories
+    const all = await storage.readAllMemories();
+    assert.ok(
+      !all.some((m) => m.frontmatter.id === id),
+      "questions must not leak into the memory corpus (readAllMemories)",
+    );
+
+    // unresolvedOnly filter works
+    const unresolved = await storage.readQuestions({ unresolvedOnly: true });
+    assert.ok(unresolved.some((x) => x.id === id));
+
+    // resolve marks it resolved
+    const resolved = await storage.resolveQuestion(id);
+    assert.equal(resolved, true);
+
+    const afterResolve = await storage.readQuestions({ unresolvedOnly: true });
+    assert.ok(!afterResolve.some((x) => x.id === id), "resolved question must not appear in unresolvedOnly");
+
+    const allAfter = await storage.readQuestions();
+    const resolvedQ = allAfter.find((x) => x.id === id);
+    assert.ok(resolvedQ, "resolved question should still be readable without the filter");
+    assert.equal(resolvedQ!.resolved, true);
+  } finally {
+    await cleanup();
+  }
+});

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

@@ -0,0 +1,90 @@
+/**
+ * Issue #1533 — Phase A contract test: public-surface enumeration.
+ *
+ * Phase A step 1: enumerate the public surface of storage.ts so the contract
+ * suite has an explicit inventory. This test pins the exported symbols the 51+
+ * importers depend on. When Phase B extracts seams, every entry here must still
+ * resolve — either on storage.ts or on the storage/* module that absorbed it.
+ *
+ * This is NOT a behavior test; it is a surface-stability guard. It documents
+ * what the MemoryStorage interface must cover.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import * as storageModule from "../storage.js";
+
+test("surface: StorageManager class is exported and constructible", () => {
+  assert.equal(typeof storageModule.StorageManager, "function");
+  assert.equal(storageModule.StorageManager.name, "StorageManager");
+});
+
+test("surface: ContentHashIndex class is exported", () => {
+  assert.equal(typeof storageModule.ContentHashIndex, "function");
+  assert.equal(storageModule.ContentHashIndex.name, "ContentHashIndex");
+});
+
+test("surface: entity helpers are exported (parseEntityFile, serializeEntityFile, normalizeEntityName)", () => {
+  assert.equal(typeof storageModule.parseEntityFile, "function");
+  assert.equal(typeof storageModule.serializeEntityFile, "function");
+  assert.equal(typeof storageModule.normalizeEntityName, "function");
+});
+
+test("surface: StorageManager exposes the documented memory CRUD methods", () => {
+  const proto = storageModule.StorageManager.prototype;
+  const required = [
+    "writeMemory",
+    "readAllMemories",
+    "readMemoryByPath",
+    "getMemoryById",
+    "invalidateMemory",
+    "updateMemory",
+    "ensureDirectories",
+    "setVersioningConfig",
+    "isSecureStoreUnlocked",
+    "getMemoryStatusVersion",
+  ];
+  for (const method of required) {
+    assert.equal(
+      typeof (proto as unknown as Record<string, unknown>)[method],
+      "function",
+      `StorageManager.prototype.${method} must be a function (documented public surface)`,
+    );
+  }
+});
+
+test("surface: StorageManager exposes the question-queue methods", () => {
+  const proto = storageModule.StorageManager.prototype;
+  assert.equal(typeof proto.writeQuestion, "function");
+  assert.equal(typeof proto.readQuestions, "function");
+  assert.equal(typeof proto.resolveQuestion, "function");
+});
+
+test("surface: StorageManager exposes cache invalidation methods (rule 37)", () => {
+  const proto = storageModule.StorageManager.prototype;
+  assert.equal(typeof proto.invalidateAllMemoriesCacheForDir, "function");
+  assert.equal(typeof proto.invalidateMemoryCachesForTiers, "function");
+});
+
+test("surface: StorageManager has a static clearAllStaticCaches for test isolation", () => {
+  assert.equal(
+    typeof storageModule.StorageManager.clearAllStaticCaches,
+    "function",
+    "clearAllStaticCaches is the test-isolation chokepoint",
+  );
+});
+
+test("surface: ContentHashIndex exposes computeHash and normalizeContent (rule 23)", () => {
+  assert.equal(typeof storageModule.ContentHashIndex.computeHash, "function");
+  assert.equal(typeof storageModule.ContentHashIndex.normalizeContent, "function");
+});
+
+test("surface: StorageManager.dir getter returns the base directory string", () => {
+  const desc = Object.getOwnPropertyDescriptor(
+    storageModule.StorageManager.prototype,
+    "dir",
+  );
+  assert.ok(desc, "dir must be a property on the prototype");
+  assert.equal(typeof desc?.get, "function", "dir must have a getter");
+});

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

@@ -0,0 +1,139 @@
+/**
+ * Issue #1533 — Phase A contract test: page versioning snapshots.
+ *
+ * When versioning is enabled, overwriting a FIXED-PATH file produces a numbered
+ * snapshot in the `.versions/` sidecar. Revert restores a prior version.
+ * This pins the versioning contract the consolidation/provenance paths rely on.
+ *
+ * NOTE: `writeMemory` generates a unique path per id, so the first write to a
+ * path never has pre-existing content to snapshot. The versioning integration
+ * is exercised through `writeProfile` — a fixed-path write that calls
+ * `snapshotBeforeWrite` before overwriting. The direct `createVersion`/
+ * `revertToVersion` API is tested separately.
+ */
+
+import assert from "node:assert/strict";
+import { mkdtemp, rm, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  createVersion,
+  listVersions,
+  revertToVersion,
+  getVersion,
+  type VersioningConfig,
+} from "../page-versioning.js";
+import { StorageManager } from "../storage.js";
+import { resetStaticCaches } from "./harness.js";
+
+const VERSIONING_CONFIG: VersioningConfig = {
+  enabled: true,
+  maxVersionsPerPage: 10,
+  sidecarDir: ".versions",
+};
+
+test("versioning: overwrite of a fixed-path file (writeProfile) produces a numbered snapshot", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-ver-snapshot-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    storage.setVersioningConfig(VERSIONING_CONFIG);
+
+    const profilePath = path.join(dir, "profile.md");
+    await storage.writeProfile("first version of profile");
+
+    // Overwrite the same fixed path → snapshotBeforeWrite fires
+    await storage.writeProfile("second version of profile");
+
+    const versions = await listVersions(profilePath, VERSIONING_CONFIG);
+    assert.ok(
+      versions.versions.length >= 1,
+      "at least one snapshot must exist after overwriting a fixed-path file",
+    );
+    assert.equal(versions.versions[0].trigger, "consolidation");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("versioning: snapshot captures the PRE-overwrite content", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-ver-pre-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    storage.setVersioningConfig(VERSIONING_CONFIG);
+
+    const profilePath = path.join(dir, "profile.md");
+    await storage.writeProfile("ORIGINAL PROFILE");
+    await storage.writeProfile("REPLACEMENT PROFILE");
+
+    const versions = await listVersions(profilePath, VERSIONING_CONFIG);
+    assert.ok(versions.versions.length >= 1);
+
+    // Read the snapshot — it must contain the ORIGINAL, not the replacement
+    const snapshot = await getVersion(profilePath, versions.versions[0].versionId, VERSIONING_CONFIG);
+    assert.ok(snapshot, "snapshot content must be readable");
+    assert.ok(
+      snapshot!.includes("ORIGINAL PROFILE"),
+      "the snapshot must contain the pre-overwrite content",
+    );
+    assert.ok(
+      !snapshot!.includes("REPLACEMENT"),
+      "the snapshot must NOT contain the replacement content",
+    );
+
+    // The live file has the replacement
+    const live = await readFile(profilePath, "utf-8");
+    assert.ok(live.includes("REPLACEMENT PROFILE"));
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("versioning: disabled by default — no snapshots created", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-ver-disabled-"));
+  try {
+    resetStaticCaches();
+    const storage = new StorageManager(dir);
+    await storage.ensureDirectories();
+    // Do NOT call setVersioningConfig — default is disabled
+    await storage.writeProfile("v1");
+    await storage.writeProfile("v2");
+
+    const profilePath = path.join(dir, "profile.md");
+    const versions = await listVersions(profilePath, VERSIONING_CONFIG);
+    assert.equal(versions.versions.length, 0, "no snapshots when versioning was disabled at write time");
+  } finally {
+    resetStaticCaches();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("versioning: createVersion → revertToVersion round-trip restores content", async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-ver-revert-"));
+  try {
+    const filePath = path.join(dir, "doc.md");
+    await writeFile(filePath, "alpha", "utf-8");
+
+    await createVersion(filePath, "alpha", "manual", VERSIONING_CONFIG);
+    await writeFile(filePath, "beta", "utf-8");
+    await createVersion(filePath, "beta", "manual", VERSIONING_CONFIG);
+
+    const versions = await listVersions(filePath, VERSIONING_CONFIG);
+    assert.ok(versions.versions.length >= 2);
+
+    const firstVersionId = versions.versions[0].versionId;
+    await revertToVersion(filePath, firstVersionId, VERSIONING_CONFIG);
+
+    const restored = await readFile(filePath, "utf-8");
+    assert.equal(restored, "alpha", "revert must restore the version-1 content");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});