@aaes-ai/govern-sdk 0.0.0-stage → 0.2.0

package/aaes.mjs

@@ -0,0 +1,1722 @@
+/**
+ * aaes - a thin, honest JavaScript/TypeScript client for the AAES HTTP
+ * contract. Dependency-free: the global fetch and nothing else.
+ *
+ * What it is
+ * ----------
+ * One client, one action: name a capability and an action, get the daemon's
+ * decision. The client holds a base URL, a bearer token and the caller's
+ * identity as the daemon stated it, and nothing else. No policy, no registry,
+ * no credential, no verification.
+ *
+ * What it deliberately does not do
+ * --------------------------------
+ * - No caller-supplied destination, method or credential. `action()` refuses any
+ *   key it does not document, so a url, a method, a header or a token cannot be
+ *   smuggled in; the endpoint and the token are configuration (the constructor
+ *   or fromEnv). The payload is checked against the same field-name families
+ *   the daemon refuses, so the mistake is caught before the request leaves the
+ *   process.
+ * - No identity claim. The client asks the daemon who the caller is
+ *   (GET /v1/capabilities, once per client) and fills tenant_id and actor_id
+ *   from the daemon's own answer. Nothing lets you write a different tenant or
+ *   actor.
+ * - No verification. Receipts, record hashes and grants are returned as the
+ *   daemon's bytes; this module checks none of them and says so. Evidence is
+ *   verified offline with AAES out of the trust path: verifyHint() renders the
+ *   command, aaesctl verify --export ... --pubkey ...
+ * - No retry that could double an effect. A call that can produce an effect is
+ *   retried only when you opted in (RetryPolicy), the daemon answered 503,
+ *   and the identical call carries its original effect key
+ *   the daemon committed the first attempt under, so a repeat is refused with
+ *   409 rather than performed twice. 409, 403, 401 and 400 are never retried.
+ *   requestAccess carries no effect key on the daemon side, so it is never
+ *   retried at all.
+ *
+ * A refusal is an answer
+ * ----------------------
+ * A decision the daemon refused is returned as a Decision with allowed false
+ * and refusal set: the daemon's reason VERBATIM plus the smallest change that
+ * would satisfy it, derived only from what the daemon itself published (the
+ * entitled slice, the requestable catalog). A thrown AaesError means no answer
+ * arrived at all.
+ *
+ * Usage
+ * -----
+ *   import { Client } from "./aaes.mjs";
+ *
+ *   const client = Client.fromEnv();            // AAES_ENDPOINT, AAES_TOKEN
+ *   const decision = await client.action({
+ *     capability: "payments.transfer",
+ *     action: "invoke",
+ *     taskId: "task-demo",
+ *     effectKeyStep: "charge-invoice-4471",
+ *     payload: { invoice_id: "4471" },
+ *   });
+ *   if (decision.ok) console.log(decision.grant.grantId, decision.receipt.recordHash);
+ *   else console.log(String(decision.refusal)); // reason + smallest change
+ */
+
+export const ENDPOINT_ENV = "AAES_ENDPOINT";
+export const TOKEN_ENV = "AAES_TOKEN";
+
+const PATH_ACTION = "/v1/action";
+const PATH_RESUME = "/v1/action/resume";
+const PATH_BROKERED = "/v1/brokered";
+const PATH_BROKERED_RESUME = "/v1/brokered/resume";
+const PATH_GRANT_PRESENT = "/v1/grants/present";
+const PATH_FEDERATE = "/v1/federate";
+const PATH_OBSERVE = "/v1/observe";
+const PATH_CAPABILITIES = "/v1/capabilities";
+const PATH_CATALOGUE = "/v1/catalogue";
+const PATH_ACCESS_REQUESTS = "/v1/access-requests";
+const PATH_HEALTHZ = "/healthz";
+const PATH_READYZ = "/readyz";
+
+const MAX_RESPONSE_BYTES = 4 << 20;
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** Refusal advice reads only snapshots this client already holds, and a
+ * catalogue snapshot stops speaking for the catalogue after this window, the
+ * same sixty seconds the Python SDK uses. */
+const CATALOGUE_SNAPSHOT_FRESH_MS = 60_000;
+
+/** Statuses a resume route reads WITHOUT decoding: a 404 maps to a refusal
+ * whether the body is the daemon's JSON or an older daemon's (or a proxy's)
+ * plain text, so the mapping can never depend on a parse that already ran. */
+const UNDECODED_404 = new Set([404]);
+
+/** The frozen effect classes (internal/types/effect.go). Never recomputed here. */
+export const EFFECT_DENIED = 0;
+export const EFFECT_MINTED_UNUSED = 1;
+export const EFFECT_EXECUTED = 2;
+export const EFFECT_AUTHORIZED = 3;
+export const EFFECT_DEFERRED = 4;
+
+/** No answer arrived, or the answer could not be read. */
+export class AaesError extends Error {}
+
+/** The payload named a destination, a request shape or a credential. */
+export class CallerRouteError extends AaesError {}
+
+/**
+ * Your explicit opt-in for retry. The default means one attempt.
+ *
+ * The rule a policy can turn on, and nothing more: a read, or a call that
+ * presents an effect key, is repeated after a 503 - always presenting the SAME
+ * key, so the daemon refuses a duplicate with 409 instead of performing it
+ * twice. Anything else is attempted once.
+ */
+export class RetryPolicy {
+  constructor({ maxAttempts = 1, baseDelayMs = 200 } = {}) {
+    this.maxAttempts = maxAttempts;
+    this.baseDelayMs = baseDelayMs;
+  }
+
+  /** Three attempts with a small backoff. Never the default: retrying is your
+   * decision and not this module's. */
+  static default() {
+    return new RetryPolicy({ maxAttempts: 3, baseDelayMs: 200 });
+  }
+
+  attempts(identified, answer503) {
+    if (this.maxAttempts <= 1 || !identified || answer503) return 1;
+    return this.maxAttempts;
+  }
+
+  delay(attempt) {
+    return this.baseDelayMs * 2 ** (attempt - 1);
+  }
+}
+
+/** A decision the daemon refused: its sentence VERBATIM, plus the smallest
+ * change that would satisfy it, derived only from what the daemon published. */
+export class Refusal {
+  constructor(status, reason, advice = [], retryable = false) {
+    this.status = status;
+    this.reason = reason;
+    this.advice = advice;
+    this.retryable = retryable;
+  }
+
+  smallestChange() {
+    return this.advice.join("; ");
+  }
+
+  toString() {
+    const head = `refused with HTTP ${this.status}: ${this.reason}`;
+    return this.advice.length ? `${head}; smallest change that would satisfy it: ${this.advice.join("; ")}` : head;
+  }
+}
+
+/** A client decision. A refusal is an answer, not an exception. */
+export class Decision {
+  constructor(fields = {}) {
+    this.allowed = false;
+    this.deferred = false;
+    this.reason = "";
+    this.intentId = "";
+    this.grant = null;
+    this.receipt = null;
+    this.latencyAddedMs = 0;
+    this.refusal = null;
+    Object.assign(this, fields);
+  }
+
+  get ok() {
+    return this.allowed && !this.deferred && this.refusal === null;
+  }
+}
+
+/** A federated call's request: ONE capability, ONE action and ONE task.
+ *
+ * There is deliberately no field for a URL, a destination, a method, a header or
+ * a credential. Unknown keys are REFUSED before a request is sent (see
+ * refuseUnknownKeys and FEDERATE_KEYS): the daemon resolves the target from the
+ * capability registration and the credential from its own custody. */
+const FEDERATE_KEYS = new Set([
+  "capability", "action", "taskId", "effectKeyStep", "amountMinor", "amountCurrency", "grantTtlMs",
+  "rotate", "correlationId",
+]);
+
+/** One STS request the WORKLOAD performs with its own identity. AAES built it
+ * and did not send it: the subject token is the workload's own. */
+export class FederatedInstructions {
+  constructor(fields = {}) {
+    this.backend = "";
+    this.method = "";
+    this.url = "";
+    this.headers = {};
+    this.form = {};
+    this.json = {};
+    this.subjectTokenIn = "";
+    this.subjectTokenField = "";
+    this.subjectTokenType = "";
+    this.durationSeconds = 0;
+    this.documentation = "";
+    this.notBuilt = [];
+    this.notes = [];
+    Object.assign(this, fields);
+  }
+
+  toString() {
+    if (!this.method) return "instructions (none)";
+    return "instructions " + this.method + " " + this.url + " (subject token in " +
+      this.subjectTokenIn + " field " + JSON.stringify(this.subjectTokenField) + "; shape from " +
+      this.documentation + ")";
+  }
+
+  toJSON() {
+    return { backend: this.backend, method: this.method, url: this.url, subjectTokenField: this.subjectTokenField };
+  }
+}
+
+/** The credential, or the instructions to obtain it. It is the ONE value in this
+ * module that must never be logged: toString, toJSON and the Node inspector all
+ * REDACT it, and nothing else in this file prints it. */
+export class FederatedMaterial {
+  constructor(fields = {}) {
+    this.kind = "";
+    this.credential = new Uint8Array(0);
+    this.instructions = null;
+    this.expiresAt = "";
+    this.audience = "";
+    Object.assign(this, fields);
+  }
+
+  toString() {
+    if (this.kind === "credential") {
+      return "federated material (credential, " + this.credential.length + " bytes, expires " +
+        (this.expiresAt || "no declared expiry") + ", REDACTED)";
+    }
+    if (this.kind === "instructions") {
+      return this.instructions === null
+        ? "federated material (instructions, none)"
+        : "federated material (" + this.instructions.toString() + ")";
+    }
+    return "federated material (none)";
+  }
+
+  toJSON() {
+    return { kind: this.kind, redacted: true, expiresAt: this.expiresAt, audience: this.audience };
+  }
+
+  [Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toString();
+  }
+}
+
+/** A federated grant: the material (or the instructions), the locator, the exact
+ * scope, the expiry and the intent id. The material is a FIELD and never appears
+ * in a render. */
+export class FederatedGrant {
+  constructor(fields = {}) {
+    this.federationId = "";
+    this.intentId = "";
+    this.decisionGrantId = "";
+    this.tenantId = "";
+    this.actorId = "";
+    this.capability = "";
+    this.capabilityVersion = "";
+    this.actions = [];
+    this.resourceId = "";
+    this.taskId = "";
+    this.dataClass = "";
+    this.tier = "";
+    this.spendCapMinor = null;
+    this.spendCapMinorPresent = false;
+    this.spendCapCurrency = "";
+    this.scopeKey = "";
+    this.backend = "";
+    this.locator = { capability: "", endpoint: "", method: "", authority: "", resourceId: "" };
+    this.issuedAt = "";
+    this.expiresAt = "";
+    this.ttlSeconds = 0;
+    this.material = new FederatedMaterial();
+    this.record = { intentId: "", mode: "", payloadSeen: false, markerReceiptHash: "", receiptId: "" };
+    Object.assign(this, fields);
+  }
+
+  /** The exact authority the grant carries, for a caller that wants to log WHAT
+   * was authorized without logging the material. */
+  scope() {
+    return {
+      capability: this.capability,
+      actions: [...this.actions],
+      resourceId: this.resourceId,
+      dataClass: this.dataClass,
+      tier: this.tier,
+      spendCapMinor: this.spendCapMinor,
+      spendCapMinorPresent: this.spendCapMinorPresent,
+      spendCapCurrency: this.spendCapCurrency,
+      scopeKey: this.scopeKey,
+    };
+  }
+
+  toString() {
+    return "federated grant " + this.federationId + " for " + this.tenantId + "/" + this.actorId +
+      " capability=" + this.capability + " actions=" + JSON.stringify(this.actions) +
+      " resource=" + this.resourceId + " task=" + this.taskId + " expires=" + this.expiresAt +
+      " mode=" + this.record.mode + " material=" + this.material.toString();
+  }
+
+  toJSON() {
+    return {
+      federation_id: this.federationId,
+      intent_id: this.intentId,
+      decision_grant_id: this.decisionGrantId,
+      tenant_id: this.tenantId,
+      actor_id: this.actorId,
+      capability: this.capability,
+      actions: this.actions,
+      resource_id: this.resourceId,
+      task_id: this.taskId,
+      data_class: this.dataClass,
+      tier: this.tier,
+      scope_key: this.scopeKey,
+      backend: this.backend,
+      locator: this.locator,
+      issued_at: this.issuedAt,
+      expires_at: this.expiresAt,
+      ttl_seconds: this.ttlSeconds,
+      material: this.material.toJSON(),
+      record: this.record,
+    };
+  }
+
+  [Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toString();
+  }
+}
+
+// --- the payload tripwire --------------------------------------------------
+
+const DESTINATION_FIELDS = new Set([
+  "url", "uri", "endpoint", "endpointurl", "endpointuri", "host", "hostname",
+  "hostport", "authority", "domain", "baseurl", "baseuri", "targeturl",
+  "targeturi", "destination", "destinationurl", "dest", "desturl", "proxy",
+  "proxyurl", "origin", "originurl", "server", "serverurl", "address", "addr",
+  "ip", "redirect", "redirecturl", "callback", "callbackurl", "webhook",
+  "webhookurl", "socket",
+]);
+const SHAPE_FIELDS = new Set([
+  "method", "headers", "header", "httpmethod", "requestmethod", "verb",
+  "contenttype", "requestline", "queryparams",
+]);
+const CREDENTIAL_FIELDS = new Set([
+  "authorization", "authorisation", "auth", "bearer", "authtoken",
+  "bearertoken", "authheader", "authvalue", "credential", "credentials",
+  "credentialref", "secret", "secrets", "secretref", "secretrefid",
+  "secretkey", "secretvalue", "token", "tokens", "accesstoken",
+  "refreshtoken", "idtoken", "apitoken", "sessiontoken", "tokenref",
+  "tokenid", "apikey", "apikeyid", "apikeysecret", "apisecret", "password",
+  "passwd", "pwd", "passphrase", "privatekey", "privatekeyid", "clientsecret",
+  "accesskey", "accesskeyid", "secretaccesskey", "signingkey", "signature",
+  "cookie", "cookies", "setcookie", "session", "sessionid", "sessionkey",
+  "userinfo", "usercredentials",
+]);
+
+const MAX_PAYLOAD_NODES = 4096;
+const MAX_PAYLOAD_DEPTH = 8;
+
+function normalizeField(key) {
+  let out = "";
+  for (const ch of String(key).toLowerCase()) {
+    if ((ch >= "a" && ch <= "z") || (ch >= "0" && ch <= "9")) out += ch;
+  }
+  return out;
+}
+
+function classify(normalized) {
+  if (DESTINATION_FIELDS.has(normalized)) return "destination";
+  if (SHAPE_FIELDS.has(normalized)) return "request shape";
+  if (CREDENTIAL_FIELDS.has(normalized)) return "credential";
+  return "";
+}
+
+function forbiddenField(key) {
+  const normalized = normalizeField(key);
+  const kind = classify(normalized);
+  if (kind) return kind;
+  if (normalized.length > 1 && normalized[0] === "x") return classify(normalized.slice(1));
+  return "";
+}
+
+/**
+ * Refuse a payload that names a destination, a request shape or a credential.
+ * The daemon refuses one too (internal/gateway/broker.go, callerRouteGuard) and
+ * that check is the authoritative one; this one catches the mistake before a
+ * request leaves the process.
+ */
+export function guardPayload(payload) {
+  if (payload === undefined || payload === null) return null;
+  if (typeof payload !== "object" || Array.isArray(payload)) {
+    throw new CallerRouteError(
+      `aaes: payload is a JSON ${jsonKind(payload)}, not an object; a payload carries the fields of one intent`,
+    );
+  }
+  scanPayload(payload, 0, [0]);
+  return payload;
+}
+
+function scanPayload(value, depth, nodes) {
+  nodes[0] += 1;
+  if (nodes[0] > MAX_PAYLOAD_NODES) throw new CallerRouteError("aaes: payload is too large to inspect; refusing");
+  if (depth > MAX_PAYLOAD_DEPTH) {
+    throw new CallerRouteError(`aaes: payload nests deeper than ${MAX_PAYLOAD_DEPTH} levels; refusing`);
+  }
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new CallerRouteError("aaes: payload numbers must be finite JSON values");
+  }
+  if (Array.isArray(value)) {
+    for (const child of value) scanPayload(child, depth + 1, nodes);
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const key of Object.keys(value).sort()) {
+      if (/[^\x00-\x7f]/.test(key)) {
+        throw new CallerRouteError(
+          `aaes: payload field ${JSON.stringify(key)} contains characters outside ASCII, so it cannot be compared with the names this client refuses; rename it in ASCII or remove it`,
+        );
+      }
+      const kind = forbiddenField(key);
+      if (kind) {
+        throw new CallerRouteError(
+          `aaes: payload names a ${kind} field ${JSON.stringify(key)}; the destination, the method and the credential come from the capability registration and from custody, never from the caller`,
+        );
+      }
+      scanPayload(value[key], depth + 1, nodes);
+    }
+  }
+}
+
+function jsonKind(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+
+// --- the client ------------------------------------------------------------
+
+/** The documented keys of one action. Anything else is refused before a request
+ * is sent, which is what keeps a url, a method or a credential out. */
+const ACTION_KEYS = new Set([
+  "capability", "action", "taskId", "callerTaskId", "effectKeyStep", "amountMinor", "amountCurrency",
+  "grantTtlMs", "correlationId", "parentIntentId", "contractId", "model", "provenanceStatus",
+  "externalRefs", "payload",
+]);
+
+const ACCESS_KEYS = new Set([
+  "capability", "actions", "resourceId", "surfaceResourceId", "teamId", "dataClass", "tier",
+  "budgetMinor", "budgetCurrency", "ttlSeconds", "taskId", "justification", "duration", "reviewDays",
+  "windowStart", "windowEnd", "windowTimezone",
+]);
+
+const OBSERVE_KEYS = new Set(["intentId", "effectId", "outcome", "observedAt", "note"]);
+
+export class Client {
+  constructor({ endpoint, token, retries, timeoutMs, fetchImpl } = {}) {
+    const base = String(endpoint ?? process.env[ENDPOINT_ENV] ?? "").trim().replace(/\/+$/, "");
+    if (!base) {
+      throw new AaesError(`aaes: an endpoint is required; pass endpoint or set ${ENDPOINT_ENV} to the daemon base URL`);
+    }
+    let parsed;
+    try {
+      parsed = new URL(base);
+    } catch {
+      throw new AaesError("aaes: endpoint is not a URL");
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new AaesError("aaes: endpoint must use http or https");
+    }
+    const host = parsed.hostname.toLowerCase();
+    if (parsed.protocol === "http:" && host !== "localhost" && host !== "[::1]" &&
+        !/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)) {
+      throw new AaesError("aaes: endpoint requires HTTPS or explicit loopback HTTP");
+    }
+    if (parsed.username || parsed.password) {
+      throw new AaesError(
+        "aaes: endpoint carries credentials in its authority; the bearer token is configuration, not part of the URL",
+      );
+    }
+    if (base.includes("?") || base.includes("#")) {
+      throw new AaesError("aaes: endpoint must not carry a query or fragment");
+    }
+    const configured = token ?? process.env[TOKEN_ENV] ?? "";
+    if (typeof configured !== "string") {
+      throw new AaesError(`aaes: ${TOKEN_ENV} must be an ASCII bearer token`);
+    }
+    const secret = configured.trim();
+    if ([...secret].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) > 126)) {
+      throw new AaesError(`aaes: ${TOKEN_ENV} must not contain control or non-ASCII characters`);
+    }
+    if (!secret) throw new AaesError(`aaes: a bearer token is required; pass token or set ${TOKEN_ENV}`);
+    const doFetch = fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== "function") {
+      throw new AaesError("aaes: this runtime has no fetch; pass fetchImpl or run on Node 18+");
+    }
+    this._endpoint = base;
+    this._token = secret;
+    this._retries = retries ?? new RetryPolicy();
+    this._timeoutMs = timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this._fetch = doFetch;
+    this._entitlement = null;
+    this._entitlementFlight = null;
+    this._catalog = null;
+    this._catalogSeenMs = 0;
+  }
+
+  /** The ten-minute path: AAES_ENDPOINT and AAES_TOKEN are the whole
+   * configuration. */
+  static fromEnv(options = {}) {
+    return new Client(options);
+  }
+
+  /** Forget the cached entitled slice and the published catalogue snapshot. The
+   * cache can never widen authority - the daemon decides every call - but an
+   * operator who just changed a scope does not have to restart the process. */
+  refresh() {
+    this._entitlement = null;
+    this._entitlementFlight = null;
+    this._catalog = null;
+    this._catalogSeenMs = 0;
+  }
+
+  /** The caller's entitled slice, read once per client until refresh(). It
+   * supplies the tenant and actor a call is attributed to and the registered
+   * tier it is sent with: both are the daemon's answers. */
+  async entitlement() {
+    if (this._entitlement !== null) return this._entitlement;
+    if (this._entitlementFlight !== null) return this._entitlementFlight;
+    const flight = this.capabilities().then((entitled) => {
+      if (!entitled.tenantId.trim() || !entitled.actorId.trim()) {
+        throw new AaesError(
+          "aaes: the daemon's entitled slice names no tenant_id or actor_id, so a call cannot be attributed to a caller",
+        );
+      }
+      // Refresh detaches the previous flight so it cannot repopulate the cache.
+      if (this._entitlementFlight === flight) this._entitlement = entitled;
+      return entitled;
+    }).finally(() => {
+      if (this._entitlementFlight === flight) this._entitlementFlight = null;
+    });
+    this._entitlementFlight = flight;
+    return flight;
+  }
+
+  /** GET /v1/capabilities: what this caller may USE. */
+  async capabilities() {
+    const { status, body } = await this._request("GET", PATH_CAPABILITIES, null, { identified: true });
+    if (status !== 200) throw this._statusError("GET " + PATH_CAPABILITIES, status, body);
+    return {
+      tenantId: body.tenant_id ?? "",
+      actorId: body.actor_id ?? "",
+      capabilities: (body.capabilities ?? []).map(capabilityFrom),
+      find(spelling) {
+        return findCapability(this.capabilities, spelling);
+      },
+    };
+  }
+
+  /** GET /v1/catalogue: what this caller may ASK FOR. A separate question from
+   * capabilities(), and the daemon keeps the two apart on purpose. A success is
+   * remembered as the published snapshot refusal advice reads until it ages out
+   * or refresh() forgets it. */
+  async catalog() {
+    const { status, body } = await this._request("GET", PATH_CATALOGUE, null, { identified: true });
+    if (status !== 200) throw this._statusError("GET " + PATH_CATALOGUE, status, body);
+    const catalog = {
+      tenantId: body.tenant_id ?? "",
+      actorId: body.actor_id ?? "",
+      requestable: (body.requestable ?? []).map(catalogueEntryFrom),
+      find(spelling) {
+        return findRequestable(this.requestable, spelling);
+      },
+    };
+    this._catalog = catalog;
+    this._catalogSeenMs = Date.now();
+    return catalog;
+  }
+
+  /** GET /healthz and GET /readyz. A not-ready 503 from readyz is an answer, not
+   * a failure, and is returned with its reason. */
+  async health() {
+    const live = await this._request("GET", PATH_HEALTHZ, null, { identified: true, answer503: true });
+    if (live.status !== 200) throw this._statusError("GET " + PATH_HEALTHZ, live.status, live.body);
+    const ready = await this._request("GET", PATH_READYZ, null, { identified: true, answer503: true });
+    if (ready.status !== 200 && ready.status !== 503) {
+      throw this._statusError("GET " + PATH_READYZ, ready.status, ready.body);
+    }
+    return {
+      healthz: live.body,
+      readyz: ready.body,
+      ready: ready.status === 200 && ready.body.status === "ready",
+      reason: ready.body.reason ?? "",
+    };
+  }
+
+  /** POST /v1/action: decide one action. It executes nothing; brokered()
+   * executes through AAES. A refusal is returned in decision.refusal. */
+  async action(action) {
+    const { wire, info } = await this._actionBody(action);
+    const identified = Boolean(info.effectKeyStep);
+    const { status, body } = await this._request("POST", PATH_ACTION, wire, { identified });
+    return await this._decision(status, body, info, identified);
+  }
+
+  /** POST /v1/action/resume: complete a deferred decision with the same body
+   * and effect key. A 404 means no deferral suspends this intent; the refusal
+   * carries the daemon's reason verbatim when it stated one. */
+  async resume(action) {
+    const { wire, info } = await this._actionBody(action);
+    const identified = Boolean(info.effectKeyStep);
+    const { status, body, rawText } = await this._request("POST", PATH_RESUME, wire, { identified, undecoded: UNDECODED_404 });
+    if (status === 404) {
+      const reason = noDeferralReason(rawText);
+      return new Decision({ reason, refusal: new Refusal(404, reason) });
+    }
+    return await this._decision(status, body, info, identified);
+  }
+
+  /** POST /v1/brokered: the same decision path, then execution through the
+   * daemon's connector. You still name only a capability and an action. */
+  async brokered(action) {
+    const { wire, info } = await this._actionBody(action);
+    const identified = Boolean(info.effectKeyStep);
+    const { status, body } = await this._request("POST", PATH_BROKERED, wire, { identified });
+    const decision = await this._decision(status, body, info, identified);
+    // Connector observations can accompany a refusal after sealing or a
+    // duplicate effect; they serve reconciliation, and the decision stays the
+    // authority for what happened.
+    return { decision, outcome: brokeredOutcome(body, decision, PATH_BROKERED) };
+  }
+
+  /** POST /v1/brokered/resume: complete a deferred brokered action with the
+   * same body and effect key. The daemon revalidates and executes through the
+   * connector, or refuses; a grant without a confirmed execution is never
+   * reported as success. On allow, outcome says what the connector observed.
+   * A 404 means no deferral suspends this intent; the refusal carries the
+   * daemon's reason verbatim when it stated one. */
+  async resumeBrokered(action) {
+    const { wire, info } = await this._actionBody(action);
+    const identified = Boolean(info.effectKeyStep);
+    const { status, body, rawText } = await this._request(
+      "POST",
+      PATH_BROKERED_RESUME,
+      wire,
+      { identified, undecoded: UNDECODED_404 },
+    );
+    if (status === 404) {
+      const reason = noDeferralReason(rawText);
+      return { decision: new Decision({ reason, refusal: new Refusal(404, reason) }), outcome: {} };
+    }
+    const decision = await this._decision(status, body, info, identified);
+    // Connector observations can accompany a refusal after sealing or a
+    // duplicate effect; they serve reconciliation, and the decision stays the
+    // authority for what happened.
+    return { decision, outcome: brokeredOutcome(body, decision, PATH_BROKERED_RESUME) };
+  }
+
+  /** POST /v1/grants/present: bind a stored grant to the authenticated caller.
+   * It does not execute. A 403 means the presenter is not the grant's actor; a
+   * 404 means the grant is unknown, expired or revoked. */
+  async presentGrant(grantId) {
+    grantId = String(grantId ?? "").trim();
+    if (!grantId) throw new AaesError("aaes: present names a grant_id; none was given");
+    const { status, body } = await this._request(
+      "POST",
+      PATH_GRANT_PRESENT,
+      { grant_id: grantId },
+      { identified: false },
+    );
+    if (status !== 200) throw this._statusError("POST " + PATH_GRANT_PRESENT, status, body);
+    return grantPresentFrom(body);
+  }
+
+  /** POST /v1/federate: run the full decision and return a FEDERATED GRANT -- the
+   * material (or the instructions) YOU use to call the application itself, so no
+   * content transits AAES.
+   *
+   * The three rules this client enforces:
+   *
+   * 1. NEVER a URL or a credential from the caller. This call names one
+   *    capability, one action and one task; any extra key -- url, endpoint,
+   *    destination, method, header, credential, token -- is refused before a
+   *    request is sent.
+   * 2. NEVER log the material. FederatedMaterial and FederatedGrant render with
+   *    the credential REDACTED, toJSON included.
+   * 3. NEVER retry a mint without an effect key. effectKeyStep is required, and a
+   *    503 is repeated only because the daemon can refuse the duplicate under the
+   *    same key with 409 instead of minting twice.
+   */
+  async federate(request = {}) {
+    refuseUnknownKeys(FEDERATE_KEYS, request, "federated call");
+    const capability = String(request.capability ?? "").trim();
+    if (!capability) throw new AaesError("aaes: a federated call names a capability; none was given");
+    const taskId = String(request.taskId ?? "").trim();
+    if (!taskId) {
+      throw new AaesError("aaes: a federated call names the task it is bounded by; none was given");
+    }
+    const effectKeyStep = String(request.effectKeyStep ?? "").trim();
+    if (!effectKeyStep) {
+      throw new AaesError(
+        "aaes: a federated call presents an effect key step. A mint is an irreversible act that creates authority, and a retry without a step name could not be told from a second mint",
+      );
+    }
+    // A non-integer amount is refused HERE: the wire carries integer minor
+    // units of one ISO 4217 currency, and a float cannot state cents honestly.
+    // AAES never converts.
+    const amountMinor = requireMinorAmount(request.amountMinor, "amountMinor");
+    const amountCurrency = String(request.amountCurrency ?? "").trim().toUpperCase();
+    const grantTtlMs = request.grantTtlMs ?? 0;
+    if (grantTtlMs < 0) throw new AaesError("aaes: a federated call cannot ask for a negative grantTtlMs");
+    // Only the keys a caller actually set are sent, exactly as the Go and
+    // Python clients do: an omitted field and a zero field are different facts on
+    // the wire, and the daemon's own defaults are the ones that should apply.
+    const wire = { capability, task_id: taskId, effect_key_step: effectKeyStep };
+    const action = String(request.action ?? "").trim();
+    if (action) wire.action = action;
+    // amount_minor is ALWAYS on the wire, including the zero value. Omitting
+    // it when unset decodes to the same zero on the daemon, but it hides the
+    // one fact an operator scanning traffic needs to see -- that a caller asked
+    // for a grant without pricing the action -- and it invites client authors
+    // to believe an unset amount is somebody else's default. It is not: the
+    // reservation for an unpriced capability without a registered ceiling is
+    // exactly zero.
+    wire.amount_minor = amountMinor;
+    if (amountCurrency) wire.amount_currency = amountCurrency;
+    if (grantTtlMs) wire.grant_ttl_ms = grantTtlMs;
+    if (request.rotate) wire.rotate = true;
+    const correlationId = String(request.correlationId ?? "").trim();
+    if (correlationId) wire.correlation_id = correlationId;
+    const info = {
+      capability,
+      action: String(request.action ?? "").trim(),
+      effectKeyStep,
+      taskId,
+    };
+    const { status, body } = await this._request("POST", PATH_FEDERATE, wire, { identified: true });
+    if (status !== 200 || body.allowed !== true || !body.grant) {
+      const reason = reasonOf(body);
+      return {
+        ok: false,
+        allowed: false,
+        reason,
+        grant: null,
+        refusal: await this._refuse(status, reason, info, true),
+      };
+    }
+    const grant = federatedGrantFrom(body.grant, body.intent_id);
+    if (grant.record.mode !== "federated" || grant.record.payloadSeen) {
+      throw new AaesError(
+        "aaes: the daemon returned a grant whose record says mode=" + JSON.stringify(grant.record.mode) +
+          " payload_seen=" + grant.record.payloadSeen +
+          "; a federated grant's record must say mode=federated and payload_seen=false",
+      );
+    }
+    if (!grant.federationId || !grant.intentId) {
+      throw new AaesError("aaes: the daemon returned a grant that names no federation id or intent id");
+    }
+    if (String(grant.record.intentId ?? "").trim() !== String(grant.intentId ?? "").trim()) {
+      throw new AaesError("aaes: the daemon returned a grant whose sealed record does not name this intent");
+    }
+    if (!String(grant.record.markerReceiptHash ?? "").trim()) {
+      throw new AaesError("aaes: the daemon returned a federated grant with no marker receipt hash");
+    }
+    if (!federatedCapabilityMatches(capability, grant) || grant.taskId !== taskId) {
+      throw new AaesError("aaes: the daemon returned a grant whose capability or task is not the federated action requested");
+    }
+    return { ok: true, allowed: true, reason: "", grant, refusal: null };
+  }
+
+  /** POST /v1/access-requests: ask an authorized approver for a time-bound permission. There is
+   * no idempotency key on this route, so this client never retries it; a 409
+   * means the actor already holds the permission, which is the correct answer
+   * rather than a failure. */
+  async requestAccess(ask = {}) {
+    refuseUnknownKeys(ACCESS_KEYS, ask, "access request");
+    const capability = String(ask.capability ?? "").trim();
+    if (!capability) throw new AaesError("aaes: an access request names a capability; none was given");
+    const actions = (ask.actions ?? []).map((a) => String(a).trim()).filter(Boolean);
+    if (actions.length === 0) {
+      // An ask with no actions is not "every action": the daemon refuses an
+      // entitlement that names no action, because nobody can review a permission
+      // that was never stated. The client says so here rather than letting the
+      // caller learn it from a 400.
+      throw new AaesError(
+        "aaes: an access request names its actions; an entitlement with no action authorises nothing and no person can review it",
+      );
+    }
+    const wire = {
+      capability,
+      actions,
+      resource_id: String(ask.resourceId ?? "").trim(),
+      data_class: String(ask.dataClass ?? "").trim(),
+      tier: String(ask.tier ?? "").trim(),
+      budget_minor: requireMinorAmount(ask.budgetMinor, "budgetMinor"),
+      budget_currency: String(ask.budgetCurrency ?? "").trim().toUpperCase(),
+      ttl_seconds: ask.ttlSeconds ?? 0,
+      task_id: String(ask.taskId ?? "").trim(),
+      justification: String(ask.justification ?? "").trim(),
+    };
+    // The ADR-010 scoping and duration fields. Each is added only when the
+    // caller supplied it, exactly like the optional fields above.
+    const surfaceResourceId = String(ask.surfaceResourceId ?? "").trim();
+    if (surfaceResourceId) wire.surface_resource_id = surfaceResourceId;
+    const teamId = String(ask.teamId ?? "").trim();
+    if (teamId) wire.team_id = teamId;
+    const duration = String(ask.duration ?? "").trim();
+    if (duration) wire.duration = duration;
+    if (ask.reviewDays) wire.review_days = ask.reviewDays;
+    const windowStart = String(ask.windowStart ?? "").trim();
+    if (windowStart) wire.window_start = windowStart;
+    const windowEnd = String(ask.windowEnd ?? "").trim();
+    if (windowEnd) wire.window_end = windowEnd;
+    const windowTimezone = String(ask.windowTimezone ?? "").trim();
+    if (windowTimezone) wire.window_timezone = windowTimezone;
+    if (!wire.tier) {
+      try {
+        const entry = (await this.catalog()).find(capability);
+        if (entry) wire.tier = entry.riskTier;
+      } catch {
+        // The catalog is a convenience here; the ask is still the caller's.
+      }
+    }
+    const info = { capability, ask: true };
+    const { status, body } = await this._request("POST", PATH_ACCESS_REQUESTS, wire, { identified: false });
+    if (status === 200 || status === 201) {
+      return {
+        requestId: body.request_id ?? "",
+        state: body.state ?? "",
+        needed: body.needed ?? {},
+        alreadyHeld: false,
+        refusal: null,
+      };
+    }
+    return {
+      requestId: "",
+      state: "",
+      needed: {},
+      alreadyHeld: status === 409,
+      refusal: await this._refuse(status, reasonOf(body), info, false),
+    };
+  }
+
+  /** GET /v1/access-requests/{id}. */
+  async accessRequest(requestId) {
+    const id = String(requestId ?? "").trim();
+    if (!id) throw new AaesError("aaes: an access request id is required");
+    const path = PATH_ACCESS_REQUESTS + "/" + encodeURIComponent(id);
+    const { status, body } = await this._request("GET", path, null, { identified: true });
+    if (status !== 200) throw this._statusError("GET " + path, status, body);
+    return accessViewFrom(body);
+  }
+
+  /** POST /v1/observe: report the effect of an intent the daemon authorized
+   * under pass_through custody. The answer is the daemon's observational
+   * receipt: attributed, not trusted, and never counted toward coverage. */
+  async observe(report = {}) {
+    refuseUnknownKeys(OBSERVE_KEYS, report, "observation report");
+    const intentId = String(report.intentId ?? "").trim();
+    if (!intentId) throw new AaesError("aaes: a report names the intent it is about; no intentId was given");
+    const wire = { intent_id: intentId };
+    if (report.effectId) wire.effect_id = String(report.effectId).trim();
+    if (report.outcome) wire.outcome = String(report.outcome).trim();
+    if (report.observedAt) wire.observed_at = report.observedAt;
+    if (report.note) wire.note = String(report.note).trim();
+    const { status, body } = await this._request("POST", PATH_OBSERVE, wire, { identified: true });
+    if (status !== 200) {
+      return {
+        intentId,
+        receipt: null,
+        label: "",
+        enforcement: "",
+        countsTowardCoverage: false,
+        refusal: await this._refuse(status, reasonOf(body), { intentId }, true),
+      };
+    }
+    return {
+      intentId: body.intent_id ?? "",
+      receipt: body.receipt ? receiptFrom(body.receipt) : null,
+      label: body.label ?? "",
+      enforcement: body.enforcement ?? "",
+      countsTowardCoverage: Boolean(body.counts_toward_coverage),
+      refusal: null,
+    };
+  }
+
+  // -- internals ------------------------------------------------------------
+
+  // Read APIs retain snake_case wire fields. Filters never change the bearer identity.
+  async _readRecord(path) {
+    const { status, body } = await this._request("GET", path, null, { identified: true });
+    if (status !== 200) throw this._statusError("GET " + path, status, body);
+    return body;
+  }
+
+  async listTask(filters = {}) {
+    return this._readRecord("/v1/task" + readQuery(filters, {"limit": "limit", "cursor": "cursor", "since": "since", "until": "until", "state": "state", "sponsor": "sponsor", "assignee": "assignee", "overdue": "overdue"}));
+  }
+
+  async listApprovals(filters = {}) {
+    return this._readRecord("/v1/approvals" + readQuery(filters, {"limit": "limit", "cursor": "cursor", "since": "since", "until": "until", "intentId": "intent_id", "taskId": "task_id", "state": "state"}));
+  }
+
+  async listEntitlements(filters = {}) {
+    return this._readRecord("/v1/entitlements" + readQuery(filters, {"limit": "limit", "cursor": "cursor", "actorId": "actor_id", "capability": "capability", "state": "state"}));
+  }
+
+  async listReceipts(filters = {}) {
+    return this._readRecord("/v1/receipts" + readQuery(filters, {"limit": "limit", "cursor": "cursor", "since": "since", "until": "until", "intentId": "intent_id", "taskId": "task_id", "effectClass": "class", "custody": "custody"}));
+  }
+
+  async task(id) { return this._readRecord("/v1/task/" + recordId(id)); }
+  async approval(id) { return this._readRecord("/v1/approvals/" + recordId(id)); }
+  async receipt(id) { return this._readRecord("/v1/receipts/" + recordId(id)); }
+
+  async managerCards() { return this._readRecord("/v1/manager-cards"); }
+
+  async decideManagerCard(decision) {
+    refuseUnknownKeys(new Set(["cardId", "approvalId", "payloadHash", "policyId", "grant", "reason"]), decision, "manager card decision");
+    for (const key of ["cardId", "approvalId", "payloadHash"]) {
+      if (typeof decision[key] !== "string" || !decision[key].trim()) throw new AaesError("aaes: " + key + " is required");
+    }
+    if (typeof decision.grant !== "boolean") throw new AaesError("aaes: grant must be an explicit boolean");
+    const wire = { card_id: decision.cardId, approval_id: decision.approvalId, payload_hash: decision.payloadHash, grant: decision.grant };
+    if (decision.policyId !== undefined) wire.policy_id = decision.policyId;
+    if (decision.reason !== undefined) wire.reason = decision.reason;
+    const { status, body } = await this._request("POST", "/v1/manager-cards/decide", wire, { identified: false });
+    if (status !== 200) throw this._statusError("manager card decision", status, body);
+    return body;
+  }
+
+  async _actionBody(action = {}) {
+    refuseUnknownKeys(ACTION_KEYS, action, "action");
+    const capability = String(action.capability ?? "").trim();
+    if (!capability) throw new AaesError("aaes: an action names a capability; none was given");
+    const amountMinor = requireMinorAmount(action.amountMinor, "amountMinor");
+    const payload = guardPayload(action.payload);
+    const entitled = await this.entitlement();
+    const info = {
+      capability,
+      action: String(action.action ?? "").trim(),
+      effectKeyStep: String(action.effectKeyStep ?? "").trim(),
+      taskId: String(action.taskId ?? "").trim(),
+      ask: false,
+    };
+    const wire = prune({
+      tenant_id: entitled.tenantId,
+      actor_id: entitled.actorId,
+      caller_task_id: String(action.callerTaskId ?? "").trim(),
+      task_id: info.taskId,
+      effect_key_step: info.effectKeyStep,
+      capability,
+      tier: "",
+      action: info.action,
+      correlation_id: String(action.correlationId ?? "").trim(),
+      parent_intent_id: String(action.parentIntentId ?? "").trim(),
+      contract_id: String(action.contractId ?? "").trim(),
+      model: String(action.model ?? "").trim(),
+      provenance_status: String(action.provenanceStatus ?? "").trim() || undefined,
+      external_refs: Array.isArray(action.externalRefs) && action.externalRefs.length
+        ? action.externalRefs
+        : undefined,
+      amount_minor: amountMinor,
+      amount_currency: String(action.amountCurrency ?? "").trim().toUpperCase() || undefined,
+      grant_ttl_ms: action.grantTtlMs,
+      payload,
+    });
+    const entry = entitled.find(capability);
+    if (!entry || typeof entry.riskTier !== "string" || !entry.riskTier.trim()) {
+      throw new AaesError(
+        `aaes: no published risk tier for capability ${JSON.stringify(capability)}; refresh capabilities or request access before an action`,
+      );
+    }
+    // The tier the daemon published for this caller. A caller cannot raise its
+    // own tier, and the daemon refuses one below the registration.
+    wire.tier = entry.riskTier;
+    if (!wire.task_id) wire.task_id = entry.taskId;
+    if (!wire.caller_task_id) wire.caller_task_id = entry.callerTaskId;
+    return { wire: prune(wire), info };
+  }
+
+  async _decision(status, body, info, identified) {
+    const decision = new Decision({
+      allowed: body.allowed === true && status === 200,
+      deferred: status === 202 && body.deferred === true,
+      reason: String(body.reason ?? "").trim(),
+      intentId: String(body.intent_id ?? "").trim(),
+      grant: body.grant ? grantFrom(body.grant) : null,
+      receipt: body.receipt ? receiptFrom(body.receipt) : null,
+      latencyAddedMs: finiteNumberFrom(body.latency_added_ms, "latency_added_ms"),
+    });
+    if (!decision.intentId && decision.receipt) decision.intentId = decision.receipt.intentId;
+    if (decision.ok || decision.deferred) return decision;
+    if (!decision.reason) decision.reason = reasonOf(body);
+    decision.refusal = await this._refuse(status, decision.reason, info, identified);
+    return decision;
+  }
+
+  async _refuse(status, reason, info, identified) {
+    const text = String(reason ?? "").trim() || `the daemon answered HTTP ${status} and stated no reason`;
+    const refusal = new Refusal(status, text);
+    if (status === 503) {
+      refusal.retryable = Boolean(identified && info.effectKeyStep && !info.ask);
+      refusal.advice.push(this._retryAdvice(info, identified));
+      return refusal;
+    }
+    if (status === 409) {
+      if (info.ask) {
+        refusal.advice.push(
+          "nothing to change: the daemon refuses to raise a request for a permission the actor already holds. Read what you hold (capabilities) or the request that issued it instead of re-asking; no approver was asked and no approval was consumed",
+        );
+      } else if (info.effectKeyStep) {
+        refusal.advice.push(
+          `this effect key is already committed for this task, so the retry was refused rather than repeated. Do not re-issue the first attempt: it either happened (the receipt is the evidence) or it did not (the record says so). Only if this really is a NEW effect, present a new effectKeyStep instead of ${JSON.stringify(info.effectKeyStep)}`,
+        );
+      } else {
+        refusal.advice.push(
+          "the daemon refused this as a duplicate of an effect already committed for this task. Do not re-issue it; read the record for the task instead. If it really is a new effect, name it with a distinct effectKeyStep",
+        );
+      }
+      return refusal;
+    }
+    if (status === 401) {
+      refusal.advice.push(
+        `check ${TOKEN_ENV}: the daemon refused the bearer token, and no decision was taken. The token is sent only in the Authorization header, so a token that tasks elsewhere and not here is a token for another tenant or a revoked key`,
+      );
+      return refusal;
+    }
+    if (status === 400) {
+      refusal.advice.push(
+        "the reason names the field the daemon refused; fix that field and send the call again. This client sends only documented fields, so a field named in a payload refusal is the caller's own",
+      );
+      return refusal;
+    }
+    if (status === 404 && info.intentId) {
+      refusal.advice.push(
+        `check the intent id ${JSON.stringify(info.intentId)}: the daemon looks it up scoped to the caller's tenant, so an id raised elsewhere reads as not found`,
+      );
+      return refusal;
+    }
+    refusal.advice.push(...(await this._publishedAdvice(info, text)));
+    if (refusal.advice.length === 0) {
+      refusal.advice.push(
+        "the daemon stated no field this client can change; read the reason above and change the field it names",
+      );
+    }
+    return refusal;
+  }
+
+  _retryAdvice(info, identified) {
+    if (info.ask) {
+      return "the daemon could not decide safely and raised nothing. An access request carries no effect key on the daemon side, so this client NEVER retries it: re-ask deliberately, after reading any request you already raised (accessRequest).";
+    }
+    if (identified) {
+      return `nothing was minted. This call presents effectKeyStep ${JSON.stringify(info.effectKeyStep)}, so repeating it is safe: the daemon commits the effect key in the same journal write that authorises the action, and a duplicate attempt under it is refused with 409 rather than repeated. This client repeats it only when you opt in with RetryPolicy.default()`;
+    }
+    return "the daemon could not complete this call safely; its effect may be uncertain. A retry is safe only under an effect key, and this call named none, so this client does not repeat it. Add effectKeyStep and opt in with RetryPolicy.default() if you want a 503 repeated";
+  }
+
+  async _publishedAdvice(info, reason) {
+    const out = [];
+    const lowered = String(reason ?? "").toLowerCase();
+    if (lowered.includes("approval") || lowered.includes("human") || lowered.includes("person")) {
+      out.push(
+        "an operator approval gate is part of this decision: the daemon refuses until an unexpired approval raised against THIS intent exists, and raises a pending one for it. The approval is decided in the operator console; nothing the caller does changes the decision",
+      );
+    }
+    const capability = String(info.capability ?? "").trim();
+    if (!capability) return out;
+    // Advice is observational and must never add network latency to a refusal,
+    // so only snapshots an earlier read already published are consulted: the
+    // catalogue snapshot expires after CATALOGUE_SNAPSHOT_FRESH_MS and
+    // refresh() clears both it and the entitled slice. With no snapshot the
+    // advice is the same one a failed read produces.
+    const fresh = this._catalog !== null && Date.now() - this._catalogSeenMs <= CATALOGUE_SNAPSHOT_FRESH_MS;
+    const catalog = fresh ? this._catalog : null;
+    let catalogueError = null;
+    if (catalog === null) catalogueError = new AaesError("no recent published catalogue snapshot");
+    const entry = catalog === null ? null : catalog.find(capability);
+    if (entry) {
+      out.push(
+        `request it: requestAccess({ capability: ${JSON.stringify(capability)}, actions: ${JSON.stringify(entry.actions)}, tier: ${JSON.stringify(entry.riskTier)}, resourceId: ${JSON.stringify(entry.resourceId)}, dataClass: ${JSON.stringify(entry.dataClass)}, taskId: ..., justification: ... }). The daemon publishes tier ${entry.riskTier}, resource ${JSON.stringify(entry.resourceId)} and data class ${JSON.stringify(entry.dataClass)} for this capability, and a request raises one operator approval whose entitlement is time-bound`,
+      );
+      return out;
+    }
+    const entitled = this._entitlement;
+    let entitledError = null;
+    if (entitled === null) entitledError = new AaesError("no published entitlement snapshot");
+    const entitledEntry = entitled === null ? null : entitled.find(capability);
+    if (entitledEntry) {
+      const action = String(info.action ?? "").trim();
+      if (entitledEntry.actions.length > 0 && action && !entitledEntry.actions.includes(action)) {
+        out.push(
+          `the daemon entitles this capability with actions ${JSON.stringify(entitledEntry.actions)}, and this call asked for ${JSON.stringify(action)}: use one of the published actions, or ask for the action you need (catalog then requestAccess)`,
+        );
+      } else if (entitledEntry.riskTier) {
+        out.push(
+          `the daemon entitles this capability at tier ${entitledEntry.riskTier} with actions ${JSON.stringify(entitledEntry.actions)}; the refusal above names what else the decision required (tier, resource, data class, task or budget)`,
+        );
+      }
+      return out;
+    }
+    if (catalogueError === null && entitledError === null) {
+      out.push(
+        `the daemon publishes capability ${JSON.stringify(capability)} neither as an entitlement nor on the requestable catalogue, so no client change satisfies this: an operator has to register it (aaesctl capability) or opt it into the catalogue (aaesctl access catalogue) first. catalog() lists everything that may be asked for`,
+      );
+    } else if (catalogueError !== null) {
+      out.push(
+        `the requestable catalogue could not be read (${catalogueError.message}), so this client cannot name the smallest change; the daemon's reason above is the whole answer`,
+      );
+    }
+    return out;
+  }
+
+  async _request(method, path, body, { identified, answer503 = false, undecoded = null }) {
+    const payload = body === null ? undefined : JSON.stringify(body);
+    const attempts = this._retries.attempts(identified, answer503);
+    let answer;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      if (attempt > 1) await sleep(this._retries.delay(attempt - 1));
+      answer = await this._once(method, path, payload, undecoded);
+      // A transport or decoding failure does not establish that nothing was
+      // minted. Only the daemon's explicit 503 answer permits repetition.
+      if (answer.status !== 503) return answer;
+    }
+    // The 503 that ends the call is decoded here and only into an object: the
+    // daemon's JSON reason reaches the refusal, while a proxy's HTML
+    // maintenance page reads as no stated reason under the same status rather
+    // than a decode error that would claim no answer arrived.
+    return answer === undefined ? answer : { ...answer, body: decodeObjectBody(answer.rawText) };
+  }
+
+  async _once(method, path, payload, undecoded = null) {
+    let response;
+    try {
+      response = await this._fetch(this._endpoint + path, {
+        method,
+        headers: {
+          Accept: "application/json",
+          ...(payload === undefined ? {} : { "Content-Type": "application/json" }),
+          // The token is put in a header and nowhere else: it never enters a URL,
+          // a query, an error string or a log line.
+          Authorization: "Bearer " + this._token,
+        },
+        body: payload,
+        redirect: "manual",
+        signal: AbortSignal.timeout(this._timeoutMs),
+      });
+    } catch (err) {
+      throw new AaesError(`aaes: ${method} ${path}: ${err.message}`);
+    }
+    if (response.status >= 300 && response.status < 400) {
+      await cancelBody(response);
+      throw new AaesError(
+        `aaes: refusing to follow a redirect to ${response.headers.get("location") ?? "another host"}: the daemon must answer at the configured endpoint`,
+      );
+    }
+    let raw;
+    try {
+      raw = await readBoundedResponse(response, method, path);
+    } catch (err) {
+      await cancelBody(response);
+      // A body read fails the same way a failed fetch does: the read's own
+      // refusals are already typed, and anything the stream or the abort
+      // signal throws keeps its original error as the cause.
+      if (err instanceof AaesError) throw err;
+      throw new AaesError(`aaes: ${method} ${path}: ${err.message}`, { cause: err });
+    }
+    // A status the caller reads without decoding is returned with its raw
+    // text; the caller parses lazily, so an unparseable body cannot turn the
+    // mapped status into a decode error.
+    if (undecoded !== null && undecoded.has(response.status)) {
+      return { status: response.status, body: {}, rawText: raw };
+    }
+    // A 503 reaches the retry loop as its status alone: a proxy serves its
+    // maintenance page as HTML, and only the 503 that ends the call is
+    // decoded, by _request, once it is surfaced to the caller.
+    if (response.status === 503) {
+      return { status: response.status, body: {}, rawText: raw };
+    }
+    let body = {};
+    if (raw.trim()) {
+      try {
+        body = JSON.parse(raw);
+      } catch {
+        throw new AaesError(`aaes: ${method} ${path} answered HTTP ${response.status} with a body this client could not decode`);
+      }
+    }
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+      throw new AaesError(`aaes: ${method} ${path} answered HTTP ${response.status} with a JSON ${jsonKind(body)}, not an object`);
+    }
+    return { status: response.status, body };
+  }
+
+  _statusError(what, status, body) {
+    return new AaesError(`aaes: ${what} answered HTTP ${status}: ${reasonOf(body) || "the daemon stated no reason"}`);
+  }
+}
+
+// --- helpers ---------------------------------------------------------------
+
+function brokeredOutcome(body, decision, route) {
+  const present = body !== null && typeof body === "object" && Object.prototype.hasOwnProperty.call(body, "outcome");
+  const outcome = present ? body.outcome : undefined;
+  if (outcome === undefined || outcome === null) {
+    if (!decision.ok) return {};
+    throw new AaesError(
+      `aaes: POST ${route} was allowed and the connector may have executed the effect, but its outcome could not be decoded`,
+    );
+  }
+  const typed = typeof outcome === "object" && !Array.isArray(outcome)
+    && (!("executed" in outcome) || typeof outcome.executed === "boolean")
+    && (!("rail_confirmed" in outcome) || typeof outcome.rail_confirmed === "boolean");
+  if (typed) return outcome;
+  if (decision.ok) {
+    throw new AaesError(
+      `aaes: POST ${route} was allowed and the connector may have executed the effect, but its outcome could not be decoded`,
+    );
+  }
+  throw new AaesError(`aaes: POST ${route} outcome could not be decoded; the connector may have executed the effect`);
+}
+
+async function cancelBody(response) {
+  try {
+    await response.body?.cancel();
+  } catch {
+    // The caller's error is the one that matters; this only releases the socket.
+  }
+}
+
+async function readBoundedResponse(response, method, path) {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  let buffer = new Uint8Array(16 * 1024);
+  let bytes = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const nextSize = bytes + value.byteLength;
+      if (nextSize > MAX_RESPONSE_BYTES) {
+        await reader.cancel();
+        throw new AaesError(`aaes: ${method} ${path} answered with a body larger than ${MAX_RESPONSE_BYTES} bytes`);
+      }
+      if (nextSize > buffer.length) {
+        const grown = new Uint8Array(Math.min(MAX_RESPONSE_BYTES, Math.max(nextSize, buffer.length * 2)));
+        grown.set(buffer.subarray(0, bytes));
+        buffer = grown;
+      }
+      buffer.set(value, bytes);
+      bytes = nextSize;
+    }
+    return new TextDecoder().decode(buffer.subarray(0, bytes));
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function refuseUnknownKeys(allowed, value, what) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new AaesError(`aaes: the ${what} must be an object`);
+  }
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) {
+      throw new AaesError(
+        `aaes: the ${what} names ${JSON.stringify(key)}, which this client does not send. A caller names a capability and an action: a URL, a method, a header, a credential, a tenant or an actor is not yours to name here`,
+      );
+    }
+  }
+}
+
+function reasonOf(body) {
+  if (body && typeof body === "object" && typeof body.reason === "string") return body.reason.trim();
+  return "";
+}
+
+/** The reason of a 404 resume answer: the daemon's sentence VERBATIM when the
+ * body stated one, and the canned no-deferral sentence only when it did not
+ * (an older daemon without the route, or a proxy, answers plain text). */
+function noDeferralReason(rawText) {
+  try {
+    return reasonOf(JSON.parse(String(rawText ?? ""))) || "no deferral suspends this intent";
+  } catch {
+    return "no deferral suspends this intent";
+  }
+}
+
+/** The body of a final 503, decoded only once it is surfaced and only into an
+ * object: the daemon's JSON reason reaches the refusal, and a proxy's HTML
+ * maintenance page reads as no stated reason under the same status. */
+function decodeObjectBody(rawText) {
+  try {
+    const parsed = JSON.parse(String(rawText ?? ""));
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+// requireMinorAmount is the wire's front line against fractional and negative
+// amounts: money on the wire is an integer count of minor units of one ISO
+// 4217 currency, and a float cannot state cents honestly. Omitted (undefined)
+// stays the documented zero. AAES never converts.
+function requireMinorAmount(value, field) {
+  const amount = value ?? 0;
+  if (!Number.isSafeInteger(amount)) {
+    throw new AaesError("aaes: " + field + " must be an integer count of minor units");
+  }
+  if (amount < 0) {
+    throw new AaesError("aaes: " + field + " cannot be negative");
+  }
+  return amount;
+}
+
+// minorUnitsFrom reads a daemon-published minor-unit cap. An omitted cap is
+// unknown (present false, value null). An explicit zero stays zero and present.
+function minorUnitsFrom(value, field) {
+  if (value === undefined) return { value: null, present: false };
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new AaesError("aaes: " + field + " is not a nonnegative JSON integer");
+  }
+  return { value, present: true };
+}
+
+// finiteNumberFrom reads a daemon-published nonnegative number such as
+// latency_added_ms. Omitted reads as zero; a string, boolean, null, negative
+// or non-finite value is refused rather than coerced.
+function finiteNumberFrom(value, field) {
+  if (value === undefined) return 0;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new AaesError("aaes: " + field + " is not a finite nonnegative JSON number");
+  }
+  return value;
+}
+
+function prune(value) {
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (item === undefined || item === null || item === "") continue;
+    out[key] = item;
+  }
+  return out;
+}
+
+// The grant names the canonical capability and version separately; its locator
+// names that canonical id. A request may pin the pair as canonical@version.
+// Exact equality wins, so a capability id that itself contains "@" stays the
+// id; only then does the last "@" start a pin.
+function federatedCapabilityMatches(requested, grant) {
+  const canonical = String(grant.capability ?? "").trim();
+  const version = String(grant.capabilityVersion ?? "").trim();
+  const locator = String(grant.locator?.capability ?? "").trim();
+  if (!canonical || locator !== canonical) return false;
+  if (requested === canonical) return true;
+  const at = requested.lastIndexOf("@");
+  if (at <= 0 || at === requested.length - 1) return false;
+  const base = requested.slice(0, at).trim();
+  const pin = requested.slice(at + 1).trim();
+  return base === canonical && pin !== "" && pin === version;
+}
+
+function explicitCapabilityPin(spelling, entries) {
+  if (!spelling.includes("@")) return false;
+  for (const entry of entries) {
+    if (String(entry.capabilityId ?? "").trim() === spelling) return false;
+  }
+  return true;
+}
+
+// onlyMatch returns the single entry a spelling selects, or null. A bare id
+// listed in several versions, or a pin listed twice, is ambiguous: picking one
+// by response order would attach another version's tier and task metadata.
+function onlyMatch(entries, matches) {
+  const found = entries.filter(matches);
+  return found.length === 1 ? found[0] : null;
+}
+
+// findCapability resolves an entitled spelling. A full capability id that
+// itself contains "@" stays that id; otherwise "@" separates a version pin.
+function findCapability(entries, spelling) {
+  const name = String(spelling ?? "").trim();
+  if (explicitCapabilityPin(name, entries)) {
+    return onlyMatch(entries, (entry) => entry.name === name);
+  }
+  return onlyMatch(entries, (entry) => entry.capabilityId.trim() === name);
+}
+
+// findRequestable resolves a catalogue spelling by the same rule: a pin
+// ("name@version") matches the id and the version, so an ask can never borrow
+// another version's tier.
+function findRequestable(entries, spelling) {
+  const name = String(spelling ?? "").trim();
+  if (explicitCapabilityPin(name, entries)) {
+    const at = name.lastIndexOf("@");
+    const base = name.slice(0, at);
+    const version = name.slice(at + 1);
+    return onlyMatch(entries, (entry) => entry.capabilityId.trim() === base && entry.version.trim() === version);
+  }
+  return onlyMatch(entries, (entry) => entry.capabilityId.trim() === name);
+}
+
+function capabilityFrom(entry) {
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    throw new AaesError("aaes: capability is not a JSON object");
+  }
+  const capabilityId = entry.capability_id ?? "";
+  const version = entry.version ?? "";
+  const pinned = Boolean(entry.pinned);
+  return {
+    capabilityId,
+    version,
+    pinned,
+    kind: entry.kind ?? "",
+    owner: entry.owner ?? "",
+    riskTier: entry.risk_tier ?? "",
+    actions: entry.actions ?? [],
+    resourceId: entry.resource_id ?? "",
+    dataClass: entry.data_class ?? "",
+    custody: entry.custody ?? "",
+    enforcement: entry.enforcement ?? "",
+    taskId: entry.task_id ?? "",
+    callerTaskId: entry.caller_task_id ?? "",
+    expiresAt: entry.expires_at ?? null,
+    source: entry.source ?? "",
+    requestId: entry.request_id ?? "",
+    get name() {
+      return pinned && version ? `${capabilityId}@${version}` : capabilityId;
+    },
+  };
+}
+
+function catalogueEntryFrom(entry) {
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    throw new AaesError("aaes: catalogue entry is not a JSON object");
+  }
+  const policy = entry.policy ?? {};
+  return {
+    capabilityId: entry.capability_id ?? "",
+    version: entry.version ?? "",
+    kind: entry.kind ?? "",
+    owner: entry.owner ?? "",
+    riskTier: entry.risk_tier ?? "",
+    actions: entry.actions ?? [],
+    resourceId: entry.resource_id ?? "",
+    dataClass: entry.data_class ?? "",
+    custody: entry.custody ?? "",
+    policy: {
+      policyId: policy.policy_id ?? "",
+      label: policy.label ?? "",
+      required: policy.required ?? 0,
+      minHumans: policy.min_humans ?? 0,
+      classes: policy.classes ?? [],
+      authority: policy.authority ?? "",
+    },
+  };
+}
+
+function grantFrom(body) {
+  if (body.non_transferable !== true) {
+    throw new AaesError("aaes: grant non_transferable must be JSON true");
+  }
+  const spendCap = minorUnitsFrom(body.spend_cap_minor, "spend_cap_minor");
+  return {
+    grantId: body.grant_id ?? "",
+    actorId: body.actor_id ?? "",
+    tenantId: body.tenant_id ?? "",
+    capability: body.capability ?? "",
+    tier: body.tier ?? "",
+    taskId: body.task_id ?? "",
+    issuedAt: body.issued_at ?? "",
+    expiresAt: body.expires_at ?? "",
+    ttlSeconds: body.ttl_seconds ?? 0,
+    spendCapMinor: spendCap.value,
+    spendCapMinorPresent: spendCap.present,
+    spendCapCurrency: body.spend_cap_currency ?? "",
+    nonTransferable: true,
+    budgetGrantId: body.budget_grant_id ?? "",
+    issuer: body.issuer ?? "",
+    signature: body.signature ?? "",
+  };
+}
+
+function grantPresentFrom(body) {
+  const spendCap = minorUnitsFrom(body.spend_cap_minor, "spend_cap_minor");
+  return {
+    grantId: body.grant_id ?? "",
+    actorId: body.actor_id ?? "",
+    tenantId: body.tenant_id ?? "",
+    capability: body.capability ?? "",
+    tier: body.tier ?? "",
+    taskId: body.task_id ?? "",
+    issuedAt: body.issued_at ?? "",
+    expiresAt: body.expires_at ?? "",
+    spendCapMinor: spendCap.value,
+    spendCapMinorPresent: spendCap.present,
+    spendCapCurrency: body.spend_cap_currency ?? "",
+  };
+}
+
+function receiptFrom(body) {
+  return {
+    receiptId: body.receipt_id ?? "",
+    intentId: body.intent_id ?? "",
+    tenantId: body.tenant_id ?? "",
+    taskId: body.task_id ?? "",
+    approvalId: body.approval_id ?? "",
+    custody: body.custody ?? "",
+    grantId: body.grant_id ?? "",
+    effectId: body.effect_id ?? "",
+    effect: body.effect ?? "",
+    recordHash: body.record_hash ?? "",
+    issuedAt: body.issued_at ?? "",
+    effectClass: body.class ?? 0,
+    railConfirmed: Boolean(body.rail_confirmed),
+    confirmedAt: body.confirmed_at ?? "",
+    reportedBy: body.reported_by ?? "",
+    reportedAt: body.reported_at ?? "",
+    observedAt: body.observed_at ?? "",
+    reportedOutcome: body.reported_outcome ?? "",
+    note: body.note ?? "",
+    receiptHash: body.receipt_hash ?? "",
+    policyBundleHash: body.policy_bundle_hash ?? "",
+    inputHash: body.input_hash ?? "",
+    engineVersion: body.engine_version ?? "",
+  };
+}
+
+/** decodeBase64 turns the daemon's credential into bytes. The wire carries it as
+ * standard base64 -- the encoding a Go []byte marshals to and every SDK decodes.
+ * An undecodable value is NO credential: a half-decoded secret is not one, and
+ * handing one back would be worse than refusing. */
+function decodeBase64(value) {
+  const raw = String(value ?? "").trim();
+  if (!raw) return new Uint8Array(0);
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(raw) || raw.length % 4 !== 0) {
+    throw new AaesError(
+      "aaes: the daemon's federated credential is not valid base64; this client refuses to hand back a half-decoded secret",
+    );
+  }
+  if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(raw, "base64"));
+  if (typeof atob === "function") {
+    const binary = atob(raw);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) out[i] = binary.charCodeAt(i);
+    return out;
+  }
+  throw new AaesError("aaes: this runtime has no base64 decoder, so the federated credential cannot be read");
+}
+
+function federatedInstructionsFrom(body = {}) {
+  return new FederatedInstructions({
+    backend: body.backend ?? "",
+    method: body.method ?? "",
+    url: body.url ?? "",
+    headers: body.headers ?? {},
+    form: body.form ?? {},
+    json: body.json ?? {},
+    subjectTokenIn: body.subject_token_in ?? "",
+    subjectTokenField: body.subject_token_field ?? "",
+    subjectTokenType: body.subject_token_type ?? "",
+    durationSeconds: body.duration_seconds ?? 0,
+    documentation: body.documentation ?? "",
+    notBuilt: body.not_built ?? [],
+    notes: body.notes ?? [],
+  });
+}
+
+function federatedMaterialFrom(body = {}) {
+  const instructions = body.instructions;
+  return new FederatedMaterial({
+    kind: body.kind ?? "",
+    credential: decodeBase64(body.credential),
+    instructions:
+      instructions !== null && typeof instructions === "object"
+        ? federatedInstructionsFrom(instructions)
+        : null,
+    expiresAt: body.expires_at ?? "",
+    audience: body.audience ?? "",
+  });
+}
+
+function federatedGrantFrom(body = {}, intentId = "") {
+  const locator = body.locator ?? {};
+  const record = body.record ?? {};
+  const spendCap = minorUnitsFrom((body.spend_cap ?? {}).minor, "spend_cap.minor");
+  if (record.payload_seen !== true && record.payload_seen !== false) {
+    throw new AaesError(
+      "aaes: the daemon returned a grant whose record omits payload_seen or did not send a JSON boolean",
+    );
+  }
+  return new FederatedGrant({
+    federationId: body.federation_id ?? "",
+    intentId: body.intent_id ?? intentId ?? "",
+    decisionGrantId: body.decision_grant_id ?? "",
+    tenantId: body.tenant_id ?? "",
+    actorId: body.actor_id ?? "",
+    capability: body.capability ?? "",
+    capabilityVersion: body.capability_version ?? "",
+    actions: body.actions ?? [],
+    resourceId: body.resource_id ?? "",
+    taskId: body.task_id ?? "",
+    dataClass: body.data_class ?? "",
+    tier: body.tier ?? "",
+    spendCapMinor: spendCap.value,
+    spendCapMinorPresent: spendCap.present,
+    spendCapCurrency: (body.spend_cap ?? {}).currency ?? "",
+    scopeKey: body.scope_key ?? "",
+    backend: body.backend ?? "",
+    locator: {
+      capability: locator.capability ?? "",
+      endpoint: locator.endpoint ?? "",
+      method: locator.method ?? "",
+      authority: locator.authority ?? "",
+      resourceId: locator.resource_id ?? "",
+    },
+    issuedAt: body.issued_at ?? "",
+    expiresAt: body.expires_at ?? "",
+    ttlSeconds: body.ttl_seconds ?? 0,
+    material: federatedMaterialFrom(body.material ?? {}),
+    record: {
+      intentId: record.intent_id ?? "",
+      mode: record.mode ?? "",
+      payloadSeen: record.payload_seen,
+      markerReceiptHash: record.marker_receipt_hash ?? "",
+      receiptId: record.receipt_id ?? "",
+    },
+  });
+}
+
+function accessViewFrom(body) {
+  return {
+    requestId: body.request_id ?? "",
+    state: body.state ?? "",
+    needed: body.needed ?? {},
+    tenantId: body.tenant_id ?? "",
+    actorId: body.actor_id ?? "",
+    capability: body.capability ?? "",
+    actions: body.actions ?? [],
+    resourceId: body.resource_id ?? "",
+    surfaceResourceId: body.surface_resource_id ?? "",
+    teamId: body.team_id ?? "",
+    dataClass: body.data_class ?? "",
+    tier: body.tier ?? "",
+    budgetMinor: body.budget_minor ?? 0,
+    budgetCurrency: body.budget_currency ?? "",
+    ttlSeconds: body.ttl_seconds ?? 0,
+    taskId: body.task_id ?? "",
+    justification: body.justification ?? "",
+    duration: body.duration ?? "",
+    reviewTtlSeconds: body.review_ttl_seconds ?? 0,
+    windowStart: body.window_start ?? "",
+    windowEnd: body.window_end ?? "",
+    windowTimezone: body.window_timezone ?? "",
+    reviewRequired: Boolean(body.review_required),
+    reviewedBy: body.reviewed_by ?? "",
+    reviewedAt: body.reviewed_at ?? null,
+    reviewed: Boolean(body.reviewed),
+    approvalId: body.approval_id ?? "",
+    approvals: body.approvals ?? [],
+    decidedBy: body.decided_by ?? [],
+    decidedAt: body.decided_at ?? null,
+    expiresAt: body.expires_at ?? null,
+    createdAt: body.created_at ?? null,
+    reason: body.reason ?? "",
+  };
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** The offline command that checks an exported log. This module verifies
+ * nothing itself: AAES is out of the trust path, and the evidence is checked by
+ * your own binary, key and export. */
+export function verifyHint(exportPath, publicKeyPath = "") {
+  let hint = "aaesctl verify --export " + shellQuote(exportPath);
+  if (String(publicKeyPath).trim()) hint += " --pubkey " + shellQuote(publicKeyPath);
+  return hint;
+}
+
+// shellQuote renders a value for a copy-pasteable shell command. Only a
+// conservative safe set travels unquoted; anything else is single-quoted.
+function shellQuote(value) {
+  const text = String(value);
+  if (text === "") return "''";
+  if (/^[A-Za-z0-9@%_+=:,./-]+$/.test(text)) return text;
+  return "'" + text.replaceAll("'", "'\\''") + "'";
+}
+
+/** Person-only daemon operations. Construct with a separately issued person token.
+ * Naming this class does not confer a role; the daemon checks it on each request. */
+export class OperatorClient extends Client {
+  static fromEnv(options = {}) { return new OperatorClient(options); }
+  async revokeAccessRequest(id, { reason = "" } = {}) {
+    const path = "/v1/access-requests/" + recordId(id) + "/revoke";
+    const { status, body } = await this._request("POST", path, { reason }, { identified: false });
+    if (status !== 200) throw this._statusError("access revocation", status, body);
+    return accessViewFrom(body);
+  }
+}
+
+function recordId(value) {
+  if (typeof value !== "string" || !value.trim() || value.trim() === "." || value.trim() === ".." || /[\\/\x00-\x1f]/.test(value)) {
+    throw new AaesError("aaes: a non-empty record id without path separators is required");
+  }
+  return encodeURIComponent(value.trim());
+}
+function readQuery(filters, mapping) {
+  refuseUnknownKeys(new Set(Object.keys(mapping)), filters, "read filters");
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(filters)) {
+    if (value === undefined || value === null || value === "") continue;
+    if (key === "limit" && (!Number.isInteger(value) || value < 0 || value > 200)) throw new AaesError("aaes: limit must be an integer between 0 and 200; pass 0 or omit it for the daemon default");
+    if (key === "limit" && value === 0) continue;
+    if (key === "overdue" && typeof value !== "boolean") throw new AaesError("aaes: overdue must be boolean");
+    if (key !== "limit" && key !== "overdue" && typeof value !== "string") throw new AaesError("aaes: read filters must be strings");
+    query.set(mapping[key], String(value));
+  }
+  const encoded = query.toString();
+  return encoded ? "?" + encoded : "";
+}