@remnic/core 9.25.7 → 9.26.0

package/src/session-namespace-bindings.test.ts

@@ -0,0 +1,358 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  createFileSessionNamespaceBindingStore,
+  createInMemorySessionNamespaceBindingStore,
+  SESSION_NAMESPACE_BINDING_MAX_ENTRIES,
+  SESSION_NAMESPACE_BINDING_MAX_NAMESPACES,
+  SESSION_NAMESPACE_BINDING_MAX_NAMESPACE_LENGTH,
+} from "./session-namespace-bindings.js";
+
+test("session namespace bindings persist prototype-named session keys", async () => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "remnic-namespace-bindings-"));
+  const filePath = path.join(directory, "session-namespace-bindings.json");
+  try {
+    const store = createFileSessionNamespaceBindingStore(filePath);
+    await store.remember("__proto__", "team-prototype");
+
+    const reloaded = createFileSessionNamespaceBindingStore(filePath);
+    assert.deepEqual(await reloaded.namespacesFor("__proto__"), ["team-prototype"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+test("session namespace bindings propagate malformed-file reads without overwriting them", async () => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "remnic-namespace-bindings-"));
+  const filePath = path.join(directory, "session-namespace-bindings.json");
+  try {
+    await writeFile(filePath, "{", "utf8");
+    const store = createFileSessionNamespaceBindingStore(filePath);
+
+    await assert.rejects(() => store.namespacesFor("malformed-session"), SyntaxError);
+    await assert.rejects(() => store.remember("malformed-session", "team-known"), SyntaxError);
+    assert.equal(await readFile(filePath, "utf8"), "{");
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("session namespace bindings reject structurally invalid files without overwriting them", async () => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "remnic-namespace-bindings-"));
+  const filePath = path.join(directory, "session-namespace-bindings.json");
+  try {
+    await writeFile(filePath, JSON.stringify({ entries: null }), "utf8");
+    const store = createFileSessionNamespaceBindingStore(filePath);
+
+    await assert.rejects(() => store.namespacesFor("invalid-structure-session"), /invalid structure/);
+    await assert.rejects(() => store.remember("invalid-structure-session", "team-known"), /invalid structure/);
+    assert.equal(await readFile(filePath, "utf8"), JSON.stringify({ entries: null }));
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("session namespace bindings reject unsupported file versions without overwriting them", async () => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "remnic-namespace-bindings-"));
+  const filePath = path.join(directory, "session-namespace-bindings.json");
+  const updatedAt = new Date().toISOString();
+  const validEntry = { namespaces: ["team-known"], updatedAt };
+  const invalidFiles = [
+    { entries: { "versionless-session": validEntry } },
+    { version: 2, entries: { "newer-version-session": validEntry } },
+  ];
+  try {
+    for (const file of invalidFiles) {
+      const raw = JSON.stringify(file);
+      await writeFile(filePath, raw, "utf8");
+      const store = createFileSessionNamespaceBindingStore(filePath);
+
+      await assert.rejects(
+        () => store.namespacesFor("unsupported-version-session"),
+        /invalid structure/,
+      );
+      await assert.rejects(
+        () => store.remember("unsupported-version-session", "team-known"),
+        /invalid structure/,
+      );
+      assert.equal(await readFile(filePath, "utf8"), raw);
+    }
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("session namespace bindings reject malformed persisted entries", async () => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "remnic-namespace-bindings-"));
+  const filePath = path.join(directory, "session-namespace-bindings.json");
+  const updatedAt = new Date().toISOString();
+  const invalidEntries = [
+    { "null-entry": null },
+    { "missing-namespaces": { updatedAt } },
+    { "missing-updated-at": { namespaces: ["team-known"] } },
+    { "invalid-namespaces": { namespaces: ["team-known", null], updatedAt } },
+    {
+      "oversized-namespace": {
+        namespaces: ["x".repeat(SESSION_NAMESPACE_BINDING_MAX_NAMESPACE_LENGTH + 1)],
+        updatedAt,
+      },
+    },
+  ];
+  try {
+    for (const entries of invalidEntries) {
+      const raw = JSON.stringify({ version: 1, entries });
+      await writeFile(filePath, raw, "utf8");
+      const store = createFileSessionNamespaceBindingStore(filePath);
+
+      await assert.rejects(
+        () => store.namespacesFor("invalid-entry-session"),
+        /entry has invalid structure/,
+      );
+      await assert.rejects(
+        () => store.remember("invalid-entry-session", "team-known"),
+        /entry has invalid structure/,
+      );
+      assert.equal(await readFile(filePath, "utf8"), raw);
+    }
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("session namespace bindings retain concurrent scope observations", async () => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "remnic-namespace-bindings-"));
+  const filePath = path.join(directory, "session-namespace-bindings.json");
+  try {
+    await Promise.all([
+      createFileSessionNamespaceBindingStore(filePath).remember("session-1", "team-first"),
+      createFileSessionNamespaceBindingStore(filePath).remember("session-1", "team-second"),
+    ]);
+
+    const reloaded = createFileSessionNamespaceBindingStore(filePath);
+    assert.deepEqual((await reloaded.namespacesFor("session-1")).sort(), ["team-first", "team-second"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("session namespace bindings persist an explicit default scope", async () => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "remnic-namespace-bindings-"));
+  const filePath = path.join(directory, "session-namespace-bindings.json");
+  try {
+    const store = createFileSessionNamespaceBindingStore(filePath);
+    await store.remember("session-1", "team-named");
+    await store.remember("session-1", "");
+
+    const reloaded = createFileSessionNamespaceBindingStore(filePath);
+    assert.deepEqual(await reloaded.namespacesFor("session-1"), ["team-named", ""]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("session namespace bindings prune expired and overflowed persisted history", async () => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "remnic-namespace-bindings-"));
+  const filePath = path.join(directory, "session-namespace-bindings.json");
+  const now = Date.now();
+  const entries = Object.fromEntries(
+    Array.from({ length: 1_000 }, (_unused, index) => [
+      `session-${index}`,
+      {
+        namespaces: [`team-${index}`],
+        updatedAt: new Date(now - index).toISOString(),
+      },
+    ])
+  ) as Record<string, { namespaces: string[]; updatedAt: string }>;
+  entries["stale-session"] = {
+    namespaces: ["team-stale"],
+    updatedAt: new Date(now - 8 * 24 * 60 * 60 * 1_000).toISOString(),
+  };
+  try {
+    await writeFile(filePath, JSON.stringify({ version: 1, entries }), "utf8");
+    const store = createFileSessionNamespaceBindingStore(filePath);
+
+    assert.deepEqual(await store.namespacesFor("stale-session"), []);
+    await store.remember("current-session", "team-current");
+
+    const persisted = JSON.parse(await readFile(filePath, "utf8")) as {
+      entries: Record<string, { namespaces: string[] }>;
+    };
+    assert.equal(Object.keys(persisted.entries).length, 1_000);
+    assert.equal("stale-session" in persisted.entries, false);
+    assert.deepEqual(await store.namespacesFor("current-session"), ["team-current"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("in-memory session namespace bindings cap inactive routing history", async () => {
+  const store = createInMemorySessionNamespaceBindingStore();
+  for (let index = 0; index <= 1_000; index += 1) {
+    await store.remember(`session-${index}`, `team-${index}`);
+  }
+
+  assert.deepEqual(await store.namespacesFor("session-0"), []);
+  assert.deepEqual(await store.namespacesFor("session-1000"), ["team-1000"]);
+});
+
+test("in-memory session namespace bindings retain sparse active sessions", async () => {
+  const store = createInMemorySessionNamespaceBindingStore();
+  for (let index = 0; index < SESSION_NAMESPACE_BINDING_MAX_ENTRIES; index += 1) {
+    await store.remember(`session-${index}`, `team-${index}`);
+  }
+
+  assert.deepEqual(await store.namespacesFor("session-0"), ["team-0"]);
+  await store.remember("overflow-session", "team-overflow");
+
+  assert.deepEqual(await store.namespacesFor("session-0"), ["team-0"]);
+  assert.deepEqual(await store.namespacesFor("session-1"), []);
+});
+
+test("session namespace bindings refresh a sparse active binding", async () => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "remnic-namespace-bindings-"));
+  const filePath = path.join(directory, "session-namespace-bindings.json");
+  const updatedAt = new Date(Date.now() - 60 * 60 * 1_000).toISOString();
+  try {
+    await writeFile(
+      filePath,
+      JSON.stringify({
+        version: 1,
+        entries: {
+          "active-session": { namespaces: ["team-active"], updatedAt },
+        },
+      }),
+      "utf8",
+    );
+    const store = createFileSessionNamespaceBindingStore(filePath);
+
+    assert.deepEqual(await store.namespacesFor("active-session"), ["team-active"]);
+
+    const persisted = JSON.parse(await readFile(filePath, "utf8")) as {
+      entries: Record<string, { updatedAt: string }>;
+    };
+    assert.ok(Date.parse(persisted.entries["active-session"].updatedAt) > Date.parse(updatedAt));
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("session namespace bindings return known scope when timestamp refresh fails", async () => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "remnic-namespace-bindings-"));
+  const filePath = path.join(directory, "session-namespace-bindings.json");
+  const updatedAt = new Date(Date.now() - 60 * 60 * 1_000).toISOString();
+  try {
+    await writeFile(
+      filePath,
+      JSON.stringify({
+        version: 1,
+        entries: {
+          "refresh-failure-session": { namespaces: ["team-known"], updatedAt },
+        },
+      }),
+      "utf8",
+    );
+    let writeAttempts = 0;
+    const store = createFileSessionNamespaceBindingStore(filePath, {
+      writeBindingFile: async () => {
+        writeAttempts += 1;
+        throw new Error("forced refresh write failure");
+      },
+    });
+
+    assert.deepEqual(await store.namespacesFor("refresh-failure-session"), ["team-known"]);
+    assert.equal(writeAttempts, 1);
+
+    const persisted = JSON.parse(await readFile(filePath, "utf8")) as {
+      entries: Record<string, { updatedAt: string }>;
+    };
+    assert.equal(persisted.entries["refresh-failure-session"].updatedAt, updatedAt);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("session namespace bindings retain failed refreshes in volatile state", async () => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "remnic-namespace-bindings-"));
+  const filePath = path.join(directory, "session-namespace-bindings.json");
+  const updatedAt = new Date(Date.now() - 60 * 60 * 1_000).toISOString();
+  try {
+    await writeFile(
+      filePath,
+      JSON.stringify({
+        version: 1,
+        entries: {
+          "volatile-refresh-session": { namespaces: ["team-known"], updatedAt },
+        },
+      }),
+      "utf8",
+    );
+    const store = createFileSessionNamespaceBindingStore(filePath, {
+      writeBindingFile: async () => {
+        throw new Error("forced refresh write failure");
+      },
+    });
+
+    assert.deepEqual(await store.namespacesFor("volatile-refresh-session"), ["team-known"]);
+    await writeFile(
+      filePath,
+      JSON.stringify({
+        version: 1,
+        entries: {
+          "volatile-refresh-session": {
+            namespaces: ["team-known"],
+            updatedAt: new Date(Date.now() - 8 * 24 * 60 * 60 * 1_000).toISOString(),
+          },
+        },
+      }),
+      "utf8",
+    );
+    assert.deepEqual(await store.namespacesFor("volatile-refresh-session"), ["team-known"]);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("session namespace bindings cap each session's namespace history", async () => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "remnic-namespace-bindings-"));
+  const filePath = path.join(directory, "session-namespace-bindings.json");
+  try {
+    const fileStore = createFileSessionNamespaceBindingStore(filePath);
+    const memoryStore = createInMemorySessionNamespaceBindingStore();
+    for (let index = 0; index <= SESSION_NAMESPACE_BINDING_MAX_NAMESPACES; index += 1) {
+      const namespace = `team-${index}`;
+      await fileStore.remember("rebound-session", namespace);
+      await memoryStore.remember("rebound-session", namespace);
+    }
+
+    const expected = Array.from(
+      { length: SESSION_NAMESPACE_BINDING_MAX_NAMESPACES },
+      (_unused, index) => `team-${index + 1}`,
+    );
+    assert.deepEqual(await fileStore.namespacesFor("rebound-session"), expected);
+    assert.deepEqual(await memoryStore.namespacesFor("rebound-session"), expected);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("session namespace bindings clean temporary files after atomic write failure", async () => {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "remnic-namespace-bindings-"));
+  const filePath = path.join(directory, "session-namespace-bindings.json");
+  const store = createFileSessionNamespaceBindingStore(filePath, {
+    renameBindingFile: async () => {
+      throw new Error("forced atomic rename failure");
+    },
+  });
+  try {
+    await assert.rejects(
+      () => store.remember("atomic-failure-session", "team-known"),
+      /forced atomic rename failure/,
+    );
+    assert.deepEqual(await readdir(directory), []);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+});

package/src/session-namespace-bindings.ts

@@ -0,0 +1,301 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export interface SessionNamespaceBindingStore {
+  namespacesFor(sessionKey: string): Promise<string[]>;
+  remember(sessionKey: string, namespace: string): Promise<void>;
+  replace?(sessionKey: string, namespaces: string[]): Promise<void>;
+}
+
+export const SESSION_NAMESPACE_BINDING_MAX_ENTRIES = 1_000;
+export const SESSION_NAMESPACE_BINDING_MAX_NAMESPACES = 64;
+export const SESSION_NAMESPACE_BINDING_MAX_NAMESPACE_LENGTH = 256;
+export const SESSION_NAMESPACE_BINDING_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1_000;
+
+interface NamespaceBindingEntry {
+  namespaces: string[];
+  updatedAt: string;
+}
+
+interface NamespaceBindingFile {
+  version: 1;
+  entries: Record<string, NamespaceBindingEntry>;
+}
+type BindingFileWriter = (filePath: string, bindings: NamespaceBindingFile) => Promise<void>;
+
+const fileWriteChains = new Map<string, Promise<void>>();
+const volatileRefreshes = new Map<string, Map<string, string>>();
+
+function retainVolatileRefresh(filePath: string, sessionKey: string, updatedAt: string): void {
+  const refreshes = volatileRefreshes.get(filePath) ?? new Map<string, string>();
+  refreshes.set(sessionKey, updatedAt);
+  volatileRefreshes.set(filePath, refreshes);
+}
+
+function clearVolatileRefresh(filePath: string, sessionKey: string): void {
+  const refreshes = volatileRefreshes.get(filePath);
+  if (refreshes === undefined) return;
+  refreshes.delete(sessionKey);
+  if (refreshes.size === 0) volatileRefreshes.delete(filePath);
+}
+
+function applyVolatileRefreshes(filePath: string, entries: Record<string, NamespaceBindingEntry>): void {
+  const refreshes = volatileRefreshes.get(filePath);
+  if (refreshes === undefined) return;
+  for (const [key, updatedAt] of refreshes) {
+    const entry = entries[key];
+    if (entry === undefined) {
+      refreshes.delete(key);
+      continue;
+    }
+    const persistedAt = Date.parse(entry.updatedAt);
+    const refreshedAt = Date.parse(updatedAt);
+    if (Number.isFinite(refreshedAt) && (!Number.isFinite(persistedAt) || refreshedAt > persistedAt)) {
+      entry.updatedAt = updatedAt;
+    } else {
+      refreshes.delete(key);
+    }
+  }
+  if (refreshes.size === 0) volatileRefreshes.delete(filePath);
+}
+
+function emptyBindingFile(): NamespaceBindingFile {
+  return { version: 1, entries: Object.create(null) as Record<string, NamespaceBindingEntry> };
+}
+
+function capNamespaceHistory(namespaces: string[]): string[] {
+  return namespaces.length > SESSION_NAMESPACE_BINDING_MAX_NAMESPACES
+    ? namespaces.slice(-SESSION_NAMESPACE_BINDING_MAX_NAMESPACES)
+    : namespaces;
+}
+
+function normalizeNamespaces(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  const namespaces: string[] = [];
+  for (const entry of value) {
+    if (typeof entry !== "string") continue;
+    const namespace = entry.trim();
+    const existing = namespaces.indexOf(namespace);
+    if (existing >= 0) namespaces.splice(existing, 1);
+    namespaces.push(namespace);
+  }
+  return capNamespaceHistory(namespaces);
+}
+
+function addNamespace(namespaces: string[], namespace: string): string[] {
+  const normalized = namespace.trim();
+  return capNamespaceHistory([
+    ...namespaces.filter((candidate) => candidate !== normalized),
+    normalized,
+  ]);
+}
+
+function pruneBindingEntries(
+  entries: Record<string, NamespaceBindingEntry>,
+  protectedKey?: string
+): Record<string, NamespaceBindingEntry> {
+  const cutoff = Date.now() - SESSION_NAMESPACE_BINDING_MAX_AGE_MS;
+  const retained = Object.entries(entries)
+    .filter(([_key, entry]) => {
+      const updatedAt = Date.parse(entry.updatedAt);
+      return Number.isFinite(updatedAt) && updatedAt >= cutoff;
+    })
+    .sort(([leftKey, left], [rightKey, right]) => {
+      if (leftKey === rightKey) return 0;
+      if (leftKey === protectedKey) return -1;
+      if (rightKey === protectedKey) return 1;
+      const leftAt = Date.parse(left.updatedAt);
+      const rightAt = Date.parse(right.updatedAt);
+      if (leftAt !== rightAt) return rightAt > leftAt ? 1 : -1;
+      return leftKey < rightKey ? -1 : 1;
+    })
+    .slice(0, SESSION_NAMESPACE_BINDING_MAX_ENTRIES);
+  const pruned = Object.create(null) as Record<string, NamespaceBindingEntry>;
+  for (const [key, entry] of retained) pruned[key] = entry;
+  return pruned;
+}
+
+function encodeSessionKey(sessionKey: string): string {
+  return encodeURIComponent(sessionKey);
+}
+
+async function readBindingFile(filePath: string): Promise<NamespaceBindingFile> {
+  let raw: string;
+  try {
+    raw = await readFile(filePath, "utf8");
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException)?.code === "ENOENT") {
+      volatileRefreshes.delete(filePath);
+      return emptyBindingFile();
+    }
+    throw err;
+  }
+  const parsed = JSON.parse(raw) as Partial<NamespaceBindingFile>;
+  if (
+    !parsed ||
+    typeof parsed !== "object" ||
+    Array.isArray(parsed) ||
+    parsed.version !== 1 ||
+    !parsed.entries ||
+    typeof parsed.entries !== "object" ||
+    Array.isArray(parsed.entries)
+  ) {
+    throw new Error("session namespace binding file has invalid structure");
+  }
+  const entries = Object.create(null) as Record<string, NamespaceBindingEntry>;
+  for (const [key, value] of Object.entries(parsed.entries)) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error("session namespace binding entry has invalid structure");
+    }
+    const entry = value as Partial<NamespaceBindingEntry>;
+    if (
+      typeof entry.updatedAt !== "string" ||
+      !Number.isFinite(Date.parse(entry.updatedAt)) ||
+      !Array.isArray(entry.namespaces) ||
+      entry.namespaces.length === 0 ||
+      entry.namespaces.some(
+        (namespace) =>
+          typeof namespace !== "string" ||
+          namespace.trim().length > SESSION_NAMESPACE_BINDING_MAX_NAMESPACE_LENGTH,
+      )
+    ) {
+      throw new Error("session namespace binding entry has invalid structure");
+    }
+    const namespaces = normalizeNamespaces(entry.namespaces);
+    if (namespaces.length === 0) {
+      throw new Error("session namespace binding entry has invalid structure");
+    }
+    entries[key] = { namespaces, updatedAt: entry.updatedAt };
+  }
+  applyVolatileRefreshes(filePath, entries);
+  return { version: 1, entries: pruneBindingEntries(entries) };
+}
+
+async function writeBindingFile(
+  filePath: string,
+  bindings: NamespaceBindingFile,
+  renameFile: typeof rename = rename,
+): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporaryPath, JSON.stringify(bindings, null, 2), "utf8");
+    await renameFile(temporaryPath, filePath);
+  } catch (err) {
+    await rm(temporaryPath, { force: true }).catch(() => undefined);
+    throw err;
+  }
+}
+
+async function queueFileWrite<TResult>(
+  filePath: string,
+  operation: () => Promise<TResult>,
+): Promise<TResult> {
+  const prior = fileWriteChains.get(filePath) ?? Promise.resolve();
+  const run = prior.catch(() => undefined).then(operation);
+  fileWriteChains.set(
+    filePath,
+    run.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return run;
+}
+
+export function createInMemorySessionNamespaceBindingStore(): SessionNamespaceBindingStore {
+  const entries = new Map<string, string[]>();
+  return {
+    async namespacesFor(sessionKey: string): Promise<string[]> {
+      const namespaces = entries.get(sessionKey);
+      if (namespaces === undefined) return [];
+      entries.delete(sessionKey);
+      entries.set(sessionKey, namespaces);
+      return [...namespaces];
+    },
+    async remember(sessionKey: string, namespace: string): Promise<void> {
+      const existing = entries.get(sessionKey) ?? [];
+      entries.delete(sessionKey);
+      entries.set(sessionKey, addNamespace(existing, namespace));
+      while (entries.size > SESSION_NAMESPACE_BINDING_MAX_ENTRIES) {
+        const oldest = entries.keys().next().value;
+        if (typeof oldest !== "string") break;
+        entries.delete(oldest);
+      }
+    },
+    async replace(sessionKey: string, namespaces: string[]): Promise<void> {
+      entries.delete(sessionKey);
+      if (namespaces.length > 0) {
+        entries.set(sessionKey, capNamespaceHistory([...namespaces]));
+      }
+      while (entries.size > SESSION_NAMESPACE_BINDING_MAX_ENTRIES) {
+        const oldest = entries.keys().next().value;
+        if (typeof oldest !== "string") break;
+        entries.delete(oldest);
+      }
+    },
+  };
+}
+
+export function createFileSessionNamespaceBindingStore(
+  filePath: string,
+  options: { writeBindingFile?: BindingFileWriter; renameBindingFile?: typeof rename } = {},
+): SessionNamespaceBindingStore {
+  const write =
+    options.writeBindingFile ??
+    ((targetPath: string, bindings: NamespaceBindingFile) =>
+      writeBindingFile(targetPath, bindings, options.renameBindingFile));
+  return {
+    async namespacesFor(sessionKey: string): Promise<string[]> {
+      const key = encodeSessionKey(sessionKey);
+      return queueFileWrite(filePath, async () => {
+        const bindings = await readBindingFile(filePath);
+        const entry = bindings.entries[key];
+        if (entry === undefined) return [];
+        const namespaces = [...entry.namespaces];
+        const updatedAt = new Date().toISOString();
+        entry.updatedAt = updatedAt;
+        bindings.entries = pruneBindingEntries(bindings.entries, key);
+        try {
+          await write(filePath, bindings);
+          clearVolatileRefresh(filePath, key);
+        } catch {
+          retainVolatileRefresh(filePath, key, updatedAt);
+          return namespaces;
+        }
+        return namespaces;
+      });
+    },
+    async remember(sessionKey: string, namespace: string): Promise<void> {
+      const key = encodeSessionKey(sessionKey);
+      await queueFileWrite(filePath, async () => {
+        const bindings = await readBindingFile(filePath);
+        const existing = bindings.entries[key]?.namespaces ?? [];
+        bindings.entries[key] = {
+          namespaces: addNamespace(existing, namespace),
+          updatedAt: new Date().toISOString(),
+        };
+        bindings.entries = pruneBindingEntries(bindings.entries, key);
+        await write(filePath, bindings);
+      });
+    },
+    async replace(sessionKey: string, namespaces: string[]): Promise<void> {
+      const key = encodeSessionKey(sessionKey);
+      await queueFileWrite(filePath, async () => {
+        const bindings = await readBindingFile(filePath);
+        if (namespaces.length === 0) {
+          delete bindings.entries[key];
+        } else {
+          bindings.entries[key] = {
+            namespaces: capNamespaceHistory([...namespaces]),
+            updatedAt: new Date().toISOString(),
+          };
+        }
+        bindings.entries = pruneBindingEntries(bindings.entries, key);
+        await write(filePath, bindings);
+        clearVolatileRefresh(filePath, key);
+      });
+    },
+  };
+}