Struct World 

pub struct World { /* private fields */ }

Central manager for all Channels.

The World maintains the channel tree and provides methods for channel lifecycle management.

Channel Tree

World
  │
  ├── IO Channel (interactive)
  │     ├── Agent Channel
  │     │     ├── Tool Channel 1
  │     │     └── Tool Channel 2
  │     │
  │     └── Background Channel
  │
  └── Other Root Channels...

Thread Safety

World is not thread-safe by itself. In a concurrent environment, wrap it in appropriate synchronization primitives (e.g., Mutex).

Example

use orcs_runtime::{World, ChannelConfig, ChannelCore, ChannelState};

let mut world = World::new();

// Create a root channel
let root = world.create_channel(ChannelConfig::interactive());

// Spawn and complete a child
let child = world.spawn(root).expect("parent exists");
world.complete(child);

assert_eq!(
    world.get(&child).expect("child channel exists").state(),
    &ChannelState::Completed
);

Implementations

impl World

pub fn new() -> Self

Creates an empty World with no channels.

Use create_channel() to create root channels.

Example

use orcs_runtime::World;

let world = World::new();
assert_eq!(world.channel_count(), 0);

pub fn create_channel(&mut self, config: ChannelConfig) -> ChannelId

Creates a root channel (no parent).

Root channels have no parent and serve as entry points to the channel tree. Multiple root channels are allowed.

Arguments

• config - Configuration for the new channel

Returns

The ID of the newly created channel.

Example

use orcs_runtime::{World, ChannelConfig, ChannelCore};

let mut world = World::new();

// Create an interactive (IO) channel
let io = world.create_channel(ChannelConfig::interactive());
assert!(world.get(&io).expect("channel exists").parent().is_none());
assert_eq!(world.get(&io).expect("channel exists").priority(), 255);

// Create a background root channel
let bg = world.create_channel(ChannelConfig::background());
assert_eq!(world.channel_count(), 2);

pub fn create_channel_with_principal( &mut self, config: ChannelConfig, principal: Principal, ) -> ChannelId

Creates a root channel with a specific principal.

Arguments

• config - Configuration for the new channel
• principal - Principal for scope resolution

pub fn spawn(&mut self, parent: ChannelId) -> Option<ChannelId>

Spawns a new child channel under the given parent with default config.

The new channel starts in Running state and is registered as a child of the parent.

Uses ChannelConfig::default() for the new channel. For explicit configuration, use spawn_with().

Arguments

• parent - ID of the parent channel

Returns

• Some(ChannelId) if the spawn succeeded
• None if the parent channel does not exist

Example

use orcs_runtime::{World, ChannelConfig, ChannelCore};

let mut world = World::new();
let root = world.create_channel(ChannelConfig::interactive());

let child = world.spawn(root).expect("parent exists");
assert_eq!(world.get(&child).expect("child channel exists").parent(), Some(root));

pub fn spawn_with( &mut self, parent: ChannelId, config: ChannelConfig, ) -> Option<ChannelId>

Spawns a new child channel with explicit configuration.

The new channel starts in Running state and is registered as a child of the parent.

Arguments

• parent - ID of the parent channel
• config - Configuration for the new channel

Returns

• Some(ChannelId) if the spawn succeeded
• None if the parent channel does not exist

Privilege Inheritance

The child’s max_privilege is automatically capped by the parent’s level. This ensures privilege reduction propagates down the channel tree.

Example

use orcs_runtime::{World, ChannelConfig, ChannelCore, MaxPrivilege};

let mut world = World::new();
let root = world.create_channel(ChannelConfig::interactive());

// Spawn a background channel
let bg = world.spawn_with(root, ChannelConfig::background())
    .expect("parent exists");
assert_eq!(world.get(&bg).expect("channel exists").priority(), 10);
assert!(!world.get(&bg).expect("channel exists").can_spawn());

// Spawn a tool channel (inherits elevated from interactive parent)
let tool = world.spawn_with(root, ChannelConfig::tool())
    .expect("parent exists");
assert_eq!(world.get(&tool).expect("channel exists").priority(), 100);
assert_eq!(world.get(&tool).expect("channel exists").config().max_privilege(), MaxPrivilege::Elevated);

// Spawn from background parent (max_privilege capped to Standard)
let child = world.spawn_with(bg, ChannelConfig::tool())
    .expect("parent exists");
assert_eq!(world.get(&child).expect("channel exists").config().max_privilege(), MaxPrivilege::Standard);

pub fn spawn_with_id( &mut self, parent: ChannelId, id: ChannelId, config: ChannelConfig, ) -> Option<ChannelId>

Spawns a new child channel with a pre-determined ChannelId.

Same as spawn_with(), but the caller provides the ChannelId instead of having one generated. This is required when the caller needs to know the ID before the World is updated (e.g. to pass the ID into a tokio::spawn closure).

Returns Some(id) on success, None if the parent does not exist.

pub fn kill(&mut self, id: ChannelId, reason: String)

Kills a channel and all its descendants.

This method:

1. Recursively kills all child channels
2. Removes the channel from its parent’s child set
3. Removes the channel from the World

Arguments

• id - ID of the channel to kill
• reason - Explanation for why the channel was killed

Note

Unlike complete(), kill() removes the channel entirely from the World rather than keeping it in a terminal state.

Example

use orcs_runtime::{World, ChannelConfig};

let mut world = World::new();
let root = world.create_channel(ChannelConfig::interactive());
let agent = world.spawn(root).expect("parent exists");
let tool = world.spawn(agent).expect("parent exists");

// Killing agent also removes tool
world.kill(agent, "task cancelled".into());

assert!(world.get(&agent).is_none());
assert!(world.get(&tool).is_none());
assert_eq!(world.channel_count(), 1); // only root

pub fn complete(&mut self, id: ChannelId) -> bool

Completes a channel, transitioning it to Completed.

Unlike kill(), the channel remains in the World with its completed state preserved.

Arguments

• id - ID of the channel to complete

Returns

• true if the channel was successfully completed
• false if the channel doesn’t exist or is already in a terminal state

Example

use orcs_runtime::{World, ChannelConfig, ChannelState};

let mut world = World::new();
let root = world.create_channel(ChannelConfig::interactive());

assert!(world.complete(root));
assert!(!world.complete(root)); // Already completed

pub fn get(&self, id: &ChannelId) -> Option<&Channel>

Returns a reference to the channel with the given ID.

Returns

• Some(&Channel) if the channel exists
• None if no channel has this ID

pub fn get_mut(&mut self, id: &ChannelId) -> Option<&mut Channel>

Returns a mutable reference to the channel with the given ID.

Returns

• Some(&mut Channel) if the channel exists
• None if no channel has this ID

pub fn channel_ids(&self) -> Vec<ChannelId>

Returns all channel IDs in the World.

The order is not guaranteed.

pub fn channel_count(&self) -> usize

Returns the total number of channels.

pub fn is_descendant_of(&self, child: ChannelId, ancestor: ChannelId) -> bool

Checks if child is a descendant of ancestor.

A channel is a descendant if there’s a path from it to the ancestor through parent relationships. A channel is NOT its own descendant.

Performance

Uses cached ancestor path for O(depth) lookup with cache-friendly sequential memory access (DOD optimization).

Arguments

• child - ID of the potential descendant
• ancestor - ID of the potential ancestor

Returns

true if child is a descendant of ancestor, false otherwise.

Example

use orcs_runtime::{World, ChannelConfig};

let mut world = World::new();
let root = world.create_channel(ChannelConfig::interactive());
let child = world.spawn(root).expect("parent exists");
let grandchild = world.spawn(child).expect("parent exists");

assert!(world.is_descendant_of(child, root));
assert!(world.is_descendant_of(grandchild, root));
assert!(world.is_descendant_of(grandchild, child));
assert!(!world.is_descendant_of(root, child)); // parent is not descendant
assert!(!world.is_descendant_of(root, root));  // not own descendant

Trait Implementations

impl Debug for World

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

Formats the value using the given formatter.

impl Default for World

fn default() -> Self

Returns the “default value” for a type.