cellos_core/authority/

mod.rs

//! Typed authority validator (Authority Model §14 + ADG).
//!
//! # Status — preview
//!
//! This module ships under the **`CELLOS_AUTHORITY_VALIDATOR_PREVIEW=1`** policy
//! authorized by the ADR-0005 SLA council (see
//! [Plans/cellos-code-complete-roadmap.md §7 Phase B1](../../../../Plans/cellos-code-complete-roadmap.md)).
//! At time of landing, ADR-0005 is **Proposed**; the council recommended
//! pre-merging the B2 validator scaffold behind this preview flag if the
//! ADR-0005 Accept SLA (deadline 2026-05-20) slips, so post-1.0 work has a
//! stable foundation to rest on.
//!
//! **What lands here (B2-1 / B2-2 / B2-3 + T3.A / F2):**
//!
//! * The four typed authority variants ([`ObservedAuthority`],
//!   [`ProvenAuthority`], [`ImposedAuthority`], [`DeclaredAuthority`]) —
//!   mechanically separated per
//!   [docs/authority-model.md §14](../../../../docs/authority-model.md)
//!   and [ADR-0006](../../../../docs/adr/0006-in-vm-observability-runner-evidence.md) §1.
//! * The validator function and supporting enums:
//!   [`AuthorityDerivation`], [`EpistemicStatus`], [`RuleClass`], [`Rule`],
//!   [`BindingStatus`], [`ValidationError`].
//! * The compile-fail [`GuestEventBuilder`] gate (T3.A / F2).
//! * Property tests for the §9 non-inflation invariants
//!   (see `tests` submodule).
//!
//! **What deliberately does NOT land here (B3, post-1.0):**
//!
//! * No producer (event-builder, supervisor admission, sni_proxy) wires these
//!   types in yet. The CloudEvent emitters keep producing today's untyped
//!   shape until the post-1.0 wiring slice replaces them.
//! * No JSON Schema integration with `contracts/schemas/`. The schema
//!   `cell-observability-l7-authority-evidence-v1.schema.json` lands as part
//!   of B3 (post-1.0).
//!
//! # `DeclaredAuthority` — F2 / T3.A
//!
//! [ADR-0006](../../../../docs/adr/0006-in-vm-observability-runner-evidence.md)
//! defines the fourth variant [`DeclaredAuthority`] (Tier ceiling 1,
//! epistemic status [`EpistemicStatus::Declared`]) for guest-side
//! `cellos-telemetry` declarations forwarded over the per-cell vsock
//! channel. The mono-class envelope ([`RuleClass::GuestAgentDeclaration`])
//! prevents host-side classes from co-occurring inside the same typed
//! authority. The companion [`GuestEventBuilder`] trait pins the rule-class
//! at compile time via a `const`-asserted check, so a guest event-builder
//! cannot accidentally route through a stronger class.
//!
//! # Doctrine gates
//!
//! * **D9 (mechanical separation):** the three types share no common base
//!   trait, expose no [`From`] / [`Into`] conversions between each other,
//!   and each carry their own validated [`AuthorityDerivation`]. Merging two
//!   stacks is a compile error, not a runtime contract.
//! * **D11 (no I/O in `cellos-core`):** the validator is pure. It takes
//!   plain values, returns [`Result`]. No tokio, no reqwest, no syscalls.
//!
//! # Overview
//!
//! The Authority Derivation Graph (ADG) — see
//! [docs/authority-derivation-graph.md](../../../../docs/authority-derivation-graph.md)
//! — is the canonical record of *how* an authority emission was computed.
//! Every typed authority MUST carry an [`AuthorityDerivation`] and the
//! validator enforces six invariants on construction:
//!
//! 1. **Confidence non-inflation** — `output.confidence ≤ max(inputs.confidence)`.
//! 2. **Tier ceiling** — `output.tier ≤ min(rule_class_tier_ceiling)`.
//! 3. **Epistemic determinism** — `output.epistemic_status` is the unique
//!    image of the rule-class set under the canonical mapping.
//! 4. **ADG presence** — emissions cannot construct without an ADG (gated
//!    by builder API and refused by the validator if `inputs` or
//!    `rules_applied` is empty).
//! 5. **Rule → class consistency** — every applied rule's declared class
//!    matches the canonical mapping.
//! 6. **Type-class compatibility** — `ObservedAuthority` cannot carry
//!    `CRYPTOGRAPHIC_PROOF` rules; `ProvenAuthority` cannot be built without
//!    one; `ImposedAuthority` requires `IMPOSED_INTERCEPTION`.
//!
//! See submodule [`validator`] for the typed-authority constructors and
//! [`crate::authority::tests`] (cfg(test)-only) for the property tests.

#![deny(missing_docs)]

mod validator;

/// T2-B21 — typed result variants for `verify_authority_derivation`.
///
/// Sibling to [`validator`] (which hosts the ADR-0006 typed-authority
/// builders). This submodule is the foundation for the typed-validator
/// scaffold from PR #40 / T2.A: it gives admission-side callers a pattern-
/// matchable result enum without disturbing the existing
/// `Result<(), CellosError>` public surface.
pub mod derivation_result;

/// F2 — guest-declared capability surface and the subset validator the host
/// runs before accepting in-VM telemetry.
///
/// Companion to [`validator`]'s ADG-validated [`DeclaredAuthority`] (the
/// *evidence* form). This submodule ships [`declared::DeclaredAuthoritySurface`]
/// (the *surface* form, three plain fields) plus
/// [`declared::validate_declared_authority_surface`], the subset check the
/// supervisor runs before accepting any guest declaration. See the module
/// docs in [`declared`] for the evidence-vs-surface split.
pub mod declared;

#[cfg(test)]
mod tests;

pub use validator::{
    canonical_class_for_rule, epistemic_for_class_set, max_tier_for_class, AppliedRule,
    AuthorityDerivation, AuthorityInput, AuthorityInputType, AuthorityOutput, BindingStatus,
    DeclaredAuthority, EpistemicStatus, GuestEventBuilder, ImposedAuthority, ObservedAuthority,
    ProvenAuthority, ProvenAuthorityArtifact, Rule, RuleClass, ValidationError,
};

pub use derivation_result::{validate_authority_derivation, AuthorityValidationResult};

pub use declared::{validate_declared_authority_surface, DeclaredAuthoritySurface};