@decionis/agent-safe-pipeline 0.1.3 → 0.2.0

package/README.md

@@ -1,28 +1,95 @@
 # `@decionis/agent-safe-pipeline`
 
-TypeScript reference implementation of Agent-Safe Pipeline: capture an immutable agent proposal, obtain an independent Decionis decision, coordinate Presence escalation, and execute only through an intent-bound single-use grant and sealed trusted handler registry.
+[![npm version](https://img.shields.io/npm/v/@decionis/agent-safe-pipeline.svg)](https://www.npmjs.com/package/@decionis/agent-safe-pipeline)
+[![Continuous integration](https://github.com/decionis/agent-safe-pipeline/actions/workflows/deploy.yml/badge.svg?branch=master)](https://github.com/decionis/agent-safe-pipeline/actions/workflows/deploy.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/decionis/agent-safe-pipeline/badge)](https://scorecard.dev/viewer/?uri=github.com/decionis/agent-safe-pipeline)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14098/badge)](https://www.bestpractices.dev/projects/14098)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/decionis/agent-safe-pipeline/blob/master/LICENSE)
 
-## Install
+**Let agents propose. Let policy decide.**
+
+`@decionis/agent-safe-pipeline` is the TypeScript reference implementation of the Execution
+Authority architecture. An AI agent may reason, plan, and propose a consequential action. It cannot
+authorize that action, hold the credentials that perform it, or choose which trusted code runs. The
+exact proposal is captured as an immutable, short-lived intent, evaluated independently by Decionis,
+escalated to a verified human when policy requires it, and executed only through a single-use grant
+bound to that one intent. Every decision leaves a Decision Dossier, so the record of what was
+authorized, under which policy, and on whose approval compounds over time.
+
+```text
+Agent -> immutable intent -> Decionis -> ALLOW / ESCALATE / BLOCK -> SafeExecutor -> downstream API
+                                      |
+                                      +-> Presence -> verified human approval -> Decionis re-evaluation
+                                      |
+                                      +-> Decision Dossier -> compounding decision record
+```
+
+The package is a library, not a hosted service. It supplies the boundary; Decionis supplies the
+decision. Its safety claims hold only when the documented trust boundary is preserved: the agent
+runtime never sees Decionis credentials, downstream credentials, or the handler registry.
+
+## Why an execution boundary
 
-Install the latest stable release:
+Model-level controls shape what an agent says. They cannot prove, after the fact, that a specific
+side effect was authorized by a specific policy at the moment it happened. Prompt filtering,
+fine-tuning, and evaluation all sit before the action; the gap is at execution. This package closes
+it structurally:
+
+- **The agent's input is only the proposal.** Action, target, and parameters. Tenant, actor,
+  downstream system, and credentials come from trusted server configuration and cannot be injected.
+- **The decision is made elsewhere.** Decionis evaluates the canonical intent hash and returns
+  `ALLOW`, `ESCALATE`, or `BLOCK` with a decision identifier and a Decision Dossier identifier.
+- **Approval is evidence, never authority.** Presence proves that a real person approved that exact
+  intent. Decionis verifies the receipt and re-evaluates current policy before any grant exists.
+- **Execution consumes a grant, not a callback.** `SafeExecutor` accepts a captured intent and a
+  decision. It claims the grant atomically, then invokes a handler from a sealed registry.
+- **Everything else fails closed.** A network error, a malformed response, a missing grant, an
+  expired intent, a replayed token, or a binding mismatch all result in no execution.
+
+## Requirements
+
+- Node.js 22.14 or later. The package is ESM-only and ships its own TypeScript declarations.
+- A server-side process that holds the Decionis credentials. Never load this package into a
+  browser, an agent sandbox, or any runtime the model can influence.
+- `zod` v4 for handler parameter schemas (installed as a dependency).
+
+## Install
 
 ```bash
 npm install @decionis/agent-safe-pipeline
 ```
 
-To evaluate this prerelease explicitly:
+Stable releases publish under the `latest` tag with npm provenance. Prereleases publish under the
+`next` tag and are never installed by default:
 
 ```bash
-npm install @decionis/agent-safe-pipeline@0.1.3-rc.2
+npm install @decionis/agent-safe-pipeline@next
 ```
 
-Production credentials belong in the trusted executor process, never the agent runtime:
+Decionis credentials belong only in the trusted executor process:
 
 ```text
 DECIONIS_API_URL=https://api.decionis.com
 DECIONIS_API_KEY=server-side-secret
 ```
 
+`DecionisGate` and `DecionisGrantVerifier` accept `apiKey` as a string or as a function read at
+each request. A deployment whose credential rotates inside a process's life gives the function: the
+next request carries the new value, a request already in flight keeps the one it sent, and nothing
+has to be rebuilt to make that true. A credential that does not rotate stays a string.
+
+```ts
+const gate = new DecionisGate({
+  baseUrl: process.env.DECIONIS_API_URL!,
+  apiKey: () => secrets.current("DECIONIS_API_KEY"),
+});
+```
+
+## Quick start: enforcement
+
+The complete production path in one file. The proposal comes from the agent; everything else comes
+from trusted configuration.
+
 ```ts
 import {
   ActionRegistry,
@@ -33,17 +100,37 @@ import {
 } from "@decionis/agent-safe-pipeline";
 import { z } from "zod";
 
+// 1. Capture the exact proposal. The agent supplies only action, target, and parameters.
+const captured = new IntentCapture().capture(
+  {
+    action: "refund_order",
+    target: "shopify:order:1001",
+    parameters: { orderId: "1001", amountMinor: 35_000 },
+  },
+  {
+    tenantId: config.tenantId,
+    actor: { id: "refund-agent", type: "AI_AGENT" },
+    downstreamTarget: { system: "shopify", operation: "refund", environment: "production" },
+    idempotencyKey: "refund-1001-v1",
+  },
+);
+
+// 2. Ask Decionis. The gate never returns an executable decision without a grant.
 const gate = new DecionisGate({
   baseUrl: process.env.DECIONIS_API_URL!,
   apiKey: process.env.DECIONIS_API_KEY!,
 });
-const captured = new IntentCapture().capture(agentProposal, trustedServerContext);
+const decision = await gate.evaluate(captured);
+
+// 3. Register trusted handlers once, then seal the registry so nothing can be added at runtime.
 const registry = new ActionRegistry()
   .register("refund_order", {
     parametersSchema: z.object({ orderId: z.string(), amountMinor: z.number().int() }).strict(),
     execute: ({ parameters }) => shopify.refund(parameters),
   })
   .seal();
+
+// 4. Execute only through a claimed single-use grant bound to this intent.
 const executor = new SafeExecutor(
   registry,
   new DecionisGrantVerifier({
@@ -51,16 +138,390 @@ const executor = new SafeExecutor(
     apiKey: process.env.DECIONIS_API_KEY!,
   }),
 );
-const result = await executor.run(captured, await gate.evaluate(captured));
+const result = await executor.run(captured, decision);
+
+if (result.outcome === "COMPLETED") {
+  // result.result is the handler's return value.
+  // result.authorization carries the consumed { decisionId, dossierId, grantId, intentHash }.
+}
+```
+
+The executor validates parameters against the handler's schema before the grant is claimed, and the
+grant is claimed before the handler runs. If either step fails, the handler is never invoked.
+
+The trusted context also accepts an optional `expectedEffectDigest` (`sha256:` plus 64 lowercase hex):
+a digest-only commitment to the downstream state predicted before dispatch. It is bound into the
+canonical intent hash and into the signed grant, and `DecionisGrantVerifier` refuses the authorization
+unless the returned grant echoes exactly that digest. The agent proposal can never carry it, and an
+intent that omits it hashes byte-identically to before the field existed. After the attempt, a trusted
+runtime that observed the effect may pass an `AuthorityEffectEvidence` record as `effectEvidence` to
+`DecionisGrantVerifier.finalize`, and read the authority's own `AuthorityEffectReport` back through
+`effectReport(authorization)`. See
+[execution intent](https://github.com/decionis/agent-safe-pipeline/blob/master/docs/execution-intent.md)
+and [execution outcomes](https://github.com/decionis/agent-safe-pipeline/blob/master/docs/execution-outcomes.md).
+
+## Outcomes
+
+Decionis returns one of three verdicts. The executor turns a verdict into exactly one execution
+outcome.
+
+| Verdict                               | Executor behavior                                                       |
+| ------------------------------------- | ----------------------------------------------------------------------- |
+| `ALLOW` with a valid single-use grant | Claim the grant atomically, then invoke the registered handler          |
+| `ESCALATE`                            | Stop. Resolve a DIRECT or MANAGED Presence escalation, then re-evaluate |
+| `BLOCK`, any error, any mismatch      | Fail closed. The handler is never invoked                               |
+
+`SafeExecutor.run` resolves to a discriminated result rather than throwing:
+
+| `outcome`                 | Meaning                                                                                                                                                                                   |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `COMPLETED`               | The grant was consumed and the handler returned. `result` holds its value.                                                                                                                |
+| `BLOCKED`                 | Nothing ran. `reason` names the refusal: a non-authoritative or non-`ALLOW` decision, a missing or invalid grant, an intent binding or conformance failure, or an unavailable audit sink. |
+| `FAILED_BEFORE_DISPATCH`  | The grant was consumed but the handler failed before reaching the provider. Safe to reason about.                                                                                         |
+| `DEFINITELY_NOT_EXECUTED` | The provider was called and refused deterministically. `reason` is its own code. Nothing was effected and there is nothing to reconcile.                                                  |
+| `UNKNOWN_AFTER_DISPATCH`  | The provider was called and its outcome is unknown. A `recovery` reference supports reconciliation.                                                                                       |
+
+A handler reports that last-but-one case by throwing `ProviderRefusal` from inside `dispatch.run`,
+with the provider's own reason code. Only a deterministic refusal belongs in it: a timeout, a 5xx
+or an unreadable answer is not a refusal, and reporting one as a refusal would turn "nobody knows"
+into "definitely not".
+
+Every outcome that consumed a grant also reports `finalization` (`RECORDED`, `PENDING`, or
+`UNSUPPORTED`). The executor records `COMMITTED`, `FAILED`, or `INDETERMINATE` with Decionis after
+the attempt so commit evidence joins the Decision Dossier chain. Finalization is evidence, never
+authority: it cannot change `outcome` or `executed`.
+
+### What each record establishes
+
+Fluent summaries lose these distinctions first. Each row names the record or state, what it
+establishes, and what it does not.
+
+| Record or state                                           | What it establishes                                                                                                                                                                                                                                                                                                                                                                                                                             | What it does not establish                                                                                                                                                                                                                                                                  |
+| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Captured intent (`IntentCapture`, `intentHash`)           | The exact action, target, and parameters the agent proposed, bound to trusted tenant, actor, and downstream context, hashed and expiring                                                                                                                                                                                                                                                                                                        | That the agent's facts, identities, or amounts are true; that anything may execute                                                                                                                                                                                                          |
+| Verified human approval (Presence `receiptDossierId`)     | A named person approved that exact intent hash under the assurance the receipt records                                                                                                                                                                                                                                                                                                                                                          | Permission to execute: Decionis re-evaluates policy with the receipt, and only that evaluation can issue a grant                                                                                                                                                                            |
+| Execution grant (`authorization` on an `ALLOW`)           | Permission for one attempt at one intent, claimed once through the `AuthorizationVerifier` immediately before the handler runs                                                                                                                                                                                                                                                                                                                  | Anything after expiry, for another intent hash, or on a second presentation; a dossier identifier, an invitation link, or an earlier `ALLOW` is not a substitute                                                                                                                            |
+| Decision Dossier (`decisionId`, `dossierId`)              | The record of why Decionis allowed, escalated, or blocked: policy snapshot, inputs, evidence, and grant metadata                                                                                                                                                                                                                                                                                                                                | An execution credential; proof that the underlying business judgement was right                                                                                                                                                                                                             |
+| Single claim, `COMPLETED`                                 | The grant was consumed once and the trusted handler returned a provider result                                                                                                                                                                                                                                                                                                                                                                  | An exactly-once downstream business effect or independent confirmation of settlement; whether an observation counts as `CONFIRMED` is the authority's judgement, not this package's                                                                                                         |
+| `UNKNOWN_AFTER_DISPATCH`, finalized `INDETERMINATE`       | Dispatch began and completion could not be proved                                                                                                                                                                                                                                                                                                                                                                                               | Permission to repeat the side effect: reconcile through provider idempotency and read-only lookup, never by a second dispatch                                                                                                                                                               |
+| `DEFINITELY_NOT_EXECUTED`, finalized `FAILED`             | Dispatch began, the provider refused it deterministically, and nothing was effected                                                                                                                                                                                                                                                                                                                                                             | Permission to try again: the refusal was about this attempt, and another needs a fresh decision and a fresh grant                                                                                                                                                                           |
+| Shadow observation (`ShadowPipeline`, `mode: "SHADOW"`)   | What Decionis would have decided about an action that already ran: a verdict and a dossier, no grant                                                                                                                                                                                                                                                                                                                                            | Enforcement, a grant, or a no-write test environment; the production write happened as before                                                                                                                                                                                               |
+| Library boundary (this package)                           | Intent capture, the gate, verification, and claim-before-handler dispatch inside the trusted integration                                                                                                                                                                                                                                                                                                                                        | Host isolation, IAM, network egress, credential storage, or incident response; see the [threat model](https://github.com/decionis/agent-safe-pipeline/blob/master/THREAT-MODEL.md) and [trust boundary](https://github.com/decionis/agent-safe-pipeline/blob/master/docs/trust-boundary.md) |
+| Trusted executor (`createTrustedExecutor`)                | What one process verifies about itself and enforces at its own door: the host posture `HostPosture` can observe, caller principals with roles and their own credentials, egress sealed to the origins `EgressPolicy` was configured with, a durable attempt journal reconciled by `StartupReconciler`, the ceilings in `HardLimits`, BEAP-vocabulary effect evidence, `HaltSwitch`, and hash-chained evidence with an offline-verifiable export | Node or kernel isolation, a CNI actually enforcing the NetworkPolicies the kit declares, an HSM or KMS, the authority's policy, or a bank's core correctness                                                                                                                                |
+| Executor evidence bundle (`agent-safe.evidence-bundle/1`) | What one executor process can say about an incident: both hash-chained streams as it still held them, the open attempts, the posture by check, the chain heads, a configuration digest, and every file's own digest                                                                                                                                                                                                                             | Origin, unless a signature over the manifest verifies against a key the reader brought; completeness, since it carries a bounded window and says how many lines it dropped; and it holds no parameter, no provider body, no secret and no digest of one                                     |
+
+The sequence that produces both records, and two synthetic records side by side, are in
+[Decision Dossiers](https://github.com/decionis/agent-safe-pipeline/blob/master/docs/decision-dossiers.md).
+
+## Human approval through Presence
+
+When policy escalates, a person must approve that exact intent with independently signed evidence.
+Presence delivers the request to an enrolled device and returns a receipt bound to the intent hash.
+Presence never authorizes execution; Decionis verifies the receipt and re-evaluates policy. The
+package supports two integration levels, and the executor's grant path is identical in both.
+
+| Mode      | Who coordinates Presence | Credentials in the executor | Entry point                                          |
+| --------- | ------------------------ | --------------------------- | ---------------------------------------------------- |
+| `DIRECT`  | Your trusted executor    | Decionis and Presence       | `PresenceApprovalCoordinator`                        |
+| `MANAGED` | Decionis                 | Decionis only               | `DecionisGate.evaluate` with an `escalation` request |
+
+In MANAGED mode, pass routing and ceremony constraints outside the canonical intent, then poll
+Decionis only:
+
+```ts
+const pending = await gate.evaluate(captured, undefined, {
+  escalation: {
+    mode: "MANAGED",
+    approver: { principal_id: approverId, role_id: "APPROVER" },
+    verification_requirements: { methods: ["WEBAUTHN"], level: "HIGH_CONFIDENCE" },
+  },
+});
+// pending.verdict === "ESCALATE"; pending.managedEscalation is set; no grant exists yet.
+
+const authorized = await gate.waitForAuthorization(captured, pending, { signal });
+const result = await executor.run(captured, authorized);
+```
+
+`waitForAuthorization` polls with capped exponential backoff and bounded jitter, and stops at the
+intent or escalation expiry. It returns a normal `ALLOW` decision with a grant only after Decionis
+has verified the Presence evidence and re-evaluated current policy. Approval cannot revive an intent
+after it expires. Presence transport or schema failures and Decionis re-authorization failures
+return stable fail-closed decisions; raw downstream error text never reaches the caller.
+
+## Shadow mode
+
+Measure before you enforce. `ShadowPipeline` wraps an execution path you already run and records
+what Decionis would have decided, without the ability to stop, delay, or alter it.
+
+```ts
+import { DecionisGate, ShadowPipeline } from "@decionis/agent-safe-pipeline";
+
+const shadow = new ShadowPipeline(new DecionisGate({ baseUrl, apiKey, mode: "SHADOW" }), {
+  timeoutMs: 2_000,
+});
+
+const run = await shadow.observe(captured, () => existingRefund(order));
+// run.production is your unchanged result, available as soon as production settles.
+const observation = await run.observation;
+// The observation runs under its own timeout and never rejects; it reports the verdict
+// Decionis would have returned, the dossier identifier, and whether a grant was discarded.
+```
+
+A shadow observation carries no grant, is structurally distinct from a `GateDecision`, and is
+rejected by `SafeExecutor` at runtime. See
+[shadow mode](https://github.com/decionis/agent-safe-pipeline/blob/master/docs/shadow-mode.md).
+
+## Adoption path
+
+The same `IntentCapture`, `ActionRegistry`, and handler code carry through every stage. Nothing is
+rewritten between them.
+
+| Stage       | Authority                                                     | What it proves                                                                   |
+| ----------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Development | `createFixtureAuthorityPair` (refuses `NODE_ENV=production`)  | The intent, registry, and executor wiring is correct                             |
+| Shadow      | `ShadowPipeline` over `DecionisGate` with `mode: "SHADOW"`    | What Decionis would have decided about actions that already run; no grant issued |
+| Enforcement | `DecionisGate` plus `DecionisGrantVerifier` in `SafeExecutor` | Nothing runs without an independent decision and a consumed single-use grant     |
+
+### Selecting the gate from the environment
+
+`createGate` moves an integration between those stages with configuration alone. It takes the
+authority and verifier you already run, and reads one variable to decide whether Decionis runs
+beside them:
+
+```ts
+import { createFixtureAuthorityPair, createGate } from "@decionis/agent-safe-pipeline";
+
+const gate = createGate({
+  local: createFixtureAuthorityPair(() => "BLOCK", { unsafeAllowDevelopmentFixture: true }),
+  tenantId: "00000000-0000-4000-8000-000000000001",
+});
+const captured = new IntentCapture().capture(proposal, { tenantId: gate.tenantId, ...trusted });
+const decision = await gate.authority.evaluate(captured);
+const result = await new SafeExecutor(registry, gate.verifier).run(captured, decision);
+```
+
+| Variable                           | Default                    | Effect                                                                                                                                                                                                           |
+| ---------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DECIONIS_API_KEY`                 | unset                      | Unset: `gate.authority` and `gate.verifier` are the `local` objects themselves, and no client is constructed. Set: `DecionisGate` runs beside `local` through `ShadowGate`.                                      |
+| `DECIONIS_TENANT_ID`               | required with the key      | The key's organization. Decionis binds every intent to it, so `gate.tenantId` returns it for the capture; without the key, `gate.tenantId` is the `tenantId` you passed.                                         |
+| `DECIONIS_MODE`                    | `SHADOW`                   | `SHADOW`: the local decision governs execution and the hosted one is recorded on `decision.hosted`. `ENFORCEMENT`: the hosted decision governs, claimed through `DecionisGrantVerifier`; local can only tighten. |
+| `DECIONIS_API_URL`                 | `https://api.decionis.com` | HTTPS only, unless `DECIONIS_ALLOW_INSECURE_LOOPBACK=true` names a loopback double.                                                                                                                              |
+| `DECIONIS_TIMEOUT_MS`              | `DecionisGate`'s default   | Budget for the hosted call. A call past it is recorded as fail-closed.                                                                                                                                           |
+| `DECIONIS_ALLOW_INSECURE_LOOPBACK` | unset                      | `true` permits `http://127.0.0.1` for `LocalAuthority`.                                                                                                                                                          |
+
+`ShadowGate` never returns a decision less restrictive than the local authority's, in either mode. A
+hosted timeout, network error, non-2xx response, malformed body, or binding mismatch is recorded on
+`decision.hosted` as `failClosed` with verdict `BLOCK`: in `SHADOW` that changes nothing about
+execution, in `ENFORCEMENT` it blocks. A hosted variable that cannot be honoured (`DECIONIS_MODE`
+outside `SHADOW` and `ENFORCEMENT`, a missing `DECIONIS_TENANT_ID`, a non-HTTPS URL) throws at
+construction rather than falling back to local, so a misconfiguration is never mistaken for hosted
+mode.
+
+`DecionisGate` sends `User-Agent: agent-safe-pipeline/<version>` on every call, and `source`
+(`{ repo, example }`, on `createGate` or the gate itself) is appended to it as a comment. It is
+client identification for the authority's own accounting, never decision input, and it is sent only
+when a call is made at all.
+
+`printDecision(decision, { out })` writes what Decionis said, when it was asked, and nothing when
+it was not: the governing verdict, the hosted verdict with its standing (`governs`, `recorded
+beside the local verdict`, or `failed closed`), the dossier identifier, the page that verifies it
+when the authority attached one (`decision.hosted.verificationUrl`), and the command that verifies
+it offline. Pass `out: process.stderr` where stdout is a transport, as in a stdio MCP server, and
+`verifyCommand` to name your own verification step; the default names this repository's
+`pnpm decionis:verify <dossier-id>`, which fetches the signed record with your key and checks its
+Ed25519 proof bundle against the authority's public JWKS offline.
+
+### One variable, a key issued in the run
+
+`createHostedGate` is `createGate` with one more way onto Decionis, for the moment a developer has
+nothing but a clone:
+
+```ts
+import { createHostedGate, printHostedOutcome } from "@decionis/agent-safe-pipeline";
+
+const gate = await createHostedGate({
+  local: createFixtureAuthorityPair(() => "BLOCK", { unsafeAllowDevelopmentFixture: true }),
+  tenantId: "00000000-0000-4000-8000-000000000001",
+  source: { repo: "owner/name", example: "basic-agent", surface: "github" },
+});
+const decision = await gate.authority.evaluate(captured);
+await printHostedOutcome(gate, decision);
+```
+
+| `DECIONIS_HOSTED` | `DECIONIS_API_KEY` | What runs                                                                                                                                                                                                                                  |
+| ----------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| unset             | unset              | The local pair, untouched; `printHostedOutcome` writes one hint line.                                                                                                                                                                      |
+| any               | set                | Exactly `createGate`: the key and `DECIONIS_TENANT_ID` from the environment, in `DECIONIS_MODE`.                                                                                                                                           |
+| `1`               | unset              | The credential this user keeps for this authority (`agentsafe login`, or an earlier run), else a free provisional workspace minted now from `POST /v1/public/agents/provision`, stored for the next run, and named on standard error once. |
+
+A provisional workspace needs no account, no email and no card; its key evaluates in `SHADOW`
+only, so the local verdict still governs and the hosted decision and its signed Decision Dossier
+are recorded beside it. The credential lives in `$AGENTSAFE_HOME`, else
+`$XDG_CONFIG_HOME/agentsafe`, else `~/.config/agentsafe/credentials.json`, readable by its owner
+alone, the same file `agentsafe login` writes; `NODE_ENV=production` refuses the whole path, as
+it refuses every stored login. `resolveHostedCredentials` is the same resolution for a process
+that is not a gate, such as the trusted executor. The provisioning call carries the client
+identification (`repo`, `example`, `surface`) in its `User-Agent`, and nothing else about the
+machine.
+
+`printHostedOutcome(gate, decision, { out })` is how an example ends: `printDecision`, then the
+signed record itself, fetched with the run's own key from `GET /v1/protocol/dossiers/{id}`
+(`gate.fetchDossier`) and shown by its proof: the algorithm, the key, when it was issued, how many
+artifacts it covers, and the issuer tier, `provisional_anonymous` for a workspace without an
+account. `fetchSignedDossier`, `summarizeDossier` and `printSignedDossier` are the parts.
+
+## Local testing
+
+`@decionis/agent-safe-pipeline/testing` ships `LocalPresence` and `LocalAuthority`: loopback doubles
+that the production clients talk to unchanged. They enforce the structural intent-hash binding,
+verify receipts the way Decionis does, issue single-use grants, orchestrate managed escalations, and
+record finalization. The person's ceremony becomes a method call.
+
+```ts
+import { DecionisGate, DecionisGrantVerifier } from "@decionis/agent-safe-pipeline";
+import {
+  LocalAuthority,
+  LocalPresence,
+  LOCAL_AUTHORITY_API_KEY,
+} from "@decionis/agent-safe-pipeline/testing";
+
+const presence = new LocalPresence({ autoComplete: "MANUAL", roles: { "synthetic-cro": "CRO" } });
+const authority = new LocalAuthority({ presence });
+await presence.start();
+await authority.start();
+
+const gate = new DecionisGate({
+  baseUrl: authority.baseUrl,
+  apiKey: LOCAL_AUTHORITY_API_KEY,
+  allowInsecureLoopback: true,
+});
+// ... evaluate, then complete the ceremony with presence.approve(requestId)
+// and assert on grants, receipts, and recorded commits.
 ```
 
-| Outcome                           | Execution behavior                                   |
-| --------------------------------- | ---------------------------------------------------- |
-| ALLOW plus valid single-use grant | Consume grant, then invoke registered handler        |
-| ESCALATE                          | Stop; obtain Presence receipt and ask Decionis again |
-| BLOCK or any error/mismatch       | Fail closed; do not invoke handler                   |
+Both doubles bind to `127.0.0.1` on an ephemeral port and refuse to construct under
+`NODE_ENV=production`. The testing entry also exports the development fixture primitives
+(`createFixtureAuthorityPair`, `FixtureDecisionAuthority`, `FixtureAuthorizationVerifier`,
+`InMemoryReplayStore`). Those remain available at the package root until 1.0; new code should import
+them from the testing entry. See
+[local testing](https://github.com/decionis/agent-safe-pipeline/blob/master/docs/local-testing.md).
+
+## API overview
+
+| Concern        | Exports                                                                                           | Role                                                                                           |
+| -------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Intent         | `IntentCapture`, `CanonicalIntentHasher`, `ExecutionIntentSchema`, `AgentProposalSchema`          | Build the immutable `agent-safe.intent/1` binding and its canonical SHA-256 hash               |
+| Decision       | `DecionisGate`, `DecisionAuthority`, `GateDecision`, `FailClosedDecision`                         | Obtain an independent `ALLOW` / `ESCALATE` / `BLOCK` decision with dossier identifiers         |
+| Selection      | `createGate`, `ShadowGate`, `SelectedGate`, `HostedEvaluation`, `printDecision`                   | Choose local, shadow, or enforcement from the environment; combine and report the two verdicts |
+| Human approval | `PresenceApprovalCoordinator`, `ManagedEscalationRequest`, `HumanApprovalEvidence`                | Coordinate DIRECT Presence ceremonies or request MANAGED orchestration by Decionis             |
+| Execution      | `SafeExecutor`, `ActionRegistry`, `DecionisGrantVerifier`, `AuthorizationVerifier`, `ReplayStore` | Claim the single-use grant, validate parameters, invoke a sealed handler, finalize the attempt |
+| Effect         | `AuthorityEffectEvidence`, `AuthorityEffectReport`, `DecionisGrantVerifier.effectReport`          | Forward a trusted runtime's downstream observation on finalize and read the authority's answer |
+| Observation    | `ShadowPipeline`, `ShadowObservation`                                                             | Record what the authority would have decided without granting execution                        |
+| Audit          | `AuditRecorder`, `AuditEventV1`, `AuditSink`                                                      | Emit immutable, redacted lifecycle records through one bounded sink call                       |
+| Testing        | `LocalPresence`, `LocalAuthority`, `createFixtureAuthorityPair` (from `/testing`)                 | Loopback doubles and fixture authorities for development and CI                                |
+
+The seam between this package and Decionis is two interfaces, `DecisionAuthority` and
+`AuthorizationVerifier`, plus a published OpenAPI contract. Anyone can implement the interfaces; the
+library checks no plan, key, or entitlement.
+
+## Production invariants
+
+1. Agent input contains only the proposed action, target, and parameters. Tenant, actor, downstream
+   target, and credentials come from trusted runtime configuration.
+2. The exact canonical intent is hashed and expires quickly.
+3. Decionis decides independently. Network errors, malformed responses, missing grants, and binding
+   mismatches fail closed.
+4. Presence proves a human approved that exact intent. It never authorizes execution; Decionis
+   verifies the receipt and re-evaluates policy.
+5. The grant is bound to the intent, decision, audience, and expiry, and is claimed atomically before
+   the handler runs. The attempt is finalized afterwards as evidence, never as authority.
+6. Downstream credentials exist only behind the trusted executor.
+7. Every decision is evidence-bearing. An `ALLOW` without a dossier identifier or grant is refused
+   as non-executable. A dossier identifier is never an execution credential.
+
+Read the [trust boundary](https://github.com/decionis/agent-safe-pipeline/blob/master/docs/trust-boundary.md)
+and the [threat model](https://github.com/decionis/agent-safe-pipeline/blob/master/THREAT-MODEL.md)
+before integrating a real downstream API.
+
+## Assurance and supply chain
+
+The reviewer's route through all of it, with what each piece of evidence establishes and what it
+does not, is
+[EVALUATION-PATH.md](https://github.com/decionis/agent-safe-pipeline/blob/master/EVALUATION-PATH.md).
+
+- **Provenance.** Every release is published through npm trusted publishing with a provenance
+  attestation, from a keyless-signed release tag, and archived under Zenodo concept DOI
+  [`10.5281/zenodo.22312955`](https://doi.org/10.5281/zenodo.22312955).
+- **Release evidence.** Each GitHub release carries the tarball, a CycloneDX SBOM, Sigstore
+  provenance and SBOM attestations, and a checksum file. See
+  [reproducible builds](https://github.com/decionis/agent-safe-pipeline/blob/master/docs/reproducible-builds.md).
+- **Testing.** Coverage gates of 90% lines, functions, and statements and 85% branches; mutation
+  testing on the trust boundary; deterministic property-based fuzzing of canonical intent handling;
+  a loopback wire-contract harness that exercises the packed package over real HTTP.
+- **Adversarial proof.** The
+  [golden adversarial demo](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/golden-adversarial-demo)
+  runs one legitimate path and eight attacks against the same boundary, offline, and exits 0 only
+  when exactly one action executes.
+- **Scanning.** CodeQL, secret scanning, OpenSSF Scorecard, and OpenSSF Best Practices, with
+  separate production and toolchain dependency audits. The control-to-artifact map is in
+  [SECURITY-EVIDENCE.md](https://github.com/decionis/agent-safe-pipeline/blob/master/SECURITY-EVIDENCE.md).
+
+## Examples
+
+Runnable, offline, and fixture-backed unless noted. Each one uses this package unchanged.
+
+- [`basic-agent`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/basic-agent): the smallest `BLOCK` flow.
+- [`shopify-refund-agent`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/shopify-refund-agent): amount-based `ALLOW` / `ESCALATE` / `BLOCK`.
+- [`github-deploy-agent`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/github-deploy-agent): environment and force-push controls.
+- [`procurement-agent`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/procurement-agent): an in-budget request held by policy.
+- [`mcp-tool-gate`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/mcp-tool-gate): a real stdio MCP server with a governed tool.
+- [`local-escalation`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/local-escalation): DIRECT and MANAGED Presence escalation against loopback doubles.
+- [`presence-live-approval`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/presence-live-approval): DIRECT Presence enforcement against the real services with a FIDO2 or FIDO2-plus-liveness ceremony (needs credentials).
+- [`presence-managed-approval`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/presence-managed-approval): Decionis-managed Presence orchestration against the real services (needs credentials).
+- [`golden-adversarial-demo`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/golden-adversarial-demo): one golden path, eight attacks, zero unauthorized executions.
+- [`whisper-boundary-demo`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/whisper-boundary-demo): the same proof for a shopping agent — six attacks, zero unauthorized effects.
+- [`crm-outreach-demo`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/crm-outreach-demo): who can approve a sales agent's CRM update or outbound message — six attacks, a lost provider response reconciled once, zero unauthorized effects.
+- [`trusted-executor`](https://github.com/decionis/agent-safe-pipeline/tree/master/examples/trusted-executor): the proof of `@decionis/agentsafe`, the execution boundary as one deployable process — an HTTP trusted executor in front of these components — over real HTTP against the loopback doubles, and the adopter's template; the image, Kubernetes manifest and shadow-to-enforcement runbook are in the repository's [deployment kit](https://github.com/decionis/agent-safe-pipeline/blob/master/deploy/README.md).
+
+## Open core
+
+This package and the repository's architecture, intent contract, execution boundary, client
+adapters, audit contract, shadow mode, conformance vectors, and examples are Apache-2.0. The sole
+license exception is the dedicated MIT-licensed Claude Desktop wrapper in
+`packages/commerce-mcp-claude-extension`; the CommerceGate runtime it bundles remains Apache-2.0.
+Decionis operates the policy control plane behind `DecionisGate`: policy evaluation, grant issuance
+and atomic consumption, Decision Dossier signing and retention, and Presence.
+[OPEN-CORE.md](https://github.com/decionis/agent-safe-pipeline/blob/master/OPEN-CORE.md) states the
+boundary and the commitments that keep it stable.
+
+## Research
+
+Decionis Research defines the architecture, this package demonstrates it as tested code, and the
+Decionis platform operates it as a hosted authority.
+
+The banking profile of the protocol, whose reference runtime builds on this package, is published at
+[banking.decionis.com](https://banking.decionis.com) (BEAP v1.0, published 2026-09-15; the profile
+Decionis publishes and implements, not a standard approved by any body). The Commerce Gate this repository's MCP server fronts is at
+[commerce.decionis.com](https://commerce.decionis.com).
+The proof-of-human infrastructure this package's `PresenceApprovalCoordinator` coordinates with is
+described at [decionis.com/proof-of-human-infrastructure](https://decionis.com/proof-of-human-infrastructure)
+and runs at [presence.decionis.com](https://presence.decionis.com); production enforcement there is
+sales-assisted.
+
+- Jejelowo, Festus. "The Execution Verifiability Gap: Why Model Governance Cannot Authorize
+  Consequential Actions." Decionis Research, version 1.0, 21 August 2026.
+  [Canonical article](https://decionis.com/research/execution-verifiability-gap) ·
+  [Archival PDF](https://decionis.com/research/execution-verifiability-gap-v1.0.pdf)
+
+To cite the software, use the
+[CITATION.cff](https://github.com/decionis/agent-safe-pipeline/blob/master/CITATION.cff) in the
+repository or the Zenodo record above.
+
+## Support and license
 
-Presence transport/schema failures and Decionis reauthorization failures return stable fail-closed
-decisions; raw downstream error text is never part of the coordinator result.
+- Vulnerabilities: [GitHub private vulnerability reporting](https://github.com/decionis/agent-safe-pipeline/security/advisories/new) or `security@decionis.com`. Never open a public issue for a security report.
+- Everything else: [GitHub Issues](https://github.com/decionis/agent-safe-pipeline/issues).
+- Architecture and full documentation: [Agent-Safe Pipeline README](https://github.com/decionis/agent-safe-pipeline#readme).
 
-Support: use [GitHub private vulnerability reporting](https://github.com/decionis/agent-safe-pipeline/security/advisories/new) or `security@decionis.com` for vulnerabilities and [GitHub Issues](https://github.com/decionis/agent-safe-pipeline/issues) for non-sensitive problems. Architecture: [Agent-Safe Pipeline README](https://github.com/decionis/agent-safe-pipeline#readme). License: Apache-2.0. Trademark terms: [TRADEMARKS.md](https://github.com/decionis/agent-safe-pipeline/blob/master/TRADEMARKS.md).
+Apache-2.0. Trademark terms in
+[TRADEMARKS.md](https://github.com/decionis/agent-safe-pipeline/blob/master/TRADEMARKS.md).

package/dist/Index.d.ts

@@ -1,14 +1,23 @@
 export * from "./approval/PresenceApprovalCoordinator.js";
+export * from "./audit/AuditRecorder.js";
+export * from "./decision/CreateGate.js";
 export * from "./decision/DecisionAuthority.js";
 export * from "./decision/DecionisGate.js";
 export * from "./decision/FixtureDecisionAuthority.js";
+export * from "./decision/Provision.js";
+export * from "./decision/ShadowGate.js";
 export * from "./execution/ActionRegistry.js";
 export * from "./execution/AuthorizationVerifier.js";
 export * from "./execution/ReplayStore.js";
 export * from "./execution/SafeExecutor.js";
+export type { ClientSource } from "./http/ClientIdentification.js";
+export * from "./http/StoredCredentials.js";
 export * from "./intent/CanonicalIntentHasher.js";
 export * from "./intent/ExecutionIntent.js";
 export * from "./intent/IntentCapture.js";
 export * from "./intent/JsonValue.js";
+export * from "./report/DecisionReport.js";
+export * from "./report/DossierReport.js";
+export * from "./report/HostedOutcome.js";
 export * from "./shadow/ShadowPipeline.js";
 //# sourceMappingURL=Index.d.ts.map

package/dist/Index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Index.d.ts","sourceRoot":"","sources":["../src/Index.ts"],"names":[],"mappings":"AAAA,cAAc,2CAA2C,CAAC;AAC1D,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"Index.d.ts","sourceRoot":"","sources":["../src/Index.ts"],"names":[],"mappings":"AAAA,cAAc,2CAA2C,CAAC;AAC1D,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,YAAY,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC"}

package/dist/Index.js

@@ -1,14 +1,22 @@
 export * from "./approval/PresenceApprovalCoordinator.js";
+export * from "./audit/AuditRecorder.js";
+export * from "./decision/CreateGate.js";
 export * from "./decision/DecisionAuthority.js";
 export * from "./decision/DecionisGate.js";
 export * from "./decision/FixtureDecisionAuthority.js";
+export * from "./decision/Provision.js";
+export * from "./decision/ShadowGate.js";
 export * from "./execution/ActionRegistry.js";
 export * from "./execution/AuthorizationVerifier.js";
 export * from "./execution/ReplayStore.js";
 export * from "./execution/SafeExecutor.js";
+export * from "./http/StoredCredentials.js";
 export * from "./intent/CanonicalIntentHasher.js";
 export * from "./intent/ExecutionIntent.js";
 export * from "./intent/IntentCapture.js";
 export * from "./intent/JsonValue.js";
+export * from "./report/DecisionReport.js";
+export * from "./report/DossierReport.js";
+export * from "./report/HostedOutcome.js";
 export * from "./shadow/ShadowPipeline.js";
 //# sourceMappingURL=Index.js.map

package/dist/Index.js.map

@@ -1 +1 @@
-{"version":3,"file":"Index.js","sourceRoot":"","sources":["../src/Index.ts"],"names":[],"mappings":"AAAA,cAAc,2CAA2C,CAAC;AAC1D,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"Index.js","sourceRoot":"","sources":["../src/Index.ts"],"names":[],"mappings":"AAAA,cAAc,2CAA2C,CAAC;AAC1D,cAAc,0BAA0B,CAAC;AACzC,cAAc,0BAA0B,CAAC;AACzC,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAE5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,mCAAmC,CAAC;AAClD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,4BAA4B,CAAC"}