@atlasent/sdk 2.5.0 → 2.12.0

package/dist/{protect-DiRVfVLq.d.cts → protect-B6w-WQMB.d.cts}

@@ -45,7 +45,7 @@ declare class StreamParseError extends Error {
     constructor(rawData: string, cause?: unknown);
 }
 /** Discriminator for {@link AtlaSentError.code}. */
-type AtlaSentErrorCode = "invalid_api_key" | "forbidden" | "rate_limited" | "timeout" | "network" | "bad_response" | "bad_request" | "server_error" | "feature_disabled";
+type AtlaSentErrorCode = "invalid_api_key" | "forbidden" | "rate_limited" | "timeout" | "network" | "bad_response" | "bad_request" | "server_error" | "feature_disabled" | "claim_evidence_incomplete";
 /** Initialization options for {@link AtlaSentError}. */
 interface AtlaSentErrorInit {
     status?: number;
@@ -97,7 +97,7 @@ type AtlaSentDecision = "deny" | "hold" | "escalate";
  * `atlasent/docs/REVOCATION_RUNBOOK.md` for the operator-facing
  * matrix this discriminator drives.
  */
-type PermitOutcome = "permit_consumed" | "permit_expired" | "permit_revoked" | "permit_not_found";
+type PermitOutcome = "permit_consumed" | "permit_expired" | "permit_revoked" | "permit_not_found" | "permit_signing_key_revoked";
 /**
  * Map a server-supplied `outcome` string to {@link PermitOutcome}.
  *
@@ -169,6 +169,11 @@ declare class AtlaSentDeniedError extends AtlaSentError {
      * (typo, cross-tenant lookup, or pre-issuance race).
      */
     get isNotFound(): boolean;
+    /**
+     * `true` when the permit's signing key KID appears in the
+     * trust-root revocation list (ADR-005 D3 R2/R3 key rotation).
+     */
+    get isSigningKeyRevoked(): boolean;
 }
 /** Initialization options for {@link AtlaSentEscalateError}. */
 interface AtlaSentEscalateErrorInit {
@@ -237,6 +242,50 @@ declare class PermitRevoked extends AtlaSentError {
     readonly revocationId: string | undefined;
     constructor(permitId: string, revocationId?: string);
 }
+/**
+ * Initialization options for {@link BundleVerificationError}.
+ */
+interface BundleVerificationErrorInit {
+    /**
+     * Machine-readable reason code:
+     *   - `trust_snapshot_expired`: the snapshot's `valid_until` has passed
+     *     and `allowExpiredSnapshot` was not set.
+     *   - `key_revoked`: the bundle's `signing_key_id` appears in
+     *     `revoked_keys` of the active trust snapshot.
+     *   - `key_role_mismatch`: the signing key's `role` is not `"R3_audit"`.
+     */
+    reason: "trust_snapshot_expired" | "key_revoked" | "key_role_mismatch";
+    /** ISO-8601 `valid_until` of the snapshot that caused the failure. */
+    snapshotValidUntil?: string;
+    /** ISO-8601 `issued_at` of the snapshot (its fetch/pin time). */
+    snapshotFetchedAt?: string;
+    /** Whether the snapshot came from the bundled vendor files or a live refresh. */
+    snapshotSource?: "pinned" | "live";
+    /** Which key id was revoked or role-mismatched, when applicable. */
+    kid?: string;
+}
+/**
+ * Thrown by {@link verifyAuditBundle} / {@link verifyBundle} when the
+ * active trust-root snapshot is expired (ADR-005 D3) or the bundle's
+ * signing key is revoked / has the wrong role.
+ *
+ * This error is **always thrown** — it is never returned as a
+ * {@link BundleVerificationResult} because ADR-005 D3 requires that
+ * an expired snapshot or revoked key constitutes a hard enforcement
+ * action, not a soft verification failure.
+ *
+ * To opt out of fail-closed expiry (air-gap / offline use), pass
+ * `allowExpiredSnapshot: true` to `verifyBundle`.
+ */
+declare class BundleVerificationError extends AtlaSentError {
+    name: string;
+    readonly reason: BundleVerificationErrorInit["reason"];
+    readonly snapshotValidUntil: string | undefined;
+    readonly snapshotFetchedAt: string | undefined;
+    readonly snapshotSource: "pinned" | "live" | undefined;
+    readonly kid: string | undefined;
+    constructor(init: BundleVerificationErrorInit);
+}
 
 /**
  * Retry-policy helpers for the AtlaSent TypeScript SDK.
@@ -268,18 +317,18 @@ declare class PermitRevoked extends AtlaSentError {
  * It avoids thundering-herd retries from many SDK instances that hit
  * a 429 in the same window.
  *
- * Default schedule matches the Python SDK:
- *   attempt 0 (1st retry): base 2 000 ms, jittered in [0, 2 000)
- *   attempt 1 (2nd retry): base 4 000 ms, jittered in [0, 4 000)
- *   attempt 2 (3rd retry): base 8 000 ms, jittered in [0, 8 000)
- *   attempt 3 (4th retry): capped at 16 000 ms, jittered in [0, 16 000)
- * Total attempts (including initial): 4
+ * Default schedule:
+ *   attempt 0 (1st retry): base 250 ms, jittered in [0, 250)
+ *   attempt 1 (2nd retry): base 500 ms, jittered in [0, 500)
+ * Total attempts (including initial): 3
  */
 /**
  * Defaults for {@link RetryPolicy}.
  *
- * Matches the Python SDK's backoff schedule:
- *   2 s → 4 s → 8 s → 16 s (4 total attempts, cap at 16 s).
+ * Exponential backoff with full jitter, base 250 ms, capped at 10 s:
+ *   attempt 0 (1st retry): base 250 ms, jittered in [0, 250)
+ *   attempt 1 (2nd retry): base 500 ms, jittered in [0, 500)
+ * Total attempts (including initial): 3
  */
 declare const DEFAULT_RETRY_POLICY: Required<RetryPolicy>;
 /**
@@ -686,6 +735,59 @@ interface DeployGateResponse {
     /** Best-effort audit/evidence metadata available to the SDK. */
     evidence: DeployGateEvidence;
 }
+/**
+ * Frozen BVS snapshot wire shape (BI4).
+ * Carried in {@link EvaluateRequest}.context.bvsSnapshot when
+ * the `behavior_conditioning` flag is enabled for the tenant.
+ * Produced by behavior-insights GET /api/patterns/snapshot/:userId
+ * and attached via `@atlasent/behavior` attachToEvaluate().
+ */
+interface BvsSnapshot {
+    user_id: string;
+    /** Factor model output — keyed by BVS factor slug, value is score 0-1. */
+    factors: Record<string, number>;
+    /** Aggregate confidence score (0-1). Decays on a 60-day half-life. */
+    confidence: number;
+    /** True when the aggregate is fresh-and-thin (too few events to trust). */
+    confidence_low: boolean;
+    /** ISO-8601 timestamp of the compute run that produced this snapshot. */
+    computed_at: string;
+}
+/**
+ * Consent-class projection (BI5) — the privacy-safe aggregate shape that
+ * third-party apps (LedgersMe, hiCoach, echobloom) receive when reading a
+ * user's behavioral summary. Counts and timestamps only; no raw free-text.
+ * Produced by behavior-insights `/api/patterns/summary/:userId` and fetched
+ * via `@atlasent/behavior` getStateSummary(). The SDK enforces
+ * {@link https://github.com/AtlaSent-Systems-Inc/atlasent-sdk | assertNoRawText}
+ * client-side before returning this shape to callers.
+ */
+interface ConsentClassProjection {
+    user_id: string;
+    window_start: string;
+    window_end: string;
+    event_count: number;
+    category_counts: Partial<Record<string, number>>;
+}
+/**
+ * Proof that a specific actor consumed a specific permit for a specific
+ * action_type. Pass an array of these as `completion_proofs` on an evaluate
+ * request to satisfy multi-actor quorum dependencies.
+ *
+ * The runtime verifies each proof via two gates (both must pass):
+ * 1. A `permit_uses` row exists for `permit_id` (permit was consumed).
+ * 2. An `execution_evaluations` row is bound to `actor_id` + `action_type`
+ *    for the same permit (actor/action binding — Codex P1 #1148 FIX #3).
+ * Proofs that fail either gate are silently dropped (fail-closed).
+ */
+interface CompletionProof {
+    /** The action_type (slug) that was completed by the prior actor. */
+    action_type: string;
+    /** The actor who completed the action. */
+    actor_id: string;
+    /** The permit token (or its hash) issued when the action was permitted. */
+    permit_id: string;
+}
 /** Input to {@link AtlaSentClient.evaluate}. */
 interface EvaluateRequest {
     /** Identifier of the calling agent (e.g. "clinical-data-agent"). */
@@ -694,6 +796,63 @@ interface EvaluateRequest {
     action: string;
     /** Arbitrary policy context (user, environment, resource IDs). */
     context?: Record<string, unknown>;
+    /**
+     * When `true`, the server populates `riskEnvelope.factors` with a
+     * per-factor breakdown of the weighted risk score. Omit (or `false`)
+     * to keep response payloads small.
+     */
+    explain?: boolean;
+    /** Deployment environment where the action executes (e.g. `"production"`). */
+    environment?: string;
+    /** Structured resource descriptor. Prefer over embedding resource info in `context`. */
+    resource?: {
+        type: string;
+        id?: string;
+        attributes?: Record<string, unknown>;
+    };
+    /** Snapshot of the resource state before the proposed action. Enables state-transition-aware policy evaluation. */
+    current_state?: {
+        description: string;
+        attributes?: Record<string, unknown>;
+    };
+    /** Desired resource state after the action executes. */
+    proposed_state?: {
+        description: string;
+        attributes?: Record<string, unknown>;
+    };
+    /** Execution surface binding — identifies the CI/CD adapter, DB driver, or enforcement point. */
+    execution_binding?: {
+        kind: string;
+        adapter_version?: string;
+        resource_id?: string;
+        enforcement_point?: string;
+    };
+    /** The desired end-state the actor wants the resource to reach. Enables trajectory-aware authorization. */
+    desired_state?: {
+        description: string;
+        attributes?: Record<string, unknown>;
+        fingerprint?: string;
+    };
+    /** Actor-proposed execution path from current_state to desired_state. The engine returns an authorized_trajectory that may differ. */
+    proposed_trajectory?: {
+        steps: Array<{
+            step: string;
+            description?: string;
+            required: boolean;
+            time_limit_seconds?: number;
+            authorized_by?: string;
+            constraints?: Record<string, unknown>;
+        }>;
+        description?: string;
+    };
+    /**
+     * Multi-actor quorum completion proofs. Supply one entry per prior actor
+     * whose completed action this evaluation depends on. The runtime verifies
+     * each proof (consumed-permit gate + actor/action binding gate) and counts
+     * only valid proofs toward quorum. Absent or empty → no quorum proofs
+     * submitted (no behavioral change for non-quorum dependencies).
+     */
+    completion_proofs?: CompletionProof[];
 }
 /**
  * Slim permit object embedded in {@link EvaluateResponse} when the decision
@@ -793,6 +952,97 @@ interface EvaluateResponse {
      * `X-RateLimit-*` headers. `null` when the server didn't emit them.
      */
     rateLimit: RateLimitState | null;
+    /**
+     * Risk envelope summary from the policy engine. Present on all responses
+     * from engine version wire-v1@1.0.0+. Provides the weighted risk score,
+     * the pre/post-promotion decisions, and (when evaluate was called with
+     * `explain: true`) a per-factor breakdown.
+     *
+     * The envelope can only raise severity — it structurally cannot soften
+     * a deny to allow. When `promoted` is true the live `decision` was
+     * upgraded from `engineDecision` to `envelopeDecision`.
+     */
+    riskEnvelope?: EvaluateRiskEnvelope;
+    /**
+     * Resolved risk class from the evaluation engine.
+     * One of `"critical"`, `"high"`, `"medium"`, `"low"`.
+     * Present when the risk envelope assigns a class.
+     */
+    riskClass?: string;
+    /**
+     * WHY this permit was issued — the authority kind and a reference to the
+     * authorizing entity. Present on `allow` decisions when the control plane
+     * attaches explicit authority provenance.
+     */
+    authorityBasis?: {
+        kind: "policy" | "approval" | "emergency" | "maintenance_window" | "delegation" | "quorum";
+        reference?: string;
+        grantedBy?: string;
+        rationale?: string;
+        expiresAt?: string;
+    };
+    /**
+     * ID of the HITL escalation auto-created by the control plane.
+     * Present iff `decision === "hold"`. Poll `GET /v1/escalations/{id}`
+     * for resolution status.
+     */
+    escalationId?: string;
+    /**
+     * Authorized execution trajectory returned when the engine approved a
+     * `proposed_trajectory`. Present only on `allow` decisions.
+     * May differ from what was proposed — the engine may add checkpoints,
+     * restrict steps, or tighten time limits. Follow this trajectory exactly;
+     * call `POST /v1/trajectory-verify` at each step to confirm on_trajectory.
+     */
+    authorized_trajectory?: {
+        trajectory_id: string;
+        steps: Array<{
+            step: string;
+            description?: string;
+            required: boolean;
+            time_limit_seconds?: number;
+            authorized_by?: string;
+            constraints?: Record<string, unknown>;
+            expected_intermediate_state?: {
+                description: string;
+                attributes?: Record<string, unknown>;
+                fingerprint?: string;
+            };
+        }>;
+        description?: string;
+        forbidden_states?: Array<{
+            description: string;
+            attributes?: Record<string, unknown>;
+            fingerprint?: string;
+        }>;
+        expires_at: string;
+    };
+}
+/** Per-factor contribution in a {@link EvaluateRiskEnvelope}. */
+interface EvaluateRiskEnvelopeFactor {
+    /** Factor identifier, e.g. `"ACTION_SENSITIVITY"`. */
+    factor: string;
+    /** Factor score in [0, 1]. Higher = more risk. */
+    value: number;
+    /** Configured weight for this factor. */
+    weight: number;
+    /** Human-readable explanation for the score. */
+    reason: string;
+}
+/** Risk envelope summary returned in a top-level {@link EvaluateResponse}. */
+interface EvaluateRiskEnvelope {
+    /** Weighted risk score in [0, 1]. Score ≥ 0.70 triggers a hold. */
+    weightedScore: number;
+    /** Policy engine decision before envelope promotion. */
+    engineDecision: Decision;
+    /** Decision resolved by the risk envelope. */
+    envelopeDecision: Decision;
+    /** `true` when the envelope raised the decision's severity (most-restrictive-wins). */
+    promoted: boolean;
+    /** Deny codes that unconditionally block regardless of score. */
+    hardBlocks: string[];
+    /** Per-factor breakdown. Present only when `explain: true` was passed. */
+    factors?: EvaluateRiskEnvelopeFactor[];
 }
 /** Input to {@link AtlaSentClient.verifyPermit}. */
 interface VerifyPermitRequest {
@@ -838,6 +1088,11 @@ interface VerifyPermitResponse {
     permitHash: string;
     /** ISO 8601 timestamp of the verification. */
     timestamp: string;
+    /**
+     * ISO-8601 expiration timestamp of the permit. `null` on pre-rollout
+     * server versions that do not yet surface this field.
+     */
+    expiresAt: string | null;
     /**
      * Per-key rate-limit state for this request's response, parsed from
      * `X-RateLimit-*` headers. `null` when the server didn't emit them.
@@ -849,18 +1104,13 @@ interface VerifyPermitResponse {
  * key the client was constructed with. Returned by `GET /v1/api-key-self`.
  *
  * Never includes the raw key or its hash — introspection is intentionally
- * read-only and safe to surface in operator dashboards. Useful for:
- *   - "which key am I?" debugging
- *   - IP_NOT_ALLOWED failures — `clientIp` is the IP the server observed
- *   - proactive expiry warnings — `expiresAt` is the server-stored expiry
- *     (`null` means the key does not auto-expire)
- *   - verifying scopes before attempting a scope-gated action
+ * read-only and safe to surface in operator dashboards.
  */
 interface ApiKeySelfResponse {
     /** Server-side UUID of the api_keys row for this key. */
     keyId: string;
     /** Organization the key belongs to. */
-    organizationId: string;
+    orgId: string;
     /** "live" or "test" (or any future environment label the server introduces). */
     environment: string;
     /** Granted scopes — e.g. ["evaluate", "audit.read"]. */
@@ -885,24 +1135,16 @@ interface ApiKeySelfResponse {
 /**
  * Result of {@link AtlaSentClient.listAuditEvents}. Extends the raw
  * wire page with a camelCase `rateLimit` alongside the snake_case
- * wire fields — the wire shape (`events`, `total`, `next_cursor`) is
- * untouched so callers that pass it to the offline verifier get
- * byte-identical behaviour.
+ * wire fields.
  */
 interface AuditEventsResult extends AuditEventsPage {
-    /**
-     * Per-key rate-limit state for this request's response, parsed from
-     * `X-RateLimit-*` headers. `null` when the server didn't emit them.
-     */
     rateLimit: RateLimitState | null;
 }
 /**
- * Filter accepted by {@link AtlaSentClient.createAuditExport}. Fields
- * are snake_case to match the server's `POST /v1-audit/exports`
- * request body; an empty object requests a full-org bundle.
+ * Filter accepted by {@link AtlaSentClient.createAuditExport}.
  */
 interface AuditExportRequest {
-    /** Comma-joined list of event types to include (e.g. `"evaluate.allow,policy.updated"`). */
+    /** Comma-joined list of event types to include. */
     types?: string;
     /** Filter to a single actor. */
     actor_id?: string;
@@ -912,18 +1154,9 @@ interface AuditExportRequest {
     to?: string;
 }
 /**
- * Result of {@link AtlaSentClient.createAuditExport}. Extends the
- * signed bundle shape with a camelCase `rateLimit`. The signed
- * envelope fields (`export_id`, `org_id`, `chain_head_hash`,
- * `event_count`, `signed_at`, `events`, `signature`) are preserved
- * byte-for-byte so the object can be handed straight to
- * `verifyAuditBundle(bundle, keys)`.
+ * Result of {@link AtlaSentClient.createAuditExport}.
  */
 interface AuditExportResult extends AuditExport {
-    /**
-     * Per-key rate-limit state for this request's response, parsed from
-     * `X-RateLimit-*` headers. `null` when the server didn't emit them.
-     */
     rateLimit: RateLimitState | null;
 }
 /** Constructor options for {@link AtlaSentClient}. */
@@ -948,16 +1181,24 @@ interface AtlaSentClientOptions {
      * Pass `{ maxAttempts: 1 }` to disable retries entirely.
      */
     retryPolicy?: RetryPolicy;
+    /**
+     * Base URL for the trust-root host (default: https://keys.atlasent.io/.well-known).
+     * Override for air-gapped / enterprise mirror deployments.
+     * Per ADR-005 D2.
+     */
+    trustRootUrl?: string;
+    /**
+     * Trust-root snapshot refresh interval in milliseconds.
+     * Default: 4 hours.  Floor: 5 minutes (ADR-005 D2).
+     * Set to 0 to inherit the default.
+     */
+    trustSnapshotRefreshMs?: number;
 }
 /** Permit lifecycle status. */
 type PermitStatus = "issued" | "verified" | "consumed" | "expired" | "revoked";
 /**
  * Wire shape of a Permit row, returned by {@link AtlaSentClient.getPermit}
- * and {@link AtlaSentClient.listPermits}. Mirrors the openapi `Permit`
- * schema.
- *
- * Revocation fields (`revoked_at`, `revoked_by`, `revoke_reason`) are
- * populated only when `status === 'revoked'`; null otherwise.
+ * and {@link AtlaSentClient.listPermits}.
  */
 interface PermitRecord {
     id: string;
@@ -976,27 +1217,23 @@ interface PermitRecord {
     signature?: string;
     payload_hash?: string | null;
     decision_id?: string | null;
+    /** SHA-256 hex of the CDO that produced this permit. P1 provisional. */
+    cdo_hash?: string | null;
 }
 /** Optional filters for {@link AtlaSentClient.listPermits}. */
 interface ListPermitsRequest {
     status?: PermitStatus;
     actorId?: string;
     actionType?: string;
-    /** ISO-8601 lower bound on `created_at`. */
     from?: string;
-    /** ISO-8601 upper bound on `created_at`. */
     to?: string;
-    /** Page size. Server max is 500; default 50. */
     limit?: number;
-    /** Pass `nextCursor` from a prior response to page forward. */
     cursor?: string;
 }
 /** Response from {@link AtlaSentClient.listPermits}. */
 interface ListPermitsResponse {
     permits: PermitRecord[];
-    /** Total matching rows ignoring `limit`/`cursor`. */
     total: number;
-    /** Pass on next call as `cursor`. Absent when no more rows. */
     nextCursor?: string;
     rateLimit: RateLimitState | null;
 }
@@ -1007,41 +1244,19 @@ interface GetPermitResponse {
 }
 /**
  * Response from {@link AtlaSentClient.checkPermitValid}.
- *
- * Lightweight validity snapshot returned by
- * `GET /v1/permits/{permitId}/valid`. Designed for guard heartbeat
- * polling — returns only the fields needed to determine whether to
- * abort a running permit mid-execution (via {@link PermitRevoked}).
  */
 interface PermitValidResponse {
-    /** True iff the permit is currently valid (active). */
     valid: boolean;
-    /**
-     * Current lifecycle status of the permit.
-     * - `"active"` — permit is valid and in-flight.
-     * - `"expired"` — TTL elapsed before revocation or consumption.
-     * - `"revoked"` — administratively revoked (see `revocation_id`).
-     * - `"consumed"` — single-use permit already consumed.
-     */
     status: "active" | "expired" | "revoked" | "consumed";
-    /** ISO-8601 timestamp when the permit was revoked. Populated only when `status === "revoked"`. */
     revoked_at?: string;
-    /** Opaque identifier of the revocation record. Populated only when `status === "revoked"`. */
     revocation_id?: string;
 }
 /** Input for {@link AtlaSentClient.revokePermitById}. */
 interface RevokePermitByIdInput {
-    /** Operator-supplied free-text reason. Recorded on the permit row,
-     *  written to the audit trail, and surfaced (truncated) on later
-     *  verify responses. Optional but strongly encouraged. */
     reason?: string;
 }
 /**
  * Response from {@link AtlaSentClient.revokePermitById}.
- *
- * Returns the updated {@link PermitRecord} with `status === 'revoked'`
- * and the populated `revoked_at` / `revoked_by` / `revoke_reason`
- * fields.
  */
 interface RevokePermitByIdResponse {
     permit: PermitRecord;
@@ -1049,23 +1264,12 @@ interface RevokePermitByIdResponse {
 }
 /**
  * Response from {@link AtlaSentClient.verifyPermitById}.
- *
- * Returns the canonical verification envelope (`valid`,
- * `verification_type`, `reason`, `verified_at`, `evidence`) plus the
- * legacy {@link PermitRecord} fields preserved at the top level for
- * backward compatibility. The envelope shape matches the unified
- * verify response in atlasent-api PR #352.
  */
 interface VerifyPermitByIdResponse {
-    /** `true` iff the permit verified — i.e. unconsumed, unexpired, and signature OK. */
     valid: boolean;
-    /** Always `'permit'` on this surface. */
     verification_type: "permit";
-    /** Operator-readable explanation when `valid` is `false`; `null` on success. */
     reason: string | null;
-    /** Server clock at the moment verification ran. */
     verified_at: string;
-    /** Type-specific evidence — same fields as the openapi PermitVerifyEvidence schema. */
     evidence: {
         permit_id: string;
         status: PermitStatus;
@@ -1075,196 +1279,608 @@ interface VerifyPermitByIdResponse {
         payload_hash?: string | null;
         decision_id?: string | null;
     };
-    /** Legacy: full permit row preserved at the top level. */
     permit: PermitRecord;
     rateLimit: RateLimitState | null;
 }
 /** Input for {@link AtlaSentClient.revokePermit}. */
 interface RevokePermitRequest {
-    /** The permit ID returned by a prior evaluate() call. */
     permitId: string;
-    /** Optional human-readable reason stored in the audit log. */
     reason?: string;
 }
 /**
  * Result of {@link AtlaSentClient.revokePermit}.
  *
  * @deprecated Use {@link RevokePermitByIdResponse} via
- * {@link AtlaSentClient.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.
+ * {@link AtlaSentClient.revokePermitById}.
  * Will be removed in `@atlasent/sdk@3`.
  */
 interface RevokePermitResponse {
-    /** `true` when the permit was found and successfully revoked. */
     revoked: boolean;
-    /** Echo of the revoked permit's ID. */
     permitId: string;
-    /** ISO-8601 timestamp of when the revocation was recorded. `undefined` when not returned by the server. */
     revokedAt?: string | undefined;
-    /** Audit hash for the revocation event. `undefined` when not returned by the server. */
     auditHash?: string | undefined;
-    /** Per-key rate-limit state. `null` when the server didn't emit headers. */
     rateLimit: RateLimitState | null;
 }
-/**
- * One stage of a single policy's constraint evaluation.
- *
- * Mirrors `ConstraintTraceStage` in
- * `atlasent-api/packages/types/src/index.ts`. Emitted by the rule
- * engine when the request URL carries `?include=constraint_trace`.
- *
- * Forward-compat: extra engine-side keys are tolerated; readers
- * should not assume this is a closed shape.
- */
 interface ConstraintTraceStage {
-    /** Engine stage name (e.g. `"role_check"`, `"context"`). */
     readonly stage: string;
-    /** Optional rule identifier; absent for wrapper stages. */
     readonly rule?: string;
-    /** True iff this stage's predicate fired. */
     readonly matched: boolean;
-    /** Optional human-readable note from the engine. */
     readonly detail?: string;
-    /** Zero-based position within the policy's `stages` array. */
     readonly order: number;
-    /** Forward-compat: tolerate unknown engine-side keys without crashing. */
     readonly [key: string]: unknown;
 }
-/**
- * Per-policy block of a constraint trace.
- *
- * Mirrors `ConstraintTracePolicy` in
- * `atlasent-api/packages/types/src/index.ts`. The handler iterates
- * active policies in order until first non-allow; the policy that
- * produced the outer decision has `decision !== "allow"`.
- */
 interface ConstraintTracePolicy {
-    /** Stable identifier of the evaluated policy. */
     readonly policy_id: string;
-    /** Policy-level decision (`"allow"|"deny"|"hold"|"escalate"`). */
     readonly decision: string;
-    /** Engine-side fingerprint of the bundle row. */
     readonly fingerprint: string;
-    /**
-     * Optional engine-computed risk score from a `risk` rule clause.
-     * Distinct from the heuristic risk score on the outer envelope.
-     */
     readonly risk_score?: number;
-    /** Ordered stages produced while evaluating this policy. */
     readonly stages: ReadonlyArray<ConstraintTraceStage>;
-    /** Forward-compat: tolerate unknown engine-side keys. */
     readonly [key: string]: unknown;
 }
-/**
- * Top-level constraint trace returned by
- * `/v1-evaluate?include=constraint_trace`.
- *
- * Mirrors `ConstraintTraceResponse` in
- * `atlasent-api/packages/types/src/index.ts`. Present iff the
- * caller requested the trace; the SDK's preflight helper always
- * requests it.
- */
 interface ConstraintTrace {
-    /** Per-policy blocks in evaluation order. */
     readonly rules_evaluated: ReadonlyArray<ConstraintTracePolicy>;
-    /**
-     * Policy id whose evaluation produced the outer decision. Equals
-     * the outer `matched_policy_id` on non-allow paths; `undefined` on
-     * a clean allow (all policies passed).
-     */
     readonly matching_policy_id?: string;
-    /** Forward-compat: tolerate unknown engine-side keys. */
     readonly [key: string]: unknown;
 }
-/**
- * Result of {@link AtlaSentClient.evaluatePreflight}.
- *
- * Wraps the regular {@link EvaluateResponse} plus the
- * {@link ConstraintTrace} returned when the request URL carries
- * `?include=constraint_trace`. The whole point of preflight is to
- * surface which stages / policies WOULD fire BEFORE pushing the
- * request onto an approval queue, so workflows can reject trivially
- * defective requests at submission time and only forward viable
- * requests to a human reviewer.
- *
- * `constraintTrace` is `null` on responses from older atlasent-api
- * deployments that do not echo the trace — forward-compatible
- * degradation.
- */
 interface EvaluatePreflightResponse {
-    /** The regular evaluate response (decision, permitId, ...). */
     readonly evaluation: EvaluateResponse;
-    /**
-     * The constraint trace, or `null` when the server omitted it
-     * (older atlasent-api version).
-     */
     readonly constraintTrace: ConstraintTrace | null;
 }
-/**
- * Options for {@link AtlaSentClient.protectStream}.
- *
- * All fields are optional; defaults are used when omitted.
- */
 interface StreamOptions {
-    /**
-     * Optional abort signal to cancel the stream from the caller side.
-     */
     signal?: AbortSignal;
-    /**
-     * Per-event timeout in milliseconds: if no SSE event arrives within
-     * this window the stream throws {@link StreamTimeoutError}.
-     * Defaults to 30 000 ms (30 s). Pass `0` to disable.
-     */
     timeoutMs?: number;
-    /**
-     * Maximum reconnection attempts on network drop before the stream
-     * gives up and throws. Defaults to 3.
-     */
     maxRetries?: number;
 }
-/** A policy decision emitted mid-stream. */
 interface StreamDecisionEvent {
     type: "decision";
-    /**
-     * Policy decision — canonical 4-value lowercase vocabulary:
-     * `"allow"`, `"deny"`, `"hold"`, or `"escalate"`.
-     *
-     * Previously emitted `"ALLOW"` / `"DENY"` (uppercase, 2-value);
-     * now unified with `decision_canonical`.
-     *
-     * @deprecated Read `decision_canonical` instead for forward-compatible
-     * branching. Both fields now carry the same value. Will be
-     * removed/changed in `@atlasent/sdk@3`.
-     */
     decision: Decision;
-    /**
-     * Canonical 4-value decision, byte-identical to the wire.
-     * One of `"allow"`, `"deny"`, `"hold"`, `"escalate"`.
-     */
     decision_canonical: DecisionCanonical;
-    /** Opaque permit identifier for a final allow. Pass to verifyPermit. */
     permitId: string;
-    /** Human-readable explanation from the policy engine. */
     reason: string;
-    /** Audit hash bound to this decision. */
     auditHash: string;
-    /** ISO-8601 timestamp of the decision. */
     timestamp: string;
-    /** When true the stream will emit done and close after this event. */
     isFinal: boolean;
 }
-/** An intermediate progress hint emitted before the final decision. */
 interface StreamProgressEvent {
     type: "progress";
-    /** Human-readable stage name (e.g. "policy_loading", "context_enrichment"). */
     stage: string;
-    /** Additional server-defined fields — forward-compat, do not rely on shape. */
     [key: string]: unknown;
 }
-/** Union of all events yielded by {@link AtlaSentClient.protectStream}. */
 type StreamEvent = StreamDecisionEvent | StreamProgressEvent;
+interface BatchEvalItem {
+    agent: string;
+    action: string;
+    context?: Record<string, unknown>;
+}
+interface EvaluateBatchResultItem {
+    index: number;
+    decision?: DecisionCanonical;
+    decisionId?: string;
+    permitToken?: string | null;
+    reason?: string;
+    auditHash?: string;
+    timestamp?: string;
+    error?: string;
+    message?: string;
+}
+interface BatchEvalResponse {
+    batchId: string;
+    items: EvaluateBatchResultItem[];
+    partial: boolean;
+    replayed?: boolean;
+    rateLimit: RateLimitState | null;
+}
+interface SubscribeDecisionsOptions {
+    types?: string[];
+    actorId?: string;
+    lastEventId?: string;
+    maxSeconds?: number;
+    signal?: AbortSignal;
+}
+interface DecisionStreamEvent {
+    id?: string;
+    type: string;
+    decision?: DecisionCanonical;
+    actorId?: string;
+    resourceType?: string;
+    resourceId?: string;
+    payload?: Record<string, unknown>;
+    hash?: string;
+    previousHash?: string;
+    occurredAt?: string;
+}
+
+/**
+ * Override types — wire shapes for `/v1/overrides`.
+ *
+ * Overrides allow an authorized actor to bypass a deny decision for a
+ * specific evaluation. They must be approved before they take effect
+ * and can be revoked at any time.
+ *
+ * Mirrors `api/src/schemas/overrides.ts` in atlasent-control-plane.
+ */
+/**
+ * Lifecycle status of an override request.
+ *
+ * - `pending`  — created, waiting for approval
+ * - `approved` — approved and active; the evaluation's deny is lifted
+ * - `revoked`  — manually revoked
+ * - `expired`  — TTL elapsed before revocation
+ */
+type OverrideStatus = "pending" | "approved" | "revoked" | "expired";
+/**
+ * The event types that can appear on an override's event log.
+ */
+type OverrideEventType = "created" | "approved" | "revoked";
+/**
+ * Canonical Override domain object returned by the API.
+ *
+ * All timestamps are ISO-8601 UTC strings. Nullable fields are `null`
+ * rather than omitted so wire shapes are stable.
+ */
+interface OverrideV1 {
+    id: string;
+    orgId: string;
+    /** The evaluation ID this override applies to. */
+    evaluationId: string;
+    /** Human-readable justification provided at creation time. */
+    reason: string;
+    status: OverrideStatus;
+    /** Actor who requested the override. */
+    requestedBy: string;
+    /** Actor who approved the override, or `null` if not yet approved. */
+    approvedBy: string | null;
+    /** Actor who revoked the override, or `null` if not revoked. */
+    revokedBy: string | null;
+    /** ISO-8601 creation timestamp. */
+    createdAt: string;
+    /** ISO-8601 approval timestamp, or `null`. */
+    approvedAt: string | null;
+    /** ISO-8601 revocation timestamp, or `null`. */
+    revokedAt: string | null;
+    /** ISO-8601 expiry timestamp, or `null` if no TTL was set. */
+    expiresAt: string | null;
+    /** Arbitrary key/value metadata attached at creation. `null` when none. */
+    metadata: Record<string, unknown> | null;
+}
+/**
+ * Paginated list of overrides.
+ */
+interface OverrideListResponse {
+    items: OverrideV1[];
+    /** Opaque cursor for the next page. `null` when there are no more results. */
+    nextCursor: string | null;
+}
+/**
+ * Input for `POST /v1/overrides` — request a new override.
+ */
+interface CreateOverrideRequest {
+    /** Human-readable justification. Required; max 2000 characters. */
+    reason: string;
+    /** The evaluation ID to override. */
+    evaluationId: string;
+    /** Lifetime in seconds. Defaults to 3600. Max 604800 (7 days). */
+    ttlSeconds?: number;
+    /** Arbitrary metadata to attach to the override record. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Audit event appended to an override's event log on every state mutation.
+ */
+interface OverrideEvent {
+    id: string;
+    overrideId: string;
+    orgId: string;
+    /** Actor who caused this event. */
+    actorId: string;
+    type: OverrideEventType;
+    /** ISO-8601 timestamp. */
+    at: string;
+    /** Event-specific payload. `null` when none. */
+    payload: Record<string, unknown> | null;
+}
+/**
+ * Response for `GET /v1/overrides/:id/events`.
+ */
+interface OverrideEventsResponse {
+    items: OverrideEvent[];
+}
+
+/**
+ * Compliance evidence types — wire shapes for `v1-compliance-evidence`.
+ *
+ * Supports on-demand SOC 2 Type II control evidence collection. The
+ * same run shape is used for ISO 27001, GDPR, and HIPAA; control IDs
+ * differ per framework.
+ */
+type ComplianceFramework = "soc2" | "iso27001" | "gdpr" | "hipaa";
+type EvidenceControlStatus = "pass" | "gap" | "finding";
+type ComplianceRunStatus = "pending" | "running" | "completed" | "failed";
+/**
+ * A single evaluated control within an evidence run.
+ * `evidence` is a free-form object whose keys are framework-specific
+ * metric names (e.g. `mfa_enforced_policies`, `audit_events_last_30d`).
+ */
+interface EvidenceControl {
+    control_id: string;
+    title: string;
+    status: EvidenceControlStatus;
+    evidence: Record<string, unknown>;
+}
+interface ComplianceEvidenceSummary {
+    total: number;
+    pass: number;
+    gap: number;
+    finding: number;
+}
+interface ComplianceEvidenceRun {
+    id: string;
+    org_id: string;
+    framework: ComplianceFramework;
+    period_start: string;
+    period_end: string;
+    status: ComplianceRunStatus;
+    controls: EvidenceControl[];
+    summary: ComplianceEvidenceSummary | null;
+    applied_by: string | null;
+    created_at: string;
+}
+interface TriggerEvidenceRunRequest {
+    framework: ComplianceFramework;
+    /** ISO 8601 date string; defaults to 30 days ago on the server. */
+    period_start?: string;
+    /** ISO 8601 date string; defaults to now on the server. */
+    period_end?: string;
+}
+interface TriggerEvidenceRunResponse {
+    run: ComplianceEvidenceRun;
+}
+interface ListEvidenceRunsResponse {
+    runs: ComplianceEvidenceRun[];
+}
+/**
+ * SOC 2 control IDs evaluated by `v1-compliance-evidence`.
+ *
+ * | ID     | Area |
+ * |--------|------|
+ * | CC6.1  | MFA enforcement |
+ * | CC6.3  | Periodic access reviews |
+ * | CC7.2  | Audit trail completeness |
+ * | CC8.1  | Change management / HITL |
+ * | CC3.2  | Policy violations |
+ */
+type SOC2ControlId = "CC6.1" | "CC6.3" | "CC7.2" | "CC8.1" | "CC3.2";
+/**
+ * Returns `true` when every control in the run has `pass` or `gap`
+ * status (no `finding`). A `gap` means a control is partially met;
+ * a `finding` is a blocking deficiency that requires remediation.
+ */
+declare function evidenceRunPasses(run: ComplianceEvidenceRun): boolean;
+/**
+ * Returns controls that do not have `pass` status, sorted so
+ * `finding` controls appear before `gap` controls.
+ */
+declare function nonPassingControls(run: ComplianceEvidenceRun): EvidenceControl[];
+
+/**
+ * Evidence Engine — per-decision proof artifacts, "why" traces, and
+ * compliance-ready bundles.
+ *
+ * Turn every AtlaSent decision into tamper-evident proof that buyers
+ * can hand to auditors, compliance teams, and regulators.
+ *
+ * Primary entry points:
+ *
+ * 1. `buildWhyTrace(decision, reasons, constraintTrace)` — converts
+ *    the ConstraintTrace from `?include=constraint_trace` into a
+ *    structured human/machine-readable "why allowed / why denied" trace.
+ *
+ * 2. `buildDecisionReceiptPayload(args)` — assembles the canonical
+ *    signable payload for a per-decision receipt.
+ *
+ * 3. `signDecisionReceiptHmac(payload, secret)` — HMAC-SHA256 sign.
+ *
+ * 4. `verifyDecisionReceiptHmac(receipt, secret)` — offline verify.
+ *
+ * 5. `computeBundleHash(bundle)` — SHA-256 of an ActionEvidenceBundle.
+ *
+ * 6. `soc2ControlCoverageForDecision(opts)` — map a decision to SOC 2
+ *    control coverage.
+ *
+ * The {@link DecisionReceipt} is the category-defining artifact: a
+ * self-contained, signed, human-readable proof that a specific action
+ * was (or was not) authorized at a specific moment. Every enforcement
+ * adapter produces one; every compliance bundle includes one.
+ */
+
+/**
+ * One evaluated stage within a policy, in the order the engine ran it.
+ */
+interface WhyStage {
+    /** Engine stage name (e.g. `"role_check"`, `"context"`). */
+    stage: string;
+    /** Rule identifier, if the stage is rule-bound. */
+    rule?: string;
+    /** Whether this stage's predicate fired / matched. */
+    matched: boolean;
+    /** Non-obvious detail from the engine. */
+    detail?: string;
+    /**
+     * Impact classification:
+     * - `"terminal"` — this stage caused the outer decision.
+     * - `"contributing"` — matched but was not the decisive stage.
+     * - `"passing"` — did not match; execution continued.
+     */
+    impact: "terminal" | "contributing" | "passing";
+}
+/** Per-policy evaluation block within a WhyTrace. */
+interface WhyPolicyEvaluation {
+    policy_id: string;
+    /** Policy-level decision. */
+    decision: string;
+    /** Engine-side fingerprint of the policy bundle row. */
+    fingerprint: string;
+    /** Optional risk score from a `risk` rule clause. */
+    risk_score?: number;
+    /** Stages evaluated for this policy, in order. */
+    stages: WhyStage[];
+    /** `true` iff this policy's decision drove the outer envelope decision. */
+    was_decisive: boolean;
+}
+/**
+ * Structured "why allowed / why denied" trace.
+ *
+ * Produced by `buildWhyTrace()` from the `ConstraintTrace` returned
+ * by `/v1-evaluate?include=constraint_trace`. Suitable for:
+ *
+ * - UI display ("Why was this denied?")
+ * - Email / Slack notifications
+ * - Compliance-bundle human-readable section
+ * - Machine-readable policy audit by external verifiers
+ *
+ * `summary` is a one-sentence plain-English explanation.
+ */
+interface WhyTrace {
+    decision: DecisionCanonical;
+    /** One-sentence human-readable explanation. */
+    summary: string;
+    /** Policy whose decision drove the outer result. Absent on clean allow. */
+    matched_policy_id?: string;
+    /** Per-policy evaluation blocks in evaluation order. */
+    policy_evaluations: WhyPolicyEvaluation[];
+    /**
+     * The single stage that caused the terminal outcome, extracted for
+     * quick access. `undefined` on a clean allow (no blocking stage).
+     */
+    terminal_stage?: WhyStage;
+    /** Total stages evaluated across all policies. */
+    total_stages_evaluated: number;
+}
+/** Signing algorithm tag on a {@link DecisionReceipt}. */
+type DecisionReceiptAlgorithm = "hmac-sha256" | "ed25519" | "none";
+/**
+ * The canonical signed payload of a {@link DecisionReceipt}.
+ *
+ * Field order is load-bearing: HMAC and chain verifiers stringify
+ * this object and must reproduce byte-identical output. Never reorder
+ * the fields; add new optional fields at the end only.
+ */
+interface DecisionReceiptPayload {
+    receipt_id: string;
+    evaluation_id: string;
+    org_id: string;
+    decision: DecisionCanonical;
+    action: string;
+    actor: string;
+    resource_type: string | null;
+    resource_id: string | null;
+    reasons: string[];
+    /** One-sentence human-readable summary from the WhyTrace. */
+    why_summary: string;
+    /** Permit ID when the decision was `"allow"`. */
+    permit_id: string | null;
+    /** Permit verification hash when the decision was `"allow"`. */
+    permit_hash: string | null;
+    /** Hash-chained audit-trail entry from the evaluate response. */
+    audit_hash: string;
+    /** SHA-256 hex of canonical JSON of the evaluate context. */
+    context_hash: string;
+    /** ISO-8601 when this receipt was issued. */
+    issued_at: string;
+    /** ISO-8601 TTL, or `null` for non-expiring receipts. */
+    expires_at: string | null;
+}
+/**
+ * A signed, tamper-evident record of a single AtlaSent authorization
+ * decision. Self-contained: contains everything an auditor needs to
+ * verify the decision without querying the API.
+ *
+ * **Signature semantics (HMAC-SHA256):**
+ *
+ *   `HMAC-SHA256(secret,
+ *     receipt_id + "\\n" + issued_at + "\\n" + JSON.stringify(payload))`
+ *
+ * When `algorithm === "ed25519"`, `signature` is hex-encoded Ed25519
+ * over the same input string encoded as UTF-8.
+ *
+ * Offline verification: `verifyDecisionReceiptHmac(receipt, secret)`.
+ *
+ * Callers MUST reject receipts where `algorithm === "none"` in any
+ * context requiring tamper-evidence.
+ */
+interface DecisionReceipt {
+    receipt_id: string;
+    evaluation_id: string;
+    org_id: string;
+    decision: DecisionCanonical;
+    action: string;
+    actor: string;
+    resource_type: string | null;
+    resource_id: string | null;
+    reasons: string[];
+    /**
+     * Full structured "why" trace. `null` when the evaluation was
+     * performed without `?include=constraint_trace`.
+     */
+    why_trace: WhyTrace | null;
+    permit_id: string | null;
+    permit_hash: string | null;
+    audit_hash: string;
+    /** SHA-256 hex of canonical JSON of the evaluate context. */
+    context_hash: string;
+    issued_at: string;
+    expires_at: string | null;
+    algorithm: DecisionReceiptAlgorithm;
+    /**
+     * Hex (HMAC-SHA256 or Ed25519) signature, or `null` when
+     * `algorithm === "none"`.
+     */
+    signature: string | null;
+    /** Registry key ID that signed, when `algorithm !== "none"`. */
+    signing_key_id: string | null;
+    /**
+     * Full payload that was signed. Pass to `verifyDecisionReceiptHmac`
+     * or reconstruct independently for external verification.
+     */
+    payload: DecisionReceiptPayload;
+}
+/** Coverage summary for one compliance control within a bundle. */
+interface ComplianceControlCoverage {
+    framework: ComplianceFramework;
+    control_id: string;
+    title: string;
+    /** `true` when this bundle provides sufficient evidence for the control. */
+    covered: boolean;
+    /** Evidence kinds present in the bundle that map to this control. */
+    evidence_kinds: string[];
+}
+/**
+ * A compliance-ready evidence bundle for a single protected action.
+ *
+ * Contains everything an auditor needs to verify the authorization
+ * decision without querying the API:
+ *
+ * - The signed {@link DecisionReceipt}
+ * - The "why" trace (why allowed / why denied)
+ * - Audit events from the decision window
+ * - Permit chain (when the decision was `"allow"`)
+ * - Active overrides that influenced the decision
+ * - Per-control SOC 2 / compliance coverage map
+ *
+ * `bundle_hash` is SHA-256 of `JSON.stringify(bundle)` with
+ * `bundle_hash` omitted, computed by `computeBundleHash()`. Use it
+ * to verify the bundle was not modified after assembly.
+ */
+interface ActionEvidenceBundle {
+    /** Wire format version. */
+    v: 1;
+    bundle_id: string;
+    evaluation_id: string;
+    org_id: string;
+    action: string;
+    actor: string;
+    decision: DecisionCanonical;
+    receipt: DecisionReceipt;
+    why_trace: WhyTrace | null;
+    /** Audit events from the evaluation window related to this action. */
+    audit_events: AuditEvent[];
+    /** Permit chain when the decision was `"allow"`. */
+    permit_chain: PermitRecord[];
+    /** Active overrides that influenced the decision. */
+    overrides: OverrideV1[];
+    compliance_controls: ComplianceControlCoverage[];
+    generated_at: string;
+    /** SHA-256 hex of canonical JSON of this bundle (sans this field). */
+    bundle_hash: string;
+}
+/**
+ * Convert a raw `ConstraintTrace` (from `?include=constraint_trace`)
+ * into a structured {@link WhyTrace} with a human-readable summary.
+ *
+ * Safe to call with `trace === null` — returns a minimal trace with
+ * the decision and a generic summary derived from `reasons`.
+ *
+ * ```ts
+ * import { buildWhyTrace } from "@atlasent/sdk";
+ *
+ * const preflight = await client.evaluatePreflight({ agent, action, context });
+ * const why = buildWhyTrace(
+ *   preflight.evaluation.decision_canonical,
+ *   preflight.evaluation.reasons,
+ *   preflight.constraintTrace,
+ * );
+ * console.log(why.summary);
+ * // "Denied at stage 'role_check': actor lacks deploy role"
+ * ```
+ */
+declare function buildWhyTrace(decision: DecisionCanonical, reasons: readonly string[], trace: ConstraintTrace | null): WhyTrace;
+/**
+ * Compute SHA-256 hex of the recursively key-sorted canonical JSON of
+ * `context`. Used as `context_hash` on a `DecisionReceipt` so the
+ * original evaluate context can be independently verified offline.
+ */
+declare function computeContextHash(context: Record<string, unknown>): Promise<string>;
+/**
+ * Assemble a {@link DecisionReceiptPayload} — the canonical object
+ * that is serialised and signed. Field insertion order is fixed;
+ * do NOT reorder the fields below.
+ */
+declare function buildDecisionReceiptPayload(args: {
+    receipt_id: string;
+    evaluation_id: string;
+    org_id: string;
+    decision: DecisionCanonical;
+    action: string;
+    actor: string;
+    resource_type?: string | null;
+    resource_id?: string | null;
+    reasons: readonly string[];
+    why_summary: string;
+    permit_id?: string | null;
+    permit_hash?: string | null;
+    audit_hash: string;
+    context_hash: string;
+    issued_at: string;
+    expires_at?: string | null;
+}): DecisionReceiptPayload;
+/**
+ * HMAC-SHA256 sign a {@link DecisionReceiptPayload}. Returns the
+ * hex-encoded MAC. Store as `receipt.signature` with
+ * `algorithm: "hmac-sha256"`.
+ *
+ * Uses `crypto.subtle` (browser / Node 20+ / Cloudflare) or falls
+ * back to `node:crypto` on older Node runtimes.
+ */
+declare function signDecisionReceiptHmac(payload: DecisionReceiptPayload, secret: string): Promise<string>;
+/**
+ * Verify an HMAC-SHA256-signed {@link DecisionReceipt} offline.
+ * Returns `false` (does not throw) on any verification failure.
+ *
+ * Callers MUST reject receipts where `receipt.algorithm !== "hmac-sha256"`.
+ */
+declare function verifyDecisionReceiptHmac(receipt: DecisionReceipt, secret: string): Promise<boolean>;
+/**
+ * Compute SHA-256 hex of `JSON.stringify(bundle)` with `bundle_hash`
+ * omitted. Store as `bundle.bundle_hash` after assembly.
+ *
+ * An external verifier can reproduce this value independently to
+ * confirm the bundle was not modified after export.
+ */
+declare function computeBundleHash(bundle: Omit<ActionEvidenceBundle, "bundle_hash">): Promise<string>;
+/**
+ * Return the SOC 2 controls covered by a single authorization decision,
+ * given what the bundle contains. Suitable for populating
+ * `ActionEvidenceBundle.compliance_controls`.
+ *
+ * For ISO 27001 / GDPR / HIPAA coverage use the `@atlasent/evidence-bundle`
+ * package's `buildEvidenceBundle()` which handles multi-framework mapping.
+ */
+declare function soc2ControlCoverageForDecision(opts: {
+    decision: DecisionCanonical;
+    hasPermitChain: boolean;
+    hasAuditEvents: boolean;
+    hasOverrides: boolean;
+}): ComplianceControlCoverage[];
 
 /** Input to {@link protect}. Same shape as `EvaluateRequest`. */
 interface ProtectRequest {
@@ -1287,6 +1903,8 @@ interface Permit {
     reason: string;
     /** ISO 8601 timestamp of the verification. */
     timestamp: string;
+    /** ISO-8601 expiration timestamp of the permit. null on pre-rollout servers. */
+    permitExpiresAt: string | null;
 }
 /** Configuration for the process-wide singleton used by {@link protect}. */
 interface ConfigureOptions {
@@ -1325,5 +1943,67 @@ declare function deployGate(request?: DeployGateRequest): Promise<DeployGateResp
  *   or server error. Same fail-closed contract: do not proceed.
  */
 declare function protect(request: ProtectRequest): Promise<Permit>;
+/**
+ * A verified {@link Permit} with an embedded signed {@link DecisionReceipt}.
+ *
+ * Returned by {@link protectWithEvidence}. Store `receipt` alongside
+ * your action record (deploy logs, payment records, close workflows)
+ * to give auditors a self-contained proof of authorization.
+ */
+interface PermitWithEvidence extends Permit {
+    /** Signed per-decision receipt. `algorithm: "none"` when no signing secret was supplied. */
+    receipt: DecisionReceipt;
+}
+/** Options for {@link protectWithEvidence}. */
+interface ProtectWithEvidenceOptions {
+    /**
+     * HMAC-SHA256 signing secret. When provided, the receipt is signed
+     * and can be verified offline with `verifyDecisionReceiptHmac`.
+     * Recommend `process.env.ATLASENT_RECEIPT_SIGNING_SECRET`.
+     */
+    signingSecret?: string;
+    /**
+     * Registry key ID recorded on the receipt, paired with `signingSecret`.
+     * Used for key rotation: store the ID alongside the receipt so
+     * verifiers know which key to use.
+     */
+    signingKeyId?: string;
+    /**
+     * If you have already called `client.evaluatePreflight()` for this
+     * request, pass `constraintTrace` here to populate
+     * `receipt.why_trace` with the full stage-by-stage "why" trace.
+     * When omitted, `why_trace` is `null` on the receipt.
+     */
+    constraintTrace?: ConstraintTrace | null;
+}
+/**
+ * Authorize an action end-to-end and mint a signed {@link DecisionReceipt}.
+ *
+ * Same fail-closed contract as {@link protect} — throws
+ * {@link AtlaSentDeniedError} on deny, {@link AtlaSentError} on
+ * transport failure. The action MUST NOT proceed if this throws.
+ *
+ * On allow, returns the verified `Permit` plus a signed `DecisionReceipt`
+ * that captures:
+ * - The evaluation ID and decision
+ * - Human-readable reasons
+ * - Permit ID and hash
+ * - Audit-trail hash (hash-chain link)
+ * - SHA-256 of the evaluate context (tamper-evidence for the inputs)
+ * - Optional "why" trace (pass `constraintTrace` from `evaluatePreflight`)
+ *
+ * ```ts
+ * const { permit, receipt } = await protectWithEvidence(
+ *   { agent: "deploy-bot", action: "production.deploy", context },
+ *   {
+ *     signingSecret: process.env.ATLASENT_RECEIPT_SIGNING_SECRET,
+ *     signingKeyId: "key-v1",
+ *   },
+ * );
+ * // Store alongside the deployment record.
+ * await db.deployments.create({ commitSha, permit, receipt });
+ * ```
+ */
+declare function protectWithEvidence(request: ProtectRequest, opts?: ProtectWithEvidenceOptions): Promise<PermitWithEvidence>;
 
-export { type DeployGateDenyCode as $, AtlaSentDeniedError as A, type AtlaSentErrorInit as B, AtlaSentEscalateError as C, type DeployGateRequest as D, type EvaluateRequest as E, type AtlaSentEscalateErrorInit as F, type GetPermitResponse as G, type AuditDecision as H, type AuditEvent as I, type AuditEventsPage as J, type AuditExport as K, type ListPermitsRequest as L, type AuditExportSignatureStatus as M, type ConfigureOptions as N, type ConstraintTrace as O, type Permit as P, type ConstraintTracePolicy as Q, type RateLimitState as R, type StreamOptions as S, type ConstraintTraceStage as T, DEFAULT_RETRY_POLICY as U, type VerifyPermitRequest as V, DEPLOYMENT_PRODUCTION_ACTION as W, DEPLOY_GATE_CODES as X, type Decision as Y, type DecisionCanonical as Z, type DeployGateContext as _, AtlaSentError as a, type DeployGateEvidence as a0, type DeployOverrideClaim as a1, type DeployPermitClaim as a2, type EvaluateResponsePermit as a3, PRODUCTION_DEPLOY_ACTION as a4, type PermitOutcome as a5, type PermitRecord as a6, PermitRevoked as a7, type PermitStatus as a8, type RetryPolicy as a9, type StreamDecisionEvent as aa, StreamParseError as ab, type StreamProgressEvent as ac, StreamTimeoutError as ad, computeBackoffMs as ae, hasAttemptsLeft as af, isRetryable as ag, mergePolicy as ah, normalizePermitOutcome as ai, type ProtectRequest as b, type AtlaSentClientOptions as c, type EvaluateResponse as d, type EvaluatePreflightResponse as e, type VerifyPermitResponse as f, type DeployGateResponse as g, type RevokePermitRequest as h, type RevokePermitResponse as i, type RevokePermitByIdInput as j, type RevokePermitByIdResponse as k, type VerifyPermitByIdResponse as l, type PermitValidResponse as m, type ListPermitsResponse as n, type ApiKeySelfResponse as o, type AuditEventsQuery as p, type AuditEventsResult as q, type AuditExportRequest as r, type AuditExportResult as s, type StreamEvent as t, protect as u, deployGate as v, configure as w, type AtlaSentDecision as x, type AtlaSentDeniedErrorInit as y, type AtlaSentErrorCode as z };
+export { BundleVerificationError as $, AtlaSentDeniedError as A, type BatchEvalItem as B, type ComplianceEvidenceRun as C, type DecisionCanonical as D, type EvaluateRequest as E, protect as F, type GetPermitResponse as G, deployGate as H, configure as I, type ActionEvidenceBundle as J, type AtlaSentDecision as K, type ListPermitsRequest as L, type AtlaSentDeniedErrorInit as M, type AtlaSentErrorCode as N, type OverrideV1 as O, type Permit as P, type AtlaSentErrorInit as Q, type RateLimitState as R, type SubscribeDecisionsOptions as S, AtlaSentEscalateError as T, type AtlaSentEscalateErrorInit as U, type VerifyPermitRequest as V, type AuditDecision as W, type AuditEvent as X, type AuditEventsPage as Y, type AuditExport as Z, type AuditExportSignatureStatus as _, AtlaSentError as a, protectWithEvidence as a$, type BvsSnapshot as a0, type CompletionProof as a1, type ComplianceControlCoverage as a2, type ComplianceEvidenceSummary as a3, type ComplianceFramework as a4, type ComplianceRunStatus as a5, type ConfigureOptions as a6, type ConsentClassProjection as a7, type ConstraintTrace as a8, type ConstraintTracePolicy as a9, type PermitRecord as aA, PermitRevoked as aB, type PermitStatus as aC, type PermitWithEvidence as aD, type ProtectWithEvidenceOptions as aE, type RetryPolicy as aF, type SOC2ControlId as aG, type StreamDecisionEvent as aH, StreamParseError as aI, type StreamProgressEvent as aJ, StreamTimeoutError as aK, type TriggerEvidenceRunRequest as aL, type TriggerEvidenceRunResponse as aM, type WhyPolicyEvaluation as aN, type WhyStage as aO, type WhyTrace as aP, buildDecisionReceiptPayload as aQ, buildWhyTrace as aR, computeBackoffMs as aS, computeBundleHash as aT, computeContextHash as aU, evidenceRunPasses as aV, hasAttemptsLeft as aW, isRetryable as aX, mergePolicy as aY, nonPassingControls as aZ, normalizePermitOutcome as a_, type ConstraintTraceStage as aa, type CreateOverrideRequest as ab, DEFAULT_RETRY_POLICY as ac, DEPLOYMENT_PRODUCTION_ACTION as ad, DEPLOY_GATE_CODES as ae, type Decision as af, type DecisionReceiptPayload as ag, type DeployGateContext as ah, type DeployGateDenyCode as ai, type DeployGateEvidence as aj, type DeployOverrideClaim as ak, type DeployPermitClaim as al, type EvaluateBatchResultItem as am, type EvaluateResponsePermit as an, type EvaluateRiskEnvelope as ao, type EvaluateRiskEnvelopeFactor as ap, type EvidenceControl as aq, type EvidenceControlStatus as ar, type ListEvidenceRunsResponse as as, type OverrideEvent as at, type OverrideEventType as au, type OverrideEventsResponse as av, type OverrideListResponse as aw, type OverrideStatus as ax, PRODUCTION_DEPLOY_ACTION as ay, type PermitOutcome as az, type ProtectRequest as b, signDecisionReceiptHmac as b0, soc2ControlCoverageForDecision as b1, verifyDecisionReceiptHmac as b2, type AtlaSentClientOptions as c, type EvaluateResponse as d, type BatchEvalResponse as e, type DecisionStreamEvent as f, type EvaluatePreflightResponse as g, type VerifyPermitResponse as h, type DeployGateRequest as i, type DeployGateResponse as j, type RevokePermitRequest as k, type RevokePermitResponse as l, type RevokePermitByIdInput as m, type RevokePermitByIdResponse as n, type VerifyPermitByIdResponse as o, type PermitValidResponse as p, type ListPermitsResponse as q, type ApiKeySelfResponse as r, type AuditEventsQuery as s, type AuditEventsResult as t, type AuditExportRequest as u, type AuditExportResult as v, type StreamOptions as w, type StreamEvent as x, type DecisionReceipt as y, type DecisionReceiptAlgorithm as z };