@hasna/recordings 0.3.2 → 0.3.9

package/dist/mcp/index.js

@@ -5054,9 +5054,118 @@ function setAgentFocus(idOrName, projectId, db) {
   d.query("UPDATE agents SET active_project_id = ?, last_seen_at = ? WHERE id = ?").run(resolvedProjectId, new Date().toISOString(), agent.id);
   return getAgent(agent.id, d);
 }
+// package.json
+var package_default = {
+  name: "@hasna/recordings",
+  version: "0.3.9",
+  type: "module",
+  description: "Speech-to-text recording tool with MCP and CLI \u2014 records, transcribes, and optionally enhances text using AI",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/hasna/apps"
+  },
+  main: "dist/index.js",
+  types: "dist/index.d.ts",
+  bin: {
+    recordings: "dist/cli/index.js",
+    "recordings-mcp": "dist/mcp/index.js",
+    "recordings-serve": "dist/server/index.js"
+  },
+  exports: {
+    ".": {
+      import: "./dist/index.js",
+      types: "./dist/index.d.ts"
+    },
+    "./storage": {
+      import: "./dist/storage.js",
+      types: "./dist/storage.d.ts"
+    },
+    "./sdk": {
+      import: "./dist/sdk/index.js",
+      types: "./dist/sdk/index.d.ts"
+    }
+  },
+  engines: {
+    bun: ">=1.0.0"
+  },
+  scripts: {
+    clean: "rm -rf dist",
+    build: "bun run clean && bun run build:cli && bun run build:mcp && bun run build:serve && bun run build:lib && tsc --emitDeclarationOnly --outDir dist",
+    "build:cli": "bun build src/cli/index.ts --target=bun --outfile=dist/cli/index.js --external=commander --external=chalk --external=openai",
+    "build:mcp": "bun build src/mcp/index.ts --target=bun --outfile=dist/mcp/index.js --external=@modelcontextprotocol/sdk --external=openai",
+    "build:serve": "bun build src/server/index.ts --target=bun --outfile=dist/server/index.js --external=@modelcontextprotocol/sdk --external=@hasna/contracts --external=openai --external=pg",
+    "build:lib": "bun build src/index.ts src/storage.ts src/sdk/index.ts --target=bun --outdir=dist --external=openai",
+    "build:native-fs-guard": "/bin/bash scripts/build_native_fs_guard.sh",
+    "generate:sdk": "bun run scripts/generate-sdk.ts",
+    migrate: "bun run scripts/migrate.ts",
+    typecheck: "tsc --noEmit",
+    "typecheck:tcc-contract": "tsc --noEmit -p tsconfig.tcc-contract.json",
+    test: "bun test",
+    "verify:ci-suite": "bun scripts/ci-linux-suite.ts --check",
+    "verify:ci-suite:run": "bun scripts/ci-linux-suite.ts --verify-run",
+    "verify:ci-native": "bun scripts/ci-native-build.ts",
+    "test:gated": 'bun scripts/ci-linux-suite.ts --check && RECORDINGS_TEST_TIMEOUT_MS="${RECORDINGS_TEST_TIMEOUT_MS:-120000}" bun test --timeout "$RECORDINGS_TEST_TIMEOUT_MS" $(bun scripts/ci-linux-suite.ts --gated)',
+    "test:vacuity-battery": 'bun scripts/vacuity-manifest-gen.ts > "${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv" && bun scripts/vacuity-mutation-battery.ts "${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv"',
+    "test:vacuity-battery:source": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/source-side.tsv",
+    "test:vacuity-battery:chain": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/install-chain.tsv",
+    "test:vacuity-battery:vars": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/variable-operands.tsv",
+    "test:vacuity-battery:reorder": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/reorder.tsv",
+    "test:coverage": "bun test --coverage",
+    "dev:cli": "bun run src/cli/index.ts",
+    "desktop:snapshot": "bun run src/cli/index.ts app snapshot",
+    "dev:mcp": "bun run src/mcp/index.ts",
+    "verify:release": "bun run scripts/release-guard.ts",
+    "scan:artifact": "bun run scripts/scan-artifact.ts",
+    "version:set": "bun run scripts/set-version.ts",
+    "version:check": "bun run scripts/set-version.ts --check",
+    prepack: "bun run prepack:platform-gate && bun run version:check && bun run build && bun run verify:release && bun run scan:artifact",
+    "prepack:platform-gate": `bash -c 'if [ "$(uname -s)" = Darwin ]; then bun run build:native-fs-guard; else echo "WARN: native fs-guard build skipped on $(uname -s) \u2014 dry-run/CI pack; publish recordings from macOS"; fi'`,
+    prepublishOnly: "bun run typecheck && bun run release-suite-gate",
+    "release-suite-gate": "bun run scripts/release-suite-gate.ts",
+    "typecheck:shortcut-contract": "tsc --noEmit -p tsconfig.test.json"
+  },
+  files: [
+    "dist/",
+    "scripts/",
+    "Dockerfile.package",
+    "bun.lock",
+    "src/native/Recordings/App/",
+    "src/native/Recordings/RecordingsLib/",
+    "src/native/Recordings/RecordingsTests/",
+    "src/native/Recordings/Updater/",
+    "src/native/Recordings/Package.swift",
+    "src/native/Recordings/Package.resolved",
+    "src/native/Recordings/build.sh",
+    "packaging/macos/",
+    "README.md",
+    "LICENSE"
+  ],
+  dependencies: {
+    "@hasna/contracts": "0.13.4",
+    "@hasna/events": "0.1.11",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    chalk: "^5.4.1",
+    commander: "^13.1.0",
+    openai: "^5.1.0",
+    pg: "^8.13.3",
+    zod: "^3.24.2"
+  },
+  devDependencies: {
+    "@types/bun": "^1.2.5",
+    "@types/pg": "^8.11.11",
+    "node-api-headers": "1.9.0",
+    typescript: "^5.8.2"
+  },
+  publishConfig: {
+    registry: "https://registry.npmjs.org",
+    access: "public"
+  },
+  license: "Apache-2.0",
+  author: "Hasna <andrei@hasna.com>"
+};
 
 // src/version.ts
-var VERSION = "0.3.2";
+var VERSION = package_default.version;
 
 // src/db/feedback.ts
 function saveFeedback(input) {
@@ -5064,59 +5173,207 @@ function saveFeedback(input) {
   db.query("INSERT INTO feedback (message, email, category, version) VALUES (?, ?, ?, ?)").run(input.message, input.email ?? null, input.category ?? "general", input.version ?? VERSION);
 }
 
-// src/lib/retired-deployment-modes.ts
-var RETIRED_DEPLOYMENT_MODES = [
-  "local",
-  "self_hosted",
-  "cloud",
-  "remote",
-  "hybrid"
-];
-function normalizeModeToken(value) {
-  return value.trim().toLowerCase().replace(/-/g, "_");
+// ../contracts/dist/client/transport.js
+import { isIP } from "net";
+import { readFileSync as readFileSync2, statSync as statSync2 } from "fs";
+import { join as join3 } from "path";
+function envToken(name) {
+  return name.toUpperCase().replace(/-/g, "_");
 }
-function asRetiredDeploymentMode(value) {
-  const token = normalizeModeToken(value);
-  return RETIRED_DEPLOYMENT_MODES.includes(token) ? token : null;
+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 retiredDeploymentModeError(rawValue, sourceEnvKey, replacement) {
-  const mode = asRetiredDeploymentMode(rawValue);
-  const value = mode === "local" ? replacement.onBox : replacement.offBox;
-  return new Error(`${sourceEnvKey}=${rawValue} names a deployment mode, and deployment modes are removed: ` + `${RETIRED_DEPLOYMENT_MODES.join(" | ")} no longer select anything. ` + `Set ${replacement.envKey}=${value} instead ` + `(${replacement.envKey} takes ${replacement.onBox} or ${replacement.offBox}).`);
+function credentialOverrideEnvKey(name) {
+  return `HASNA_${envToken(name)}_API_KEY_OVERRIDE`;
 }
+var CREDENTIAL_PROFILE_ENV_KEY = "HASNA_PROFILE";
 
-// src/http/client.ts
-var SERVER_BACKEND_VALUES = ["sqlite", "postgresql", "postgres"];
-function envToken(name) {
-  return name.toUpperCase().replace(/-/g, "_");
+class CredentialResolutionError extends Error {
+  appName;
+  attempted;
+  constructor(appName, message, attempted) {
+    super(message);
+    this.name = "CredentialResolutionError";
+    this.appName = appName;
+    this.attempted = attempted;
+  }
+}
+var HASNA_STATE_DIR = ".hasna";
+var FLEET_CREDENTIAL_DIR = "cloud";
+var CONFIG_DIR = ".config";
+var CONFIG_NAMESPACE = "hasna";
+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]/;
+function homeDir(env) {
+  const home = env.HOME?.trim();
+  return home ? home : null;
+}
+function credentialDiskSources(name, env) {
+  return profileDiskSources(name, env, null);
+}
+function profileDiskSources(name, env, profile) {
+  const home = homeDir(env);
+  if (!home || !SAFE_APP_SLUG.test(name))
+    return [];
+  const stem = profile ? `${name}.${profile}` : name;
+  const configStem = profile ? `${name}-${profile}` : name;
+  return [
+    join3(home, HASNA_STATE_DIR, FLEET_CREDENTIAL_DIR, `${stem}.env`),
+    join3(home, CONFIG_DIR, CONFIG_NAMESPACE, `${configStem}-cloud.env`)
+  ];
 }
-function clientStoreReplacement(envKey) {
-  return { envKey, onBox: "sqlite", offBox: "http" };
+function parseEnvFile(text) {
+  const values = new Map;
+  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))
+        continue;
+      value = value.slice(1, -1);
+    }
+    if (value.length === 0)
+      continue;
+    values.set(key, value);
+  }
+  return values;
 }
-function normalizeClientStore(value, sourceEnvKey, replacementEnvKey) {
-  const normalized = normalizeModeToken(value);
-  if (normalized === "sqlite")
-    return "sqlite";
-  if (normalized === "http" || normalized === "https")
-    return "http";
-  if (asRetiredDeploymentMode(value)) {
-    throw retiredDeploymentModeError(value, sourceEnvKey, clientStoreReplacement(replacementEnvKey));
+function readAppConfigFile(path) {
+  let text;
+  try {
+    const stats = statSync2(path);
+    if (!stats.isFile() || stats.size > MAX_CREDENTIAL_FILE_BYTES)
+      return null;
+    text = readFileSync2(path, "utf8");
+  } catch {
+    return null;
   }
-  throw new Error(`Unknown client store: ${value}. Use sqlite or http.`);
+  return parseEnvFile(text);
 }
-function defaultApiBaseUrl(name) {
-  return `http://localhost:8874`;
+function readCredentialFile(path, apiKeyKeys) {
+  const values = readAppConfigFile(path);
+  if (!values)
+    return null;
+  for (const key of apiKeyKeys) {
+    const value = values.get(key)?.trim();
+    if (value)
+      return value;
+  }
+  return null;
 }
-function envKeys(name) {
-  const token = envToken(name);
-  return {
-    storeKeys: [`HASNA_${token}_CLIENT_STORE`, `${token}_CLIENT_STORE`],
-    retiredModeKeys: [`HASNA_${token}_STORAGE_MODE`, `HASNA_${token}_MODE`, `${token}_STORAGE_MODE`, `${token}_MODE`],
-    apiUrlKeys: [`HASNA_${token}_API_URL`, `${token}_API_URL`],
-    apiKeyKeys: [`HASNA_${token}_API_KEY`, `${token}_API_KEY`]
+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 values = readAppConfigFile(path);
+    if (!values)
+      continue;
+    for (const key of wanted) {
+      const value = values.get(key)?.trim();
+      if (value)
+        return { key, value, path };
+    }
+  }
+  return null;
+}
+function assertUsableCredential(appName, source, value) {
+  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");
+var CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE = "caller-supplied CredentialProvider";
+function sealCredential(fields) {
+  const { apiKey } = fields;
+  const visible = {
+    tier: fields.tier,
+    source: fields.source,
+    deliberate: fields.deliberate,
+    deprecated: fields.deprecated,
+    diskCandidates: Object.freeze([...fields.diskCandidates]),
+    warning: fields.warning
   };
+  const sealed = { ...visible };
+  Object.defineProperty(sealed, "apiKey", {
+    value: apiKey,
+    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 isSealedCredential(credential) {
+  return credential[CREDENTIAL_SEAL] === true;
+}
+function explicitCredential(appName, apiKey) {
+  const source = "explicit apiKey option";
+  assertUsableCredential(appName, source, apiKey);
+  return sealCredential({
+    apiKey,
+    tier: "argument",
+    source,
+    deliberate: true,
+    deprecated: false,
+    diskCandidates: [],
+    warning: null
+  });
 }
-function firstEnv(env, keys) {
+function validateAndSealResolvedCredential(appName, credential) {
+  const apiKey = credential.apiKey;
+  assertUsableCredential(appName, CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE, apiKey);
+  if (!isSealedCredential(credential)) {
+    return sealCredential({
+      apiKey,
+      tier: "argument",
+      source: CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE,
+      deliberate: true,
+      deprecated: false,
+      diskCandidates: [],
+      warning: null
+    });
+  }
+  return sealCredential({
+    apiKey,
+    tier: credential.tier,
+    source: credential.source,
+    deliberate: credential.deliberate,
+    deprecated: credential.deprecated,
+    diskCandidates: credential.diskCandidates,
+    warning: credential.warning
+  });
+}
+function firstEnvValue(env, keys) {
   for (const key of keys) {
     const value = env[key]?.trim();
     if (value)
@@ -5124,71 +5381,343 @@ function firstEnv(env, keys) {
   }
   return null;
 }
-function assertNoRetiredMode(env, keys) {
-  for (const key of keys.retiredModeKeys) {
-    const value = env[key]?.trim();
-    if (!value)
-      continue;
-    const normalized = normalizeModeToken(value);
-    if (SERVER_BACKEND_VALUES.includes(normalized))
-      continue;
-    if (asRetiredDeploymentMode(value)) {
-      throw retiredDeploymentModeError(value, key, clientStoreReplacement(keys.storeKeys[0]));
+var DEPRECATION_REGISTRY = Symbol.for("hasna:contracts:credentialDeprecationNotices");
+function deprecationNotified() {
+  const host = globalThis;
+  const existing = host[DEPRECATION_REGISTRY];
+  if (existing instanceof Set)
+    return existing;
+  const created = new Set;
+  host[DEPRECATION_REGISTRY] = created;
+  return created;
+}
+function defaultDeprecationSink(message) {
+  if (typeof process !== "undefined" && process.stderr) {
+    process.stderr.write(`${message}
+`);
+  }
+}
+function resolveCredential(name, env, options = {}) {
+  const { apiKeyKeys } = clientTransportEnvKeys(name);
+  const diskPaths = credentialDiskSources(name, env);
+  const explicitKey = options.apiKey?.trim();
+  if (explicitKey) {
+    assertUsableCredential(name, "the explicit apiKey argument", explicitKey);
+    return sealCredential({
+      apiKey: explicitKey,
+      tier: "argument",
+      source: "explicit apiKey argument",
+      deliberate: true,
+      deprecated: false,
+      diskCandidates: diskPaths,
+      warning: null
+    });
+  }
+  const overrideKeyName = credentialOverrideEnvKey(name);
+  const overrideRaw = env[overrideKeyName];
+  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,
+      deprecated: false,
+      diskCandidates: diskPaths,
+      warning: null
+    });
+  }
+  const profile = options.profile?.trim() || env[CREDENTIAL_PROFILE_ENV_KEY]?.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,
+          deprecated: false,
+          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 diskHits = diskPaths.map((path) => ({ path, value: readCredentialFile(path, apiKeyKeys) })).filter((hit) => hit.value !== null);
+  if (diskHits.length > 0) {
+    const winner = diskHits[0];
+    assertUsableCredential(name, winner.path, winner.value);
+    const divergentSources = [
+      ...diskHits.slice(1).filter((hit) => hit.value !== winner.value).map((hit) => hit.path),
+      ...(() => {
+        const legacyHit = firstEnvValue(env, apiKeyKeys);
+        return legacyHit && legacyHit.value !== winner.value ? [legacyHit.key] : [];
+      })()
+    ];
+    const warning = divergentSources.length > 0 ? `Credential sources disagree for '${name}': ${winner.path} and ` + `${divergentSources.join(", ")} hold different keys. ${winner.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: "disk",
+      source: winner.path,
+      deliberate: false,
+      deprecated: false,
+      diskCandidates: diskPaths,
+      warning
+    });
+  }
+  const legacy = firstEnvValue(env, apiKeyKeys);
+  if (legacy) {
+    assertUsableCredential(name, legacy.key, legacy.value);
+    const where = diskPaths.length > 0 ? `Put the current key in ${diskPaths[0]} \u2014 it is re-read on every call, so rotations take effect immediately.` : `This environment has no HOME, so no credential file could be consulted at all; the disk tier is ` + `unavailable here and this process will keep using the environment snapshot.`;
+    const message = `[${name}] DEPRECATED: the API key came from ${legacy.key} in this process's environment. ` + `Environment variables are a snapshot taken when this process started, so a shell that started ` + `before a key rotation keeps using the old key until it exits. ${where}`;
+    const sink = options.onDeprecation ?? defaultDeprecationSink;
+    const notified = deprecationNotified();
+    if (!notified.has(name)) {
+      notified.add(name);
+      sink(message);
+    }
+    return sealCredential({
+      apiKey: legacy.value,
+      tier: "legacy-env",
+      source: legacy.key,
+      deliberate: false,
+      deprecated: true,
+      diskCandidates: diskPaths,
+      warning: message
+    });
+  }
+  return null;
+}
+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 firstEnv(env, keys, options = {}) {
+  for (const key of keys) {
+    const raw = env[key];
+    const value = raw?.trim();
+    if (value)
+      return { key, value: options.preserveRaw ? raw : value };
+  }
+  return null;
+}
+function firstEnvDefinedKey(env, keys) {
+  for (const key of keys) {
+    if (env[key] !== undefined)
+      return key;
+  }
+  return null;
+}
+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.");
     }
-    throw new Error(`${key}=${value} is not a client store. ${key} no longer selects one; ` + `set ${keys.storeKeys[0]}=sqlite or ${keys.storeKeys[0]}=http instead.`);
   }
+  return rawHostname.toLowerCase();
+}
+function isDeliberateLoopbackHttpAuthority(authority) {
+  return /^(?:localhost|127\.0\.0\.1|\[::1\])(?::[0-9]+)?$/i.test(authority);
 }
 function toV1BaseUrl(apiUrl) {
-  const url = new URL(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`;
-  url.search = "";
-  url.hash = "";
   return url.toString().replace(/\/+$/, "");
 }
-function resolveTransport(name, env = process.env) {
-  const keys = envKeys(name);
-  assertNoRetiredMode(env, keys);
-  const storeHit = firstEnv(env, keys.storeKeys);
-  const urlHit = firstEnv(env, keys.apiUrlKeys);
+function resolveClientTransport(name, env = process.env, options = {}) {
+  const keys = clientTransportEnvKeys(name);
+  const envUrlHit = firstEnv(env, keys.apiUrlKeys, { preserveRaw: true });
+  const explicitLocalKey = envUrlHit ? null : firstEnvDefinedKey(env, keys.apiUrlKeys);
+  const diskUrlHit = envUrlHit || explicitLocalKey ? null : appConfigDiskValue(name, env, keys.apiUrlKeys);
+  const urlHit = envUrlHit ?? (diskUrlHit ? { key: diskUrlHit.path, value: diskUrlHit.value } : null);
   const keyHit = firstEnv(env, keys.apiKeyKeys);
-  let requested = "sqlite";
-  let modeSource = "default";
-  if (storeHit) {
-    requested = normalizeClientStore(storeHit.value, storeHit.key, keys.storeKeys[0]);
-    modeSource = storeHit.key;
-  } else if (urlHit && keyHit) {
-    requested = "http";
-    modeSource = "auto:api-url+api-key";
+  const warnings = [];
+  if (!urlHit) {
+    if (explicitLocalKey) {
+      const overriddenPointer = appConfigDiskValue(name, env, keys.apiUrlKeys);
+      if (overriddenPointer) {
+        warnings.push(`${explicitLocalKey} is defined but blank, which selects the local store. ` + `The server URL in ${overriddenPointer.path} was NOT selected: an explicit blank wins over a disk pointer.`);
+      }
+      return {
+        transport: "sqlite",
+        transportSource: explicitLocalKey,
+        baseUrl: null,
+        apiUrlSource: null,
+        apiKeyPresent: Boolean(keyHit),
+        apiKeySource: keyHit ? keyHit.key : null,
+        apiKeyTier: null,
+        misconfigured: false,
+        warning: warnings.length > 0 ? warnings.join(" ") : null
+      };
+    }
+    return {
+      transport: "sqlite",
+      transportSource: "default",
+      baseUrl: null,
+      apiUrlSource: null,
+      apiKeyPresent: Boolean(keyHit),
+      apiKeySource: keyHit ? keyHit.key : null,
+      apiKeyTier: null,
+      misconfigured: false,
+      warning: null
+    };
   }
-  if (requested === "sqlite") {
-    return { transport: "sqlite", requested, modeSource, baseUrl: null, apiKeyPresent: Boolean(keyHit), misconfigured: false, warning: null };
+  if (diskUrlHit) {
+    warnings.push(`No ${keys.apiUrlKeys[0]} in the environment; the server URL in ${diskUrlHit.path} was used, so this client connects to the server. ` + `Unset the pointer or remove the file to stay on the local store.`);
   }
-  if (!keyHit) {
+  const credential = resolveCredential(name, env, options.credentials);
+  if (!credential) {
+    const diskHint = credentialDiskSourcesForMessage(name, env);
+    warnings.push(`${urlHit.key} selects the HTTP server for '${name}', but no API key could be resolved; ` + `refusing to route and leaving the local sqlite store selected. ` + `Looked for a credential file at ${diskHint}, then for ${keys.apiKeyKeys[0]} in the environment.`);
     return {
       transport: "sqlite",
-      requested,
-      modeSource,
+      transportSource: urlHit.key,
       baseUrl: null,
+      apiUrlSource: urlHit.key,
       apiKeyPresent: false,
+      apiKeySource: null,
+      apiKeyTier: null,
       misconfigured: true,
-      warning: `${modeSource}=http but no API key is set (${keys.apiKeyKeys[0]}). Refusing to route to the API.`
+      warning: warnings.join(" ")
     };
   }
-  const rawUrl = urlHit?.value ?? defaultApiBaseUrl(name);
+  if (credential.warning)
+    warnings.push(credential.warning);
+  const apiUrlSource = urlHit.key;
   let baseUrl;
   try {
-    baseUrl = toV1BaseUrl(rawUrl);
+    baseUrl = toV1BaseUrl(urlHit.value);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    return { transport: "sqlite", requested, modeSource, baseUrl: null, apiKeyPresent: true, misconfigured: true, warning: `Invalid API URL: ${message}.` };
+    warnings.push(`Invalid API URL from ${apiUrlSource}: ${message}. Using local store.`);
+    return {
+      transport: "sqlite",
+      transportSource: urlHit.key,
+      baseUrl: null,
+      apiUrlSource: urlHit.key,
+      apiKeyPresent: true,
+      apiKeySource: credential.source,
+      apiKeyTier: credential.tier,
+      misconfigured: true,
+      warning: warnings.join(" ")
+    };
   }
-  return { transport: "http", requested, modeSource, baseUrl, apiKeyPresent: true, misconfigured: false, warning: null };
+  return {
+    transport: "http",
+    transportSource: urlHit.key,
+    baseUrl,
+    apiUrlSource,
+    apiKeyPresent: true,
+    apiKeySource: credential.source,
+    apiKeyTier: credential.tier,
+    misconfigured: false,
+    warning: warnings.length > 0 ? warnings.join(" ") : null
+  };
+}
+function credentialDiskSourcesForMessage(name, env) {
+  const paths = credentialDiskSources(name, env);
+  return paths.length > 0 ? paths.join(" or ") : "<no HOME set in this environment, so no credential file was consulted>";
 }
 
 class HasnaHttpError extends Error {
@@ -5196,49 +5725,113 @@ class HasnaHttpError extends Error {
   method;
   path;
   body;
-  constructor(method, path, status, body) {
-    super(`Hasna request failed: ${method} ${path} -> ${status}`);
+  credentialSource;
+  credentialTier;
+  constructor(method, path, status, body, credential) {
+    const guidance = credential ? `. ${credential.guidance}` : "";
+    super(`Hasna cloud request failed: ${method} ${path} -> ${status}${guidance}`);
     this.name = "HasnaHttpError";
     this.status = status;
     this.method = method;
     this.path = path;
     this.body = body;
+    this.credentialSource = credential?.source ?? null;
+    this.credentialTier = credential?.tier ?? null;
+  }
+}
+function currentCredential(name, apiKey) {
+  if (typeof apiKey === "function") {
+    return validateAndSealResolvedCredential(name, apiKey());
+  }
+  return explicitCredential(name, apiKey);
+}
+function authFailureGuidance(credential) {
+  const origin = `The API key for this request came from ${credential.source}`;
+  if (credential.deliberate) {
+    const remedy = credential.source === CALLER_SUPPLIED_CREDENTIAL_PROVIDER_SOURCE ? `Fix that provider so it returns the current key, or replace it with resolveCredential() ` + `so diagnostics can name the original source.` : `Rotate that key, or unset the override to use the credential on disk.`;
+    return `${origin} \u2014 a credential you selected deliberately. It was NOT substituted with any other key: ` + `falling back here would authenticate as a different principal than the one you named, which is ` + `exactly the failure an override exists to prevent. ${remedy}`;
+  }
+  if (credential.deprecated) {
+    const target = credential.diskCandidates[0];
+    const remedy = target ? `Write the CURRENT key to ${target} \u2014 that file is re-read on every call, so rotations take ` + `effect immediately and in every shell. Do not simply unset ${credential.source}: nothing was ` + `found on disk, so that would leave this client with no credential at all.` : `This environment has no HOME, so no credential file could be consulted; the disk tier is ` + `unavailable here and there is nothing to fall back to. Set HOME, or supply the key explicitly.`;
+    return `${origin}, a variable in this process's environment \u2014 which is a snapshot taken when the process ` + `started. A STALE SHELL is the most common cause of this error: this shell exported the key before ` + `it was rotated, and will keep sending the old one until it exits. ${remedy}`;
+  }
+  return `${origin}, which was re-read from disk on this very call \u2014 so a stale shell is NOT the cause here. ` + `The stored credential is genuinely being rejected: rotate it, or re-run the fleet key distribution ` + `so this machine gets the current key.`;
+}
+var DEFAULT_RETRY_STATUSES = [408, 425, 429, 500, 502, 503, 504];
+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"
+]);
+function assertNoAuthorityOverrideHeaders(headers, source) {
+  if (!headers)
+    return;
+  const forbidden = Object.keys(headers).find((name) => AUTHORITY_OVERRIDE_HEADERS.has(name.trim().toLowerCase()));
+  if (forbidden) {
+    throw new Error(`Authenticated ${source} headers must not set authority header '${forbidden}'.`);
   }
 }
 function appendQuery(path, query) {
   if (!query)
     return path;
-  const params = new URLSearchParams;
-  for (const [key, value] of Object.entries(query)) {
-    if (value === null || value === undefined)
-      continue;
-    if (Array.isArray(value))
-      for (const v of value)
-        params.append(key, String(v));
-    else
-      params.append(key, String(value));
+  const params = query instanceof URLSearchParams ? query : new URLSearchParams;
+  if (!(query instanceof URLSearchParams)) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === null || value === undefined)
+        continue;
+      if (Array.isArray(value)) {
+        for (const v of value)
+          params.append(key, String(v));
+      } else {
+        params.append(key, String(value));
+      }
+    }
   }
   const qs = params.toString();
-  return qs ? `${path}${path.includes("?") ? "&" : "?"}${qs}` : path;
+  if (!qs)
+    return path;
+  return `${path}${path.includes("?") ? "&" : "?"}${qs}`;
 }
-var RETRY_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
-var IDEMPOTENT = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
-var defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
-function createHttpTransport(options) {
+var defaultSleep = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
+function createHasnaHttpTransport(options) {
   const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
-  const base = options.baseUrl.replace(/\/+$/, "");
+  const base = toV1BaseUrl(options.baseUrl);
   const timeoutMs = options.timeoutMs ?? 30000;
   const sleep = options.sleepImpl ?? defaultSleep;
-  async function once(method, rel, url, body, opts) {
+  const defaultRetry = options.retry;
+  function resolveRetry(callRetry) {
+    const chosen = callRetry !== undefined ? callRetry : defaultRetry;
+    if (chosen === false)
+      return null;
+    const r = chosen ?? {};
+    return {
+      retries: r.retries ?? 2,
+      baseDelayMs: r.baseDelayMs ?? 200,
+      maxDelayMs: r.maxDelayMs ?? 2000,
+      retryStatuses: r.retryStatuses ?? [...DEFAULT_RETRY_STATUSES]
+    };
+  }
+  async function once(method, rel, url, body, opts, credential) {
+    assertNoAuthorityOverrideHeaders(options.headers, "transport");
+    assertNoAuthorityOverrideHeaders(opts.headers, "request");
     const headers = {
-      "x-api-key": options.apiKey,
-      Authorization: `Bearer ${options.apiKey}`,
+      "x-api-key": credential.apiKey,
+      Authorization: `Bearer ${credential.apiKey}`,
       Accept: "application/json",
+      ...options.headers ?? {},
       ...opts.headers ?? {}
     };
     if (opts.idempotencyKey)
       headers["Idempotency-Key"] = opts.idempotencyKey;
-    const init = { method, headers };
+    const init = {
+      method,
+      headers,
+      redirect: "manual"
+    };
     if (body !== undefined) {
       headers["Content-Type"] = "application/json";
       init.body = JSON.stringify(body);
@@ -5276,7 +5869,27 @@ function createHttpTransport(options) {
       }
     }
     if (!response.ok) {
-      return { ok: false, retryable: RETRY_STATUSES.has(response.status), error: new HasnaHttpError(method, rel, response.status, parsed) };
+      if (response.status >= 300 && response.status < 400) {
+        return {
+          ok: false,
+          retryable: false,
+          error: new HasnaHttpError(method, rel, response.status, parsed)
+        };
+      }
+      if (response.status === 401 || response.status === 403) {
+        return {
+          ok: false,
+          retryable: false,
+          error: new HasnaHttpError(method, rel, response.status, parsed, {
+            source: credential.source,
+            tier: credential.tier,
+            guidance: authFailureGuidance(credential)
+          })
+        };
+      }
+      const retry = resolveRetry(opts.retry);
+      const retryable = retry ? retry.retryStatuses.includes(response.status) : false;
+      return { ok: false, retryable, error: new HasnaHttpError(method, rel, response.status, parsed) };
     }
     return { ok: true, value: parsed };
   }
@@ -5284,24 +5897,23 @@ function createHttpTransport(options) {
     const upper = method.toUpperCase();
     const rel = appendQuery(path.startsWith("/") ? path : `/${path}`, opts.query);
     const url = `${base}${rel}`;
-    const methodRetryable = IDEMPOTENT.has(upper) || Boolean(opts.idempotencyKey);
-    const maxRetries = opts.retries ?? 2;
-    const maxAttempts = methodRetryable ? maxRetries + 1 : 1;
+    const retry = resolveRetry(opts.retry);
+    const methodRetryable = IDEMPOTENT_METHODS.has(upper) || Boolean(opts.idempotencyKey);
+    const maxAttempts = retry && methodRetryable ? retry.retries + 1 : 1;
+    const credential = currentCredential(options.name, options.apiKey);
     let last = null;
     for (let attempt = 1;attempt <= maxAttempts; attempt++) {
-      const result = await once(upper, rel, url, body, opts);
+      const result = await once(upper, rel, url, body, opts, credential);
       if (result.ok)
         return result.value;
       last = result;
-      const canRetry = methodRetryable && result.retryable && attempt < maxAttempts;
+      const canRetry = retry !== null && methodRetryable && result.retryable && attempt < maxAttempts;
       if (!canRetry)
         break;
-      const backoff = Math.min(2000, 200 * 2 ** (attempt - 1));
+      const backoff = Math.min(retry.maxDelayMs, retry.baseDelayMs * 2 ** (attempt - 1));
       const jitter = Math.floor(Math.random() * (backoff / 2 + 1));
       await sleep(backoff + jitter);
     }
-    if (last === null)
-      throw new Error(`Request to ${rel} completed without a result`);
     throw last.error;
   }
   return {
@@ -5309,81 +5921,289 @@ function createHttpTransport(options) {
     request,
     get: (path, opts) => request("GET", path, undefined, opts),
     post: (path, body, opts) => request("POST", path, body, opts),
-    patch: (path, body, opts) => request("PATCH", path, body, opts),
     put: (path, body, opts) => request("PUT", path, body, opts),
+    patch: (path, body, opts) => request("PATCH", path, body, opts),
     del: (path, body, opts) => request("DELETE", path, body, opts)
   };
 }
+function createClientTransport(name, env = process.env, overrides) {
+  const credentialOptions = overrides?.credentials;
+  const resolution = resolveClientTransport(name, env, { ...credentialOptions ? { credentials: credentialOptions } : {} });
+  if (resolution.misconfigured) {
+    throw new Error(resolution.warning ?? `Client for '${name}' is misconfigured for the API client.`);
+  }
+  if (resolution.transport === "sqlite" || !resolution.baseUrl) {
+    return { transport: "sqlite", client: null, resolution };
+  }
+  const credentialProvider = () => {
+    const resolved = resolveCredential(name, env, credentialOptions);
+    if (!resolved) {
+      throw new Error(`Client for '${name}' resolved to the http transport but no API key is available any more. ` + `Looked at ${credentialDiskSourcesForMessage(name, env)}, then the environment. ` + `A credential file that was removed after this client was built is the usual cause.`);
+    }
+    return resolved;
+  };
+  return {
+    transport: "http",
+    client: createHasnaHttpTransport({
+      name,
+      baseUrl: resolution.baseUrl,
+      apiKey: credentialProvider,
+      ...overrides?.fetchImpl ? { fetchImpl: overrides.fetchImpl } : {},
+      ...overrides?.headers ? { headers: overrides.headers } : {},
+      ...overrides?.timeoutMs ? { timeoutMs: overrides.timeoutMs } : {},
+      ...overrides?.retry !== undefined ? { retry: overrides.retry } : {},
+      ...overrides?.sleepImpl ? { sleepImpl: overrides.sleepImpl } : {}
+    }),
+    resolution
+  };
+}
+
+// ../contracts/dist/client/storage.js
+var MAX_CREDENTIAL_FILE_BYTES2 = 64 * 1024;
+var INSPECT_CUSTOM2 = Symbol.for("nodejs.util.inspect.custom");
+var CREDENTIAL_SEAL2 = Symbol.for("hasna:contracts:sealedCredential");
+var DEPRECATION_REGISTRY2 = Symbol.for("hasna:contracts:credentialDeprecationNotices");
+var IDEMPOTENT_METHODS2 = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
+var AUTHORITY_OVERRIDE_HEADERS2 = new Set([
+  "host",
+  ":authority",
+  "forwarded",
+  "x-forwarded-host",
+  "x-original-host"
+]);
+function resourcePath(resource) {
+  const trimmed = resource.replace(/^\/+|\/+$/g, "");
+  if (!trimmed)
+    throw new Error("resource must be a non-empty path segment");
+  return `/${trimmed}`;
+}
+function entityPath(resource, id) {
+  if (id === undefined || id === null || `${id}`.length === 0) {
+    throw new Error("id must be a non-empty string");
+  }
+  return `${resourcePath(resource)}/${encodeURIComponent(String(id))}`;
+}
 function newIdempotencyKey() {
   const g = globalThis;
   if (g.crypto?.randomUUID)
     return g.crypto.randomUUID();
   return `idmp_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 12)}`;
 }
-function extractItems(raw, extraKeys = []) {
+function extractItems(raw) {
   if (Array.isArray(raw))
     return raw;
   if (raw && typeof raw === "object") {
     const obj = raw;
-    for (const key of [...extraKeys, "items", "data", "results", "rows", "records"]) {
+    for (const key of ["items", "data", "results", "rows", "records"]) {
       if (Array.isArray(obj[key]))
         return obj[key];
     }
   }
   return [];
 }
-function createStorageClient(name, transport) {
-  const rp = (r) => `/${r.replace(/^\/+|\/+$/g, "")}`;
-  const ep = (r, id) => `${rp(r)}/${encodeURIComponent(String(id))}`;
+function extractTotal(raw) {
+  if (raw && typeof raw === "object") {
+    const obj = raw;
+    for (const key of ["total", "count", "totalCount", "total_count"]) {
+      if (typeof obj[key] === "number")
+        return obj[key];
+    }
+  }
+  return null;
+}
+function extractCursor(raw) {
+  if (raw && typeof raw === "object") {
+    const obj = raw;
+    for (const key of ["cursor", "nextCursor", "next_cursor", "next"]) {
+      if (typeof obj[key] === "string")
+        return obj[key];
+    }
+  }
+  return null;
+}
+function isNotFoundHttpError(error) {
+  return typeof error === "object" && error !== null && error.name === "HasnaHttpError" && error.status === 404;
+}
+function createHasnaStorageClient(name, transport) {
   return {
     name,
     baseUrl: transport.baseUrl,
     transport,
-    async list(resource, query) {
-      const raw = await transport.get(rp(resource), { query });
-      return { items: extractItems(raw, [resource]), raw };
+    async list(resource, options = {}) {
+      const raw = await transport.get(resourcePath(resource), options);
+      return {
+        items: extractItems(raw),
+        total: extractTotal(raw),
+        cursor: extractCursor(raw),
+        raw
+      };
     },
-    async get(resource, id) {
+    async get(resource, id, options = {}) {
       try {
-        return await transport.get(ep(resource, id));
+        return await transport.get(entityPath(resource, id), options);
       } catch (error) {
-        if (error instanceof HasnaHttpError && error.status === 404)
+        if (isNotFoundHttpError(error))
           return null;
         throw error;
       }
     },
-    async create(resource, body, idempotencyKey) {
-      return transport.post(rp(resource), body, { idempotencyKey: idempotencyKey ?? newIdempotencyKey() });
+    async create(resource, body, options = {}) {
+      const { idempotencyKey, ...rest } = options;
+      return transport.post(resourcePath(resource), body, {
+        ...rest,
+        idempotencyKey: idempotencyKey ?? newIdempotencyKey()
+      });
     },
-    async update(resource, id, patch, method = "PATCH") {
+    async update(resource, id, patch, options = {}) {
+      const { method = "PATCH", idempotencyKey, ...rest } = options;
       const call = method === "PUT" ? transport.put : transport.patch;
-      return call(ep(resource, id), patch);
+      return call(entityPath(resource, id), patch, { ...rest, ...idempotencyKey ? { idempotencyKey } : {} });
     },
-    async delete(resource, id) {
+    async delete(resource, id, options = {}) {
       try {
-        await transport.del(ep(resource, id));
+        await transport.del(entityPath(resource, id), undefined, options);
       } catch (error) {
-        if (error instanceof HasnaHttpError && error.status === 404)
+        if (isNotFoundHttpError(error))
           return;
         throw error;
       }
     }
   };
 }
-function resolveStorageClient(name, env = process.env, fetchImpl) {
+
+// src/http/client.ts
+function envToken2(name) {
+  return name.toUpperCase().replace(/-/g, "_");
+}
+function envKeys(name) {
+  const token = envToken2(name);
+  return {
+    storeKeys: [`HASNA_${token}_CLIENT_STORE`, `${token}_CLIENT_STORE`],
+    apiUrlKeys: [`HASNA_${token}_API_URL`],
+    apiKeyKeys: [`HASNA_${token}_API_KEY`]
+  };
+}
+function normalizeClientStore(value) {
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "sqlite")
+    return "sqlite";
+  if (normalized === "http" || normalized === "https")
+    return "http";
+  throw new Error(`Unknown client store: ${value}. Use sqlite or http.`);
+}
+function firstEnv2(env, keys) {
+  for (const key of keys) {
+    const value = env[key]?.trim();
+    if (value)
+      return { key, value };
+  }
+  return null;
+}
+function toV1BaseUrl2(apiUrl) {
+  const url = new URL(apiUrl);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("API URL must use http or https.");
+  }
+  let path = url.pathname.replace(/\/+$/, "");
+  if (path.endsWith("/v1"))
+    path = path.slice(0, -"/v1".length);
+  url.pathname = `${path}/v1`;
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/+$/, "");
+}
+function resolveTransport(name, env = process.env) {
+  const keys = envKeys(name);
+  const storeHit = firstEnv2(env, keys.storeKeys);
+  const urlHit = firstEnv2(env, keys.apiUrlKeys);
+  const keyHit = firstEnv2(env, keys.apiKeyKeys);
+  let requested = "sqlite";
+  let modeSource = "default";
+  if (storeHit) {
+    requested = normalizeClientStore(storeHit.value);
+    modeSource = storeHit.key;
+  } else if (urlHit && keyHit) {
+    requested = "http";
+    modeSource = "auto:api-url+api-key";
+  } else if (urlHit || keyHit) {
+    const missing = urlHit ? keys.apiKeyKeys[0] : keys.apiUrlKeys[0];
+    const present = urlHit ? keys.apiUrlKeys[0] : keys.apiKeyKeys[0];
+    return {
+      transport: "sqlite",
+      requested,
+      modeSource,
+      baseUrl: null,
+      apiKeyPresent: Boolean(keyHit),
+      misconfigured: true,
+      warning: `${present} is set but ${missing} is not: the hosted API is only ` + `selected when BOTH are present. Set ${missing}, or unset ${present} to ` + `use the on-box store.`
+    };
+  }
+  if (requested === "sqlite") {
+    return { transport: "sqlite", requested, modeSource, baseUrl: null, apiKeyPresent: Boolean(keyHit), misconfigured: false, warning: null };
+  }
+  if (!urlHit) {
+    return {
+      transport: "sqlite",
+      requested,
+      modeSource,
+      baseUrl: null,
+      apiKeyPresent: Boolean(keyHit),
+      misconfigured: true,
+      warning: `${modeSource}=http but no API URL is set (${keys.apiUrlKeys[0]}). Refusing to route to the API.`
+    };
+  }
+  if (!keyHit) {
+    return {
+      transport: "sqlite",
+      requested,
+      modeSource,
+      baseUrl: null,
+      apiKeyPresent: false,
+      misconfigured: true,
+      warning: `${modeSource}=http but no API key is set (${keys.apiKeyKeys[0]}). Refusing to route to the API.`
+    };
+  }
+  const rawUrl = urlHit.value;
+  let baseUrl;
+  try {
+    baseUrl = toV1BaseUrl2(rawUrl);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { transport: "sqlite", requested, modeSource, baseUrl: null, apiKeyPresent: true, misconfigured: true, warning: `Invalid API URL: ${message}.` };
+  }
+  return { transport: "http", requested, modeSource, baseUrl, apiKeyPresent: true, misconfigured: false, warning: null };
+}
+var RETRY_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+var IDEMPOTENT = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
+function resolveStoreClient(name, env = process.env) {
   const resolution = resolveTransport(name, env);
   if (resolution.misconfigured) {
+    const wired2 = createClientTransport(name, env);
+    if (wired2.transport === "http") {
+      return {
+        transport: "http",
+        client: createHasnaStorageClient(name, wired2.client),
+        resolution: {
+          transport: "http",
+          requested: "http",
+          modeSource: resolution.modeSource === "default" ? "auto:api-url+seam-credential" : resolution.modeSource,
+          baseUrl: wired2.resolution.baseUrl,
+          apiKeyPresent: true,
+          misconfigured: false,
+          warning: null
+        }
+      };
+    }
     throw new Error(resolution.warning ?? `Client for '${name}' is misconfigured for the /v1 API.`);
   }
   if (resolution.transport === "sqlite" || !resolution.baseUrl) {
     return { transport: "sqlite", client: null, resolution };
   }
-  const keys = envKeys(name);
-  const apiKey = firstEnv(env, keys.apiKeyKeys)?.value;
-  if (!apiKey)
+  const wired = createClientTransport(name, env);
+  if (wired.transport !== "http") {
     throw new Error(`Client for '${name}' resolved to the /v1 API without an API key.`);
-  const transport = createHttpTransport({ name, baseUrl: resolution.baseUrl, apiKey, ...fetchImpl ? { fetchImpl } : {} });
-  return { transport: "http", client: createStorageClient(name, transport), resolution };
+  }
+  return { transport: "http", client: createHasnaStorageClient(name, wired.client), resolution };
 }
 
 // src/store.ts
@@ -5466,6 +6286,22 @@ var localStore = {
     await withLocalStoreReaderLease(() => saveFeedback(input));
   }
 };
+async function listResource(client, resource, query) {
+  const raw = await client.transport.get(`/${resource}`, query ? { query } : undefined);
+  return { items: extractEnvelopeItems(raw, resource), raw };
+}
+function extractEnvelopeItems(raw, resource) {
+  if (Array.isArray(raw))
+    return raw;
+  if (raw && typeof raw === "object") {
+    const obj = raw;
+    for (const key of [resource, "items", "data", "results", "rows", "records"]) {
+      if (Array.isArray(obj[key]))
+        return obj[key];
+    }
+  }
+  return [];
+}
 function apiStore(client) {
   return {
     mode: "http",
@@ -5473,7 +6309,7 @@ function apiStore(client) {
     async createRecording(input, idempotencyKey) {
       const keyCandidate = idempotencyKey === undefined && (input.id === undefined || input.id === null) ? randomUUID2() : idempotencyKey;
       const identity = recordingCreateIdentity(input, keyCandidate, { bindIdempotencyKeyToId: false });
-      const res = await client.create("recordings", identity.input, identity.idempotencyKey);
+      const res = await client.create("recordings", identity.input, { idempotencyKey: identity.idempotencyKey });
       return unwrap(res, "recording");
     },
     async getRecording(id) {
@@ -5481,7 +6317,7 @@ function apiStore(client) {
       return res ? unwrap(res, "recording") : null;
     },
     async listRecordings(filter) {
-      const { items } = await client.list("recordings", listQuery(filter));
+      const { items } = await listResource(client, "recordings", listQuery(filter));
       return items;
     },
     async countRecordings(filter) {
@@ -5492,7 +6328,7 @@ function apiStore(client) {
       const seenPageKeys = new Set;
       while (pageRequests < maxPageRequests) {
         pageRequests += 1;
-        const { items, raw } = await client.list("recordings", {
+        const { items, raw } = await listResource(client, "recordings", {
           ...listQuery(filter),
           limit: pageLimit,
           offset
@@ -5515,7 +6351,7 @@ function apiStore(client) {
       throw new Error(`Recordings API exceeded ${maxPageRequests} pages while counting legacy results`);
     },
     async searchRecordings(query, filter) {
-      const { items } = await client.list("recordings", listQuery({ ...filter ?? {}, search: query }));
+      const { items } = await listResource(client, "recordings", listQuery({ ...filter ?? {}, search: query }));
       return items;
     },
     async deleteRecording(id) {
@@ -5547,7 +6383,7 @@ function apiStore(client) {
       return res ? unwrap(res, "agent") : null;
     },
     async listAgents() {
-      const { items } = await client.list("agents");
+      const { items } = await listResource(client, "agents");
       return items;
     },
     async heartbeatAgent(idOrName) {
@@ -5587,7 +6423,7 @@ function apiStore(client) {
       return res ? unwrap(res, "project") : null;
     },
     async listProjects() {
-      const { items } = await client.list("projects");
+      const { items } = await listResource(client, "projects");
       return items;
     },
     async saveFeedback(input) {
@@ -5635,7 +6471,7 @@ var cached = null;
 function getStore(env = process.env) {
   if (env === process.env && cached)
     return cached;
-  const resolved = resolveStorageClient(APP, env);
+  const resolved = resolveStoreClient(APP, env);
   const store = resolved.transport === "http" ? apiStore(resolved.client) : localStore;
   if (env === process.env)
     cached = store;