@atlasent/sdk 1.5.0 → 2.5.0

package/dist/protect-DiRVfVLq.d.cts

@@ -0,0 +1,1329 @@
+/**
+ * Error types for the AtlaSent TypeScript SDK.
+ *
+ * The SDK follows a fail-closed design: a clean policy DENY is
+ * returned as `EvaluateResponse.decision === "deny"` (not thrown),
+ * but any failure to confirm authorization — network, timeout,
+ * bad response, invalid key, rate limit — throws an
+ * {@link AtlaSentError}.
+ */
+/**
+ * Thrown when no SSE event arrives within the configured timeout window.
+ *
+ * Callers can catch this specifically to distinguish a stalled stream
+ * from other network or parse failures:
+ *
+ * ```ts
+ * catch (e) {
+ *   if (e instanceof StreamTimeoutError) { // reconnect or alert }
+ * }
+ * ```
+ */
+declare class StreamTimeoutError extends Error {
+    name: string;
+    /** Timeout that was exceeded, in milliseconds. */
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Thrown when the SSE stream closes with a partial / malformed JSON payload.
+ *
+ * This is a recoverable condition — the stream closed mid-JSON. The
+ * caller can reconnect using the last received `Last-Event-ID` and
+ * resume from where the server left off.
+ *
+ * ```ts
+ * catch (e) {
+ *   if (e instanceof StreamParseError) { // log raw data, maybe reconnect }
+ * }
+ * ```
+ */
+declare class StreamParseError extends Error {
+    name: string;
+    /** The raw data string that failed to parse. */
+    readonly rawData: string;
+    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";
+/** Initialization options for {@link AtlaSentError}. */
+interface AtlaSentErrorInit {
+    status?: number;
+    code?: AtlaSentErrorCode;
+    requestId?: string;
+    retryAfterMs?: number;
+    cause?: unknown;
+}
+/**
+ * The only error type this SDK throws.
+ *
+ * Flat top-level properties mirror the convention used by Stripe,
+ * Octokit, and Supabase. `cause` is forwarded to the standard
+ * ES2022 `Error` constructor.
+ */
+declare class AtlaSentError extends Error {
+    name: string;
+    /** HTTP status code, when the error originated from an API response. */
+    readonly status: number | undefined;
+    /** Coarse category — useful for `switch` statements at call sites. */
+    readonly code: AtlaSentErrorCode | undefined;
+    /** Correlation ID echoed from the `X-Request-ID` header the SDK sent. */
+    readonly requestId: string | undefined;
+    /** Parsed `Retry-After` header value, in milliseconds. Only set for 429. */
+    readonly retryAfterMs: number | undefined;
+    constructor(message: string, init?: AtlaSentErrorInit);
+}
+/**
+ * Outcome of a denied decision.
+ *
+ * `"deny"` is what the current `/v1-evaluate` API returns. `"hold"`
+ * and `"escalate"` are reserved for forthcoming API decisions that
+ * put a permit into a pending state requiring human review; the
+ * union is declared now so call sites can `switch` exhaustively
+ * from the start and adopt new decisions without a breaking change.
+ */
+type AtlaSentDecision = "deny" | "hold" | "escalate";
+/**
+ * Reason an already-issued permit failed verification.
+ *
+ * Surfaced on {@link AtlaSentDeniedError.outcome} so callers can
+ * distinguish replay (`permit_consumed`) from revocation
+ * (`permit_revoked`) from natural expiry (`permit_expired`) without
+ * parsing {@link AtlaSentDeniedError.reason}. The set is defined by
+ * `contract/vectors/permit_outcomes.json`; any new outcome MUST be
+ * added there first.
+ *
+ * Mirrors the Python SDK's `PermitOutcome`. See
+ * `atlasent/docs/REVOCATION_RUNBOOK.md` for the operator-facing
+ * matrix this discriminator drives.
+ */
+type PermitOutcome = "permit_consumed" | "permit_expired" | "permit_revoked" | "permit_not_found";
+/**
+ * Map a server-supplied `outcome` string to {@link PermitOutcome}.
+ *
+ * Returns `undefined` for `undefined`, `""`, `"verified"`, or any
+ * unrecognized value. Used at the SDK's deny boundary so we don't
+ * surface mis-typed outcomes — when the server adds a new outcome
+ * string, callers branching on {@link AtlaSentDeniedError.outcome}
+ * see `undefined` and fall through to their generic deny path
+ * rather than match an unknown literal.
+ */
+declare function normalizePermitOutcome(raw: string | undefined): PermitOutcome | undefined;
+/** Initialization options for {@link AtlaSentDeniedError}. */
+interface AtlaSentDeniedErrorInit {
+    decision: AtlaSentDecision;
+    evaluationId: string;
+    reason?: string;
+    requestId?: string;
+    auditHash?: string;
+    /**
+     * When the denial came from permit verification (not policy
+     * evaluation), the discriminator that distinguishes replay,
+     * expiry, revocation, and missing-record failures. `undefined`
+     * for evaluate-time denials.
+     */
+    outcome?: PermitOutcome;
+}
+/**
+ * Thrown by {@link atlasent.protect} when the policy engine refuses
+ * the action, or when a permit fails end-to-end verification.
+ *
+ * This is the **fail-closed boundary** of the SDK: every code path
+ * that short-circuits an action because authorization was not
+ * confirmed raises an `AtlaSentDeniedError`. Callers cannot silently
+ * proceed on a denial by forgetting to branch on a return value.
+ *
+ * Extends {@link AtlaSentError} so `instanceof AtlaSentError`
+ * catches denials as part of the SDK's single exception family;
+ * use `instanceof AtlaSentDeniedError` to distinguish a policy
+ * denial from a transport/auth error.
+ */
+declare class AtlaSentDeniedError extends AtlaSentError {
+    name: string;
+    /** Policy decision — `"deny"` today; `"hold"` / `"escalate"` reserved. */
+    readonly decision: AtlaSentDecision;
+    /** Opaque permit/decision id from `/v1-evaluate`. */
+    readonly evaluationId: string;
+    /** Human-readable explanation from the policy engine, if provided. */
+    readonly reason: string | undefined;
+    /** Hash-chained audit-trail entry associated with the decision. */
+    readonly auditHash: string | undefined;
+    /**
+     * 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}.
+     */
+    readonly outcome: PermitOutcome | undefined;
+    constructor(init: AtlaSentDeniedErrorInit);
+    /** `true` when the permit was explicitly revoked (D3 endpoint). */
+    get isRevoked(): boolean;
+    /** `true` when the permit's TTL passed before verification. */
+    get isExpired(): boolean;
+    /**
+     * `true` when the permit was already consumed by a prior verify
+     * (v1 single-use replay protection).
+     */
+    get isConsumed(): boolean;
+    /**
+     * `true` when the permit id wasn't recognized server-side
+     * (typo, cross-tenant lookup, or pre-issuance race).
+     */
+    get isNotFound(): boolean;
+}
+/** Initialization options for {@link AtlaSentEscalateError}. */
+interface AtlaSentEscalateErrorInit {
+    requestId?: string;
+    userId?: string;
+    cause?: unknown;
+}
+/**
+ * Thrown when an evaluate response carries `decision: "escalate"`.
+ *
+ * Distinct from {@link AtlaSentDeniedError} — an escalation does not
+ * constitute a hard denial. It signals that the policy engine has
+ * deferred the authorization decision to a human review queue.
+ * Middleware and agent orchestrators should catch this specifically
+ * and route the pending action to the appropriate HITL channel.
+ *
+ * ```ts
+ * catch (e) {
+ *   if (e instanceof AtlaSentEscalateError) {
+ *     await humanReviewQueue.submit({ userId: e.userId, requestId: e.requestId });
+ *   }
+ * }
+ * ```
+ *
+ * Extends {@link AtlaSentError} so `instanceof AtlaSentError` catches
+ * escalations alongside other SDK errors; use
+ * `instanceof AtlaSentEscalateError` to branch specifically.
+ */
+declare class AtlaSentEscalateError extends AtlaSentError {
+    name: string;
+    /** Always `"escalate"` — discriminates this error from other AtlaSent errors. */
+    readonly decision: "escalate";
+    /** The user whose action triggered the escalation, if available. */
+    readonly userId: string | undefined;
+    constructor(message: string, opts?: AtlaSentEscalateErrorInit);
+}
+/**
+ * Thrown by an SDK guard heartbeat when `GET /v1/permits/:id/valid`
+ * returns `status: 'revoked'` during tool execution (PROD-D9
+ * continuous-authorization lease model).
+ *
+ * This error is **always re-thrown** — it is never serialized as a
+ * `tool-result` denial because it represents a live enforcement action,
+ * not a policy evaluation at request time. Callers should treat it as
+ * an immediate halt signal.
+ *
+ * ```ts
+ * catch (e) {
+ *   if (e instanceof PermitRevoked) {
+ *     // log e.permitId and e.revocationId for incident correlation
+ *     await incidentLog.record({ permitId: e.permitId, revocationId: e.revocationId });
+ *   }
+ * }
+ * ```
+ *
+ * Guard heartbeat is configured via `permitRevalidationIntervalMs` in
+ * the guard options (minimum 1000 ms). The heartbeat activates only
+ * when the {@link AtlaSentClient} exposes `checkPermitValid` — i.e.
+ * when `atlasent-api` has deployed `GET /v1/permits/:id/valid`.
+ */
+declare class PermitRevoked extends AtlaSentError {
+    name: string;
+    /** The id of the permit that was revoked mid-execution. */
+    readonly permitId: string;
+    /** The `scope_revocations.id` that triggered the revocation, when available. */
+    readonly revocationId: string | undefined;
+    constructor(permitId: string, revocationId?: string);
+}
+
+/**
+ * Retry-policy helpers for the AtlaSent TypeScript SDK.
+ *
+ * This module is **pure**: no I/O, no network, no globals beyond
+ * `Math.random`. The intent is that {@link AtlaSentClient} (and any
+ * caller wrapping `protect()` / `evaluate()`) can ask
+ * {@link isRetryable} whether to retry a given {@link AtlaSentError},
+ * then ask {@link computeBackoffMs} how long to sleep before the next
+ * attempt.
+ *
+ * Wire-up into the client itself is intentionally deferred — see
+ * ROADMAP item #7 (Post-GA). Sentry breadcrumb emission is also
+ * deferred; both will land together once a transport-level retry
+ * loop is wired into `client.ts`.
+ *
+ * Retry classification (matches the server's documented contract):
+ *   - `network` / `timeout`        → retry (transient transport)
+ *   - `server_error` (HTTP 5xx)    → retry
+ *   - `rate_limited` (HTTP 429)    → retry, honour `retryAfterMs`
+ *   - `bad_response`               → retry (likely truncated body)
+ *   - `invalid_api_key`/`forbidden`/`bad_request` → never retry
+ *
+ * Backoff: capped exponential with full jitter.
+ *   delay = min(maxDelayMs, baseDelayMs * 2^attempt) * random[0, 1)
+ *
+ * "Full jitter" is the AWS-recommended scheme — see
+ * https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/.
+ * 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
+ */
+/**
+ * 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).
+ */
+declare const DEFAULT_RETRY_POLICY: Required<RetryPolicy>;
+/**
+ * Caller-tunable retry policy. All fields optional; missing fields
+ * fall back to {@link DEFAULT_RETRY_POLICY}.
+ */
+interface RetryPolicy {
+    /**
+     * Total attempts including the first try. `1` disables retries
+     * entirely. Must be `>= 1`; values below are clamped to `1`.
+     */
+    maxAttempts?: number;
+    /**
+     * Initial backoff for `attempt = 0`. Doubles per attempt up to
+     * `maxDelayMs`. Must be `>= 0`.
+     */
+    baseDelayMs?: number;
+    /**
+     * Hard ceiling on the per-attempt sleep, applied **before** jitter.
+     * The actual sleep is uniformly distributed in `[0, ceiling]`.
+     */
+    maxDelayMs?: number;
+}
+/**
+ * Decide whether `err` is worth a retry. Anything that isn't an
+ * {@link AtlaSentError} is treated as non-retryable — the SDK's
+ * transport layer always wraps fetch failures in `AtlaSentError`,
+ * so a non-AtlaSent throwable is by definition a programmer bug
+ * (a bad input, an assertion in user code) and should propagate.
+ */
+declare function isRetryable(err: unknown): boolean;
+/**
+ * Compute how long to sleep before retry attempt `attempt`
+ * (zero-indexed: `attempt = 0` is the first retry, i.e. the second
+ * total request). Uses capped exponential backoff with full jitter.
+ *
+ * When `err` carries a `retryAfterMs` (server-provided `Retry-After`
+ * header), the result is `max(retryAfterMs, jitteredDelay)` — the
+ * server's hint is treated as a floor so we never retry sooner than
+ * the server asked.
+ *
+ * @param attempt    Zero-indexed retry attempt (0, 1, 2, ...).  For
+ *                   the default policy this produces delays drawn from
+ *                   [0, 2 000), [0, 4 000), [0, 8 000), [0, 16 000).
+ * @param policy     Optional override of {@link DEFAULT_RETRY_POLICY}.
+ * @param err        Optional error whose `retryAfterMs` is honoured.
+ * @param random     Injectable RNG, defaults to `Math.random`. Must
+ *                   return values in `[0, 1)` to preserve the
+ *                   distribution.
+ */
+declare function computeBackoffMs(attempt: number, policy?: RetryPolicy, err?: unknown, random?: () => number): number;
+/**
+ * Returns `true` when `attempt` (zero-indexed) is below the policy's
+ * `maxAttempts - 1` ceiling — i.e. when there is still budget for at
+ * least one more try after this one. Convenience wrapper so retry
+ * loops read top-to-bottom:
+ *
+ * ```ts
+ * for (let attempt = 0; ; attempt++) {
+ *   try { return await op(); }
+ *   catch (err) {
+ *     if (!isRetryable(err) || !hasAttemptsLeft(attempt, policy)) throw err;
+ *     await sleep(computeBackoffMs(attempt, policy, err));
+ *   }
+ * }
+ * ```
+ */
+declare function hasAttemptsLeft(attempt: number, policy?: RetryPolicy): boolean;
+/**
+ * Merge a partial policy with {@link DEFAULT_RETRY_POLICY} and clamp
+ * each field into a sensible range. Exported for tests and for
+ * callers that want to log the resolved policy.
+ */
+declare function mergePolicy(policy: RetryPolicy): Required<RetryPolicy>;
+
+/**
+ * Shared audit wire types — the `/v1/audit/*` HTTP surface.
+ *
+ * Source of truth: `atlasent-api/supabase/functions/v1-audit/index.ts`
+ * (the edge function that serves `GET /v1/audit/events`,
+ * `POST /v1/audit/exports`, and `POST /v1/audit/verify`). The docstring
+ * at the top of that file describes these shapes. Keep this module in
+ * lockstep with it; `test/audit-types.test.ts` contains type-level
+ * assertions against the field set to make drift obvious.
+ *
+ * Fields are snake_case because that is what the server emits on the
+ * wire — unlike the evaluate / verify-permit types in `./types.ts`,
+ * which use camelCase on the SDK side and translate at the client
+ * boundary, the audit surface is intentionally wire-identical so that
+ * signed export bundles round-trip byte-for-byte through verifiers.
+ */
+/** Policy decision enum used on `audit_events.decision`. */
+type AuditDecision = 'allow' | 'deny' | 'hold' | 'escalate';
+/**
+ * Signing status reported on an export bundle. "signed" is the normal
+ * path; "unsigned" means the deployment has no active signing key;
+ * "signing_failed" means a key is configured but signing errored and
+ * the export was returned anyway (the signature is an empty string).
+ */
+type AuditExportSignatureStatus = 'signed' | 'unsigned' | 'signing_failed';
+/**
+ * One persisted row from `audit_events`, as returned by
+ * `GET /v1/audit/events` and embedded inside `AuditExport.events`.
+ *
+ * `decision` is nullable because not every event is an evaluation —
+ * CRUD-style audit writes (e.g. `policy.updated`) omit it. All other
+ * nullable fields follow the same "field doesn't apply to this event
+ * type" convention rather than "unknown value".
+ */
+interface AuditEvent {
+    /** Event UUID. Stable; surfaces as `tampered_event_ids` on verify failure. */
+    id: string;
+    /** Organization this event belongs to. */
+    org_id: string;
+    /** Per-org monotonic sequence. Used as the pagination cursor's payload. */
+    sequence: number;
+    /** Event type tag (e.g. "evaluate.allow", "policy.updated"). */
+    type: string;
+    /** Policy decision when the event is an evaluation; `null` otherwise. */
+    decision: AuditDecision | null;
+    /** Actor id (user / API key / agent) when applicable. */
+    actor_id: string | null;
+    /** Optional resource tag — e.g. "policy". */
+    resource_type: string | null;
+    /** Optional resource id — paired with `resource_type`. */
+    resource_id: string | null;
+    /** Canonical JSON of the event payload. Hashed into `hash`. */
+    payload: Record<string, unknown> | null;
+    /** SHA-256(prev_hash || canonicalJSON(payload)), hex. */
+    hash: string;
+    /** Previous event's `hash` (genesis is `"0".repeat(64)`). */
+    previous_hash: string;
+    /** When the underlying action occurred (ISO 8601). */
+    occurred_at: string;
+    /** When the row was persisted (ISO 8601). */
+    created_at: string;
+}
+/**
+ * Response shape for `GET /v1/audit/events`.
+ *
+ * `total` is the filter's full count (not just this page) so callers
+ * can show "page 1 of N" without an extra HEAD request.
+ *
+ * `next_cursor` is an opaque base64url string. Pass it back verbatim
+ * as `?cursor=...` to fetch the next page. Absent when this is the
+ * last page.
+ */
+interface AuditEventsPage {
+    events: AuditEvent[];
+    total: number;
+    next_cursor?: string;
+}
+/**
+ * Query parameters accepted by `GET /v1/audit/events`. Serialize as
+ * URL search params — `types` is a comma-joined list on the wire
+ * (e.g. `types=evaluate.allow,policy.updated`).
+ *
+ * All fields are optional; the server defaults `limit` to 50 and caps
+ * it at 500.
+ */
+interface AuditEventsQuery {
+    /** Comma-joined list of event types to filter on. */
+    types?: string;
+    /** Filter to a single actor. */
+    actor_id?: string;
+    /** Inclusive lower bound on `occurred_at` (ISO 8601). */
+    from?: string;
+    /** Inclusive upper bound on `occurred_at` (ISO 8601). */
+    to?: string;
+    /** Page size. Default 50, min 1, max 500. */
+    limit?: number;
+    /** Opaque cursor returned as `next_cursor` by the prior page. */
+    cursor?: string;
+}
+/**
+ * Response shape for `POST /v1/audit/exports` — a signed bundle of
+ * audit events suitable for offline verification.
+ *
+ * `signature` is detached Ed25519 over `signedBytesFor(bundle)` (see
+ * `./auditBundle.ts`). An empty string means the server attempted to
+ * sign but failed; check `signature_status` to distinguish.
+ *
+ * `tampered_event_ids` surfaces rows whose recomputed hash doesn't
+ * match the stored hash — even when `chain_integrity_ok` is false,
+ * the signature still covers whatever the server emitted, so callers
+ * that trust the signature must still inspect this list.
+ */
+interface AuditExport {
+    /** Server-assigned UUID for this export. */
+    export_id: string;
+    /** Organization the bundle belongs to. */
+    org_id: string;
+    /** Events in canonical (ascending sequence) order. */
+    events: AuditEvent[];
+    /** Last event's `hash`, or `"0".repeat(64)` if `events` is empty. */
+    chain_head_hash: string;
+    /** `true` iff adjacency + re-hash succeeded for every event. */
+    chain_integrity_ok: boolean;
+    /** `AuditEvent.id`s whose recomputed hash != stored hash. */
+    tampered_event_ids: string[];
+    /** Detached Ed25519 signature (base64url). Empty string on sign failure. */
+    signature: string;
+    /** Outcome of the signing attempt. */
+    signature_status: AuditExportSignatureStatus;
+    /** Registry id of the key that signed — absent when unsigned. */
+    signing_key_id?: string;
+    /** When the bundle was signed (ISO 8601). */
+    signed_at: string;
+}
+
+/**
+ * Canonical 4-value policy decision, byte-identical to the wire.
+ *
+ * - `allow`    — action is authorized; a Permit is issued.
+ * - `deny`     — action is blocked.
+ * - `hold`     — decision deferred (e.g. waiting on an approval signal).
+ * - `escalate` — routed to a human reviewer queue.
+ *
+ * Pin to this type on new code.
+ */
+type DecisionCanonical = "allow" | "deny" | "hold" | "escalate";
+/**
+ * Decision type — unified with the canonical 4-value vocabulary.
+ *
+ * This type previously emitted `"ALLOW"` / `"DENY"` (uppercase, 2-value).
+ * It now reflects the canonical wire values (`"allow" | "deny" | "hold" |
+ * "escalate"`) so the `decision` and `decision_canonical` fields on
+ * {@link EvaluateResponse} carry identical values and types.
+ *
+ * Backward compatibility: the SDK normalises API response values to
+ * lowercase (`.toLowerCase()`) before returning them, so callers that
+ * previously checked `=== "ALLOW"` must update to `=== "allow"`. The
+ * canonical field `decision_canonical` is also available and was always
+ * lowercase — prefer it on new code.
+ *
+ * Legacy uppercase input accepted by the SDK is normalised to lowercase
+ * output; `"ALLOW"` in → `"allow"` out, `"DENY"` in → `"deny"` out.
+ */
+type Decision = DecisionCanonical;
+/**
+ * Rate-limit state parsed from the server's `X-RateLimit-*` headers.
+ *
+ * Present on every authenticated response (success and 429) when the
+ * server emits the headers. `null` when the server doesn't — older
+ * deployments, or internal endpoints that skip per-key rate limiting.
+ *
+ * Clients should check `remaining` and sleep until `resetAt` to
+ * preemptively back off before hitting a 429.
+ */
+interface RateLimitState {
+    /** Value of `X-RateLimit-Limit` — the per-minute budget. */
+    limit: number;
+    /** Value of `X-RateLimit-Remaining` — unused budget in the current window. */
+    remaining: number;
+    /**
+     * Parsed `X-RateLimit-Reset` — the UTC instant when the current
+     * window's counter zeroes. Accepts either a unix-seconds integer or
+     * an ISO 8601 string on the wire.
+     */
+    resetAt: Date;
+}
+/**
+ * Canonical Deploy Gate V1 protected action.
+ *
+ * Use this constant (or its string value `"production.deploy"`) on all
+ * new code. Server-side `action_classes.slug` was canonicalised to
+ * `production.deploy` in atlasent-api PR #662 / atlasent-console
+ * PR #432; the SDK default now matches.
+ */
+declare const PRODUCTION_DEPLOY_ACTION: "production.deploy";
+/**
+ * Legacy alias for {@link PRODUCTION_DEPLOY_ACTION}.
+ *
+ * @deprecated since 2.3.0 — use {@link PRODUCTION_DEPLOY_ACTION}. The
+ * server alias-tolerates `deployment.production` during the V1 alias
+ * window, so existing callers continue to work unchanged; please
+ * migrate by the next minor release.
+ */
+declare const DEPLOYMENT_PRODUCTION_ACTION: "deployment.production";
+/**
+ * Permit claim for `production.deploy` evaluations (Rule 3).
+ *
+ * Pass as `permit` inside {@link DeployGateContext}.
+ * The `verified` flag is set by the verify-permit service after a
+ * successful `/v1-verify-permit` call — do not self-assert it.
+ */
+interface DeployPermitClaim {
+    permit_id?: string;
+    environment?: string;
+    action_type?: string;
+    /** ISO-8601 timestamp when the permit was issued. */
+    issued_at?: string;
+    /** Set server-side by the verify-permit service. Do not self-assert. */
+    verified?: boolean;
+}
+/**
+ * Override claim for `production.deploy` evaluations (Rule 8).
+ *
+ * Both `override_reason` and `authority_basis` must be non-empty to
+ * receive `OVERRIDE_APPROVED`. Missing or blank fields return `DENY_POLICY`.
+ */
+interface DeployOverrideClaim {
+    /** Human-readable reason. Required and non-empty. */
+    override_reason?: string;
+    /** Authoritative basis — runbook section, incident ticket, etc. Required and non-empty. */
+    authority_basis?: string;
+    /** Approver actor ID (audit record; does not gate the decision). */
+    approver_actor_id?: string;
+}
+/**
+ * Typed context shape for `production.deploy` evaluations.
+ *
+ * Pass as `context` to `protect()`, `deployGate()`, or
+ * {@link AtlaSentClient.evaluate} for the Deploy Gate V1 flow.
+ *
+ * @example
+ * ```ts
+ * const permit = await atlasent.protect({
+ *   agent: "deploy-bot",
+ *   action: PRODUCTION_DEPLOY_ACTION,
+ *   context: {
+ *     environment: "production",
+ *     evaluation_confirmed: true,
+ *     actorMetadata: { role: "deploy_engineer" },
+ *     permit: {
+ *       permit_id: permitToken,
+ *       environment: "production",
+ *       action_type: PRODUCTION_DEPLOY_ACTION,
+ *       issued_at: new Date().toISOString(),
+ *       verified: true,
+ *     },
+ *   } satisfies DeployGateContext,
+ * });
+ * ```
+ */
+interface DeployGateContext {
+    /** Must be `"production"` for the production gate to apply. */
+    environment?: "production" | "staging" | "development";
+    /**
+     * When `true`, all rule failures are shadowed to `allow` (fail-open).
+     * Malformed-timestamp inconsistencies still escalate.
+     * Use for initial rollout before locking enforcement.
+     */
+    pilot_mode?: boolean;
+    /** Must be `true` — confirms an evaluation record exists before proceeding. */
+    evaluation_confirmed?: boolean;
+    /** ISO-8601 timestamp of when evaluation was confirmed. */
+    evaluation_confirmed_at?: string;
+    /** Actor role metadata. `role` must be one of the approved deploy roles. */
+    actorMetadata?: {
+        role?: string;
+    };
+    /** Signed permit claim — required for non-pilot production deployments. */
+    permit?: DeployPermitClaim;
+    /** Override claim — short-circuits all rules when both fields are non-empty. */
+    override?: DeployOverrideClaim;
+    [key: string]: unknown;
+}
+/**
+ * Canonical deploy gate decision codes emitted for `production.deploy`.
+ *
+ * Appears as `deny_code` / `matchedRuleId` on evaluation responses.
+ * Pin dashboards, alerting, and routing logic to these codes — not to
+ * `deny_reason` strings, which may change.
+ */
+type DeployGateDenyCode = "ALLOW" | "DENY_POLICY" | "DENY_AUTHORITY" | "DENY_ENVIRONMENT" | "PERMIT_EXPIRED" | "VERIFY_FAILED" | "ESCALATE_REQUIRED" | "OVERRIDE_APPROVED";
+/** Typed constants for {@link DeployGateDenyCode}. */
+declare const DEPLOY_GATE_CODES: Readonly<{
+    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";
+}>;
+/** Input to {@link AtlaSentClient.deployGate}. */
+interface DeployGateRequest {
+    /** CI/repo actor performing the deployment. Defaults to `ci-deploy-bot`. */
+    agent?: string;
+    /** Protected action. Defaults to `production.deploy`. */
+    action?: typeof PRODUCTION_DEPLOY_ACTION | typeof DEPLOYMENT_PRODUCTION_ACTION | string;
+    /** Typed deploy gate context for `production.deploy`. */
+    context?: DeployGateContext | Record<string, unknown>;
+}
+/** Evidence metadata returned by {@link AtlaSentClient.deployGate}. */
+interface DeployGateEvidence {
+    permitId?: string;
+    permitHash?: string;
+    auditHash?: string;
+    verifiedAt?: string;
+}
+/** Result of the canonical Deploy Gate V1 flow. */
+interface DeployGateResponse {
+    /** True only after evaluate allowed AND `/v1-verify-permit` verified server-side. */
+    allowed: boolean;
+    /** Evaluation response from `POST /v1-evaluate`, when available. */
+    evaluation?: EvaluateResponse;
+    /** Verification response from `POST /v1-verify-permit`, when evaluation allowed. */
+    verification?: VerifyPermitResponse;
+    /** Human-readable block/allow reason. */
+    reason: string;
+    /** Best-effort audit/evidence metadata available to the SDK. */
+    evidence: DeployGateEvidence;
+}
+/** Input to {@link AtlaSentClient.evaluate}. */
+interface EvaluateRequest {
+    /** Identifier of the calling agent (e.g. "clinical-data-agent"). */
+    agent: string;
+    /** The action being authorized (e.g. "modify_patient_record"). */
+    action: string;
+    /** Arbitrary policy context (user, environment, resource IDs). */
+    context?: Record<string, unknown>;
+}
+/**
+ * Slim permit object embedded in {@link EvaluateResponse} when the decision
+ * is `"allow"`. Contains the essential fields needed to act on the permit
+ * immediately without a separate `GET /v1/permits/:id` round-trip.
+ *
+ * Mirrors the `Permit` schema in atlasent-control-plane
+ * `api/src/schemas/permits.ts`.
+ */
+interface EvaluateResponsePermit {
+    id: string;
+    orgId: string;
+    subject: string;
+    scope: string;
+    status: "active" | "revoked" | "expired";
+    /** The evaluation that produced this permit. */
+    evaluationId: string | null;
+    issuedBy: string;
+    revokedBy: string | null;
+    /** ISO-8601 issuance timestamp. */
+    issuedAt: string;
+    revokedAt: string | null;
+    expiresAt: string | null;
+    metadata: Record<string, unknown> | null;
+}
+/** Result of {@link AtlaSentClient.evaluate}. */
+interface EvaluateResponse {
+    /**
+     * Policy decision — canonical 4-value lowercase vocabulary:
+     * `"allow"`, `"deny"`, `"hold"`, or `"escalate"`.
+     *
+     * Previously emitted `"ALLOW"` / `"DENY"` (uppercase, 2-value);
+     * the SDK now normalises all values to lowercase and passes `hold`
+     * and `escalate` through rather than collapsing them to `"DENY"`.
+     *
+     * The `decision_canonical` field carries the same value and is the
+     * recommended field for new code.
+     */
+    decision: Decision;
+    /**
+     * Canonical 4-value decision, byte-identical to the wire.
+     *
+     * One of `"allow"`, `"deny"`, `"hold"`, `"escalate"`. Branch on
+     * this field on new code. `hold` and `escalate` are non-terminal
+     * states that route to a human reviewer / approval signal — they
+     * are not equivalent to a `deny`.
+     */
+    decision_canonical: DecisionCanonical;
+    /**
+     * Server-assigned identifier for this evaluation decision.
+     *
+     * Stable across retries and used as the key for proof retrieval
+     * (`GET /v1/proof/:evaluationId`) and override requests. Also
+     * available as the legacy `permitId` field for backward compatibility.
+     */
+    evaluationId: string;
+    /** Opaque permit identifier, passed to {@link AtlaSentClient.verifyPermit}.
+     *
+     * @deprecated Prefer `evaluationId`. This field is kept for backward
+     * compatibility and points to the same server-assigned ID.
+     */
+    permitId: string;
+    /**
+     * Slim permit object issued when `decision === "allow"`.
+     * `null` on deny, hold, or escalate decisions.
+     *
+     * Mirrors the `Permit` schema from the control-plane.
+     */
+    permit: EvaluateResponsePermit | null;
+    /**
+     * Opaque HMAC-signed permit token issued when `decision === "allow"`.
+     * Pass to `POST /v1/verify-permit` to verify the permit server-side.
+     * `null` on deny, hold, or escalate decisions.
+     */
+    permitToken: string | null;
+    /**
+     * Machine-readable reasons emitted by the policy engine.
+     *
+     * The array may be empty. For deny/hold/escalate decisions the array
+     * typically contains a single human-readable explanation; for allow
+     * decisions it is often empty. Do not parse these strings — use
+     * `decision` for branching.
+     */
+    reasons: string[];
+    /** Human-readable explanation from the policy engine.
+     *
+     * @deprecated Prefer `reasons[0]` or `reasons`. This field is the
+     * first element of `reasons` (or an empty string) for backward compat.
+     */
+    reason: string;
+    /** Hash-chained audit-trail entry (21 CFR Part 11 / GxP-ready). */
+    auditHash: string;
+    /** ISO 8601 timestamp of the decision. */
+    timestamp: string;
+    /**
+     * 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;
+}
+/** Input to {@link AtlaSentClient.verifyPermit}. */
+interface VerifyPermitRequest {
+    /** The permit ID returned by a prior evaluate() call. */
+    permitId: string;
+    /** Optional: re-state the action for cross-check with the server. */
+    action?: string;
+    /** Optional: re-state the agent for cross-check with the server. */
+    agent?: string;
+    /** Optional: re-state the context for cross-check with the server. */
+    context?: Record<string, unknown>;
+    /**
+     * Environment of the permit being verified. Sourced from the evaluate
+     * payload (context.environment → top-level environment → "production").
+     * Required by the server for production permits as of 2026-05-14.
+     * P1-1 fix: withPermit/protect now always populates this field.
+     */
+    environment?: string;
+    /**
+     * SHA-256 hex digest of the recursively key-sorted canonical JSON of the
+     * original evaluate payload. Required by the server for production permits
+     * as of 2026-05-14.
+     * P1-5 fix: withPermit/protect now always computes and sends this field.
+     */
+    execution_hash?: string;
+}
+/**
+ * Result of {@link AtlaSentClient.verifyPermit}.
+ *
+ * @deprecated Use {@link VerifyPermitByIdResponse} via
+ * {@link AtlaSentClient.verifyPermitById} — the canonical REST surface
+ * (`POST /v1/permits/{id}/verify`) returns the unified verification
+ * envelope (`valid`, `verification_type`, `reason`, `verified_at`,
+ * `evidence`) plus the full {@link PermitRecord} fields. Will be
+ * removed in `@atlasent/sdk@3`.
+ */
+interface VerifyPermitResponse {
+    /** `true` when the permit is valid and un-revoked. */
+    verified: boolean;
+    /** Verification outcome string from the server. */
+    outcome: string;
+    /** Verification hash bound to the permit. */
+    permitHash: string;
+    /** ISO 8601 timestamp of the verification. */
+    timestamp: string;
+    /**
+     * 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;
+}
+/**
+ * Result of {@link AtlaSentClient.keySelf} — self-introspection of the API
+ * 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
+ */
+interface ApiKeySelfResponse {
+    /** Server-side UUID of the api_keys row for this key. */
+    keyId: string;
+    /** Organization the key belongs to. */
+    organizationId: string;
+    /** "live" or "test" (or any future environment label the server introduces). */
+    environment: string;
+    /** Granted scopes — e.g. ["evaluate", "audit.read"]. */
+    scopes: string[];
+    /**
+     * Per-key IP allowlist as CIDR strings (e.g. ["10.0.0.0/8"]). `null`
+     * when the key is unrestricted.
+     */
+    allowedCidrs: string[] | null;
+    /** Server-enforced per-minute rate limit for this key. */
+    rateLimitPerMinute: number;
+    /** Client IP as the server observed it (first hop of X-Forwarded-For). */
+    clientIp: string | null;
+    /** Server-stored expiry; `null` means the key does not auto-expire. */
+    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.
+     */
+    rateLimit: RateLimitState | null;
+}
+/**
+ * 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.
+ */
+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.
+ */
+interface AuditExportRequest {
+    /** Comma-joined list of event types to include (e.g. `"evaluate.allow,policy.updated"`). */
+    types?: string;
+    /** Filter to a single actor. */
+    actor_id?: string;
+    /** Inclusive lower bound on `occurred_at` (ISO 8601). */
+    from?: string;
+    /** Inclusive upper bound on `occurred_at` (ISO 8601). */
+    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)`.
+ */
+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}. */
+interface AtlaSentClientOptions {
+    /** Required. Your AtlaSent API key. */
+    apiKey: string;
+    /** API base URL. Defaults to "https://api.atlasent.io". */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Defaults to 10_000. */
+    timeoutMs?: number;
+    /**
+     * Inject a fetch implementation (primarily for testing).
+     * Defaults to `globalThis.fetch`.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Retry policy for transient failures (network errors, timeouts,
+     * 429 rate-limit, 5xx server errors, malformed responses).
+     * Omit to use the default: 4 total attempts, 2 000 ms base, 16 000 ms cap,
+     * full-jitter exponential backoff matching the Python SDK schedule
+     * (2 s → 4 s → 8 s → 16 s).
+     * Pass `{ maxAttempts: 1 }` to disable retries entirely.
+     */
+    retryPolicy?: RetryPolicy;
+}
+/** 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.
+ */
+interface PermitRecord {
+    id: string;
+    org_id: string;
+    actor_id: string;
+    action_id: string;
+    target_id?: string;
+    environment?: string;
+    status: PermitStatus;
+    issued_at: string;
+    expires_at: string;
+    consumed_at?: string | null;
+    revoked_at?: string | null;
+    revoked_by?: string | null;
+    revoke_reason?: string | null;
+    signature?: string;
+    payload_hash?: string | null;
+    decision_id?: 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;
+}
+/** Response from {@link AtlaSentClient.getPermit}. */
+interface GetPermitResponse {
+    permit: PermitRecord;
+    rateLimit: RateLimitState | null;
+}
+/**
+ * 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;
+    rateLimit: RateLimitState | null;
+}
+/**
+ * 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;
+        actor_id?: string;
+        action_id?: string;
+        expires_at?: string;
+        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.
+ * 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;
+
+/** Input to {@link protect}. Same shape as `EvaluateRequest`. */
+interface ProtectRequest {
+    agent: string;
+    action: string;
+    context?: Record<string, unknown>;
+}
+/**
+ * Success return from {@link protect}. The action is authorized
+ * end-to-end — evaluation allowed AND the resulting permit verified.
+ */
+interface Permit {
+    /** Opaque permit / decision identifier. */
+    permitId: string;
+    /** Verification hash bound to the permit. */
+    permitHash: string;
+    /** Audit-trail entry associated with the decision (hash-chained). */
+    auditHash: string;
+    /** Human-readable reason from the policy engine. */
+    reason: string;
+    /** ISO 8601 timestamp of the verification. */
+    timestamp: string;
+}
+/** Configuration for the process-wide singleton used by {@link protect}. */
+interface ConfigureOptions {
+    /** Overrides `ATLASENT_API_KEY` env var. */
+    apiKey?: string;
+    /** Overrides the default `https://api.atlasent.io`. */
+    baseUrl?: string;
+    /** Per-request timeout in ms. */
+    timeoutMs?: number;
+    /** Inject a custom fetch (primarily for tests). */
+    fetch?: typeof fetch;
+    /** Override the retry policy. Pass `{ maxAttempts: 1 }` to disable retries. */
+    retryPolicy?: RetryPolicy;
+}
+/**
+ * Configure the singleton client used by {@link protect}. Optional —
+ * if `ATLASENT_API_KEY` is set in the environment, `protect` works
+ * without any configuration. Calling `configure` again replaces the
+ * singleton; subsequent `protect` calls use the new settings.
+ */
+declare function configure(options: ConfigureOptions): void;
+/**
+ * Run the canonical Deploy Gate V1 helper using the process-wide client.
+ * Defaults to action `production.deploy`; execution is allowed only after
+ * server-side `/v1-evaluate` and `/v1-verify-permit` both pass.
+ */
+declare function deployGate(request?: DeployGateRequest): Promise<DeployGateResponse>;
+/**
+ * Authorize an action end-to-end. On allow, returns a verified
+ * {@link Permit}. On anything else, throws:
+ *
+ * - {@link AtlaSentDeniedError} — policy denied, or the permit
+ *   failed verification. Fail-closed: if this throws, the action
+ *   MUST NOT proceed.
+ * - {@link AtlaSentError} — transport, timeout, auth, rate-limit,
+ *   or server error. Same fail-closed contract: do not proceed.
+ */
+declare function protect(request: ProtectRequest): Promise<Permit>;
+
+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 };