Metrology Lab

A metrology lab is the governance authority of a Mandrel mesh: the trusted bridge between static agent development (the CLI) and secure runtime execution (the Collet). It is the Promotion Authority — no agent operates under full Mandrel governance without being measured, certified and signed.

The name references precision manufacturing metrology, the science of measurement, reflecting its role in quantifying and certifying an agent’s behavioral envelope.

The Lab and a lab

The distinction matters more than it looks.

Anything satisfying the contract is a metrology lab. The managed service is one conforming implementation; a CI pipeline holding a signing key is another. The Collet was built against the contract and has never heard of either.

That is deliberate. The Collet never calls a lab to verify a Realized Spec — verification is offline by construction, checking a signature against a key it already holds. So producing realized specs needs no HTTP server, no database and no uptime. See the metrology contract for the conformance profiles and what the minimum deployment actually requires.

Functional Features

The Metrology Lab role encompasses several critical governance responsibilities:

The Promotion Gate

When mandrel-cli agents promote is called, the lab runs the promotion gate:

1. Validates the spec against the same rules as mandrel-cli validate (same E0xx codes).
2. Applies platform policy baking: numeric ceilings use min(spec, platform); models on the platform deny-list cause outright rejection (L001).
3. Computes spec_hash over the RFC 8785 canonical form of the source spec block. If an approved, unexpired realized spec already carries the same hash, it is returned unchanged — idempotent promotion, so formatting-only changes do not re-trigger signing.
4. Resolves workload references: path-only entries and tag:spiffe-auth are bound to the platform’s trust domain, and an absolute reference naming an unfederated domain is rejected.
5. Signs the whole document with the lab’s active key, producing a compact JWS at the top-level signature field.
6. Stores and returns the promoted MandrelSpec.

The status block

A realized spec is a MandrelSpec with a status block added at the top level by the lab at promotion time. The Collet distinguishes raw from realized by the presence and validity of this block.

status:
  phase: approved                          # pending | approved | rejected | revoked
  promotedAt: "2026-05-07T09:00:00Z"
  promotedBy: "metrology-lab-a1b2c3d4"
signature: "eyJhbGciOiJFZERTQSIsImtpZCI6ImExYjJjM2Q0In0..."

signature is top-level, a sibling of status rather than a member of it, and covers the entire document except itself. That includes status.phase, which gates the first enforcement decision — leaving it unsigned would put an unauthenticated field in front of every subsequent check.

The payload carries sub, iss, iat, exp, phase, and two hashes: doc_hash over the document minus the signature, and spec_hash over the source spec block. Expiry is the JWT exp claim, not a separate YAML field.

An enforcement engine fails closed on any of: absent status, phase != approved, invalid signature, expired token, doc_hash mismatch, or a phase claim disagreeing with status.phase.

The algorithm belongs to the key

The contract does not fix a signature algorithm — any the operator’s infrastructure supports is permitted, so a client whose HSM lacks a particular primitive is not excluded from hosting a lab. EdDSA is what the reference implementation uses.

That agility carries one requirement, and it is normative for anyone implementing the role:

A verifier resolves the key by kid from its key provider, reads the expected algorithm from that key entry, and rejects the token if the header disagrees. It must not select a cryptographic primitive based on the token’s alg.

Once more than one algorithm is admissible, a verifier that trusts the token’s alg is open to the standard JWS confusion attacks — alg: none, or naming a symmetric algorithm so the public key is used as an HMAC secret. Resolving the key first makes both a mismatch between two values an attacker does not control together.

Promotion diagnostics

API Surface

Authentication: JWT Bearer (OIDC) on all protected endpoints. X-Mandrel-Lab-Key is accepted in dev mode (--dev-api-key). GET /v1/health and GET /v1/identity/jwks are unauthenticated.

Agent Card endpoints

Reference data endpoints

Infrastructure endpoints

Key Distribution

The lab publishes all active signing public keys at GET /v1/identity/jwks as an OKP/Ed25519 JWK Set. Multiple keys are present simultaneously during rotation overlap; the Collet selects the correct key using the kid claim in the JWS header.

The Gantry’s MandrelPlatformConfig CRD carries pre-distributed copies of these keys as K8s Secrets — an offline fallback for air-gapped environments.

Signing Strategies

The lab’s signing key is sourced via a KeyProvider strategy, selected at startup:

High-Assurance Implementation

While the Mandrel project defines the standard interface for a Metrology Lab, our Managed Service Provider (MSP) implementation provides the high-assurance backbone required for enterprise-grade agentic meshes:

• Isolated Intent Classification: Utilizes a dedicated, hardened LLM environment to classify user intents, eliminating the risk of prompt injection from the agent’s primary task model.
• Hardware-Backed Signing: Integration with FIPS 140-2 Level 3 Hardware Security Modules (HSMs) for all cryptographic spec attestation and signing.
• Continuous Policy Re-evaluation: Automatically triggers agent re-promotion and CAE-driven revocation when global platform policies or risk thresholds change.
• Golden Dataset Benchmarking: Built-in integration with the Metrology Lab Registry to run performance-risk benchmarks as a mandatory promotion gate.
• Continuous Conformance & Drift Mitigation: Periodic re-evaluation of promoted agents against evolving “Golden Datasets” and new threat vectors, ensuring long-term behavioral integrity without manual developer intervention.

The Promotion Gate

# 1. Obtain a token (OIDC device flow)
mandrel-cli auth login --issuer https://accounts.google.com \
                       --audience mandrel-metrology-lab

# 2. Register and promote an agent
mandrel-cli agents register --file finance-agent.yaml \
                            --metrology-lab https://lab.mandrel.internal:8740
mandrel-cli agents promote finance-specialist \
                          --metrology-lab https://lab.mandrel.internal:8740

# 3. Inspect the realized spec (the "baked" output)
mandrel-cli agents realized finance-specialist \
                           --metrology-lab https://lab.mandrel.internal:8740

# 4. Check promotion status
mandrel-cli agents status finance-specialist \
                         --metrology-lab https://lab.mandrel.internal:8740

Administrator Workflow

Platform administrators can manage the global policy and rate tables:

# Update the global platform policy
mandrel-cli platform policy put global-policy.yaml

# Update the chip rate table
mandrel-cli platform chip-rates put rates-v2.yaml

Relationship to Other Components