@hasna/mementos 0.14.87 → 0.15.2

package/dist/project-registration.js

@@ -72,16 +72,7 @@ function serverDataBackendEnvKeys(name) {
     databaseUrlKeys: [`HASNA_${token}_DATABASE_URL`, `${token}_DATABASE_URL`]
   };
 }
-function legacyModeKeys(name) {
-  const token = envToken(name);
-  return [
-    `HASNA_${token}_STORAGE_MODE`,
-    `HASNA_${token}_MODE`,
-    `${token}_STORAGE_MODE`,
-    `${token}_MODE`
-  ];
-}
-function firstEnv(env, keys) {
+function firstDatabaseUrl(env, keys) {
   for (const key of keys) {
     const value = ownString(env, key)?.trim();
     if (value)
@@ -89,23 +80,8 @@ function firstEnv(env, keys) {
   }
   return null;
 }
-function firstDefinedEnvKey(env, keys) {
-  for (const key of keys) {
-    if (Object.hasOwn(env, key) && env[key] !== undefined)
-      return key;
-  }
-  return null;
-}
-function assertNoLegacyStorageMode(name, env = process.env) {
-  const legacyKey = firstDefinedEnvKey(env, legacyModeKeys(name));
-  if (!legacyKey)
-    return;
-  const canonicalDatabaseUrl = serverDataBackendEnvKeys(name).databaseUrlKeys[0];
-  throw new Error(`${legacyKey} was removed. Delete the storage-mode variable; ` + `set ${canonicalDatabaseUrl} to select the postgresql server backend, ` + `or leave it unset for sqlite.`);
-}
 function resolveServerDataBackend(name, env = process.env) {
-  assertNoLegacyStorageMode(name, env);
-  const databaseUrl = firstEnv(env, serverDataBackendEnvKeys(name).databaseUrlKeys);
+  const databaseUrl = firstDatabaseUrl(env, serverDataBackendEnvKeys(name).databaseUrlKeys);
   if (!databaseUrl) {
     return {
       backend: "sqlite",
@@ -122,41 +98,125 @@ function resolveServerDataBackend(name, env = process.env) {
   };
 }
 function resolveDatabaseUrl(name, env = process.env) {
-  assertNoLegacyStorageMode(name, env);
-  const hit = firstEnv(env, serverDataBackendEnvKeys(name).databaseUrlKeys);
-  return hit?.value ?? null;
+  return firstDatabaseUrl(env, serverDataBackendEnvKeys(name).databaseUrlKeys)?.value ?? null;
 }
 var init_backend = () => {};
 
-// src/lib/retired-storage-mode.ts
-function firstDefinedEnvKey2(env, keys) {
-  for (const key of keys) {
-    if (Object.hasOwn(env, key) && env[key] !== undefined)
-      return key;
+// src/lib/paths.ts
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+import { homedir as pathsResolverHomedir } from "os";
+import { join as pathsResolverJoin } from "path";
+function pathsResolverAssertApp(app) {
+  if (typeof app !== "string" || app.length === 0) {
+    throw new TypeError("paths: app must be a non-empty string");
+  }
+  if (!PATHS_RESOLVER_APP_SLUG_RE.test(app)) {
+    throw new TypeError(`paths: invalid app slug "${app}" \u2014 expected lowercase kebab-case ([a-z0-9]+(-[a-z0-9]+)*)`);
+  }
+}
+function pathsResolverAssertKind(kind) {
+  if (!Object.keys(PATHS_RESOLVER_KIND_ENV).includes(kind)) {
+    throw new TypeError(`paths: invalid path kind "${kind}" \u2014 expected one of ${Object.keys(PATHS_RESOLVER_KIND_ENV).join(", ")}`);
+  }
+}
+function pathsResolverBaseDir(kind, options) {
+  pathsResolverAssertKind(kind);
+  const env = options.env ?? process.env;
+  const override = env[PATHS_RESOLVER_KIND_ENV[kind]];
+  if (typeof override === "string" && override.length > 0)
+    return override;
+  const home = options.home ?? pathsResolverHomedir();
+  const platform = options.platform ?? process.platform;
+  if (platform === "darwin") {
+    switch (kind) {
+      case "data":
+        return pathsResolverJoin(home, "Library", "Application Support", "Hasna");
+      case "cache":
+        return pathsResolverJoin(home, "Library", "Caches", "Hasna");
+      case "state":
+        return pathsResolverJoin(home, "Library", "Logs", "Hasna");
+    }
+  }
+  switch (kind) {
+    case "data":
+      return pathsResolverJoin(home, ".local", "share", "hasna");
+    case "state":
+      return pathsResolverJoin(home, ".local", "state", "hasna");
+    case "cache":
+      return pathsResolverJoin(home, ".cache", "hasna");
   }
-  return null;
 }
-function assertNoLegacyStorageMode2(env = process.env) {
-  const legacyKey = firstDefinedEnvKey2(env, LEGACY_STORAGE_MODE_KEYS);
-  if (!legacyKey)
-    return;
-  throw new Error(`${legacyKey} was removed. Deployment modes no longer exist: delete the storage-mode variable. ` + `The client uses the local SQLite store, or the HTTP API selected by ` + `HASNA_MEMENTOS_API_URL + HASNA_MEMENTOS_API_KEY. ` + `On the server, set HASNA_MEMENTOS_DATABASE_URL to select the postgresql backend, ` + `or leave it unset for sqlite.`);
-}
-var LEGACY_STORAGE_MODE_KEYS;
-var init_retired_storage_mode = __esm(() => {
-  LEGACY_STORAGE_MODE_KEYS = [
-    "HASNA_MEMENTOS_STORAGE_MODE",
-    "HASNA_MEMENTOS_MODE",
-    "MEMENTOS_STORAGE_MODE",
-    "MEMENTOS_MODE"
-  ];
+function pathsResolverResolve(kind, options) {
+  pathsResolverAssertApp(options.app);
+  const appSegment = options.internal === true ? pathsResolverJoin("internal", options.app) : options.app;
+  return pathsResolverJoin(pathsResolverBaseDir(kind, options), appSegment);
+}
+function dataDir(options) {
+  return pathsResolverResolve("data", options);
+}
+function effectiveHome() {
+  return process.env["HOME"] || process.env["USERPROFILE"] || homedir() || "/tmp";
+}
+function legacyDataRoot() {
+  return join(effectiveHome(), ".hasna", "mementos");
+}
+function resolverDataRoot() {
+  return dataDir({
+    app: "mementos",
+    home: process.env["HOME"] || process.env["USERPROFILE"] || undefined
+  });
+}
+function adoptResolverDataRoot(resolved, env = process.env) {
+  const dataOverride = env.HASNA_DATA_HOME;
+  if (typeof dataOverride === "string" && dataOverride.trim().length > 0)
+    return true;
+  return existsSync(join(resolved, "mementos.db"));
+}
+function exactDataRoot() {
+  for (const key of ["HASNA_MEMENTOS_HOME", "MEMENTOS_HOME"]) {
+    const dir = process.env[key]?.trim();
+    if (dir)
+      return resolve(dir);
+  }
+  return;
+}
+function getDataRoot() {
+  const exact = exactDataRoot();
+  if (exact)
+    return exact;
+  const resolved = resolverDataRoot();
+  return adoptResolverDataRoot(resolved) ? resolve(resolved) : resolve(legacyDataRoot());
+}
+var PATHS_RESOLVER_KIND_ENV, PATHS_RESOLVER_APP_SLUG_RE;
+var init_paths = __esm(() => {
+  PATHS_RESOLVER_KIND_ENV = {
+    data: "HASNA_DATA_HOME",
+    state: "HASNA_STATE_HOME",
+    cache: "HASNA_CACHE_HOME"
+  };
+  PATHS_RESOLVER_APP_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+});
+
+// src/lib/env.ts
+var alias = (canonical, legacy) => process.env[canonical] ?? process.env[legacy], env;
+var init_env = __esm(() => {
+  env = {
+    apiKey: () => alias("HASNA_MEMENTOS_API_KEY", "MEMENTOS_API_KEY"),
+    defaultScope: () => alias("HASNA_MEMENTOS_DEFAULT_SCOPE", "MEMENTOS_DEFAULT_SCOPE"),
+    defaultCategory: () => alias("HASNA_MEMENTOS_DEFAULT_CATEGORY", "MEMENTOS_DEFAULT_CATEGORY"),
+    defaultImportance: () => alias("HASNA_MEMENTOS_DEFAULT_IMPORTANCE", "MEMENTOS_DEFAULT_IMPORTANCE"),
+    pgsyncQueryTimeoutMs: () => alias("HASNA_MEMENTOS_PGSYNC_QUERY_TIMEOUT_MS", "MEMENTOS_PGSYNC_QUERY_TIMEOUT_MS"),
+    reflectProvider: () => alias("HASNA_MEMENTOS_REFLECT_PROVIDER", "MEMENTOS_REFLECT_PROVIDER"),
+    reflectModel: () => alias("HASNA_MEMENTOS_REFLECT_MODEL", "MEMENTOS_REFLECT_MODEL")
+  };
 });
 
 // src/storage.ts
 import { Database } from "bun:sqlite";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { homedir } from "os";
-import { join } from "path";
+import { existsSync as existsSync2, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join as join2 } from "path";
 import { fileURLToPath } from "url";
 import { Worker } from "worker_threads";
 import pg from "pg";
@@ -181,6 +241,7 @@ class SqliteAdapter {
   db;
   constructor(path) {
     this.db = new Database(path, { create: true });
+    this.db.exec("PRAGMA busy_timeout = 5000");
     this.db.exec("PRAGMA journal_mode = WAL");
     this.db.exec("PRAGMA foreign_keys = ON");
   }
@@ -415,7 +476,7 @@ function readEnv(name) {
   return value ? value : null;
 }
 function readConfigFile() {
-  if (!existsSync(STORAGE_CONFIG_PATH)) {
+  if (!existsSync2(STORAGE_CONFIG_PATH)) {
     return {};
   }
   try {
@@ -431,9 +492,9 @@ function getConfigPath() {
   return STORAGE_CONFIG_PATH;
 }
 function getStorageDatabaseEnv() {
-  for (const env of DATABASE_ENV_NAMES) {
-    if (readEnv(env.name))
-      return env;
+  for (const env2 of DATABASE_ENV_NAMES) {
+    if (readEnv(env2.name))
+      return env2;
   }
   return null;
 }
@@ -443,20 +504,19 @@ function getStorageEnvName(key) {
   return readEnv(canonical) || !readEnv(fallback) ? canonical : fallback;
 }
 function getStorageDatabaseUrl() {
-  const env = getStorageDatabaseEnv();
-  return env ? readEnv(env.name) : null;
+  const env2 = getStorageDatabaseEnv();
+  return env2 ? readEnv(env2.name) : null;
 }
 function getStorageDatabaseEnvName() {
   return getStorageEnvName("databaseUrl");
 }
-function getStorageBackend(env = process.env) {
-  return resolveServerDataBackend("mementos", env).backend;
+function getStorageBackend(env2 = process.env) {
+  return resolveServerDataBackend("mementos", env2).backend;
 }
-function getStorageBackendDatabaseUrl(env = process.env) {
-  return resolveDatabaseUrl("mementos", env);
+function getStorageBackendDatabaseUrl(env2 = process.env) {
+  return resolveDatabaseUrl("mementos", env2);
 }
 function getStorageConfig() {
-  assertNoLegacyStorageMode2();
   const fileConfig = readConfigFile();
   const merged = {
     ...DEFAULT_STORAGE_CONFIG,
@@ -543,14 +603,14 @@ function storageEnvStatus(key) {
   };
 }
 function postgresBackendStatus(config) {
-  const env = getStorageDatabaseEnv();
-  const envUrl = env ? readEnv(env.name) : null;
-  if (env && envUrl) {
+  const env2 = getStorageDatabaseEnv();
+  const envUrl = env2 ? readEnv(env2.name) : null;
+  if (env2 && envUrl) {
     const validation = validatePostgresConnectionString(envUrl);
     return {
       configured: validation.ok,
       source: "env",
-      env_name: env.name,
+      env_name: env2.name,
       redacted_url: validation.redacted_url,
       missing: [],
       issues: validation.issues,
@@ -596,7 +656,6 @@ function getSafeStorageConfigSummary(config = getStorageConfig()) {
   };
 }
 function getStorageStatus() {
-  assertNoLegacyStorageMode2();
   const config = getStorageConfig();
   const backend = getStorageBackend();
   const postgresRequested = backend === "postgresql";
@@ -677,11 +736,7 @@ function saveStorageConfig(config) {
 function getConfiguredConnectionString() {
   return getStorageDatabaseUrl() ?? undefined;
 }
-function getStorageConnectionString(dbName = "mementos") {
-  assertNoLegacyStorageMode2();
-  if (!isServerContext()) {
-    throw new Error("Refusing to construct an RDS Postgres DSN outside the mementos-serve server. " + "The raw database DSN is NEVER distributed to client machines. " + "Clients must use the HTTP API: set HASNA_MEMENTOS_API_URL and " + "HASNA_MEMENTOS_API_KEY (and unset HASNA_MEMENTOS_DATABASE_URL).");
-  }
+function resolveConfiguredConnectionString(dbName) {
   const envConnectionString = getConfiguredConnectionString();
   if (envConnectionString) {
     const validation = validatePostgresConnectionString(envConnectionString);
@@ -700,7 +755,7 @@ function getStorageConnectionString(dbName = "mementos") {
     missing.push("storage.rds.username");
   }
   if (missing.length > 0) {
-    throw new Error(`Remote storage database is not configured. Missing ${missing.join(", ")}. Set HASNA_MEMENTOS_DATABASE_URL or configure ~/.hasna/mementos/storage/config.json.`);
+    throw new Error(`Remote storage database is not configured. Missing ${missing.join(", ")}. Set HASNA_MEMENTOS_DATABASE_URL or configure ${STORAGE_CONFIG_PATH}.`);
   }
   const password = process.env[password_env];
   if (!password) {
@@ -709,6 +764,15 @@ function getStorageConnectionString(dbName = "mementos") {
   const sslParam = ssl ? "?sslmode=require" : "";
   return `postgres://${username}:${encodeURIComponent(password)}@${host}:${port}/${dbName}${sslParam}`;
 }
+function getStorageConnectionString(dbName = "mementos") {
+  if (!isServerContext()) {
+    throw new Error("Refusing to construct an RDS Postgres DSN outside the mementos-serve server. " + "The raw database DSN is NEVER distributed to client machines. " + "Clients must use the HTTP API: set HASNA_MEMENTOS_API_URL and " + "HASNA_MEMENTOS_API_KEY (and unset HASNA_MEMENTOS_DATABASE_URL).");
+  }
+  return resolveConfiguredConnectionString(dbName);
+}
+function getStorageConnectionStringForOperator(dbName = "mementos") {
+  return resolveConfiguredConnectionString(dbName);
+}
 function isSyncExcludedTable(table) {
   return SYNC_EXCLUDED_TABLE_PATTERNS.some((pattern) => pattern.test(table));
 }
@@ -877,7 +941,8 @@ CREATE TABLE IF NOT EXISTS _sync_meta (
 )`;
 var init_storage = __esm(() => {
   init_backend();
-  init_retired_storage_mode();
+  init_paths();
+  init_env();
   PgSyncPool = class PgSyncPool {
     worker;
     status;
@@ -887,7 +952,7 @@ var init_storage = __esm(() => {
     generation = 0;
     static DATA_BYTES = 128 * 1024 * 1024;
     static queryTimeoutMs() {
-      const raw = process.env["MEMENTOS_PGSYNC_QUERY_TIMEOUT_MS"]?.trim();
+      const raw = env.pgsyncQueryTimeoutMs()?.trim();
       const parsed = raw ? Number(raw) : Number.NaN;
       return Number.isFinite(parsed) && parsed > 0 ? parsed : 60000;
     }
@@ -895,12 +960,12 @@ var init_storage = __esm(() => {
       const ext = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
       const here = fileURLToPath(new URL(".", import.meta.url));
       const candidates = [
-        join(here, `pg-sync-worker${ext}`),
-        join(here, "..", `pg-sync-worker${ext}`),
-        join(here, "..", "..", `pg-sync-worker${ext}`)
+        join2(here, `pg-sync-worker${ext}`),
+        join2(here, "..", `pg-sync-worker${ext}`),
+        join2(here, "..", "..", `pg-sync-worker${ext}`)
       ];
       for (const candidate of candidates) {
-        if (existsSync(candidate))
+        if (existsSync2(candidate))
           return candidate;
       }
       return candidates[0];
@@ -988,7 +1053,7 @@ var init_storage = __esm(() => {
   MEMENTOS_STORAGE_FALLBACK_ENV = {
     databaseUrl: "MEMENTOS_DATABASE_URL"
   };
-  LOCAL_DATA_DIR = join(homedir(), ".hasna", "mementos");
+  LOCAL_DATA_DIR = getDataRoot();
   DEFAULT_STORAGE_CONFIG = {
     rds: {
       host: "",
@@ -1003,8 +1068,8 @@ var init_storage = __esm(() => {
       schedule_minutes: 0
     }
   };
-  STORAGE_CONFIG_DIR = join(LOCAL_DATA_DIR, "storage");
-  STORAGE_CONFIG_PATH = join(STORAGE_CONFIG_DIR, "config.json");
+  STORAGE_CONFIG_DIR = join2(LOCAL_DATA_DIR, "storage");
+  STORAGE_CONFIG_PATH = join2(STORAGE_CONFIG_DIR, "config.json");
   DATABASE_ENV_NAMES = [
     { name: MEMENTOS_STORAGE_ENV.databaseUrl, deprecated: false },
     { name: MEMENTOS_STORAGE_FALLBACK_ENV.databaseUrl, deprecated: false }
@@ -1028,28 +1093,96 @@ var init_storage = __esm(() => {
   ];
 });
 
+// src/lib/local-opt-in.ts
+import {
+  clientTransportEnvKeys,
+  credentialOverrideEnvKey,
+  credentialPointerEnvKey,
+  CREDENTIAL_PROFILE_ENV_KEY
+} from "@hasna/contracts/client";
+function isMementosLocalOptIn(env2 = process.env) {
+  return MEMENTOS_LOCAL_OPT_IN_ENV_KEYS.some((key) => (env2[key] ?? "").trim() !== "");
+}
+function hasExplicitLocalDbPath(env2 = process.env) {
+  return MEMENTOS_DB_PATH_ENV_KEYS.some((key) => (env2[key] ?? "").trim() !== "");
+}
+function mementosAuthorityEnvKeys() {
+  const keys = clientTransportEnvKeys("mementos");
+  return [
+    ...keys.apiUrlKeys,
+    ...keys.apiKeyKeys,
+    credentialOverrideEnvKey("mementos"),
+    credentialPointerEnvKey("mementos"),
+    CREDENTIAL_PROFILE_ENV_KEY
+  ];
+}
+function hasMementosEnvAuthorityIntent(env2 = process.env) {
+  return mementosAuthorityEnvKeys().some((key) => (env2[key] ?? "").trim() !== "");
+}
+function selectsMementosLocalStore(env2 = process.env) {
+  if (hasExplicitLocalDbPath(env2))
+    return true;
+  return !hasMementosEnvAuthorityIntent(env2) && isMementosLocalOptIn(env2);
+}
+function mementosResolverEnv(env2) {
+  const blanks = mementosAuthorityEnvKeys().filter((key) => (key in env2) && (env2[key] ?? "").trim() === "");
+  if (blanks.length === 0)
+    return env2;
+  const next = { ...env2 };
+  for (const key of blanks)
+    delete next[key];
+  return next;
+}
+function isAmbientMementosEnv(env2) {
+  if (typeof process !== "undefined" && env2 === process.env)
+    return true;
+  return env2[CONTRACTS_AMBIENT_ENVIRONMENT] === true;
+}
+function mementosResolverInputs(env2, credentials = {}) {
+  const normalised = mementosResolverEnv(env2);
+  if (normalised === env2)
+    return { env: normalised, credentials };
+  const keychain = { ...credentials.keychain };
+  if (keychain.enabled === undefined && keychain.run === undefined) {
+    keychain.enabled = isAmbientMementosEnv(env2);
+  }
+  return { env: normalised, credentials: { ...credentials, keychain } };
+}
+var MEMENTOS_LOCAL_OPT_IN_ENV_KEYS, MEMENTOS_DB_PATH_ENV_KEYS, CONTRACTS_AMBIENT_ENVIRONMENT;
+var init_local_opt_in = __esm(() => {
+  MEMENTOS_LOCAL_OPT_IN_ENV_KEYS = ["HASNA_MEMENTOS_LOCAL", "MEMENTOS_LOCAL"];
+  MEMENTOS_DB_PATH_ENV_KEYS = ["HASNA_MEMENTOS_DB_PATH", "MEMENTOS_DB_PATH"];
+  CONTRACTS_AMBIENT_ENVIRONMENT = Symbol.for("hasna:contracts:ambientClientEnvironment");
+});
+
 // src/db/api-mode.ts
 import { tmpdir } from "os";
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 import { writeFileSync as writeFileSync2, unlinkSync } from "fs";
 import { randomUUID } from "crypto";
-function firstEnv2(keys) {
+import {
+  clientTransportEnvKeys as clientTransportEnvKeys2,
+  resolveClientTransport,
+  resolveCredential,
+  toV1BaseUrl,
+  ClientTransportConfigurationError
+} from "@hasna/contracts/client";
+function firstEnv(keys, env2 = process.env) {
   for (const k of keys) {
-    const v = process.env[k]?.trim();
+    const v = env2[k]?.trim();
     if (v)
       return v;
   }
   return;
 }
-function firstEnvKey(keys) {
-  for (const k of keys) {
-    if (process.env[k]?.trim())
-      return k;
-  }
-  return null;
+function hasDatabaseUrl(env2 = process.env) {
+  return Boolean(firstEnv(DATABASE_URL_ENV_KEYS, env2));
 }
-function hasDatabaseUrl() {
-  return Boolean(firstEnv2(DATABASE_URL_ENV_KEYS));
+function assertCleanResolvedBase(baseUrl) {
+  if (/[?#]/.test(baseUrl)) {
+    throw new Error("mementos base URL must not contain userinfo, query, or fragment data");
+  }
+  return baseUrl;
 }
 function isLoopbackHost(rawHost) {
   const host = rawHost.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
@@ -1070,50 +1203,61 @@ function assertRequestAllowedUnderTest(baseUrl) {
     return;
   throw new Error("api-mode: REFUSING to make a cloud request from a test process \u2014 this would write to or read " + "from the SHARED PRODUCTION memory store, where test fixtures are indistinguishable from real " + `memories.
 ` + `  host           : ${host || "(unparseable base URL)"}
-` + `  how this happens: a selector set at module scope (after the bun test preload ran), or \`bun test\` ` + `invoked from a directory with no bunfig.toml so the preload never loaded.
+` + "  how this happens: a selector set at module scope (after the bun test preload ran), or `bun test` " + `invoked from a directory with no bunfig.toml so the preload never loaded.
 ` + "  fix            : build the child/process env via src/test-support/store-isolation.ts, or point the " + `suite at a loopback stub.
 ` + `  override       : set ${ALLOW_REMOTE_API_IN_TESTS_ENV}=1 only for a test that must reach a remote endpoint.`);
 }
-function normalizeBase(raw) {
-  let base = raw.trim().replace(/\/+$/, "");
-  if (/\/(v1|api)$/.test(base))
-    return base;
-  return `${base}/v1`;
-}
-function assertUnambiguousStoreEnv(env = process.env) {
-  assertNoLegacyStorageMode2(env);
-  if (firstEnvKey(DB_PATH_ENV_KEYS))
-    return;
-  if (hasDatabaseUrl())
-    return;
-  const urlKey = firstEnvKey(API_URL_ENV_KEYS);
-  const keyKey = firstEnvKey(API_KEY_ENV_KEYS);
-  if (urlKey && !keyKey) {
-    throw new MementosStoreConfigError(`${urlKey} points at the cloud memory store but ${API_KEY_ENV_KEYS[0]} is not set. ` + `Refusing to serve the on-box SQLite store in its place, because it holds a different ` + `dataset. Set ${API_KEY_ENV_KEYS[0]} to reach the cloud store. If you meant to use the ` + `on-box SQLite store, unset ${urlKey} or set ${DB_PATH_ENV_KEYS[0]} explicitly.`);
-  }
-  if (keyKey && !urlKey) {
-    throw new MementosStoreConfigError(`${keyKey} is set but ${API_URL_ENV_KEYS[0]} is not, so the cloud memory store cannot be ` + `reached. Refusing to serve the on-box SQLite store in its place, because it holds a ` + `different dataset. Set ${API_URL_ENV_KEYS[0]} to reach the cloud store. If you meant to ` + `use the on-box SQLite store, unset ${keyKey} or set ${DB_PATH_ENV_KEYS[0]} explicitly.`);
-  }
+function toStoreConfigError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return new MementosStoreConfigError(`${message} Local SQLite is opt-in only (${DB_PATH_ENV_KEYS[0]}, or ${MEMENTOS_LOCAL_OPT_IN_ENV_KEYS[0]} = 1) and is disabled by default \u2014 failing closed`);
 }
-function getApiConfig() {
-  assertUnambiguousStoreEnv();
-  if (firstEnvKey(DB_PATH_ENV_KEYS))
+function getApiConfig(env2 = process.env, options = {}) {
+  if (hasDatabaseUrl(env2))
     return null;
-  const rawBase = firstEnv2(API_URL_ENV_KEYS);
-  const apiKey = firstEnv2(API_KEY_ENV_KEYS);
-  if (!rawBase || !apiKey)
+  if (selectsMementosLocalStore(env2))
     return null;
-  return { baseUrl: normalizeBase(rawBase), apiKey };
+  const inputs = mementosResolverInputs(env2, options.credentials);
+  let credential;
+  try {
+    credential = resolveCredential("mementos", inputs.env, inputs.credentials);
+  } catch (error) {
+    throw toStoreConfigError(error);
+  }
+  let resolution;
+  try {
+    resolution = resolveClientTransport("mementos", inputs.env, {
+      credentials: credential ? { ...inputs.credentials, apiKey: credential.apiKey } : inputs.credentials
+    });
+  } catch (error) {
+    if (error instanceof ClientTransportConfigurationError && credential === null && /is not set and no API key could be resolved/.test(error.message)) {
+      return null;
+    }
+    throw toStoreConfigError(error);
+  }
+  return { baseUrl: assertCleanResolvedBase(resolution.baseUrl), apiKey: credential.apiKey };
 }
 function isApiMode() {
   if (hasDatabaseUrl())
     return false;
   return getApiConfig() !== null;
 }
+function assertClientStoreConfigured(env2 = process.env, options = {}) {
+  if (selectsMementosLocalStore(env2))
+    return;
+  if (hasDatabaseUrl(env2))
+    return;
+  const config = getApiConfig(env2, options);
+  if (config !== null)
+    return;
+  throw new MementosStoreConfigError(unconfiguredStoreMessage());
+}
+function unconfiguredStoreMessage() {
+  return "mementos is not configured to reach any memory store, and will NOT fall back to the " + "on-box SQLite store (~/.hasna/mementos/mementos.db). " + "No credential could be resolved from the Keychain item hasna.credentials.mementos.api-key " + "(macOS only), ~/.hasna/mementos/config/credentials, or " + `${API_KEY_ENV_KEYS[0]}; the authority would be the fleet gateway ${"https://api.hasna.com/mementos"} ` + `(or ${API_URL_ENV_KEYS[0]} if set). ` + `Set ${API_URL_ENV_KEYS[0]} and ${API_KEY_ENV_KEYS[0]} (the resolver also accepts the legacy ` + `${API_URL_ENV_KEYS[1]} / ${API_KEY_ENV_KEYS[1]} aliases for one release) to use the fleet memory ` + `API, or opt into an explicit local SQLite file with ${DB_PATH_ENV_KEYS[0]} / ` + `${DB_PATH_ENV_KEYS[1]} (or ${MEMENTOS_LOCAL_OPT_IN_ENV_KEYS[0]}=1).`;
+}
 function apiRequestRaw(method, path, body) {
   const cfg = getApiConfig();
   if (!cfg)
-    throw new Error("api-mode: not configured (HASNA_MEMENTOS_API_URL / HASNA_MEMENTOS_API_KEY)");
+    throw new Error("api-mode: not configured (no Hasna mementos credential resolved)");
   assertRequestAllowedUnderTest(cfg.baseUrl);
   const url = `${cfg.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
   const hasBody = body !== undefined && body !== null;
@@ -1140,7 +1284,7 @@ x-api-key: ${cfg.apiKey}
   ];
   let bodyFile;
   if (hasBody) {
-    bodyFile = join2(tmpdir(), `mem-req-${process.pid}-${randomUUID()}.json`);
+    bodyFile = join3(tmpdir(), `mem-req-${process.pid}-${randomUUID()}.json`);
     writeFileSync2(bodyFile, JSON.stringify(body), { mode: 384 });
     args.push("--data-binary", `@${bodyFile}`);
   }
@@ -1228,13 +1372,13 @@ function toQuery(params) {
   const s = sp.toString();
   return s ? `?${s}` : "";
 }
-var API_URL_ENV_KEYS, API_KEY_ENV_KEYS, DATABASE_URL_ENV_KEYS, ALLOW_REMOTE_API_IN_TESTS_ENV = "MEMENTOS_ALLOW_REMOTE_API_IN_TESTS", DB_PATH_ENV_KEYS, MementosStoreConfigError, ApiRequestError, DEFAULT_TIMEOUT_S = "45";
+var API_URL_ENV_KEYS, API_KEY_ENV_KEYS, DATABASE_URL_ENV_KEYS, DB_PATH_ENV_KEYS, ALLOW_REMOTE_API_IN_TESTS_ENV = "MEMENTOS_ALLOW_REMOTE_API_IN_TESTS", MementosStoreConfigError, ApiRequestError, DEFAULT_TIMEOUT_S = "45";
 var init_api_mode = __esm(() => {
-  init_retired_storage_mode();
-  API_URL_ENV_KEYS = ["HASNA_MEMENTOS_API_URL", "MEMENTOS_API_URL"];
-  API_KEY_ENV_KEYS = ["HASNA_MEMENTOS_API_KEY", "MEMENTOS_API_KEY"];
+  init_local_opt_in();
+  API_URL_ENV_KEYS = clientTransportEnvKeys2("mementos").apiUrlKeys;
+  API_KEY_ENV_KEYS = clientTransportEnvKeys2("mementos").apiKeyKeys;
   DATABASE_URL_ENV_KEYS = ["HASNA_MEMENTOS_DATABASE_URL", "MEMENTOS_DATABASE_URL"];
-  DB_PATH_ENV_KEYS = ["HASNA_MEMENTOS_DB_PATH", "MEMENTOS_DB_PATH"];
+  DB_PATH_ENV_KEYS = MEMENTOS_DB_PATH_ENV_KEYS;
   MementosStoreConfigError = class MementosStoreConfigError extends Error {
     code = "MEMENTOS_STORE_CONFIG";
     constructor(message) {
@@ -2660,18 +2804,18 @@ __export(exports_database, {
   escapeLikePrefix: () => escapeLikePrefix,
   closeDatabase: () => closeDatabase
 });
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, cpSync } from "fs";
-import { dirname, join as join3, resolve } from "path";
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, cpSync } from "fs";
+import { dirname, join as join4, resolve as resolve2 } from "path";
 function isInMemoryDb(path) {
   return path === ":memory:" || path.startsWith("file::memory:");
 }
 function findNearestMementosDb(startDir) {
-  let dir = resolve(startDir);
+  let dir = resolve2(startDir);
   const home = process.env["HOME"] || process.env["USERPROFILE"] || "~";
-  const legacyHomeDb = resolve(home, ".mementos", "mementos.db");
+  const legacyHomeDb = resolve2(home, ".mementos", "mementos.db");
   while (true) {
-    const candidate = join3(dir, ".mementos", "mementos.db");
-    if (existsSync2(candidate) && resolve(candidate) !== legacyHomeDb)
+    const candidate = join4(dir, ".mementos", "mementos.db");
+    if (existsSync3(candidate) && resolve2(candidate) !== legacyHomeDb)
       return candidate;
     const parent = dirname(dir);
     if (parent === dir)
@@ -2681,9 +2825,9 @@ function findNearestMementosDb(startDir) {
   return null;
 }
 function findGitRoot(startDir) {
-  let dir = resolve(startDir);
+  let dir = resolve2(startDir);
   while (true) {
-    if (existsSync2(join3(dir, ".git")))
+    if (existsSync3(join4(dir, ".git")))
       return dir;
     const parent = dirname(dir);
     if (parent === dir)
@@ -2693,11 +2837,13 @@ function findGitRoot(startDir) {
   return null;
 }
 function migrateGlobalDir() {
+  if (!selectsMementosLocalStore())
+    return;
   const home = process.env["HOME"] || process.env["USERPROFILE"] || "~";
-  const newDir = join3(home, ".hasna", "mementos");
-  const oldDir = join3(home, ".mementos");
-  if (!existsSync2(newDir) && existsSync2(oldDir)) {
-    mkdirSync2(join3(home, ".hasna"), { recursive: true });
+  const newDir = getDataRoot();
+  const oldDir = join4(home, ".mementos");
+  if (!existsSync3(newDir) && existsSync3(oldDir)) {
+    mkdirSync2(dirname(newDir), { recursive: true });
     cpSync(oldDir, newDir, { recursive: true });
   }
 }
@@ -2714,18 +2860,17 @@ function getDbPath() {
   if (process.env["MEMENTOS_DB_SCOPE"] === "project") {
     const gitRoot = findGitRoot(cwd);
     if (gitRoot) {
-      return join3(gitRoot, ".mementos", "mementos.db");
+      return join4(gitRoot, ".mementos", "mementos.db");
     }
   }
   migrateGlobalDir();
-  const home = process.env["HOME"] || process.env["USERPROFILE"] || "~";
-  return join3(home, ".hasna", "mementos", "mementos.db");
+  return join4(getDataRoot(), "mementos.db");
 }
 function ensureDir(filePath) {
   if (isInMemoryDb(filePath))
     return;
-  const dir = dirname(resolve(filePath));
-  if (!existsSync2(dir)) {
+  const dir = dirname(resolve2(filePath));
+  if (!existsSync3(dir)) {
     mkdirSync2(dir, { recursive: true });
   }
 }
@@ -2755,6 +2900,9 @@ function getDatabase(dbPath) {
         throw new Error("REFUSING-UNPINNED-TEST-OPEN: a test process tried to open the default local " + `SQLite store (${getDbPath()}) with no explicit dbPath argument and no ` + `${DB_PATH_ENV_KEYS.join("/")} set. Pass an explicit dbPath (e.g. ":memory:" ` + "or a scratch file), or set one of those env keys to a scratch path, before " + "calling getDatabase(). This guard exists because an unpinned test process " + "would otherwise silently read and write the real, shared, on-disk memory " + "store (todos 57b8b8c5).");
       }
     }
+    if (process.env["NODE_ENV"] !== "test" && !isServerContext()) {
+      assertClientStoreConfigured();
+    }
   }
   const path = dbPath || getDbPath();
   if (_db) {
@@ -2767,7 +2915,6 @@ function getDatabase(dbPath) {
   ensureDir(path);
   _db = new SqliteAdapter(path);
   _db.run("PRAGMA journal_mode = WAL");
-  _db.run("PRAGMA busy_timeout = 5000");
   _db.run("PRAGMA foreign_keys = ON");
   _db.run("PRAGMA wal_autocheckpoint = 100");
   runMigrations(_db);
@@ -2863,6 +3010,8 @@ var init_database = __esm(() => {
   init_storage();
   init_api_mode();
   init_migrations();
+  init_paths();
+  init_local_opt_in();
   ALLOWED_TABLES = new Set([
     "memories",
     "agents",
@@ -2882,7 +3031,7 @@ var init_database = __esm(() => {
 
 // src/project-registration/authority.ts
 import { createHash as createHash2 } from "crypto";
-import { resolve as resolve2 } from "path";
+import { resolve as resolve3 } from "path";
 
 // src/db/projects.ts
 init_database();
@@ -2891,13 +3040,13 @@ import { createHash } from "crypto";
 
 // src/lib/package-version.ts
 import { readFileSync as readFileSync2 } from "fs";
-import { dirname as dirname2, join as join4 } from "path";
+import { dirname as dirname2, join as join5 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function getMementosPackageVersion() {
   const here = dirname2(fileURLToPath2(import.meta.url));
   for (const candidate of [
-    join4(here, "..", "..", "package.json"),
-    join4(here, "..", "package.json")
+    join5(here, "..", "..", "package.json"),
+    join5(here, "..", "package.json")
   ]) {
     try {
       const parsed = JSON.parse(readFileSync2(candidate, "utf8"));
@@ -3750,7 +3899,7 @@ function ownedPath(target) {
   }
   const path = target.withOwnedPath((value) => value);
   requireString(path, "target path", { max: 4096 });
-  if (path !== resolve2(path)) {
+  if (path !== resolve3(path)) {
     throw new MementosProjectRegistrationError("MEMENTOS_PROJECT_REGISTRATION_INVALID_INPUT", "target path must already be canonical and absolute");
   }
   return path;
@@ -5084,6 +5233,17 @@ var SECRET_PATTERNS = [
   { name: "jwt", pattern: /eyJ[a-zA-Z0-9_-]{10,}\.eyJ[a-zA-Z0-9_-]{10,}\.[a-zA-Z0-9_-]{10,}/g },
   { name: "hex_secret", pattern: /(?<=(?:key|token|secret|password|hash)\s*[:=]\s*["']?)[0-9a-f]{32,}(?=["']?)/gi }
 ];
+var KEY_TAG_SECRET_PATTERNS = SECRET_PATTERNS.filter((p) => new Set([
+  "openai_key",
+  "anthropic_key",
+  "aws_key",
+  "github_token",
+  "github_oauth",
+  "npm_token",
+  "stripe_key",
+  "slack_token",
+  "jwt"
+]).has(p.name));
 function redactSecrets(text) {
   let result = text;
   for (const { pattern } of SECRET_PATTERNS) {
@@ -5092,6 +5252,14 @@ function redactSecrets(text) {
   }
   return result;
 }
+function redactCredentialKey(text) {
+  let result = text;
+  for (const { pattern } of KEY_TAG_SECRET_PATTERNS) {
+    pattern.lastIndex = 0;
+    result = result.replace(pattern, REDACTED);
+  }
+  return result;
+}
 function containsSecrets(text) {
   for (const { pattern } of SECRET_PATTERNS) {
     pattern.lastIndex = 0;
@@ -5100,6 +5268,40 @@ function containsSecrets(text) {
   }
   return false;
 }
+function redactValueTree(value) {
+  if (typeof value === "string")
+    return redactSecrets(value);
+  if (Array.isArray(value))
+    return value.map(redactValueTree);
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = redactValueTree(v);
+    }
+    return out;
+  }
+  return value;
+}
+function redactMemoryWriteInput(input) {
+  const out = { ...input };
+  if (typeof out.key === "string")
+    out.key = redactCredentialKey(out.key);
+  if (typeof out.value === "string")
+    out.value = redactSecrets(out.value);
+  if (out.summary !== undefined && out.summary !== null) {
+    out.summary = redactSecrets(String(out.summary));
+  }
+  if (Array.isArray(out.tags)) {
+    out.tags = out.tags.map((t) => redactCredentialKey(String(t)));
+  }
+  if (typeof out.when_to_use === "string") {
+    out.when_to_use = redactSecrets(out.when_to_use);
+  }
+  if (out.metadata !== undefined) {
+    out.metadata = redactValueTree(out.metadata);
+  }
+  return out;
+}
 
 // src/lib/hooks.ts
 var _idCounter = 0;
@@ -5412,6 +5614,7 @@ function createMemory(input, dedupeMode = "merge", db) {
   if (reservedViolation) {
     throw new Error(reservedViolation);
   }
+  input = redactMemoryWriteInput(input);
   if (!db && isApiMode()) {
     const { status, data } = apiJson("POST", "/memories", { ...input, dedupe: dedupeMode });
     if (!data || !data.id) {
@@ -5443,12 +5646,22 @@ function createMemory(input, dedupeMode = "merge", db) {
   const effectiveMode = dedupeMode === "overwrite" ? "merge" : dedupeMode === "version-fork" ? "create" : dedupeMode;
   if (effectiveMode === "error") {
     const existing = d.query(`SELECT id, agent_id, updated_at FROM memories
-       WHERE key = ? AND scope = ? AND COALESCE(project_id, '') = ? AND status = 'active'
+       WHERE key = ? AND scope = ? AND COALESCE(project_id, '') = ?
        LIMIT 1`).get(input.key, input.scope || "private", input.project_id || "");
     if (existing) {
       throw new MemoryConflictError(input.key, existing);
     }
   }
+  if (effectiveMode === "create") {
+    const existing = d.query(`SELECT id, agent_id, updated_at FROM memories
+       WHERE key = ? AND scope = ?
+         AND COALESCE(agent_id, '') = ?
+         AND COALESCE(project_id, '') = ?
+         AND COALESCE(session_id, '') = ?`).get(input.key, input.scope || "private", input.agent_id || "", input.project_id || "", input.session_id || "");
+    if (existing) {
+      throw new MemoryConflictError(input.key, existing);
+    }
+  }
   if (effectiveMode === "merge") {
     const existing = d.query(`SELECT id, version FROM memories
          WHERE key = ? AND scope = ?
@@ -5859,6 +6072,7 @@ function listMemoriesBounded(filter = {}, target, db) {
   };
 }
 function updateMemory(id, input, db) {
+  input = redactMemoryWriteInput(input);
   if (!db && isApiMode()) {
     const { status, data } = apiJson("PATCH", `/memories/${encodeURIComponent(id)}`, input, { allow404: true });
     if (status === 404)
@@ -5876,6 +6090,17 @@ function updateMemory(id, input, db) {
   if (existing.version !== input.version) {
     throw new VersionConflictError(id, input.version, existing.version);
   }
+  if (input.scope !== undefined && input.scope !== existing.scope) {
+    const conflict = d.query(`SELECT id, agent_id, updated_at FROM memories
+         WHERE key = ? AND scope = ?
+           AND COALESCE(agent_id, '') = ?
+           AND COALESCE(project_id, '') = ?
+           AND COALESCE(session_id, '') = ?
+           AND id != ?`).get(existing.key, input.scope, existing.agent_id || "", existing.project_id || "", existing.session_id || "", memoryId);
+    if (conflict) {
+      throw new MemoryConflictError(existing.key, conflict);
+    }
+  }
   const sets = ["version = version + 1", "updated_at = ?"];
   const params = [now()];
   if (input.value !== undefined) {