# Authority IR

Authority IR is Capsulang's control-plane vocabulary for agentic authorization. It is designed to express not only what a capsule can compute, but under whose authority it may request an effect, why that authority exists, how it was delegated, which runtime boundary must contain it, and what evidence must be emitted afterwards.

The feature is intentionally an IR layer rather than an identity provider, policy engine, credential issuer, sandbox, or SIEM. Capsulang parses, checks, prints, and exports the authority model. The host runtime is still responsible for issuing credentials, evaluating live policy, executing mediated effects, enforcing sandbox profiles, and writing audit evidence.

## Design intent

Authority IR separates computation from authority:

```text
Capsulang machine/function:
  computes a checked state transition or effect intent

Authority IR:
  describes the accountable actor, mandate, delegation chain,
  scoped capability, policy decision surface, trust boundary,
  telemetry duty, and memory-governance policy around that intent
```

This gives the Capsule contract compiler a stable target: high-level governance contracts can lower to Authority IR plus ordinary Capsulang machines, effects, gates, ports, stores, and ledgers.

## Constructs

### `principal`

A principal is an accountable actor. It may be a human, organization, service, or agent. Agent principals should declare cryptographic identity material and non-static credentials.

```lisp
(principal RefundReviewer
  (kind agent)
  (identity cryptographic)
  (credential short-lived)
  (attestation required)
  (owner ClaimsLead))
```

### `mandate`

A mandate is the bounded reason a principal may act.

```lisp
(mandate RefundReviewMandate
  (issued-by ClaimsLead)
  (issued-to RefundReviewer)
  (purpose "Review and optionally issue one refund.")
  (subject refund_id)
  (scope tenant.current refund.current)
  (valid-for 30m)
  (revocable true))
```

### `delegation`

A delegation is a scoped handoff of authority from one principal to another under a mandate.

```lisp
(delegation RefundReviewDelegation
  (from ClaimsLead)
  (to RefundReviewer)
  (under RefundReviewMandate)
  (may-use RefundAPI.issue_refund RefundLedger)
  (may-delegate false)
  (expires-after 30m)
  (requires traceable-chain human-approval-for-high-risk))
```

### `capability`

A capability is a short-lived action right bound to a principal and effect intent. It is not a credential by itself. Runtime policy must still decide whether to issue or honor it.

```lisp
(capability IssueSmallRefund
  (principal RefundReviewer)
  (effect (http.call RefundAPI.issue_refund))
  (resource refund_id)
  (scope tenant.current refund.current)
  (valid-for 5m)
  (requires-mandate RefundReviewMandate)
  (requires-delegation RefundReviewDelegation)
  (revocation immediate)
  (risk medium)
  (approval RefundApprovalGate)
  (limit max-amount-usd 100))
```

### `authority-policy`

An authority policy describes the typed decision surface for live authorization. The checker verifies outcomes, defaults, and effect targets; it does not execute runtime ABAC/JIT decisions.

```lisp
(authority-policy RefundPolicy
  (input principal mandate delegation capability effect context risk)
  (outcome allow deny defer escalate)
  (default deny)
  (on allow
    (if (<= amount_usd 50)))
  (on escalate
    (if (> amount_usd 50))
    (effect (approval.request RefundApprovalGate))))
```

### `trust-boundary`

A trust boundary declares required execution-environment constraints for a capsule, module, or deployment target. The compiler can emit these into container, MXC, microVM, Kubernetes, or host-policy profiles.

```lisp
(trust-boundary RefundAgentBoundary
  (sandbox required)
  (network deny-by-default)
  (filesystem read-only)
  (egress RefundAPI)
  (secrets ambient-false)
  (attestation required)
  (capability IssueSmallRefund))
```

### `telemetry-obligation`

Telemetry is a contract duty. It must be available to ledger, tracing, audit, SIEM, or other observability systems.

```lisp
(telemetry-obligation RefundTelemetry
  (must-emit invocation.start invocation.end policy.evaluated capability.issued effect.intent effect.executed effect.denied)
  (include trace_id span_id principal_id mandate_id delegation_id capability_id contract_hash effect_intent_id)
  (export otel siem ledger)
  (tamper-evident true))
```

### `memory-policy`

A memory policy governs persistent context and agent memory.

```lisp
(memory-policy RefundMemory
  (isolation per-tenant per-session)
  (ttl untrusted-context 24h)
  (source-attribution required)
  (hash-validation on-read)
  (quarantine-on-integrity-fail true)
  (promotion requires-accepted-claim))
```

## CLI

Emit the Authority IR subset:

```bash
python -m capsulang authority-ir examples/25_authority_ir.caps
```

The payload has this top-level form:

```json
{
  "schemaVersion": 1,
  "kind": "capsulang.authority_ir",
  "module": "examples.authority_ir",
  "authority": {
    "principals": {},
    "mandates": {},
    "delegations": {},
    "capabilities": {},
    "policies": {},
    "trust_boundaries": {},
    "telemetry_obligations": {},
    "memory_policies": {}
  }
}
```

## Checker behavior

The checker validates:

- references between principals, mandates, delegations, capabilities, and gates
- effect targets used by capabilities and authority-policy rules
- authority-policy outcomes and defaults
- trust-boundary capability references
- telemetry obligations with required attribution fields
- memory-policy isolation, attribution, and integrity hints

Warnings are used for maturity gaps such as missing identity, static credentials, missing validity windows, non-tamper-evident telemetry, or missing memory isolation. Errors are used for unresolved names, incomplete required declarations, invalid effect targets, and inconsistent authority policies.

## Layering rule

Authority IR declares and verifies authority obligations. It does not grant ambient power. A live runtime should still follow this boundary:

```text
Capsulang checks and emits EffectIntent + Authority IR
Host policy evaluates allow / deny / defer / escalate
Host adapters issue credentials and execute mediated effects
Ledger/tracing systems persist evidence
Sandbox/container systems enforce lower-level containment
```