@decionis/agent-safe-pipeline 0.1.4 → 0.3.0

package/dist/decision/ImmutableGateDecision.js

@@ -21,6 +21,14 @@ export function immutableGateDecision(decision) {
                     reasonCodes: Object.freeze([...decision.managedEscalation.reasonCodes]),
                 }),
             }),
+        ...(decision.hosted === undefined
+            ? {}
+            : {
+                hosted: Object.freeze({
+                    ...decision.hosted,
+                    reasonCodes: Object.freeze([...decision.hosted.reasonCodes]),
+                }),
+            }),
     });
 }
 //# sourceMappingURL=ImmutableGateDecision.js.map

package/dist/decision/ImmutableGateDecision.js.map

@@ -1 +1 @@
-{"version":3,"file":"ImmutableGateDecision.js","sourceRoot":"","sources":["../../src/decision/ImmutableGateDecision.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,qBAAqB,CAAC,QAAsB;IAC1D,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,QAAQ;QACX,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;QACrD,aAAa,EACX,QAAQ,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,QAAQ,CAAC,aAAa,EAAE,CAAC;QACvF,GAAG,CAAC,QAAQ,CAAC,QAAQ,KAAK,SAAS;YACjC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC;oBACtB,GAAG,QAAQ,CAAC,QAAQ;oBACpB,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,aAAa,KAAK,SAAS;wBAC/C,CAAC,CAAC,EAAE;wBACJ,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,QAAQ,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC,EAAE,CAAC;iBAC9E,CAAC;aACH,CAAC;QACN,GAAG,CAAC,QAAQ,CAAC,iBAAiB,KAAK,SAAS;YAC1C,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,iBAAiB,EAAE,MAAM,CAAC,MAAM,CAAC;oBAC/B,GAAG,QAAQ,CAAC,iBAAiB;oBAC7B,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;iBACxE,CAAC;aACH,CAAC;KACP,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"ImmutableGateDecision.js","sourceRoot":"","sources":["../../src/decision/ImmutableGateDecision.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,qBAAqB,CAAC,QAAsB;IAC1D,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,QAAQ;QACX,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;QACrD,aAAa,EACX,QAAQ,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,QAAQ,CAAC,aAAa,EAAE,CAAC;QACvF,GAAG,CAAC,QAAQ,CAAC,QAAQ,KAAK,SAAS;YACjC,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC;oBACtB,GAAG,QAAQ,CAAC,QAAQ;oBACpB,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,aAAa,KAAK,SAAS;wBAC/C,CAAC,CAAC,EAAE;wBACJ,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,QAAQ,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC,EAAE,CAAC;iBAC9E,CAAC;aACH,CAAC;QACN,GAAG,CAAC,QAAQ,CAAC,iBAAiB,KAAK,SAAS;YAC1C,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,iBAAiB,EAAE,MAAM,CAAC,MAAM,CAAC;oBAC/B,GAAG,QAAQ,CAAC,iBAAiB;oBAC7B,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;iBACxE,CAAC;aACH,CAAC;QACN,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,SAAS;YAC/B,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC;oBACpB,GAAG,QAAQ,CAAC,MAAM;oBAClB,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;iBAC7D,CAAC;aACH,CAAC;KACP,CAAC,CAAC;AACL,CAAC"}

package/dist/decision/Provision.d.ts

@@ -0,0 +1,33 @@
+import { type ClientSource } from "../http/ClientIdentification.js";
+export interface ProvisionOptions {
+    /** The authority to provision from; HTTPS, or loopback when allowed. */
+    readonly baseUrl: string;
+    readonly allowInsecureLoopback?: boolean;
+    readonly fetch?: typeof fetch;
+    readonly timeoutMs?: number;
+    readonly source?: ClientSource;
+    /** Shown to the person who later claims the workspace. */
+    readonly agentName?: string;
+}
+export interface ProvisionedWorkspace {
+    readonly orgId: string;
+    /** The key, seen here and nowhere else; the caller stores it. */
+    readonly rawKey: string;
+    readonly provisional: true;
+    /** The caps on the anonymous lane, as the authority stated them. */
+    readonly limits: Readonly<Record<string, unknown>>;
+    /** How a person attaches themselves to the workspace, as the authority stated it. */
+    readonly claim: Readonly<Record<string, unknown>>;
+}
+export declare class ProvisionError extends Error {
+    readonly code: "PROVISION_LIMIT_REACHED" | "PROVISION_REFUSED" | "PROVISION_UNAVAILABLE" | "PROVISION_RESPONSE_INVALID" | "PROVISION_TIMED_OUT";
+    readonly status: number | null;
+    /** Seconds to wait before another attempt, when the authority said. */
+    readonly retryAfterSeconds: number | null;
+    constructor(code: "PROVISION_LIMIT_REACHED" | "PROVISION_REFUSED" | "PROVISION_UNAVAILABLE" | "PROVISION_RESPONSE_INVALID" | "PROVISION_TIMED_OUT", status: number | null, 
+    /** Seconds to wait before another attempt, when the authority said. */
+    retryAfterSeconds?: number | null);
+}
+/** Mints a provisional workspace, or throws a `ProvisionError` that names why. */
+export declare function provisionWorkspace(options: ProvisionOptions): Promise<ProvisionedWorkspace>;
+//# sourceMappingURL=Provision.d.ts.map

package/dist/decision/Provision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Provision.d.ts","sourceRoot":"","sources":["../../src/decision/Provision.ts"],"names":[],"mappings":"AAcA,OAAO,EAAa,KAAK,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAE/E,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD;AAoBD,qBAAa,cAAe,SAAQ,KAAK;aAErB,IAAI,EAChB,yBAAyB,GACzB,mBAAmB,GACnB,uBAAuB,GACvB,4BAA4B,GAC5B,qBAAqB;aACT,MAAM,EAAE,MAAM,GAAG,IAAI;IACrC,uEAAuE;aACvD,iBAAiB,EAAE,MAAM,GAAG,IAAI;gBARhC,IAAI,EAChB,yBAAyB,GACzB,mBAAmB,GACnB,uBAAuB,GACvB,4BAA4B,GAC5B,qBAAqB,EACT,MAAM,EAAE,MAAM,GAAG,IAAI;IACrC,uEAAuE;IACvD,iBAAiB,GAAE,MAAM,GAAG,IAAW;CAK1D;AAQD,kFAAkF;AAClF,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA8DjG"}

package/dist/decision/Provision.js

@@ -0,0 +1,116 @@
+/**
+ * A free Decionis key, issued in the run itself. `POST
+ * /v1/public/agents/provision` mints a provisional workspace with no
+ * account, no email and no card: an organization id, a key returned exactly
+ * once, an allowance of governed decisions, and the way a person later
+ * claims it. Every dossier such a workspace mints is signed with the
+ * `provisional_anonymous` issuer tier, so a verifier can always tell it
+ * from an owned organization's record. The call carries the client
+ * identification the hosted gate carries, so the authority can say which
+ * repository, example and surface the workspace came from.
+ */
+import { z } from "zod";
+import { AuthorityBaseUrl } from "../http/AuthorityBaseUrl.js";
+import { BoundedResponseBody } from "../http/BoundedResponseBody.js";
+import { userAgent } from "../http/ClientIdentification.js";
+const MAX_RESPONSE_BYTES = 64 * 1024;
+const DEFAULT_TIMEOUT_MS = 8_000;
+const MAX_AGENT_NAME = 64;
+/**
+ * Mirrors `AgentProvisionResponse`: the four fields the caller needs are
+ * required; the rest of the contract is open and rides along as it came.
+ */
+const ProvisionResponseSchema = z
+    .object({
+    org_id: z.string().uuid(),
+    raw_key: z.string().min(1).max(4_096),
+    provisional: z.literal(true),
+    limits: z.record(z.string(), z.unknown()).default({}),
+    claim: z.record(z.string(), z.unknown()).default({}),
+})
+    .passthrough();
+export class ProvisionError extends Error {
+    code;
+    status;
+    retryAfterSeconds;
+    constructor(code, status, 
+    /** Seconds to wait before another attempt, when the authority said. */
+    retryAfterSeconds = null) {
+        super(code);
+        this.code = code;
+        this.status = status;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = "ProvisionError";
+    }
+}
+function retryAfter(response) {
+    const value = response.headers.get("retry-after");
+    if (value === null || !/^\d{1,7}$/.test(value.trim()))
+        return null;
+    return Number(value.trim());
+}
+/** Mints a provisional workspace, or throws a `ProvisionError` that names why. */
+export async function provisionWorkspace(options) {
+    const baseUrl = AuthorityBaseUrl.normalize(options.baseUrl, options.allowInsecureLoopback ?? false);
+    const doFetch = options.fetch ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const agentName = options.agentName?.slice(0, MAX_AGENT_NAME);
+    let response;
+    try {
+        response = await doFetch(`${baseUrl}/v1/public/agents/provision`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: "application/json",
+                "user-agent": userAgent(options.source),
+            },
+            body: JSON.stringify(agentName === undefined ? {} : { agent_name: agentName }),
+            redirect: "error",
+            signal: controller.signal,
+        });
+    }
+    catch {
+        clearTimeout(timer);
+        throw new ProvisionError(controller.signal.aborted ? "PROVISION_TIMED_OUT" : "PROVISION_UNAVAILABLE", null);
+    }
+    let text;
+    try {
+        text = await BoundedResponseBody.read(response, MAX_RESPONSE_BYTES);
+    }
+    catch {
+        text = null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (response.status === 429) {
+        throw new ProvisionError("PROVISION_LIMIT_REACHED", 429, retryAfter(response));
+    }
+    if (response.status >= 500) {
+        throw new ProvisionError("PROVISION_UNAVAILABLE", response.status, retryAfter(response));
+    }
+    if (response.status !== 201 && response.status !== 200) {
+        throw new ProvisionError("PROVISION_REFUSED", response.status);
+    }
+    if (text === null)
+        throw new ProvisionError("PROVISION_RESPONSE_INVALID", response.status);
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw new ProvisionError("PROVISION_RESPONSE_INVALID", response.status);
+    }
+    const parsed = ProvisionResponseSchema.safeParse(body);
+    if (!parsed.success)
+        throw new ProvisionError("PROVISION_RESPONSE_INVALID", response.status);
+    return {
+        orgId: parsed.data.org_id,
+        rawKey: parsed.data.raw_key,
+        provisional: true,
+        limits: parsed.data.limits,
+        claim: parsed.data.claim,
+    };
+}
+//# sourceMappingURL=Provision.js.map

package/dist/decision/Provision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Provision.js","sourceRoot":"","sources":["../../src/decision/Provision.ts"],"names":[],"mappings":"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"}

package/dist/decision/ShadowGate.d.ts

@@ -0,0 +1,31 @@
+import type { CapturedIntent } from "../intent/ExecutionIntent.js";
+import { type DecisionAuthority, type DecisionEvaluationMode, type DecisionEvaluationOptions, type DecisionEvidence, type GateDecision } from "./DecisionAuthority.js";
+/**
+ * Runs a local authority and a hosted Decionis gate against the same intent.
+ *
+ * `SHADOW`: the local decision governs execution exactly as it would alone,
+ * and the hosted evaluation rides along as `hosted` for display and audit. A
+ * hosted failure is recorded and changes nothing, so setting a key cannot
+ * break an integration that works today.
+ *
+ * `ENFORCEMENT`: the hosted decision governs, because only its grant can be
+ * claimed by the enforcement verifier. The local authority can still tighten
+ * it: when the local verdict is strictly more restrictive, that decision is
+ * returned instead, and it carries no hosted grant.
+ *
+ * Neither mode returns a decision less restrictive than the local authority's.
+ */
+export declare class ShadowGate implements DecisionAuthority {
+    private readonly local;
+    private readonly hosted;
+    private readonly mode;
+    readonly evaluationMode?: DecisionEvaluationMode;
+    constructor(local: DecisionAuthority, hosted: DecisionAuthority, mode: DecisionEvaluationMode);
+    evaluate(captured: CapturedIntent, evidence?: DecisionEvidence, options?: DecisionEvaluationOptions): Promise<GateDecision>;
+    /**
+     * The hosted side never rejects and never answers about another intent:
+     * either would let a network fault or a misbound service reach execution.
+     */
+    private hostedDecision;
+}
+//# sourceMappingURL=ShadowGate.d.ts.map

package/dist/decision/ShadowGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShadowGate.d.ts","sourceRoot":"","sources":["../../src/decision/ShadowGate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,gBAAgB,EAErB,KAAK,YAAY,EAClB,MAAM,wBAAwB,CAAC;AAUhC;;;;;;;;;;;;;;GAcG;AACH,qBAAa,UAAW,YAAW,iBAAiB;IAIhD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IALvB,SAAgB,cAAc,CAAC,EAAE,sBAAsB,CAAC;gBAGrC,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,sBAAsB;IASlC,QAAQ,CACnB,QAAQ,EAAE,cAAc,EACxB,QAAQ,CAAC,EAAE,gBAAgB,EAC3B,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,YAAY,CAAC;IAuBxB;;;OAGG;YACW,cAAc;CAgB7B"}

package/dist/decision/ShadowGate.js

@@ -0,0 +1,79 @@
+import { FailClosedDecision, } from "./DecisionAuthority.js";
+import { immutableGateDecision } from "./ImmutableGateDecision.js";
+/** Higher is more restrictive. The Decionis contract has no fourth verdict. */
+const RESTRICTIVENESS = Object.freeze({
+    ALLOW: 0,
+    ESCALATE: 1,
+    BLOCK: 2,
+});
+/**
+ * Runs a local authority and a hosted Decionis gate against the same intent.
+ *
+ * `SHADOW`: the local decision governs execution exactly as it would alone,
+ * and the hosted evaluation rides along as `hosted` for display and audit. A
+ * hosted failure is recorded and changes nothing, so setting a key cannot
+ * break an integration that works today.
+ *
+ * `ENFORCEMENT`: the hosted decision governs, because only its grant can be
+ * claimed by the enforcement verifier. The local authority can still tighten
+ * it: when the local verdict is strictly more restrictive, that decision is
+ * returned instead, and it carries no hosted grant.
+ *
+ * Neither mode returns a decision less restrictive than the local authority's.
+ */
+export class ShadowGate {
+    local;
+    hosted;
+    mode;
+    evaluationMode;
+    constructor(local, hosted, mode) {
+        this.local = local;
+        this.hosted = hosted;
+        this.mode = mode;
+        if (mode !== "SHADOW" && mode !== "ENFORCEMENT") {
+            throw new Error("DECIONIS_GATE_MODE_INVALID");
+        }
+        const declared = mode === "ENFORCEMENT" ? mode : local.evaluationMode;
+        if (declared !== undefined)
+            this.evaluationMode = declared;
+    }
+    async evaluate(captured, evidence, options = {}) {
+        const [local, hosted] = await Promise.all([
+            this.local.evaluate(captured, evidence, options),
+            this.hostedDecision(captured, evidence, options),
+        ]);
+        const governs = this.mode === "ENFORCEMENT" &&
+            RESTRICTIVENESS[hosted.verdict] >= RESTRICTIVENESS[local.verdict];
+        return immutableGateDecision({
+            ...(governs ? hosted : local),
+            hosted: {
+                mode: this.mode,
+                governs,
+                verdict: hosted.verdict,
+                decisionId: hosted.decisionId,
+                dossierId: hosted.dossierId,
+                reasonCodes: hosted.reasonCodes,
+                failClosed: hosted.failClosed,
+                verificationUrl: hosted.verificationUrl ?? null,
+            },
+        });
+    }
+    /**
+     * The hosted side never rejects and never answers about another intent:
+     * either would let a network fault or a misbound service reach execution.
+     */
+    async hostedDecision(captured, evidence, options) {
+        let decision;
+        try {
+            decision = await this.hosted.evaluate(captured, evidence, options);
+        }
+        catch {
+            return FailClosedDecision.create(captured.intentHash, "AUTHORITY_UNAVAILABLE");
+        }
+        if (decision.intentHash !== captured.intentHash) {
+            return FailClosedDecision.create(captured.intentHash, "AUTHORITY_BINDING_MISMATCH");
+        }
+        return decision;
+    }
+}
+//# sourceMappingURL=ShadowGate.js.map

package/dist/decision/ShadowGate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShadowGate.js","sourceRoot":"","sources":["../../src/decision/ShadowGate.ts"],"names":[],"mappings":"AACA,OAAO,EACL,kBAAkB,GAOnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,+EAA+E;AAC/E,MAAM,eAAe,GAA8C,MAAM,CAAC,MAAM,CAAC;IAC/E,KAAK,EAAE,CAAC;IACR,QAAQ,EAAE,CAAC;IACX,KAAK,EAAE,CAAC;CACT,CAAC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,UAAU;IAIF;IACA;IACA;IALH,cAAc,CAA0B;IAExD,YACmB,KAAwB,EACxB,MAAyB,EACzB,IAA4B;QAF5B,UAAK,GAAL,KAAK,CAAmB;QACxB,WAAM,GAAN,MAAM,CAAmB;QACzB,SAAI,GAAJ,IAAI,CAAwB;QAE7C,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,aAAa,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAChD,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,KAAK,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC;QACtE,IAAI,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,cAAc,GAAG,QAAQ,CAAC;IAC7D,CAAC;IAEM,KAAK,CAAC,QAAQ,CACnB,QAAwB,EACxB,QAA2B,EAC3B,UAAqC,EAAE;QAEvC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACxC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC;YAChD,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC;SACjD,CAAC,CAAC;QACH,MAAM,OAAO,GACX,IAAI,CAAC,IAAI,KAAK,aAAa;YAC3B,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,eAAe,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACpE,OAAO,qBAAqB,CAAC;YAC3B,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;YAC7B,MAAM,EAAE;gBACN,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO;gBACP,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,IAAI;aAChD;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,cAAc,CAC1B,QAAwB,EACxB,QAAsC,EACtC,OAAkC;QAElC,IAAI,QAAsB,CAAC;QAC3B,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,uBAAuB,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,QAAQ,CAAC,UAAU,KAAK,QAAQ,CAAC,UAAU,EAAE,CAAC;YAChD,OAAO,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,4BAA4B,CAAC,CAAC;QACtF,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}

package/dist/execution/ActionRegistry.d.ts

@@ -15,6 +15,14 @@ export interface ActionExecutionContext<TParameters> {
 export interface ProviderDispatch {
     readonly idempotencyKey: string;
     run<TResult>(operation: (idempotencyKey: string) => Promise<TResult> | TResult): Promise<TResult>;
+    /**
+     * The provider's signed effect receipt, when it returned one with its
+     * answer, verbatim. It is carried on the attempt to the finalization, where
+     * the verifier forwards it to the authority to verify and record; this
+     * package never reads it. Only meaningful inside `run`: a receipt before
+     * the dispatch describes nothing.
+     */
+    receipt(token: string): void;
 }
 export interface ActionReconciliationContext<TParameters> {
     readonly intent: CapturedIntent;
@@ -38,11 +46,43 @@ export interface ActionHandler<TParameters, TResult> {
 export type ActionExecutionAttempt = {
     readonly status: "COMPLETED";
     readonly result: unknown;
+    readonly receipt: string | null;
 } | {
     readonly status: "FAILED_BEFORE_DISPATCH";
+} | {
+    readonly status: "REFUSED_AFTER_DISPATCH";
+    readonly reason: string;
+    readonly receipt: string | null;
 } | {
     readonly status: "UNKNOWN_AFTER_DISPATCH";
+    readonly receipt: string | null;
 };
+/**
+ * What a handler throws when the provider refused, definitively, after the
+ * dispatch boundary was crossed.
+ *
+ * Without this, a handler has two ways to report a refusal and neither is
+ * true. Returning normally says the side effect happened. Throwing says the
+ * outcome is unknown, which invites a reconciliation of something that never
+ * needed one. This says the third thing: the request reached the provider,
+ * the provider said no, and nothing was effected.
+ *
+ * Only the provider's own deterministic refusal belongs here — a 4xx with a
+ * body that says which rule refused it. A timeout, a 5xx, a dropped
+ * connection or an unreadable answer is not a refusal, and throwing this for
+ * one of those would turn "nobody knows" into "definitely not", which is the
+ * one direction this boundary must never move in.
+ *
+ * Thrown before the dispatch, it is a handler failure like any other: a
+ * refusal cannot be claimed for a request that was never sent.
+ */
+export declare class ProviderRefusal extends Error {
+    /** The provider's own reason, as a code; never its response body. */
+    readonly reason: string;
+    constructor(
+    /** The provider's own reason, as a code; never its response body. */
+    reason: string);
+}
 export declare class ActionRegistry {
     private readonly actions;
     private readonly pendingReconciliations;

package/dist/execution/ActionRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionRegistry.d.ts","sourceRoot":"","sources":["../../src/execution/ActionRegistry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ActionRegistry.d.ts","sourceRoot":"","sources":["../../src/execution/ActionRegistry.ts"],"names":[],"mappings":"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"}

package/dist/execution/ActionRegistry.js

@@ -1,3 +1,32 @@
+/**
+ * What a handler throws when the provider refused, definitively, after the
+ * dispatch boundary was crossed.
+ *
+ * Without this, a handler has two ways to report a refusal and neither is
+ * true. Returning normally says the side effect happened. Throwing says the
+ * outcome is unknown, which invites a reconciliation of something that never
+ * needed one. This says the third thing: the request reached the provider,
+ * the provider said no, and nothing was effected.
+ *
+ * Only the provider's own deterministic refusal belongs here — a 4xx with a
+ * body that says which rule refused it. A timeout, a 5xx, a dropped
+ * connection or an unreadable answer is not a refusal, and throwing this for
+ * one of those would turn "nobody knows" into "definitely not", which is the
+ * one direction this boundary must never move in.
+ *
+ * Thrown before the dispatch, it is a handler failure like any other: a
+ * refusal cannot be claimed for a request that was never sent.
+ */
+export class ProviderRefusal extends Error {
+    reason;
+    constructor(
+    /** The provider's own reason, as a code; never its response body. */
+    reason) {
+        super(reason);
+        this.reason = reason;
+        this.name = "ProviderRefusal";
+    }
+}
 export class ActionRegistry {
     actions = new Map();
     pendingReconciliations = new Map();
@@ -43,6 +72,7 @@ export class ActionRegistry {
         if (!result.success)
             throw new Error("ACTION_PARAMETERS_INVALID");
         let dispatched = false;
+        let receipt = null;
         const dispatch = Object.freeze({
             idempotencyKey: captured.intent.idempotencyKey,
             run: async (operation) => {
@@ -51,6 +81,11 @@ export class ActionRegistry {
                 dispatched = true;
                 return await operation(captured.intent.idempotencyKey);
             },
+            receipt: (token) => {
+                if (!dispatched)
+                    throw new Error("PROVIDER_RECEIPT_BEFORE_DISPATCH");
+                receipt = token;
+            },
         });
         try {
             return {
@@ -61,10 +96,20 @@ export class ActionRegistry {
                     authorization,
                     dispatch,
                 }),
+                receipt,
             };
         }
-        catch {
-            return { status: dispatched ? "UNKNOWN_AFTER_DISPATCH" : "FAILED_BEFORE_DISPATCH" };
+        catch (error) {
+            // A refusal the provider made is only a refusal if the request reached
+            // it. Before the dispatch it is a handler failure, because nothing was
+            // sent for anyone to refuse. A receipt can accompany either answer
+            // after the dispatch: a provider's signed refusal is evidence too.
+            if (dispatched && error instanceof ProviderRefusal) {
+                return { status: "REFUSED_AFTER_DISPATCH", reason: error.reason, receipt };
+            }
+            return dispatched
+                ? { status: "UNKNOWN_AFTER_DISPATCH", receipt }
+                : { status: "FAILED_BEFORE_DISPATCH" };
         }
     }
     async reconcile(captured, idempotencyKey) {

package/dist/execution/ActionRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"ActionRegistry.js","sourceRoot":"","sources":["../../src/execution/ActionRegistry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ActionRegistry.js","sourceRoot":"","sources":["../../src/execution/ActionRegistry.ts"],"names":[],"mappings":"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"}