@remnic/core 9.3.704 → 9.3.705

package/src/storage-contract/harness.ts

@@ -0,0 +1,148 @@
+/**
+ * Issue #1533 — Storage contract test harness.
+ *
+ * Shared fixture helpers for the storage public-surface contract suite AND
+ * the #1522 catalog-touch fitness test (both live under `storage-contract/`
+ * per the issue's coordination note: "build both on ONE shared harness so the
+ * write-entry-point enumeration lives in exactly one place").
+ *
+ * Every helper creates a fresh temp directory and returns a `cleanup` that
+ * tears it down — tests never share state. `StorageManager.clearAllStaticCaches()`
+ * is called on setup and teardown so the module-level caches (readAllMemories
+ * in-flight, version sentinels, secure-store entity cache) do not leak between
+ * tests.
+ */
+
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { StorageManager } from "../storage.js";
+import {
+  NamespaceStorageRouter,
+} from "../namespaces/storage.js";
+import type { PluginConfig } from "../types.js";
+
+/** Clear every module-level cache so tests start from a known-empty state. */
+export function resetStaticCaches(): void {
+  StorageManager.clearAllStaticCaches();
+}
+
+/**
+ * Create a StorageManager backed by a fresh temp directory.
+ *
+ * Returns the manager, the on-disk base directory, and a `cleanup` that removes
+ * the directory and clears static caches. Callers MUST call `cleanup` in a
+ * `try/finally` (or via `node:test`'s `t.after`).
+ */
+export async function makeStorage(
+  prefix = "remnic-storage-contract-",
+): Promise<{
+  storage: StorageManager;
+  baseDir: string;
+  cleanup: () => Promise<void>;
+}> {
+  resetStaticCaches();
+  const baseDir = await mkdtemp(path.join(os.tmpdir(), prefix));
+  const storage = new StorageManager(baseDir);
+  await storage.ensureDirectories();
+  storage.invalidateAllMemoriesCacheForDir();
+  return {
+    storage,
+    baseDir,
+    cleanup: async () => {
+      resetStaticCaches();
+      await rm(baseDir, { recursive: true, force: true });
+    },
+  };
+}
+
+/**
+ * Build a minimal valid memory markdown body for raw seeding (bypasses
+ * writeMemory so the test controls exact on-disk bytes).
+ */
+export function rawMemoryMarkdown(
+  id: string,
+  category: string,
+  content: string,
+  extra: Record<string, string> = {},
+): string {
+  const now = new Date().toISOString();
+  const lines = [
+    "---",
+    `id: ${id}`,
+    `category: ${category}`,
+    `created: ${now}`,
+    `updated: ${now}`,
+    "source: test",
+    "confidence: 0.9",
+    'tags: ["contract"]',
+  ];
+  for (const [key, value] of Object.entries(extra)) {
+    lines.push(`${key}: ${value}`);
+  }
+  lines.push("---", "", content, "");
+  return lines.join("\n");
+}
+
+/**
+ * Seed a raw markdown file at a path relative to `baseDir`. Used when a test
+ * needs to control exact placement (e.g. a specific category dir + date nest)
+ * without going through `writeMemory`.
+ */
+export async function seedRawFile(
+  baseDir: string,
+  relPath: string,
+  content: string,
+): Promise<string> {
+  const fullPath = path.join(baseDir, relPath);
+  await mkdir(path.dirname(fullPath), { recursive: true });
+  await writeFile(fullPath, content, "utf-8");
+  return fullPath;
+}
+
+/**
+ * Minimal PluginConfig for NamespaceStorageRouter tests. Only the fields the
+ * router reads are populated; the rest default to values that keep the router
+ * in the namespaces-enabled mode the tests exercise.
+ */
+export function makeNamespaceConfig(
+  memoryDir: string,
+  overrides: Record<string, unknown> = {},
+): PluginConfig {
+  return {
+    memoryDir,
+    namespacesEnabled: true,
+    defaultNamespace: "default",
+    entitySchemas: {},
+    inlineSourceAttributionFormat: undefined,
+    ...overrides,
+  } as unknown as PluginConfig;
+}
+
+/**
+ * Create a NamespaceStorageRouter over a fresh temp dir with namespaces
+ * enabled. Returns the router, the memory dir, and a cleanup.
+ */
+export async function makeNamespaceRouter(
+  overrides: Partial<PluginConfig> = {},
+): Promise<{
+  router: NamespaceStorageRouter;
+  memoryDir: string;
+  config: PluginConfig;
+  cleanup: () => Promise<void>;
+}> {
+  resetStaticCaches();
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-ns-contract-"));
+  const config = makeNamespaceConfig(memoryDir, overrides);
+  const router = new NamespaceStorageRouter(config);
+  return {
+    router,
+    memoryDir,
+    config,
+    cleanup: async () => {
+      resetStaticCaches();
+      await rm(memoryDir, { recursive: true, force: true });
+    },
+  };
+}

package/src/storage-contract/namespace-routing.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Issue #1533 — Phase A contract test: namespace routing.
+ *
+ * NamespaceStorageRouter must route the SAME operation through the correct
+ * on-disk root for default vs named namespaces, while rejecting escaping paths
+ * (the containment invariants from #1506 — a FILE at the namespaces root or at
+ * a token dir is rejected via statSync().isDirectory(), not existsSync; rule 24).
+ *
+ * Contracts pinned:
+ *  - default namespace → memoryDir (legacy root)
+ *  - named namespace → memoryDir/namespaces/<token>
+ *  - unsafe namespace segments (/, \, .., absolute) are rejected
+ *  - writes in one namespace are invisible to another
+ */
+
+import assert from "node:assert/strict";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import test from "node:test";
+
+import { makeStorage, makeNamespaceRouter } from "./harness.js";
+import { resolveNamespaceStorageRoot } from "../namespaces/storage.js";
+import { namespaceIdentityToken } from "../namespaces/identity.js";
+
+test("namespace-routing: default namespace resolves to the legacy memoryDir root", async () => {
+  const { router, memoryDir, config, cleanup } = await makeNamespaceRouter();
+  try {
+    const root = await resolveNamespaceStorageRoot(config, "default");
+    assert.equal(root, memoryDir);
+
+    const sm = await router.storageFor("default");
+    assert.equal(sm.dir, memoryDir);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("namespace-routing: named namespace resolves to a tokenized subdirectory", async () => {
+  const { router, memoryDir, config, cleanup } = await makeNamespaceRouter();
+  try {
+    const ns = "team-alpha";
+    const root = await resolveNamespaceStorageRoot(config, ns);
+    const token = namespaceIdentityToken(ns);
+    assert.ok(
+      root.includes(path.join("namespaces", token)),
+      `named namespace root ${root} should include namespaces/${token}`,
+    );
+
+    const sm = await router.storageFor(ns);
+    assert.ok(sm.dir.startsWith(memoryDir), "named namespace must be under memoryDir");
+    assert.ok(sm.dir.includes("namespaces"), "named namespace must be under namespaces/");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("namespace-routing: two named namespaces resolve to DIFFERENT roots", async () => {
+  const { router, cleanup } = await makeNamespaceRouter();
+  try {
+    const sm1 = await router.storageFor("team-alpha");
+    const sm2 = await router.storageFor("team-beta");
+    assert.notEqual(sm1.dir, sm2.dir, "different namespaces must have different roots");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("namespace-routing: writes in one namespace are invisible to another (isolation)", async () => {
+  const { router, cleanup } = await makeNamespaceRouter();
+  try {
+    const sm1 = await router.storageFor("team-alpha");
+    const id = await sm1.writeMemory("fact", "alpha-only fact");
+
+    const sm2 = await router.storageFor("team-beta");
+    const found = await sm2.getMemoryById(id);
+    assert.equal(found, null, "beta namespace must not see alpha's memories");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("namespace-routing: resolveNamespaceStorageRoot rejects traversal segments", async () => {
+  const { config, cleanup } = await makeNamespaceRouter();
+  try {
+    for (const bad of ["../escape", "a/b", "a\\b", "/abs"]) {
+      await assert.rejects(
+        () => resolveNamespaceStorageRoot(config, bad),
+        /unsafe namespace path segment/,
+        `should reject ${bad}`,
+      );
+    }
+  } finally {
+    await cleanup();
+  }
+});
+
+test("namespace-routing: storageFor rejects unsafe non-default namespaces", async () => {
+  const { router, cleanup } = await makeNamespaceRouter();
+  try {
+    for (const bad of ["../escape", "a/b"]) {
+      await assert.rejects(
+        () => router.storageFor(bad),
+        /unsafe namespace/,
+        `should reject ${bad}`,
+      );
+    }
+  } finally {
+    await cleanup();
+  }
+});
+
+test("namespace-routing: namespaces disabled → all namespaces use memoryDir", async () => {
+  const { router, memoryDir, cleanup } = await makeNamespaceRouter({
+    namespacesEnabled: false,
+  });
+  try {
+    const sm1 = await router.storageFor("default");
+    const sm2 = await router.storageFor("anything");
+    assert.equal(sm1.dir, memoryDir);
+    assert.equal(sm2.dir, memoryDir);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("namespace-routing: router caches StorageManager per namespace (same instance on repeat)", async () => {
+  const { router, cleanup } = await makeNamespaceRouter();
+  try {
+    const sm1 = await router.storageFor("team-alpha");
+    const sm2 = await router.storageFor("team-alpha");
+    assert.equal(sm1, sm2, "storageFor must return the cached instance for the same namespace");
+  } finally {
+    await cleanup();
+  }
+});

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