# Architecture

The technical and philosophical framework for engineering amorphous AI.

Source: https://mandrel-web-363efb.gitlab.io/docs/overview/architecture/

---


The Mandrel Project provides a deterministic governance layer for stochastic AI agents. It is designed to "clamp" amorphous agent behaviors to a rigid, machine-readable contract.

## Design Philosophy: Engineering the Amorphous

In high-precision manufacturing, a **Mandrel** provides internal support and defines the shape of a workpiece. Similarly, the Mandrel Project provides the deterministic axis for risk mitigation in agentic systems:

*   **The Mandrel Spec**: A declarative contract defining an agent's structural boundaries and risk envelope.
*   **The Collet (Sidecar)**: A high-performance proxy that "clamps" the agent to the spec, ensuring it never slips from security, financial, or data-sovereignty constraints.
*   **The Gantry**: An automated capability for **Agent Lifecycle Management**, including sidecar injection and SPIFFE identity provisioning.
*   **The Metrology Lab**: The **Promotion Authority** where agents are certified and signed against platform policies and "Golden Datasets" to quantify performance risk. The role it fills is defined as a portable contract, so a deployment can satisfy it with the managed service, a self-hosted lab, or a CI pipeline holding a signing key — see the [metrology contract](https://mandrel-web-363efb.gitlab.io/docs/spec/metrology-contract.md).


## Core Architectural Pillars

### 1. Runtime Mesh (Orchestrator-Specialist)
Mandrel utilizes a decoupled pattern enforced by the Collet sidecar:
- **Orchestrator**: Handles intent classification and task delegation.
- **Specialist**: An ephemeral, domain-specific worker bound to scoped infrastructure and governed by a specific Mandrel Spec.
- **Model Context Protocol (MCP)**: The standardized interface used by specialists to interact with enterprise systems (Resources, Prompts, and Tools).

For late-binding topologies where orchestrators dynamically discover and bind specialists over the network at runtime, see the white paper on [governing late-binding agent harnesses](https://mandrel-web-363efb.gitlab.io/docs/white-papers/late-binding-agent-harnesses.md).

### 2. Compound Identity (The "Double Badge")
To prevent privilege escalation and "Identity Wash," Mandrel mandates a two-factor context:
- **Machine Identity**: [SPIFFE](https://spiffe.io/) SVIDs managed by the Gantry.
- **Human Context**: User authorization propagated via OIDC and Nested JWTs (RFC 8693).

### 3. High-Assurance Governance
The architecture ensures a **Fail-Closed** posture. If the governance layer (Collet, Registry, or IdP) is unreachable or a constraint is ambiguous, the system terminates the action rather than failing-open. This assurance is maintained throughout the agent lifecycle via **Continuous Conformance Checks**, which periodically re-evaluate promoted agents against "Golden Datasets" to mitigate model and threat drift.

## Layered Workload Maturity Model

Individual agent workloads progress through four operational maturity tiers as they advance toward production. While [Enterprise Governance Maturity](https://mandrel-web-363efb.gitlab.io/docs/white-papers/enterprise-governance-maturity.md) measures overall enterprise program adoption, a mature organization enforces automated workload maturity gates to promote agents through these specific tiers:

1.  **Tier 1: Sandbox (Private)**: Rapid prototyping using read-only MCP resources.
2.  **Tier 2: Trusted (Verified)**: Agent passes `mandrel-cli validate` static checks; receives a SPIFFE ID; HITL is mandated for high-variance actions.
3.  **Tier 3: Federated (Discoverable)**: Realized Spec is signed and published to the Metrology Lab for dynamic capability discovery by orchestrators.
4.  **Tier 4: Autonomous (Scalable)**: Fully hardened runtime controls enabled, including Dynamic Client Registration (DCR) and Continuous Access Evaluation (CAE) real-time revocation.

## Logical Flow

```mermaid
graph TD
    subgraph "User Layer"
        U[Human Operator] -->|Auth| IDP[Identity Provider]
        U -->|Task| ORCH[Orchestrator Agent]
    end

    subgraph "The Mandrel Mesh"
        ORCH -->|Discovery| LAB[(Metrology Lab)]
        ORCH -.->|A2A gRPC| COL[Collet / Specialist]
    end

    subgraph "Governance Control"
        COL -.->|Evaluate| OPA{Open Policy Agent}
        COL -.->|Audit| OTEL[OpenTelemetry]
    end
```