@remnic/core 9.25.6 → 9.26.0

package/dist/session-namespace-bindings.d.ts

@@ -0,0 +1,27 @@
+import { rename } from 'node:fs/promises';
+
+interface SessionNamespaceBindingStore {
+    namespacesFor(sessionKey: string): Promise<string[]>;
+    remember(sessionKey: string, namespace: string): Promise<void>;
+    replace?(sessionKey: string, namespaces: string[]): Promise<void>;
+}
+declare const SESSION_NAMESPACE_BINDING_MAX_ENTRIES = 1000;
+declare const SESSION_NAMESPACE_BINDING_MAX_NAMESPACES = 64;
+declare const SESSION_NAMESPACE_BINDING_MAX_NAMESPACE_LENGTH = 256;
+declare const SESSION_NAMESPACE_BINDING_MAX_AGE_MS: number;
+interface NamespaceBindingEntry {
+    namespaces: string[];
+    updatedAt: string;
+}
+interface NamespaceBindingFile {
+    version: 1;
+    entries: Record<string, NamespaceBindingEntry>;
+}
+type BindingFileWriter = (filePath: string, bindings: NamespaceBindingFile) => Promise<void>;
+declare function createInMemorySessionNamespaceBindingStore(): SessionNamespaceBindingStore;
+declare function createFileSessionNamespaceBindingStore(filePath: string, options?: {
+    writeBindingFile?: BindingFileWriter;
+    renameBindingFile?: typeof rename;
+}): SessionNamespaceBindingStore;
+
+export { SESSION_NAMESPACE_BINDING_MAX_AGE_MS, SESSION_NAMESPACE_BINDING_MAX_ENTRIES, SESSION_NAMESPACE_BINDING_MAX_NAMESPACES, SESSION_NAMESPACE_BINDING_MAX_NAMESPACE_LENGTH, type SessionNamespaceBindingStore, createFileSessionNamespaceBindingStore, createInMemorySessionNamespaceBindingStore };

package/dist/session-namespace-bindings.js

@@ -0,0 +1,243 @@
+import "./chunk-PZ5AY32C.js";
+
+// src/session-namespace-bindings.ts
+import { randomUUID } from "crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "fs/promises";
+import path from "path";
+var SESSION_NAMESPACE_BINDING_MAX_ENTRIES = 1e3;
+var SESSION_NAMESPACE_BINDING_MAX_NAMESPACES = 64;
+var SESSION_NAMESPACE_BINDING_MAX_NAMESPACE_LENGTH = 256;
+var SESSION_NAMESPACE_BINDING_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
+var fileWriteChains = /* @__PURE__ */ new Map();
+var volatileRefreshes = /* @__PURE__ */ new Map();
+function retainVolatileRefresh(filePath, sessionKey, updatedAt) {
+  const refreshes = volatileRefreshes.get(filePath) ?? /* @__PURE__ */ new Map();
+  refreshes.set(sessionKey, updatedAt);
+  volatileRefreshes.set(filePath, refreshes);
+}
+function clearVolatileRefresh(filePath, sessionKey) {
+  const refreshes = volatileRefreshes.get(filePath);
+  if (refreshes === void 0) return;
+  refreshes.delete(sessionKey);
+  if (refreshes.size === 0) volatileRefreshes.delete(filePath);
+}
+function applyVolatileRefreshes(filePath, entries) {
+  const refreshes = volatileRefreshes.get(filePath);
+  if (refreshes === void 0) return;
+  for (const [key, updatedAt] of refreshes) {
+    const entry = entries[key];
+    if (entry === void 0) {
+      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() {
+  return { version: 1, entries: /* @__PURE__ */ Object.create(null) };
+}
+function capNamespaceHistory(namespaces) {
+  return namespaces.length > SESSION_NAMESPACE_BINDING_MAX_NAMESPACES ? namespaces.slice(-SESSION_NAMESPACE_BINDING_MAX_NAMESPACES) : namespaces;
+}
+function normalizeNamespaces(value) {
+  if (!Array.isArray(value)) return [];
+  const namespaces = [];
+  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, namespace) {
+  const normalized = namespace.trim();
+  return capNamespaceHistory([
+    ...namespaces.filter((candidate) => candidate !== normalized),
+    normalized
+  ]);
+}
+function pruneBindingEntries(entries, protectedKey) {
+  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 = /* @__PURE__ */ Object.create(null);
+  for (const [key, entry] of retained) pruned[key] = entry;
+  return pruned;
+}
+function encodeSessionKey(sessionKey) {
+  return encodeURIComponent(sessionKey);
+}
+async function readBindingFile(filePath) {
+  let raw;
+  try {
+    raw = await readFile(filePath, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") {
+      volatileRefreshes.delete(filePath);
+      return emptyBindingFile();
+    }
+    throw err;
+  }
+  const parsed = JSON.parse(raw);
+  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 = /* @__PURE__ */ Object.create(null);
+  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;
+    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, bindings, renameFile = rename) {
+  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(() => void 0);
+    throw err;
+  }
+}
+async function queueFileWrite(filePath, operation) {
+  const prior = fileWriteChains.get(filePath) ?? Promise.resolve();
+  const run = prior.catch(() => void 0).then(operation);
+  fileWriteChains.set(
+    filePath,
+    run.then(
+      () => void 0,
+      () => void 0
+    )
+  );
+  return run;
+}
+function createInMemorySessionNamespaceBindingStore() {
+  const entries = /* @__PURE__ */ new Map();
+  return {
+    async namespacesFor(sessionKey) {
+      const namespaces = entries.get(sessionKey);
+      if (namespaces === void 0) return [];
+      entries.delete(sessionKey);
+      entries.set(sessionKey, namespaces);
+      return [...namespaces];
+    },
+    async remember(sessionKey, namespace) {
+      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, namespaces) {
+      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);
+      }
+    }
+  };
+}
+function createFileSessionNamespaceBindingStore(filePath, options = {}) {
+  const write = options.writeBindingFile ?? ((targetPath, bindings) => writeBindingFile(targetPath, bindings, options.renameBindingFile));
+  return {
+    async namespacesFor(sessionKey) {
+      const key = encodeSessionKey(sessionKey);
+      return queueFileWrite(filePath, async () => {
+        const bindings = await readBindingFile(filePath);
+        const entry = bindings.entries[key];
+        if (entry === void 0) return [];
+        const namespaces = [...entry.namespaces];
+        const updatedAt = (/* @__PURE__ */ 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, namespace) {
+      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: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        bindings.entries = pruneBindingEntries(bindings.entries, key);
+        await write(filePath, bindings);
+      });
+    },
+    async replace(sessionKey, namespaces) {
+      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: (/* @__PURE__ */ new Date()).toISOString()
+          };
+        }
+        bindings.entries = pruneBindingEntries(bindings.entries, key);
+        await write(filePath, bindings);
+        clearVolatileRefresh(filePath, key);
+      });
+    }
+  };
+}
+export {
+  SESSION_NAMESPACE_BINDING_MAX_AGE_MS,
+  SESSION_NAMESPACE_BINDING_MAX_ENTRIES,
+  SESSION_NAMESPACE_BINDING_MAX_NAMESPACES,
+  SESSION_NAMESPACE_BINDING_MAX_NAMESPACE_LENGTH,
+  createFileSessionNamespaceBindingStore,
+  createInMemorySessionNamespaceBindingStore
+};
+//# sourceMappingURL=session-namespace-bindings.js.map

package/dist/session-namespace-bindings.js.map

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

package/dist/storage.js

@@ -16,14 +16,14 @@ import {
   parseFrontmatter,
   parseFrontmatterStringValue,
   serializeEntityFile
-} from "./chunk-K4DP5KZA.js";
-import "./chunk-2QMKMVHH.js";
+} from "./chunk-UZK7VVPD.js";
 import "./chunk-UHVXE24Y.js";
+import "./chunk-2QMKMVHH.js";
 import "./chunk-DEBHXHJR.js";
 import "./chunk-DNHVPZOD.js";
 import "./chunk-6CIAGZ6X.js";
-import "./chunk-J6A3CX5N.js";
 import "./chunk-HKF5VASQ.js";
+import "./chunk-J6A3CX5N.js";
 import "./chunk-V25OWXAC.js";
 import "./chunk-XKGPIWGI.js";
 import "./chunk-EGGE52UU.js";
@@ -43,12 +43,12 @@ import {
 import "./chunk-BT7NVCML.js";
 import "./chunk-JYIJNNN3.js";
 import "./chunk-AAD2ZS6P.js";
-import "./chunk-W5H6ZRPT.js";
 import "./chunk-5VQJBH2G.js";
 import "./chunk-AITCS2RC.js";
 import "./chunk-XMMESCPD.js";
 import "./chunk-42JKGUFJ.js";
 import "./chunk-PDJTHRAW.js";
+import "./chunk-W5H6ZRPT.js";
 import "./chunk-G7D6GZ5J.js";
 import "./chunk-C23BYTJV.js";
 import "./chunk-QIEUU4UK.js";

package/dist/testing/lifecycle-matrix.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Lifecycle scenario-matrix harness (issue #1993, umbrella #1988 phase 5).
+ *
+ * AGENTS.md mandates a scenario matrix for stateful subsystem changes
+ * (session/retrieval/cache work): the nine canonical rows a reviewer will
+ * otherwise probe by hand — provider identity, sparse metadata ± remembered
+ * binding, provider rebinding, restart/reload recovery, compaction flush,
+ * `before_reset`, `session_end`, and dedupe/replay. Historically that matrix
+ * lived only as prose (see the "Why Stateful PRs Churn" section) and nobody
+ * instantiated it, so PR #1923 burned 53 review threads on exactly those
+ * adjacent invariants.
+ *
+ * This module makes the matrix EXECUTABLE. A subsystem adapter implements
+ * `LifecycleSubject<S>`; `runLifecycleMatrix` registers one named test per
+ * `MATRIX_ROWS` entry. Adding a row here is a one-file change that
+ * automatically extends every adopter — the whole point of the harness.
+ *
+ * Test-support only: this file lives under `src/testing/` and is exported solely
+ * so adapter test subjects can share the canonical matrix across packages.
+ * The registrar loads `node:test` through `createRequire` so the built artifact
+ * keeps the builtin specifier, and runtime code must never import this module.
+ */
+/** The nine canonical AGENTS.md session/retrieval/cache matrix rows. */
+type MatrixRowId = "explicit-provider-identity" | "sparse-metadata-with-binding" | "sparse-metadata-without-binding" | "provider-rebinding" | "restart-reload-recovery" | "compaction-flush" | "before-reset" | "session-end" | "dedupe-replay";
+/**
+ * Typed scenario axes a subject can branch on instead of re-parsing the row
+ * id. These encode the real dimensions the AGENTS.md matrix probes.
+ */
+interface MatrixRowDimensions {
+    /** How the session's provider/identity binding is established. */
+    readonly providerIdentity: "explicit" | "sparse" | "rebound" | "none";
+    /** Whether a previously remembered binding is available to reuse. */
+    readonly rememberedBinding: boolean;
+    /** Whether the scenario exercises a fresh instance over persisted state. */
+    readonly restart: boolean;
+    /** The forced-flush lifecycle transition under test, if any. */
+    readonly flush: "before_reset" | "session_end" | "compaction" | "none";
+    /** Whether the scenario replays/duplicates content through the dedupe path. */
+    readonly dedupeOrReplay: boolean;
+}
+interface MatrixRow {
+    readonly id: MatrixRowId;
+    /** Human-readable row title (matches the AGENTS.md bullet). */
+    readonly title: string;
+    readonly dimensions: MatrixRowDimensions;
+}
+/**
+ * The canonical matrix. Order and membership mirror AGENTS.md
+ * "Minimum scenario matrix for session/retrieval/cache work". Frozen so an
+ * adopter cannot mutate the shared set.
+ */
+declare const MATRIX_ROWS: readonly MatrixRow[];
+/**
+ * A subsystem adapter. Each row runs `setup → exercise → invariants`. `setup`
+ * is transactional — it cleans up its own partial state if it throws — and once
+ * it returns a fixture, `teardown` always runs (even when `exercise` or
+ * `invariants` throws), so a leaked temp dir or orchestrator cannot poison a
+ * sibling row.
+ *
+ * A row a subject cannot honestly realize must NOT be faked: return a skip
+ * reason from `appliesTo` and the harness registers it as an explicit skipped
+ * test (a mock-only pass is a finding about the code, not the harness — #1993).
+ */
+interface LifecycleSubject<S> {
+    /** Build the row-specific fixture; MUST clean up its own partial state if it throws. */
+    setup(row: MatrixRow): Promise<S>;
+    /** Drive the behavior under test. */
+    exercise(subject: S, row: MatrixRow): Promise<void>;
+    /** Row-specific assertions against observable effects. */
+    invariants(subject: S, row: MatrixRow): Promise<void>;
+    /** Always-run cleanup. */
+    teardown(subject: S, row: MatrixRow): Promise<void>;
+    /**
+     * Optional: return a non-empty string to SKIP a row with that reason, or
+     * `false`. Omitted / `true` means the row applies. A skip is honest coverage
+     * documentation, not a silent pass.
+     */
+    appliesTo?(row: MatrixRow): boolean | string;
+}
+/** Minimal test registrar seam (defaults to `node:test`), injectable for self-test. */
+type MatrixTestRegistrar = (name: string, fn: () => void | Promise<void>) => void;
+type MatrixSkipRegistrar = (name: string, reason: string) => void;
+interface RunLifecycleMatrixOptions {
+    /** Override the test registrar (self-test injects a capturing fake). */
+    readonly register?: MatrixTestRegistrar;
+    /** Override the skip registrar. */
+    readonly registerSkipped?: MatrixSkipRegistrar;
+    /** Override the row set (self-test only; production adopters use MATRIX_ROWS). */
+    readonly rows?: readonly MatrixRow[];
+}
+/** Deterministic, greppable test name — the coverage manifest and CI depend on it. */
+declare function lifecycleTestName(subjectName: string, row: MatrixRow): string;
+/**
+ * Register one test per matrix row for `subject`, named with the row identity
+ * so a failing row is unambiguous in CI output. Runs `setup → exercise →
+ * invariants`; `teardown` runs whenever `setup` produced a fixture.
+ */
+declare function runLifecycleMatrix<S>(subjectName: string, subject: LifecycleSubject<S>, options?: RunLifecycleMatrixOptions): void;
+
+export { type LifecycleSubject, MATRIX_ROWS, type MatrixRow, type MatrixRowDimensions, type MatrixRowId, type MatrixSkipRegistrar, type MatrixTestRegistrar, type RunLifecycleMatrixOptions, lifecycleTestName, runLifecycleMatrix };

package/dist/testing/lifecycle-matrix.js

@@ -0,0 +1,149 @@
+import "../chunk-PZ5AY32C.js";
+
+// src/testing/lifecycle-matrix.ts
+import { createRequire } from "module";
+var MATRIX_ROWS = Object.freeze([
+  {
+    id: "explicit-provider-identity",
+    title: "explicit provider identity",
+    dimensions: {
+      providerIdentity: "explicit",
+      rememberedBinding: false,
+      restart: false,
+      flush: "none",
+      dedupeOrReplay: false
+    }
+  },
+  {
+    id: "sparse-metadata-with-binding",
+    title: "sparse metadata with remembered binding",
+    dimensions: {
+      providerIdentity: "sparse",
+      rememberedBinding: true,
+      restart: false,
+      flush: "none",
+      dedupeOrReplay: false
+    }
+  },
+  {
+    id: "sparse-metadata-without-binding",
+    title: "sparse metadata without remembered binding",
+    dimensions: {
+      providerIdentity: "sparse",
+      rememberedBinding: false,
+      restart: false,
+      flush: "none",
+      dedupeOrReplay: false
+    }
+  },
+  {
+    id: "provider-rebinding",
+    title: "provider rebinding",
+    dimensions: {
+      providerIdentity: "rebound",
+      rememberedBinding: true,
+      restart: false,
+      flush: "none",
+      dedupeOrReplay: false
+    }
+  },
+  {
+    id: "restart-reload-recovery",
+    title: "restart/reload recovery",
+    dimensions: {
+      providerIdentity: "explicit",
+      rememberedBinding: true,
+      restart: true,
+      flush: "none",
+      dedupeOrReplay: false
+    }
+  },
+  {
+    id: "compaction-flush",
+    title: "compaction flush",
+    dimensions: {
+      providerIdentity: "explicit",
+      rememberedBinding: false,
+      restart: false,
+      flush: "compaction",
+      dedupeOrReplay: false
+    }
+  },
+  {
+    id: "before-reset",
+    title: "before_reset",
+    dimensions: {
+      providerIdentity: "explicit",
+      rememberedBinding: false,
+      restart: false,
+      flush: "before_reset",
+      dedupeOrReplay: false
+    }
+  },
+  {
+    id: "session-end",
+    title: "session_end",
+    dimensions: {
+      providerIdentity: "explicit",
+      rememberedBinding: false,
+      restart: false,
+      flush: "session_end",
+      dedupeOrReplay: false
+    }
+  },
+  {
+    id: "dedupe-replay",
+    title: "dedupe/replay behavior",
+    dimensions: {
+      providerIdentity: "explicit",
+      rememberedBinding: false,
+      restart: false,
+      flush: "none",
+      dedupeOrReplay: true
+    }
+  }
+]);
+function lifecycleTestName(subjectName, row) {
+  return `lifecycle-matrix[${subjectName}] :: ${row.id} \u2014 ${row.title}`;
+}
+var requiredNodeTest = createRequire(import.meta.url)("node:test");
+var nodeTest = typeof requiredNodeTest === "function" ? requiredNodeTest : requiredNodeTest.test;
+var defaultRegister = (name, fn) => {
+  nodeTest(name, fn);
+};
+var defaultRegisterSkipped = (name, reason) => {
+  nodeTest(name, { skip: reason }, () => {
+  });
+};
+function runLifecycleMatrix(subjectName, subject, options = {}) {
+  const register = options.register ?? defaultRegister;
+  const registerSkipped = options.registerSkipped ?? defaultRegisterSkipped;
+  const rows = options.rows ?? MATRIX_ROWS;
+  for (const row of rows) {
+    const name = lifecycleTestName(subjectName, row);
+    const applicability = subject.appliesTo ? subject.appliesTo(row) : true;
+    if (applicability !== true) {
+      const reason = typeof applicability === "string" && applicability.length > 0 ? applicability : "not applicable to this subsystem";
+      registerSkipped(name, reason);
+      continue;
+    }
+    register(name, async () => {
+      let built;
+      let setupDone = false;
+      try {
+        built = await subject.setup(row);
+        setupDone = true;
+        await subject.exercise(built, row);
+        await subject.invariants(built, row);
+      } finally {
+        if (setupDone) await subject.teardown(built, row);
+      }
+    });
+  }
+}
+export {
+  MATRIX_ROWS,
+  lifecycleTestName,
+  runLifecycleMatrix
+};
+//# sourceMappingURL=lifecycle-matrix.js.map

package/dist/testing/lifecycle-matrix.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/testing/lifecycle-matrix.ts"],"sourcesContent":["/**\n * Lifecycle scenario-matrix harness (issue #1993, umbrella #1988 phase 5).\n *\n * AGENTS.md mandates a scenario matrix for stateful subsystem changes\n * (session/retrieval/cache work): the nine canonical rows a reviewer will\n * otherwise probe by hand — provider identity, sparse metadata ± remembered\n * binding, provider rebinding, restart/reload recovery, compaction flush,\n * `before_reset`, `session_end`, and dedupe/replay. Historically that matrix\n * lived only as prose (see the \"Why Stateful PRs Churn\" section) and nobody\n * instantiated it, so PR #1923 burned 53 review threads on exactly those\n * adjacent invariants.\n *\n * This module makes the matrix EXECUTABLE. A subsystem adapter implements\n * `LifecycleSubject<S>`; `runLifecycleMatrix` registers one named test per\n * `MATRIX_ROWS` entry. Adding a row here is a one-file change that\n * automatically extends every adopter — the whole point of the harness.\n *\n * Test-support only: this file lives under `src/testing/` and is exported solely\n * so adapter test subjects can share the canonical matrix across packages.\n * The registrar loads `node:test` through `createRequire` so the built artifact\n * keeps the builtin specifier, and runtime code must never import this module.\n */\n\nimport { createRequire } from \"node:module\";\n\n/** The nine canonical AGENTS.md session/retrieval/cache matrix rows. */\nexport type MatrixRowId =\n  | \"explicit-provider-identity\"\n  | \"sparse-metadata-with-binding\"\n  | \"sparse-metadata-without-binding\"\n  | \"provider-rebinding\"\n  | \"restart-reload-recovery\"\n  | \"compaction-flush\"\n  | \"before-reset\"\n  | \"session-end\"\n  | \"dedupe-replay\";\n\n/**\n * Typed scenario axes a subject can branch on instead of re-parsing the row\n * id. These encode the real dimensions the AGENTS.md matrix probes.\n */\nexport interface MatrixRowDimensions {\n  /** How the session's provider/identity binding is established. */\n  readonly providerIdentity: \"explicit\" | \"sparse\" | \"rebound\" | \"none\";\n  /** Whether a previously remembered binding is available to reuse. */\n  readonly rememberedBinding: boolean;\n  /** Whether the scenario exercises a fresh instance over persisted state. */\n  readonly restart: boolean;\n  /** The forced-flush lifecycle transition under test, if any. */\n  readonly flush: \"before_reset\" | \"session_end\" | \"compaction\" | \"none\";\n  /** Whether the scenario replays/duplicates content through the dedupe path. */\n  readonly dedupeOrReplay: boolean;\n}\n\nexport interface MatrixRow {\n  readonly id: MatrixRowId;\n  /** Human-readable row title (matches the AGENTS.md bullet). */\n  readonly title: string;\n  readonly dimensions: MatrixRowDimensions;\n}\n\n/**\n * The canonical matrix. Order and membership mirror AGENTS.md\n * \"Minimum scenario matrix for session/retrieval/cache work\". Frozen so an\n * adopter cannot mutate the shared set.\n */\nexport const MATRIX_ROWS: readonly MatrixRow[] = Object.freeze([\n  {\n    id: \"explicit-provider-identity\",\n    title: \"explicit provider identity\",\n    dimensions: {\n      providerIdentity: \"explicit\",\n      rememberedBinding: false,\n      restart: false,\n      flush: \"none\",\n      dedupeOrReplay: false,\n    },\n  },\n  {\n    id: \"sparse-metadata-with-binding\",\n    title: \"sparse metadata with remembered binding\",\n    dimensions: {\n      providerIdentity: \"sparse\",\n      rememberedBinding: true,\n      restart: false,\n      flush: \"none\",\n      dedupeOrReplay: false,\n    },\n  },\n  {\n    id: \"sparse-metadata-without-binding\",\n    title: \"sparse metadata without remembered binding\",\n    dimensions: {\n      providerIdentity: \"sparse\",\n      rememberedBinding: false,\n      restart: false,\n      flush: \"none\",\n      dedupeOrReplay: false,\n    },\n  },\n  {\n    id: \"provider-rebinding\",\n    title: \"provider rebinding\",\n    dimensions: {\n      providerIdentity: \"rebound\",\n      rememberedBinding: true,\n      restart: false,\n      flush: \"none\",\n      dedupeOrReplay: false,\n    },\n  },\n  {\n    id: \"restart-reload-recovery\",\n    title: \"restart/reload recovery\",\n    dimensions: {\n      providerIdentity: \"explicit\",\n      rememberedBinding: true,\n      restart: true,\n      flush: \"none\",\n      dedupeOrReplay: false,\n    },\n  },\n  {\n    id: \"compaction-flush\",\n    title: \"compaction flush\",\n    dimensions: {\n      providerIdentity: \"explicit\",\n      rememberedBinding: false,\n      restart: false,\n      flush: \"compaction\",\n      dedupeOrReplay: false,\n    },\n  },\n  {\n    id: \"before-reset\",\n    title: \"before_reset\",\n    dimensions: {\n      providerIdentity: \"explicit\",\n      rememberedBinding: false,\n      restart: false,\n      flush: \"before_reset\",\n      dedupeOrReplay: false,\n    },\n  },\n  {\n    id: \"session-end\",\n    title: \"session_end\",\n    dimensions: {\n      providerIdentity: \"explicit\",\n      rememberedBinding: false,\n      restart: false,\n      flush: \"session_end\",\n      dedupeOrReplay: false,\n    },\n  },\n  {\n    id: \"dedupe-replay\",\n    title: \"dedupe/replay behavior\",\n    dimensions: {\n      providerIdentity: \"explicit\",\n      rememberedBinding: false,\n      restart: false,\n      flush: \"none\",\n      dedupeOrReplay: true,\n    },\n  },\n] as const);\n\n/**\n * A subsystem adapter. Each row runs `setup → exercise → invariants`. `setup`\n * is transactional — it cleans up its own partial state if it throws — and once\n * it returns a fixture, `teardown` always runs (even when `exercise` or\n * `invariants` throws), so a leaked temp dir or orchestrator cannot poison a\n * sibling row.\n *\n * A row a subject cannot honestly realize must NOT be faked: return a skip\n * reason from `appliesTo` and the harness registers it as an explicit skipped\n * test (a mock-only pass is a finding about the code, not the harness — #1993).\n */\nexport interface LifecycleSubject<S> {\n  /** Build the row-specific fixture; MUST clean up its own partial state if it throws. */\n  setup(row: MatrixRow): Promise<S>;\n  /** Drive the behavior under test. */\n  exercise(subject: S, row: MatrixRow): Promise<void>;\n  /** Row-specific assertions against observable effects. */\n  invariants(subject: S, row: MatrixRow): Promise<void>;\n  /** Always-run cleanup. */\n  teardown(subject: S, row: MatrixRow): Promise<void>;\n  /**\n   * Optional: return a non-empty string to SKIP a row with that reason, or\n   * `false`. Omitted / `true` means the row applies. A skip is honest coverage\n   * documentation, not a silent pass.\n   */\n  appliesTo?(row: MatrixRow): boolean | string;\n}\n\n/** Minimal test registrar seam (defaults to `node:test`), injectable for self-test. */\nexport type MatrixTestRegistrar = (\n  name: string,\n  fn: () => void | Promise<void>,\n) => void;\n\nexport type MatrixSkipRegistrar = (name: string, reason: string) => void;\n\nexport interface RunLifecycleMatrixOptions {\n  /** Override the test registrar (self-test injects a capturing fake). */\n  readonly register?: MatrixTestRegistrar;\n  /** Override the skip registrar. */\n  readonly registerSkipped?: MatrixSkipRegistrar;\n  /** Override the row set (self-test only; production adopters use MATRIX_ROWS). */\n  readonly rows?: readonly MatrixRow[];\n}\n\n/** Deterministic, greppable test name — the coverage manifest and CI depend on it. */\nexport function lifecycleTestName(subjectName: string, row: MatrixRow): string {\n  return `lifecycle-matrix[${subjectName}] :: ${row.id} — ${row.title}`;\n}\ntype NodeTestRegistrar = {\n  (name: string, fn: () => void | Promise<void>): void;\n  (name: string, options: { skip: string }, fn: () => void): void;\n};\n\nconst requiredNodeTest = createRequire(import.meta.url)(\"node:test\") as\n  | NodeTestRegistrar\n  | { test: NodeTestRegistrar };\nconst nodeTest: NodeTestRegistrar =\n  typeof requiredNodeTest === \"function\" ? requiredNodeTest : requiredNodeTest.test;\n\nconst defaultRegister: MatrixTestRegistrar = (name, fn) => {\n  nodeTest(name, fn);\n};\n\nconst defaultRegisterSkipped: MatrixSkipRegistrar = (name, reason) => {\n  nodeTest(name, { skip: reason }, () => {});\n};\n\n/**\n * Register one test per matrix row for `subject`, named with the row identity\n * so a failing row is unambiguous in CI output. Runs `setup → exercise →\n * invariants`; `teardown` runs whenever `setup` produced a fixture.\n */\nexport function runLifecycleMatrix<S>(\n  subjectName: string,\n  subject: LifecycleSubject<S>,\n  options: RunLifecycleMatrixOptions = {},\n): void {\n  const register = options.register ?? defaultRegister;\n  const registerSkipped = options.registerSkipped ?? defaultRegisterSkipped;\n  const rows = options.rows ?? MATRIX_ROWS;\n\n  for (const row of rows) {\n    const name = lifecycleTestName(subjectName, row);\n    const applicability = subject.appliesTo ? subject.appliesTo(row) : true;\n    if (applicability !== true) {\n      const reason =\n        typeof applicability === \"string\" && applicability.length > 0\n          ? applicability\n          : \"not applicable to this subsystem\";\n      registerSkipped(name, reason);\n      continue;\n    }\n\n    register(name, async () => {\n      let built: S | undefined;\n      let setupDone = false;\n      try {\n        built = await subject.setup(row);\n        setupDone = true;\n        await subject.exercise(built, row);\n        await subject.invariants(built, row);\n      } finally {\n        // Teardown runs whenever setup COMPLETED — even when a subject's fixture\n        // type is `void`/undefined — and is skipped only when setup itself threw\n        // (a transactional setup cleans up its own partial state on throw). The\n        // sentinel is a completion flag, NOT the fixture value, so a stateless or\n        // void subject that did setup work is still torn down.\n        if (setupDone) await subject.teardown(built as S, row);\n      }\n    });\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/transfer/backup.js

@@ -1,14 +1,14 @@
 import {
   backupMemoryDir
-} from "../chunk-2NLLXCJG.js";
+} from "../chunk-BXLOS5AJ.js";
 import "../chunk-765K3SAT.js";
-import "../chunk-X7Y7WX73.js";
+import "../chunk-DQEMWVMT.js";
 import "../chunk-J4EB7DNW.js";
-import "../chunk-UI3NYK34.js";
-import "../chunk-GCGJW34D.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";
 import "../chunk-FP2373TW.js";
+import "../chunk-UI3NYK34.js";
+import "../chunk-GCGJW34D.js";
 import "../chunk-A6XUJE5D.js";
 import "../chunk-PZ5AY32C.js";
 export {

package/dist/transfer/capsule-export.js

@@ -1,15 +1,15 @@
 import {
   exportCapsule,
   isValidCapsuleSince
-} from "../chunk-KQAFEZQX.js";
+} from "../chunk-VDX2J7OX.js";
 import "../chunk-WEHSQBFR.js";
-import "../chunk-X7Y7WX73.js";
+import "../chunk-DQEMWVMT.js";
 import "../chunk-J4EB7DNW.js";
-import "../chunk-UI3NYK34.js";
-import "../chunk-GCGJW34D.js";
 import "../chunk-BJMBJZ2Y.js";
 import "../chunk-UKJAGEXH.js";
 import "../chunk-FP2373TW.js";
+import "../chunk-UI3NYK34.js";
+import "../chunk-GCGJW34D.js";
 import "../chunk-A6XUJE5D.js";
 import "../chunk-PZ5AY32C.js";
 export {