Contract Management

Edictum Console uses a three-level model for contract management: Contract (authoring unit), Composition (assembly recipe), and Bundle (deployed artifact). This separation lets you write contracts once, reuse them across environments, and change enforcement modes without editing YAML.

The Three Levels

Contract (Authoring Unit)

A contract is an individual governance rule stored in the console's contract library. It is the smallest unit of governance -- one rule, one purpose.

Contracts are versioned. Every update creates a new version. Old versions are preserved -- you can always see what a contract looked like at any point in time.

Contract types map directly to the core library:

Composition (Assembly Recipe)

A composition is a named, ordered recipe that assembles contracts into a deployable bundle. It defines which contracts to include, in what order, and with what enforcement modes.

Each item in a composition references a contract from the library and can override its mode:

When adding contracts to a composition, the contract picker includes a Create New Contract inline action. Selecting it opens the contract editor without leaving the picker flow — the new contract is immediately available to add.

Mode resolution follows a clear precedence:

Item mode_override > Contract definition > Composition defaults_mode

• enforce -- contract failures deny the tool call
• observe -- contract failures produce audit events but do not deny
• inherit -- falls through to the composition's defaults_mode

This lets you roll out a new contract in observe mode (test it in observe mode against production traffic), then flip it to enforce when you're confident -- without editing the contract itself.

Bundle (Deployed Artifact)

A bundle is the assembled YAML artifact that agents actually enforce. It is the output of either:

1. Composing from the library -- the composition recipe assembles contracts into a YAML bundle
2. Direct upload -- raw YAML uploaded through the API or dashboard

Every bundle is signed with Ed25519 on deploy. The signature and public key are included in the SSE event so agents can verify authenticity.

Import: YAML to Library

The Import dialog accepts three YAML formats. It automatically wraps single contracts and lists into a bundle before sending to the backend — you do not need to pre-format your YAML as a bundle.

POST /api/v1/contracts/import
Body: { "yaml_content": "..." }

Single contract, list, or full bundle
    |
    +-> Contract: block-dotenv (type: pre, v1)
    +-> Contract: pii-scan (type: post, v1)
    +-> Contract: rate-limit (type: session, v1)
    +-> Contract: workspace-sandbox (type: sandbox, v1)
    +-> Contract: block-sql-injection (type: pre, v1)

Each contract extracted from the YAML becomes a library contract at version 1. Existing contracts with the same id get a new version instead of a duplicate.

Version Management

Both contracts and bundles are versioned independently:

• Contract versions: each update to a contract definition creates a new version. The old version is preserved. Compositions reference the latest version of each contract at assembly time.
• Bundle versions: each deployment (from composition or direct upload) creates a new bundle version. The diff viewer lets you compare any two versions side by side.

Contract: block-dotenv
  v1: when args.path contains ".env" -> deny
  v2: when args.path contains ".env" or ".secret" -> deny
  v3: when args.path matches ".*\.(env|secret|key)$" -> deny

Bundle: production-standard
  v1: block-dotenv(v1) + pii-scan(v1)
  v2: block-dotenv(v2) + pii-scan(v1)  <- contract updated
  v3: block-dotenv(v2) + pii-scan(v1) + rate-limit(v1)  <- contract added
  v4: block-dotenv(v3) + pii-scan(v1) + rate-limit(v2)  <- two contracts updated

The Dashboard Experience

The Contracts page has four tabs:

Drift Detection

When an agent connects via SSE, it sends its policy_version (the SHA-256 revision hash of its current bundle). The console compares this against the latest deployed bundle for that agent's environment:

Drift is visible on the fleet monitoring page. A drifted agent will pick up the latest bundle on its next SSE reconnect.

Next Steps

• Hot-Reload -- how deployed bundles reach running agents via SSE
• How It Works -- the boundary between core library and console
• Security Model -- bundle signing and key rotation