@atlasent/sdk 2.5.0 → 2.10.0

package/README.md

@@ -42,6 +42,41 @@ client.deployGate({ agent?, action?, context? })
 
 `verifyPermit()` confirms a previously-issued permit server-side. Signed/offline permit artifacts never imply deployment authorization by themselves.
 
+## Decision replay
+
+Re-evaluate a recorded decision against its originally-pinned policy bundle and engine version. **Side-effect-free**: no audit row is written, no permit is minted (ADR-016 `mode: "replay"` sentinel). Useful for compliance review, regression-testing bundle changes, and post-incident investigation.
+
+Two surfaces exist; pick the one that matches your call site:
+
+```ts
+// SDK-canonical (preferred for new code) — wire DECISION_CHANGED is normalized
+// to POLICY_DRIFT; 409 replay_not_eligible returns ENGINE_DRIFT or BUNDLE_MISSING
+// instead of throwing. You can always `switch` on the variance kind.
+const r = await client.replay({ evaluationId: "dec_abc123" });
+switch (r.varianceKind) {
+  case "NONE":             /* replay agrees */                          break;
+  case "POLICY_DRIFT":     /* same envelope/bundle, different decision */ break;
+  case "ENVELOPE_DRIFT":   /* recorded envelope no longer hashes */     break;
+  case "ENGINE_DRIFT":     /* original engine retired beyond archival */ break;
+  case "BUNDLE_MISSING":   /* original eval had no bundle pinned */     break;
+  case "CHAIN_TAMPER":     /* audit-chain v5 detector tripped */        break;
+}
+```
+
+```ts
+// Raw-wire surface — variance values pass through verbatim
+// (NONE / DECISION_CHANGED / ENVELOPE_DRIFT); 409 throws AtlaSentError
+const result = await client.replayDecision("dec_abc123");
+if (result.variance === "DECISION_CHANGED") {
+  console.warn(
+    `Decision ${result.decision_id} drifted: ` +
+    `${result.original_decision} → ${result.replay_decision}`,
+  );
+}
+```
+
+`/v1/decisions/:id/replay` is alpha per `atlasent-api/docs/STABLE_V2_PROMOTION.md` — wire shapes can shift without a deprecation cycle until it graduates to stable v1.
+
 ## CI deploy-gate pattern
 
 ```ts

package/dist/hono.cjs

@@ -173,9 +173,8 @@ function normalizeEvaluateRequest(input) {
       action_type: legacy.action,
       actor_id: legacy.agent
     };
-    if (legacy.context !== void 0) {
-      normalized.context = legacy.context;
-    }
+    if (legacy.context !== void 0) normalized.context = legacy.context;
+    if (legacy.explain !== void 0) normalized.explain = legacy.explain;
     return normalized;
   }
   return input;
@@ -347,6 +346,7 @@ var AtlaSentClient = class {
       actor_id: normalized.actor_id,
       context: normalized.context ?? {}
     };
+    if (normalized.explain !== void 0) body.explain = normalized.explain;
     const { body: wire, rateLimit } = await this.post(
       "/v1-evaluate",
       body
@@ -383,9 +383,211 @@ var AtlaSentClient = class {
       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.
    *
@@ -452,7 +654,17 @@ var AtlaSentClient = class {
       reason,
       auditHash: wire.audit_hash ?? "",
       timestamp: wire.timestamp ?? "",
-      rateLimit
+      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") {
@@ -501,6 +713,7 @@ var AtlaSentClient = class {
       outcome: wire.outcome ?? "",
       permitHash: wire.permit_hash ?? "",
       timestamp: wire.timestamp ?? "",
+      expiresAt: wire.expires_at ?? null,
       rateLimit
     };
   }
@@ -822,6 +1035,151 @@ var AtlaSentClient = class {
     }
     return { ...wire, rateLimit };
   }
+  /**
+   * 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`.
    *
@@ -870,6 +1228,8 @@ var AtlaSentClient = class {
         "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) {
@@ -957,7 +1317,9 @@ var AtlaSentClient = class {
       Accept: "application/json",
       Authorization: `Bearer ${this.apiKey}`,
       "User-Agent": this.userAgent,
-      "X-Request-ID": requestId
+      "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 bodyStr = method === "POST" ? JSON.stringify(body) : void 0;
@@ -1573,6 +1935,69 @@ var AtlaSentClient = class {
     );
     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");
@@ -1874,6 +2299,7 @@ function getClient() {
   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;
@@ -1912,6 +2338,12 @@ async function computeExecutionHash(payload) {
   }
 }
 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") {
@@ -1922,12 +2354,13 @@ async function protect(request) {
       auditHash: evaluation.auditHash
     });
   }
-  const environment = request.context?.environment ?? (() => {
-    console.warn(
-      "[atlasent] environment not set on evaluate request \u2014 defaulting to 'production'. Set context.environment explicitly to suppress."
+  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" }
     );
-    return "production";
-  })();
+  }
   const evaluatePayload = {
     action_type: request.action,
     actor_id: request.agent,
@@ -1958,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
   };
 }