Enum Principal 

pub enum Principal {
    User(PrincipalId),
    Component(ComponentId),
    System,
}

The actor performing an action.

A Principal represents identity only, not permission level. Permission is determined by the runtime layer’s Session.

Variants

Variant	Description	Typical Use
User	Human user	Interactive CLI usage
Component	Autonomous component	Background processing
System	Internal operations	Lifecycle, cleanup

Why Not Just Use ComponentId?

ComponentId identifies what is executing (LLM, Tool, etc.). Principal identifies who initiated the action.

A Tool component may execute a file write, but the Principal is the human user who requested it. This distinction enables:

• Audit trails attributing actions to users
• Permission checks based on who initiated
• Rate limiting per user, not per component

Example

use orcs_types::{Principal, ComponentId, PrincipalId};

// Human user
let user = Principal::User(PrincipalId::new());

// Component acting autonomously (e.g., scheduled task)
let component = Principal::Component(ComponentId::builtin("scheduler"));

// System internal operation
let system = Principal::System;

Variants

User(PrincipalId)

Human user identified by PrincipalId.

Represents interactive CLI usage or API calls from authenticated users.

Component(ComponentId)

Component acting autonomously.

Used when a component initiates actions without direct human involvement, such as:

• Scheduled background tasks
• Event-driven reactions
• Plugin self-maintenance

System

System internal operations.

Used for operations that are not attributable to any specific user or component:

• Lifecycle management (startup, shutdown)
• Garbage collection
• Internal housekeeping

Implementations

impl Principal

pub fn is_user(&self) -> bool

Returns true if this is a Principal::User.

pub fn is_component(&self) -> bool

Returns true if this is a Principal::Component.

pub fn is_system(&self) -> bool

Returns true if this is Principal::System.

pub fn user_id(&self) -> Option<&PrincipalId>

Returns the PrincipalId if this is a User, otherwise None.

pub fn component_id(&self) -> Option<&ComponentId>

Returns the ComponentId if this is a Component, otherwise None.

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<(), Error>

Formats the value using the given formatter.

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

fn deserialize<__D>( __deserializer: __D, ) -> Result<Principal, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Principal

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

Formats the value using the given formatter.

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 as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Principal

impl StructuralPartialEq for Principal