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

// 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

# Run contract parity check
bun run contract-parity

Conformance Suite

The conformance suite validates protocol implementations across languages:

Test Suites

Running Conformance

# 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:

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:

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