Enum Principal 

pub enum Principal {
    Operator {
        id: OperatorId,
    },
    Platform {
        id: PlatformId,
    },
    Delegate {
        authorizing: Box<Principal>,
        delegate: DelegateId,
        scope: AuthorityScope,
    },
    Federated {
        trust_root: TrustRoot,
        identity: ExternalId,
    },
}

A first-class principal — the entity acting in CellOS authority chains.

Per ADR-0019 §Decision, every signed event attributes one of these four variants. Composition (Delegate.scope ⊆ authorizing.scope) is enforced by Principal::compose.

Wire form

The structured representation uses an internally-tagged enum with kind as the discriminant — see the module-level docs for the URI form. Round-trip is guaranteed: Principal::from_source_uri(p.to_source_uri()) == Ok(p) for every valid principal.

Variants

Operator

The historical case: a human operator’s bearer-token identity. Preserved as the v0.5 wire form so existing consumers round-trip byte-for-byte.

Fields

id: OperatorId

Platform

The hosted control plane itself acting on behalf of a tenant. Used for periodic compaction, tenant migration, billing snapshots.

Fields

id: PlatformId

Delegate

An LLM session / programmatic agent acting on behalf of an authorizing principal, with bounded scope. Use Principal::compose to construct — the constructor enforces the narrowing invariant.

Fields

authorizing: Box<Principal>

delegate: DelegateId

scope: AuthorityScope

Federated

An external IAM (OIDC issuer, ADO org, GitHub org) acting as a principal via federation.

Fields

trust_root: TrustRoot

identity: ExternalId

Implementations

impl Principal

pub fn root_operator(&self) -> Option<&OperatorId>

Returns Some(operator_id) iff the principal chain bottoms out at a human Principal::Operator at any depth; None otherwise. Used by compliance queries to answer ADR-0019’s “did a human author this action at any depth?” question.

pub fn effective_scope(&self) -> AuthorityScope

The effective scope a principal exposes to a downstream delegate.

• A Delegate exposes its own (already-narrowed) scope.
• Any other variant is treated as holding the root scope (AuthorityScope::root) for the purpose of composition. ADR-0019 §Out-of-scope leaves “what specific capabilities a non-delegate principal holds” to the tenancy and federated- authority ADRs; pre-ratification we treat the root as unbounded so composition does not block legitimate first delegations.

pub fn compose( authorizing: Principal, delegate: DelegateId, requested_scope: AuthorityScope, ) -> Result<Principal, AuthorityScopeViolation>

Compose a delegate principal. Returns Ok(Principal::Delegate { … }) iff requested_scope is a subset of authorizing.effective_scope(). Otherwise returns AuthorityScopeViolation naming the first non-narrowing capability — the admission discriminant delegate_scope_not_narrowing.

pub fn to_source_uri(&self) -> String

Render the CloudEvent source URI representation per ADR-0019:

• Operator: principal://operator/<id>
• Platform: principal://platform/<id>
• Delegate: principal://<chain>/delegate/<id>?scope=<csv> where <chain> is the authorizing principal’s URI body (everything after principal://, query stripped).
• Federated: principal://federated/<root_kind>/<root_id>/identity/<external_id>

The ?scope= query carries capabilities in sorted-token form (the AuthorityScope backing BTreeSet orders them), comma- separated, so the URI is canonical and to_source_uri ∘ from_source_uri is a deterministic identity on valid principals.

pub fn from_source_uri(uri: &str) -> Result<Principal, PrincipalParseError>

Parse a CloudEvent source URI back into a Principal. Returns PrincipalParseError for any input that does not match the grammar in Principal::to_source_uri.

Trait Implementations

impl Clone for Principal

fn clone(&self) -> Principal

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Principal

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Principal

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Principal

fn eq(&self, other: &Principal) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Principal

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Principal

impl StructuralPartialEq for Principal