@hasna/mementos 0.15.2 → 0.17.0

package/dist/index.js

@@ -1239,6 +1239,8 @@ function getApiConfig(env2 = process.env, options = {}) {
 function isApiMode() {
   if (hasDatabaseUrl())
     return false;
+  if (isServerContext())
+    return false;
   return getApiConfig() !== null;
 }
 function assertClientStoreConfigured(env2 = process.env, options = {}) {
@@ -1285,7 +1287,14 @@ x-api-key: ${cfg.apiKey}
   let bodyFile;
   if (hasBody) {
     bodyFile = join3(tmpdir(), `mem-req-${process.pid}-${randomUUID()}.json`);
-    writeFileSync2(bodyFile, JSON.stringify(body), { mode: 384 });
+    try {
+      writeFileSync2(bodyFile, JSON.stringify(body), { mode: 384 });
+    } catch (error) {
+      try {
+        unlinkSync(bodyFile);
+      } catch {}
+      throw error;
+    }
     args.push("--data-binary", `@${bodyFile}`);
   }
   args.push(url);
@@ -1333,7 +1342,7 @@ function apiJson(method, path, body, options) {
       try {
         data = JSON.parse(raw.body);
       } catch (e) {
-        throw new ApiRequestError(`mementos cloud ${method} ${path} returned status ${raw.status} with a body that is not valid JSON (${e instanceof Error ? e.message : String(e)}) \u2014 the response is truncated or the server is unhealthy`, raw.status, raw.body.slice(0, 500));
+        throw new ApiRequestError(`mementos cloud ${method} ${path} returned status ${raw.status} with a body that is not valid JSON (${e instanceof Error ? e.message : String(e)}) \u2014 the response is truncated or the server is unhealthy`, raw.status, "");
       }
     } else {
       data = undefined;
@@ -1375,6 +1384,7 @@ function toQuery(params) {
 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_local_opt_in();
+  init_storage();
   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"];
@@ -2787,6 +2797,220 @@ INSERT OR IGNORE INTO _migrations (id) VALUES (38);
     `
 ${sqliteMementosMemoryProjectLinkSchemaSql()}
 INSERT OR IGNORE INTO _migrations (id) VALUES (40);
+`,
+    `
+DROP TABLE IF EXISTS temp.mementos_m41_machine_preflight;
+CREATE TEMP TABLE mementos_m41_machine_preflight (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL CHECK(
+    length(name) BETWEEN 1 AND 128
+    AND instr(name, char(0)) = 0
+    AND instr(name, char(1)) = 0
+    AND instr(name, char(2)) = 0
+    AND instr(name, char(3)) = 0
+    AND instr(name, char(4)) = 0
+    AND instr(name, char(5)) = 0
+    AND instr(name, char(6)) = 0
+    AND instr(name, char(7)) = 0
+    AND instr(name, char(8)) = 0
+    AND instr(name, char(9)) = 0
+    AND instr(name, char(10)) = 0
+    AND instr(name, char(11)) = 0
+    AND instr(name, char(12)) = 0
+    AND instr(name, char(13)) = 0
+    AND instr(name, char(14)) = 0
+    AND instr(name, char(15)) = 0
+    AND instr(name, char(16)) = 0
+    AND instr(name, char(17)) = 0
+    AND instr(name, char(18)) = 0
+    AND instr(name, char(19)) = 0
+    AND instr(name, char(20)) = 0
+    AND instr(name, char(21)) = 0
+    AND instr(name, char(22)) = 0
+    AND instr(name, char(23)) = 0
+    AND instr(name, char(24)) = 0
+    AND instr(name, char(25)) = 0
+    AND instr(name, char(26)) = 0
+    AND instr(name, char(27)) = 0
+    AND instr(name, char(28)) = 0
+    AND instr(name, char(29)) = 0
+    AND instr(name, char(30)) = 0
+    AND instr(name, char(31)) = 0
+    AND instr(name, char(127)) = 0
+  ),
+  hostname TEXT NOT NULL UNIQUE CHECK(
+    length(hostname) BETWEEN 1 AND 253
+    AND hostname = lower(rtrim(trim(hostname), '.'))
+    AND instr(hostname, ' ') = 0
+    AND instr(hostname, char(9)) = 0
+    AND instr(hostname, char(10)) = 0
+    AND instr(hostname, char(13)) = 0
+    AND instr(hostname, '/') = 0
+    AND instr(hostname, char(92)) = 0
+  ),
+  platform TEXT NOT NULL CHECK(
+    length(platform) BETWEEN 1 AND 64
+    AND platform = lower(trim(platform))
+    AND platform NOT GLOB '*[^a-z0-9._-]*'
+  ),
+  is_primary INTEGER NOT NULL CHECK(is_primary IN (0, 1)),
+  created_at TEXT NOT NULL CHECK(julianday(created_at) IS NOT NULL),
+  last_seen_at TEXT NOT NULL CHECK(
+    julianday(last_seen_at) IS NOT NULL
+    AND julianday(last_seen_at) >= julianday(created_at)
+  )
+);
+INSERT INTO mementos_m41_machine_preflight
+  (id, name, hostname, platform, is_primary, created_at, last_seen_at)
+SELECT
+  id,
+  name,
+  lower(rtrim(trim(hostname), '.')),
+  platform,
+  is_primary,
+  created_at,
+  last_seen_at
+FROM machines;
+
+UPDATE machines
+SET hostname = (
+  SELECT preflight.hostname
+  FROM mementos_m41_machine_preflight preflight
+  WHERE preflight.id = machines.id
+);
+
+DROP TABLE mementos_m41_machine_preflight;
+DROP TRIGGER IF EXISTS machines_single_primary_insert;
+DROP TRIGGER IF EXISTS machines_single_primary_update;
+DROP INDEX IF EXISTS idx_machines_hostname;
+CREATE UNIQUE INDEX idx_machines_hostname ON machines(hostname);
+DROP INDEX IF EXISTS idx_machines_single_primary;
+CREATE UNIQUE INDEX idx_machines_single_primary
+  ON machines(is_primary) WHERE is_primary = 1;
+
+CREATE TRIGGER IF NOT EXISTS machines_hostname_canonical_insert
+BEFORE INSERT ON machines
+WHEN NEW.hostname != lower(rtrim(trim(NEW.hostname), '.'))
+  OR length(NEW.hostname) NOT BETWEEN 1 AND 253
+  OR instr(NEW.hostname, ' ') > 0
+  OR instr(NEW.hostname, char(9)) > 0
+  OR instr(NEW.hostname, char(10)) > 0
+  OR instr(NEW.hostname, char(13)) > 0
+  OR instr(NEW.hostname, '/') > 0
+  OR instr(NEW.hostname, char(92)) > 0
+BEGIN
+  SELECT RAISE(ABORT, 'machines.hostname must be canonical');
+END;
+
+CREATE TRIGGER IF NOT EXISTS machines_hostname_canonical_update
+BEFORE UPDATE OF hostname ON machines
+WHEN NEW.hostname != lower(rtrim(trim(NEW.hostname), '.'))
+  OR length(NEW.hostname) NOT BETWEEN 1 AND 253
+  OR instr(NEW.hostname, ' ') > 0
+  OR instr(NEW.hostname, char(9)) > 0
+  OR instr(NEW.hostname, char(10)) > 0
+  OR instr(NEW.hostname, char(13)) > 0
+  OR instr(NEW.hostname, '/') > 0
+  OR instr(NEW.hostname, char(92)) > 0
+BEGIN
+  SELECT RAISE(ABORT, 'machines.hostname must be canonical');
+END;
+
+CREATE TRIGGER IF NOT EXISTS machines_runtime_contract_insert
+BEFORE INSERT ON machines
+WHEN length(NEW.name) NOT BETWEEN 1 AND 128
+  OR instr(NEW.name, char(0)) > 0
+  OR instr(NEW.name, char(1)) > 0
+  OR instr(NEW.name, char(2)) > 0
+  OR instr(NEW.name, char(3)) > 0
+  OR instr(NEW.name, char(4)) > 0
+  OR instr(NEW.name, char(5)) > 0
+  OR instr(NEW.name, char(6)) > 0
+  OR instr(NEW.name, char(7)) > 0
+  OR instr(NEW.name, char(8)) > 0
+  OR instr(NEW.name, char(9)) > 0
+  OR instr(NEW.name, char(10)) > 0
+  OR instr(NEW.name, char(11)) > 0
+  OR instr(NEW.name, char(12)) > 0
+  OR instr(NEW.name, char(13)) > 0
+  OR instr(NEW.name, char(14)) > 0
+  OR instr(NEW.name, char(15)) > 0
+  OR instr(NEW.name, char(16)) > 0
+  OR instr(NEW.name, char(17)) > 0
+  OR instr(NEW.name, char(18)) > 0
+  OR instr(NEW.name, char(19)) > 0
+  OR instr(NEW.name, char(20)) > 0
+  OR instr(NEW.name, char(21)) > 0
+  OR instr(NEW.name, char(22)) > 0
+  OR instr(NEW.name, char(23)) > 0
+  OR instr(NEW.name, char(24)) > 0
+  OR instr(NEW.name, char(25)) > 0
+  OR instr(NEW.name, char(26)) > 0
+  OR instr(NEW.name, char(27)) > 0
+  OR instr(NEW.name, char(28)) > 0
+  OR instr(NEW.name, char(29)) > 0
+  OR instr(NEW.name, char(30)) > 0
+  OR instr(NEW.name, char(31)) > 0
+  OR instr(NEW.name, char(127)) > 0
+  OR length(NEW.platform) NOT BETWEEN 1 AND 64
+  OR NEW.platform != lower(trim(NEW.platform))
+  OR NEW.platform GLOB '*[^a-z0-9._-]*'
+  OR NEW.is_primary NOT IN (0, 1)
+  OR julianday(NEW.created_at) IS NULL
+  OR julianday(NEW.last_seen_at) IS NULL
+  OR julianday(NEW.last_seen_at) < julianday(NEW.created_at)
+BEGIN
+  SELECT RAISE(ABORT, 'machines row violates the persisted runtime contract');
+END;
+
+CREATE TRIGGER IF NOT EXISTS machines_runtime_contract_update
+BEFORE UPDATE OF name, platform, is_primary, created_at, last_seen_at ON machines
+WHEN length(NEW.name) NOT BETWEEN 1 AND 128
+  OR instr(NEW.name, char(0)) > 0
+  OR instr(NEW.name, char(1)) > 0
+  OR instr(NEW.name, char(2)) > 0
+  OR instr(NEW.name, char(3)) > 0
+  OR instr(NEW.name, char(4)) > 0
+  OR instr(NEW.name, char(5)) > 0
+  OR instr(NEW.name, char(6)) > 0
+  OR instr(NEW.name, char(7)) > 0
+  OR instr(NEW.name, char(8)) > 0
+  OR instr(NEW.name, char(9)) > 0
+  OR instr(NEW.name, char(10)) > 0
+  OR instr(NEW.name, char(11)) > 0
+  OR instr(NEW.name, char(12)) > 0
+  OR instr(NEW.name, char(13)) > 0
+  OR instr(NEW.name, char(14)) > 0
+  OR instr(NEW.name, char(15)) > 0
+  OR instr(NEW.name, char(16)) > 0
+  OR instr(NEW.name, char(17)) > 0
+  OR instr(NEW.name, char(18)) > 0
+  OR instr(NEW.name, char(19)) > 0
+  OR instr(NEW.name, char(20)) > 0
+  OR instr(NEW.name, char(21)) > 0
+  OR instr(NEW.name, char(22)) > 0
+  OR instr(NEW.name, char(23)) > 0
+  OR instr(NEW.name, char(24)) > 0
+  OR instr(NEW.name, char(25)) > 0
+  OR instr(NEW.name, char(26)) > 0
+  OR instr(NEW.name, char(27)) > 0
+  OR instr(NEW.name, char(28)) > 0
+  OR instr(NEW.name, char(29)) > 0
+  OR instr(NEW.name, char(30)) > 0
+  OR instr(NEW.name, char(31)) > 0
+  OR instr(NEW.name, char(127)) > 0
+  OR length(NEW.platform) NOT BETWEEN 1 AND 64
+  OR NEW.platform != lower(trim(NEW.platform))
+  OR NEW.platform GLOB '*[^a-z0-9._-]*'
+  OR NEW.is_primary NOT IN (0, 1)
+  OR julianday(NEW.created_at) IS NULL
+  OR julianday(NEW.last_seen_at) IS NULL
+  OR julianday(NEW.last_seen_at) < julianday(NEW.created_at)
+BEGIN
+  SELECT RAISE(ABORT, 'machines row violates the persisted runtime contract');
+END;
+
+INSERT OR IGNORE INTO _migrations (id) VALUES (41);
 `
   ];
 });
@@ -2802,7 +3026,8 @@ __export(exports_database, {
   getDbPath: () => getDbPath,
   getDatabase: () => getDatabase,
   escapeLikePrefix: () => escapeLikePrefix,
-  closeDatabase: () => closeDatabase
+  closeDatabase: () => closeDatabase,
+  applyMachineIdentityMigration: () => applyMachineIdentityMigration
 });
 import { existsSync as existsSync3, mkdirSync as mkdirSync2, cpSync } from "fs";
 import { dirname, join as join4, resolve as resolve2 } from "path";
@@ -2930,32 +3155,62 @@ function getDatabase(dbPath) {
   return _db;
 }
 function runMigrations(db) {
+  let currentLevel = 0;
   try {
     const result = db.query("SELECT MAX(id) as max_id FROM _migrations").get();
-    const currentLevel = result?.max_id ?? 0;
-    for (let i = currentLevel;i < MIGRATIONS.length; i++) {
-      try {
-        applyMigration(db, i);
-      } catch (e) {
-        console.warn(`[mementos] Migration ${i + 1} failed: ${e instanceof Error ? e.message : String(e)}`);
-      }
-    }
-  } catch {
-    for (let i = 0;i < MIGRATIONS.length; i++) {
-      try {
-        applyMigration(db, i);
-      } catch (e) {
-        console.warn(`[mementos] Migration ${i + 1} failed: ${e instanceof Error ? e.message : String(e)}`);
+    currentLevel = result?.max_id ?? 0;
+  } catch {}
+  for (let i = currentLevel;i < MIGRATIONS.length; i++) {
+    try {
+      applyMigration(db, i);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (i === 40) {
+        throw new Error(`Mementos migration 41 refused unsafe machine identity data: ${message}`);
       }
+      console.warn(`[mementos] Migration ${i + 1} failed: ${message}`);
     }
   }
 }
 function applyMigration(db, index) {
-  if (index === 32) {
+  if (index === 32)
     ensureMachinePrimaryColumn(db);
+  if (index === 40) {
+    applyMachineIdentityMigration(db);
+    return;
   }
   db.exec(MIGRATIONS[index]);
 }
+function applyMachineIdentityMigration(db) {
+  db.transaction(() => {
+    const rows = db.query("SELECT id, name, hostname, platform, is_primary, created_at, last_seen_at FROM machines").all();
+    const identities = new Map;
+    let primaryCount = 0;
+    for (const row of rows) {
+      const canonical = row.hostname.trim().replace(/\.+$/, "").toLowerCase();
+      const createdAt = new Date(row.created_at).getTime();
+      const lastSeenAt = new Date(row.last_seen_at).getTime();
+      const primaryValueValid = row.is_primary === 0 || row.is_primary === 1 || row.is_primary === false || row.is_primary === true;
+      if (!row.id || !row.name || row.name.length > 128 || /[\u0000-\u001f\u007f]/.test(row.name) || !canonical || canonical.length > 253 || /[\u0000-\u001f\u007f/\\\s]/.test(canonical) || !row.platform || row.platform.length > 64 || row.platform !== row.platform.trim().toLowerCase() || !/^[a-z0-9._-]+$/.test(row.platform) || !primaryValueValid || !Number.isFinite(createdAt) || !Number.isFinite(lastSeenAt) || lastSeenAt < createdAt) {
+        throw new Error(`invalid legacy machine row ${row.id || "(missing id)"}`);
+      }
+      const owner = identities.get(canonical);
+      if (owner && owner !== row.id) {
+        throw new Error(`ambiguous normalized hostname '${canonical}' belongs to both ${owner} and ${row.id}`);
+      }
+      identities.set(canonical, row.id);
+      if (Boolean(row.is_primary))
+        primaryCount += 1;
+    }
+    if (primaryCount > 1) {
+      throw new Error(`legacy machine registry contains ${primaryCount} primary rows`);
+    }
+    db.exec(MIGRATIONS[40]);
+    const receipt = db.query("SELECT id FROM _migrations WHERE id = 41").get();
+    if (receipt?.id !== 41)
+      throw new Error("machine identity migration did not record completion");
+  });
+}
 function ensureMachinePrimaryColumn(db) {
   const columns = db.query("PRAGMA table_info(machines)").all();
   if (columns.length === 0 || columns.some((column) => column.name === "is_primary")) {
@@ -3100,10 +3355,10 @@ var init_util = __esm(() => {
         return obj[e];
       });
     };
-    util2.objectKeys = typeof Object.keys === "function" ? (obj) => Object.keys(obj) : (object) => {
+    util2.objectKeys = typeof Object.keys === "function" ? (obj) => Object.keys(obj) : (object2) => {
       const keys = [];
-      for (const key in object) {
-        if (Object.prototype.hasOwnProperty.call(object, key)) {
+      for (const key in object2) {
+        if (Object.prototype.hasOwnProperty.call(object2, key)) {
           keys.push(key);
         }
       }
@@ -7457,19 +7712,19 @@ function floatSafeRemainder2(val, step) {
   const stepInt = Number.parseInt(step.toFixed(decCount).replace(".", ""));
   return valInt % stepInt / 10 ** decCount;
 }
-function defineLazy(object, key, getter) {
+function defineLazy(object2, key, getter) {
   const set = false;
-  Object.defineProperty(object, key, {
+  Object.defineProperty(object2, key, {
     get() {
       if (!set) {
         const value = getter();
-        object[key] = value;
+        object2[key] = value;
         return value;
       }
       throw new Error("cached value already set");
     },
     set(v) {
-      Object.defineProperty(object, key, {
+      Object.defineProperty(object2, key, {
         value: v
       });
     },
@@ -8085,7 +8340,7 @@ __export(exports_regexes, {
   undefined: () => _undefined,
   ulid: () => ulid,
   time: () => time,
-  string: () => string,
+  string: () => string2,
   rfc5322Email: () => rfc5322Email,
   number: () => number,
   null: () => _null,
@@ -8094,7 +8349,7 @@ __export(exports_regexes, {
   ksuid: () => ksuid,
   ipv6: () => ipv6,
   ipv4: () => ipv4,
-  integer: () => integer,
+  integer: () => integer2,
   html5Email: () => html5Email,
   hostname: () => hostname2,
   guid: () => guid,
@@ -8111,7 +8366,7 @@ __export(exports_regexes, {
   cidrv6: () => cidrv6,
   cidrv4: () => cidrv4,
   browserEmail: () => browserEmail,
-  boolean: () => boolean,
+  boolean: () => boolean2,
   bigint: () => bigint,
   base64url: () => base64url,
   base64: () => base64,
@@ -8142,10 +8397,10 @@ var cuid, cuid2, ulid, xid, ksuid, nanoid, duration, extendedDuration, guid, uui
   if (!version)
     return /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$/;
   return new RegExp(`^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-${version}[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$`);
-}, uuid4, uuid6, uuid7, email, html5Email, rfc5322Email, unicodeEmail, browserEmail, _emoji = `^(\\p{Extended_Pictographic}|\\p{Emoji_Component})+$`, ipv4, ipv6, cidrv4, cidrv6, base64, base64url, hostname2, domain, e164, dateSource = `(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))`, date, string = (params) => {
+}, uuid4, uuid6, uuid7, email, html5Email, rfc5322Email, unicodeEmail, browserEmail, _emoji = `^(\\p{Extended_Pictographic}|\\p{Emoji_Component})+$`, ipv4, ipv6, cidrv4, cidrv6, base64, base64url, hostname2, domain, e164, dateSource = `(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))`, date, string2 = (params) => {
   const regex = params ? `[\\s\\S]{${params?.minimum ?? 0},${params?.maximum ?? ""}}` : `[\\s\\S]*`;
   return new RegExp(`^${regex}$`);
-}, bigint, integer, number, boolean, _null, _undefined, lowercase, uppercase;
+}, bigint, integer2, number, boolean2, _null, _undefined, lowercase, uppercase;
 var init_regexes = __esm(() => {
   cuid = /^[cC][^\s-]{8,}$/;
   cuid2 = /^[0-9a-z]+$/;
@@ -8175,9 +8430,9 @@ var init_regexes = __esm(() => {
   e164 = /^\+(?:[0-9]){6,14}[0-9]$/;
   date = /* @__PURE__ */ new RegExp(`^${dateSource}$`);
   bigint = /^\d+n?$/;
-  integer = /^\d+$/;
+  integer2 = /^\d+$/;
   number = /^-?\d+(?:\.\d+)?/i;
-  boolean = /true|false/i;
+  boolean2 = /true|false/i;
   _null = /null/i;
   _undefined = /undefined/i;
   lowercase = /^[^A-Z]*$/;
@@ -8296,7 +8551,7 @@ var init_checks = __esm(() => {
       bag.minimum = minimum;
       bag.maximum = maximum;
       if (isInt)
-        bag.pattern = integer;
+        bag.pattern = integer2;
     });
     inst._zod.check = (payload) => {
       const input = payload.value;
@@ -9098,7 +9353,7 @@ var init_schemas = __esm(() => {
   });
   $ZodString = /* @__PURE__ */ $constructor("$ZodString", (inst, def) => {
     $ZodType.init(inst, def);
-    inst._zod.pattern = [...inst?._zod.bag?.patterns ?? []].pop() ?? string(inst._zod.bag);
+    inst._zod.pattern = [...inst?._zod.bag?.patterns ?? []].pop() ?? string2(inst._zod.bag);
     inst._zod.parse = (payload, _) => {
       if (def.coerce)
         try {
@@ -9398,7 +9653,7 @@ var init_schemas = __esm(() => {
   });
   $ZodBoolean = /* @__PURE__ */ $constructor("$ZodBoolean", (inst, def) => {
     $ZodType.init(inst, def);
-    inst._zod.pattern = boolean;
+    inst._zod.pattern = boolean2;
     inst._zod.parse = (payload, _ctx) => {
       if (def.coerce)
         try {
@@ -17422,7 +17677,7 @@ var init_parse2 = __esm(() => {
 });
 
 // ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v4/classic/schemas.js
-function string2(params) {
+function string3(params) {
   return _string(ZodString2, params);
 }
 function email2(params) {
@@ -17512,7 +17767,7 @@ function int32(params) {
 function uint32(params) {
   return _uint32(ZodNumberFormat, params);
 }
-function boolean2(params) {
+function boolean3(params) {
   return _boolean(ZodBoolean2, params);
 }
 function bigint2(params) {
@@ -17555,7 +17810,7 @@ function keyof(schema) {
   const shape = schema._zod.def.shape;
   return literal(Object.keys(shape));
 }
-function object(shape, params) {
+function object2(shape, params) {
   const def = {
     type: "object",
     get shape() {
@@ -17621,7 +17876,7 @@ function tuple(items, _paramsOrRest, _params) {
     ...exports_util.normalizeParams(params)
   });
 }
-function record(keyType, valueType, params) {
+function record2(keyType, valueType, params) {
   return new ZodRecord2({
     type: "record",
     keyType,
@@ -17819,7 +18074,7 @@ function _instanceof(cls, params = {
 }
 function json2(params) {
   const jsonSchema = lazy(() => {
-    return union([string2(params), number2(), boolean2(), _null3(), array(jsonSchema), record(string2(), jsonSchema)]);
+    return union([string3(params), number2(), boolean3(), _null3(), array(jsonSchema), record2(string3(), jsonSchema)]);
   });
   return jsonSchema;
 }
@@ -18390,19 +18645,19 @@ var init_compat = __esm(() => {
 // ../../node_modules/.bun/zod@3.25.76/node_modules/zod/v4/classic/coerce.js
 var exports_coerce = {};
 __export(exports_coerce, {
-  string: () => string3,
+  string: () => string4,
   number: () => number3,
   date: () => date4,
-  boolean: () => boolean3,
+  boolean: () => boolean4,
   bigint: () => bigint3
 });
-function string3(params) {
+function string4(params) {
   return _coercedString(ZodString2, params);
 }
 function number3(params) {
   return _coercedNumber(ZodNumber2, params);
 }
-function boolean3(params) {
+function boolean4(params) {
   return _coercedBoolean(ZodBoolean2, params);
 }
 function bigint3(params) {
@@ -18446,7 +18701,7 @@ __export(exports_external2, {
   success: () => success,
   stringbool: () => stringbool,
   stringFormat: () => stringFormat,
-  string: () => string2,
+  string: () => string3,
   strictObject: () => strictObject,
   startsWith: () => _startsWith,
   size: () => _size,
@@ -18458,7 +18713,7 @@ __export(exports_external2, {
   regexes: () => exports_regexes,
   regex: () => _regex,
   refine: () => refine,
-  record: () => record,
+  record: () => record2,
   readonly: () => readonly,
   property: () => _property,
   promise: () => promise,
@@ -18472,7 +18727,7 @@ __export(exports_external2, {
   parse: () => parse3,
   overwrite: () => _overwrite,
   optional: () => optional,
-  object: () => object,
+  object: () => object2,
   number: () => number2,
   nullish: () => nullish2,
   nullable: () => nullable,
@@ -18543,7 +18798,7 @@ __export(exports_external2, {
   cidrv4: () => cidrv42,
   check: () => check,
   catch: () => _catch2,
-  boolean: () => boolean2,
+  boolean: () => boolean3,
   bigint: () => bigint2,
   base64url: () => base64url2,
   base64: () => base642,
@@ -20056,11 +20311,11 @@ function parseMapDef(def, refs) {
   };
 }
 function parseNativeEnumDef(def) {
-  const object2 = def.values;
+  const object3 = def.values;
   const actualKeys = Object.keys(def.values).filter((key) => {
-    return typeof object2[object2[key]] !== "number";
+    return typeof object3[object3[key]] !== "number";
   });
-  const actualValues = actualKeys.map((key) => object2[key]);
+  const actualValues = actualKeys.map((key) => object3[key]);
   const parsedTypes = Array.from(new Set(actualValues.map((values) => typeof values)));
   return {
     type: parsedTypes.length === 1 ? parsedTypes[0] === "string" ? "string" : "number" : ["string", "number"],
@@ -35417,7 +35672,7 @@ var require_token_io = __commonJS((exports, module) => {
   module.exports = __toCommonJS(token_io_exports);
   var import_path = __toESM2(__require("path"));
   var import_fs = __toESM2(__require("fs"));
-  var import_os2 = __toESM2(__require("os"));
+  var import_os = __toESM2(__require("os"));
   var import_token_error = require_token_error();
   function findRootDir() {
     try {
@@ -35438,11 +35693,11 @@ var require_token_io = __commonJS((exports, module) => {
     if (process.env.XDG_DATA_HOME) {
       return process.env.XDG_DATA_HOME;
     }
-    switch (import_os2.default.platform()) {
+    switch (import_os.default.platform()) {
       case "darwin":
-        return import_path.default.join(import_os2.default.homedir(), "Library/Application Support");
+        return import_path.default.join(import_os.default.homedir(), "Library/Application Support");
       case "linux":
-        return import_path.default.join(import_os2.default.homedir(), ".local/share");
+        return import_path.default.join(import_os.default.homedir(), ".local/share");
       case "win32":
         if (process.env.LOCALAPPDATA) {
           return process.env.LOCALAPPDATA;
@@ -35552,10 +35807,10 @@ var require_oauth = __commonJS((exports, module) => {
     refreshTokenRequest: () => refreshTokenRequest
   });
   module.exports = __toCommonJS(oauth_exports);
-  var import_os2 = __require("os");
+  var import_os = __require("os");
   var VERCEL_ISSUER = "https://vercel.com";
   var VERCEL_CLI_CLIENT_ID = "cl_HYyOPBNtFMfHhaUn9L4QPfTZz6TP47bp";
-  var userAgent = `@vercel/oidc node-${process.version} ${(0, import_os2.platform)()} (${(0, import_os2.arch)()}) ${(0, import_os2.hostname)()}`;
+  var userAgent = `@vercel/oidc node-${process.version} ${(0, import_os.platform)()} (${(0, import_os.arch)()}) ${(0, import_os.hostname)()}`;
   var _tokenEndpoint = null;
   async function getTokenEndpoint() {
     if (_tokenEndpoint) {
@@ -40695,8 +40950,8 @@ function prepareCallSettings({
     seed
   };
 }
-function isNonEmptyObject(object2) {
-  return object2 != null && Object.keys(object2).length > 0;
+function isNonEmptyObject(object22) {
+  return object22 != null && Object.keys(object22).length > 0;
 }
 async function prepareToolsAndToolChoice({
   tools,
@@ -47784,7 +48039,7 @@ var import_api2, import_api3, __defProp2, __export2 = (target, all) => {
   createElementStreamTransform() {
     return;
   }
-}), object2 = ({
+}), object3 = ({
   schema: inputSchema,
   name: name232,
   description
@@ -52522,7 +52777,7 @@ var init_dist8 = __esm(() => {
     array: () => array2,
     choice: () => choice,
     json: () => json3,
-    object: () => object2,
+    object: () => object3,
     text: () => text
   });
   originalGenerateId = createIdGenerator({
@@ -54008,7 +54263,7 @@ function buildMemoryListConditions(filter) {
       conditions.push("status = 'active'");
     }
     if (filter.project_id) {
-      conditions.push("project_id = ?");
+      conditions.push(filter.include_unassigned_project === true ? "(project_id = ? OR project_id IS NULL)" : "project_id = ?");
       params.push(filter.project_id);
     }
     if (filter.agent_id) {
@@ -54088,6 +54343,7 @@ function listMemoriesPage(filter, db) {
       pinned: f.pinned,
       agent_id: f.agent_id,
       project_id: f.project_id,
+      include_unassigned_project: f.project_id && f.include_unassigned_project === true ? true : undefined,
       session_id: f.session_id,
       machine_id: f.machine_id,
       visible_to_machine_id: f.visible_to_machine_id,
@@ -54112,7 +54368,7 @@ function listMemoriesPage(filter, db) {
   if (conditions.length > 0) {
     sql += ` WHERE ${conditions.join(" AND ")}`;
   }
-  sql += " ORDER BY importance DESC, created_at DESC";
+  sql += " ORDER BY importance DESC, created_at DESC, id DESC";
   if (f.limit) {
     sql += " LIMIT ?";
     params.push(f.limit);
@@ -55435,17 +55691,83 @@ function updateAgent(id, updates, db) {
 // src/db/locks.ts
 init_database();
 init_api_mode();
-function parseLockRow(row) {
+
+// src/db/api-response-contract.ts
+class MementosApiProtocolError extends Error {
+  code = "MEMENTOS_API_PROTOCOL";
+  constructor(operation, detail) {
+    super(`mementos cloud ${operation} returned a malformed 2xx response: ${detail}`);
+    this.name = "MementosApiProtocolError";
+  }
+}
+function expectObject(value, operation) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new MementosApiProtocolError(operation, "expected a JSON object");
+  }
+  return value;
+}
+function expectArray(value, operation, field) {
+  if (!Array.isArray(value)) {
+    throw new MementosApiProtocolError(operation, field ? `expected '${field}' to be an array` : "expected a JSON array");
+  }
+  return value;
+}
+function expectString(object, field, operation, options = {}) {
+  const value = object[field];
+  if (typeof value !== "string" || !options.allowEmpty && value.length === 0) {
+    throw new MementosApiProtocolError(operation, `expected '${field}' to be ${options.allowEmpty ? "a string" : "a non-empty string"}`);
+  }
+  return value;
+}
+function expectBoolean(object, field, operation) {
+  const value = object[field];
+  if (typeof value !== "boolean") {
+    throw new MementosApiProtocolError(operation, `expected '${field}' to be a boolean`);
+  }
+  return value;
+}
+function expectNonNegativeInteger(object, field, operation) {
+  const value = object[field];
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new MementosApiProtocolError(operation, `expected '${field}' to be a non-negative safe integer`);
+  }
+  return value;
+}
+
+// src/db/locks.ts
+var RESOURCE_TYPES = new Set(["project", "memory", "entity", "agent", "connector", "file"]);
+var LOCK_TYPES = new Set(["advisory", "exclusive"]);
+function parseLockRow(row, operation = "lock response") {
+  const object = expectObject(row, operation);
+  const resourceType = expectString(object, "resource_type", operation);
+  const lockType = expectString(object, "lock_type", operation);
+  if (!RESOURCE_TYPES.has(resourceType)) {
+    throw new MementosApiProtocolError(operation, "unsupported 'resource_type'");
+  }
+  if (!LOCK_TYPES.has(lockType)) {
+    throw new MementosApiProtocolError(operation, "unsupported 'lock_type'");
+  }
+  const timestamp = (field) => {
+    const value = object[field];
+    const date = value instanceof Date ? value : new Date(typeof value === "string" ? value : Number.NaN);
+    if (!Number.isFinite(date.getTime())) {
+      throw new MementosApiProtocolError(operation, `expected '${field}' to be a timestamp`);
+    }
+    return date.toISOString();
+  };
   return {
-    id: row["id"],
-    resource_type: row["resource_type"],
-    resource_id: row["resource_id"],
-    agent_id: row["agent_id"],
-    lock_type: row["lock_type"],
-    locked_at: row["locked_at"],
-    expires_at: row["expires_at"]
+    id: expectString(object, "id", operation),
+    resource_type: resourceType,
+    resource_id: expectString(object, "resource_id", operation),
+    agent_id: expectString(object, "agent_id", operation),
+    lock_type: lockType,
+    locked_at: timestamp("locked_at"),
+    expires_at: timestamp("expires_at")
   };
 }
+function parseLockList(value, operation) {
+  return expectArray(value, operation).map((row, index) => parseLockRow(row, `${operation} item ${index}`));
+}
 function acquireLock(agentId, resourceType, resourceId, lockType = "exclusive", ttlSeconds = 300, db) {
   if (!db && isApiMode()) {
     try {
@@ -55456,7 +55778,7 @@ function acquireLock(agentId, resourceType, resourceId, lockType = "exclusive",
         lock_type: lockType,
         ttl_seconds: ttlSeconds
       });
-      return data;
+      return parseLockRow(data, "POST /locks");
     } catch (e) {
       if (e instanceof ApiRequestError && e.status === 409)
         return null;
@@ -55465,7 +55787,7 @@ function acquireLock(agentId, resourceType, resourceId, lockType = "exclusive",
   }
   const d = db || getDatabase();
   cleanExpiredLocks(d);
-  const ownLock = d.query("SELECT * FROM resource_locks WHERE resource_type = ? AND resource_id = ? AND agent_id = ? AND lock_type = ? AND expires_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now')").get(resourceType, resourceId, agentId, lockType);
+  const ownLock = d.query("SELECT * FROM resource_locks WHERE resource_type = ? AND resource_id = ? AND agent_id = ? AND lock_type = ? AND expires_at > ?").get(resourceType, resourceId, agentId, lockType, now());
   if (ownLock) {
     const newExpiry = new Date(Date.now() + ttlSeconds * 1000).toISOString();
     d.run("UPDATE resource_locks SET expires_at = ? WHERE id = ?", [
@@ -55475,7 +55797,7 @@ function acquireLock(agentId, resourceType, resourceId, lockType = "exclusive",
     return parseLockRow({ ...ownLock, expires_at: newExpiry });
   }
   if (lockType === "exclusive") {
-    const existing = d.query("SELECT * FROM resource_locks WHERE resource_type = ? AND resource_id = ? AND lock_type = 'exclusive' AND agent_id != ? AND expires_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now')").get(resourceType, resourceId, agentId);
+    const existing = d.query("SELECT * FROM resource_locks WHERE resource_type = ? AND resource_id = ? AND lock_type = 'exclusive' AND agent_id != ? AND expires_at > ?").get(resourceType, resourceId, agentId, now());
     if (existing) {
       return null;
     }
@@ -55496,8 +55818,11 @@ function acquireLock(agentId, resourceType, resourceId, lockType = "exclusive",
 }
 function releaseLock(lockId, agentId, db) {
   if (!db && isApiMode()) {
-    const { status } = apiJson("DELETE", `/locks/${encodeURIComponent(lockId)}`, { agent_id: agentId }, { allow404: true });
-    return status !== 404;
+    const operation = `DELETE /locks/${encodeURIComponent(lockId)}`;
+    const { status, data } = apiJson("DELETE", `/locks/${encodeURIComponent(lockId)}`, { agent_id: agentId }, { allow404: true });
+    if (status === 404)
+      return false;
+    return expectBoolean(expectObject(data, operation), "released", operation);
   }
   const d = db || getDatabase();
   const result = d.run("DELETE FROM resource_locks WHERE id = ? AND agent_id = ?", [lockId, agentId]);
@@ -55510,8 +55835,9 @@ function releaseResourceLocks(agentId, resourceType, resourceId, db) {
 }
 function releaseAllAgentLocks(agentId, db) {
   if (!db && isApiMode()) {
+    const operation = `DELETE /agents/${encodeURIComponent(agentId)}/locks`;
     const { data } = apiJson("DELETE", `/agents/${encodeURIComponent(agentId)}/locks`);
-    return data?.released ?? 0;
+    return expectNonNegativeInteger(expectObject(data, operation), "released", operation);
   }
   const d = db || getDatabase();
   const result = d.run("DELETE FROM resource_locks WHERE agent_id = ?", [agentId]);
@@ -55521,69 +55847,714 @@ function checkLock(resourceType, resourceId, lockType, db) {
   if (!db && isApiMode()) {
     const q = toQuery({ resource_type: resourceType, resource_id: resourceId, lock_type: lockType });
     const { data } = apiJson("GET", `/locks${q}`);
-    return data ?? [];
+    return parseLockList(data, "GET /locks");
   }
   const d = db || getDatabase();
   cleanExpiredLocks(d);
-  const query = lockType ? "SELECT * FROM resource_locks WHERE resource_type = ? AND resource_id = ? AND lock_type = ? AND expires_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now')" : "SELECT * FROM resource_locks WHERE resource_type = ? AND resource_id = ? AND expires_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now')";
-  const rows = lockType ? d.query(query).all(resourceType, resourceId, lockType) : d.query(query).all(resourceType, resourceId);
-  return rows.map(parseLockRow);
+  const query = lockType ? "SELECT * FROM resource_locks WHERE resource_type = ? AND resource_id = ? AND lock_type = ? AND expires_at > ?" : "SELECT * FROM resource_locks WHERE resource_type = ? AND resource_id = ? AND expires_at > ?";
+  const rows = lockType ? d.query(query).all(resourceType, resourceId, lockType, now()) : d.query(query).all(resourceType, resourceId, now());
+  return rows.map((row) => parseLockRow(row));
 }
 function agentHoldsLock(agentId, resourceType, resourceId, lockType, db) {
+  if (!db && isApiMode()) {
+    const locks = checkLock(resourceType, resourceId, lockType, db);
+    return locks.find((l) => l.agent_id === agentId) ?? null;
+  }
   const d = db || getDatabase();
-  const query = lockType ? "SELECT * FROM resource_locks WHERE agent_id = ? AND resource_type = ? AND resource_id = ? AND lock_type = ? AND expires_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now')" : "SELECT * FROM resource_locks WHERE agent_id = ? AND resource_type = ? AND resource_id = ? AND expires_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now')";
-  const row = lockType ? d.query(query).get(agentId, resourceType, resourceId, lockType) : d.query(query).get(agentId, resourceType, resourceId);
+  const query = lockType ? "SELECT * FROM resource_locks WHERE agent_id = ? AND resource_type = ? AND resource_id = ? AND lock_type = ? AND expires_at > ?" : "SELECT * FROM resource_locks WHERE agent_id = ? AND resource_type = ? AND resource_id = ? AND expires_at > ?";
+  const row = lockType ? d.query(query).get(agentId, resourceType, resourceId, lockType, now()) : d.query(query).get(agentId, resourceType, resourceId, now());
   return row ? parseLockRow(row) : null;
 }
 function listAgentLocks(agentId, db) {
   if (!db && isApiMode()) {
+    const operation = `GET /agents/${encodeURIComponent(agentId)}/locks`;
     const { data } = apiJson("GET", `/agents/${encodeURIComponent(agentId)}/locks`);
-    return data ?? [];
+    return parseLockList(data, operation);
   }
   const d = db || getDatabase();
   cleanExpiredLocks(d);
-  const rows = d.query("SELECT * FROM resource_locks WHERE agent_id = ? AND expires_at > strftime('%Y-%m-%dT%H:%M:%fZ', 'now') ORDER BY locked_at DESC").all(agentId);
-  return rows.map(parseLockRow);
+  const rows = d.query("SELECT * FROM resource_locks WHERE agent_id = ? AND expires_at > ? ORDER BY locked_at DESC").all(agentId, now());
+  return rows.map((row) => parseLockRow(row));
 }
 function cleanExpiredLocks(db) {
   if (!db && isApiMode()) {
+    const operation = "POST /locks/clean";
     const { data } = apiJson("POST", "/locks/clean");
-    return data?.cleaned ?? 0;
+    return expectNonNegativeInteger(expectObject(data, operation), "cleaned", operation);
   }
   const d = db || getDatabase();
-  const result = d.run("DELETE FROM resource_locks WHERE expires_at <= strftime('%Y-%m-%dT%H:%M:%fZ', 'now')");
+  const result = d.run("DELETE FROM resource_locks WHERE expires_at <= ?", now());
   return result.changes;
 }
-// src/lib/memory-lock.ts
+// src/db/audit.ts
+init_storage();
 init_database();
+init_api_mode();
+import { createHash as createHash2, createHmac, randomBytes, timingSafeEqual } from "crypto";
+
+// src/audit-contract.ts
+var AUDIT_TRAIL_CONTRACT = "mementos.audit.trail.v1";
+var AUDIT_EXPORT_CONTRACT = "mementos.audit.export.v1";
+var AUDIT_STATS_CONTRACT = "mementos.audit.stats.v1";
+var AUDIT_CURSOR_VERSION = 1;
+var AUDIT_DEFAULT_LIMIT = 50;
+var AUDIT_OPERATIONS = [
+  "create",
+  "update",
+  "delete",
+  "archive",
+  "restore",
+  "read"
+];
+
+class AuditContractError extends Error {
+  code = "MEMENTOS_AUDIT_CONTRACT";
+  constructor(message) {
+    super(message);
+    this.name = "AuditContractError";
+  }
+}
+var ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+var MD5_HEX = /^[0-9a-f]{32}$/;
+var ENTRY_KEYS = new Set([
+  "id",
+  "memory_id",
+  "memory_key",
+  "operation",
+  "agent_id",
+  "old_value_hash",
+  "new_value_hash",
+  "changes",
+  "created_at"
+]);
+var PAGE_KEYS = new Set([
+  "contract",
+  "entries",
+  "count",
+  "total",
+  "limit",
+  "cursor",
+  "next_cursor",
+  "consumed",
+  "has_more",
+  "complete",
+  "snapshot_at",
+  "filters",
+  "sort"
+]);
+function object(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new AuditContractError(`${label} must be a JSON object`);
+  }
+  return value;
+}
+function exactKeys(value, allowed, label) {
+  const unexpected = Object.keys(value).filter((key) => !allowed.has(key));
+  if (unexpected.length)
+    throw new AuditContractError(`${label} has unexpected field '${unexpected[0]}'`);
+}
+function string(value, label, options = {}) {
+  if (options.nullable && value === null)
+    return null;
+  if (typeof value !== "string" || value.length === 0 || value.length > (options.max ?? 2048) || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw new AuditContractError(`${label} must be a non-empty printable string of at most ${options.max ?? 2048} characters`);
+  }
+  return value;
+}
+function cursorString(value, label) {
+  if (value === null)
+    return null;
+  if (typeof value !== "string" || !value || value.length > 4096 || !/^[A-Za-z0-9_-]+$/.test(value)) {
+    throw new AuditContractError(`${label} must be a bounded base64url cursor or null`);
+  }
+  return value;
+}
+function integer(value, label, minimum = 0) {
+  if (!Number.isSafeInteger(value) || value < minimum) {
+    throw new AuditContractError(`${label} must be a safe integer >= ${minimum}`);
+  }
+  return value;
+}
+function boolean(value, label) {
+  if (typeof value !== "boolean")
+    throw new AuditContractError(`${label} must be a boolean`);
+  return value;
+}
+function canonicalAuditTimestamp(value, label) {
+  if (value instanceof Date)
+    value = value.toISOString();
+  if (typeof value !== "string")
+    throw new AuditContractError(`${label} must be a canonical UTC timestamp`);
+  const candidate = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}(?:\.\d{1,3})?$/.test(value) ? `${value.replace(" ", "T")}${value.includes(".") ? "" : ".000"}Z` : value;
+  if (!ISO_UTC.test(candidate))
+    throw new AuditContractError(`${label} must use YYYY-MM-DDTHH:mm:ss.sssZ`);
+  const parsed = new Date(candidate);
+  if (!Number.isFinite(parsed.getTime()) || parsed.toISOString() !== candidate) {
+    throw new AuditContractError(`${label} must be a real calendar timestamp`);
+  }
+  return candidate;
+}
+function auditOperation(value, label = "operation") {
+  if (typeof value !== "string" || !AUDIT_OPERATIONS.includes(value)) {
+    throw new AuditContractError(`${label} must be one of: ${AUDIT_OPERATIONS.join(", ")}`);
+  }
+  return value;
+}
+function nullableHash(value, label) {
+  if (value === null)
+    return null;
+  if (typeof value !== "string" || !MD5_HEX.test(value)) {
+    throw new AuditContractError(`${label} must be a lowercase md5 hex digest or null`);
+  }
+  return value;
+}
+function record(value, label) {
+  return object(value, label);
+}
+function validateAuditEntry(value, label = "audit entry") {
+  const row = object(value, label);
+  exactKeys(row, ENTRY_KEYS, label);
+  return {
+    id: string(row.id, `${label}.id`, { max: 512 }),
+    memory_id: string(row.memory_id, `${label}.memory_id`, { max: 512 }),
+    memory_key: string(row.memory_key, `${label}.memory_key`, { nullable: true, max: 4096 }),
+    operation: auditOperation(row.operation, `${label}.operation`),
+    agent_id: string(row.agent_id, `${label}.agent_id`, { nullable: true, max: 512 }),
+    old_value_hash: nullableHash(row.old_value_hash, `${label}.old_value_hash`),
+    new_value_hash: nullableHash(row.new_value_hash, `${label}.new_value_hash`),
+    changes: record(row.changes, `${label}.changes`),
+    created_at: canonicalAuditTimestamp(row.created_at, `${label}.created_at`)
+  };
+}
+function nullableTimestamp2(value, label) {
+  return value === null ? null : canonicalAuditTimestamp(value, label);
+}
+function validateFilters(value) {
+  const filters = object(value, "audit page filters");
+  const expected = new Set(["memory_id", "since", "until", "operation", "agent_id"]);
+  exactKeys(filters, expected, "audit page filters");
+  const result = {
+    memory_id: string(filters.memory_id, "filters.memory_id", { nullable: true, max: 512 }),
+    since: nullableTimestamp2(filters.since, "filters.since"),
+    until: nullableTimestamp2(filters.until, "filters.until"),
+    operation: filters.operation === null ? null : auditOperation(filters.operation, "filters.operation"),
+    agent_id: string(filters.agent_id, "filters.agent_id", { nullable: true, max: 512 })
+  };
+  if (result.since && result.until && result.since > result.until) {
+    throw new AuditContractError("filters.since must not be after filters.until");
+  }
+  return result;
+}
+function compareEntryOrder(left, right) {
+  if (left.created_at !== right.created_at)
+    return left.created_at > right.created_at ? -1 : 1;
+  return left.id > right.id ? -1 : left.id < right.id ? 1 : 0;
+}
+function validateAuditPage(value, expected) {
+  const page = object(value, "audit page");
+  exactKeys(page, PAGE_KEYS, "audit page");
+  if (page.contract !== expected.contract)
+    throw new AuditContractError(`expected contract '${expected.contract}'`);
+  const entries = Array.isArray(page.entries) ? page.entries.map((entry, index) => validateAuditEntry(entry, `entries[${index}]`)) : (() => {
+    throw new AuditContractError("entries must be an array");
+  })();
+  const count = integer(page.count, "count");
+  const total = integer(page.total, "total");
+  const limit = integer(page.limit, "limit", 1);
+  const requestedLimit = integer(expected.limit, "requested limit", 1);
+  if (limit !== requestedLimit)
+    throw new AuditContractError("limit receipt does not match the request");
+  const consumed = integer(page.consumed, "consumed");
+  const cursor = cursorString(page.cursor, "cursor");
+  const nextCursor = cursorString(page.next_cursor, "next_cursor");
+  const hasMore = boolean(page.has_more, "has_more");
+  const complete = boolean(page.complete, "complete");
+  const snapshotAt = canonicalAuditTimestamp(page.snapshot_at, "snapshot_at");
+  const filters = validateFilters(page.filters);
+  const sort = object(page.sort, "sort");
+  exactKeys(sort, new Set(["field", "direction", "tie_breaker"]), "sort");
+  if (sort.field !== "created_at" || sort.direction !== "desc" || sort.tie_breaker !== "id") {
+    throw new AuditContractError("sort must be created_at desc with id tie-breaker");
+  }
+  if (cursor !== expected.cursor)
+    throw new AuditContractError("cursor receipt does not match the request");
+  for (const key of ["memory_id", "since", "until", "operation", "agent_id"]) {
+    if (filters[key] !== expected.filters[key]) {
+      throw new AuditContractError(`filters.${key} receipt does not match the request`);
+    }
+  }
+  if (count !== entries.length || count > limit || total < count || consumed < count || consumed > total) {
+    throw new AuditContractError("count/limit/consumed/total fields are inconsistent");
+  }
+  if (hasMore !== consumed < total)
+    throw new AuditContractError("has_more does not match consumed/total");
+  if (hasMore !== (nextCursor !== null))
+    throw new AuditContractError("next_cursor does not match has_more");
+  if (total > 0 && count === 0)
+    throw new AuditContractError("non-empty audit result must make progress on every page");
+  if (hasMore && nextCursor === cursor)
+    throw new AuditContractError("next_cursor must advance beyond the request cursor");
+  const shouldBeComplete = cursor === null && !hasMore && consumed === total;
+  if (complete !== shouldBeComplete)
+    throw new AuditContractError("complete is not truthful for this page");
+  if (cursor === null && consumed !== count)
+    throw new AuditContractError("initial page consumed must equal count");
+  for (let index = 1;index < entries.length; index++) {
+    if (compareEntryOrder(entries[index - 1], entries[index]) >= 0) {
+      throw new AuditContractError("entries are not strictly ordered by created_at desc, id desc");
+    }
+  }
+  const ids = new Set;
+  for (const entry of entries) {
+    if (ids.has(entry.id))
+      throw new AuditContractError(`duplicate audit entry id '${entry.id}'`);
+    ids.add(entry.id);
+    if (filters.memory_id && entry.memory_id !== filters.memory_id)
+      throw new AuditContractError("entry violates memory_id filter");
+    if (filters.operation && entry.operation !== filters.operation)
+      throw new AuditContractError("entry violates operation filter");
+    if (filters.agent_id && entry.agent_id !== filters.agent_id)
+      throw new AuditContractError("entry violates agent_id filter");
+    if (filters.since && entry.created_at < filters.since)
+      throw new AuditContractError("entry violates since filter");
+    if (filters.until && entry.created_at > filters.until)
+      throw new AuditContractError("entry violates until filter");
+    if (entry.created_at > snapshotAt)
+      throw new AuditContractError("entry is newer than the snapshot boundary");
+  }
+  return {
+    contract: expected.contract,
+    entries,
+    count,
+    total,
+    limit,
+    cursor,
+    next_cursor: nextCursor,
+    consumed,
+    has_more: hasMore,
+    complete,
+    snapshot_at: snapshotAt,
+    filters,
+    sort: { field: "created_at", direction: "desc", tie_breaker: "id" }
+  };
+}
+function validateAuditStats(value) {
+  const stats = object(value, "audit stats");
+  exactKeys(stats, new Set(["contract", "total_entries", "by_operation", "recent_24h", "snapshot_at"]), "audit stats");
+  if (stats.contract !== AUDIT_STATS_CONTRACT)
+    throw new AuditContractError(`expected contract '${AUDIT_STATS_CONTRACT}'`);
+  const total = integer(stats.total_entries, "total_entries");
+  const recent = integer(stats.recent_24h, "recent_24h");
+  const byOperationObject = object(stats.by_operation, "by_operation");
+  exactKeys(byOperationObject, new Set(AUDIT_OPERATIONS), "by_operation");
+  const byOperation = Object.fromEntries(AUDIT_OPERATIONS.map((operation) => [operation, integer(byOperationObject[operation], `by_operation.${operation}`)]));
+  if (Object.values(byOperation).reduce((sum, count) => sum + count, 0) !== total) {
+    throw new AuditContractError("by_operation counts do not sum to total_entries");
+  }
+  if (recent > total)
+    throw new AuditContractError("recent_24h exceeds total_entries");
+  return {
+    contract: AUDIT_STATS_CONTRACT,
+    total_entries: total,
+    by_operation: byOperation,
+    recent_24h: recent,
+    snapshot_at: canonicalAuditTimestamp(stats.snapshot_at, "snapshot_at")
+  };
+}
+
+// src/db/audit.ts
+var DEFAULT_TRAIL_LIMIT = AUDIT_DEFAULT_LIMIT;
+var DEFAULT_EXPORT_LIMIT = AUDIT_DEFAULT_LIMIT;
+var MAX_AUDIT_LIMIT = 1000;
+var MAX_CURSOR_BYTES = 4096;
+var PROCESS_CURSOR_SECRET = randomBytes(32).toString("base64url");
+var CURSOR_MAC_DOMAIN = "mementos.audit.cursor.v1\x00";
+function protocol(operation, error) {
+  if (error instanceof MementosApiProtocolError)
+    throw error;
+  const detail = error instanceof Error ? error.message : String(error);
+  throw new MementosApiProtocolError(operation, detail);
+}
+function safeLimit(value, fallback) {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved < 1 || resolved > MAX_AUDIT_LIMIT) {
+    throw new AuditContractError(`limit must be an integer between 1 and ${MAX_AUDIT_LIMIT}`);
+  }
+  return resolved;
+}
+function printableIdentifier(value, label, maximum = 512) {
+  if (value === undefined)
+    return null;
+  if (!value || value.length > maximum || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw new AuditContractError(`${label} must be a non-empty printable string of at most ${maximum} characters`);
+  }
+  return value;
+}
+function normalizeAuditFilters(input) {
+  const filters = {
+    memory_id: printableIdentifier(input.memory_id, "memory_id"),
+    since: input.since === undefined ? null : canonicalAuditTimestamp(input.since, "since"),
+    until: input.until === undefined ? null : canonicalAuditTimestamp(input.until, "until"),
+    operation: input.operation === undefined ? null : auditOperation(input.operation),
+    agent_id: printableIdentifier(input.agent_id, "agent_id")
+  };
+  if (filters.since && filters.until && filters.since > filters.until) {
+    throw new AuditContractError("since must not be after until");
+  }
+  return filters;
+}
+function filterFingerprint(filters) {
+  return createHash2("sha256").update(JSON.stringify(filters), "utf8").digest("hex");
+}
+function auditCursorSecret() {
+  return process.env["MEMENTOS_AUDIT_CURSOR_SECRET"]?.trim() || process.env["API_KEY_SIGNING_SECRET"]?.trim() || process.env["HASNA_MEMENTOS_API_SIGNING_KEY"]?.trim() || process.env["HASNA_API_SIGNING_KEY"]?.trim() || PROCESS_CURSOR_SECRET;
+}
+function cursorMac(payload, secret) {
+  return createHmac("sha256", secret).update(CURSOR_MAC_DOMAIN, "utf8").update(JSON.stringify(payload), "utf8").digest();
+}
+function encodeAuditCursor(payload, secret) {
+  const mac = cursorMac(payload, secret).toString("base64url");
+  return Buffer.from(JSON.stringify({ ...payload, mac }), "utf8").toString("base64url");
+}
+function decodeAuditCursor(cursor, contract, filters, secret) {
+  if (!cursor || Buffer.byteLength(cursor, "utf8") > MAX_CURSOR_BYTES || !/^[A-Za-z0-9_-]+$/.test(cursor)) {
+    throw new AuditContractError("cursor is not a valid bounded audit cursor");
+  }
+  let raw;
+  try {
+    raw = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+  } catch {
+    throw new AuditContractError("cursor is not valid base64url JSON");
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw))
+    throw new AuditContractError("cursor payload must be an object");
+  const object2 = raw;
+  const keys = Object.keys(object2).sort();
+  const expectedKeys = [
+    "after_created_at",
+    "after_id",
+    "consumed",
+    "contract",
+    "filter_fingerprint",
+    "mac",
+    "snapshot_created_at",
+    "snapshot_id",
+    "snapshot_total",
+    "v"
+  ].sort();
+  if (JSON.stringify(keys) !== JSON.stringify(expectedKeys))
+    throw new AuditContractError("cursor payload fields are invalid");
+  const timestamp = (value, label) => value === null ? null : canonicalAuditTimestamp(value, label);
+  const identifier = (value, label) => {
+    if (value === null)
+      return null;
+    if (typeof value !== "string")
+      throw new AuditContractError(`${label} must be a string or null`);
+    return printableIdentifier(value, label);
+  };
+  const payload = {
+    v: object2.v === AUDIT_CURSOR_VERSION ? AUDIT_CURSOR_VERSION : (() => {
+      throw new AuditContractError("unsupported cursor version");
+    })(),
+    contract: object2.contract === AUDIT_TRAIL_CONTRACT || object2.contract === AUDIT_EXPORT_CONTRACT ? object2.contract : (() => {
+      throw new AuditContractError("cursor contract is invalid");
+    })(),
+    snapshot_created_at: timestamp(object2.snapshot_created_at, "cursor.snapshot_created_at"),
+    snapshot_id: identifier(object2.snapshot_id, "cursor.snapshot_id"),
+    after_created_at: timestamp(object2.after_created_at, "cursor.after_created_at"),
+    after_id: identifier(object2.after_id, "cursor.after_id"),
+    snapshot_total: Number.isSafeInteger(object2.snapshot_total) && object2.snapshot_total >= 0 ? object2.snapshot_total : (() => {
+      throw new AuditContractError("cursor.snapshot_total must be a non-negative safe integer");
+    })(),
+    consumed: Number.isSafeInteger(object2.consumed) && object2.consumed >= 0 ? object2.consumed : (() => {
+      throw new AuditContractError("cursor.consumed must be a non-negative safe integer");
+    })(),
+    filter_fingerprint: typeof object2.filter_fingerprint === "string" ? object2.filter_fingerprint : ""
+  };
+  const encodedMac = object2.mac;
+  if (typeof encodedMac !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(encodedMac)) {
+    throw new AuditContractError("cursor authentication code is invalid");
+  }
+  const providedMac = Buffer.from(encodedMac, "base64url");
+  const expectedMac = cursorMac(payload, secret);
+  if (providedMac.length !== expectedMac.length || !timingSafeEqual(providedMac, expectedMac) || payload.contract !== contract || payload.filter_fingerprint !== filterFingerprint(filters)) {
+    throw new AuditContractError("cursor authentication or query binding failed");
+  }
+  if (!payload.snapshot_created_at || !payload.snapshot_id || !payload.after_created_at || !payload.after_id) {
+    throw new AuditContractError("continuation cursor is missing its snapshot or ordering boundary");
+  }
+  if (payload.after_created_at > payload.snapshot_created_at || payload.after_created_at === payload.snapshot_created_at && payload.after_id > payload.snapshot_id) {
+    throw new AuditContractError("cursor continuation lies outside its snapshot boundary");
+  }
+  return payload;
+}
+function dbTimestamp(value, db) {
+  if (db instanceof PgAdapter)
+    return new Date(value);
+  const withoutZone = value.slice(0, -1).replace("T", " ");
+  return withoutZone.endsWith(".000") ? withoutZone.slice(0, -4) : withoutZone;
+}
+function normalizedDbEntry(row) {
+  let changes = row.changes;
+  if (typeof changes === "string") {
+    try {
+      changes = JSON.parse(changes || "{}");
+    } catch {
+      throw new AuditContractError("audit database row changes is not valid JSON");
+    }
+  }
+  return validateAuditEntry({
+    id: row.id,
+    memory_id: row.memory_id,
+    memory_key: row.memory_key ?? null,
+    operation: row.operation,
+    agent_id: row.agent_id ?? null,
+    old_value_hash: row.old_value_hash ?? null,
+    new_value_hash: row.new_value_hash ?? null,
+    changes: changes ?? {},
+    created_at: canonicalAuditTimestamp(row.created_at, "audit database row created_at")
+  }, "audit database row");
+}
+function buildFilterSql(filters, db) {
+  const conditions = [];
+  const params = [];
+  if (filters.memory_id) {
+    conditions.push("memory_id = ?");
+    params.push(filters.memory_id);
+  }
+  if (filters.since) {
+    conditions.push("created_at >= ?");
+    params.push(dbTimestamp(filters.since, db));
+  }
+  if (filters.until) {
+    conditions.push("created_at <= ?");
+    params.push(dbTimestamp(filters.until, db));
+  }
+  if (filters.operation) {
+    conditions.push("operation = ?");
+    params.push(filters.operation);
+  }
+  if (filters.agent_id) {
+    conditions.push("agent_id = ?");
+    params.push(filters.agent_id);
+  }
+  return { conditions, params };
+}
+function auditSortExpression(db) {
+  return db instanceof PgAdapter ? "date_trunc('milliseconds', created_at)" : "created_at";
+}
+function boundarySql(payload, db) {
+  const conditions = [];
+  const params = [];
+  const createdAt = auditSortExpression(db);
+  if (payload.snapshot_created_at && payload.snapshot_id) {
+    const value = dbTimestamp(payload.snapshot_created_at, db);
+    conditions.push(`(${createdAt} < ? OR (${createdAt} = ? AND id <= ?))`);
+    params.push(value, value, payload.snapshot_id);
+  }
+  if (payload.after_created_at && payload.after_id) {
+    const value = dbTimestamp(payload.after_created_at, db);
+    conditions.push(`(${createdAt} < ? OR (${createdAt} = ? AND id < ?))`);
+    params.push(value, value, payload.after_id);
+  }
+  return { conditions, params };
+}
+function whereClause(conditions) {
+  return conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+}
+function numberFromDb(value, label) {
+  const number = typeof value === "number" ? value : Number(value);
+  if (!Number.isSafeInteger(number) || number < 0)
+    throw new AuditContractError(`${label} is not a non-negative safe integer`);
+  return number;
+}
+function readAuditPage(contract, filters, options, db) {
+  const limit = safeLimit(options.limit, contract === AUDIT_TRAIL_CONTRACT ? DEFAULT_TRAIL_LIMIT : DEFAULT_EXPORT_LIMIT);
+  const requestedCursor = options.cursor ?? null;
+  const secret = auditCursorSecret();
+  const continuation = requestedCursor ? decodeAuditCursor(requestedCursor, contract, filters, secret) : null;
+  return db.transaction(() => {
+    const base = buildFilterSql(filters, db);
+    let snapshotCreatedAt = continuation?.snapshot_created_at ?? null;
+    let snapshotId = continuation?.snapshot_id ?? null;
+    if (!continuation) {
+      const createdAt = auditSortExpression(db);
+      const snapshotRow = db.query(`SELECT ${createdAt} AS created_at, id FROM memory_audit_log ${whereClause(base.conditions)} ORDER BY ${createdAt} DESC, id DESC LIMIT 1`).get(...base.params);
+      if (snapshotRow) {
+        snapshotCreatedAt = canonicalAuditTimestamp(snapshotRow.created_at, "audit snapshot created_at");
+        snapshotId = printableIdentifier(String(snapshotRow.id ?? ""), "audit snapshot id");
+      }
+    }
+    const snapshotBoundary = boundarySql({
+      snapshot_created_at: snapshotCreatedAt,
+      snapshot_id: snapshotId,
+      after_created_at: null,
+      after_id: null
+    }, db);
+    const countConditions = [...base.conditions, ...snapshotBoundary.conditions];
+    const countParams = [...base.params, ...snapshotBoundary.params];
+    const totalRow = db.query(`SELECT COUNT(*) AS count FROM memory_audit_log ${whereClause(countConditions)}`).get(...countParams);
+    const total = numberFromDb(totalRow?.count ?? 0, "audit total");
+    if (continuation && continuation.snapshot_total !== total) {
+      throw new AuditContractError("audit snapshot changed while following the cursor; restart from the first page");
+    }
+    const pageBoundary = boundarySql({
+      snapshot_created_at: snapshotCreatedAt,
+      snapshot_id: snapshotId,
+      after_created_at: continuation?.after_created_at ?? null,
+      after_id: continuation?.after_id ?? null
+    }, db);
+    const pageConditions = [...base.conditions, ...pageBoundary.conditions];
+    const pageParams = [...base.params, ...pageBoundary.params];
+    const rawRows = db.query(`SELECT id, memory_id, memory_key, operation, agent_id, old_value_hash, new_value_hash, changes, created_at
+       FROM memory_audit_log ${whereClause(pageConditions)}
+       ORDER BY ${auditSortExpression(db)} DESC, id DESC LIMIT ?`).all(...pageParams, limit + 1);
+    const hasExtra = rawRows.length > limit;
+    const rows = hasExtra ? rawRows.slice(0, limit) : rawRows;
+    const entries = rows.map(normalizedDbEntry);
+    const consumedBefore = continuation?.consumed ?? 0;
+    const consumed = consumedBefore + entries.length;
+    if (consumed > total || hasExtra !== consumed < total) {
+      throw new AuditContractError("audit page changed inside its database snapshot");
+    }
+    const hasMore = consumed < total;
+    const last = entries.at(-1);
+    const nextCursor = hasMore && last && snapshotCreatedAt && snapshotId ? encodeAuditCursor({
+      v: AUDIT_CURSOR_VERSION,
+      contract,
+      snapshot_created_at: snapshotCreatedAt,
+      snapshot_id: snapshotId,
+      after_created_at: last.created_at,
+      after_id: last.id,
+      snapshot_total: total,
+      consumed,
+      filter_fingerprint: filterFingerprint(filters)
+    }, secret) : null;
+    const page = {
+      contract,
+      entries,
+      count: entries.length,
+      total,
+      limit,
+      cursor: requestedCursor,
+      next_cursor: nextCursor,
+      consumed,
+      has_more: hasMore,
+      complete: requestedCursor === null && !hasMore,
+      snapshot_at: snapshotCreatedAt ?? now(),
+      filters,
+      sort: { field: "created_at", direction: "desc", tie_breaker: "id" }
+    };
+    return validateAuditPage(page, { contract, cursor: requestedCursor, filters, limit });
+  });
+}
+function hostedAuditPage(contract, path, filters, options) {
+  const limit = safeLimit(options.limit, contract === AUDIT_TRAIL_CONTRACT ? DEFAULT_TRAIL_LIMIT : DEFAULT_EXPORT_LIMIT);
+  const cursor = options.cursor ?? null;
+  const operation = `GET ${path.split("?")[0]}`;
+  const { data } = apiJson("GET", path);
+  try {
+    return validateAuditPage(data, { contract, cursor, filters, limit });
+  } catch (error) {
+    return protocol(operation, error);
+  }
+}
+function getMemoryAuditTrailPage(memoryId, options = {}, db) {
+  const filters = normalizeAuditFilters({ memory_id: memoryId });
+  const limit = safeLimit(options.limit, DEFAULT_TRAIL_LIMIT);
+  if (!db && isApiMode()) {
+    const query = toQuery({ limit, cursor: options.cursor });
+    return hostedAuditPage(AUDIT_TRAIL_CONTRACT, `/memories/${encodeURIComponent(filters.memory_id)}/audit-trail${query}`, filters, { limit, cursor: options.cursor });
+  }
+  return readAuditPage(AUDIT_TRAIL_CONTRACT, filters, { limit, cursor: options.cursor }, db ?? getDatabase());
+}
+function exportAuditLogPage(options = {}, db) {
+  const filters = normalizeAuditFilters(options);
+  const limit = safeLimit(options.limit, DEFAULT_EXPORT_LIMIT);
+  if (!db && isApiMode()) {
+    const query = toQuery({
+      since: filters.since ?? undefined,
+      until: filters.until ?? undefined,
+      operation: filters.operation ?? undefined,
+      agent_id: filters.agent_id ?? undefined,
+      limit,
+      cursor: options.cursor
+    });
+    return hostedAuditPage(AUDIT_EXPORT_CONTRACT, `/audit/export${query}`, filters, { limit, cursor: options.cursor });
+  }
+  return readAuditPage(AUDIT_EXPORT_CONTRACT, filters, { limit, cursor: options.cursor }, db ?? getDatabase());
+}
+function getMemoryAuditTrail(memoryId, limit = DEFAULT_TRAIL_LIMIT, db) {
+  return getMemoryAuditTrailPage(memoryId, { limit }, db).entries;
+}
+function exportAuditLog(options = {}, db) {
+  return exportAuditLogPage(options, db).entries;
+}
+function auditStatsFromDb(db) {
+  const snapshotAt = now();
+  const recentSince = new Date(new Date(snapshotAt).getTime() - 24 * 60 * 60 * 1000).toISOString();
+  const snapshotParam = dbTimestamp(snapshotAt, db);
+  const recentParam = dbTimestamp(recentSince, db);
+  const row = db.query(`SELECT
+       COUNT(*) AS total_entries,
+       SUM(CASE WHEN operation = 'create' THEN 1 ELSE 0 END) AS create_count,
+       SUM(CASE WHEN operation = 'update' THEN 1 ELSE 0 END) AS update_count,
+       SUM(CASE WHEN operation = 'delete' THEN 1 ELSE 0 END) AS delete_count,
+       SUM(CASE WHEN operation = 'archive' THEN 1 ELSE 0 END) AS archive_count,
+       SUM(CASE WHEN operation = 'restore' THEN 1 ELSE 0 END) AS restore_count,
+       SUM(CASE WHEN operation = 'read' THEN 1 ELSE 0 END) AS read_count,
+       SUM(CASE WHEN created_at >= ? AND created_at <= ? THEN 1 ELSE 0 END) AS recent_24h
+     FROM memory_audit_log
+     WHERE created_at <= ?`).get(recentParam, snapshotParam, snapshotParam);
+  const byOperation = Object.fromEntries(AUDIT_OPERATIONS.map((operation) => [
+    operation,
+    numberFromDb(row?.[`${operation}_count`] ?? 0, `audit ${operation} count`)
+  ]));
+  return validateAuditStats({
+    contract: AUDIT_STATS_CONTRACT,
+    total_entries: numberFromDb(row?.total_entries ?? 0, "audit total_entries"),
+    by_operation: byOperation,
+    recent_24h: numberFromDb(row?.recent_24h ?? 0, "audit recent_24h"),
+    snapshot_at: snapshotAt
+  });
+}
+function getAuditStats(db) {
+  if (!db && isApiMode()) {
+    const operation = "GET /audit/stats";
+    const { data } = apiJson("GET", "/audit/stats");
+    try {
+      return validateAuditStats(data);
+    } catch (error) {
+      return protocol(operation, error);
+    }
+  }
+  return auditStatsFromDb(db ?? getDatabase());
+}
+// src/lib/memory-lock.ts
 var MEMORY_WRITE_TTL = 30;
 function memoryLockId(key, scope, projectId) {
   return `${scope}:${key}:${projectId ?? ""}`;
 }
 function acquireMemoryWriteLock(agentId, key, scope, projectId, ttlSeconds = MEMORY_WRITE_TTL, db) {
-  const d = db || getDatabase();
-  return acquireLock(agentId, "memory", memoryLockId(key, scope, projectId), "exclusive", ttlSeconds, d);
+  return acquireLock(agentId, "memory", memoryLockId(key, scope, projectId), "exclusive", ttlSeconds, db);
 }
 function releaseMemoryWriteLock(lockId, agentId, db) {
-  const d = db || getDatabase();
-  return releaseLock(lockId, agentId, d);
+  return releaseLock(lockId, agentId, db);
 }
 function checkMemoryWriteLock(key, scope, projectId, db) {
-  const d = db || getDatabase();
-  const locks = checkLock("memory", memoryLockId(key, scope, projectId), "exclusive", d);
+  const locks = checkLock("memory", memoryLockId(key, scope, projectId), "exclusive", db);
   return locks[0] ?? null;
 }
 function withMemoryLock(agentId, key, scope, projectId, fn, ttlSeconds = MEMORY_WRITE_TTL, db) {
-  const d = db || getDatabase();
-  const lock = acquireMemoryWriteLock(agentId, key, scope, projectId, ttlSeconds, d);
+  const lock = acquireMemoryWriteLock(agentId, key, scope, projectId, ttlSeconds, db);
   if (!lock) {
-    const existing = checkMemoryWriteLock(key, scope, projectId, d);
+    const existing = checkMemoryWriteLock(key, scope, projectId, db);
     throw new MemoryLockConflictError(key, scope, existing?.agent_id ?? "unknown");
   }
   try {
     return fn();
   } finally {
-    releaseLock(lock.id, agentId, d);
+    releaseLock(lock.id, agentId, db);
   }
 }
 
@@ -55667,7 +56638,7 @@ function focusFilterSQL(agentId, projectId) {
 // src/db/projects.ts
 init_database();
 init_api_mode();
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 function parseProjectRow2(row) {
   return {
     id: row["id"],
@@ -55729,7 +56700,7 @@ function canonicalProjectUpdateJson(value) {
   return JSON.stringify(canonicalizeProjectUpdateValue(value));
 }
 function digestProjectUpdateValue(value) {
-  return createHash2("sha256").update(canonicalProjectUpdateJson(value)).digest("hex");
+  return createHash3("sha256").update(canonicalProjectUpdateJson(value)).digest("hex");
 }
 function timestampString2(value) {
   return value instanceof Date ? value.toISOString() : String(value);
@@ -56152,7 +57123,7 @@ function getProjectUpdateReceipt(id, receiptId, identity = projectUpdateAuthorit
   return receipt;
 }
 // src/project-registration/authority.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash4 } from "crypto";
 import { resolve as resolve3 } from "path";
 
 // src/project-registration/project-references.ts
@@ -56243,10 +57214,10 @@ function canonicalize2(value) {
   return out;
 }
 function digestMementosProjectRegistrationValue(value) {
-  return createHash3("sha256").update(canonicalMementosProjectRegistrationJson(value)).digest("hex");
+  return createHash4("sha256").update(canonicalMementosProjectRegistrationJson(value)).digest("hex");
 }
 function digestOwnedPath(path) {
-  return createHash3("sha256").update(path).digest("hex");
+  return createHash4("sha256").update(path).digest("hex");
 }
 function deriveMementosProjectRegistrationIdempotencyKey(input) {
   return `prk_${digestMementosProjectRegistrationValue({
@@ -56317,7 +57288,7 @@ function requireString(value, field, options = {}) {
   }
   return value;
 }
-function exactKeys(value, expected, field) {
+function exactKeys2(value, expected, field) {
   const actual = Object.keys(value).sort();
   const wanted = [...expected].sort();
   if (actual.length !== wanted.length || actual.some((key, i) => key !== wanted[i])) {
@@ -56374,7 +57345,7 @@ function assertGuardedUpdateRequest(targetId, request, capability) {
   if (!request.updates || typeof request.updates !== "object") {
     throw new MementosProjectRegistrationError("MEMENTOS_PROJECT_REGISTRATION_INVALID_INPUT", "guarded project updates must contain exactly one private path handle");
   }
-  exactKeys(request.updates, ["path"], "updates");
+  exactKeys2(request.updates, ["path"], "updates");
   return { identity, path: ownedPath(request.updates.path) };
 }
 function publicGuardedUpdateReceipt(receipt, capability) {
@@ -56698,7 +57669,7 @@ function assertForwardRequest2(request, capability) {
   if (request.direction !== "forward" || request.accepted_receipt !== undefined) {
     throw new MementosProjectRegistrationError("MEMENTOS_PROJECT_REGISTRATION_INVALID_INPUT", "conditional create requires a forward request without an accepted receipt");
   }
-  exactKeys(request.desired, [
+  exactKeys2(request.desired, [
     "name",
     "source_project_id",
     "source_project_slug",
@@ -56732,7 +57703,7 @@ function assertInverseRequest(request, capability) {
   if (accepted.authority !== "mementos" || accepted.route !== capability.route || accepted.package_version !== capability.package_version || accepted.authority_id !== capability.authority_id || accepted.tenant_id !== capability.tenant_id || accepted.corpus_id !== capability.corpus_id || accepted.operation_id !== request.operation_id || accepted.step_id !== request.step_id || accepted.resource_kind !== "project" || accepted.direction !== "forward" || accepted.outcome !== "accepted" || !accepted.created_by_operation || !accepted.target_id || !accepted.result_revision || !accepted.result_digest || request.target_selector !== accepted.target_id) {
     throw new MementosProjectRegistrationError("MEMENTOS_PROJECT_REGISTRATION_INVALID_INPUT", "accepted receipt is not an exact attempt-created forward receipt");
   }
-  exactKeys(request.desired, ["accepted_receipt_id", "target_id"], "inverse desired");
+  exactKeys2(request.desired, ["accepted_receipt_id", "target_id"], "inverse desired");
   if (request.desired["accepted_receipt_id"] !== accepted.receipt_id || request.desired["target_id"] !== accepted.target_id) {
     throw new MementosProjectRegistrationError("MEMENTOS_PROJECT_REGISTRATION_DIGEST_MISMATCH", "inverse desired payload does not bind the accepted receipt");
   }
@@ -56826,8 +57797,8 @@ class PackageOwnedMementosProjectRegistrationAuthority {
         target_id: accepted.target_id
       });
     }
-    const record = projectRecord(this.db, project);
-    if (record.revision !== accepted.result_revision || record.digest !== accepted.result_digest) {
+    const record2 = projectRecord(this.db, project);
+    if (record2.revision !== accepted.result_revision || record2.digest !== accepted.result_digest) {
       return this.terminal(request, callDigest, "accepted_target_drifted", {
         target_id: accepted.target_id
       });
@@ -56854,7 +57825,7 @@ class PackageOwnedMementosProjectRegistrationAuthority {
     if (project.updated_at !== receipt.result_revision) {
       throw new MementosProjectRegistrationError("MEMENTOS_PROJECT_REGISTRATION_ATOMICITY_UNAVAILABLE", "guarded project result revision did not match its immutable receipt");
     }
-    const record = {
+    const record2 = {
       target_id: targetId2,
       revision: receipt.result_revision,
       digest: receipt.result_digest
@@ -56862,7 +57833,7 @@ class PackageOwnedMementosProjectRegistrationAuthority {
     return withBoundedResponseControl({
       dry_run: false,
       applied: true,
-      record,
+      record: record2,
       receipt: publicGuardedUpdateReceipt(receipt, this.capabilityValue)
     }, bounds, startedAt);
   }
@@ -56991,12 +57962,12 @@ class PackageOwnedMementosProjectRegistrationAuthority {
         if (!project || project.path !== path) {
           throw new MementosProjectRegistrationError("MEMENTOS_PROJECT_REGISTRATION_CONFLICT", "project write did not read back by its full id");
         }
-        const record = projectRecord(this.db, project);
+        const record2 = projectRecord(this.db, project);
         const acceptedReceipt = makeReceipt2(request, this.capabilityValue, callDigest, now2, {
           outcome: "accepted",
-          target_id: record.target_id,
-          result_revision: record.revision,
-          result_digest: record.digest,
+          target_id: record2.target_id,
+          result_revision: record2.revision,
+          result_digest: record2.digest,
           created_by_operation: true
         });
         this.writeBoundary("before_receipt_write", request);
@@ -57036,9 +58007,9 @@ class PackageOwnedMementosProjectRegistrationAuthority {
     if (!project || project.path !== path) {
       throw new MementosProjectRegistrationError("MEMENTOS_PROJECT_REGISTRATION_RECORD_NOT_FOUND", "exact full-id project readback did not resolve the owned path");
     }
-    const record = projectRecord(this.db, project);
-    assertWithinBounds(record, request, startedAt);
-    return record;
+    const record2 = projectRecord(this.db, project);
+    assertWithinBounds(record2, request, startedAt);
+    return record2;
   }
   async lookupReceipt(request) {
     const startedAt = Date.now();
@@ -57816,103 +58787,401 @@ function getMementosProjectResourceExact(projectId, resourceKind, stableId, db,
 }
 // src/db/machines.ts
 init_database();
+init_api_mode();
+import { createHash as createHash5 } from "crypto";
 import { hostname, platform } from "os";
-function parseMachine(row) {
+var MACHINE_REGISTRATION_CONTRACT = "mementos.machine-registration.v1";
+var MACHINE_LIST_CONTRACT = "mementos.machines.v1";
+var MACHINE_MUTATION_CONTRACT = "mementos.machine-mutation.v1";
+var MACHINE_TOUCH_CONTRACT = "mementos.machine-touch.v1";
+
+class MachineRegistryError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "MachineRegistryError";
+  }
+}
+var ISO_UTC_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+function canonicalTimestamp(value, operation, field) {
+  const stringValue = value instanceof Date ? value.toISOString() : value;
+  if (typeof stringValue !== "string" || !ISO_UTC_TIMESTAMP.test(stringValue)) {
+    throw new MementosApiProtocolError(operation, `expected '${field}' to be a canonical UTC ISO-8601 timestamp`);
+  }
+  const parsed = new Date(stringValue);
+  if (!Number.isFinite(parsed.getTime()) || parsed.toISOString() !== stringValue) {
+    throw new MementosApiProtocolError(operation, `expected '${field}' to be a real calendar timestamp`);
+  }
+  return stringValue;
+}
+function machineFromDb(row, operation = "machine database row") {
   if (!row)
     return null;
+  if (typeof row.id !== "string" || !row.id || typeof row.name !== "string" || !row.name || row.name.length > 128 || /[\u0000-\u001f\u007f]/.test(row.name) || typeof row.hostname !== "string" || !row.hostname || typeof row.platform !== "string" || !row.platform) {
+    throw new Error(`${operation} is missing or violates required machine identity fields`);
+  }
+  const canonicalHostname = normalizeMachineHostname(row.hostname);
+  const canonicalPlatform = normalizeMachinePlatform(row.platform);
+  if (canonicalHostname !== row.hostname || canonicalPlatform !== row.platform) {
+    throw new Error(`${operation} contains noncanonical hostname or platform data`);
+  }
+  if (!["boolean", "number"].includes(typeof row.is_primary)) {
+    throw new Error(`${operation} has an invalid is_primary value`);
+  }
+  const createdValue = row.created_at instanceof Date ? row.created_at : new Date(String(row.created_at ?? ""));
+  const lastSeenValue = row.last_seen_at instanceof Date ? row.last_seen_at : new Date(String(row.last_seen_at ?? ""));
+  if (!Number.isFinite(createdValue.getTime()) || !Number.isFinite(lastSeenValue.getTime())) {
+    throw new Error(`${operation} has an invalid timestamp`);
+  }
+  const createdAt = createdValue.toISOString();
+  const lastSeenAt = lastSeenValue.toISOString();
+  if (lastSeenAt < createdAt)
+    throw new Error(`${operation} has last_seen_at before created_at`);
   return {
-    ...row,
-    is_primary: Boolean(row.is_primary)
-  };
+    id: row.id,
+    name: row.name,
+    hostname: canonicalHostname,
+    platform: canonicalPlatform,
+    is_primary: Boolean(row.is_primary),
+    created_at: createdAt,
+    last_seen_at: lastSeenAt
+  };
+}
+function decodeMachine(value, operation) {
+  const object2 = expectObject(value, operation);
+  const name = expectString(object2, "name", operation);
+  if (name.length > 128 || /[\u0000-\u001f\u007f]/.test(name)) {
+    throw new MementosApiProtocolError(operation, "machine.name is outside the public contract");
+  }
+  const rawHost = expectString(object2, "hostname", operation);
+  const rawPlatform = expectString(object2, "platform", operation);
+  let machineHostname;
+  let machinePlatform;
+  try {
+    machineHostname = normalizeMachineHostname(rawHost);
+    machinePlatform = normalizeMachinePlatform(rawPlatform);
+  } catch {
+    throw new MementosApiProtocolError(operation, "machine hostname or platform is not canonical");
+  }
+  if (machineHostname !== rawHost || machinePlatform !== rawPlatform) {
+    throw new MementosApiProtocolError(operation, "machine hostname or platform is not canonical");
+  }
+  const createdAt = canonicalTimestamp(object2["created_at"], operation, "created_at");
+  const lastSeenAt = canonicalTimestamp(object2["last_seen_at"], operation, "last_seen_at");
+  if (lastSeenAt < createdAt) {
+    throw new MementosApiProtocolError(operation, "last_seen_at precedes created_at");
+  }
+  return {
+    id: expectString(object2, "id", operation),
+    name,
+    hostname: machineHostname,
+    platform: machinePlatform,
+    is_primary: expectBoolean(object2, "is_primary", operation),
+    created_at: createdAt,
+    last_seen_at: lastSeenAt
+  };
+}
+function expectContract(object2, contract, operation) {
+  if (object2["contract"] !== contract) {
+    throw new MementosApiProtocolError(operation, `expected contract '${contract}'`);
+  }
+}
+function decodeRegistration(value, expected) {
+  const operation = "POST /v1/machines";
+  const object2 = expectObject(value, operation);
+  expectContract(object2, MACHINE_REGISTRATION_CONTRACT, operation);
+  const machine = decodeMachine(object2["machine"], operation);
+  const created = expectBoolean(object2, "created", operation);
+  const identity = expectObject(object2["identity"], operation);
+  if (identity["idempotency_key"] !== "normalized_hostname") {
+    throw new MementosApiProtocolError(operation, "expected normalized-hostname identity semantics");
+  }
+  if (expectString(identity, "stable_id", operation) !== machine.id) {
+    throw new MementosApiProtocolError(operation, "identity stable_id does not match machine.id");
+  }
+  const expectedHostname = normalizeMachineHostname(expected.hostname);
+  const expectedPlatform = normalizeMachinePlatform(expected.platform);
+  if (machine.hostname !== expectedHostname || machine.platform !== expectedPlatform) {
+    throw new MementosApiProtocolError(operation, "registration receipt does not match the requested hostname/platform");
+  }
+  if (created && machine.name !== normalizeMachineName(expected.name, expectedHostname)) {
+    throw new MementosApiProtocolError(operation, "created registration receipt does not match the requested name");
+  }
+  return { machine, created };
+}
+function decodeMachineList(value) {
+  const operation = "GET /v1/machines";
+  const object2 = expectObject(value, operation);
+  expectContract(object2, MACHINE_LIST_CONTRACT, operation);
+  const values = expectArray(object2["machines"], operation, "machines");
+  const count = expectNonNegativeInteger(object2, "count", operation);
+  if (count !== values.length) {
+    throw new MementosApiProtocolError(operation, "count does not match machines.length");
+  }
+  if (object2["complete"] !== true) {
+    throw new MementosApiProtocolError(operation, "expected complete=true");
+  }
+  const machines = values.map((entry, index) => decodeMachine(entry, `${operation} machines[${index}]`));
+  const ids = new Set;
+  const hosts = new Set;
+  const names = new Set;
+  let primaryCount = 0;
+  for (const machine of machines) {
+    if (ids.has(machine.id))
+      throw new MementosApiProtocolError(operation, `duplicate machine id '${machine.id}'`);
+    if (hosts.has(machine.hostname))
+      throw new MementosApiProtocolError(operation, `duplicate machine hostname '${machine.hostname}'`);
+    if (names.has(machine.name))
+      throw new MementosApiProtocolError(operation, `duplicate machine name '${machine.name}'`);
+    ids.add(machine.id);
+    hosts.add(machine.hostname);
+    names.add(machine.name);
+    if (machine.is_primary)
+      primaryCount += 1;
+  }
+  if (primaryCount > 1)
+    throw new MementosApiProtocolError(operation, "more than one machine is primary");
+  return machines;
+}
+function decodeMachineMutation(value, operation, expectedId) {
+  const object2 = expectObject(value, operation);
+  expectContract(object2, MACHINE_MUTATION_CONTRACT, operation);
+  const machine = decodeMachine(object2["machine"], operation);
+  if (machine.id !== expectedId) {
+    throw new MementosApiProtocolError(operation, "returned machine id does not match the requested stable id");
+  }
+  return machine;
+}
+function normalizeMachineHostname(host) {
+  const normalized = host.trim().replace(/\.+$/, "").toLowerCase();
+  if (!normalized || normalized.length > 253 || /[\u0000-\u001f\u007f/\\\s]/.test(normalized)) {
+    throw new MachineRegistryError("MACHINE_INVALID_INPUT", "Machine hostname must be a non-empty hostname of at most 253 characters");
+  }
+  return normalized;
+}
+function normalizeMachinePlatform(value) {
+  const normalized = value.trim().toLowerCase();
+  if (!normalized || normalized.length > 64 || !/^[a-z0-9._-]+$/.test(normalized)) {
+    throw new MachineRegistryError("MACHINE_INVALID_INPUT", "Machine platform must contain 1-64 lowercase letters, digits, dots, underscores, or hyphens");
+  }
+  return normalized;
+}
+function normalizeMachineName(value, fallback) {
+  const normalized = value?.trim() || fallback;
+  if (!normalized || normalized.length > 128 || /[\u0000-\u001f\u007f]/.test(normalized)) {
+    throw new MachineRegistryError("MACHINE_INVALID_INPUT", "Machine name must contain 1-128 printable characters");
+  }
+  return normalized;
 }
-function normalizeHostname(host) {
-  return host.replace(/\.(local|lan|home|internal)$/i, "");
+function getMachineById(id, db) {
+  return machineFromDb(db.query("SELECT * FROM machines WHERE id = ?").get(id));
 }
-function registerMachine(name, db = getDatabase()) {
-  const rawHost = hostname();
-  const host = normalizeHostname(rawHost);
-  const plat = platform();
-  const machineName = name?.trim() || host;
-  const existing = parseMachine(db.query("SELECT * FROM machines WHERE hostname = ?").get(host));
-  if (existing) {
-    db.run("UPDATE machines SET last_seen_at = ? WHERE id = ?", [now(), existing.id]);
-    return parseMachine(db.query("SELECT * FROM machines WHERE id = ?").get(existing.id));
+function registerMachineRecord(input, db) {
+  const d = db ?? getDatabase();
+  const host = normalizeMachineHostname(input.hostname);
+  const machineName = normalizeMachineName(input.name, host);
+  const machinePlatform = normalizeMachinePlatform(input.platform);
+  const proposedId = uuid();
+  const seenAt = now();
+  try {
+    const row = d.query(`INSERT INTO machines (id, name, hostname, platform, created_at, last_seen_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(hostname) DO UPDATE SET
+         platform = excluded.platform,
+         last_seen_at = CASE
+           WHEN machines.last_seen_at > excluded.last_seen_at THEN machines.last_seen_at
+           ELSE excluded.last_seen_at
+         END
+       RETURNING *, id = ? AS registration_created`).get(proposedId, machineName, host, machinePlatform, seenAt, seenAt, proposedId);
+    const machine = machineFromDb(row, "machine registration upsert");
+    if (!machine || typeof row?.registration_created !== "boolean" && typeof row?.registration_created !== "number") {
+      throw new MachineRegistryError("MACHINE_REGISTRATION_CONFLICT", "Machine registration returned no stable identity receipt");
+    }
+    return { machine, created: Boolean(row.registration_created) };
+  } catch (error) {
+    if (error instanceof MachineRegistryError)
+      throw error;
+    const details = error && typeof error === "object" ? error : {};
+    const diagnostic = `${String(details.constraint ?? "")} ${String(details.message ?? "")}`;
+    if (/machines(?:_|\.)name|machines_name_key/i.test(diagnostic)) {
+      throw new MachineRegistryError("MACHINE_NAME_CONFLICT", `Machine name already taken: ${machineName}`);
+    }
+    throw error;
   }
-  let finalName = machineName;
-  let suffix = 2;
-  while (db.query("SELECT id FROM machines WHERE name = ?").get(finalName)) {
-    finalName = `${machineName}-${suffix++}`;
+}
+function registerMachine(name, db) {
+  const host = normalizeMachineHostname(hostname());
+  const plat = normalizeMachinePlatform(platform());
+  if (!db && isApiMode()) {
+    const input = { name: name?.trim() || undefined, hostname: host, platform: plat };
+    const { data } = apiJson("POST", "/machines", input);
+    return decodeRegistration(data, input).machine;
   }
-  const id = uuid();
-  db.run("INSERT INTO machines (id, name, hostname, platform) VALUES (?, ?, ?, ?)", [id, finalName, host, plat]);
-  return parseMachine(db.query("SELECT * FROM machines WHERE id = ?").get(id));
-}
-function listMachines(db = getDatabase()) {
-  const rows = db.query("SELECT * FROM machines ORDER BY is_primary DESC, last_seen_at DESC, created_at ASC").all();
-  return rows.map((row) => parseMachine(row));
-}
-function getMachine(id, db = getDatabase()) {
-  return parseMachine(db.query("SELECT * FROM machines WHERE id = ? OR name = ?").get(id, id));
-}
-function renameMachine(id, newName, db = getDatabase()) {
-  const m = parseMachine(db.query("SELECT * FROM machines WHERE id = ?").get(id));
-  if (!m)
-    throw new Error(`Machine not found: ${id}`);
-  const clash = db.query("SELECT id FROM machines WHERE name = ? AND id != ?").get(newName, id);
-  if (clash)
-    throw new Error(`Machine name already taken: ${newName}`);
-  db.run("UPDATE machines SET name = ?, last_seen_at = ? WHERE id = ?", [newName, now(), id]);
-  return parseMachine(db.query("SELECT * FROM machines WHERE id = ?").get(id));
-}
-function getPrimaryMachine(db = getDatabase()) {
-  return parseMachine(db.query("SELECT * FROM machines WHERE is_primary = 1 LIMIT 1").get());
-}
-function getPrimaryMachineCandidate(db = getDatabase()) {
-  if (getPrimaryMachine(db))
+  return registerMachineRecord({ name, hostname: host, platform: plat }, db).machine;
+}
+function listMachines(db) {
+  if (!db && isApiMode()) {
+    const { data } = apiJson("GET", "/machines");
+    return decodeMachineList(data);
+  }
+  const d = db ?? getDatabase();
+  const rows = d.query("SELECT * FROM machines ORDER BY is_primary DESC, last_seen_at DESC, created_at ASC, id ASC").all();
+  return rows.map((row) => machineFromDb(row));
+}
+function getMachine(idOrName, db) {
+  if (!db && isApiMode()) {
+    const { status, data } = apiJson("GET", `/machines/${encodeURIComponent(idOrName)}`, undefined, { allow404: true });
+    if (status === 404)
+      return null;
+    return decodeMachineMutation(data, "GET /v1/machines/:id", idOrName);
+  }
+  const d = db ?? getDatabase();
+  return machineFromDb(d.query("SELECT * FROM machines WHERE id = ? OR name = ?").get(idOrName, idOrName));
+}
+function renameMachine(id, newName, db) {
+  const normalizedName = normalizeMachineName(newName, "");
+  if (!db && isApiMode()) {
+    const { data } = apiJson("PATCH", `/machines/${encodeURIComponent(id)}`, { name: normalizedName });
+    const machine = decodeMachineMutation(data, "PATCH /v1/machines/:id", id);
+    if (machine.name !== normalizedName) {
+      throw new MementosApiProtocolError("PATCH /v1/machines/:id", "returned name does not match the requested rename");
+    }
+    return machine;
+  }
+  const d = db ?? getDatabase();
+  if (!getMachineById(id, d))
+    throw new MachineRegistryError("MACHINE_NOT_FOUND", `Machine not found: ${id}`);
+  try {
+    const updated = machineFromDb(d.query("UPDATE machines SET name = ? WHERE id = ? RETURNING *").get(normalizedName, id));
+    if (!updated)
+      throw new MachineRegistryError("MACHINE_NOT_FOUND", `Machine not found: ${id}`);
+    return updated;
+  } catch (error) {
+    if (error instanceof MachineRegistryError)
+      throw error;
+    const clash = d.query("SELECT id FROM machines WHERE name = ? AND id != ?").get(normalizedName, id);
+    if (clash)
+      throw new MachineRegistryError("MACHINE_NAME_CONFLICT", `Machine name already taken: ${normalizedName}`);
+    throw error;
+  }
+}
+function getPrimaryMachine(db) {
+  if (!db && isApiMode())
+    return listMachines().find((machine) => machine.is_primary) ?? null;
+  const d = db ?? getDatabase();
+  return machineFromDb(d.query("SELECT * FROM machines WHERE is_primary = 1 LIMIT 1").get());
+}
+function getPrimaryMachineCandidate(db) {
+  if (!db && isApiMode()) {
+    const machines = listMachines();
+    if (machines.some((machine) => machine.is_primary))
+      return null;
+    return [...machines].sort((a, b) => a.created_at.localeCompare(b.created_at) || a.id.localeCompare(b.id))[0] ?? null;
+  }
+  const d = db ?? getDatabase();
+  if (getPrimaryMachine(d))
     return null;
-  return parseMachine(db.query("SELECT * FROM machines ORDER BY created_at ASC, id ASC LIMIT 1").get());
+  return machineFromDb(d.query("SELECT * FROM machines ORDER BY created_at ASC, id ASC LIMIT 1").get());
 }
-function setPrimaryMachine(id, db = getDatabase()) {
-  const machine = getMachine(id, db);
-  if (!machine)
-    throw new Error(`Machine not found: ${id}`);
-  const updatedAt = now();
-  db.run("UPDATE machines SET is_primary = 0, last_seen_at = ? WHERE is_primary = 1 AND id != ?", [updatedAt, machine.id]);
-  db.run("UPDATE machines SET is_primary = 1, last_seen_at = ? WHERE id = ?", [updatedAt, machine.id]);
-  return getMachine(machine.id, db);
-}
-function deleteMachine(id, db = getDatabase()) {
-  const machine = getMachine(id, db);
-  if (!machine)
-    throw new Error(`Machine not found: ${id}`);
-  if (machine.is_primary) {
-    throw new Error(`Primary machine cannot be deleted: ${machine.name}`);
+function setPrimaryMachine(id, db) {
+  if (!db && isApiMode()) {
+    const { data } = apiJson("POST", `/machines/${encodeURIComponent(id)}/primary`);
+    const machine = decodeMachineMutation(data, "POST /v1/machines/:id/primary", id);
+    if (!machine.is_primary) {
+      throw new MementosApiProtocolError("POST /v1/machines/:id/primary", "returned machine is not primary");
+    }
+    return machine;
+  }
+  const d = db ?? getDatabase();
+  return d.transaction(() => {
+    if (!getMachineById(id, d))
+      throw new MachineRegistryError("MACHINE_NOT_FOUND", `Machine not found: ${id}`);
+    d.run("UPDATE machines SET is_primary = 0 WHERE is_primary = 1 AND id != ?", id);
+    const updated = machineFromDb(d.query("UPDATE machines SET is_primary = 1 WHERE id = ? RETURNING *").get(id));
+    if (!updated)
+      throw new MachineRegistryError("MACHINE_NOT_FOUND", `Machine not found: ${id}`);
+    return updated;
+  });
+}
+function deleteMachine(id, db) {
+  if (!db && isApiMode()) {
+    const operation = "DELETE /v1/machines/:id";
+    const { data } = apiJson("DELETE", `/machines/${encodeURIComponent(id)}`);
+    const object2 = expectObject(data, operation);
+    expectContract(object2, MACHINE_MUTATION_CONTRACT, operation);
+    if (expectString(object2, "id", operation) !== id || object2["deleted"] !== true) {
+      throw new MementosApiProtocolError(operation, "expected deleted=true for the requested stable id");
+    }
+    if (hostedMachineCache?.id === id)
+      hostedMachineCache = null;
+    return;
   }
-  db.run("DELETE FROM machines WHERE id = ?", [machine.id]);
+  const d = db ?? getDatabase();
+  const machine = getMachineById(id, d);
+  if (!machine)
+    throw new MachineRegistryError("MACHINE_NOT_FOUND", `Machine not found: ${id}`);
+  if (machine.is_primary)
+    throw new MachineRegistryError("MACHINE_PRIMARY_DELETE_REFUSED", `Primary machine cannot be deleted: ${machine.name}`);
+  d.run("DELETE FROM machines WHERE id = ?", id);
 }
-function getFallbackSyncTargetMachine(db = getDatabase()) {
+function getFallbackSyncTargetMachine(db) {
   return getPrimaryMachine(db);
 }
-function getPrimaryMachineStartupWarning(db = getDatabase()) {
+function getPrimaryMachineStartupWarning(db) {
   if (getPrimaryMachine(db))
     return null;
   const candidate = getPrimaryMachineCandidate(db);
-  if (!candidate) {
+  if (!candidate)
     return "No primary machine configured. Fallback sync target is unset because no machines are registered yet.";
-  }
   return `No primary machine configured. Fallback sync target is unset. Candidate: ${candidate.name} (${candidate.id.slice(0, 8)} / ${candidate.hostname}). Confirm it with set_primary_machine.`;
 }
-function touchMachine(id, db = getDatabase()) {
-  db.run("UPDATE machines SET last_seen_at = ? WHERE id = ?", [now(), id]);
-}
-function getCurrentMachineId(db = getDatabase()) {
-  const host = normalizeHostname(hostname());
-  const m = db.query("SELECT id FROM machines WHERE hostname = ?").get(host);
-  if (m) {
-    touchMachine(m.id, db);
-    return m.id;
+function touchMachine(id, db) {
+  if (!db && isApiMode()) {
+    const operation = "POST /v1/machines/:id/touch";
+    const { data } = apiJson("POST", `/machines/${encodeURIComponent(id)}/touch`);
+    const object2 = expectObject(data, operation);
+    expectContract(object2, MACHINE_TOUCH_CONTRACT, operation);
+    if (object2["touched"] !== true || expectString(object2, "id", operation) !== id) {
+      throw new MementosApiProtocolError(operation, "expected touched=true for the requested stable id");
+    }
+    const machine2 = decodeMachine(object2["machine"], operation);
+    const touchedAt2 = canonicalTimestamp(object2["touched_at"], operation, "touched_at");
+    if (machine2.id !== id || machine2.last_seen_at !== touchedAt2) {
+      throw new MementosApiProtocolError(operation, "touch receipt does not match the returned machine");
+    }
+    return machine2;
   }
-  return registerMachine(undefined, db).id;
+  const d = db ?? getDatabase();
+  const touchedAt = now();
+  const machine = machineFromDb(d.query("UPDATE machines SET last_seen_at = ? WHERE id = ? RETURNING *").get(touchedAt, id));
+  if (!machine || machine.id !== id)
+    throw new MachineRegistryError("MACHINE_NOT_FOUND", `Machine not found: ${id}`);
+  return machine;
+}
+var hostedMachineCache = null;
+function getCurrentMachineId(db) {
+  if (!db && isApiMode()) {
+    const host = normalizeMachineHostname(hostname());
+    const plat = normalizeMachinePlatform(platform());
+    const configBefore = getApiConfig();
+    if (!configBefore)
+      throw new Error("mementos hosted machine identity requires a resolved API authority");
+    const credentialFingerprint = createHash5("sha256").update(configBefore.apiKey).digest("hex");
+    const key = `${configBefore.baseUrl}\x00${credentialFingerprint}\x00${host}\x00${plat}`;
+    if (hostedMachineCache?.key === key)
+      return hostedMachineCache.id;
+    const id = registerMachine().id;
+    const configAfter = getApiConfig();
+    const fingerprintAfter = configAfter ? createHash5("sha256").update(configAfter.apiKey).digest("hex") : null;
+    if (!configAfter || configAfter.baseUrl !== configBefore.baseUrl || fingerprintAfter !== credentialFingerprint) {
+      throw new Error("MEMENTOS_AUTHORITY_CHANGED: the machine registry authority or credential changed while resolving the stable machine identity");
+    }
+    hostedMachineCache = { key, id };
+    return id;
+  }
+  const d = db ?? getDatabase();
+  return registerMachine(undefined, d).id;
 }
 // src/lib/search.ts
 init_database();
@@ -59177,14 +60446,27 @@ function ensureDir2(dir) {
     mkdirSync3(dir, { recursive: true });
   }
 }
+// src/lib/injection-project.ts
+function resolveInjectionProjectId(projectRef, db) {
+  if (projectRef === undefined)
+    return;
+  const project = getProject(projectRef, db);
+  if (!project)
+    throw new Error(`Project not found: ${projectRef}`);
+  return project.id;
+}
+
 // src/lib/machine-visibility.ts
+init_api_mode();
 function resolveVisibleMachineId(machineId, db) {
   if (machineId !== undefined) {
     return machineId;
   }
   try {
     return getCurrentMachineId(db);
-  } catch {
+  } catch (error) {
+    if (!db && isApiMode())
+      throw error;
     return null;
   }
 }
@@ -59194,6 +60476,10 @@ function visibleToMachineFilter(machineId, db) {
   };
 }
 
+// src/lib/profile-synthesizer.ts
+init_api_mode();
+init_storage();
+
 // src/db/tool-events.ts
 init_database();
 init_api_mode();
@@ -59206,6 +60492,10 @@ class MemoryInjector {
     this.config = config || loadConfig();
   }
   getInjectionContext(options = {}) {
+    const projectId = resolveInjectionProjectId(options.project_id, options.db);
+    return this.getInjectionContextForProject(options, projectId);
+  }
+  getInjectionContextForProject(options, projectId) {
     const maxTokens = options.max_tokens || this.config.injection.max_tokens;
     const minImportance = options.min_importance || this.config.injection.min_importance;
     const categories = options.categories || this.config.injection.categories;
@@ -59221,13 +60511,13 @@ class MemoryInjector {
       limit: 100
     }, db);
     allMemories.push(...globalMems);
-    if (options.project_id) {
+    if (projectId) {
       const sharedMems = listMemories({
         scope: "shared",
         category: categories,
         min_importance: minImportance,
         status: "active",
-        project_id: options.project_id,
+        project_id: projectId,
         ...visibleToMachineFilter(visibleMachineId),
         limit: 100
       }, db);
@@ -59240,6 +60530,8 @@ class MemoryInjector {
         min_importance: minImportance,
         status: "active",
         agent_id: options.agent_id,
+        project_id: projectId,
+        include_unassigned_project: true,
         ...visibleToMachineFilter(visibleMachineId),
         limit: 100
       }, db);
@@ -59251,7 +60543,7 @@ class MemoryInjector {
         status: "active",
         ...options.session_id ? { session_id: options.session_id } : {},
         ...options.agent_id ? { agent_id: options.agent_id } : {},
-        ...options.project_id ? { project_id: options.project_id } : {},
+        ...projectId ? { project_id: projectId } : {},
         ...visibleToMachineFilter(visibleMachineId),
         limit: 100
       }, db);
@@ -59356,6 +60648,7 @@ ${sections.join(`
     if (!options.query) {
       return this.getInjectionContext(options);
     }
+    const projectId = resolveInjectionProjectId(options.project_id, options.db);
     const maxTokens = options.max_tokens || this.config.injection.max_tokens;
     const minImportance = options.min_importance || this.config.injection.min_importance;
     const categories = options.categories || this.config.injection.categories;
@@ -59371,13 +60664,13 @@ ${sections.join(`
       limit: 100
     }, db);
     allMemories.push(...globalMems);
-    if (options.project_id) {
+    if (projectId) {
       const sharedMems = listMemories({
         scope: "shared",
         category: categories,
         min_importance: minImportance,
         status: "active",
-        project_id: options.project_id,
+        project_id: projectId,
         ...visibleToMachineFilter(visibleMachineId),
         limit: 100
       }, db);
@@ -59390,6 +60683,8 @@ ${sections.join(`
         min_importance: minImportance,
         status: "active",
         agent_id: options.agent_id,
+        project_id: projectId,
+        include_unassigned_project: true,
         ...visibleToMachineFilter(visibleMachineId),
         limit: 100
       }, db);
@@ -59401,7 +60696,7 @@ ${sections.join(`
         status: "active",
         ...options.session_id ? { session_id: options.session_id } : {},
         ...options.agent_id ? { agent_id: options.agent_id } : {},
-        ...options.project_id ? { project_id: options.project_id } : {},
+        ...projectId ? { project_id: projectId } : {},
         ...visibleToMachineFilter(visibleMachineId),
         limit: 100
       }, db);
@@ -59427,7 +60722,7 @@ ${sections.join(`
       } catch {}
     }
     if (embeddingMap.size === 0) {
-      return this.getInjectionContext(options);
+      return this.getInjectionContextForProject(options, projectId);
     }
     const nowMs = Date.now();
     const oldestMs = Math.min(...unique.map((m) => new Date(m.updated_at).getTime()));
@@ -59685,6 +60980,14 @@ var defaultSyncAgents = ["claude", "codex", "gemini"];
 // src/lib/storage-sync.ts
 init_storage();
 init_database();
+init_local_opt_in();
+var STORAGE_SYNC_LOCAL_ONLY_MESSAGE = "REMOTE_COMMAND_UNSUPPORTED: mementos storage push/pull/sync/status operate on the on-box SQLite store, " + "which is opt-in only (" + `${MEMENTOS_LOCAL_OPT_IN_ENV_KEYS[0]}=1 or an explicit ${MEMENTOS_DB_PATH_ENV_KEYS[0]}` + ") and disabled by default. On the hosted route there is no local store to sync \u2014 refusing rather than " + "creating one. Run these verbs where the on-box store deliberately lives (the local opt-in) or in mementos-serve.";
+function openLocalSyncAdapter() {
+  if (!isServerContext() && !selectsMementosLocalStore(process.env)) {
+    throw new Error(STORAGE_SYNC_LOCAL_ONLY_MESSAGE);
+  }
+  return new SqliteAdapter(getDbPath2());
+}
 var MEMORY_TABLE = "memories";
 var MEMORY_SYNC_META_TABLE = "_mementos_storage_sync_meta";
 var SOURCE_MACHINE_METADATA_KEY = "last_synced_source_machine";
@@ -60063,7 +61366,7 @@ function resolveTables(local, tables) {
 function withManagedAdapters(options, fn) {
   const localOwned = !options.local;
   const remoteOwned = !options.remote;
-  const local = options.local ?? new SqliteAdapter(getDbPath2());
+  const local = options.local ?? openLocalSyncAdapter();
   const remote = options.remote ?? new PgAdapter(getStorageConnectionString("mementos"));
   try {
     const currentMachineId = resolveCurrentMachineId(local, options.current_machine_id);
@@ -60119,7 +61422,7 @@ function pullStorageChanges(options = {}) {
 function getStorageSyncStatus(options = {}) {
   const backend = getStorageBackend();
   const localOwned = !options.local;
-  const local = options.local ?? new SqliteAdapter(getDbPath2());
+  const local = options.local ?? openLocalSyncAdapter();
   try {
     const currentMachineId = resolveCurrentMachineId(local, options.current_machine_id);
     return {
@@ -62729,6 +64032,8 @@ export {
   getMemoryLinks,
   getMemoryByKey,
   getMemoryBacklinks,
+  getMemoryAuditTrailPage,
+  getMemoryAuditTrail,
   getMemory,
   getMemoriesForEntity,
   getMemoriesByKey,
@@ -62747,6 +64052,7 @@ export {
   getDatabase,
   getCurrentMachineId,
   getAutoMemoryStats,
+  getAuditStats,
   getAgent,
   getActiveProfile,
   getActiveModel,
@@ -62754,6 +64060,8 @@ export {
   formatMementosProjectPanel,
   focusFilterSQL,
   findPath,
+  exportAuditLogPage,
+  exportAuditLog,
   enforceQuotas,
   digestMementosProjectRegistrationValue,
   deriveMementosProjectRegistrationIdempotencyKey,
@@ -62815,6 +64123,7 @@ export {
   MementosProjectRegistrationHttpClient,
   MementosProjectRegistrationError,
   MementosProjectAuthorityIdentityError,
+  MachineRegistryError,
   MEMORY_PROJECT_LINK_RECEIPT_COLUMNS,
   MEMENTOS_STORAGE_TABLES,
   MEMENTOS_STORAGE_FALLBACK_ENV,
@@ -62828,11 +64137,19 @@ export {
   MEMENTOS_PROJECT_GUARDED_UPDATE_ROUTE,
   MEMENTOS_PROJECT_AUTHORITY_ENV,
   MEMENTOS_MEMORY_PROJECT_LINK_ROUTE,
+  MACHINE_TOUCH_CONTRACT,
+  MACHINE_REGISTRATION_CONTRACT,
+  MACHINE_MUTATION_CONTRACT,
+  MACHINE_LIST_CONTRACT,
   InvalidScopeError,
   EntityNotFoundError,
   DuplicateMemoryError,
   DEFAULT_REFLECTION_PROVIDER,
   DEFAULT_REFLECTION_MODEL,
   DEFAULT_MODEL,
-  DEFAULT_CONFIG
+  DEFAULT_CONFIG,
+  AUDIT_TRAIL_CONTRACT,
+  AUDIT_STATS_CONTRACT,
+  AUDIT_OPERATIONS,
+  AUDIT_EXPORT_CONTRACT
 };