Policy System Overview

Audience: Policy authors, reviewers, and operators getting their bearings before diving into the language, lifecycle, or runtime guides. Scope: What the Policy system does, its layers and inputs, and how policies are governed and enforced online and in air-gapped sites.

Governance requirement: Policies that change reachability or trust weighting still require shadow and coverage evidence before promotion. The current Engine does not implement the Registry shadow/review/publish workflow; unavailable evidence is not a successful gate. Follow the registered lifecycle and its limits. Lifecycle source verified: 05534daa6eb60609d9b716f7a7c1db38adb74551 (2026-08-31), Program.MapPolicyPacks and PostgresPolicyPackRepository; re-verify with the lifecycle source commands. This is not live acceptance.

This overview orients authors, reviewers, and operators to the Stella Ops 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 boundary: the Engine bundle-compilation signature is an offline-testing stub, not DSSE approval/publication. Separate verdict or export attestations require their own verified path.
• Distribution design: trusted signed promotion/offline evidence remains required where used; Engine Approved metadata does not publish an artifact or attest its review.

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. Create explicit Draft metadata through /api/policy/packs/{packId}/revisions, including the approved activation requirement.
2. Compile/store the exact bundle; compilation does not approve it.
3. Obtain real governing review, coverage, shadow and determinism evidence. Registry automation is unavailable; do not turn this gap into a pass.
4. Explicitly upsert Approved metadata, then request activation through the canonical pack/revision endpoint with the configured actor threshold.
5. Verify the actual consumer independently. Activation does not start a run, publish, or archive; rollback needs its own approved procedure.

5. Governance & Roles

• The registered pack API uses policy:edit for metadata/bundles, policy:read for listing/evaluation, and policy:activate for activation. Other scopes do not enable an absent Registry workflow.
• Two-person activation is a persisted per-revision requirement resolved through PolicyEngine:Activation when metadata is created. It is not an author/reviewer separation check or publication quorum.
• AOC: Aggregation-Only Contract applies to regulated tenants—UI/CLI must respect AOC flags on policies and evidence.

6. Review Checklist (fast path)

These are governance requirements, not assertions that the Engine validates their attachments. Hold the governed operation when required evidence is unavailable.

• 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

• Preserve exact policy/source/input digests, coverage and trusted signatures through the approved offline procedure.
• Offline operation does not make Registry review/shadow/publication available. Do not credit a CLI flag or compile signature stub as a sealed rehearsal or signed approval.
• Verify the concrete owner API and package contents; automatic export of Registry approval records and publication events is not established by the pack lifecycle.

8. Key References

• Stella Policy DSL (stella-dsl@1) — language reference.
• Policy Lifecycle & Approvals — process and gates.
• Policy Runs & Orchestration — run modes and scheduling.
• Policy Runtime & Evaluation — compile, cache, and evaluate.
• Policy Governance — roles, signing, and audit.
• Policy Engine Architecture — engine internals.
• Policy implementation plan — roadmap and status.