@decionis/agent-safe-pipeline 0.1.3 → 0.2.0

package/dist/decision/DecionisGate.js

@@ -1,108 +1,885 @@
 import { z } from "zod";
 import { AuthorityBaseUrl } from "../http/AuthorityBaseUrl.js";
+import { credentialReader } from "../http/Credential.js";
 import { BoundedResponseBody } from "../http/BoundedResponseBody.js";
+import { userAgent } from "../http/ClientIdentification.js";
 import { CanonicalIntentHasher } from "../intent/CanonicalIntentHasher.js";
 import { FailClosedDecision, } from "./DecisionAuthority.js";
 import { immutableGateDecision } from "./ImmutableGateDecision.js";
-const reasonCode = z
+const boundedIdentifier = z
     .string()
     .min(1)
-    .max(120)
-    .regex(/^[A-Z][A-Z0-9_:-]*$/);
+    .max(200)
+    .refine(hasNoControlCharacters, { message: "IDENTIFIER_INVALID" });
+const intentHash = z.string().regex(/^sha256:[0-9a-f]{64}$/);
+const reasonCodes = z.array(boundedIdentifier).max(50);
+const roleIdentifier = z.string().regex(/^[A-Z][A-Z0-9_]{1,63}$/);
+const ManagedEscalationRequestSchema = z
+    .object({
+    mode: z.literal("MANAGED"),
+    approver: z
+        .object({
+        principal_id: boundedIdentifier.optional(),
+        role_id: roleIdentifier.optional(),
+    })
+        .strict()
+        .refine((approver) => approver.principal_id !== undefined || approver.role_id !== undefined, {
+        message: "MANAGED_ESCALATION_APPROVER_EMPTY",
+    })
+        .optional(),
+    verification_requirements: z
+        .object({
+        methods: z
+            .array(z.enum(["WEBAUTHN", "ACTIVE_LIVENESS"]))
+            .min(1)
+            .max(3)
+            .refine((methods) => new Set(methods).size === methods.length, {
+            message: "MANAGED_ESCALATION_METHOD_DUPLICATE",
+        }),
+        level: z.enum(["STANDARD", "HIGH_CONFIDENCE"]).optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+const managedEscalationStatuses = [
+    "PENDING_PRESENCE",
+    "PRESENCE_REQUESTED",
+    "AWAITING_APPROVER",
+    "PRESENCE_VERIFIED",
+    "REAUTHORIZING",
+    "GRANT_READY",
+    "EXPIRED",
+    "REJECTED",
+    "BLOCKED",
+    "CANCELLED",
+    "FAILED",
+];
+const managedEscalationPendingStatuses = new Set([
+    "PENDING_PRESENCE",
+    "PRESENCE_REQUESTED",
+    "AWAITING_APPROVER",
+    "PRESENCE_VERIFIED",
+    "REAUTHORIZING",
+]);
+const ManagedEscalationWireSchema = z
+    .object({
+    outcome: z.enum(["ESCALATE_PENDING", "ALLOW", "BLOCK", "ERROR"]),
+    escalation_id: boundedIdentifier,
+    intent_id: boundedIdentifier,
+    status: z.enum(managedEscalationStatuses),
+    expires_at: z.string().datetime(),
+    reason_codes: reasonCodes,
+})
+    .strict()
+    .superRefine((value, context) => {
+    const expectedOutcome = value.status === "GRANT_READY"
+        ? "ALLOW"
+        : value.status === "FAILED"
+            ? "ERROR"
+            : managedEscalationPendingStatuses.has(value.status)
+                ? "ESCALATE_PENDING"
+                : "BLOCK";
+    if (value.outcome !== expectedOutcome) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "MANAGED_ESCALATION_STATE_OUTCOME_MISMATCH",
+        });
+    }
+});
+/**
+ * The dossier's verification envelope, as `evaluate-decision` attaches it and
+ * `enforce-and-bind` may: the contract declares the block open, so only the
+ * page a person can open without an account is read from it.
+ */
+const VerificationEnvelopeSchema = z
+    .object({
+    verification_page_url: z.string().url().max(2_000),
+    verification_url: z.string().url().max(2_000).optional(),
+    link_expires_at: z.string().datetime().nullable().optional(),
+})
+    .passthrough();
+/**
+ * Mirrors `ExecutionAuthorityDecision` in the Decionis OpenAPI contract, which
+ * declares `additionalProperties: false`; an undocumented field therefore fails
+ * closed instead of being interpreted as execution semantics.
+ */
 const AuthorityResponseSchema = z
     .object({
-    decision_id: z.string().min(1).max(200),
+    decision_id: boundedIdentifier,
+    chain_id: boundedIdentifier.nullable(),
     status: z.enum(["ALLOW", "BLOCK", "ESCALATE", "REVIEW_REQUIRED", "ERROR"]),
     should_execute: z.boolean(),
-    reason_codes: z.array(reasonCode).max(50),
-    action_hash: z.string().regex(/^sha256:[0-9a-f]{64}$/),
-    execution_token: z
-        .string()
-        .min(1)
-        .max(100 * 1024)
-        .nullable(),
+    reason_codes: reasonCodes,
+    action_hash: intentHash,
+    policy_version: boundedIdentifier.nullable().optional(),
+    mode: z.enum(["SHADOW", "PARALLEL", "ENFORCEMENT"]).nullable().optional(),
+    execution_token: z.string().min(1).max(20_000).nullable(),
     execution_token_expires_at: z.string().datetime().nullable(),
-    dossier_id: z.string().min(1).max(200).nullable(),
+    dossier_id: boundedIdentifier.nullable(),
+    dossier_sha256: boundedIdentifier.nullable().optional(),
+    dossier_url: z.string().min(1).max(2_000).nullable(),
+    approval_request_id: boundedIdentifier.nullable().optional(),
+    ledger_entry_id: boundedIdentifier.nullable().optional(),
+    authority_classification: z.enum(["AUTHORITATIVE", "OBSERVATIONAL"]).optional(),
+    execution_eligible: z.boolean().optional(),
+    execution_binding_digest: intentHash.nullable().optional(),
+    execution_token_jti: boundedIdentifier.nullable().optional(),
+    execution_token_key_id: boundedIdentifier.nullable().optional(),
+    managed_escalation: ManagedEscalationWireSchema.nullable().optional(),
+    verification: VerificationEnvelopeSchema.nullable().optional(),
+})
+    .strict();
+const ManagedEscalationStatusResponseSchema = z
+    .object({
+    escalation_id: boundedIdentifier,
+    intent_id: boundedIdentifier,
+    action_hash: intentHash,
+    status: z.enum(managedEscalationStatuses),
+    outcome: z.enum(["ESCALATE_PENDING", "ALLOW", "BLOCK", "ERROR"]),
+    expires_at: z.string().datetime(),
+    reason_codes: reasonCodes,
+    decision: AuthorityResponseSchema.nullable(),
 })
     .strict();
+const WAITING_STATUS_RANK = Object.freeze({
+    PENDING_PRESENCE: 0,
+    PRESENCE_REQUESTED: 1,
+    AWAITING_APPROVER: 2,
+    PRESENCE_VERIFIED: 3,
+    REAUTHORIZING: 4,
+});
 const MAX_RESPONSE_BYTES = 100 * 1024;
+const DEFAULT_MANAGED_INITIAL_DELAY_MS = 500;
+const DEFAULT_MANAGED_MAX_DELAY_MS = 5_000;
+const MAX_MANAGED_DELAY_MS = 5_000;
+const MAX_MANAGED_ATTEMPTS = 1_000;
 export class DecionisGate {
+    evaluationMode;
     baseUrl;
     apiKey;
     timeoutMs;
     fetchImpl;
+    userAgent;
+    pendingAuthorizationWaits = new Map();
     constructor(options) {
         this.baseUrl = AuthorityBaseUrl.normalize(options.baseUrl, options.allowInsecureLoopback === true);
-        this.apiKey = options.apiKey;
+        this.apiKey = credentialReader(options.apiKey);
         this.timeoutMs = Math.min(Math.max(options.timeoutMs ?? 4_000, 1), 15_000);
         this.fetchImpl = options.fetch ?? fetch;
+        this.userAgent = userAgent(options.source);
+        const mode = options.mode ?? "ENFORCEMENT";
+        if (mode !== "ENFORCEMENT" && mode !== "SHADOW") {
+            throw new Error("DECIONIS_GATE_MODE_INVALID");
+        }
+        this.evaluationMode = mode;
     }
-    async evaluate(captured, evidence) {
+    async evaluate(captured, evidence, options = {}) {
+        // An intent past its expiry is refused before the authority is asked: no
+        // grant could outlive it, and a decision about it would only record a
+        // dead intent.
+        if (!(Date.parse(captured.intent.expiresAt) > Date.now())) {
+            return FailClosedDecision.create(captured.intentHash, "INTENT_EXPIRED");
+        }
+        const escalation = this.validEscalationRequest(options.escalation);
+        if (escalation === null) {
+            return FailClosedDecision.create(captured.intentHash, "MANAGED_ESCALATION_REQUEST_INVALID");
+        }
+        if (escalation !== undefined && this.evaluationMode !== "ENFORCEMENT") {
+            return FailClosedDecision.create(captured.intentHash, "MANAGED_ESCALATION_SHADOW_FORBIDDEN");
+        }
+        if (escalation !== undefined && evidence !== undefined) {
+            return FailClosedDecision.create(captured.intentHash, "MANAGED_ESCALATION_EVIDENCE_FORBIDDEN");
+        }
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
         try {
             const response = await this.fetchImpl(`${this.baseUrl}/v1/authority/enforce-and-bind`, {
                 method: "POST",
                 headers: {
-                    authorization: `Bearer ${this.apiKey}`,
+                    authorization: `Bearer ${this.apiKey()}`,
                     "content-type": "application/json",
-                    "idempotency-key": captured.intent.idempotencyKey,
+                    // The contract requires the header to equal the signed intent_id;
+                    // intent_id is the authority's grant-issuance boundary.
+                    "idempotency-key": captured.intent.intentId,
+                    "user-agent": this.userAgent,
                 },
                 body: JSON.stringify({
                     ...CanonicalIntentHasher.bindingOf(captured.intent),
                     intent_hash: captured.intentHash,
-                    mode: "ENFORCEMENT",
+                    mode: this.evaluationMode,
                     ...(evidence === undefined ? {} : { evidence }),
+                    ...(escalation === undefined ? {} : { escalation }),
                 }),
                 signal: controller.signal,
             });
-            if (!response.ok) {
-                return FailClosedDecision.create(captured.intentHash, "AUTHORITY_REQUEST_FAILED");
-            }
             const text = await BoundedResponseBody.read(response, MAX_RESPONSE_BYTES);
             if (text === null) {
                 return FailClosedDecision.create(captured.intentHash, "AUTHORITY_RESPONSE_TOO_LARGE");
             }
+            if (!response.ok) {
+                return DecionisGate.failedResponse(captured, text);
+            }
             const parsed = AuthorityResponseSchema.parse(JSON.parse(text));
-            if (parsed.action_hash !== captured.intentHash) {
-                return FailClosedDecision.create(captured.intentHash, "AUTHORITY_BINDING_MISMATCH");
-            }
-            const verdict = parsed.status === "ALLOW"
-                ? "ALLOW"
-                : parsed.status === "ESCALATE" || parsed.status === "REVIEW_REQUIRED"
-                    ? "ESCALATE"
-                    : "BLOCK";
-            const canExecute = verdict === "ALLOW" &&
-                parsed.should_execute &&
-                parsed.dossier_id !== null &&
-                parsed.execution_token !== null &&
-                parsed.execution_token_expires_at !== null &&
-                Date.parse(parsed.execution_token_expires_at) > Date.now() &&
-                Date.parse(parsed.execution_token_expires_at) <= Date.parse(captured.intent.expiresAt);
-            if (verdict === "ALLOW" && !canExecute) {
-                return FailClosedDecision.create(captured.intentHash, "AUTHORITY_GRANT_MISSING");
+            const managed = this.initialManagedState(captured, parsed, escalation);
+            if (managed.reasonCode !== undefined) {
+                return FailClosedDecision.create(captured.intentHash, managed.reasonCode);
+            }
+            return this.decisionFromResponse(captured, parsed, evidence, managed.state);
+        }
+        catch {
+            return FailClosedDecision.create(captured.intentHash, "AUTHORITY_UNAVAILABLE");
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    /** Performs one authenticated, read-only status lookup against Decionis. */
+    async getManagedEscalationStatus(captured, escalation, options = {}) {
+        const expectedFailure = this.expectedStateFailure(captured, escalation);
+        if (expectedFailure !== null) {
+            return this.failedManagedStatus(captured, escalation, expectedFailure);
+        }
+        const now = DecionisGate.clockNow(options.clock ?? Date.now);
+        if (now === null) {
+            return this.failedManagedStatus(captured, escalation, "MANAGED_ESCALATION_CLOCK_INVALID");
+        }
+        const deadline = this.managedDeadline(captured, escalation);
+        if (deadline === null) {
+            return this.failedManagedStatus(captured, escalation, "MANAGED_ESCALATION_EXPIRY_INVALID");
+        }
+        if (now >= deadline)
+            return this.expiredManagedStatus(captured, escalation);
+        if (options.signal?.aborted === true) {
+            return this.failedManagedStatus(captured, escalation, "MANAGED_ESCALATION_ABORTED");
+        }
+        const controller = new AbortController();
+        let callerAborted = false;
+        const onAbort = () => {
+            callerAborted = true;
+            controller.abort();
+        };
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        if (DecionisGate.signalAborted(options.signal))
+            onAbort();
+        const timeout = setTimeout(() => controller.abort(), Math.max(1, Math.min(this.timeoutMs, deadline - now)));
+        try {
+            const response = await this.fetchImpl(`${this.baseUrl}/v1/authority/escalations/${encodeURIComponent(escalation.escalationId)}`, {
+                method: "GET",
+                headers: { authorization: `Bearer ${this.apiKey()}`, "user-agent": this.userAgent },
+                signal: controller.signal,
+            });
+            const text = await BoundedResponseBody.read(response, MAX_RESPONSE_BYTES);
+            if (text === null) {
+                return this.failedManagedStatus(captured, escalation, "MANAGED_ESCALATION_RESPONSE_TOO_LARGE");
+            }
+            if (!response.ok) {
+                return this.failedManagedStatus(captured, escalation, "MANAGED_ESCALATION_STATUS_FAILED");
+            }
+            let body;
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                return this.failedManagedStatus(captured, escalation, "MANAGED_ESCALATION_RESPONSE_INVALID");
+            }
+            const result = ManagedEscalationStatusResponseSchema.safeParse(body);
+            if (!result.success) {
+                return this.failedManagedStatus(captured, escalation, "MANAGED_ESCALATION_RESPONSE_INVALID");
+            }
+            const parsed = result.data;
+            const mismatch = this.statusBindingFailure(captured, escalation, parsed);
+            if (mismatch !== null)
+                return this.failedManagedStatus(captured, escalation, mismatch);
+            const after = DecionisGate.clockNow(options.clock ?? Date.now);
+            if (after === null) {
+                return this.failedManagedStatus(captured, escalation, "MANAGED_ESCALATION_CLOCK_INVALID");
+            }
+            if (after >= deadline)
+                return this.expiredManagedStatus(captured, escalation);
+            return this.statusResult(captured, parsed);
+        }
+        catch {
+            if (callerAborted) {
+                return this.failedManagedStatus(captured, escalation, "MANAGED_ESCALATION_ABORTED");
+            }
+            const after = DecionisGate.clockNow(options.clock ?? Date.now);
+            if (after !== null && after >= deadline) {
+                return this.expiredManagedStatus(captured, escalation);
+            }
+            return this.failedManagedStatus(captured, escalation, "MANAGED_ESCALATION_STATUS_FAILED");
+        }
+        finally {
+            clearTimeout(timeout);
+            options.signal?.removeEventListener("abort", onAbort);
+        }
+    }
+    /**
+     * Waits only on Decionis. Presence credentials, invitation locators, and
+     * receipt evidence never cross this client boundary in managed mode.
+     */
+    async waitForAuthorization(captured, pendingDecision, options = {}) {
+        const escalation = pendingDecision.managedEscalation;
+        if (escalation === undefined ||
+            pendingDecision.verdict !== "ESCALATE" ||
+            pendingDecision.authorization !== null ||
+            pendingDecision.intentHash !== captured.intentHash ||
+            !DecionisGate.validManagedStateSemantics(escalation) ||
+            this.expectedStateFailure(captured, escalation) !== null) {
+            return FailClosedDecision.create(captured.intentHash, "MANAGED_ESCALATION_REFERENCE_INVALID");
+        }
+        const configuration = DecionisGate.waitConfiguration(options);
+        if (configuration === null) {
+            return this.failedWaitDecision(captured, pendingDecision, escalation, "MANAGED_ESCALATION_POLLING_OPTIONS_INVALID");
+        }
+        // Default waits for the same exact binding share one read-only poll loop.
+        // Custom scheduling or cancellation stays caller-local.
+        if (Object.keys(options).length === 0) {
+            const key = `${captured.intentHash}\u0000${escalation.escalationId}`;
+            const existing = this.pendingAuthorizationWaits.get(key);
+            if (existing !== undefined)
+                return await existing;
+            const wait = this.waitForAuthorizationInternal(captured, pendingDecision, escalation, configuration, options.signal).finally(() => this.pendingAuthorizationWaits.delete(key));
+            this.pendingAuthorizationWaits.set(key, wait);
+            return await wait;
+        }
+        return await this.waitForAuthorizationInternal(captured, pendingDecision, escalation, configuration, options.signal);
+    }
+    async waitForAuthorizationInternal(captured, pendingDecision, escalation, configuration, signal) {
+        const deadline = this.managedDeadline(captured, escalation);
+        if (deadline === null) {
+            return this.failedWaitDecision(captured, pendingDecision, escalation, "MANAGED_ESCALATION_EXPIRY_INVALID");
+        }
+        let lastStatus = DecionisGate.isPendingStatus(escalation.status)
+            ? escalation.status
+            : undefined;
+        for (let attempt = 0; configuration.maxAttempts === null || attempt < configuration.maxAttempts; attempt += 1) {
+            const boundary = this.waitBoundaryFailure(configuration.clock, deadline, signal);
+            if (boundary !== null) {
+                return boundary === "INTENT_EXPIRED"
+                    ? this.expiredWaitDecision(captured, pendingDecision, escalation)
+                    : this.failedWaitDecision(captured, pendingDecision, escalation, boundary);
+            }
+            const status = await this.getManagedEscalationStatus(captured, escalation, {
+                ...(signal === undefined ? {} : { signal }),
+                clock: configuration.clock,
+            });
+            const afterLookup = this.waitBoundaryFailure(configuration.clock, deadline, signal);
+            if (afterLookup !== null) {
+                return afterLookup === "INTENT_EXPIRED"
+                    ? this.expiredWaitDecision(captured, pendingDecision, escalation)
+                    : this.failedWaitDecision(captured, pendingDecision, escalation, afterLookup);
             }
+            if (!DecionisGate.isPendingStatus(escalation.status) && status.status !== escalation.status) {
+                return this.failedWaitDecision(captured, pendingDecision, escalation, "MANAGED_ESCALATION_STATE_REGRESSION");
+            }
+            if (status.status === "GRANT_READY")
+                return status.decision;
+            if (status.outcome !== "ESCALATE_PENDING") {
+                return this.terminalWaitDecision(captured, pendingDecision, status);
+            }
+            if (lastStatus === undefined ||
+                WAITING_STATUS_RANK[status.status] < WAITING_STATUS_RANK[lastStatus]) {
+                return this.failedWaitDecision(captured, pendingDecision, escalation, "MANAGED_ESCALATION_STATE_REGRESSION");
+            }
+            lastStatus = status.status;
+            if (configuration.maxAttempts !== null && attempt + 1 >= configuration.maxAttempts) {
+                return this.failedWaitDecision(captured, pendingDecision, escalation, "MANAGED_ESCALATION_TIMEOUT");
+            }
+            const delay = DecionisGate.backoffDelay(configuration, attempt);
+            if (delay === null) {
+                return this.failedWaitDecision(captured, pendingDecision, escalation, "MANAGED_ESCALATION_POLLING_RANDOM_INVALID");
+            }
+            const now = DecionisGate.clockNow(configuration.clock);
+            if (now === null) {
+                return this.failedWaitDecision(captured, pendingDecision, escalation, "MANAGED_ESCALATION_CLOCK_INVALID");
+            }
+            const remaining = deadline - now;
+            if (remaining <= 0)
+                return this.expiredWaitDecision(captured, pendingDecision, escalation);
+            const slept = await DecionisGate.boundedSleep(configuration.sleep, Math.min(delay, remaining), remaining, signal);
+            if (slept !== null) {
+                return slept === "INTENT_EXPIRED"
+                    ? this.expiredWaitDecision(captured, pendingDecision, escalation)
+                    : this.failedWaitDecision(captured, pendingDecision, escalation, slept);
+            }
+        }
+        return this.failedWaitDecision(captured, pendingDecision, escalation, "MANAGED_ESCALATION_TIMEOUT");
+    }
+    decisionFromResponse(captured, parsed, evidence, managedEscalation) {
+        if (parsed.action_hash !== captured.intentHash) {
+            return FailClosedDecision.create(captured.intentHash, "AUTHORITY_BINDING_MISMATCH");
+        }
+        const mode = parsed.mode ?? null;
+        if (mode !== null && mode !== this.evaluationMode) {
+            return FailClosedDecision.create(captured.intentHash, "AUTHORITY_MODE_MISMATCH");
+        }
+        const verdict = parsed.status === "ALLOW"
+            ? "ALLOW"
+            : parsed.status === "ESCALATE" || parsed.status === "REVIEW_REQUIRED"
+                ? "ESCALATE"
+                : "BLOCK";
+        const verificationUrl = parsed.verification?.verification_page_url;
+        const verification = verificationUrl === undefined ? {} : { verificationUrl };
+        if (this.evaluationMode === "SHADOW") {
             return immutableGateDecision({
                 verdict,
                 decisionId: parsed.decision_id,
                 dossierId: parsed.dossier_id,
                 intentHash: parsed.action_hash,
                 reasonCodes: parsed.reason_codes,
-                authorization: canExecute
-                    ? {
-                        token: parsed.execution_token,
-                        expiresAt: parsed.execution_token_expires_at,
-                    }
-                    : null,
+                authorization: null,
                 failClosed: parsed.status === "ERROR",
+                ...verification,
+                ...(evidence === undefined ? {} : { evidence }),
+            });
+        }
+        const canExecute = verdict === "ALLOW" &&
+            parsed.should_execute &&
+            mode === "ENFORCEMENT" &&
+            (parsed.authority_classification === undefined ||
+                parsed.authority_classification === "AUTHORITATIVE") &&
+            (parsed.execution_eligible === undefined || parsed.execution_eligible === true) &&
+            (parsed.execution_binding_digest === undefined || parsed.execution_binding_digest !== null) &&
+            (parsed.execution_token_jti === undefined || parsed.execution_token_jti !== null) &&
+            (parsed.execution_token_key_id === undefined || parsed.execution_token_key_id !== null) &&
+            parsed.dossier_id !== null &&
+            parsed.execution_token !== null &&
+            parsed.execution_token_expires_at !== null &&
+            Date.parse(parsed.execution_token_expires_at) > Date.now() &&
+            Date.parse(parsed.execution_token_expires_at) <= Date.parse(captured.intent.expiresAt);
+        if (verdict === "ALLOW" && !canExecute) {
+            return FailClosedDecision.create(captured.intentHash, "AUTHORITY_GRANT_MISSING");
+        }
+        return immutableGateDecision({
+            verdict,
+            decisionId: parsed.decision_id,
+            dossierId: parsed.dossier_id,
+            intentHash: parsed.action_hash,
+            reasonCodes: parsed.reason_codes,
+            authorization: canExecute
+                ? {
+                    token: parsed.execution_token,
+                    expiresAt: parsed.execution_token_expires_at,
+                }
+                : null,
+            failClosed: parsed.status === "ERROR",
+            ...verification,
+            ...(evidence === undefined ? {} : { evidence }),
+            ...(managedEscalation === undefined ? {} : { managedEscalation }),
+        });
+    }
+    initialManagedState(captured, response, requested) {
+        const managed = response.managed_escalation ?? undefined;
+        if (managed === undefined) {
+            return requested !== undefined &&
+                (response.status === "ESCALATE" || response.status === "REVIEW_REQUIRED")
+                ? { reasonCode: "MANAGED_ESCALATION_MISSING" }
+                : {};
+        }
+        if (requested === undefined)
+            return { reasonCode: "MANAGED_ESCALATION_UNEXPECTED" };
+        if (response.status !== "ESCALATE" ||
+            response.should_execute ||
+            response.execution_token !== null ||
+            response.execution_token_expires_at !== null ||
+            response.execution_eligible === true ||
+            response.execution_binding_digest != null ||
+            response.execution_token_jti != null ||
+            response.execution_token_key_id != null) {
+            return { reasonCode: "MANAGED_ESCALATION_PENDING_GRANT_FORBIDDEN" };
+        }
+        const state = DecionisGate.managedStateFromWire(managed);
+        const failure = this.expectedStateFailure(captured, state);
+        return failure === null ? { state } : { reasonCode: failure };
+    }
+    statusResult(captured, response) {
+        const base = {
+            escalationId: response.escalation_id,
+            intentId: response.intent_id,
+            actionHash: response.action_hash,
+            expiresAt: response.expires_at,
+            reasonCodes: Object.freeze([...response.reason_codes]),
+        };
+        if (DecionisGate.isPendingStatus(response.status)) {
+            if (response.outcome !== "ESCALATE_PENDING" || response.decision !== null) {
+                return this.failedStatusFromBase(base, "MANAGED_ESCALATION_RESPONSE_INVALID");
+            }
+            return Object.freeze({
+                ...base,
+                status: response.status,
+                outcome: "ESCALATE_PENDING",
+                decision: null,
+            });
+        }
+        if (response.status === "GRANT_READY") {
+            if (response.outcome !== "ALLOW" ||
+                response.decision === null ||
+                response.decision.managed_escalation != null) {
+                return this.failedStatusFromBase(base, "MANAGED_ESCALATION_GRANT_INVALID");
+            }
+            const state = DecionisGate.managedStateFromStatus(response);
+            const decision = this.decisionFromResponse(captured, response.decision, undefined, state);
+            if (decision.verdict !== "ALLOW" || decision.authorization === null || decision.failClosed) {
+                return this.failedStatusFromBase(base, decision.reasonCodes[0] ?? "MANAGED_ESCALATION_GRANT_INVALID");
+            }
+            return Object.freeze({
+                ...base,
+                status: "GRANT_READY",
+                outcome: "ALLOW",
+                decision,
             });
         }
+        if (response.status === "FAILED") {
+            if (response.outcome !== "ERROR" || response.decision !== null) {
+                return this.failedStatusFromBase(base, "MANAGED_ESCALATION_RESPONSE_INVALID");
+            }
+            return Object.freeze({ ...base, status: "FAILED", outcome: "ERROR", decision: null });
+        }
+        if (response.outcome !== "BLOCK" || response.decision !== null) {
+            return this.failedStatusFromBase(base, "MANAGED_ESCALATION_RESPONSE_INVALID");
+        }
+        return Object.freeze({
+            ...base,
+            status: response.status,
+            outcome: "BLOCK",
+            decision: null,
+        });
+    }
+    expectedStateFailure(captured, escalation) {
+        if (!DecionisGate.isBoundedIdentifier(escalation.escalationId)) {
+            return "MANAGED_ESCALATION_ID_INVALID";
+        }
+        if (escalation.intentId !== captured.intent.intentId) {
+            return "MANAGED_ESCALATION_INTENT_MISMATCH";
+        }
+        const expiresAt = Date.parse(escalation.expiresAt);
+        const intentExpiresAt = Date.parse(captured.intent.expiresAt);
+        if (!Number.isFinite(expiresAt) ||
+            !Number.isFinite(intentExpiresAt) ||
+            expiresAt > intentExpiresAt ||
+            expiresAt <= Date.parse(captured.intent.capturedAt)) {
+            return "MANAGED_ESCALATION_EXPIRY_INVALID";
+        }
+        return null;
+    }
+    statusBindingFailure(captured, expected, actual) {
+        if (actual.escalation_id !== expected.escalationId) {
+            return "MANAGED_ESCALATION_ID_MISMATCH";
+        }
+        if (actual.intent_id !== expected.intentId || actual.intent_id !== captured.intent.intentId) {
+            return "MANAGED_ESCALATION_INTENT_MISMATCH";
+        }
+        if (actual.action_hash !== captured.intentHash)
+            return "AUTHORITY_BINDING_MISMATCH";
+        if (actual.expires_at !== expected.expiresAt)
+            return "MANAGED_ESCALATION_EXPIRY_MISMATCH";
+        return null;
+    }
+    managedDeadline(captured, escalation) {
+        const intentExpiresAt = Date.parse(captured.intent.expiresAt);
+        const escalationExpiresAt = Date.parse(escalation.expiresAt);
+        return Number.isFinite(intentExpiresAt) && Number.isFinite(escalationExpiresAt)
+            ? Math.min(intentExpiresAt, escalationExpiresAt)
+            : null;
+    }
+    waitBoundaryFailure(clock, deadline, signal) {
+        if (signal?.aborted === true)
+            return "MANAGED_ESCALATION_ABORTED";
+        const now = DecionisGate.clockNow(clock);
+        if (now === null)
+            return "MANAGED_ESCALATION_CLOCK_INVALID";
+        return now >= deadline ? "INTENT_EXPIRED" : null;
+    }
+    terminalWaitDecision(captured, pending, status) {
+        const fallback = status.status === "EXPIRED"
+            ? ["INTENT_EXPIRED", "RECAPTURE_REQUIRED"]
+            : status.status === "REJECTED"
+                ? ["PRESENCE_REJECTED"]
+                : status.status === "BLOCKED"
+                    ? ["REAUTHORIZATION_BLOCKED"]
+                    : status.status === "CANCELLED"
+                        ? ["CANCELLED"]
+                        : ["MANAGED_ESCALATION_FAILED"];
+        const codes = status.reasonCodes.length === 0 ? fallback : status.reasonCodes;
+        return immutableGateDecision({
+            verdict: "BLOCK",
+            decisionId: pending.decisionId,
+            dossierId: pending.dossierId,
+            intentHash: captured.intentHash,
+            reasonCodes: codes,
+            authorization: null,
+            failClosed: status.outcome === "ERROR",
+            managedEscalation: DecionisGate.managedStateFromStatusResult(status),
+        });
+    }
+    expiredWaitDecision(captured, pending, escalation) {
+        return immutableGateDecision({
+            verdict: "BLOCK",
+            decisionId: pending.decisionId,
+            dossierId: pending.dossierId,
+            intentHash: captured.intentHash,
+            reasonCodes: ["INTENT_EXPIRED", "RECAPTURE_REQUIRED"],
+            authorization: null,
+            failClosed: false,
+            managedEscalation: {
+                ...escalation,
+                status: "EXPIRED",
+                outcome: "BLOCK",
+                reasonCodes: ["INTENT_EXPIRED", "RECAPTURE_REQUIRED"],
+            },
+        });
+    }
+    failedWaitDecision(captured, pending, escalation, reasonCode) {
+        return immutableGateDecision({
+            verdict: "BLOCK",
+            decisionId: pending.decisionId,
+            dossierId: pending.dossierId,
+            intentHash: captured.intentHash,
+            reasonCodes: [reasonCode],
+            authorization: null,
+            failClosed: true,
+            managedEscalation: {
+                ...escalation,
+                status: "FAILED",
+                outcome: "ERROR",
+                reasonCodes: [reasonCode],
+            },
+        });
+    }
+    failedManagedStatus(captured, escalation, reasonCode) {
+        return this.failedStatusFromBase({
+            escalationId: escalation.escalationId,
+            intentId: escalation.intentId,
+            actionHash: captured.intentHash,
+            expiresAt: escalation.expiresAt,
+            reasonCodes: Object.freeze([reasonCode]),
+        }, reasonCode);
+    }
+    expiredManagedStatus(captured, escalation) {
+        return Object.freeze({
+            escalationId: escalation.escalationId,
+            intentId: escalation.intentId,
+            actionHash: captured.intentHash,
+            expiresAt: escalation.expiresAt,
+            reasonCodes: Object.freeze(["INTENT_EXPIRED", "RECAPTURE_REQUIRED"]),
+            status: "EXPIRED",
+            outcome: "BLOCK",
+            decision: null,
+        });
+    }
+    failedStatusFromBase(base, reasonCode) {
+        return Object.freeze({
+            ...base,
+            reasonCodes: Object.freeze([reasonCode]),
+            status: "FAILED",
+            outcome: "ERROR",
+            decision: null,
+        });
+    }
+    validEscalationRequest(value) {
+        if (value === undefined)
+            return undefined;
+        const parsed = ManagedEscalationRequestSchema.safeParse(value);
+        if (!parsed.success)
+            return null;
+        return {
+            mode: parsed.data.mode,
+            ...(parsed.data.approver === undefined
+                ? {}
+                : {
+                    approver: {
+                        ...(parsed.data.approver.principal_id === undefined
+                            ? {}
+                            : { principal_id: parsed.data.approver.principal_id }),
+                        ...(parsed.data.approver.role_id === undefined
+                            ? {}
+                            : { role_id: parsed.data.approver.role_id }),
+                    },
+                }),
+            ...(parsed.data.verification_requirements === undefined
+                ? {}
+                : {
+                    verification_requirements: {
+                        methods: parsed.data.verification_requirements.methods,
+                        ...(parsed.data.verification_requirements.level === undefined
+                            ? {}
+                            : { level: parsed.data.verification_requirements.level }),
+                    },
+                }),
+        };
+    }
+    static managedStateFromWire(value) {
+        return {
+            escalationId: value.escalation_id,
+            intentId: value.intent_id,
+            status: value.status,
+            outcome: value.outcome,
+            expiresAt: value.expires_at,
+            reasonCodes: value.reason_codes,
+        };
+    }
+    static managedStateFromStatus(value) {
+        return {
+            escalationId: value.escalation_id,
+            intentId: value.intent_id,
+            status: value.status,
+            outcome: value.outcome,
+            expiresAt: value.expires_at,
+            reasonCodes: value.reason_codes,
+        };
+    }
+    static managedStateFromStatusResult(value) {
+        return {
+            escalationId: value.escalationId,
+            intentId: value.intentId,
+            status: value.status,
+            outcome: value.outcome,
+            expiresAt: value.expiresAt,
+            reasonCodes: value.reasonCodes,
+        };
+    }
+    static isPendingStatus(status) {
+        return Object.hasOwn(WAITING_STATUS_RANK, status);
+    }
+    static validManagedStateSemantics(state) {
+        if (DecionisGate.isPendingStatus(state.status)) {
+            return state.outcome === "ESCALATE_PENDING";
+        }
+        if (state.status === "GRANT_READY")
+            return state.outcome === "ALLOW";
+        if (state.status === "FAILED")
+            return state.outcome === "ERROR";
+        return state.outcome === "BLOCK";
+    }
+    static waitConfiguration(options) {
+        const maxAttempts = options.maxAttempts ?? null;
+        const initialDelayMs = options.initialDelayMs ?? DEFAULT_MANAGED_INITIAL_DELAY_MS;
+        const maxDelayMs = options.maxDelayMs ?? DEFAULT_MANAGED_MAX_DELAY_MS;
+        if ((maxAttempts !== null &&
+            (!Number.isInteger(maxAttempts) ||
+                maxAttempts < 1 ||
+                maxAttempts > MAX_MANAGED_ATTEMPTS)) ||
+            !Number.isInteger(initialDelayMs) ||
+            initialDelayMs < 1 ||
+            initialDelayMs > MAX_MANAGED_DELAY_MS ||
+            !Number.isInteger(maxDelayMs) ||
+            maxDelayMs < initialDelayMs ||
+            maxDelayMs > MAX_MANAGED_DELAY_MS ||
+            (options.clock !== undefined && typeof options.clock !== "function") ||
+            (options.sleep !== undefined && typeof options.sleep !== "function") ||
+            (options.random !== undefined && typeof options.random !== "function")) {
+            return null;
+        }
+        return {
+            maxAttempts,
+            initialDelayMs,
+            maxDelayMs,
+            clock: options.clock ?? Date.now,
+            sleep: options.sleep ?? DecionisGate.sleep,
+            random: options.random ?? Math.random,
+        };
+    }
+    static backoffDelay(configuration, attempt) {
+        let random;
+        try {
+            random = configuration.random();
+        }
         catch {
-            return FailClosedDecision.create(captured.intentHash, "AUTHORITY_UNAVAILABLE");
+            return null;
         }
-        finally {
-            clearTimeout(timeout);
+        if (!Number.isFinite(random) || random < 0 || random > 1)
+            return null;
+        const exponential = configuration.initialDelayMs * 2 ** Math.min(attempt, 30);
+        const capped = Math.min(exponential, configuration.maxDelayMs);
+        return Math.max(1, Math.floor(capped * (0.5 + random * 0.5)));
+    }
+    static async boundedSleep(sleep, delayMs, remainingMs, signal) {
+        if (signal?.aborted === true)
+            return "MANAGED_ESCALATION_ABORTED";
+        return await new Promise((resolve) => {
+            let settled = false;
+            const settle = (reason) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                resolve(reason);
+            };
+            const onAbort = () => settle("MANAGED_ESCALATION_ABORTED");
+            const timer = setTimeout(() => settle("INTENT_EXPIRED"), remainingMs);
+            signal?.addEventListener("abort", onAbort, { once: true });
+            void Promise.resolve()
+                .then(async () => await sleep(delayMs, signal))
+                .then(() => settle(null), () => settle(signal?.aborted === true
+                ? "MANAGED_ESCALATION_ABORTED"
+                : "MANAGED_ESCALATION_UNAVAILABLE"));
+        });
+    }
+    static async sleep(delayMs, signal) {
+        await new Promise((resolve, reject) => {
+            if (signal?.aborted === true) {
+                reject(new Error("MANAGED_ESCALATION_ABORTED"));
+                return;
+            }
+            const onAbort = () => {
+                clearTimeout(timer);
+                reject(new Error("MANAGED_ESCALATION_ABORTED"));
+            };
+            const timer = setTimeout(() => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve();
+            }, delayMs);
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
+    static clockNow(clock) {
+        try {
+            const now = clock();
+            return Number.isFinite(now) ? now : null;
         }
+        catch {
+            return null;
+        }
+    }
+    static signalAborted(signal) {
+        return signal?.aborted === true;
+    }
+    static isBoundedIdentifier(value) {
+        return value.length > 0 && value.length <= 200 && hasNoControlCharacters(value);
+    }
+    /**
+     * The contract returns an `ERROR` decision body on 409 and 503 so the
+     * refusal is evidence-bearing. Anything else fails closed generically.
+     */
+    static failedResponse(captured, text) {
+        try {
+            const parsed = AuthorityResponseSchema.parse(JSON.parse(text));
+            if (parsed.status !== "ERROR" || parsed.action_hash !== captured.intentHash) {
+                return FailClosedDecision.create(captured.intentHash, "AUTHORITY_REQUEST_FAILED");
+            }
+            return immutableGateDecision({
+                verdict: "BLOCK",
+                decisionId: parsed.decision_id,
+                dossierId: parsed.dossier_id,
+                intentHash: captured.intentHash,
+                reasonCodes: parsed.reason_codes.length === 0 ? ["AUTHORITY_REQUEST_FAILED"] : parsed.reason_codes,
+                authorization: null,
+                failClosed: true,
+            });
+        }
+        catch {
+            return FailClosedDecision.create(captured.intentHash, "AUTHORITY_REQUEST_FAILED");
+        }
+    }
+}
+function hasNoControlCharacters(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        if (codeUnit <= 0x1f || codeUnit === 0x7f)
+            return false;
     }
+    return true;
 }
 //# sourceMappingURL=DecionisGate.js.map