---
title: Protocol & Conformance
url: https://arcana.otnelhq.com/docs/protocol
---

New in v0.4.0 

Protocol extension registry enforcement and contract parity CI.

# Protocol & Conformance

Arcana's governance protocol defines how authorization requests, approvals, and proofs are structured, signed, and verified. The protocol is enforced through an **extension registry** and validated by a **conformance test suite**.

## Extension Registry

The extension registry validates that protocol extensions are recognized and allowed:

- **Envelope validation** — Signed envelopes are checked against the registry
- **Policy bundle validation** — Policy bundles verify extension compatibility
- **Unknown field rejection** — Strict rejection of unknown mandatory fields

```javascript
// Default extension registry
const DEFAULT_EXTENSION_REGISTRY = {
  "arcana.governance.v1": true,
  "arcana.proof.v1": true,
  "arcana.approval.v1": true
}
```

## Contract Parity

Automated comparison between contract specifications and runtime implementation:

- **Approval API contract** — `contracts/approval-api.v1.yaml` vs mounted runtime API
- **Events contract** — `contracts/events.v1.json` vs emitted durable event envelopes
- **CI job** — Runs on every PR to catch drift

```bash
# Run contract parity check
bun run contract-parity
```

## Conformance Suite

The conformance suite validates protocol implementations across languages:

### Test Suites

| Suite | Language | Vectors |
| --- | --- | --- |
| TS golden crypto | TypeScript | 100 |
| TS D-10 hostile matrix | TypeScript | 15 |
| Rust independent verifier | Rust | 46 |
| SDK surface | TypeScript | 4 |
| Adapter request-hash vectors | TypeScript | 4 |

### Running Conformance

```bash
# Run all conformance suites
bun run conformance

# Run specific suite
bun run conformance --suite ts-golden
bun run conformance --suite rust-verifier
```

## Canonical Serialization

Protocol objects use deterministic serialization for signing and verification:

- **7 signature domains** — Separate domains for different object types
- **Object registry** — Typed object IDs with version tracking
- **Labels and lineage** — Provenance tracking for all objects
- **Reason-code registry** — Standardized reason codes for decisions

## SDK Compatibility

The JavaScript SDK implements the full governance surface:

```javascript
import { verifyEnvelope, verifyRunProof } from "@arcana/sdk/v2/governance"

// Verify a signed envelope
const result = verifyEnvelope(envelope, publicKey)

// Verify a RunProof
const proof = verifyRunProof(runProof)
```

### Rust SDK

The Rust SDK provides cross-language verification:

```rust
use arcana_sdk::{verify_envelope, verify_request};

// Verify envelope signature
let result = verify_envelope(&envelope, &public_key)?;

// Verify authorization request hash
let hash = verify_request(&request)?;
```

## Version Negotiation

Protocol versions are negotiated between nodes:

- **compatibleFrom** — Minimum supported version
- **compatibleTo** — Maximum supported version
- **Fail-closed** — Missing or out-of-range versions reject the bundle

## Protocol Governance

The protocol governance model defines:

- **Version lifecycle** — Draft → Stable → Deprecated → Removed
- **Deprecation policy** — Minimum 2 major versions notice
- **Security advisories** — Coordinated disclosure process
- **Extension registry** — Central registry of allowed extensions
- **Compatibility matrix** — Version compatibility documentation

## Related

- [Trust & Security](/docs/trust-boundaries) — Security model and trust boundaries
- [Enterprise](/docs/enterprise) — Fleet management and compliance
- [Desktop](/docs/desktop) — Local approval and forensic companion