Tutorial: Complete Cyb OS Cell in Rs

This example demonstrates all seven Rs primitives working together in a single file.

// edition = "rs" (set in Cargo.toml: edition = "rs")

use rs_lang::prelude::*;

// Hardware register for network DMA
#[register(base = 0x4000_0000, bank_size = 0x100)]
mod net_dma {
    #[reg(offset = 0x00, access = "rw")]
    pub struct Control {
        #[field(bits = 0..1)]
        pub enabled: bool,
        #[field(bits = 1..2)]
        pub interrupt_on_complete: bool,
    }

    #[reg(offset = 0x04, access = "wo")]
    pub struct TxDescriptor {
        #[field(bits = 0..32)]
        pub address: u32,
    }

    #[reg(offset = 0x08, access = "ro")]
    pub struct Status {
        #[field(bits = 0..1)]
        pub tx_complete: bool,
        #[field(bits = 1..2)]
        pub error: bool,
    }
}

// Addressed data structure
#[derive(Addressed, Clone)]
pub struct Cyberlink {
    pub from: Particle,
    pub to: Particle,
    pub agent: Address,
    pub height: u64,
}

// A complete cyb os cell
cell! {
    name: KnowledgeGraph,
    version: 1,
    budget: Duration::from_millis(1500),
    heartbeat: Duration::from_secs(1),

    state {
        links: BoundedMap<Particle, Cyberlink, 10_000_000>,
        agent_links: BoundedMap<Address, BoundedVec<Particle, 100_000>, 1_000_000>,
        link_count: u64,
    }

    step_state {
        new_links_this_step: BoundedVec<Cyberlink, 50_000>,
    }

    /// Add a cyberlink to the knowledge graph.
    /// Deterministic: same input always produces same state change.
    #[deterministic]
    pub fn add_cyberlink(
        &mut self,
        from: Particle,
        to: Particle,
        agent: Address,
    ) -> Result<Particle> {
        let link = Cyberlink {
            from, to, agent,
            height: self.current_step(),
        };

        let particle = link.particle();

        self.state.links.try_insert(particle, link.clone())
            .map_err(|_| Error::GraphFull)?;

        self.state.agent_links
            .entry(agent)
            .or_default()
            .try_push(particle)
            .map_err(|_| Error::AgentLimitReached)?;

        self.step_state.new_links_this_step.try_push(link)
            .map_err(|_| Error::StepFull)?;

        self.state.link_count = self.state.link_count
            .checked_add(1)
            .ok_or(Error::Overflow)?;

        Ok(particle)
    }

    /// Query links from a particle. Bounded async — 50ms max.
    pub async(Duration::from_millis(50)) fn get_outlinks(&self, from: Particle) -> Result<Vec<Cyberlink>> {
        // Vec allowed here because it's a query return, not persistent state
        // (could also use BoundedVec if strict)
        #[allow(rs::heap)]
        let mut results = Vec::new();

        for (_, link) in self.state.links.iter() {
            if link.from == from {
                results.push(link.clone());
            }
        }

        Ok(results)
    }

    /// Get count of links created this step.
    pub fn step_link_count(&self) -> usize {
        self.step_state.new_links_this_step.len()
    }

    migrate from v0 {
        links: old.links,
        agent_links: BoundedMap::new(),  // new in v1, rebuild from links
        link_count: old.links.len() as u64,
    }
}

This file:

• Is valid Rs (compiles with rsc --edition rs or via Cargo.toml edition)
• Is almost valid standard Rust (compiles with rustc + rs-lang/rs-lang-macros crates, minus async(Duration::from_millis(50)) syntax inside cell!)
• Has zero unsafe
• Has compile-time MMIO verification
• Has determinism guarantees on state transitions
• Has bounded async on all queries
• Has addressed (hash-identified) data by default
• Has auto-resetting step state
• Has hot-swap capability with state migration
• Can be generated by any LLM that knows Rust