@atlasent/sdk 1.5.0 → 2.10.0

package/dist/hono.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/hono.ts
@@ -28,6 +38,27 @@ __export(hono_exports, {
 module.exports = __toCommonJS(hono_exports);
 
 // src/errors.ts
+var StreamTimeoutError = class extends Error {
+  name = "StreamTimeoutError";
+  /** Timeout that was exceeded, in milliseconds. */
+  timeoutMs;
+  constructor(timeoutMs) {
+    super(`AtlaSent stream timed out after ${timeoutMs}ms with no event`);
+    this.timeoutMs = timeoutMs;
+  }
+};
+var StreamParseError = class extends Error {
+  name = "StreamParseError";
+  /** The raw data string that failed to parse. */
+  rawData;
+  constructor(rawData, cause) {
+    super(`AtlaSent stream received malformed JSON: ${rawData.slice(0, 200)}`);
+    this.rawData = rawData;
+    if (cause !== void 0) {
+      this.cause = cause;
+    }
+  }
+};
 var AtlaSentError = class extends Error {
   // Subclasses override to their own literal (e.g. "AtlaSentDeniedError");
   // keep this assignable rather than pinned to a single literal.
@@ -51,6 +82,18 @@ var AtlaSentError = class extends Error {
     this.retryAfterMs = init.retryAfterMs;
   }
 };
+var KNOWN_PERMIT_OUTCOMES = /* @__PURE__ */ new Set([
+  "permit_consumed",
+  "permit_expired",
+  "permit_revoked",
+  "permit_not_found"
+]);
+function normalizePermitOutcome(raw) {
+  if (raw !== void 0 && KNOWN_PERMIT_OUTCOMES.has(raw)) {
+    return raw;
+  }
+  return void 0;
+}
 var AtlaSentDeniedError = class extends AtlaSentError {
   name = "AtlaSentDeniedError";
   /** Policy decision — `"deny"` today; `"hold"` / `"escalate"` reserved. */
@@ -61,6 +104,12 @@ var AtlaSentDeniedError = class extends AtlaSentError {
   reason;
   /** Hash-chained audit-trail entry associated with the decision. */
   auditHash;
+  /**
+   * Discriminator for permit-side denial reasons. Populated only
+   * when the server reported `verified=false` from `/v1-verify-permit`;
+   * `undefined` for evaluate-time denials. See {@link PermitOutcome}.
+   */
+  outcome;
   constructor(init) {
     const msg = init.reason ? `AtlaSent ${init.decision}: ${init.reason}` : `AtlaSent ${init.decision}`;
     const errInit = { status: 200 };
@@ -70,92 +119,833 @@ var AtlaSentDeniedError = class extends AtlaSentError {
     this.evaluationId = init.evaluationId;
     this.reason = init.reason;
     this.auditHash = init.auditHash;
+    this.outcome = init.outcome;
+  }
+  // ── Outcome discriminators ───────────────────────────────────────
+  // Convenience predicates that mirror the operator runbook's matrix.
+  // Callers can compare `outcome` directly; these are sugar so the
+  // common cases are explicit at the call site.
+  /** `true` when the permit was explicitly revoked (D3 endpoint). */
+  get isRevoked() {
+    return this.outcome === "permit_revoked";
+  }
+  /** `true` when the permit's TTL passed before verification. */
+  get isExpired() {
+    return this.outcome === "permit_expired";
+  }
+  /**
+   * `true` when the permit was already consumed by a prior verify
+   * (v1 single-use replay protection).
+   */
+  get isConsumed() {
+    return this.outcome === "permit_consumed";
+  }
+  /**
+   * `true` when the permit id wasn't recognized server-side
+   * (typo, cross-tenant lookup, or pre-issuance race).
+   */
+  get isNotFound() {
+    return this.outcome === "permit_not_found";
   }
 };
 
+// src/types.ts
+var PRODUCTION_DEPLOY_ACTION = "production.deploy";
+var DEPLOY_GATE_CODES = Object.freeze({
+  ALLOW: "ALLOW",
+  DENY_POLICY: "DENY_POLICY",
+  DENY_AUTHORITY: "DENY_AUTHORITY",
+  DENY_ENVIRONMENT: "DENY_ENVIRONMENT",
+  PERMIT_EXPIRED: "PERMIT_EXPIRED",
+  VERIFY_FAILED: "VERIFY_FAILED",
+  ESCALATE_REQUIRED: "ESCALATE_REQUIRED",
+  OVERRIDE_APPROVED: "OVERRIDE_APPROVED"
+});
+
+// src/compat.ts
+function normalizeEvaluateRequest(input) {
+  if ("action" in input && !("action_type" in input)) {
+    console.warn(
+      "[atlasent] Deprecation: action/agent request shape is deprecated. Use action_type/actor_id instead. This compatibility shim will be removed in v3.0.0."
+    );
+    const legacy = input;
+    const normalized = {
+      action_type: legacy.action,
+      actor_id: legacy.agent
+    };
+    if (legacy.context !== void 0) normalized.context = legacy.context;
+    if (legacy.explain !== void 0) normalized.explain = legacy.explain;
+    return normalized;
+  }
+  return input;
+}
+
+// src/retry.ts
+var DEFAULT_RETRY_POLICY = {
+  maxAttempts: 4,
+  baseDelayMs: 2e3,
+  maxDelayMs: 16e3
+};
+var RETRYABLE_CODES = /* @__PURE__ */ new Set([
+  "network",
+  "timeout",
+  "rate_limited",
+  "server_error",
+  "bad_response"
+]);
+function isRetryable(err) {
+  if (!(err instanceof AtlaSentError)) return false;
+  if (err.code === void 0) return false;
+  return RETRYABLE_CODES.has(err.code);
+}
+function computeBackoffMs(attempt, policy = {}, err, random = Math.random) {
+  const merged = mergePolicy(policy);
+  const safeAttempt = Math.max(0, Math.floor(attempt));
+  const exp = Math.min(safeAttempt, 30);
+  const ceiling = Math.min(merged.maxDelayMs, merged.baseDelayMs * 2 ** exp);
+  const jittered = Math.floor(ceiling * clampUnit(random()));
+  const retryAfterMs = err instanceof AtlaSentError && typeof err.retryAfterMs === "number" ? Math.max(0, err.retryAfterMs) : 0;
+  return Math.max(retryAfterMs, jittered);
+}
+function hasAttemptsLeft(attempt, policy = {}) {
+  const merged = mergePolicy(policy);
+  return attempt + 1 < merged.maxAttempts;
+}
+function mergePolicy(policy) {
+  const maxAttempts = Math.max(
+    1,
+    Math.floor(policy.maxAttempts ?? DEFAULT_RETRY_POLICY.maxAttempts)
+  );
+  const baseDelayMs = Math.max(
+    0,
+    policy.baseDelayMs ?? DEFAULT_RETRY_POLICY.baseDelayMs
+  );
+  const maxDelayMs = Math.max(
+    baseDelayMs,
+    policy.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs
+  );
+  return { maxAttempts, baseDelayMs, maxDelayMs };
+}
+function clampUnit(n) {
+  if (!Number.isFinite(n)) return 0;
+  if (n < 0) return 0;
+  if (n >= 1) return 0.999999999;
+  return n;
+}
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.atlasent.io";
 var DEFAULT_TIMEOUT_MS = 1e4;
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "2.2.0";
+function _buildUserAgent() {
+  const isNode2 = typeof process !== "undefined" && typeof process?.versions?.node === "string";
+  return isNode2 ? `@atlasent/sdk/${SDK_VERSION} node/${process.version}` : `@atlasent/sdk/${SDK_VERSION} browser`;
+}
+var CONTEXT_PROPERTIES_SOFT_CAP = 64;
+function _warnOversizeContext(context) {
+  if (context && Object.keys(context).length > CONTEXT_PROPERTIES_SOFT_CAP) {
+    console.warn(
+      `[atlasent] context has ${Object.keys(context).length} top-level keys (soft cap ${CONTEXT_PROPERTIES_SOFT_CAP}); the server may reject this. Pack richer payloads under a single top-level key.`
+    );
+  }
+}
+function _enforceTls(baseUrl) {
+  const nodeEnvValue = typeof process !== "undefined" && process.env ? process.env.ATLASENT_ALLOW_INSECURE_HTTP : void 0;
+  const allow = nodeEnvValue === "1" || globalThis.ATLASENT_ALLOW_INSECURE_HTTP === "1";
+  if (allow) return baseUrl;
+  let parsed;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    throw new AtlaSentError(`Invalid baseUrl: ${baseUrl}`, {
+      code: "bad_request"
+    });
+  }
+  if (parsed.protocol !== "https:") {
+    throw new AtlaSentError(
+      `AtlaSent baseUrl must use https:// (got ${parsed.protocol}). For local development, set ATLASENT_ALLOW_INSECURE_HTTP=1.`,
+      { code: "bad_request" }
+    );
+  }
+  return baseUrl;
+}
+var API_KEY_PATTERN = /^ask_(?:live|test)_[A-Za-z0-9_-]+$/;
+function _validateApiKey(apiKey) {
+  if (typeof apiKey !== "string" || apiKey.length === 0) {
+    throw new AtlaSentError("apiKey is required", { code: "invalid_api_key" });
+  }
+  if (!API_KEY_PATTERN.test(apiKey)) {
+    const head = apiKey.slice(0, 8);
+    throw new AtlaSentError(
+      `AtlaSent apiKey does not match expected shape \`ask_(live|test)_<entropy>\` (got prefix=${JSON.stringify(head)}). Check for whitespace, quotes, or trailing characters.`,
+      { code: "invalid_api_key" }
+    );
+  }
+  return apiKey;
+}
+var isNode = typeof process !== "undefined" && typeof process.versions?.node === "string";
+var NODE_VERSION = isNode ? process.version : null;
+function deployGateEvidence(input) {
+  const evidence = {};
+  if (input.permitId) evidence.permitId = input.permitId;
+  if (input.permitHash) evidence.permitHash = input.permitHash;
+  if (input.auditHash) evidence.auditHash = input.auditHash;
+  if (input.verifiedAt) evidence.verifiedAt = input.verifiedAt;
+  return evidence;
+}
 var AtlaSentClient = class {
   apiKey;
   baseUrl;
   timeoutMs;
   fetchImpl;
+  userAgent;
+  retryPolicy;
   constructor(options) {
     if (!options.apiKey || typeof options.apiKey !== "string") {
       throw new AtlaSentError("apiKey is required", {
         code: "invalid_api_key"
       });
     }
-    this.apiKey = options.apiKey;
-    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    if (typeof AbortSignal.timeout !== "function") {
+      throw new AtlaSentError(
+        "@atlasent/sdk requires AbortSignal.timeout, which is not available in this runtime. Minimum supported browsers: Chrome 103+, Firefox 100+, Safari 16+. Upgrade your browser or add an AbortSignal.timeout polyfill.",
+        { code: "network" }
+      );
+    }
+    this.apiKey = _validateApiKey(options.apiKey);
+    this.baseUrl = _enforceTls(options.baseUrl ?? DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      ""
+    );
     this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.userAgent = _buildUserAgent();
+    this.retryPolicy = mergePolicy(options.retryPolicy ?? {});
   }
   /**
    * Ask the policy engine whether an agent action is permitted.
    *
-   * A "DENY" is **not** thrown — it is returned in
+   * Accepts either the current v2.0 shape (`action_type` / `actor_id`)
+   * or the legacy v1.x shape (`action` / `agent`). Legacy callers
+   * receive a deprecation warning via `console.warn`; the shim is
+   * handled by {@link normalizeEvaluateRequest} and will be removed
+   * in v3.0.0.
+   *
+   * A "deny" is **not** thrown — it is returned in
    * `response.decision`. Network errors, invalid API key, rate
    * limits, timeouts, and malformed responses throw
    * {@link AtlaSentError}.
    */
   async evaluate(input) {
+    _warnOversizeContext(input.context);
+    const normalized = normalizeEvaluateRequest(
+      input
+    );
     const body = {
-      action: input.action,
-      agent: input.agent,
-      context: input.context ?? {},
-      api_key: this.apiKey
+      action_type: normalized.action_type,
+      actor_id: normalized.actor_id,
+      context: normalized.context ?? {}
     };
-    const { body: wire, rateLimit } = await this.post("/v1-evaluate", body);
-    if (typeof wire.permitted !== "boolean" || typeof wire.decision_id !== "string") {
+    if (normalized.explain !== void 0) body.explain = normalized.explain;
+    const { body: wire, rateLimit } = await this.post(
+      "/v1-evaluate",
+      body
+    );
+    let decision = typeof wire.decision === "string" ? wire.decision.toLowerCase() : wire.decision;
+    if (decision === void 0 && typeof wire.permitted === "boolean") {
+      decision = wire.permitted ? "allow" : "deny";
+    }
+    const permitToken = wire.permit_token ?? wire.decision_id;
+    if (decision !== "allow" && decision !== "deny" && decision !== "hold" && decision !== "escalate") {
+      throw new AtlaSentError(
+        "Malformed response from /v1-evaluate: missing `decision` (or legacy `permitted`)",
+        { code: "bad_response" }
+      );
+    }
+    if (decision === "allow" && (typeof permitToken !== "string" || permitToken.length === 0)) {
       throw new AtlaSentError(
-        "Malformed response from /v1-evaluate: missing `permitted` or `decision_id`",
+        "Malformed response from /v1-evaluate: decision='allow' but no `permit_token` (or legacy `decision_id`)",
         { code: "bad_response" }
       );
     }
+    const reason = wire.denial?.reason ?? wire.reason ?? "";
+    const permitId = permitToken ?? "";
     return {
-      decision: wire.permitted ? "ALLOW" : "DENY",
-      permitId: wire.decision_id,
-      reason: wire.reason ?? "",
+      decision,
+      decision_canonical: decision,
+      evaluationId: permitId,
+      permitId,
+      // /v1-evaluate does not return a control-plane-shaped Permit body;
+      // callers needing the full record fetch GET /v1/permits/:id.
+      permit: null,
+      permitToken: decision === "allow" ? permitToken ?? null : null,
+      reasons: reason ? [reason] : [],
+      reason,
       auditHash: wire.audit_hash ?? "",
       timestamp: wire.timestamp ?? "",
+      rateLimit,
+      ...wire.risk_envelope && {
+        riskEnvelope: {
+          weightedScore: wire.risk_envelope.weighted_score,
+          engineDecision: wire.risk_envelope.engine_decision,
+          envelopeDecision: wire.risk_envelope.envelope_decision,
+          promoted: wire.risk_envelope.promoted,
+          hardBlocks: wire.risk_envelope.hard_blocks ?? [],
+          ...wire.risk_envelope.factors && { factors: wire.risk_envelope.factors }
+        }
+      }
+    };
+  }
+  /**
+   * Batch evaluate — send up to 100 decisions in a single round-trip.
+   *
+   * Wraps `POST /v1-evaluate-batch`. The server evaluates each item
+   * against the active policy bundle and returns results in the same
+   * order as the input. One rate-limit token is consumed for the
+   * whole batch, and one audit-chain entry lists every included
+   * decision id.
+   *
+   * A per-item policy `deny` is **not** thrown — it appears as
+   * `item.decision === "deny"` in the returned items. A whole-batch
+   * network error, 4xx, or 5xx throws {@link AtlaSentError}.
+   *
+   * Requires the `v2_batch` tenant feature flag to be enabled on the
+   * org (returns 404 when off). Requires scope `evaluate:write`.
+   *
+   * @param requests - 1–100 evaluate items.
+   * @param batchId  - Optional caller-supplied UUID for idempotency.
+   *   A retried call with the same `batchId` and identical items
+   *   returns the cached response within 24 h (`replayed: true`).
+   */
+  async evaluateBatch(requests, batchId) {
+    if (!Array.isArray(requests) || requests.length === 0) {
+      throw new AtlaSentError(
+        "evaluateBatch: requests must be a non-empty array",
+        { code: "bad_request" }
+      );
+    }
+    if (requests.length > 100) {
+      throw new AtlaSentError(
+        `evaluateBatch: requests.length ${requests.length} exceeds the 100-item cap`,
+        { code: "bad_request" }
+      );
+    }
+    const wireItems = requests.map((r) => ({
+      action_type: r.action,
+      actor_id: r.agent,
+      context: r.context ?? {}
+    }));
+    const wireBody = { items: wireItems };
+    if (batchId) wireBody.batch_id = batchId;
+    const { body: wire, rateLimit } = await this.post(
+      "/v1-evaluate-batch",
+      wireBody
+    );
+    const items = (wire.items ?? []).map(
+      (item) => {
+        const rawDecision = typeof item.decision === "string" ? item.decision.toLowerCase() : void 0;
+        const decision = rawDecision === "allow" || rawDecision === "deny" || rawDecision === "hold" || rawDecision === "escalate" ? rawDecision : void 0;
+        return {
+          index: item.index,
+          ...decision !== void 0 ? { decision } : {},
+          ...item.decision_id ? { decisionId: item.decision_id } : {},
+          ...item.permit_token != null ? { permitToken: item.permit_token } : {},
+          ...item.reason != null ? { reason: item.reason } : {},
+          ...item.audit_entry_hash ? { auditHash: item.audit_entry_hash } : {},
+          ...item.timestamp ? { timestamp: item.timestamp } : {},
+          ...item.error ? { error: item.error } : {},
+          ...item.message ? { message: item.message } : {}
+        };
+      }
+    );
+    return {
+      batchId: wire.batch_id,
+      items,
+      partial: wire.partial ?? false,
+      ...wire.replayed ? { replayed: wire.replayed } : {},
       rateLimit
     };
   }
+  /**
+   * Subscribe to a live stream of decisions for this org.
+   *
+   * Wraps `GET /v1-decisions-stream`. The server emits one SSE frame
+   * per audit event and sends a heartbeat every 15 s. The session
+   * auto-closes after `maxSeconds` (default 30 min); reconnect with
+   * the last received `event.id` to resume without replaying history.
+   *
+   * ```ts
+   * const controller = new AbortController();
+   * for await (const event of client.subscribeDecisions({ signal: controller.signal })) {
+   *   if (event.type === "heartbeat") continue;
+   *   console.log(event.type, event.decision, event.actorId);
+   *   if (event.type === "session_end") break; // reconnect
+   * }
+   * ```
+   *
+   * Requires scope `audit:read`. Requires the `v2_decisions_stream`
+   * tenant feature flag (returns 404 when off).
+   */
+  async *subscribeDecisions(opts = {}) {
+    const url = new URL(`${this.baseUrl}/v1-decisions-stream`);
+    if (opts.types?.length) url.searchParams.set("types", opts.types.join(","));
+    if (opts.actorId) url.searchParams.set("actor_id", opts.actorId);
+    if (opts.maxSeconds !== void 0) url.searchParams.set("max_seconds", String(opts.maxSeconds));
+    const headers = {
+      Accept: "text/event-stream",
+      Authorization: `Bearer ${this.apiKey}`,
+      "User-Agent": this.userAgent,
+      // ADR-025: declare the wire-protocol version we were built
+      // against. Runtime serves this version's response shape; older
+      // versions outside the compatibility window get 426.
+      "X-AtlaSent-Protocol-Version": "1"
+    };
+    if (opts.lastEventId) headers["Last-Event-ID"] = opts.lastEventId;
+    let response;
+    try {
+      response = await this.fetchImpl(url.toString(), {
+        method: "GET",
+        headers,
+        ...opts.signal ? { signal: opts.signal } : {}
+      });
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") return;
+      throw new AtlaSentError(
+        `Failed to connect to decisions stream: ${err instanceof Error ? err.message : String(err)}`,
+        { code: "network" }
+      );
+    }
+    if (!response.ok) {
+      const code = response.status === 401 ? "invalid_api_key" : "server_error";
+      throw new AtlaSentError(
+        `Decisions stream returned ${response.status}`,
+        { code, status: response.status }
+      );
+    }
+    if (!response.body) {
+      throw new AtlaSentError("Decisions stream response has no body", { code: "bad_response" });
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder("utf-8");
+    let buf = "";
+    try {
+      while (true) {
+        let chunk;
+        try {
+          chunk = await reader.read();
+        } catch (err) {
+          if (err instanceof Error && err.name === "AbortError") return;
+          throw new AtlaSentError(
+            `Decisions stream read error: ${err instanceof Error ? err.message : String(err)}`,
+            { code: "network" }
+          );
+        }
+        if (chunk.done) break;
+        buf += decoder.decode(chunk.value, { stream: true });
+        const rawBlocks = buf.split("\n\n");
+        buf = rawBlocks.pop() ?? "";
+        for (const block of rawBlocks) {
+          if (!block.trim()) continue;
+          if (block.trimStart().startsWith(":")) {
+            yield { type: "heartbeat" };
+            continue;
+          }
+          let id;
+          let eventType = "audit_event";
+          let dataLine = "";
+          for (const line of block.split("\n")) {
+            if (line.startsWith("id:")) id = line.slice(3).trim();
+            else if (line.startsWith("event:")) eventType = line.slice(6).trim();
+            else if (line.startsWith("data:")) dataLine = line.slice(5).trim();
+          }
+          if (!dataLine) continue;
+          let parsed;
+          try {
+            parsed = JSON.parse(dataLine);
+          } catch {
+            continue;
+          }
+          if (eventType === "session_end") {
+            yield { ...id !== void 0 ? { id } : {}, type: "session_end", payload: parsed };
+            return;
+          }
+          const decision = typeof parsed.decision === "string" ? parsed.decision.toLowerCase() : void 0;
+          yield {
+            ...id !== void 0 ? { id } : {},
+            type: eventType,
+            ...decision ? { decision } : {},
+            ...typeof parsed.actor_id === "string" ? { actorId: parsed.actor_id } : {},
+            ...typeof parsed.resource_type === "string" ? { resourceType: parsed.resource_type } : {},
+            ...typeof parsed.resource_id === "string" ? { resourceId: parsed.resource_id } : {},
+            ...parsed.payload && typeof parsed.payload === "object" ? { payload: parsed.payload } : {},
+            ...typeof parsed.hash === "string" ? { hash: parsed.hash } : {},
+            ...typeof parsed.previous_hash === "string" ? { previousHash: parsed.previous_hash } : {},
+            ...typeof parsed.occurred_at === "string" ? { occurredAt: parsed.occurred_at } : {}
+          };
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  /**
+   * Pre-flight evaluation that always returns the constraint trace.
+   *
+   * Wraps `POST /v1-evaluate?include=constraint_trace`. Use this from
+   * a workflow's submission step to surface trivial defects (missing
+   * fields, wrong roles, mis-set context) BEFORE pushing the request
+   * onto an approval queue — only requests that would actually pass
+   * make it through to a human reviewer.
+   *
+   * Returns an {@link EvaluatePreflightResponse} carrying the regular
+   * {@link EvaluateResponse} plus the {@link ConstraintTrace}. Unlike
+   * {@link evaluate}, this method does NOT mark a non-allow as a
+   * thrown condition — the whole point is to inspect both the outcome
+   * AND the per-policy trace, so the caller branches on
+   * `result.evaluation.decision` and reads `result.constraintTrace`
+   * to render the failing stages.
+   *
+   * The constraint-trace shape mirrors `ConstraintTraceResponse` in
+   * atlasent-api (`packages/types/src/index.ts`). On older
+   * atlasent-api deployments that omit the trace, `constraintTrace`
+   * is `null` rather than throwing — forward-compatible degradation.
+   *
+   * Performance: one extra round-trip on submission. Latency is
+   * comparable to {@link evaluate}; the response body is fuller
+   * (includes the per-stage trace) so the wire payload is larger.
+   * If the caller does not need the trace, prefer {@link evaluate}.
+   */
+  async evaluatePreflight(input) {
+    _warnOversizeContext(input.context);
+    const body = {
+      action_type: input.action,
+      actor_id: input.agent,
+      context: input.context ?? {}
+    };
+    const query = new URLSearchParams({ include: "constraint_trace" });
+    const { body: wire, rateLimit } = await this.post(
+      "/v1-evaluate",
+      body,
+      query
+    );
+    let decision = typeof wire.decision === "string" ? wire.decision.toLowerCase() : wire.decision;
+    if (decision === void 0 && typeof wire.permitted === "boolean") {
+      decision = wire.permitted ? "allow" : "deny";
+    }
+    if (decision !== "allow" && decision !== "deny" && decision !== "hold" && decision !== "escalate") {
+      throw new AtlaSentError(
+        "Malformed response from /v1-evaluate: missing `decision` (or legacy `permitted`)",
+        { code: "bad_response" }
+      );
+    }
+    const permitToken = wire.permit_token ?? wire.decision_id;
+    const reason = wire.denial?.reason ?? wire.reason ?? "";
+    const permitId = permitToken ?? "";
+    const evaluation = {
+      decision,
+      decision_canonical: decision,
+      evaluationId: permitId,
+      permitId,
+      // /v1-evaluate does not return a control-plane-shaped Permit body;
+      // callers needing the full record fetch GET /v1/permits/:id.
+      permit: null,
+      permitToken: decision === "allow" ? permitToken ?? null : null,
+      reasons: reason ? [reason] : [],
+      reason,
+      auditHash: wire.audit_hash ?? "",
+      timestamp: wire.timestamp ?? "",
+      rateLimit,
+      ...wire.risk_envelope && {
+        riskEnvelope: {
+          weightedScore: wire.risk_envelope.weighted_score,
+          engineDecision: wire.risk_envelope.engine_decision,
+          envelopeDecision: wire.risk_envelope.envelope_decision,
+          promoted: wire.risk_envelope.promoted,
+          hardBlocks: wire.risk_envelope.hard_blocks ?? [],
+          ...wire.risk_envelope.factors && { factors: wire.risk_envelope.factors }
+        }
+      }
+    };
+    let constraintTrace = null;
+    if (wire.constraint_trace !== void 0 && wire.constraint_trace !== null && typeof wire.constraint_trace === "object") {
+      constraintTrace = wire.constraint_trace;
+    }
+    return { evaluation, constraintTrace };
+  }
   /**
    * Verify that a previously issued permit is still valid.
    *
+   * @deprecated Use {@link verifyPermitById} — the canonical REST
+   * surface (`POST /v1/permits/{id}/verify`) returns the unified
+   * verification envelope plus the full {@link PermitRecord}, instead
+   * of the legacy `{verified, outcome, permitHash}` shape this method
+   * emits. Will be removed in `@atlasent/sdk@3`.
+   *
    * A `verified: false` response is **not** thrown — inspect the
    * returned object. Only transport / server errors throw.
    */
   async verifyPermit(input) {
+    _warnOversizeContext(input.context);
     const body = {
-      decision_id: input.permitId,
-      action: input.action ?? "",
-      agent: input.agent ?? "",
-      context: input.context ?? {},
-      api_key: this.apiKey
+      permit_token: input.permitId,
+      action_type: input.action ?? "",
+      actor_id: input.agent ?? ""
     };
+    if (input.environment !== void 0) {
+      body.environment = input.environment;
+    }
+    if (input.execution_hash !== void 0) {
+      body.execution_hash = input.execution_hash;
+    }
     const { body: wire, rateLimit } = await this.post(
       "/v1-verify-permit",
       body
     );
-    if (typeof wire.verified !== "boolean") {
+    const valid = typeof wire.valid === "boolean" ? wire.valid : wire.verified;
+    if (typeof valid !== "boolean") {
       throw new AtlaSentError(
-        "Malformed response from /v1-verify-permit: missing `verified`",
+        "Malformed response from /v1-verify-permit: missing `valid` (or legacy `verified`)",
         { code: "bad_response" }
       );
     }
     return {
-      verified: wire.verified,
+      verified: valid,
       outcome: wire.outcome ?? "",
       permitHash: wire.permit_hash ?? "",
       timestamp: wire.timestamp ?? "",
+      expiresAt: wire.expires_at ?? null,
+      rateLimit
+    };
+  }
+  /**
+   * Run the canonical Deploy Gate V1 flow:
+   * evaluate `production.deploy`, verify the issued permit server-side,
+   * and return allow/block plus audit/evidence metadata.
+   *
+   * This helper never treats a signed/offline permit artifact as sufficient
+   * authorization. Execution is allowed only when `POST /v1-evaluate` returns
+   * `decision: "allow"` with a permit AND `POST /v1-verify-permit` returns
+   * `verified: true` / `valid: true`.
+   */
+  async deployGate(input = {}) {
+    const agent = input.agent ?? "ci-deploy-bot";
+    const action = input.action ?? PRODUCTION_DEPLOY_ACTION;
+    const context = input.context ?? {};
+    const evaluation = await this.evaluate({ agent, action, context });
+    if (evaluation.decision !== "allow") {
+      return {
+        allowed: false,
+        evaluation,
+        reason: evaluation.reason || `Deploy Gate blocked by decision=${evaluation.decision}`,
+        evidence: deployGateEvidence({
+          permitId: evaluation.permitId,
+          auditHash: evaluation.auditHash
+        })
+      };
+    }
+    const verification = await this.verifyPermit({
+      permitId: evaluation.permitId,
+      agent,
+      action,
+      context
+    });
+    if (!verification.verified) {
+      return {
+        allowed: false,
+        evaluation,
+        verification,
+        reason: verification.outcome ? `Deploy Gate blocked by permit verification outcome=${verification.outcome}` : "Deploy Gate blocked because permit verification failed",
+        evidence: deployGateEvidence({
+          permitId: evaluation.permitId,
+          permitHash: verification.permitHash,
+          auditHash: evaluation.auditHash,
+          verifiedAt: verification.timestamp
+        })
+      };
+    }
+    return {
+      allowed: true,
+      evaluation,
+      verification,
+      reason: evaluation.reason || "Deploy Gate permit verified",
+      evidence: deployGateEvidence({
+        permitId: evaluation.permitId,
+        permitHash: verification.permitHash,
+        auditHash: evaluation.auditHash,
+        verifiedAt: verification.timestamp
+      })
+    };
+  }
+  /**
+   * Revoke a previously-issued permit so it can no longer pass
+   * {@link verifyPermit}.
+   *
+   * @deprecated Use {@link revokePermitById} — the canonical REST
+   * surface (`POST /v1/permits/{id}/revoke`) returns the full updated
+   * {@link PermitRecord} with `revoked_at`/`revoked_by`/`revoke_reason`
+   * populated, instead of the legacy `{revoked, permitId}` envelope
+   * this method emits. Will be removed in `@atlasent/sdk@3`.
+   *
+   * Use this when an agent's action is cancelled, superseded, or
+   * determined to be unauthorized after the fact. The revocation is
+   * recorded in the audit log with the optional `reason`.
+   *
+   * Throws {@link AtlaSentError} on transport / auth failures.
+   */
+  async revokePermit(input) {
+    const body = {
+      decision_id: input.permitId,
+      reason: input.reason ?? "",
+      api_key: this.apiKey
+    };
+    const { body: wire, rateLimit } = await this.post("/v1-revoke-permit", body);
+    if (typeof wire.revoked !== "boolean" || typeof wire.decision_id !== "string") {
+      throw new AtlaSentError(
+        "Malformed response from /v1-revoke-permit: missing `revoked` or `decision_id`",
+        { code: "bad_response" }
+      );
+    }
+    return {
+      revoked: wire.revoked,
+      permitId: wire.decision_id,
+      revokedAt: wire.revoked_at,
+      auditHash: wire.audit_hash,
+      rateLimit
+    };
+  }
+  /**
+   * Revoke a permit through the canonical REST surface
+   * (`POST /v1/permits/{permitId}/revoke`).
+   *
+   * Returns the full updated {@link PermitRecord} with `status === 'revoked'`
+   * and `revoked_at` / `revoked_by` / `revoke_reason` populated. After
+   * revocation, subsequent verify calls return `410 PERMIT_REVOKED`.
+   *
+   * Idempotent on `409 permit_revoked` for already-revoked permits;
+   * server returns the existing revoked row in that case.
+   *
+   * Throws {@link AtlaSentError} on `404` (permit not in calling org),
+   * `409` (already in a terminal state), `410` (expired before revoke),
+   * or `429` (rate limited).
+   */
+  async revokePermitById(permitId, input = {}) {
+    if (!permitId) {
+      throw new AtlaSentError("permitId is required", { code: "bad_request" });
+    }
+    const body = {};
+    if (input.reason !== void 0) body.reason = input.reason;
+    const { body: wire, rateLimit } = await this.post(
+      `/v1/permits/${encodeURIComponent(permitId)}/revoke`,
+      body
+    );
+    return { permit: wire, rateLimit };
+  }
+  /**
+   * Verify a permit through the canonical REST surface
+   * (`POST /v1/permits/{permitId}/verify`).
+   *
+   * Returns the unified verification envelope (`valid`,
+   * `verification_type: 'permit'`, `reason`, `verified_at`, `evidence`)
+   * plus the full {@link PermitRecord} fields preserved at the top
+   * level. The `valid` field is the contract — pin to it.
+   *
+   * A `valid: false` is **not** thrown when the server returns 200 with
+   * a denial reason (matches the verify-shape unification on the wire);
+   * it is thrown on 4xx (`404` not found, `410` expired/consumed).
+   */
+  async verifyPermitById(permitId) {
+    if (!permitId) {
+      throw new AtlaSentError("permitId is required", { code: "bad_request" });
+    }
+    const { body: wire, rateLimit } = await this.post(`/v1/permits/${encodeURIComponent(permitId)}/verify`, {});
+    const { valid, verification_type, reason, verified_at, evidence, ...row } = wire;
+    return {
+      valid,
+      verification_type,
+      reason,
+      verified_at,
+      evidence,
+      permit: row,
       rateLimit
     };
   }
+  /**
+   * Get a single permit's full lifecycle state.
+   *
+   * Calls `GET /v1/permits/{permitId}` (the canonical REST surface).
+   * Returns `status`, all timestamps, `revoked_at` / `revoked_by` /
+   * `revoke_reason` (when applicable), and the bound `payload_hash`
+   * / `decision_id`.
+   *
+   * Operator-facing introspection — answers "what state is this permit
+   * in, and why?" without reading audit logs.
+   *
+   * Throws {@link AtlaSentError} on `404` (permit not in calling org)
+   * or `410` (expired before retrieval).
+   */
+  async getPermit(permitId) {
+    if (!permitId) {
+      throw new AtlaSentError("permitId is required", { code: "bad_request" });
+    }
+    const { body: wire, rateLimit } = await this.get(
+      `/v1/permits/${encodeURIComponent(permitId)}`
+    );
+    return { permit: wire, rateLimit };
+  }
+  /**
+   * Poll whether a permit is currently valid.
+   *
+   * Calls `GET /v1/permits/{permitId}/valid` — a lightweight read
+   * returning only the status snapshot optimised for guard heartbeat
+   * polling. Guards with `permitRevalidationIntervalMs` set race this
+   * against `tool.execute()` and throw {@link PermitRevoked} when
+   * `status === "revoked"` arrives.
+   *
+   * Throws {@link AtlaSentError} on transport / auth failures.
+   */
+  async checkPermitValid(permitId) {
+    if (!permitId) {
+      throw new AtlaSentError("permitId is required", { code: "bad_request" });
+    }
+    const { body } = await this.get(
+      `/v1/permits/${encodeURIComponent(permitId)}/valid`
+    );
+    return body;
+  }
+  /**
+   * List permits issued to the calling org, most-recently-issued first.
+   *
+   * Calls `GET /v1/permits` (the canonical REST surface). Cursor-paged.
+   * Filters narrow on server side; pagination uses the `created_at`
+   * timestamp opaquely (`nextCursor`).
+   *
+   * Designed for incident review, debugging, and compliance
+   * reconstruction.
+   */
+  async listPermits(input = {}) {
+    const params = new URLSearchParams();
+    if (input.status) params.set("status", input.status);
+    if (input.actorId) params.set("actor_id", input.actorId);
+    if (input.actionType) params.set("action_type", input.actionType);
+    if (input.from) params.set("from", input.from);
+    if (input.to) params.set("to", input.to);
+    if (input.limit !== void 0) params.set("limit", String(input.limit));
+    if (input.cursor) params.set("cursor", input.cursor);
+    const { body: wire, rateLimit } = await this.get("/v1/permits", params);
+    if (!Array.isArray(wire.permits)) {
+      throw new AtlaSentError(
+        "Malformed response from /v1/permits: missing `permits` array",
+        { code: "bad_response" }
+      );
+    }
+    const result = {
+      permits: wire.permits,
+      total: typeof wire.total === "number" ? wire.total : wire.permits.length,
+      rateLimit
+    };
+    if (wire.next_cursor !== void 0) result.nextCursor = wire.next_cursor;
+    return result;
+  }
   /**
    * Self-introspection: ask the server to describe the API key this
    * client was constructed with. Returns the key's ID, organization,
@@ -170,9 +960,7 @@ var AtlaSentClient = class {
    * taxonomy as {@link AtlaSentClient.evaluate}.
    */
   async keySelf() {
-    const { body: wire, rateLimit } = await this.get(
-      "/v1-api-key-self"
-    );
+    const { body: wire, rateLimit } = await this.get("/v1-api-key-self");
     if (typeof wire.key_id !== "string" || typeof wire.organization_id !== "string") {
       throw new AtlaSentError(
         "Malformed response from /v1-api-key-self: missing `key_id` or `organization_id`",
@@ -247,8 +1035,276 @@ var AtlaSentClient = class {
     }
     return { ...wire, rateLimit };
   }
-  async post(path, body) {
-    return this.request(path, "POST", body, void 0);
+  /**
+   * Re-evaluate a recorded decision against its originally-pinned policy
+   * bundle and engine version, and report whether the result agrees with
+   * what was recorded.
+   *
+   * Wraps `POST /v1-decisions-replay/:id/replay`. **Side-effect-free** — no
+   * audit chain row is written and no permit is issued (per ADR-016).
+   * Useful for compliance review, regression testing of bundle changes,
+   * and post-incident investigation.
+   *
+   * Outcomes encoded in the response:
+   * - `variance: "NONE"` — replay agrees with the original decision.
+   * - `variance: "DECISION_CHANGED"` — same envelope, same bundle, different
+   *   decision. Almost always indicates non-determinism in a rule
+   *   (e.g. wall-clock comparison) and warrants investigation.
+   * - `variance: "ENVELOPE_DRIFT"` — the recorded request envelope no longer
+   *   hashes to the recorded value. The replay short-circuits without
+   *   running the engine; `replay_decision` is absent. Treat as evidence
+   *   of substrate tamper or a recorder bug.
+   *
+   * Server-side 409 responses (replay refused because the engine version
+   * does not accept replay, or because no bundle was pinned) surface as
+   * `AtlaSentError` with `code: "replay_not_eligible"` — callers should
+   * treat them as expected for old / un-pinned decisions, not as bugs.
+   *
+   * Requires the `evaluate:write` API key scope.
+   *
+   * @param decisionId The UUID of the recorded decision to replay.
+   *                   Matches `execution_evaluations.request_id`.
+   *
+   * @example
+   * ```ts
+   * const result = await client.replayDecision("dec_abc123");
+   * if (result.variance === "DECISION_CHANGED") {
+   *   console.warn(
+   *     `Decision ${result.decision_id} changed on replay: ` +
+   *     `${result.original_decision} → ${result.replay_decision}`,
+   *   );
+   * }
+   * ```
+   */
+  async replayDecision(decisionId) {
+    if (typeof decisionId !== "string" || decisionId.length === 0) {
+      throw new AtlaSentError("decisionId is required", {
+        code: "bad_request"
+      });
+    }
+    const path = `/v1-decisions-replay/${encodeURIComponent(decisionId)}/replay`;
+    const { body: wire, rateLimit } = await this.post(
+      path,
+      {}
+    );
+    if (typeof wire.decision_id !== "string" || typeof wire.original_decision !== "string" || typeof wire.engine_version_kind !== "string" || typeof wire.accepts_replay !== "boolean" || typeof wire.variance !== "string" || typeof wire.envelope_verification !== "string" || typeof wire.replayed_at !== "string") {
+      throw new AtlaSentError(
+        "Malformed response from /v1-decisions-replay/:id/replay: missing required fields",
+        { code: "bad_response" }
+      );
+    }
+    return { ...wire, rateLimit };
+  }
+  /**
+   * ADR-015 Phase C — SDK-canonical replay runtime.
+   *
+   * Re-evaluates a recorded decision against its originally-pinned policy
+   * bundle and engine version via `POST /v1/decisions/:id/replay`.
+   * Side-effect-free server-side: no audit chain row is written and no
+   * permit is issued (ADR-016 `mode: "replay"` sentinel).
+   *
+   * Differences from {@link replayDecision} (the 2.7.0 raw-wire surface):
+   *
+   * | | `replayDecision()` | `replay()` |
+   * | --- | --- | --- |
+   * | Path | `/v1-decisions-replay/:id/replay` | `/v1/decisions/:id/replay` |
+   * | Variance | raw wire (`DECISION_CHANGED`) | SDK-canonical (`POLICY_DRIFT`) |
+   * | 409 handling | throws `AtlaSentError` | returns `ENGINE_DRIFT` / `BUNDLE_MISSING` |
+   * | Input shape | `decisionId: string` | `{ evaluationId }` |
+   *
+   * **Never throws on `409 replay_not_eligible`** — instead returns a
+   * `ReplayResponse` with `varianceKind: "ENGINE_DRIFT"` (engine retired
+   * beyond archival window) or `"BUNDLE_MISSING"` (no bundle pinned on
+   * the original evaluation). Callers can always `switch` on
+   * `result.varianceKind` without a try/catch.
+   *
+   * Fix-forward note: this method was originally landed in PR #275 but
+   * dropped from the squash merge. The TS types (`ReplayResponse`,
+   * `ReplayRequest`) and CHANGELOG made it through; the method itself
+   * did not. Restored here to match the Python {@link
+   * AtlaSentClient}.replay() that landed in atlasent-sdk@2.6.0 (Python).
+   */
+  async replay(input) {
+    if (!input || typeof input.evaluationId !== "string" || input.evaluationId.length === 0) {
+      throw new AtlaSentError("evaluationId is required", {
+        code: "bad_request"
+      });
+    }
+    const path = `/v1/decisions/${encodeURIComponent(input.evaluationId)}/replay`;
+    let wire;
+    let rateLimit;
+    try {
+      const result = await this.post(path, {});
+      wire = result.body;
+      rateLimit = result.rateLimit;
+    } catch (err) {
+      if (err instanceof AtlaSentError && err.status === 409) {
+        const msg = (err.message ?? "").toLowerCase();
+        const varianceKind2 = msg.includes("bundle") ? "BUNDLE_MISSING" : "ENGINE_DRIFT";
+        return {
+          decisionId: input.evaluationId,
+          varianceKind: varianceKind2,
+          originalDecision: "deny",
+          acceptsReplay: false,
+          replayedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          rateLimit: null
+        };
+      }
+      throw err;
+    }
+    const VARIANCE_MAP = {
+      NONE: "NONE",
+      DECISION_CHANGED: "POLICY_DRIFT",
+      ENVELOPE_DRIFT: "ENVELOPE_DRIFT",
+      CHAIN_TAMPER: "CHAIN_TAMPER",
+      BUNDLE_MISSING: "BUNDLE_MISSING",
+      ENGINE_DRIFT: "ENGINE_DRIFT"
+    };
+    const rawVariance = typeof wire.variance === "string" ? wire.variance : "";
+    const varianceKind = VARIANCE_MAP[rawVariance] ?? "NONE";
+    const replayDec = typeof wire.replay_decision === "string" ? wire.replay_decision.toLowerCase() : void 0;
+    const originalDec = typeof wire.original_decision === "string" ? wire.original_decision.toLowerCase() : "deny";
+    const response = {
+      decisionId: typeof wire.decision_id === "string" ? wire.decision_id : input.evaluationId,
+      varianceKind,
+      originalDecision: originalDec,
+      acceptsReplay: typeof wire.accepts_replay === "boolean" ? wire.accepts_replay : true,
+      replayedAt: typeof wire.replayed_at === "string" ? wire.replayed_at : (/* @__PURE__ */ new Date()).toISOString(),
+      rateLimit
+    };
+    if (typeof wire.original_deny_code === "string") response.originalDenyCode = wire.original_deny_code;
+    if (replayDec !== void 0) response.replayedDecision = replayDec;
+    if (typeof wire.replay_deny_code === "string") response.replayedDenyCode = wire.replay_deny_code;
+    if (typeof wire.engine_version === "string") response.engineVersion = wire.engine_version;
+    if (typeof wire.engine_version_kind === "string") response.engineVersionKind = wire.engine_version_kind;
+    if (typeof wire.envelope_verification === "string") response.envelopeVerification = wire.envelope_verification;
+    return response;
+  }
+  /**
+   * Open a streaming evaluation session against `POST /v1-evaluate-stream`.
+   *
+   * Yields {@link StreamDecisionEvent} and {@link StreamProgressEvent} objects
+   * as the server emits them. The iterator ends cleanly when the server sends
+   * `event: done`; it throws {@link AtlaSentError} on transport errors or when
+   * the server sends `event: error`.
+   *
+   * The final {@link StreamDecisionEvent} (isFinal: true) carries a `permitId`
+   * suitable for passing to {@link verifyPermit} after the stream closes.
+   *
+   * Hardening:
+   * - Throws {@link StreamTimeoutError} when no event arrives within
+   *   `opts.timeoutMs` (default 30 s). Pass `0` to disable.
+   * - Retries up to `opts.maxRetries` times (default 3) with 1 s / 2 s / 4 s
+   *   delays on network drop (before a terminal event). Sends `Last-Event-ID`
+   *   on reconnect when the server has emitted event IDs.
+   * - Throws {@link StreamParseError} on partial / malformed JSON rather than
+   *   crashing with a raw `SyntaxError`.
+   * - Closes cleanly on `event: done` or a decision event with `done: true`.
+   *
+   * ```ts
+   * for await (const event of client.protectStream({ agent, action })) {
+   *   if (event.type === "decision" && event.isFinal) {
+   *     await client.verifyPermit({ permitId: event.permitId });
+   *   }
+   * }
+   * ```
+   */
+  async *protectStream(input, opts = {}) {
+    const streamTimeoutMs = opts.timeoutMs ?? 3e4;
+    const maxRetries = opts.maxRetries ?? 3;
+    const body = {
+      action: input.action,
+      agent: input.agent,
+      context: input.context ?? {},
+      api_key: this.apiKey
+    };
+    const requestId = globalThis.crypto.randomUUID();
+    const url = `${this.baseUrl}/v1-evaluate-stream`;
+    let lastEventId;
+    let retryCount = 0;
+    while (true) {
+      const headers = {
+        Accept: "text/event-stream",
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`,
+        "User-Agent": this.userAgent,
+        // ADR-025: wire-protocol version declared on every request.
+        "X-AtlaSent-Protocol-Version": "1",
+        "X-Request-ID": requestId
+      };
+      if (lastEventId !== void 0) {
+        headers["Last-Event-ID"] = lastEventId;
+      }
+      const connectionTimeoutSignal = AbortSignal.timeout(this.timeoutMs);
+      const signal = opts.signal ? AbortSignal.any([connectionTimeoutSignal, opts.signal]) : connectionTimeoutSignal;
+      let response;
+      try {
+        response = await this.fetchImpl(url, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(body),
+          signal
+        });
+      } catch (err) {
+        const mapped = mapFetchError(err, requestId);
+        if (mapped.code === "network" && retryCount < maxRetries) {
+          retryCount++;
+          await sleep(1e3 * Math.pow(2, retryCount - 1));
+          continue;
+        }
+        throw mapped;
+      }
+      if (!response.ok) {
+        throw await buildHttpError(response, requestId);
+      }
+      if (!response.body) {
+        throw new AtlaSentError("Expected streaming body from AtlaSent API", {
+          code: "bad_response",
+          status: response.status,
+          requestId
+        });
+      }
+      let streamDone = false;
+      let networkDrop = false;
+      try {
+        for await (const event of parseSseStream(
+          response.body,
+          requestId,
+          streamTimeoutMs,
+          (id) => {
+            lastEventId = id;
+          }
+        )) {
+          yield event;
+          if (event.type === "decision" && event.isFinal) {
+            streamDone = true;
+          }
+        }
+        streamDone = true;
+      } catch (err) {
+        if (err instanceof AtlaSentError && err.code === "network") {
+          networkDrop = true;
+        } else {
+          throw err;
+        }
+      }
+      if (streamDone) break;
+      if (networkDrop && retryCount < maxRetries) {
+        retryCount++;
+        await sleep(1e3 * Math.pow(2, retryCount - 1));
+        continue;
+      }
+      if (networkDrop) {
+        throw new AtlaSentError(
+          `AtlaSent stream dropped after ${retryCount} reconnection attempts`,
+          { code: "network", requestId }
+        );
+      }
+      break;
+    }
+  }
+  async post(path, body, query) {
+    return this.request(path, "POST", body, query);
   }
   async get(path, query) {
     return this.request(path, "GET", void 0, query);
@@ -260,48 +1316,688 @@ var AtlaSentClient = class {
     const headers = {
       Accept: "application/json",
       Authorization: `Bearer ${this.apiKey}`,
-      "User-Agent": `@atlasent/sdk/${SDK_VERSION} node/${process.version}`,
-      "X-Request-ID": requestId
+      "User-Agent": this.userAgent,
+      "X-Request-ID": requestId,
+      // ADR-025: wire-protocol version declared on every request.
+      "X-AtlaSent-Protocol-Version": "1"
     };
     if (method === "POST") headers["Content-Type"] = "application/json";
-    const init = {
-      method,
-      headers,
-      signal: AbortSignal.timeout(this.timeoutMs)
-    };
-    if (method === "POST") init.body = JSON.stringify(body);
-    let response;
-    try {
-      response = await this.fetchImpl(url, init);
-    } catch (err) {
-      throw mapFetchError(err, requestId);
+    const bodyStr = method === "POST" ? JSON.stringify(body) : void 0;
+    for (let attempt = 0; ; attempt++) {
+      const init = {
+        method,
+        headers,
+        signal: AbortSignal.timeout(this.timeoutMs)
+      };
+      if (bodyStr !== void 0) init.body = bodyStr;
+      let response;
+      try {
+        response = await this.fetchImpl(url, init);
+      } catch (err) {
+        const mapped = mapFetchError(err, requestId);
+        if (isRetryable(mapped) && hasAttemptsLeft(attempt, this.retryPolicy)) {
+          await sleep(computeBackoffMs(attempt, this.retryPolicy, mapped));
+          continue;
+        }
+        throw mapped;
+      }
+      if (!response.ok) {
+        const httpErr = await buildHttpError(response, requestId);
+        if (isRetryable(httpErr) && hasAttemptsLeft(attempt, this.retryPolicy)) {
+          await sleep(computeBackoffMs(attempt, this.retryPolicy, httpErr));
+          continue;
+        }
+        throw httpErr;
+      }
+      let parsed;
+      try {
+        parsed = await response.json();
+      } catch (err) {
+        const jsonErr = new AtlaSentError(
+          "Invalid JSON response from AtlaSent API",
+          {
+            code: "bad_response",
+            status: response.status,
+            requestId,
+            cause: err
+          }
+        );
+        if (isRetryable(jsonErr) && hasAttemptsLeft(attempt, this.retryPolicy)) {
+          await sleep(computeBackoffMs(attempt, this.retryPolicy, jsonErr));
+          continue;
+        }
+        throw jsonErr;
+      }
+      if (parsed === null || typeof parsed !== "object") {
+        const shapeErr = new AtlaSentError(
+          "Expected a JSON object from AtlaSent API",
+          {
+            code: "bad_response",
+            status: response.status,
+            requestId
+          }
+        );
+        if (isRetryable(shapeErr) && hasAttemptsLeft(attempt, this.retryPolicy)) {
+          await sleep(computeBackoffMs(attempt, this.retryPolicy, shapeErr));
+          continue;
+        }
+        throw shapeErr;
+      }
+      return {
+        body: parsed,
+        rateLimit: parseRateLimitHeaders(response.headers)
+      };
     }
-    if (!response.ok) {
-      throw await buildHttpError(response, requestId);
+  }
+  /**
+   * Open a new HITL escalation. Bridges a `hold` outcome from
+   * `protect()` to the approval queue: an agent that receives a
+   * `hold` decision calls this to enroll the proposed action for
+   * human review. The returned escalation can then be polled with
+   * `getHitlEscalation()` or driven to terminal by
+   * `approveHitlEscalation()` / `rejectHitlEscalation()`.
+   *
+   * Quorum, pool size, fallback decision and routing inherit from
+   * the server-side policy when omitted from `input`.
+   *
+   * Calls `POST /v1/hitl`.
+   */
+  async createHitlEscalation(input) {
+    const { body, rateLimit } = await this.post(
+      "/v1/hitl",
+      input
+    );
+    return { escalation: body, rateLimit };
+  }
+  /**
+   * List HITL escalations for the calling org. Defaults to
+   * `status=pending`; pass `status` to query other queues
+   * (`escalated`, `approved`, `rejected`, `auto_approved`,
+   * `timed_out`).
+   *
+   * Calls `GET /v1/hitl`.
+   */
+  async listHitlEscalations(input = {}) {
+    const params = new URLSearchParams();
+    if (input.status) params.set("status", input.status);
+    if (input.agentId) params.set("agent_id", input.agentId);
+    if (input.assignedToUserId)
+      params.set("assigned_to_user_id", input.assignedToUserId);
+    if (input.limit !== void 0) params.set("limit", String(input.limit));
+    if (input.cursor) params.set("cursor", input.cursor);
+    const { body, rateLimit } = await this.get(
+      "/v1/hitl",
+      params
+    );
+    return { data: body, rateLimit };
+  }
+  /**
+   * Get a HITL escalation. The server payload includes a live
+   * `quorum_progress` snapshot when the escalation is still open.
+   *
+   * Calls `GET /v1/hitl/:id`.
+   */
+  async getHitlEscalation(escalationId) {
+    if (!escalationId) {
+      throw new AtlaSentError("escalationId is required", {
+        code: "bad_request"
+      });
     }
-    let parsed;
-    try {
-      parsed = await response.json();
-    } catch (err) {
-      throw new AtlaSentError("Invalid JSON response from AtlaSent API", {
-        code: "bad_response",
-        status: response.status,
-        requestId,
-        cause: err
+    const { body, rateLimit } = await this.get(
+      `/v1/hitl/${encodeURIComponent(escalationId)}`
+    );
+    return { escalation: body, rateLimit };
+  }
+  /**
+   * List per-approver vote rows for an escalation.
+   * Calls `GET /v1/hitl/:id/approvals`.
+   */
+  async listHitlApprovals(escalationId) {
+    const { body, rateLimit } = await this.get(`/v1/hitl/${encodeURIComponent(escalationId)}/approvals`);
+    return { approvals: body.approvals ?? [], rateLimit };
+  }
+  /**
+   * List the escalation chain hops for an escalation. Each `/escalate`
+   * call appends one row.
+   * Calls `GET /v1/hitl/:id/chain`.
+   */
+  async getHitlChain(escalationId) {
+    const { body, rateLimit } = await this.get(
+      `/v1/hitl/${encodeURIComponent(escalationId)}/chain`
+    );
+    return { chain: body.chain ?? [], rateLimit };
+  }
+  /**
+   * Record an approve vote. Resolves the escalation only once the
+   * server-side quorum count is satisfied; before that the response
+   * carries a refreshed escalation row with the latest
+   * `quorum_progress`.
+   *
+   * Calls `POST /v1/hitl/:id/approve`. The server returns 409
+   * `duplicate_vote` if the same principal has already voted, and
+   * 409 `already_rejected` if a concurrent reject crossed the line.
+   */
+  async approveHitlEscalation(escalationId, input = {}) {
+    const { body, rateLimit } = await this.post(
+      `/v1/hitl/${encodeURIComponent(escalationId)}/approve`,
+      input
+    );
+    return { escalation: body, rateLimit };
+  }
+  /**
+   * Record a reject vote. Reject is short-circuit terminal — a single
+   * reject closes the escalation regardless of how many approves have
+   * accumulated.
+   *
+   * Calls `POST /v1/hitl/:id/reject`.
+   */
+  async rejectHitlEscalation(escalationId, input = {}) {
+    const { body, rateLimit } = await this.post(
+      `/v1/hitl/${encodeURIComponent(escalationId)}/reject`,
+      input
+    );
+    return { escalation: body, rateLimit };
+  }
+  /**
+   * Re-route an open escalation to a higher tier. Bounded by the
+   * escalation's `max_escalation_depth` — the server returns 409
+   * `chain_exhausted` and applies the configured fallback decision
+   * once the ceiling is hit.
+   *
+   * Calls `POST /v1/hitl/:id/escalate`.
+   */
+  async escalateHitlEscalation(escalationId, input) {
+    const { body, rateLimit } = await this.post(
+      `/v1/hitl/${encodeURIComponent(escalationId)}/escalate`,
+      input
+    );
+    return { escalation: body, rateLimit };
+  }
+  /**
+   * Manually apply the escalation's `fallback_decision`. Useful for
+   * admin recovery of a hung escalation when the cron sweeper hasn't
+   * run yet, or to short-circuit a stuck flow during incident
+   * response.
+   *
+   * Calls `POST /v1/hitl/:id/timeout`.
+   */
+  async timeoutHitlEscalation(escalationId) {
+    const { body, rateLimit } = await this.post(
+      `/v1/hitl/${encodeURIComponent(escalationId)}/timeout`,
+      {}
+    );
+    return { escalation: body, rateLimit };
+  }
+  /**
+   * Run a named governance graph traversal query.
+   *
+   * Dispatches to `GET /v1/governance/graph/query?type=<queryType>`.
+   * Each query type returns a different row shape — the return type
+   * narrows automatically based on the literal `queryType` argument.
+   *
+   * `"user_approvals"` requires `params.actor_id` — the server returns
+   * a 400 if it is absent.
+   */
+  async queryGovernanceGraph(queryType, params = {}) {
+    const qs = new URLSearchParams({ type: queryType });
+    if (params.actor_id) qs.set("actor_id", params.actor_id);
+    const { body, rateLimit } = await this.get("/v1/governance/graph/query", qs);
+    return { ...body, rateLimit };
+  }
+  /**
+   * Reconstruct the multi-system execution timeline for a specific incident.
+   *
+   * Calls `GET /v1/governance/timeline/incident/{incidentId}`. Backed
+   * server-side by `reconstruct_incident_chains_v2()`, which fixes the
+   * `executor_id → actor_id` bug that silently produced empty timelines
+   * in the original function.
+   *
+   * Returns full execution rows including the §13.1 columns
+   * (`delegation_chain_id`, `replay_of_execution_id`, `incident_id`,
+   * `policy_version_id`, `bundle_version_id`) alongside the actor
+   * timeline and evidence rows.
+   */
+  async getIncidentTimeline(incidentId) {
+    if (!incidentId) {
+      throw new AtlaSentError("incidentId is required", {
+        code: "bad_request"
       });
     }
-    if (parsed === null || typeof parsed !== "object") {
-      throw new AtlaSentError("Expected a JSON object from AtlaSent API", {
-        code: "bad_response",
-        status: response.status,
-        requestId
+    const { body, rateLimit } = await this.get(`/v1/governance/timeline/incident/${encodeURIComponent(incidentId)}`);
+    return { ...body, rateLimit };
+  }
+  // ── Connector Management ─────────────────────────────────────────────────
+  /**
+   * List connectors registered for the calling org.
+   * Calls `GET /v1/governance/connectors`.
+   */
+  async listConnectors(options = {}) {
+    const params = new URLSearchParams();
+    if (options.cursor) params.set("cursor", options.cursor);
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    const { body, rateLimit } = await this.get("/v1/governance/connectors", params);
+    const result = {
+      connectors: body.connectors ?? [],
+      total: body.total,
+      rateLimit
+    };
+    if (body.next_cursor) result.nextCursor = body.next_cursor;
+    return result;
+  }
+  /**
+   * Register and install a new connector for the calling org.
+   * Calls `POST /v1/governance/connectors`.
+   */
+  async installConnector(input) {
+    const { body, rateLimit } = await this.post("/v1/governance/connectors", input);
+    return { connector: body, rateLimit };
+  }
+  /**
+   * Store encrypted credentials for a connector.
+   * Calls `POST /v1/governance/connectors/{id}/authenticate`.
+   */
+  async authenticateConnector(connectorId, input) {
+    if (!connectorId) {
+      throw new AtlaSentError("connectorId is required", {
+        code: "bad_request"
       });
     }
+    const { body, rateLimit } = await this.post(
+      `/v1/governance/connectors/${encodeURIComponent(connectorId)}/authenticate`,
+      input
+    );
     return {
-      body: parsed,
-      rateLimit: parseRateLimitHeaders(response.headers)
+      credential_id: body.credential_id,
+      version: body.version,
+      rateLimit
     };
   }
+  /**
+   * Trigger an incremental sync for a connector.
+   * Calls `POST /v1/governance/connectors/{id}/sync`.
+   */
+  async syncConnector(connectorId) {
+    if (!connectorId) {
+      throw new AtlaSentError("connectorId is required", {
+        code: "bad_request"
+      });
+    }
+    const { body, rateLimit } = await this.post(`/v1/governance/connectors/${encodeURIComponent(connectorId)}/sync`, {});
+    return { ...body, rateLimit };
+  }
+  /**
+   * Revoke a connector and all its associated credentials.
+   * Calls `POST /v1/governance/connectors/{id}/revoke`.
+   */
+  async revokeConnector(connectorId, reason) {
+    if (!connectorId) {
+      throw new AtlaSentError("connectorId is required", {
+        code: "bad_request"
+      });
+    }
+    const body = {};
+    if (reason !== void 0) body.reason = reason;
+    const { body: wire, rateLimit } = await this.post(
+      `/v1/governance/connectors/${encodeURIComponent(connectorId)}/revoke`,
+      body
+    );
+    return { ...wire, rateLimit };
+  }
+  /**
+   * Rotate the credentials for a connector.
+   * Calls `POST /v1/governance/connectors/{id}/rotate-credentials`.
+   */
+  async rotateConnectorCredentials(connectorId) {
+    if (!connectorId) {
+      throw new AtlaSentError("connectorId is required", {
+        code: "bad_request"
+      });
+    }
+    const { body, rateLimit } = await this.post(
+      `/v1/governance/connectors/${encodeURIComponent(connectorId)}/rotate-credentials`,
+      {}
+    );
+    return { ...body, rateLimit };
+  }
+  /**
+   * List enforcement policies for the calling org, optionally filtered by connector type.
+   * Calls `GET /v1/governance/enforcement-policies`.
+   */
+  async listEnforcementPolicies(connectorType) {
+    const params = new URLSearchParams();
+    if (connectorType) params.set("connector_type", connectorType);
+    const { body, rateLimit } = await this.get("/v1/governance/enforcement-policies", params);
+    return { policies: body.policies ?? [], total: body.total, rateLimit };
+  }
+  /**
+   * Create or update a connector enforcement policy.
+   * Calls `POST /v1/governance/enforcement-policies`.
+   */
+  async upsertEnforcementPolicy(input) {
+    const { body, rateLimit } = await this.post("/v1/governance/enforcement-policies", input);
+    return { policy: body, rateLimit };
+  }
+  // ── Organizational Risk Graph ─────────────────────────────────────────────
+  /**
+   * Trigger a fresh org-level risk score computation.
+   * Calls `POST /v1/governance/risk/compute`.
+   */
+  async computeOrgRisk(options = {}) {
+    const { body, rateLimit } = await this.post("/v1/governance/risk/compute", options);
+    return { score: body, rateLimit };
+  }
+  /**
+   * Retrieve the most recently computed risk score for the calling org.
+   * Calls `GET /v1/governance/risk/latest`.
+   */
+  async getLatestOrgRisk() {
+    const { body, rateLimit } = await this.get("/v1/governance/risk/latest");
+    return { score: body.score ?? null, rateLimit };
+  }
+  /**
+   * Page through historical org risk scores, most-recent first.
+   * Calls `GET /v1/governance/risk/history`.
+   */
+  async listOrgRiskHistory(options = {}) {
+    const params = new URLSearchParams();
+    if (options.cursor) params.set("cursor", options.cursor);
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    const { body, rateLimit } = await this.get("/v1/governance/risk/history", params);
+    const result = {
+      scores: body.scores ?? [],
+      total: body.total,
+      rateLimit
+    };
+    if (body.next_cursor) result.nextCursor = body.next_cursor;
+    return result;
+  }
+  // ── Cross-Org Permission Negotiation ──────────────────────────────────────
+  async checkCrossOrgPermission(req) {
+    const { body } = await this.post(
+      "/v1/cross-org/permissions/check",
+      req
+    );
+    return body;
+  }
+  async listCrossOrgPermissionChecks(params) {
+    const qs = new URLSearchParams();
+    if (params?.source_org_id) qs.set("source_org_id", params.source_org_id);
+    if (params?.target_org_id) qs.set("target_org_id", params.target_org_id);
+    if (params?.allowed !== void 0)
+      qs.set("allowed", String(params.allowed));
+    if (params?.limit !== void 0) qs.set("limit", String(params.limit));
+    const { body } = await this.get("/v1/cross-org/permissions/checks", qs);
+    return body.checks ?? [];
+  }
+  // ── Anomaly Response Automation ───────────────────────────────────────────
+  async listAnomalyResponseRules() {
+    const { body } = await this.get(
+      "/v1/anomaly-response/rules"
+    );
+    return body.rules ?? [];
+  }
+  async createAnomalyResponseRule(req) {
+    const { body } = await this.post(
+      "/v1/anomaly-response/rules",
+      req
+    );
+    return body;
+  }
+  async updateAnomalyResponseRule(id, updates) {
+    const { body } = await this.post(
+      `/v1/anomaly-response/rules/${encodeURIComponent(id)}/update`,
+      updates
+    );
+    return body;
+  }
+  async deleteAnomalyResponseRule(id) {
+    await this.post(
+      `/v1/anomaly-response/rules/${encodeURIComponent(id)}/delete`,
+      {}
+    );
+  }
+  async triggerAnomalyResponse(req) {
+    const { body } = await this.post(
+      "/v1/anomaly-response/trigger",
+      req
+    );
+    return body.events ?? [];
+  }
+  async listAnomalyResponseEvents(params) {
+    const qs = new URLSearchParams();
+    if (params?.execution_id) qs.set("execution_id", params.execution_id);
+    if (params?.limit !== void 0) qs.set("limit", String(params.limit));
+    const { body } = await this.get(
+      "/v1/anomaly-response/events",
+      qs
+    );
+    return body.events ?? [];
+  }
+  // ── Budget Exception Workflows ────────────────────────────────────────────
+  async listBudgetExceptions(params) {
+    const qs = new URLSearchParams();
+    if (params?.status) qs.set("status", params.status);
+    if (params?.budget_policy_id)
+      qs.set("budget_policy_id", params.budget_policy_id);
+    if (params?.limit !== void 0) qs.set("limit", String(params.limit));
+    if (params?.offset !== void 0) qs.set("offset", String(params.offset));
+    const { body } = await this.get(
+      "/v1/budget-exceptions",
+      qs
+    );
+    return body.exceptions ?? [];
+  }
+  async getBudgetException(id) {
+    const { body } = await this.get(
+      `/v1/budget-exceptions/${encodeURIComponent(id)}`
+    );
+    return body;
+  }
+  async createBudgetException(req) {
+    const { body } = await this.post(
+      "/v1/budget-exceptions",
+      req
+    );
+    return body;
+  }
+  async approveBudgetException(id, req) {
+    const { body } = await this.post(
+      `/v1/budget-exceptions/${encodeURIComponent(id)}/approve`,
+      req
+    );
+    return body;
+  }
+  async rejectBudgetException(id, review_notes) {
+    const { body } = await this.post(
+      `/v1/budget-exceptions/${encodeURIComponent(id)}/reject`,
+      { review_notes }
+    );
+    return body;
+  }
+  async cancelBudgetException(id) {
+    const { body } = await this.post(
+      `/v1/budget-exceptions/${encodeURIComponent(id)}/cancel`,
+      {}
+    );
+    return body;
+  }
+  // ── Regulatory Escalation Chain ───────────────────────────────────────────
+  async listRegulatoryAuthorityLevels() {
+    const { body } = await this.get(
+      "/v1/regulatory/authority-levels"
+    );
+    return body.levels ?? [];
+  }
+  async createRegulatoryAuthorityLevel(req) {
+    const { body } = await this.post(
+      "/v1/regulatory/authority-levels",
+      req
+    );
+    return body;
+  }
+  async listRegulatoryEscalations(params) {
+    const qs = new URLSearchParams();
+    if (params?.status) qs.set("status", params.status);
+    if (params?.subject_type) qs.set("subject_type", params.subject_type);
+    if (params?.subject_id) qs.set("subject_id", params.subject_id);
+    const { body } = await this.get(
+      "/v1/regulatory/escalations",
+      qs
+    );
+    return body.escalations ?? [];
+  }
+  async createRegulatoryEscalation(req) {
+    const { body } = await this.post(
+      "/v1/regulatory/escalations",
+      req
+    );
+    return body;
+  }
+  async acknowledgeRegulatoryEscalation(id) {
+    const { body } = await this.post(
+      `/v1/regulatory/escalations/${encodeURIComponent(id)}/acknowledge`,
+      {}
+    );
+    return body;
+  }
+  async resolveRegulatoryEscalation(id, resolution, resolution_details) {
+    const { body } = await this.post(
+      `/v1/regulatory/escalations/${encodeURIComponent(id)}/resolve`,
+      { resolution, resolution_details }
+    );
+    return body;
+  }
+  async overrideRegulatoryEscalation(id, reason) {
+    const { body } = await this.post(
+      `/v1/regulatory/escalations/${encodeURIComponent(id)}/override`,
+      { reason }
+    );
+    return body;
+  }
+  // ── Incentive Signal Feedback Loop ────────────────────────────────────────
+  async listSignalActions(signal_id) {
+    const { body } = await this.get(
+      `/v1/governance/signals/${encodeURIComponent(signal_id)}/actions`
+    );
+    return body.actions ?? [];
+  }
+  async recordSignalAction(signal_id, req) {
+    const { body } = await this.post(
+      `/v1/governance/signals/${encodeURIComponent(signal_id)}/actions`,
+      req
+    );
+    return body;
+  }
+  async recordSignalOutcome(signal_id, action_id, req) {
+    const { body } = await this.post(
+      `/v1/governance/signals/${encodeURIComponent(signal_id)}/actions/${encodeURIComponent(action_id)}/outcome`,
+      req
+    );
+    return body;
+  }
+  async getSignalActionSummary() {
+    const { body } = await this.get(
+      "/v1/governance/signals/actions/summary"
+    );
+    return body;
+  }
+  // ── Cross-Org Impersonation ───────────────────────────────────────────────
+  async listImpersonationGrants() {
+    const { body } = await this.get(
+      "/v1/cross-org/impersonation/grants"
+    );
+    return body.grants ?? [];
+  }
+  async createImpersonationGrant(req) {
+    const { body } = await this.post(
+      "/v1/cross-org/impersonation/grants",
+      req
+    );
+    return body;
+  }
+  async revokeImpersonationGrant(id) {
+    await this.post(
+      `/v1/cross-org/impersonation/grants/${encodeURIComponent(id)}/revoke`,
+      {}
+    );
+  }
+  async issueImpersonationToken(grant_id, requested_duration_seconds) {
+    const { body } = await this.post(
+      `/v1/cross-org/impersonation/grants/${encodeURIComponent(grant_id)}/token`,
+      { requested_duration_seconds }
+    );
+    return body;
+  }
+  async validateImpersonationToken(token) {
+    const { body } = await this.post(
+      "/v1/cross-org/impersonation/validate",
+      { token }
+    );
+    return body;
+  }
+  // ── Constrained governance agents (read surface) ──────────────────────────
+  //
+  // Three GETs onto the v1-governance-agents edge function. Doctrine:
+  // findings produced by these endpoints are advisory signal, never
+  // authority. There is no `runGovernanceAgent` method on this client —
+  // invocation belongs in CI (atlasent-action `governance-agents` mode),
+  // not in application code.
+  /**
+   * List the advisory governance-agent registry for the calling org.
+   *
+   * Calls `GET /v1/governance/agents`. The registry is reference data
+   * seeded at runtime-DB migration time; every row has
+   * `authority_class = "advisory"` and `can_authorize = false` —
+   * structural invariants enforced by the schema, not policy.
+   */
+  async listGovernanceAgents() {
+    const { body } = await this.get(
+      "/v1/governance/agents"
+    );
+    return [...body.agents ?? []];
+  }
+  /**
+   * List advisory findings emitted against one governed change.
+   *
+   * Calls `GET /v1/governance/findings?change_id=…[&agent_slug=…]`.
+   * Returns the typed-finding rows in `created_at DESC` order, including
+   * `routed_gate_id` when the finding→gate trigger linked them. Findings
+   * with `can_authorize === false` (always) are advisory; rendering them
+   * never satisfies a gate.
+   */
+  async listGovernanceFindings(query) {
+    if (!query?.change_id) {
+      throw new AtlaSentError("change_id is required", { code: "bad_request" });
+    }
+    const params = new URLSearchParams({ change_id: query.change_id });
+    if (query.agent_slug) params.set("agent_slug", query.agent_slug);
+    const { body } = await this.get(
+      "/v1/governance/findings",
+      params
+    );
+    return [...body.findings ?? []];
+  }
+  /**
+   * List agent run records against one governed change.
+   *
+   * Calls `GET /v1/governance/evaluations?change_id=…[&agent_slug=…]`.
+   * Returns every persisted evaluation, including `failed` / `timeout`
+   * runs and `completed` runs with zero findings — the latter is the
+   * positive signal "the agent ran and found nothing", which the UI
+   * surfaces as `clear`.
+   */
+  async listGovernanceEvaluations(query) {
+    if (!query?.change_id) {
+      throw new AtlaSentError("change_id is required", { code: "bad_request" });
+    }
+    const params = new URLSearchParams({ change_id: query.change_id });
+    if (query.agent_slug) params.set("agent_slug", query.agent_slug);
+    const { body } = await this.get(
+      "/v1/governance/evaluations",
+      params
+    );
+    return [...body.evaluations ?? []];
+  }
 };
 function parseRateLimitHeaders(headers) {
   const rawLimit = headers.get("x-ratelimit-limit");
@@ -446,6 +2142,9 @@ function buildAuditEventsQuery(query) {
   }
   return params;
 }
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
 function parseRetryAfter(raw) {
   if (!raw) return void 0;
   const seconds = Number(raw);
@@ -457,13 +2156,133 @@ function parseRetryAfter(raw) {
   }
   return void 0;
 }
+async function* parseSseStream(body, requestId, timeoutMs, onEventId) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let buf = "";
+  async function readChunk() {
+    if (timeoutMs <= 0) {
+      return reader.read();
+    }
+    return new Promise((resolve2, reject) => {
+      const timer = setTimeout(() => {
+        reject(new StreamTimeoutError(timeoutMs));
+      }, timeoutMs);
+      reader.read().then(
+        (result) => {
+          clearTimeout(timer);
+          resolve2(result);
+        },
+        (err) => {
+          clearTimeout(timer);
+          reject(err);
+        }
+      );
+    });
+  }
+  try {
+    for (; ; ) {
+      let done;
+      let value;
+      try {
+        const result = await readChunk();
+        done = result.done;
+        value = result.value;
+      } catch (err) {
+        if (err instanceof StreamTimeoutError) throw err;
+        throw new AtlaSentError(
+          `AtlaSent stream read failed: ${err instanceof Error ? err.message : String(err)}`,
+          { code: "network", requestId, cause: err }
+        );
+      }
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      let boundary;
+      while ((boundary = buf.indexOf("\n\n")) !== -1) {
+        const block = buf.slice(0, boundary);
+        buf = buf.slice(boundary + 2);
+        let eventType = "message";
+        let data = "";
+        let eventId;
+        for (const line of block.split("\n")) {
+          if (line.startsWith("event: ")) eventType = line.slice(7).trim();
+          else if (line.startsWith("data: ")) data = line.slice(6);
+          else if (line.startsWith("id: ")) eventId = line.slice(4).trim();
+          else if (line.startsWith("id:")) eventId = line.slice(3).trim();
+        }
+        if (eventId !== void 0) onEventId(eventId);
+        if (!data) continue;
+        if (eventType === "done") return;
+        let parsed;
+        try {
+          parsed = JSON.parse(data);
+        } catch (err) {
+          throw new StreamParseError(data, err);
+        }
+        if (eventType === "error") {
+          const e = parsed;
+          throw new AtlaSentError(
+            e.message ?? "Stream error from AtlaSent API",
+            {
+              code: e.code ?? "server_error",
+              requestId: e.request_id ?? requestId
+            }
+          );
+        }
+        if (eventType === "decision") {
+          const d = parsed;
+          if (typeof d.permitted !== "boolean" || typeof d.decision_id !== "string") {
+            throw new AtlaSentError(
+              "Malformed decision event from AtlaSent API",
+              {
+                code: "bad_response",
+                requestId
+              }
+            );
+          }
+          const streamDecision = d.permitted ? "allow" : "deny";
+          const isFinal = d.is_final ?? false;
+          yield {
+            type: "decision",
+            decision: streamDecision,
+            decision_canonical: streamDecision,
+            permitId: d.decision_id,
+            reason: d.reason ?? "",
+            auditHash: d.audit_hash ?? "",
+            timestamp: d.timestamp ?? "",
+            isFinal
+          };
+          if (isFinal || d.done === true) return;
+        } else if (eventType === "progress") {
+          const p = parsed;
+          yield {
+            type: "progress",
+            stage: String(p["stage"] ?? ""),
+            ...p
+          };
+          if (p.done === true) return;
+        } else {
+          if (parsed !== null && typeof parsed === "object" && parsed.done === true) {
+            return;
+          }
+        }
+      }
+    }
+    if (buf.trim().length > 0) {
+      throw new StreamParseError(buf);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
 
 // src/protect.ts
 var sharedClient = null;
 var overrides = {};
 function getClient() {
   if (sharedClient) return sharedClient;
-  const apiKey = overrides.apiKey ?? process.env.ATLASENT_API_KEY;
+  const envApiKey = typeof process !== "undefined" && process.env ? process.env.ATLASENT_API_KEY : void 0;
+  const apiKey = overrides.apiKey ?? envApiKey;
   if (!apiKey) {
     throw new AtlaSentError(
       "AtlaSent is not configured. Set ATLASENT_API_KEY in the environment, or call atlasent.configure({ apiKey }).",
@@ -472,20 +2291,62 @@ function getClient() {
   }
   const options = { apiKey };
   if (overrides.baseUrl !== void 0) options.baseUrl = overrides.baseUrl;
-  if (overrides.timeoutMs !== void 0) options.timeoutMs = overrides.timeoutMs;
+  if (overrides.timeoutMs !== void 0)
+    options.timeoutMs = overrides.timeoutMs;
   if (overrides.fetch !== void 0) options.fetch = overrides.fetch;
+  if (overrides.retryPolicy !== void 0)
+    options.retryPolicy = overrides.retryPolicy;
   sharedClient = new AtlaSentClient(options);
   return sharedClient;
 }
+var ACTION_TYPE_RE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/;
 function wireDecisionToDenied(serverDecision) {
   const lower = serverDecision.toLowerCase();
   if (lower === "hold" || lower === "escalate") return lower;
   return "deny";
 }
+function sortKeysDeep(val) {
+  if (Array.isArray(val)) return val.map(sortKeysDeep);
+  if (val !== null && typeof val === "object") {
+    return Object.keys(val).sort().reduce((acc, k) => {
+      acc[k] = sortKeysDeep(val[k]);
+      return acc;
+    }, {});
+  }
+  return val;
+}
+async function computeExecutionHash(payload) {
+  const sorted = sortKeysDeep(payload);
+  const canonical = JSON.stringify(sorted);
+  if (typeof globalThis !== "undefined" && globalThis.crypto?.subtle?.digest) {
+    const bytes = new TextEncoder().encode(canonical);
+    const buf = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  }
+  try {
+    const { createHash } = await import(
+      /* @vite-ignore */
+      /* webpackIgnore: true */
+      "crypto"
+    );
+    return createHash("sha256").update(canonical, "utf8").digest("hex");
+  } catch {
+    console.warn(
+      "[atlasent] Could not compute execution_hash: neither crypto.subtle nor node:crypto is available in this runtime."
+    );
+    return "";
+  }
+}
 async function protect(request) {
+  if (!ACTION_TYPE_RE.test(request.action)) {
+    throw new AtlaSentError(
+      `action must be in dot-notation format (e.g. "production.deploy"). Got: ${JSON.stringify(request.action)}`,
+      { code: "bad_request" }
+    );
+  }
   const client = getClient();
   const evaluation = await client.evaluate(request);
-  if (evaluation.decision !== "ALLOW") {
+  if (evaluation.decision !== "allow") {
     throw new AtlaSentDeniedError({
       decision: wireDecisionToDenied(evaluation.decision),
       evaluationId: evaluation.permitId,
@@ -493,19 +2354,36 @@ async function protect(request) {
       auditHash: evaluation.auditHash
     });
   }
+  const environment = request.context?.environment;
+  if (!environment) {
+    throw new AtlaSentError(
+      'context.environment is required. Pass the environment where this action executes (e.g. "production", "staging").',
+      { code: "bad_request" }
+    );
+  }
+  const evaluatePayload = {
+    action_type: request.action,
+    actor_id: request.agent,
+    context: request.context ?? {}
+  };
+  const execution_hash = await computeExecutionHash(evaluatePayload);
   const verifyRequest = {
     permitId: evaluation.permitId,
     agent: request.agent,
-    action: request.action
+    action: request.action,
+    environment,
+    ...execution_hash ? { execution_hash } : {}
   };
   if (request.context !== void 0) verifyRequest.context = request.context;
   const verification = await client.verifyPermit(verifyRequest);
   if (!verification.verified) {
+    const outcome = normalizePermitOutcome(verification.outcome);
     throw new AtlaSentDeniedError({
       decision: "deny",
       evaluationId: evaluation.permitId,
       reason: `Permit failed verification (${verification.outcome})`,
-      auditHash: evaluation.auditHash
+      auditHash: evaluation.auditHash,
+      ...outcome !== void 0 && { outcome }
     });
   }
   return {
@@ -513,7 +2391,8 @@ async function protect(request) {
     permitHash: verification.permitHash,
     auditHash: evaluation.auditHash,
     reason: evaluation.reason,
-    timestamp: verification.timestamp
+    timestamp: verification.timestamp,
+    permitExpiresAt: verification.expiresAt ?? null
   };
 }