Architecture

Six primitives, an evidence pipeline, three deployment tiers. This page is the canonical description, if a behavior contradicts it, the behavior is the bug.

Six primitives

Tool

Discriminated union over dataClassification: 'public' | 'personal' | 'special_category' | 'confidential'. Each variant has different required fields. The compiler refuses constructions that omit art9Basis for special-category, subjectRef policy in Ctx, or retention.

Agent

defineAgent({ purpose, lawfulBasis, annexIIIDomain, producesArt22Decision, model, tools, output, maxSteps, retryBudget, deps }). The lawful basis is checked against each tool's retention at run start.

Loop

runAgent owns the model dispatch, tool dispatch, retry counter, and the suspend/resume branch. Providers are configured with maxRetries: 0; the loop alone decides retries against maxSteps. The loop is non-bypassable: there is no API for a tool to call a sibling except ctx.invoke(name, input), which re-enters the loop.

Evidence

Every span goes through EvidenceEmitter. Records are RFC 8785 canonicalized, hashed (SHA-256), and chained with prevHash. The chain head is the run-root. verifyChain walks the chain to confirm no record was added, removed, reordered, or modified.

Policy

PolicyEngine is the interface; CerbosPolicyEngine is the production implementation. A policy decision is allow | deny | error. error halts the run with fuze.policy.engine_error=true. There is no fallback.

Guardrails

Three phases run around the model dispatch: input, toolResult, output. Guardrails get a restricted model handle, never the raw provider. A guardrail can hard-block (halt with fuze.guardrail.hard_block=true) or annotate (record a decision and continue).

Runtime topology

Evidence pipeline

Every primitive is a discrete recordable event. The pipeline guarantees:

  • monotonic sequence
  • canonical serialization (RFC 8785)
  • forward-linked hash chain
  • pluggable sink (in-memory, daemon, sovereign object store)
  • pluggable signer (LocalKeySigner, KmsSigner)
  • pluggable transparency log

Deployment tiers

TierPolicy engineEvidence sinkSignerTransparency
DevStaticPolicyEnginein-memorynonenone
CloudCerbos WASMEU-hosted daemonLocalKeySignerEU public log
SovereignCerbos podcustomer S3 + PostgresKmsSignercustomer-witnessed log

The public surface is identical across tiers. A run authored against the Dev tier ports to Sovereign by swapping the engine, sink, and signer. No code changes inside defineAgent or defineTool.

Invariants

  • Tools never receive sibling tools.
  • Tools cannot call models.
  • Guardrails get a restricted model handle.
  • Providers run with maxRetries: 0.
  • Ctx.secrets returns opaque SecretRef. Plaintext never reaches evidence.
  • Cerbos engine error is fail-stop.
  • Lawful-basis mismatch refuses at run start.
  • subjectRef is required for non-public data classifications.
  • Annex III domain non-'none' requires an oversight tool.
  • Hash chain is non-bypassable.