> For the complete documentation index, see [llms.txt](https://cerebral-systems.gitbook.io/cerebral-systems-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cerebral-systems.gitbook.io/cerebral-systems-docs/architecture.md).

# Architecture

Warrant is the **proposal → gate → execute → audit** triad, lifted out of the `mesh` runtime and made vendor-neutral so any external agent can drive it.

### The narrow waist

The unit of work is an **action proposal**: not "run this command" but a justified, blast-radius-scoped request to take one bounded action.

```
ActionProposal ──▶ Trusted Catalog ──▶ PolicyGate ──▶ Verdict {allow | deny | needs_approval}
                                     │
                          allow / approved
                                     ▼
                                 Durable execution job
                                     │
                                     ▼
                                 Actuator (registered, allowlisted, idempotent)
                                     │
                                     ▼
                                 AuditLog (sequenced hash-chained event stream)
```

Each box is a stable interface (see `src/warrant/`):

* **`PolicyGate.evaluate(proposal) -> Verdict`** — pure function of a proposal plus tenant policy. No side effects.
* **`OperationCatalog`** — operator-reviewed minimum risk, closed parameter schema, effects, reversibility, actuator binding, and pinned MCP schema for each operation.
* **`Actuator.execute(action) -> ActuatorResult`** — the only thing that touches the outside world. Registered by the developer; bounded by an allowlist.
* **`AuditLog.append(event)`** — canonical, sequenced event envelopes bind the full proposal commitment, authenticated principal, effective semantics, verdict, and policy/catalog hashes. Strict tenants require signed leaves.

API-key or session context supplies `authenticated_principal`. Proposal `actor`, risk, `on_behalf_of`, and request-body approver values are retained as claims, never trusted as audit identity. Durable jobs use `tenant_id:proposal_id` downstream idempotency keys; leased attempts can be reclaimed after expiry without changing that key.

### End-to-end runtime flow

1. An agent authenticates and submits an `ActionProposal`. Warrant derives `authenticated_principal` from the API key or hosted session; submitted actor and risk fields remain non-authoritative claims.
2. The current tenant catalog resolves `target_system.operation`, validates the closed parameter schema, and raises the effective risk to at least the reviewed minimum.
3. The side-effect-free policy gate returns `allow`, `needs_approval`, or `deny` using the effective risk and explicit system/operation allowlists.
4. An `allow`, or a later approval by an authenticated approver, atomically updates the action record, appends the audit event, and creates one durable execution job.
5. Warrant tries a newly queued job inline. If it cannot reach a terminal result, the HTTP response is `202` with a polling URL.
6. A worker leases the job and passes the stable `tenant_id:proposal_id` idempotency key, attempt number, catalog hash, and deadline to the actuator.
7. Successful work becomes `executed`; permanent failure becomes `execution_failed`. Retryable or ambiguous idempotent work returns to `execution_pending` with bounded backoff. Unsafe ambiguity becomes `outcome_unknown`.
8. Audit verification recomputes the proposal commitment, event sequence, principal, effective semantics, verdict, policy/catalog commitments, approval, and execution result.

### Trust boundary and non-goals

| Warrant guarantees                                                                          | Warrant does not guarantee                                                                                                          |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Actions routed through the gateway cannot execute before `allow` or authenticated approval. | An agent cannot bypass Warrant when it still has direct credentials, unrestricted shell/network access, or another tool connection. |
| Catalog risk and closed schemas override caller claims.                                     | The catalog is correct; operators must review and maintain its semantics and schema pins.                                           |
| Warrant-side claims, leases, and transitions are durable and replay-safe.                   | Exactly-once downstream effects from an actuator that ignores the idempotency key.                                                  |
| Signed/hash-bound evidence detects covered-field and event-order tampering.                 | Public-key non-repudiation or signing-key custody; strict leaves use a deployment-managed HMAC secret.                              |
| The bounded verifier checks the supplied world model for forbidden reachable states.        | That agent reasoning is correct, the supplied model is complete, or an unbounded theorem has been proved.                           |

Credential custody and raw process/network egress enforcement are separate controls. Policy and catalog revisions carry authenticated authors and hash commitments, but are not yet a separate globally signed control-plane event chain.

### Extraction map (from `mesh`)

Warrant does not reinvent these; it generalizes battle-tested code.

| Warrant concept     | Source in `mesh`                                               | Generalization applied                                                                           |
| ------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `ActionProposal`    | `shared/mesh_runtime/schemas/decision.schema.json`             | `decision_type` / `system` enums → open `target` + `operation` strings; SRE fields made optional |
| `PolicyGate`        | `services/evaluation/service.py::EvaluationService.evaluate()` | decouple from investigation-quality / SRE-judge stages; policy becomes tenant data, not code     |
| `Verdict`           | `shared/mesh_runtime/schemas/evaluation-result.schema.json`    | `final_recommendation: execute\|human_review\|reject` → `allow\|needs_approval\|deny`            |
| `Actuator` registry | `services/actuators/service.py` adapters                       | adapter `(parameters: dict) -> ActuatorResult` becomes a public plugin interface                 |
| `AuditLog`          | `shared/mesh_runtime/merkle.py` + `run_events.py`              | reused as-is; exposed as a first-class export                                                    |
| Dry-run / replay    | `services/simulation/`                                         | becomes the SDK `--dry-run` backend                                                              |

### The key decoupling

In `mesh`, the gate only ever sees `Decision`s produced by mesh's own investigation loop, and the actuators are SRE-specific (Kubernetes, ArgoCD, feature flags). For external developers:

1. The gate must accept a proposal from **any** agent.
2. The actuators must be **registered by the developer**, not hardcoded.

So `target_system` and `operation` are open strings in the Warrant proposal schema, and mesh's concrete actuators become *reference implementations*, not the contract.

### Out-of-process boundary

The gateway now runs as a multi-tenant HTTP platform (API keys, per-tenant policies and stores, Postgres-backed persistence) behind the same `/v1` contract the Phase 1 curl test defined. The gate, the actuator registry, and the audit log remain stable interfaces.

### Verification boundary

Warrant does not verify an agent's reasoning. It verifies the boundary where agent intent becomes an external side effect.

The verifier models a typed world signature, transition actions, invariants, and the same policy gate used at runtime. With a signature, undeclared systems, operations, resources, capabilities, or effects fail closed instead of silently severing a graph edge and reporting a partial model as safe.

Model inputs stay small and product-owned:

* `warrant.importers.github_actions.import_workflows` maps workflow dispatch, secrets, and command effects into verifier actions.
* `warrant.importers.oauth_scopes.import_scope_grant` maps Slack/GitHub OAuth scopes into capability bounds.
* `warrant.importers.action_history.import_action_history` drafts least-privilege policy from traffic already routed through Warrant.
* `warrant.mcp_surface` may record MCP `_meta.warrant` for informational verification input, but self-description cannot complete enforcement coverage or create actuator routing; those require operator-reviewed overlays/catalogs.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cerebral-systems.gitbook.io/cerebral-systems-docs/architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.