@hasna/mementos 0.14.88 → 0.16.0

package/dist/sdk/index.js

@@ -1,5 +1,1077 @@
 // @bun
+// 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_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 nullableTimestamp(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: nullableTimestamp(filters.since, "filters.since"),
+    until: nullableTimestamp(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")
+  };
+}
+
+// ../../node_modules/.bun/@hasna+contracts@1.0.2+e8014c875821e0be/node_modules/@hasna/contracts/dist/client/transport.js
+import { isIP } from "net";
+import { spawnSync } from "child_process";
+import { closeSync, fstatSync, openSync, readFileSync } from "fs";
+import { O_NOFOLLOW, O_NONBLOCK, O_RDONLY } from "constants";
+import { createRequire } from "module";
+import { hostname as osHostname } from "os";
+import { isAbsolute, join } from "path";
+function envToken(name) {
+  return name.toUpperCase().replace(/-/g, "_");
+}
+function clientTransportEnvKeys(name) {
+  const envSegment = envToken(name);
+  return {
+    apiUrlKeys: [`HASNA_${envSegment}_API_URL`, `${envSegment}_API_URL`],
+    apiKeyKeys: [`HASNA_${envSegment}_API_KEY`, `${envSegment}_API_KEY`]
+  };
+}
+function credentialOverrideEnvKey(name) {
+  return `HASNA_${envToken(name)}_API_KEY_OVERRIDE`;
+}
+var CREDENTIAL_PROFILE_ENV_KEY = "HASNA_PROFILE";
+function credentialPointerEnvKey(name) {
+  return `HASNA_${envToken(name)}_API_KEY_REF`;
+}
+
+class CredentialResolutionError extends Error {
+  appName;
+  attempted;
+  constructor(appName, message, attempted) {
+    super(message);
+    this.name = "CredentialResolutionError";
+    this.appName = appName;
+    this.attempted = attempted;
+  }
+}
+
+class CredentialFileUnsafeError extends Error {
+  path;
+  constructor(path, reason) {
+    super(`Refusing unsafe credential/config file ${path}: ${reason}.`);
+    this.name = "CredentialFileUnsafeError";
+    this.path = path;
+  }
+}
+var HASNA_HOME_ENV_KEY = "HASNA_HOME";
+var HASNA_CONFIG_HOME_ENV_KEY = "HASNA_CONFIG_HOME";
+var KEYCHAIN_STATION_ENV_KEY = "HASNA_STATION";
+var HASNA_HOME_DIR = ".hasna";
+var CONFIG_SUBDIR = "config";
+var CREDENTIALS_FILE = "credentials";
+var KEYCHAIN_SECURITY_BIN = "/usr/bin/security";
+var KEYCHAIN_SERVICE_PREFIX = "hasna.credentials";
+var KEYCHAIN_ITEM_NOT_FOUND_STATUS = 44;
+var KEYCHAIN_SPAWN_TIMEOUT_MS = 1e4;
+var MAX_CREDENTIAL_FILE_BYTES = 64 * 1024;
+var SAFE_APP_SLUG = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+var SAFE_PROFILE = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
+var ILLEGAL_IN_HEADER_VALUE = /[^\t\x20-\x7e]/;
+var VAULT_POINTER_SHAPE = /^[a-z0-9][a-z0-9-]*(?:\/[a-z0-9][a-z0-9-_.]*){2,}$/;
+function homeDir(env) {
+  const home = env.HOME?.trim();
+  return home ? home : null;
+}
+function absoluteOverride(env, key) {
+  const value = env[key]?.trim();
+  return value && isAbsolute(value) ? value : null;
+}
+function hasnaHomeDir(env) {
+  const override = absoluteOverride(env, HASNA_HOME_ENV_KEY);
+  if (override)
+    return override;
+  const home = homeDir(env);
+  return home ? join(home, HASNA_HOME_DIR) : null;
+}
+function appConfigDir(name, env) {
+  const configRoot = absoluteOverride(env, HASNA_CONFIG_HOME_ENV_KEY);
+  if (configRoot)
+    return join(configRoot, name);
+  const root = hasnaHomeDir(env);
+  return root ? join(root, name, CONFIG_SUBDIR) : null;
+}
+function credentialDiskSourceList(name, env, profile = null) {
+  if (!SAFE_APP_SLUG.test(name))
+    return [];
+  const directory = appConfigDir(name, env);
+  if (!directory)
+    return [];
+  const file = profile ? `${CREDENTIALS_FILE}-${profile}` : CREDENTIALS_FILE;
+  return [{ path: join(directory, file), tier: "disk" }];
+}
+function credentialDiskSources(name, env) {
+  return credentialDiskSourceList(name, env, null).map((s) => s.path);
+}
+function profileDiskSources(name, env, profile) {
+  return credentialDiskSourceList(name, env, profile).map((s) => s.path);
+}
+function parseEnvFile(text) {
+  const values = new Map;
+  const unusable = new Set;
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith("#"))
+      continue;
+    const withoutExport = line.startsWith("export ") ? line.slice("export ".length).trim() : line;
+    const equals = withoutExport.indexOf("=");
+    if (equals <= 0)
+      continue;
+    const key = withoutExport.slice(0, equals).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+      continue;
+    let value = withoutExport.slice(equals + 1).trim();
+    const quote = value[0];
+    if (quote === '"' || quote === "'") {
+      if (value.length < 2 || !value.endsWith(quote)) {
+        unusable.add(key);
+        continue;
+      }
+      value = value.slice(1, -1);
+    }
+    if (value.trim().length === 0) {
+      unusable.add(key);
+      continue;
+    }
+    if (values.has(key) && values.get(key) !== value)
+      unusable.add(key);
+    values.set(key, value);
+  }
+  return { values, unusable };
+}
+function configFileModeAllowed(mode) {
+  const permissions = mode & 4095;
+  return permissions === 256 || permissions === 384;
+}
+function configFileReadsCoherent(before, after) {
+  return before.dev === after.dev && before.ino === after.ino && before.size === after.size && before.mtimeMs === after.mtimeMs && before.ctimeMs === after.ctimeMs;
+}
+function readAppConfigFile(path) {
+  const unsafe = (reason) => {
+    throw new CredentialFileUnsafeError(path, reason);
+  };
+  let fd = -1;
+  try {
+    fd = openSync(path, O_RDONLY | O_NOFOLLOW | O_NONBLOCK);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR")
+      return null;
+    if (code === "ELOOP")
+      unsafe("the path is a symlink");
+    unsafe(`the path could not be opened (${code ?? "unknown error"})`);
+  }
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile())
+      unsafe("the path is not a regular file");
+    if (!configFileModeAllowed(before.mode)) {
+      unsafe(`permission mode ${(before.mode & 4095).toString(8).padStart(4, "0")} is not owner-only 0400 or 0600`);
+    }
+    const uid = process.getuid?.() ?? process.geteuid?.();
+    if (uid !== undefined && before.uid !== uid)
+      unsafe("the file is not owned by the current user");
+    if (before.size > MAX_CREDENTIAL_FILE_BYTES)
+      unsafe("the file exceeds the size limit");
+    const bytes = readFileSync(fd);
+    const after = fstatSync(fd);
+    if (!configFileReadsCoherent(before, after)) {
+      unsafe("the file changed while being read");
+    }
+    return parseEnvFile(bytes.toString("utf8"));
+  } finally {
+    if (fd !== -1)
+      closeSync(fd);
+  }
+}
+function readCredentialFile(path, apiKeyKeys) {
+  const parsed = readAppConfigFile(path);
+  if (!parsed)
+    return null;
+  for (const key of apiKeyKeys) {
+    if (parsed.unusable.has(key)) {
+      throw new CredentialFileUnsafeError(path, `${key} is declared but blank or malformed`);
+    }
+  }
+  const values = apiKeyKeys.map((key) => parsed.values.get(key)?.trim()).filter((value) => Boolean(value));
+  if (new Set(values).size > 1) {
+    throw new CredentialFileUnsafeError(path, "credential aliases disagree");
+  }
+  return values[0] ?? null;
+}
+var CREDENTIAL_SHAPED_KEY = /(?:^|_)(?:API_KEY|KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH)(?:_|$)/;
+function appConfigDiskValue(name, env, keys) {
+  const wanted = keys.filter((key) => !CREDENTIAL_SHAPED_KEY.test(key));
+  if (wanted.length === 0)
+    return null;
+  for (const path of credentialDiskSources(name, env)) {
+    const parsed = readAppConfigFile(path);
+    if (!parsed)
+      continue;
+    if (wanted.some((key) => parsed.unusable.has(key))) {
+      return { key: wanted.find((key) => parsed.unusable.has(key)), value: "", path, unusable: true };
+    }
+    const values = wanted.map((key) => parsed.values.get(key)?.trim()).filter((value) => Boolean(value));
+    if (new Set(values).size > 1)
+      throw new CredentialFileUnsafeError(path, "configuration aliases disagree");
+    for (const key of wanted) {
+      if (parsed.unusable.has(key))
+        return { key, value: "", path, unusable: true };
+      const value = parsed.values.get(key)?.trim();
+      if (value)
+        return { key, value, path };
+    }
+  }
+  return null;
+}
+function assertUsableCredential(appName, source, value) {
+  if (VAULT_POINTER_SHAPE.test(value)) {
+    throw new CredentialResolutionError(appName, `The credential from ${source} looks like a secrets-vault pointer (a path-shaped reference like ` + `'namespace/app/live/api_key'). A vault path is NEVER accepted as a literal API key. ` + `Use ${credentialPointerEnvKey(appName)} to resolve the key through the vault, or provide the actual key value.`, [source]);
+  }
+  if (!ILLEGAL_IN_HEADER_VALUE.test(value))
+    return;
+  throw new CredentialResolutionError(appName, `The credential from ${source} contains characters that cannot be sent in an HTTP header ` + `(a control character or non-ASCII byte). A file written with CR-only line endings is the usual ` + `cause. Rewrite that credential file with one LF-terminated KEY=value line. ` + `The value is not shown here, and is deliberately never logged.`, [source]);
+}
+var INSPECT_CUSTOM = Symbol.for("nodejs.util.inspect.custom");
+var CREDENTIAL_SEAL = Symbol.for("hasna:contracts:sealedCredential");
+function sealCredential(fields) {
+  const { apiKey } = fields;
+  const visible = {
+    tier: fields.tier,
+    source: fields.source,
+    deliberate: fields.deliberate,
+    diskCandidates: Object.freeze([...fields.diskCandidates]),
+    warning: fields.warning
+  };
+  const sealed = { ...visible };
+  Object.defineProperty(sealed, "apiKey", {
+    value: apiKey,
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  if (fields.pointerVaultKey !== undefined) {
+    Object.defineProperty(sealed, "pointerVaultKey", {
+      value: fields.pointerVaultKey,
+      enumerable: false,
+      writable: false,
+      configurable: false
+    });
+  }
+  Object.defineProperty(sealed, INSPECT_CUSTOM, {
+    value: () => ({ ...visible, apiKey: "[redacted]" }),
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  Object.defineProperty(sealed, CREDENTIAL_SEAL, {
+    value: true,
+    enumerable: false,
+    writable: false,
+    configurable: false
+  });
+  return Object.freeze(sealed);
+}
+function firstEnvValue(env, keys) {
+  for (const key of keys) {
+    if (!Object.prototype.hasOwnProperty.call(env, key))
+      continue;
+    const value = env[key]?.trim();
+    if (value)
+      return { key, value };
+  }
+  return null;
+}
+var AMBIENT_ENVIRONMENT = Symbol.for("hasna:contracts:ambientClientEnvironment");
+function isAmbientEnvironment(env) {
+  return env === process.env || env[AMBIENT_ENVIRONMENT] === true;
+}
+function defaultKeychainRunner(argv) {
+  const result = spawnSync(KEYCHAIN_SECURITY_BIN, [...argv], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: KEYCHAIN_SPAWN_TIMEOUT_MS
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.error ? result.error.message : result.stderr ?? ""
+  };
+}
+function keychainTierEnabled(env, options) {
+  if ((options.platform ?? process.platform) !== "darwin")
+    return false;
+  if (options.enabled !== undefined)
+    return options.enabled;
+  return options.run !== undefined || isAmbientEnvironment(env);
+}
+function keychainAccount(env, options) {
+  const station = env[KEYCHAIN_STATION_ENV_KEY]?.trim();
+  if (station)
+    return station;
+  const host = (options.hostname ?? osHostname)().split(".")[0]?.trim() ?? "";
+  if (host)
+    return host;
+  const user = env.USER?.trim();
+  return user || null;
+}
+function keychainFailureHint(text) {
+  const line = text.split(/\r?\n/).find((entry) => entry.trim().length > 0)?.trim() ?? "";
+  const clean = line.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, 200);
+  return clean ? `: ${clean}` : "";
+}
+function readKeychainItem(name, env, kind, options) {
+  if (!SAFE_APP_SLUG.test(name) || !keychainTierEnabled(env, options))
+    return null;
+  const account = keychainAccount(env, options);
+  if (!account)
+    return null;
+  const service = `${KEYCHAIN_SERVICE_PREFIX}.${name}.${kind}`;
+  const source = `keychain:${service}@${account}`;
+  const run = options.run ?? defaultKeychainRunner;
+  let result;
+  try {
+    result = run(["find-generic-password", "-a", account, "-s", service, "-w"]);
+  } catch (error) {
+    const reason = keychainFailureHint(error instanceof Error ? error.message : String(error));
+    throw new CredentialResolutionError(name, `The Keychain lookup for ${source} could not run${reason}. A Keychain failure is never resolved ` + `around: fix the keychain, or delete the item to fall through to the credential on disk.`, [source]);
+  }
+  if (result.status === KEYCHAIN_ITEM_NOT_FOUND_STATUS)
+    return null;
+  if (result.status !== 0) {
+    throw new CredentialResolutionError(name, `The Keychain lookup for ${source} failed (security exited ` + `${result.status ?? "without a status"}${keychainFailureHint(result.stderr)}). A Keychain item that ` + `exists but cannot be read is never resolved around: unlock the keychain, run from a session that ` + `may use it, or delete the item to fall through to the credential on disk.`, [source]);
+  }
+  const value = result.stdout.trim();
+  if (!value) {
+    throw new CredentialResolutionError(name, `${source} exists but holds an empty value; a declared item never falls through to another ` + `identity. Store a value in it or delete the item.`, [source]);
+  }
+  return { value, source };
+}
+function keychainConfigValue(name, env, options = {}) {
+  return readKeychainItem(name, env, "api-url", options);
+}
+function snapshotClientEnvironment(name, env) {
+  const keys = clientTransportEnvKeys(name);
+  const ambient = isAmbientEnvironment(env);
+  const snapshot = Object.create(null);
+  for (const key of [
+    ...keys.apiUrlKeys,
+    ...keys.apiKeyKeys,
+    credentialOverrideEnvKey(name),
+    credentialPointerEnvKey(name),
+    CREDENTIAL_PROFILE_ENV_KEY,
+    "HOME",
+    HASNA_HOME_ENV_KEY,
+    HASNA_CONFIG_HOME_ENV_KEY,
+    KEYCHAIN_STATION_ENV_KEY,
+    "USER"
+  ]) {
+    const descriptor = Object.getOwnPropertyDescriptor(env, key);
+    if (!descriptor)
+      continue;
+    if (!("value" in descriptor)) {
+      throw new CredentialResolutionError(name, `${key} is accessor-backed; client configuration requires own data properties.`, [key]);
+    }
+    if (descriptor.value !== undefined && typeof descriptor.value !== "string") {
+      throw new CredentialResolutionError(name, `${key} must be a string data property.`, [key]);
+    }
+    snapshot[key] = descriptor.value;
+  }
+  if (ambient) {
+    Object.defineProperty(snapshot, AMBIENT_ENVIRONMENT, {
+      value: true,
+      enumerable: false,
+      writable: false,
+      configurable: false
+    });
+  }
+  return Object.freeze(snapshot);
+}
+function resolveCredential(name, env, options = {}) {
+  env = snapshotClientEnvironment(name, env);
+  const { apiKeyKeys } = clientTransportEnvKeys(name);
+  const diskPaths = credentialDiskSources(name, env);
+  if (options.apiKey !== undefined) {
+    const explicitKey = options.apiKey.trim();
+    if (!explicitKey) {
+      throw new CredentialResolutionError(name, "The explicit apiKey argument is blank; an explicit credential never falls through to another identity.", ["explicit apiKey argument"]);
+    }
+    assertUsableCredential(name, "the explicit apiKey argument", explicitKey);
+    return sealCredential({
+      apiKey: explicitKey,
+      tier: "argument",
+      source: "explicit apiKey argument",
+      deliberate: true,
+      diskCandidates: diskPaths,
+      warning: null
+    });
+  }
+  const overrideKeyName = credentialOverrideEnvKey(name);
+  const overrideRaw = Object.prototype.hasOwnProperty.call(env, overrideKeyName) ? env[overrideKeyName] : undefined;
+  if (overrideRaw !== undefined) {
+    const override = overrideRaw.trim();
+    if (!override) {
+      throw new CredentialResolutionError(name, `${overrideKeyName} is set but empty. It is a deliberate override, so it is not resolved around: ` + `either give it a real key or unset it to fall back to the credential on disk.`, [overrideKeyName]);
+    }
+    assertUsableCredential(name, overrideKeyName, override);
+    return sealCredential({
+      apiKey: override,
+      tier: "override",
+      source: overrideKeyName,
+      deliberate: true,
+      diskCandidates: diskPaths,
+      warning: null
+    });
+  }
+  const pointerKeyName = credentialPointerEnvKey(name);
+  const pointerRaw = Object.prototype.hasOwnProperty.call(env, pointerKeyName) ? env[pointerKeyName] : undefined;
+  if (pointerRaw !== undefined) {
+    const pointer = pointerRaw.trim();
+    if (!pointer) {
+      throw new CredentialResolutionError(name, `${pointerKeyName} is set but empty. It is a deliberate vault pointer, so it is not resolved around: ` + `either give it a vault item key or unset it to fall back to the credential on disk.`, [pointerKeyName]);
+    }
+    if (!VAULT_POINTER_SHAPE.test(pointer)) {
+      throw new CredentialResolutionError(name, `${pointerKeyName} must name a vault ITEM KEY (a path-shaped reference like ` + `'namespace/app/live/api_key'), not a credential value. A pointer that carries a literal is refused.`, [pointerKeyName]);
+    }
+    return sealCredential({
+      apiKey: "",
+      pointerVaultKey: pointer,
+      tier: "pointer",
+      source: pointerKeyName,
+      deliberate: true,
+      diskCandidates: diskPaths,
+      warning: null
+    });
+  }
+  if (options.profile !== undefined && !options.profile.trim()) {
+    throw new CredentialResolutionError(name, "The explicit profile argument is blank; an explicit identity selection never falls through.", ["explicit profile argument"]);
+  }
+  const profileRaw = Object.prototype.hasOwnProperty.call(env, CREDENTIAL_PROFILE_ENV_KEY) ? env[CREDENTIAL_PROFILE_ENV_KEY] : undefined;
+  if (profileRaw !== undefined && !profileRaw.trim()) {
+    throw new CredentialResolutionError(name, `${CREDENTIAL_PROFILE_ENV_KEY} is set but blank.`, [CREDENTIAL_PROFILE_ENV_KEY]);
+  }
+  const profile = options.profile?.trim() || profileRaw?.trim();
+  if (profile) {
+    const profileSource = options.profile?.trim() ? "explicit profile argument" : CREDENTIAL_PROFILE_ENV_KEY;
+    if (!SAFE_PROFILE.test(profile)) {
+      throw new CredentialResolutionError(name, `Profile name from ${profileSource} is not usable in a path. ` + `Use letters, digits, dot, dash, or underscore.`, [profileSource]);
+    }
+    const paths = profileDiskSources(name, env, profile);
+    for (const path of paths) {
+      const value = readCredentialFile(path, apiKeyKeys);
+      if (value) {
+        assertUsableCredential(name, path, value);
+        return sealCredential({
+          apiKey: value,
+          tier: "profile",
+          source: path,
+          deliberate: true,
+          diskCandidates: paths,
+          warning: null
+        });
+      }
+    }
+    throw new CredentialResolutionError(name, `Profile '${profile}' (from ${profileSource}) has no ${apiKeyKeys[0]} for '${name}'. ` + `Looked in: ${paths.join(", ") || "<no HOME in this environment>"}. ` + `A profile names WHICH identity to use, so it is never resolved around \u2014 ` + `create the profile's credential file or unset ${CREDENTIAL_PROFILE_ENV_KEY}.`, paths);
+  }
+  const definedEnvEntries = apiKeyKeys.filter((key) => Object.prototype.hasOwnProperty.call(env, key) && env[key] !== undefined).map((key) => ({ key, value: String(env[key]).trim() }));
+  const blankEnv = definedEnvEntries.find((entry) => entry.value.length === 0);
+  if (blankEnv) {
+    throw new CredentialResolutionError(name, `${blankEnv.key} is set but blank; a declared credential never falls through to another alias or identity.`, [blankEnv.key]);
+  }
+  if (definedEnvEntries.length > 1 && new Set(definedEnvEntries.map((entry) => entry.value)).size > 1) {
+    throw new CredentialResolutionError(name, `${definedEnvEntries.map((entry) => entry.key).join(" and ")} disagree; credential aliases must be identical or only one may be set.`, definedEnvEntries.map((entry) => entry.key));
+  }
+  const envHit = firstEnvValue(env, apiKeyKeys);
+  const keychainHit = readKeychainItem(name, env, "api-key", options.keychain ?? {});
+  if (keychainHit) {
+    assertUsableCredential(name, keychainHit.source, keychainHit.value);
+    const warning = envHit && envHit.value !== keychainHit.value ? `Credential sources disagree for '${name}': ${keychainHit.source} and ${envHit.key} hold ` + `different keys. ${keychainHit.source} wins, because the Keychain is re-read on every call while ` + `an environment variable is a snapshot. Reconcile them \u2014 a rotation that updated only one leaves ` + `the other to fail 401 wherever it is loaded first.` : null;
+    return sealCredential({
+      apiKey: keychainHit.value,
+      tier: "keychain",
+      source: keychainHit.source,
+      deliberate: false,
+      diskCandidates: diskPaths,
+      warning
+    });
+  }
+  const diskSourceList = credentialDiskSourceList(name, env, null);
+  const diskHits = diskSourceList.map((src) => ({ src, value: readCredentialFile(src.path, apiKeyKeys) })).filter((hit) => hit.value !== null);
+  if (diskHits.length > 0) {
+    const winner = diskHits[0];
+    assertUsableCredential(name, winner.src.path, winner.value);
+    const divergentSources = [
+      ...diskHits.slice(1).filter((hit) => hit.value !== winner.value).map((hit) => hit.src.path),
+      ...envHit && envHit.value !== winner.value ? [envHit.key] : []
+    ];
+    const warning = divergentSources.length > 0 ? `Credential sources disagree for '${name}': ${winner.src.path} and ` + `${divergentSources.join(", ")} hold different keys. ${winner.src.path} wins, because a file on ` + `disk is re-read on every call while an environment variable is a snapshot. Reconcile them \u2014 ` + `a rotation that updated only one leaves the other to fail 401 wherever it is loaded first.` : null;
+    return sealCredential({
+      apiKey: winner.value,
+      tier: winner.src.tier,
+      source: winner.src.path,
+      deliberate: false,
+      diskCandidates: diskPaths,
+      warning
+    });
+  }
+  if (envHit) {
+    assertUsableCredential(name, envHit.key, envHit.value);
+    return sealCredential({
+      apiKey: envHit.value,
+      tier: "env",
+      source: envHit.key,
+      deliberate: false,
+      diskCandidates: diskPaths,
+      warning: null
+    });
+  }
+  return null;
+}
+var SECRETS_PACKAGE_SPECIFIER = "@hasna/" + "secrets";
+var requireSecretsSdk = createRequire(import.meta.url);
+var DEFAULT_FLEET_GATEWAY_ORIGIN = "https://api.hasna.com";
+var DEFAULT_AUTHORITY_SOURCE = "default";
+function defaultFleetGatewayBaseUrl(name) {
+  return `${DEFAULT_FLEET_GATEWAY_ORIGIN}/${validateAppSlug(name)}`;
+}
+var ASCII_CONTROL_PATTERN = /[\u0000-\u001f\u007f]/;
+var DNS_LABEL_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+function isValidDnsDomain(value) {
+  if (value.length === 0 || value.length > 253 || ASCII_CONTROL_PATTERN.test(value) || /[^\x00-\x7f]/.test(value)) {
+    return false;
+  }
+  return value.split(".").every((label) => label.length <= 63 && !label.startsWith("xn--") && DNS_LABEL_PATTERN.test(label));
+}
+function validateAppSlug(name) {
+  if (name.length > 63 || !DNS_LABEL_PATTERN.test(name)) {
+    throw new Error("App name must be one lowercase DNS label.");
+  }
+  return name;
+}
+function rawAuthority(value) {
+  const match = /^[a-z][a-z0-9+.-]*:\/\//i.exec(value);
+  if (!match)
+    throw new Error("API URL must be absolute.");
+  const afterScheme = value.slice(match[0].length);
+  const boundary = afterScheme.search(/[/?#]/);
+  const authority = boundary === -1 ? afterScheme : afterScheme.slice(0, boundary);
+  if (!authority)
+    throw new Error("API URL must include a hostname.");
+  return authority;
+}
+function assertCanonicalPort(port) {
+  if (!/^[0-9]+$/.test(port) || port.length > 1 && port.startsWith("0")) {
+    throw new Error("API URL authority must contain a canonical port between 1 and 65535.");
+  }
+  const numericPort = Number(port);
+  if (!Number.isSafeInteger(numericPort) || numericPort < 1 || numericPort > 65535) {
+    throw new Error("API URL authority must contain a canonical port between 1 and 65535.");
+  }
+}
+function canonicalAuthorityHostname(authority) {
+  let rawHostname;
+  if (authority.startsWith("[")) {
+    const closingBracket = authority.indexOf("]");
+    if (closingBracket === -1) {
+      throw new Error("API URL authority must contain a canonical hostname.");
+    }
+    rawHostname = authority.slice(0, closingBracket + 1);
+    const portSuffix = authority.slice(closingBracket + 1);
+    if (portSuffix) {
+      if (!portSuffix.startsWith(":")) {
+        throw new Error("API URL authority must contain a canonical hostname and port.");
+      }
+      assertCanonicalPort(portSuffix.slice(1));
+    }
+    if (isIP(rawHostname.slice(1, -1)) !== 6) {
+      throw new Error("API URL authority must contain a canonical IPv6 literal.");
+    }
+  } else {
+    const firstColon = authority.indexOf(":");
+    const lastColon = authority.lastIndexOf(":");
+    if (firstColon !== lastColon) {
+      throw new Error("IPv6 API URL authorities must use brackets.");
+    }
+    if (lastColon !== -1) {
+      const port = authority.slice(lastColon + 1);
+      assertCanonicalPort(port);
+      rawHostname = authority.slice(0, lastColon);
+    } else {
+      rawHostname = authority;
+    }
+    const ipVersion = isIP(rawHostname);
+    const numericAddressParts = rawHostname.split(".");
+    const looksLikeNonCanonicalIpv4 = numericAddressParts.every((part) => /^(?:0x[0-9a-f]+|[0-9]+)$/i.test(part));
+    if (ipVersion !== 4 && looksLikeNonCanonicalIpv4 || ipVersion !== 4 && !isValidDnsDomain(rawHostname.toLowerCase())) {
+      throw new Error("API URL authority must contain a canonical ASCII hostname.");
+    }
+  }
+  return rawHostname.toLowerCase();
+}
+function isDeliberateLoopbackHttpAuthority(authority) {
+  return /^(?:localhost|127\.0\.0\.1|\[::1\])(?::[0-9]+)?$/i.test(authority);
+}
+function toV1BaseUrl(apiUrl) {
+  if (ASCII_CONTROL_PATTERN.test(apiUrl)) {
+    throw new Error("API URL must not contain ASCII control characters.");
+  }
+  const input = apiUrl.trim();
+  const authority = rawAuthority(input);
+  if (authority.includes("@") || authority.includes("\\") || authority.includes("%") || /[^\x00-\x7f]/.test(authority)) {
+    throw new Error("API URL authority must be canonical ASCII without credentials.");
+  }
+  const canonicalHostname = canonicalAuthorityHostname(authority);
+  const url = new URL(input);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("API URL must use http or https.");
+  }
+  if (url.username || url.password) {
+    throw new Error("API URL must not include credentials.");
+  }
+  if (!url.hostname || url.hostname.endsWith(".")) {
+    throw new Error("API URL must include a canonical hostname.");
+  }
+  if (url.hostname.toLowerCase() !== canonicalHostname) {
+    throw new Error("API URL authority must not rely on parser hostname normalization.");
+  }
+  if (url.hostname.split(".").some((label) => label.toLowerCase().startsWith("xn--"))) {
+    throw new Error("API URL must not use IDN or punycode hostnames.");
+  }
+  if (url.protocol === "http:" && !isDeliberateLoopbackHttpAuthority(authority)) {
+    throw new Error("API URL may use http only for an exact loopback authority.");
+  }
+  if (url.search || url.hash) {
+    throw new Error("API URL must not include a query string or fragment.");
+  }
+  let path = url.pathname.replace(/\/+$/, "");
+  if (path.endsWith("/v1"))
+    path = path.slice(0, -"/v1".length);
+  url.pathname = `${path}/v1`;
+  return url.toString().replace(/\/+$/, "");
+}
+class ClientTransportConfigurationError extends Error {
+  appName;
+  sources;
+  constructor(appName, message, sources = []) {
+    super(message);
+    this.name = "ClientTransportConfigurationError";
+    this.appName = appName;
+    this.sources = Object.freeze([...sources]);
+  }
+}
+function resolveClientTransportSnapshot(name, env = process.env, options = {}) {
+  env = snapshotClientEnvironment(name, env);
+  const keys = clientTransportEnvKeys(name);
+  const definedUrlEntries = keys.apiUrlKeys.filter((key) => Object.prototype.hasOwnProperty.call(env, key) && env[key] !== undefined).map((key) => ({ key, raw: String(env[key]) }));
+  const blankUrl = definedUrlEntries.find((entry) => entry.raw.trim().length === 0);
+  if (blankUrl) {
+    throw new ClientTransportConfigurationError(name, `${blankUrl.key} is set but blank; public clients require an explicit HTTPS API URL and never select local storage.`, [blankUrl.key]);
+  }
+  const controlledUrl = definedUrlEntries.find((entry) => ASCII_CONTROL_PATTERN.test(entry.raw));
+  if (controlledUrl) {
+    throw new ClientTransportConfigurationError(name, `${controlledUrl.key} contains ASCII control characters.`, [controlledUrl.key]);
+  }
+  const usableUrlEntries = definedUrlEntries.map((entry) => ({ key: entry.key, value: entry.raw.trim() }));
+  if (usableUrlEntries.length > 1 && new Set(usableUrlEntries.map((entry) => entry.value)).size > 1) {
+    throw new ClientTransportConfigurationError(name, `${usableUrlEntries.map((entry) => entry.key).join(" and ")} disagree; client authority aliases must be identical or only one may be set.`, usableUrlEntries.map((entry) => entry.key));
+  }
+  const envUrlHit = usableUrlEntries[0] ?? null;
+  const keychainUrlHit = keychainConfigValue(name, env, options.credentials?.keychain);
+  const diskConfigUrlHit = appConfigDiskValue(name, env, keys.apiUrlKeys);
+  if (diskConfigUrlHit?.unusable) {
+    throw new ClientTransportConfigurationError(name, `${diskConfigUrlHit.key} in ${diskConfigUrlHit.path} is declared but blank or malformed; public clients require a valid HTTPS service authority.`, [diskConfigUrlHit.path]);
+  }
+  const urlCandidates = [
+    ...envUrlHit ? [envUrlHit] : [],
+    ...keychainUrlHit ? [{ key: keychainUrlHit.source, value: keychainUrlHit.value }] : [],
+    ...diskConfigUrlHit ? [{ key: diskConfigUrlHit.path, value: diskConfigUrlHit.value.trim() }] : []
+  ];
+  const configuredUrl = urlCandidates[0] ?? null;
+  const divergentUrls = urlCandidates.filter((candidate) => candidate.value !== configuredUrl?.value);
+  if (configuredUrl && divergentUrls.length > 0) {
+    throw new ClientTransportConfigurationError(name, `${configuredUrl.key} and ${divergentUrls.map((candidate) => candidate.key).join(" and ")} select different service authorities; refusing to send a credential written for one authority to the other.`, urlCandidates.map((candidate) => candidate.key));
+  }
+  const warnings = [];
+  if (configuredUrl && !envUrlHit) {
+    warnings.push(`No ${keys.apiUrlKeys[0]} in the environment; the server URL in ${configuredUrl.key} was used, so this client connects to the server. ` + `Keep that entry aligned with the intended service authority.`);
+  }
+  const credential = resolveCredential(name, env, options.credentials);
+  if (!credential) {
+    const diskHint = credentialDiskSourcesForMessage(name, env);
+    const lead = configuredUrl ? `${configuredUrl.key} selects the HTTP server for '${name}', but no API key could be resolved` : `${keys.apiUrlKeys[0]} is not set and no API key could be resolved for '${name}'; a credential is required before the default fleet gateway authority applies`;
+    warnings.push(`${lead}; refusing to create an unauthenticated client \u2014 public clients never fall back to SQLite or another local store. ` + `Looked in the Keychain (macOS only), then for a credential file at ${diskHint}, then for ${keys.apiKeyKeys[0]} in the environment.`);
+    throw new ClientTransportConfigurationError(name, warnings.join(" "), [configuredUrl?.key ?? keys.apiUrlKeys[0]]);
+  }
+  if (credential.warning)
+    warnings.push(credential.warning);
+  let urlHit;
+  if (configuredUrl) {
+    urlHit = configuredUrl;
+  } else {
+    try {
+      urlHit = { key: DEFAULT_AUTHORITY_SOURCE, value: defaultFleetGatewayBaseUrl(name) };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new ClientTransportConfigurationError(name, `No ${keys.apiUrlKeys[0]} is configured and the default fleet gateway authority cannot be composed for '${name}': ${message}`, [keys.apiUrlKeys[0]]);
+    }
+  }
+  const apiUrlSource = urlHit.key;
+  let baseUrl;
+  try {
+    baseUrl = toV1BaseUrl(urlHit.value);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new ClientTransportConfigurationError(name, `Invalid API URL from ${apiUrlSource}: ${message}`, [apiUrlSource]);
+  }
+  return {
+    resolution: {
+      transport: "http",
+      transportSource: urlHit.key,
+      baseUrl,
+      apiUrlSource,
+      apiKeyPresent: true,
+      apiKeySource: credential.source,
+      apiKeyTier: credential.tier,
+      misconfigured: false,
+      warning: warnings.length > 0 ? warnings.join(" ") : null
+    },
+    credential
+  };
+}
+function resolveClientTransport(name, env = process.env, options = {}) {
+  return resolveClientTransportSnapshot(name, env, options).resolution;
+}
+function credentialDiskSourcesForMessage(name, env) {
+  const paths = credentialDiskSources(name, env);
+  return paths.length > 0 ? paths.join(" or ") : "<no HOME or HASNA_HOME set in this environment, so no credential file was consulted>";
+}
+var IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
+var AUTHORITY_OVERRIDE_HEADERS = new Set([
+  "host",
+  ":authority",
+  "forwarded",
+  "x-forwarded-host",
+  "x-original-host"
+]);
+
+// src/lib/local-opt-in.ts
+var MEMENTOS_LOCAL_OPT_IN_ENV_KEYS = ["HASNA_MEMENTOS_LOCAL", "MEMENTOS_LOCAL"];
+var MEMENTOS_DB_PATH_ENV_KEYS = ["HASNA_MEMENTOS_DB_PATH", "MEMENTOS_DB_PATH"];
+function isMementosLocalOptIn(env = process.env) {
+  return MEMENTOS_LOCAL_OPT_IN_ENV_KEYS.some((key) => (env[key] ?? "").trim() !== "");
+}
+function hasExplicitLocalDbPath(env = process.env) {
+  return MEMENTOS_DB_PATH_ENV_KEYS.some((key) => (env[key] ?? "").trim() !== "");
+}
+function mementosAuthorityEnvKeys() {
+  const keys = clientTransportEnvKeys("mementos");
+  return [
+    ...keys.apiUrlKeys,
+    ...keys.apiKeyKeys,
+    credentialOverrideEnvKey("mementos"),
+    credentialPointerEnvKey("mementos"),
+    CREDENTIAL_PROFILE_ENV_KEY
+  ];
+}
+function hasMementosEnvAuthorityIntent(env = process.env) {
+  return mementosAuthorityEnvKeys().some((key) => (env[key] ?? "").trim() !== "");
+}
+function selectsMementosLocalStore(env = process.env) {
+  if (hasExplicitLocalDbPath(env))
+    return true;
+  return !hasMementosEnvAuthorityIntent(env) && isMementosLocalOptIn(env);
+}
+function mementosResolverEnv(env) {
+  const blanks = mementosAuthorityEnvKeys().filter((key) => (key in env) && (env[key] ?? "").trim() === "");
+  if (blanks.length === 0)
+    return env;
+  const next = { ...env };
+  for (const key of blanks)
+    delete next[key];
+  return next;
+}
+var CONTRACTS_AMBIENT_ENVIRONMENT = Symbol.for("hasna:contracts:ambientClientEnvironment");
+function isAmbientMementosEnv(env) {
+  if (typeof process !== "undefined" && env === process.env)
+    return true;
+  return env[CONTRACTS_AMBIENT_ENVIRONMENT] === true;
+}
+function mementosResolverInputs(env, credentials = {}) {
+  const normalised = mementosResolverEnv(env);
+  if (normalised === env)
+    return { env: normalised, credentials };
+  const keychain = { ...credentials.keychain };
+  if (keychain.enabled === undefined && keychain.run === undefined) {
+    keychain.enabled = isAmbientMementosEnv(env);
+  }
+  return { env: normalised, credentials: { ...credentials, keychain } };
+}
+
 // src/sdk/index.ts
+var MEMENTOS_MACHINE_REGISTRATION_CONTRACT = "mementos.machine-registration.v1";
+var MEMENTOS_MACHINE_LIST_CONTRACT = "mementos.machines.v1";
+var MEMENTOS_MACHINE_MUTATION_CONTRACT = "mementos.machine-mutation.v1";
+var MEMENTOS_MACHINE_TOUCH_CONTRACT = "mementos.machine-touch.v1";
+
 class MementosError extends Error {
   status;
   details;
@@ -11,26 +1083,449 @@ class MementosError extends Error {
   }
 }
 
+class MementosConfigError extends Error {
+  code = "MEMENTOS_STORE_CONFIG";
+  constructor(message, options) {
+    super(message, options);
+    this.name = "MementosConfigError";
+  }
+}
+var SESSION_JOBS_PAGE_CONTRACT = "mementos.sessions.jobs.v2";
+function sdkProtocolError(operation, detail) {
+  return new MementosError(`mementos ${operation} returned a malformed 2xx response: ${detail}`, 502);
+}
+function sessionProtocolError(detail) {
+  return sdkProtocolError("session jobs", detail);
+}
+function auditSdkError(operation, error) {
+  if (error instanceof MementosError)
+    throw error;
+  const detail = error instanceof Error ? error.message : String(error);
+  throw sdkProtocolError(operation, detail);
+}
+function sdkAuditIdentifier(value, label) {
+  if (value === undefined)
+    return null;
+  if (!value || value.length > 512 || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw new AuditContractError(`${label} must be a non-empty printable string of at most 512 characters`);
+  }
+  return value;
+}
+function sdkAuditFilters(input) {
+  const filters = {
+    memory_id: sdkAuditIdentifier(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: sdkAuditIdentifier(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 sdkAuditCursor(cursor) {
+  if (cursor === undefined)
+    return;
+  if (!cursor || cursor.length > 4096 || !/^[A-Za-z0-9_-]+$/.test(cursor)) {
+    throw new AuditContractError("cursor must be a bounded base64url audit cursor");
+  }
+  return cursor;
+}
+function sdkAuditLimit(limit) {
+  if (limit === undefined)
+    return;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000) {
+    throw new AuditContractError("limit must be an integer between 1 and 1000");
+  }
+  return limit;
+}
+function sdkObject(value, operation, field = "response") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw sdkProtocolError(operation, `expected ${field} to be a JSON object`);
+  }
+  return value;
+}
+var SDK_MACHINE_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+function sdkMachineHostname(value, operation) {
+  const normalized = value.trim().replace(/\.+$/, "").toLowerCase();
+  if (!normalized || normalized.length > 253 || /[\u0000-\u001f\u007f/\\\s]/.test(normalized) || normalized !== value) {
+    throw sdkProtocolError(operation, "machine.hostname is not canonical");
+  }
+  return normalized;
+}
+function sdkMachinePlatform(value, operation) {
+  const normalized = value.trim().toLowerCase();
+  if (!normalized || normalized.length > 64 || !/^[a-z0-9._-]+$/.test(normalized) || normalized !== value) {
+    throw sdkProtocolError(operation, "machine.platform is not canonical");
+  }
+  return normalized;
+}
+function sdkMachineName(value, operation) {
+  if (typeof value !== "string" || !value || value.length > 128 || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw sdkProtocolError(operation, "machine.name is outside the public contract");
+  }
+  return value;
+}
+function sdkMachineTimestamp(value, operation, field) {
+  if (typeof value !== "string" || !SDK_MACHINE_TIMESTAMP.test(value)) {
+    throw sdkProtocolError(operation, `machine.${field} is not a canonical UTC timestamp`);
+  }
+  const parsed = new Date(value);
+  if (!Number.isFinite(parsed.getTime()) || parsed.toISOString() !== value) {
+    throw sdkProtocolError(operation, `machine.${field} is not a real calendar timestamp`);
+  }
+  return value;
+}
+function sdkMachine(value, operation) {
+  const machine = sdkObject(value, operation, "machine");
+  if (typeof machine["id"] !== "string" || !machine["id"]) {
+    throw sdkProtocolError(operation, "expected machine.id to be a non-empty string");
+  }
+  if (typeof machine["hostname"] !== "string" || typeof machine["platform"] !== "string") {
+    throw sdkProtocolError(operation, "expected machine hostname/platform strings");
+  }
+  if (typeof machine["is_primary"] !== "boolean") {
+    throw sdkProtocolError(operation, "expected machine.is_primary to be a boolean");
+  }
+  const createdAt = sdkMachineTimestamp(machine["created_at"], operation, "created_at");
+  const lastSeenAt = sdkMachineTimestamp(machine["last_seen_at"], operation, "last_seen_at");
+  if (lastSeenAt < createdAt)
+    throw sdkProtocolError(operation, "machine.last_seen_at precedes created_at");
+  return {
+    id: machine["id"],
+    name: sdkMachineName(machine["name"], operation),
+    hostname: sdkMachineHostname(machine["hostname"], operation),
+    platform: sdkMachinePlatform(machine["platform"], operation),
+    is_primary: machine["is_primary"],
+    created_at: createdAt,
+    last_seen_at: lastSeenAt
+  };
+}
+function sdkMachineMutation(value, operation, expectedId) {
+  const response = sdkObject(value, operation);
+  if (response["contract"] !== MEMENTOS_MACHINE_MUTATION_CONTRACT) {
+    throw sdkProtocolError(operation, `expected contract '${MEMENTOS_MACHINE_MUTATION_CONTRACT}'`);
+  }
+  const machine = sdkMachine(response["machine"], operation);
+  if (machine.id !== expectedId) {
+    throw sdkProtocolError(operation, "returned machine id does not match the requested stable id");
+  }
+  return machine;
+}
+function sessionObject(value, field = "response") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw sessionProtocolError(`expected ${field} to be a JSON object`);
+  }
+  return value;
+}
+function sessionString(object2, field, nullable = false) {
+  const value = object2[field];
+  if (nullable && value === null)
+    return null;
+  if (typeof value !== "string" || !nullable && value.length === 0) {
+    throw sessionProtocolError(`expected '${field}' to be ${nullable ? "a string or null" : "a non-empty string"}`);
+  }
+  return value;
+}
+function sessionCount(object2, field) {
+  const value = object2[field];
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw sessionProtocolError(`expected '${field}' to be a non-negative safe integer`);
+  }
+  return value;
+}
+function decodeSessionJob(value, index) {
+  const job = sessionObject(value, `jobs[${index}]`);
+  const source = sessionString(job, "source");
+  if (!["claude-code", "codex", "manual", "open-sessions"].includes(source)) {
+    throw sessionProtocolError(`jobs[${index}] has unsupported 'source'`);
+  }
+  const status = sessionString(job, "status");
+  if (!["pending", "processing", "completed", "failed"].includes(status)) {
+    throw sessionProtocolError(`jobs[${index}] has unsupported 'status'`);
+  }
+  const metadata = sessionObject(job["metadata"], `jobs[${index}].metadata`);
+  return {
+    id: sessionString(job, "id"),
+    session_id: sessionString(job, "session_id"),
+    agent_id: sessionString(job, "agent_id", true),
+    project_id: sessionString(job, "project_id", true),
+    source,
+    status,
+    transcript: typeof job["transcript"] === "string" ? job["transcript"] : (() => {
+      throw sessionProtocolError(`jobs[${index}] expected 'transcript' to be a string`);
+    })(),
+    chunk_count: sessionCount(job, "chunk_count"),
+    memories_extracted: sessionCount(job, "memories_extracted"),
+    error: sessionString(job, "error", true),
+    metadata,
+    created_at: sessionString(job, "created_at"),
+    started_at: sessionString(job, "started_at", true),
+    completed_at: sessionString(job, "completed_at", true)
+  };
+}
+function decodeSessionJobsPage(value) {
+  const page = sessionObject(value);
+  if (page["contract"] !== SESSION_JOBS_PAGE_CONTRACT) {
+    throw sessionProtocolError(`expected contract '${SESSION_JOBS_PAGE_CONTRACT}'`);
+  }
+  if (!Array.isArray(page["jobs"]))
+    throw sessionProtocolError("expected 'jobs' to be an array");
+  const jobs = page["jobs"].map(decodeSessionJob);
+  const count = sessionCount(page, "count");
+  const limit = sessionCount(page, "limit");
+  const offset = sessionCount(page, "offset");
+  if (limit < 1)
+    throw sessionProtocolError("expected 'limit' to be positive");
+  if (count !== jobs.length || count > limit) {
+    throw sessionProtocolError("page count is inconsistent with jobs/limit");
+  }
+  if (typeof page["has_more"] !== "boolean")
+    throw sessionProtocolError("expected 'has_more' to be a boolean");
+  const nextOffset = page["next_offset"];
+  if (nextOffset !== null && (!Number.isSafeInteger(nextOffset) || nextOffset < 0)) {
+    throw sessionProtocolError("expected 'next_offset' to be a non-negative safe integer or null");
+  }
+  if (page["has_more"] === true && nextOffset !== offset + jobs.length) {
+    throw sessionProtocolError("'has_more' requires the exact next offset");
+  }
+  if (page["has_more"] === false && nextOffset !== null) {
+    throw sessionProtocolError("terminal page must set 'next_offset' to null");
+  }
+  return {
+    contract: SESSION_JOBS_PAGE_CONTRACT,
+    jobs,
+    count,
+    limit,
+    offset,
+    has_more: page["has_more"],
+    next_offset: nextOffset
+  };
+}
+function decodeSessionIngestReceipt(value, transcript, expectedSessionId) {
+  const receipt = sessionObject(value);
+  if (receipt["contract"] !== "mementos.sessions.ingest.v2") {
+    throw sdkProtocolError("session ingest", "expected contract 'mementos.sessions.ingest.v2'");
+  }
+  const jobId = sessionString(receipt, "job_id");
+  if (receipt["status"] !== "queued")
+    throw sdkProtocolError("session ingest", "expected status 'queued'");
+  const message = sessionString(receipt, "message");
+  const rawJob = sessionObject(receipt["job"], "job");
+  const job = decodeSessionJob({ ...rawJob, transcript }, 0);
+  if (job.id !== jobId || job.session_id !== expectedSessionId) {
+    throw sdkProtocolError("session ingest", "job receipt identity does not match the request");
+  }
+  return {
+    contract: "mementos.sessions.ingest.v2",
+    job_id: jobId,
+    status: "queued",
+    message,
+    job
+  };
+}
+function decodeQueueStats(value) {
+  const stats = sessionObject(value);
+  return {
+    pending: sessionCount(stats, "pending"),
+    processing: sessionCount(stats, "processing"),
+    completed: sessionCount(stats, "completed"),
+    failed: sessionCount(stats, "failed")
+  };
+}
+var SDK_RESOURCE_TYPES = new Set(["project", "memory", "entity", "agent", "connector", "file"]);
+var SDK_LOCK_TYPES = new Set(["advisory", "exclusive"]);
+function decodeResourceLock(value, operation) {
+  const lock = sessionObject(value, "lock");
+  const resourceType = sessionString(lock, "resource_type");
+  const lockType = sessionString(lock, "lock_type");
+  if (!SDK_RESOURCE_TYPES.has(resourceType)) {
+    throw sdkProtocolError(operation, "unsupported 'resource_type'");
+  }
+  if (!SDK_LOCK_TYPES.has(lockType)) {
+    throw sdkProtocolError(operation, "unsupported 'lock_type'");
+  }
+  return {
+    id: sessionString(lock, "id"),
+    resource_type: resourceType,
+    resource_id: sessionString(lock, "resource_id"),
+    agent_id: sessionString(lock, "agent_id"),
+    lock_type: lockType,
+    locked_at: sessionString(lock, "locked_at"),
+    expires_at: sessionString(lock, "expires_at")
+  };
+}
+function decodeResourceLocks(value, operation) {
+  if (!Array.isArray(value))
+    throw sdkProtocolError(operation, "expected a JSON array");
+  return value.map((lock) => decodeResourceLock(lock, operation));
+}
+function decodeBooleanReceipt(value, field, operation) {
+  const receipt = sessionObject(value);
+  if (typeof receipt[field] !== "boolean")
+    throw sdkProtocolError(operation, `expected '${field}' to be a boolean`);
+  return { [field]: receipt[field] };
+}
+function decodeCountReceipt(value, field, operation) {
+  const receipt = sessionObject(value);
+  const count = receipt[field];
+  if (!Number.isSafeInteger(count) || count < 0) {
+    throw sdkProtocolError(operation, `expected '${field}' to be a non-negative safe integer`);
+  }
+  return { [field]: count };
+}
+var MEMENTOS_DEFAULT_BASE_URL = "http://localhost:19428";
+function resolveMementosApiBase(rawBaseUrl, explicitPrefix) {
+  const trimmed = (rawBaseUrl ?? MEMENTOS_DEFAULT_BASE_URL).trim().replace(/\/+$/, "") || MEMENTOS_DEFAULT_BASE_URL;
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    throw new Error("mementos base URL must be an absolute http(s) URL (the configured value does not parse as a URL)");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("mementos base URL must be an absolute http(s) URL");
+  }
+  if (url.username || url.password || url.search || url.hash || /[?#]/.test(trimmed)) {
+    throw new Error("mementos base URL must not contain userinfo, query, or fragment data");
+  }
+  const prefixMatch = /^(.*)(\/(?:v1|api))$/.exec(trimmed);
+  if (explicitPrefix !== undefined) {
+    const prefix = explicitPrefix.replace(/\/+$/, "");
+    const baseUrl = prefixMatch ? prefixMatch[1] || trimmed : trimmed;
+    return { baseUrl, prefix };
+  }
+  if (prefixMatch)
+    return { baseUrl: prefixMatch[1] || trimmed, prefix: prefixMatch[2] };
+  return { baseUrl: trimmed, prefix: "/v1" };
+}
+var localNoticePrinted = false;
+function __resetMementosSdkLocalNotice() {
+  localNoticePrinted = false;
+}
+function stripV1(baseUrl) {
+  return baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "");
+}
+function assertCleanSdkBase(baseUrl) {
+  if (/[?#]/.test(baseUrl)) {
+    throw new Error("mementos base URL must not contain userinfo, query, or fragment data");
+  }
+  return baseUrl;
+}
+function announceLocal(notice, reason) {
+  if (localNoticePrinted)
+    return;
+  localNoticePrinted = true;
+  const line = `mementos: LOCAL mode \u2014 reading and writing the on-box mementos-serve at ${MEMENTOS_DEFAULT_BASE_URL} ` + `(${reason}), not the hosted fleet. Unset it and set HASNA_MEMENTOS_API_KEY, add the Keychain item ` + `hasna.credentials.mementos.api-key, or write ~/.hasna/mementos/config/credentials to go hosted.`;
+  if (notice)
+    notice(line);
+  else if (typeof process !== "undefined")
+    process.stderr.write(`${line}
+`);
+}
+function unconfiguredSdkMessage() {
+  const keys = clientTransportEnvKeys("mementos");
+  const urlKey = keys.apiUrlKeys[0];
+  const keyKey = keys.apiKeyKeys[0];
+  return "mementos is not configured to reach any memory store, and will NOT fall back to the " + `on-box mementos-serve (${MEMENTOS_DEFAULT_BASE_URL}). ` + "No credential could be resolved from the Keychain item hasna.credentials.mementos.api-key " + `(macOS only), ~/.hasna/mementos/config/credentials, or ${keyKey}; the authority would be the ` + `fleet gateway https://api.hasna.com/mementos (or ${urlKey} if set). ` + `Set ${keyKey} (the resolver also accepts the legacy ${keys.apiKeyKeys[1]} alias for one release), ` + "add the Keychain item, or write the credentials file to use the fleet memory API, or opt into " + `the on-box mementos-serve with ${MEMENTOS_LOCAL_OPT_IN_ENV_KEYS[0]}=1 (or an explicit ` + `${MEMENTOS_DB_PATH_ENV_KEYS[0]}).`;
+}
+function resolveMementosSdkTransport(options = {}) {
+  const rawEnv = options.env ?? (typeof process !== "undefined" ? process.env : {});
+  const requestedCredentials = {
+    ...options.credentials,
+    ...options.apiKey !== undefined ? { apiKey: options.apiKey } : {}
+  };
+  const { env, credentials } = mementosResolverInputs(rawEnv, requestedCredentials);
+  if (options.baseUrl) {
+    return {
+      mode: "http",
+      baseUrl: stripV1(options.baseUrl),
+      apiKey: options.apiKey ?? null,
+      apiKeySource: options.apiKey ? "explicit apiKey argument" : null,
+      apiUrlSource: "explicit baseUrl argument"
+    };
+  }
+  if (selectsMementosLocalStore(env)) {
+    announceLocal(options.notice, "HASNA_MEMENTOS_LOCAL is set (or HASNA_MEMENTOS_DB_PATH) and nothing configures an authority");
+    return {
+      mode: "local-serve",
+      baseUrl: MEMENTOS_DEFAULT_BASE_URL,
+      apiKey: options.apiKey ?? null,
+      apiKeySource: options.apiKey ? "explicit apiKey argument" : null,
+      apiUrlSource: "local-serve"
+    };
+  }
+  let credential = null;
+  credential = resolveCredential("mementos", env, credentials);
+  const chainOptions = {
+    credentials: credential ? { ...credentials, apiKey: credential.apiKey } : credentials
+  };
+  let resolution;
+  try {
+    resolution = resolveClientTransport("mementos", env, chainOptions);
+  } catch (error) {
+    if (error instanceof ClientTransportConfigurationError && !credential && /is not set and no API key could be resolved/.test(error.message)) {
+      throw new MementosConfigError(unconfiguredSdkMessage(), { cause: error });
+    }
+    throw error;
+  }
+  return {
+    mode: "http",
+    baseUrl: stripV1(assertCleanSdkBase(resolution.baseUrl)),
+    apiKey: credential ? credential.apiKey : null,
+    apiKeySource: credential ? credential.source : resolution.apiKeySource,
+    apiUrlSource: resolution.apiUrlSource ?? "default"
+  };
+}
+
 class MementosClient {
-  baseUrl;
   _fetch;
   apiKey;
   prefix;
+  _resolveOptions;
+  _pinnedAuthority = null;
   constructor(config = {}) {
-    this.baseUrl = (config.baseUrl ?? "http://localhost:19428").replace(/\/$/, "");
+    const resolved = resolveMementosApiBase(config.baseUrl, config.prefix);
     this._fetch = config.fetch ?? globalThis.fetch.bind(globalThis);
     this.apiKey = config.apiKey;
-    this.prefix = (config.prefix ?? "/v1").replace(/\/$/, "");
+    this.prefix = resolved.prefix;
+    this._resolveOptions = {
+      ...config.baseUrl !== undefined ? { baseUrl: config.baseUrl } : {},
+      ...config.apiKey !== undefined ? { apiKey: config.apiKey } : {},
+      ...config.credentials !== undefined ? { credentials: config.credentials } : {},
+      ...config.env !== undefined ? { env: config.env } : {},
+      ...config.notice !== undefined ? { notice: config.notice } : {}
+    };
   }
   static fromEnv(overrides = {}) {
-    const env = typeof process !== "undefined" ? process.env : undefined;
-    const baseUrl = env?.["MEMENTOS_API_URL"] ?? env?.["MEMENTOS_URL"] ?? "http://localhost:19428";
-    const apiKey = env?.["MEMENTOS_API_KEY"];
-    return new MementosClient({ baseUrl, apiKey, ...overrides });
+    return new MementosClient(overrides);
+  }
+  get apiUrl() {
+    const transport = resolveMementosSdkTransport(this._resolveOptions);
+    const base = this.pinnedTarget(transport);
+    return `${base}${this.prefix}`;
+  }
+  currentTransport() {
+    return resolveMementosSdkTransport(this._resolveOptions);
+  }
+  targetOf(transport) {
+    return transport.mode === "http" ? transport.baseUrl : MEMENTOS_DEFAULT_BASE_URL;
+  }
+  pinnedTarget(transport) {
+    const target = this.targetOf(transport);
+    if (this._pinnedAuthority !== null && target !== this._pinnedAuthority) {
+      throw new MementosConfigError(`MEMENTOS_AUTHORITY_CHANGED: the configured service authority changed from ${this._pinnedAuthority} to ${target}. ` + "A credential is only ever sent to the authority it resolved with \u2014 construct a new client " + "before sending data (hasna/apps#1794).");
+    }
+    this._pinnedAuthority = target;
+    return target;
   }
   async request(method, path, body, query) {
+    const transport = this.currentTransport();
+    const baseUrl = this.pinnedTarget(transport);
+    const apiKey = transport.mode === "http" ? transport.apiKey ?? this.apiKey : this.apiKey;
     const routed = path.startsWith("/api/") ? `${this.prefix}${path.slice(4)}` : path;
-    let url = `${this.baseUrl}${routed}`;
+    let url = `${baseUrl}${routed}`;
     if (query) {
       const params = new URLSearchParams;
       for (const [k, v] of Object.entries(query)) {
@@ -44,9 +1539,9 @@ class MementosClient {
     const headers = {};
     if (body !== undefined)
       headers["Content-Type"] = "application/json";
-    if (this.apiKey) {
-      headers["Authorization"] = `Bearer ${this.apiKey}`;
-      headers["x-api-key"] = this.apiKey;
+    if (apiKey) {
+      headers["Authorization"] = `Bearer ${apiKey}`;
+      headers["x-api-key"] = apiKey;
     }
     const res = await this._fetch(url, {
       method,
@@ -108,6 +1603,8 @@ class MementosClient {
         q["agent_id"] = filter.agent_id;
       if (filter.project_id)
         q["project_id"] = filter.project_id;
+      if (filter.project_id && filter.include_unassigned_project)
+        q["include_unassigned_project"] = true;
       if (filter.session_id)
         q["session_id"] = filter.session_id;
       if (filter.namespace)
@@ -266,6 +1763,126 @@ class MementosClient {
   listAgentsByProject(projectId) {
     return this.get(`/api/agents`, { project_id: projectId });
   }
+  async getMemoryAuditTrail(memoryId, options = {}) {
+    const operation = "GET /v1/memories/:id/audit-trail";
+    try {
+      const filters = sdkAuditFilters({ memory_id: memoryId });
+      const requestedLimit = sdkAuditLimit(options.limit);
+      const limit = requestedLimit ?? AUDIT_DEFAULT_LIMIT;
+      const requestedCursor = sdkAuditCursor(options.cursor);
+      const cursor = requestedCursor ?? null;
+      const response = await this.get(`/api/memories/${encodeURIComponent(filters.memory_id)}/audit-trail`, { limit: requestedLimit, cursor: requestedCursor });
+      return validateAuditPage(response, { contract: AUDIT_TRAIL_CONTRACT, cursor, filters, limit });
+    } catch (error) {
+      return auditSdkError(operation, error);
+    }
+  }
+  async exportAuditLog(options = {}) {
+    const operation = "GET /v1/audit/export";
+    try {
+      const filters = sdkAuditFilters(options);
+      const requestedLimit = sdkAuditLimit(options.limit);
+      const limit = requestedLimit ?? AUDIT_DEFAULT_LIMIT;
+      const requestedCursor = sdkAuditCursor(options.cursor);
+      const cursor = requestedCursor ?? null;
+      const response = await this.get("/api/audit/export", {
+        since: filters.since ?? undefined,
+        until: filters.until ?? undefined,
+        operation: filters.operation ?? undefined,
+        agent_id: filters.agent_id ?? undefined,
+        limit: requestedLimit,
+        cursor: requestedCursor
+      });
+      return validateAuditPage(response, { contract: AUDIT_EXPORT_CONTRACT, cursor, filters, limit });
+    } catch (error) {
+      return auditSdkError(operation, error);
+    }
+  }
+  async getAuditStats() {
+    const operation = "GET /v1/audit/stats";
+    try {
+      return validateAuditStats(await this.get("/api/audit/stats"));
+    } catch (error) {
+      return auditSdkError(operation, error);
+    }
+  }
+  async listMachines() {
+    const operation = "GET /v1/machines";
+    const response = sdkObject(await this.get("/api/machines"), operation);
+    if (response["contract"] !== MEMENTOS_MACHINE_LIST_CONTRACT || response["complete"] !== true || !Array.isArray(response["machines"])) {
+      throw sdkProtocolError(operation, `expected contract '${MEMENTOS_MACHINE_LIST_CONTRACT}', complete=true, and a machines array`);
+    }
+    const machines = response["machines"].map((entry, index) => sdkMachine(entry, `${operation} machines[${index}]`));
+    if (!Number.isSafeInteger(response["count"]) || response["count"] !== machines.length) {
+      throw sdkProtocolError(operation, "count does not match machines.length");
+    }
+    if (new Set(machines.map((machine) => machine.id)).size !== machines.length || new Set(machines.map((machine) => machine.hostname)).size !== machines.length || new Set(machines.map((machine) => machine.name)).size !== machines.length) {
+      throw sdkProtocolError(operation, "machine ids, hostnames, or names are duplicated");
+    }
+    if (machines.filter((machine) => machine.is_primary).length > 1) {
+      throw sdkProtocolError(operation, "more than one machine is primary");
+    }
+    return { machines, count: machines.length, complete: true };
+  }
+  async registerMachine(input) {
+    const operation = "POST /v1/machines";
+    const response = sdkObject(await this.post("/api/machines", input), operation);
+    if (response["contract"] !== MEMENTOS_MACHINE_REGISTRATION_CONTRACT || typeof response["created"] !== "boolean") {
+      throw sdkProtocolError(operation, `expected contract '${MEMENTOS_MACHINE_REGISTRATION_CONTRACT}' and a boolean created receipt`);
+    }
+    const machine = sdkMachine(response["machine"], operation);
+    const identity = sdkObject(response["identity"], operation, "identity");
+    if (identity["idempotency_key"] !== "normalized_hostname" || identity["stable_id"] !== machine.id) {
+      throw sdkProtocolError(operation, "identity receipt does not match the stable machine id");
+    }
+    const expectedHostname = sdkMachineHostname(input.hostname.trim().replace(/\.+$/, "").toLowerCase(), operation);
+    const expectedPlatform = sdkMachinePlatform(input.platform.trim().toLowerCase(), operation);
+    if (machine.hostname !== expectedHostname || machine.platform !== expectedPlatform) {
+      throw sdkProtocolError(operation, "registration receipt does not match the requested hostname/platform");
+    }
+    if (response["created"] === true) {
+      const expectedName = input.name?.trim() || expectedHostname;
+      if (machine.name !== expectedName)
+        throw sdkProtocolError(operation, "created registration receipt does not match the requested name");
+    }
+    return machine;
+  }
+  async getMachine(id) {
+    return sdkMachineMutation(await this.get(`/api/machines/${encodeURIComponent(id)}`), "GET /v1/machines/:id", id);
+  }
+  async renameMachine(id, name) {
+    const normalizedName = name.trim();
+    const machine = sdkMachineMutation(await this.patch(`/api/machines/${encodeURIComponent(id)}`, { name: normalizedName }), "PATCH /v1/machines/:id", id);
+    if (machine.name !== normalizedName)
+      throw sdkProtocolError("PATCH /v1/machines/:id", "returned name does not match the requested rename");
+    return machine;
+  }
+  async setPrimaryMachine(id) {
+    const machine = sdkMachineMutation(await this.post(`/api/machines/${encodeURIComponent(id)}/primary`), "POST /v1/machines/:id/primary", id);
+    if (!machine.is_primary)
+      throw sdkProtocolError("POST /v1/machines/:id/primary", "returned machine is not primary");
+    return machine;
+  }
+  async touchMachine(id) {
+    const operation = "POST /v1/machines/:id/touch";
+    const response = sdkObject(await this.post(`/api/machines/${encodeURIComponent(id)}/touch`), operation);
+    if (response["contract"] !== MEMENTOS_MACHINE_TOUCH_CONTRACT || response["touched"] !== true || response["id"] !== id) {
+      throw sdkProtocolError(operation, "expected touched=true for the requested stable id");
+    }
+    const machine = sdkMachine(response["machine"], operation);
+    if (machine.id !== id || response["touched_at"] !== machine.last_seen_at) {
+      throw sdkProtocolError(operation, "touch receipt does not match the returned machine");
+    }
+    return machine;
+  }
+  async deleteMachine(id) {
+    const operation = "DELETE /v1/machines/:id";
+    const response = sdkObject(await this.delete(`/api/machines/${encodeURIComponent(id)}`), operation);
+    if (response["contract"] !== MEMENTOS_MACHINE_MUTATION_CONTRACT || response["deleted"] !== true || response["id"] !== id) {
+      throw sdkProtocolError(operation, "expected deleted=true for the requested stable id");
+    }
+    return { deleted: true, id };
+  }
   listProjects() {
     return this.get("/api/projects");
   }
@@ -486,30 +2103,30 @@ class MementosClient {
   }
   async acquireLock(input) {
     try {
-      return await this.post("/api/locks", input);
-    } catch (e) {
-      if (e instanceof Error && e.message.includes("409"))
+      return decodeResourceLock(await this.post("/api/locks", input), "lock acquire");
+    } catch (error) {
+      if (error instanceof MementosError && error.status === 409)
         return null;
-      throw e;
+      throw error;
     }
   }
-  checkLock(resourceType, resourceId, lockType) {
+  async checkLock(resourceType, resourceId, lockType) {
     const params = { resource_type: resourceType, resource_id: resourceId };
     if (lockType)
       params["lock_type"] = lockType;
-    return this.get("/api/locks", params);
+    return decodeResourceLocks(await this.get("/api/locks", params), "lock list");
   }
-  releaseLock(lockId, agentId) {
-    return this.request("DELETE", `/api/locks/${lockId}`, { agent_id: agentId });
+  async releaseLock(lockId, agentId) {
+    return decodeBooleanReceipt(await this.request("DELETE", `/api/locks/${encodeURIComponent(lockId)}`, { agent_id: agentId }), "released", "lock release");
   }
-  listAgentLocks(agentId) {
-    return this.get(`/api/agents/${agentId}/locks`);
+  async listAgentLocks(agentId) {
+    return decodeResourceLocks(await this.get(`/api/agents/${encodeURIComponent(agentId)}/locks`), "agent lock list");
   }
-  releaseAllAgentLocks(agentId) {
-    return this.request("DELETE", `/api/agents/${agentId}/locks`);
+  async releaseAllAgentLocks(agentId) {
+    return decodeCountReceipt(await this.request("DELETE", `/api/agents/${encodeURIComponent(agentId)}/locks`), "released", "agent lock release");
   }
-  cleanExpiredLocks() {
-    return this.post("/api/locks/clean", {});
+  async cleanExpiredLocks() {
+    return decodeCountReceipt(await this.post("/api/locks/clean", {}), "cleaned", "lock cleanup");
   }
   createTask(input) {
     return this.post("/api/tasks", input);
@@ -631,32 +2248,71 @@ class MementosClient {
   rollbackSynthesis(runId) {
     return this.post(`/api/synthesis/rollback/${runId}`, {});
   }
-  ingestSession(input) {
-    return this.post("/api/sessions/ingest", input);
+  async ingestSession(input) {
+    return decodeSessionIngestReceipt(await this.post("/api/sessions/ingest", input), input.transcript, input.session_id);
   }
-  getSessionJob(jobId) {
-    return this.get(`/api/sessions/jobs/${jobId}`);
+  async getSessionJob(jobId) {
+    return decodeSessionJob(await this.get(`/api/sessions/jobs/${encodeURIComponent(jobId)}`), 0);
   }
-  listSessionJobs(filter) {
+  async listSessionJobs(filter) {
     const params = new URLSearchParams;
     if (filter?.agent_id)
       params.set("agent_id", filter.agent_id);
     if (filter?.project_id)
       params.set("project_id", filter.project_id);
+    if (filter?.session_id)
+      params.set("session_id", filter.session_id);
     if (filter?.status)
       params.set("status", filter.status);
-    if (filter?.limit)
+    if (filter?.limit !== undefined)
       params.set("limit", String(filter.limit));
+    if (filter?.offset !== undefined)
+      params.set("offset", String(filter.offset));
     const qs = params.toString() ? `?${params.toString()}` : "";
-    return this.get(`/api/sessions/jobs${qs}`);
+    const response = await this.get(`/api/sessions/jobs${qs}`);
+    const page = decodeSessionJobsPage(response);
+    if (filter?.limit !== undefined && page.limit !== filter.limit) {
+      throw sessionProtocolError("server did not preserve requested 'limit'");
+    }
+    if (filter?.offset !== undefined && page.offset !== filter.offset) {
+      throw sessionProtocolError("server did not preserve requested 'offset'");
+    }
+    for (const job of page.jobs) {
+      if (filter?.agent_id !== undefined && job.agent_id !== filter.agent_id) {
+        throw sessionProtocolError("server did not preserve requested 'agent_id'");
+      }
+      if (filter?.project_id !== undefined && job.project_id !== filter.project_id) {
+        throw sessionProtocolError("server did not preserve requested 'project_id'");
+      }
+      if (filter?.session_id !== undefined && job.session_id !== filter.session_id) {
+        throw sessionProtocolError("server did not preserve requested 'session_id'");
+      }
+      if (filter?.status !== undefined && job.status !== filter.status) {
+        throw sessionProtocolError("server did not preserve requested 'status'");
+      }
+    }
+    return page;
   }
-  getSessionQueueStats() {
-    return this.get("/api/sessions/queue/stats");
+  async getSessionQueueStats() {
+    return decodeQueueStats(await this.get("/api/sessions/queue/stats"));
   }
 }
 var sdk_default = MementosClient;
 export {
+  resolveMementosSdkTransport,
+  resolveMementosApiBase,
   sdk_default as default,
+  __resetMementosSdkLocalNotice,
+  SESSION_JOBS_PAGE_CONTRACT,
   MementosError,
-  MementosClient
+  MementosConfigError,
+  MementosClient,
+  MEMENTOS_MACHINE_TOUCH_CONTRACT,
+  MEMENTOS_MACHINE_REGISTRATION_CONTRACT,
+  MEMENTOS_MACHINE_MUTATION_CONTRACT,
+  MEMENTOS_MACHINE_LIST_CONTRACT,
+  MEMENTOS_DEFAULT_BASE_URL,
+  AUDIT_TRAIL_CONTRACT as MEMENTOS_AUDIT_TRAIL_CONTRACT,
+  AUDIT_STATS_CONTRACT as MEMENTOS_AUDIT_STATS_CONTRACT,
+  AUDIT_EXPORT_CONTRACT as MEMENTOS_AUDIT_EXPORT_CONTRACT
 };