# Capsule Compiler

Capsulang now includes a Capsule contract frontend. Capsule describes the governance contract; Capsulang is the executable contract backend.

```text
Capsule contract
  -> Capsule IR
  -> Enclosure DSL
  -> Capsulang Authority IR and machine workflow
  -> host policy, sandbox, telemetry, receipt, attestation, and evidence bundle
```

The compiler is intentionally not a path to ambient authority. The generated Capsulang capsule computes state transitions, Authority IR, policy/gate intents, telemetry obligations, receipts, and effect intents. The host runtime still owns identity-provider integration, capability issuance, adapter execution, sandbox enforcement, ledger writes, and SIEM export.

## Commands

```bash
caps capsule-check examples/29_capsule_refund_reviewer.capsule.yaml --json
caps capsule-ir examples/29_capsule_refund_reviewer.capsule.yaml
caps capsule-compile examples/29_capsule_refund_reviewer.capsule.yaml \
  --out-dir build/capsule-refund \
  --json
```

`capsule-compile` emits the EDL bundle plus Capsule frontend artifacts:

```text
<name>.capsule.json
<name>.edl.yaml
<name>.caps
<name>.enclosure.json
<name>.docker-compose.yml
<name>.seatbelt.sb
<name>.doorkeeper.json
<name>.telemetry.json
<name>.receipts.json
<name>.negative-tests.json
<name>.attestation.json
```

The generated `.caps` file is parsed and checked before compilation reports success.

## Capsule Contract Shape

```yaml
capsule: 0.1
module: claims.refund_reviewer
version: 1.2.0

identity:
  kind: agent
  cryptographic: required
  credentials: short_lived
  attestation: required
  owner: human:ClaimsLead

effects:
  - read: CustomerDB.claims
  - call: RefundAPI.issue_refund
    max_amount_usd: 100
    approval_required_above_usd: 50

telemetry:
  required: true
  tamper_evident: true
  export: [otel, siem]

policy:
  default: deny
  escalation:
    - if: amount_usd > 50
      require: [human_approval]
```

## Validation

Capsule diagnostics reject contracts that miss the minimum control-plane posture:

- missing module, version, identity, effects, policy, or telemetry
- non-agent/service identity kinds
- missing cryptographic identity
- credentials other than `short_lived`
- missing attestation
- policy defaults other than `deny`
- escalations that do not require `human_approval`
- telemetry that is not required or tamper-evident

After Capsule validation, the compiler lowers to EDL and runs EDL enforcement checks:

- every protected effect must have a gate action
- enforce mode must deny network and ambient credentials by default
- high-risk effects must require receipts and postconditions
- high-risk effects must have approval-bound capabilities
- generated Capsulang must parse and check

## Lowering Rules

| Capsule | Lowered target |
|---|---|
| `module`, `version` | EDL name/version and Capsulang `(module ...)` / `(capsule ...)` |
| `identity` | `principal`, `mandate`, `delegation` |
| `effects` | gate actions, capabilities, policy rules, machine effect intents |
| `policy.default` | EDL authority policy default |
| `policy.escalation` | `escalate` rules plus approval-bound capabilities |
| `telemetry` | `telemetry-obligation` and telemetry manifest |
| `runtime` | enclosure, Docker Compose, Seatbelt, doorkeeper endpoint |
| `memory` | `memory-policy` |

High-risk effects are currently inferred from explicit approval thresholds, `approval_required`, writes, and sensitive effect names such as refund, deploy, and merge. They lower to single-use approval-bound capabilities and receipt-required doorkeeper actions.