# Policy System Overview

> **Imposed rule:** Policies that change reachability or trust weighting must enter shadow mode first and ship coverage fixtures; promotion is blocked until shadow + coverage gates pass (see `docs/policy/lifecycle.md`).

This overview orients authors, reviewers, and operators to the Stella Policy system: the SPL language, lifecycle, evidence inputs, and how policies are enforced online and in air-gapped sites.

## 1. What the Policy System Does
- Combines SBOM facts, advisories (Concelier), VEX claims (Excititor), reachability signals (Graphs + runtime), trust/entropy signals, and operator metadata to produce deterministic findings.
- Produces explainable outputs: every verdict carries rule, rationale (`because`), inputs, and evidence hashes.
- Works online or offline: policies, inputs, and outputs are content-addressed and can be replayed with no network.

## 2. Layers
- **SPL (Stella Policy Language):** declarative rules (`stella-dsl@1`) with profiles, maps, and rule blocks; no loops or network calls.
- **Compiler:** canonicalises SPL, emits IR + hash; used by CLI, Console, and CI. Canonical hashes feed attestation and replay.
- **Engine:** evaluates IR against SBOM/VEX/reachability signals; outputs effective findings and explains every rule fire.
- **Attestation:** optional DSSE over policy IR and approval metadata; Rekor mirror when online.
- **Distribution:** policy packs are versioned, tenant-scoped, and promoted via Authority scopes; Offline Kit includes packs + attestations.

## 3. Inputs & Signals
- SBOM inventory/usage (Scanner), advisories (Concelier), VEX (Excititor), reachability graphs/runtime (Signals), trust/entropy/uncertainty scores, secret-leak findings, environment metadata, and tenant policy defaults.
- Signals dictionary (normalised): `trust_score`, `reachability.state/score`, `entropy_penalty`, `uncertainty.level`, `runtime_hits`.
- All inputs must be content-addressed; missing fields evaluate to `unknown`/null and must be handled explicitly.

## 4. Lifecycle (summary)
1. Draft in SPL with shadow mode on and coverage fixtures (`stella policy test`).
2. Submit with lint/simulate + coverage artefacts attached.
3. Review/approve with Authority scopes; determinism and shadow gates enforced in CI.
4. Publish/attest (DSSE + optional Rekor); promote to environments; activate runs.
5. Archive or roll back with audit trail preserved.

## 5. Governance & Roles
- Scopes: `policy:author`, `policy:review`, `policy:approve`, `policy:operate`, `policy:publish`, `policy:activate`, `policy:audit`.
- Two-person rule recommended for publish/promote; enforced by Authority per tenant.
- AOC: Aggregation-Only Contract applies to regulated tenants—UI/CLI must respect AOC flags on policies and evidence.

## 6. Review Checklist (fast path)
- Lint + simulate outputs attached and fresh (<24h).
- Shadow mode enabled; coverage fixtures passing; twin-run determinism check green.
- `because` present on every status/severity change; suppressions scoped.
- Inputs handled explicitly when `unknown` (reachability/runtime missing).
- Attestation metadata ready (reason, ticket, IR hash) if publish is requested.
- AOC impact noted; air-gap replay steps documented if applicable.

## 7. Air-gap / Offline Notes
- Policy packs, attestations, and coverage fixtures ship in Offline Kits; no live feed calls allowed during evaluation.
- CLI `stella policy simulate --sealed` enforces no-network; policy runs must use frozen SBOM/advisory/VEX bundles and reachability graphs.
- Attestations and hashes recorded in Evidence Locker; Timeline events emitted on publish/activate.

## 8. Key References
- `docs/policy/dsl.md` (language)
- `docs/policy/lifecycle.md` (process, gates)
- `docs/policy/architecture.md` (engine internals)
- `docs/modules/policy/implementation_plan.md`
- `docs/policy/governance.md` (once published)