strat9_kernel/silo/

mod.rs

//! Silo manager (kernel-side, minimal mechanisms only)
//!
//! This module provides the core kernel structures and syscalls
//! to create and manage silos. Policy lives in userspace (silo admin).

use crate::{
    capability::{get_capability_manager, CapId, CapPermissions, Capability, ResourceType},
    hardware::storage::{ahci, virtio_block},
    ipc::port::{self, PortId},
    memory::{UserSliceRead, UserSliceWrite},
    process::{current_task_clone, task::Task, TaskId},
    sync::{FixedQueue, SpinLock},
    syscall::error::SyscallError,
};
use alloc::{
    boxed::Box,
    collections::BTreeMap,
    string::{String, ToString},
    sync::Arc,
    vec::Vec,
};
use core::sync::atomic::{AtomicU64, Ordering};
use heapless::Vec as HVec;

// ============================================================================
// Public ABI structs (repr(C) for syscall boundary)
// ============================================================================

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
#[repr(u8)]
pub enum SiloTier {
    Critical = 0,
    System = 1,
    User = 2,
}

#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct SiloId {
    pub sid: u32,
    pub tier: SiloTier,
}

impl SiloId {
    /// Creates a new instance.
    pub const fn new(sid: u32) -> Self {
        let tier = match sid {
            1..=9 => SiloTier::Critical,
            10..=999 => SiloTier::System,
            _ => SiloTier::User,
        };
        Self { sid, tier }
    }

    /// Returns this as u64.
    pub fn as_u64(&self) -> u64 {
        self.sid as u64
    }
}

#[cfg(feature = "selftest")]
pub mod silo_test;

use bitflags::bitflags;

bitflags! {
    #[repr(transparent)]
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub struct ControlMode: u8 {
        const LIST  = 0b100;
        const STOP  = 0b010;
        const SPAWN = 0b001;
    }
}

bitflags! {
    #[repr(transparent)]
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub struct HardwareMode: u8 {
        const INTERRUPT = 0b100;
        const IO        = 0b010;
        const DMA       = 0b001;
    }
}

bitflags! {
    #[repr(transparent)]
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub struct RegistryMode: u8 {
        const LOOKUP = 0b100;
        const BIND   = 0b010;
        const PROXY  = 0b001;
    }
}

#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OctalMode {
    pub control: ControlMode,
    pub hardware: HardwareMode,
    pub registry: RegistryMode,
}

impl OctalMode {
    /// Builds this from octal.
    pub const fn from_octal(val: u16) -> Self {
        Self {
            control: ControlMode::from_bits_truncate(((val >> 6) & 0o7) as u8),
            hardware: HardwareMode::from_bits_truncate(((val >> 3) & 0o7) as u8),
            registry: RegistryMode::from_bits_truncate((val & 0o7) as u8),
        }
    }

    /// Returns whether subset of.
    pub const fn is_subset_of(&self, other: &OctalMode) -> bool {
        (self.control.bits() & !other.control.bits() == 0)
            && (self.hardware.bits() & !other.hardware.bits() == 0)
            && (self.registry.bits() & !other.registry.bits() == 0)
    }

    /// Performs the pledge operation.
    pub fn pledge(&mut self, new_mode: OctalMode) -> Result<(), SyscallError> {
        if !new_mode.is_subset_of(self) {
            return Err(SyscallError::PermissionDenied); // Escalation attempt
        }
        *self = new_mode;
        Ok(())
    }
}

/// Performs the sys silo pledge operation.
pub fn sys_silo_pledge(mode_val: u64) -> Result<u64, SyscallError> {
    let new_mode = OctalMode::from_octal(mode_val as u16);
    let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;

    let mut mgr = SILO_MANAGER.lock();
    if let Some(silo_id) = mgr.silo_for_task(task.id) {
        if let Ok(silo) = mgr.get_mut(silo_id) {
            silo.mode.pledge(new_mode)?;
            // Keep the raw ABI view in sync (snapshots and sandbox checks
            // read config.mode; kernel_pledge_silo does the same).
            silo.config.mode = mode_val as u16;

            mgr.push_event(SiloEvent {
                silo_id: silo_id as u64,
                kind: SiloEventKind::Started, // Re-using Started as "Updated" for now
                data0: mode_val,
                data1: 0,
                tick: crate::process::scheduler::ticks(),
            });
            return Ok(0);
        }
    }
    Err(SyscallError::BadHandle)
}

/// Performs the sys silo unveil operation.
pub fn sys_silo_unveil(
    path_ptr: u64,
    path_len: u64,
    rights_bits: u64,
) -> Result<u64, SyscallError> {
    const MAX_UNVEIL_PATH: usize = 1024;
    const MAX_UNVEIL_RULES: usize = 128;

    if path_ptr == 0 {
        return Err(SyscallError::Fault);
    }
    let len = usize::try_from(path_len).map_err(|_| SyscallError::InvalidArgument)?;
    if len == 0 || len > MAX_UNVEIL_PATH {
        return Err(SyscallError::InvalidArgument);
    }
    let user = UserSliceRead::new(path_ptr, len)?;
    let raw = user.read_to_vec();
    let path = core::str::from_utf8(&raw).map_err(|_| SyscallError::InvalidArgument)?;
    if path.is_empty() || !path.starts_with('/') || path.as_bytes().iter().any(|b| *b == 0) {
        return Err(SyscallError::InvalidArgument);
    }
    let path = normalize_unveil_path(path)?;
    let rights = UnveilRights::from_bits(rights_bits)?;

    let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
    let mut mgr = SILO_MANAGER.lock();
    let silo_id = mgr.silo_for_task(task.id).ok_or(SyscallError::BadHandle)?;
    let silo = mgr.get_mut(silo_id)?;

    if let Some(rule) = silo.unveil_rules.iter_mut().find(|r| r.path == path) {
        rule.rights = rule.rights.intersect(rights);
        return Ok(0);
    }
    if silo.unveil_rules.len() >= MAX_UNVEIL_RULES {
        return Err(SyscallError::QueueFull);
    }
    // Pre-validated: len() < MAX_UNVEIL_RULES, push cannot fail.
    let _ = silo.unveil_rules.push(UnveilRule { path, rights });
    Ok(0)
}

/// Performs the sys silo enter sandbox operation.
pub fn sys_silo_enter_sandbox() -> Result<u64, SyscallError> {
    let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
    let mut mgr = SILO_MANAGER.lock();
    let silo_id = mgr.silo_for_task(task.id).ok_or(SyscallError::BadHandle)?;
    let silo = mgr.get_mut(silo_id)?;
    if silo.sandboxed {
        return Ok(0);
    }
    silo.sandboxed = true;
    silo.mode.registry = RegistryMode::empty();
    silo.config.mode =
        ((silo.mode.control.bits() as u16) << 6) | ((silo.mode.hardware.bits() as u16) << 3);
    Ok(0)
}

/// Sets the `strate_label` of a silo identified by handle.
///
/// Requires silo-admin capability. The label must be non-empty, at most 31
/// bytes, and contain ONLY ASCII alphanumeric characters, `-`, `_`, or `.`.
pub fn sys_silo_rename(handle: u64, label_ptr: u64, label_len: u64) -> Result<u64, SyscallError> {
    require_silo_admin()?;
    const MAX_LABEL: usize = 31;
    let len = label_len as usize;
    if len == 0 || len > MAX_LABEL {
        return Err(SyscallError::InvalidArgument);
    }
    let user_slice = UserSliceRead::new(label_ptr, len)?;
    let raw = user_slice.read_to_vec();
    let label = core::str::from_utf8(&raw).map_err(|_| SyscallError::InvalidArgument)?;
    if !is_valid_label(label) {
        return Err(SyscallError::InvalidArgument);
    }
    let silo_id = resolve_silo_handle(handle, CapPermissions::read_write())?;
    let mut mgr = SILO_MANAGER.lock();
    // Reject if another silo already owns this label.
    if mgr
        .silos
        .values()
        .any(|s| s.id.sid != silo_id && s.strate_label.as_deref() == Some(label))
    {
        return Err(SyscallError::AlreadyExists);
    }
    let silo = mgr.get_mut(silo_id)?;
    silo.strate_label = Some(String::from(label));
    Ok(0)
}

/// Performs the enforce silo may grant operation.
pub fn enforce_silo_may_grant() -> Result<(), SyscallError> {
    let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
    if is_admin_task(&task) {
        return Ok(());
    }
    let mgr = SILO_MANAGER.lock();
    let Some(silo_id) = mgr.silo_for_task(task.id) else {
        return Ok(());
    };
    let silo = mgr.get(silo_id)?;
    if silo.sandboxed {
        return Err(SyscallError::PermissionDenied);
    }
    Ok(())
}

/// Normalise an unveil path: collapse duplicate slashes, reject dot
/// segments.
///
/// `.` and `..` are rejected outright rather than resolved: rule matching
/// is lexical prefix matching, so a query like `/etc/../secret` would
/// match an `/etc` rule while the backing filesystem resolves a different
/// path - a policy bypass waiting for a resolver that handles dot
/// segments.
fn normalize_unveil_path(path: &str) -> Result<String, SyscallError> {
    if !path.starts_with('/') {
        return Err(SyscallError::InvalidArgument);
    }
    let mut out = String::new();
    let mut prev_slash = false;
    let mut cur_segment = String::new();
    for ch in path.chars() {
        if ch == '/' {
            if !prev_slash {
                if cur_segment == "." || cur_segment == ".." {
                    return Err(SyscallError::InvalidArgument);
                }
                out.push('/');
                cur_segment.clear();
            }
            prev_slash = true;
            continue;
        }
        if ch == '\0' {
            return Err(SyscallError::InvalidArgument);
        }
        prev_slash = false;
        cur_segment.push(ch);
        out.push(ch);
    }
    if cur_segment == "." || cur_segment == ".." {
        return Err(SyscallError::InvalidArgument);
    }
    while out.len() > 1 && out.ends_with('/') {
        out.pop();
    }
    if out.is_empty() {
        out.push('/');
    }
    Ok(out)
}

/// Performs the path rule matches operation.
fn path_rule_matches(rule: &str, path: &str) -> bool {
    if rule == "/" {
        return true;
    }
    if path == rule {
        return true;
    }
    if !path.starts_with(rule) {
        return false;
    }
    let bytes = path.as_bytes();
    let idx = rule.len();
    idx < bytes.len() && bytes[idx] == b'/'
}

/// Performs the enforce path for current task operation.
pub fn enforce_path_for_current_task(
    path: &str,
    want_read: bool,
    want_write: bool,
    want_execute: bool,
) -> Result<(), SyscallError> {
    let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
    if is_admin_task(&task) {
        return Ok(());
    }
    let path = normalize_unveil_path(path)?;
    let mgr = SILO_MANAGER.lock();
    let Some(silo_id) = mgr.silo_for_task(task.id) else {
        return Ok(());
    };
    let silo = mgr.get(silo_id)?;
    if silo.sandboxed {
        return Err(SyscallError::PermissionDenied);
    }
    if silo.unveil_rules.is_empty() {
        return Ok(());
    }
    for rule in &silo.unveil_rules {
        if !path_rule_matches(&rule.path, &path) {
            continue;
        }
        if (!want_read || rule.rights.read)
            && (!want_write || rule.rights.write)
            && (!want_execute || rule.rights.execute)
        {
            return Ok(());
        }
    }
    Err(SyscallError::PermissionDenied)
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(C)]
struct UnveilRights {
    read: bool,
    write: bool,
    execute: bool,
}

impl UnveilRights {
    /// Builds this from bits.
    fn from_bits(bits: u64) -> Result<Self, SyscallError> {
        if bits & !0x7 != 0 {
            return Err(SyscallError::InvalidArgument);
        }
        Ok(Self {
            read: (bits & 0x1) != 0,
            write: (bits & 0x2) != 0,
            execute: (bits & 0x4) != 0,
        })
    }

    /// Performs the intersect operation.
    fn intersect(self, other: Self) -> Self {
        Self {
            read: self.read && other.read,
            write: self.write && other.write,
            execute: self.execute && other.execute,
        }
    }
}

#[derive(Debug, Clone)]
struct UnveilRule {
    path: String,
    rights: UnveilRights,
}

#[repr(u8)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StrateFamily {
    SYS = 0,
    DRV = 1,
    FS = 2,
    NET = 3,
    WASM = 4,
    USR = 5,
}

#[repr(u32)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SiloState {
    Created = 0,
    Loading = 1,
    Ready = 2,
    Running = 3,
    Paused = 4,
    Stopping = 5,
    Stopped = 6,
    Crashed = 7,
    Zombie = 8,
    Destroyed = 9,
}

pub const SILO_FLAG_ADMIN: u64 = 1 << 0;
pub const SILO_FLAG_GRAPHICS: u64 = 1 << 1;
pub const SILO_FLAG_WEBRTC_NATIVE: u64 = 1 << 2;
pub const SILO_FLAG_GRAPHICS_READ_ONLY: u64 = 1 << 3;
pub const SILO_FLAG_WEBRTC_TURN_FORCE: u64 = 1 << 4;

#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct SiloConfig {
    pub mem_min: u64,
    pub mem_max: u64,
    pub cpu_shares: u32,
    pub cpu_quota_us: u64,
    pub cpu_period_us: u64,
    pub cpu_affinity_mask: u64,
    pub max_tasks: u32,
    pub io_bw_read: u64,
    pub io_bw_write: u64,
    pub caps_ptr: u64,
    pub caps_len: u64,
    pub flags: u64,
    pub sid: u32,
    pub mode: u16,
    pub family: u8,
    /// CPU features that this silo requires (bitflags from `CpuFeatures`).
    pub cpu_features_required: u64,
    /// CPU features that this silo is allowed to use.
    pub cpu_features_allowed: u64,
    /// Effective XCR0 mask (computed from allowed features & host capabilities).
    pub xcr0_mask: u64,
    /// Maximum concurrent graphics sessions for this silo (0 = disabled).
    pub graphics_max_sessions: u16,
    /// Graphics session time-to-live in seconds.
    pub graphics_session_ttl_sec: u32,
    /// Reserved for ABI expansion.
    pub graphics_reserved: u16,
}

impl Default for SiloConfig {
    fn default() -> Self {
        SiloConfig {
            mem_min: 0,
            mem_max: 0,
            cpu_shares: 0,
            cpu_quota_us: 0,
            cpu_period_us: 0,
            cpu_affinity_mask: 0,
            max_tasks: 0,
            io_bw_read: 0,
            io_bw_write: 0,
            caps_ptr: 0,
            caps_len: 0,
            flags: 0,
            sid: 42,
            mode: 0,
            family: StrateFamily::USR as u8,
            cpu_features_required: 0,
            cpu_features_allowed: u64::MAX,
            xcr0_mask: 0,
            graphics_max_sessions: 0,
            graphics_session_ttl_sec: 0,
            graphics_reserved: 0,
        }
    }
}

impl SiloConfig {
    /// Performs the validate operation.
    fn validate(&self) -> Result<(), SyscallError> {
        if self.mem_min > self.mem_max && self.mem_max != 0 {
            return Err(SyscallError::InvalidArgument);
        }
        if self.cpu_quota_us > 0 && self.cpu_period_us == 0 {
            return Err(SyscallError::InvalidArgument);
        }
        if self.caps_len > MAX_SILO_CAPS as u64 {
            return Err(SyscallError::InvalidArgument);
        }
        if self.caps_len > 0 && self.caps_ptr == 0 {
            return Err(SyscallError::InvalidArgument);
        }
        if self.flags & SILO_FLAG_WEBRTC_NATIVE != 0 && self.flags & SILO_FLAG_GRAPHICS == 0 {
            return Err(SyscallError::InvalidArgument);
        }
        if self.flags & SILO_FLAG_GRAPHICS == 0 {
            if self.graphics_max_sessions != 0 || self.graphics_session_ttl_sec != 0 {
                return Err(SyscallError::InvalidArgument);
            }
        } else {
            if self.graphics_max_sessions == 0 {
                return Err(SyscallError::InvalidArgument);
            }
            if self.graphics_session_ttl_sec == 0 {
                return Err(SyscallError::InvalidArgument);
            }
        }
        Ok(())
    }
}

#[repr(C, packed)]
#[derive(Clone, Copy)]
pub struct Strat9ModuleHeader {
    pub magic: [u8; 4], // "CMOD"
    pub version: u16,
    pub cpu_arch: u8, // 0 = x86_64
    pub flags: u32,
    pub code_offset: u64,
    pub code_size: u64,
    pub data_offset: u64,
    pub data_size: u64,
    pub bss_size: u64,
    pub entry_point: u64,
    pub export_table_offset: u64,
    pub import_table_offset: u64,
    pub relocation_table_offset: u64,
    pub key_id: [u8; 8],
    pub signature: [u8; 64],
    /// CPU features required by this module (CpuFeatures bitflags). Header v2+.
    pub cpu_features_required: u64,
    pub reserved: [u8; 48],
}

impl core::fmt::Debug for Strat9ModuleHeader {
    /// Performs the fmt operation.
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        // SAFETY: read fields via read_unaligned to avoid UB on packed struct.
        let version = unsafe { core::ptr::addr_of!(self.version).read_unaligned() };
        let flags = unsafe { core::ptr::addr_of!(self.flags).read_unaligned() };
        let entry = unsafe { core::ptr::addr_of!(self.entry_point).read_unaligned() };
        let code_sz = unsafe { core::ptr::addr_of!(self.code_size).read_unaligned() };
        let data_sz = unsafe { core::ptr::addr_of!(self.data_size).read_unaligned() };
        f.debug_struct("Strat9ModuleHeader")
            .field("magic", &self.magic)
            .field("version", &version)
            .field("cpu_arch", &self.cpu_arch)
            .field("flags", &flags)
            .field("entry_point", &entry)
            .field("code_size", &code_sz)
            .field("data_size", &data_sz)
            .finish_non_exhaustive()
    }
}

#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct ModuleInfo {
    pub id: u64,
    pub format: u32, // 0 = raw/ELF, 1 = CMOD
    pub flags: u32,
    pub version: u16,
    pub cpu_arch: u8,
    pub reserved: u8,
    pub code_size: u64,
    pub data_size: u64,
    pub bss_size: u64,
    pub entry_point: u64,
    pub total_size: u64,
}

#[repr(u32)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SiloEventKind {
    Started = 1,
    Stopped = 2,
    Killed = 3,
    Crashed = 4,
    Paused = 5,
    Resumed = 6,
}

#[repr(u64)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SiloFaultReason {
    PageFault = 1,
    GeneralProtection = 2,
    InvalidOpcode = 3,
}

#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct SiloEvent {
    pub silo_id: u64,
    pub kind: SiloEventKind,
    pub data0: u64,
    pub data1: u64,
    pub tick: u64,
}

// data0 encoding for Crashed:
// - bits 0..15: fault reason (SiloFaultReason)
// - bits 16..31: fault subcode (arch-specific)
// - bits 32..63: reserved
pub const FAULT_SUBCODE_SHIFT: u64 = 16;

/// Performs the pack fault operation.
pub fn pack_fault(reason: SiloFaultReason, subcode: u64) -> u64 {
    (reason as u64) | (subcode << FAULT_SUBCODE_SHIFT)
}

// ============================================================================
// Internal kernel structs
// ============================================================================

#[derive(Debug)]
struct Silo {
    id: SiloId,
    name: String,
    strate_label: Option<String>,
    state: SiloState,
    config: SiloConfig,
    mode: OctalMode,
    family: StrateFamily,
    /// Current memory usage accounted to this silo (bytes).
    /// This tracks user-space virtual regions reserved/mapped via AddressSpace APIs.
    mem_usage_bytes: u64,
    flags: u32,
    module_id: Option<u64>,
    tasks: HVec<TaskId, 64>,
    granted_caps: HVec<u64, 64>,
    granted_resources: HVec<GrantedResource, 32>,
    unveil_rules: HVec<UnveilRule, 128>,
    sandboxed: bool,
    event_seq: u64,
    /// Ring buffer capturing debug output for `silo attach`.
    output_buf: Option<Box<SiloOutputBuf>>,
}

const SILO_OUTPUT_CAPACITY: usize = 4096;

struct SiloOutputBuf {
    buf: [u8; SILO_OUTPUT_CAPACITY],
    head: usize,
    count: usize,
}

impl core::fmt::Debug for SiloOutputBuf {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("SiloOutputBuf")
            .field("count", &self.count)
            .finish()
    }
}

impl SiloOutputBuf {
    const fn new() -> Self {
        Self {
            buf: [0; SILO_OUTPUT_CAPACITY],
            head: 0,
            count: 0,
        }
    }

    fn push(&mut self, data: &[u8]) {
        for &b in data {
            let tail = (self.head + self.count) % SILO_OUTPUT_CAPACITY;
            self.buf[tail] = b;
            if self.count < SILO_OUTPUT_CAPACITY {
                self.count += 1;
            } else {
                self.head = (self.head + 1) % SILO_OUTPUT_CAPACITY;
            }
        }
    }

    fn drain(&mut self) -> Vec<u8> {
        let mut out = Vec::with_capacity(self.count);
        for i in 0..self.count {
            out.push(self.buf[(self.head + i) % SILO_OUTPUT_CAPACITY]);
        }
        self.head = 0;
        self.count = 0;
        out
    }
}

#[derive(Debug, Clone)]
pub struct SiloSnapshot {
    pub id: u32,
    pub tier: SiloTier,
    pub name: String,
    pub strate_label: Option<String>,
    pub state: SiloState,
    pub task_count: usize,
    pub mem_usage_bytes: u64,
    pub mem_min_bytes: u64,
    pub mem_max_bytes: u64,
    pub mode: u16,
    pub graphics_flags: u64,
    pub graphics_max_sessions: u16,
    pub graphics_session_ttl_sec: u32,
}

#[derive(Debug, Clone)]
pub struct SiloDetailSnapshot {
    pub base: SiloSnapshot,
    pub family: StrateFamily,
    pub sandboxed: bool,
    pub cpu_shares: u32,
    pub cpu_affinity_mask: u64,
    pub max_tasks: u32,
    pub task_ids: Vec<u64>,
    pub unveil_rules: Vec<(String, u8)>,
    pub granted_caps_count: usize,
    pub cpu_features_required: u64,
    pub cpu_features_allowed: u64,
    pub xcr0_mask: u64,
    pub graphics_flags: u64,
    pub graphics_max_sessions: u16,
    pub graphics_session_ttl_sec: u32,
}

#[derive(Debug, Clone)]
pub struct SiloEventSnapshot {
    pub silo_id: u64,
    pub kind: SiloEventKind,
    pub data0: u64,
    pub data1: u64,
    pub tick: u64,
}

struct SiloManager {
    silos: BTreeMap<u32, Box<Silo>>,
    events: FixedQueue<SiloEvent, SILO_EVENTS_CAPACITY>,
    task_to_silo: BTreeMap<TaskId, u32>,
}

const SILO_EVENTS_CAPACITY: usize = 256;

impl SiloManager {
    /// Creates a new instance.
    const fn new() -> Self {
        SiloManager {
            silos: BTreeMap::new(),
            events: FixedQueue::new(),
            task_to_silo: BTreeMap::new(),
        }
    }

    /// Creates silo.
    fn create_silo(&mut self, config: &SiloConfig) -> Result<SiloId, SyscallError> {
        let id = SiloId::new(config.sid);
        if self.silos.contains_key(&id.sid) {
            return Err(SyscallError::AlreadyExists);
        }

        kernel_check_spawn_invariants(&id, &OctalMode::from_octal(config.mode))?;

        let mut name = String::from("silo-");
        name.push_str(&id.sid.to_string());

        let family = decode_family(config.family)?;

        let silo = Silo {
            id,
            name,
            strate_label: None,
            state: SiloState::Created,
            config: *config,
            mode: OctalMode::from_octal(config.mode),
            family,
            mem_usage_bytes: 0,
            flags: config.flags as u32,
            module_id: None,
            tasks: HVec::new(),
            granted_caps: HVec::new(),
            granted_resources: HVec::new(),
            unveil_rules: HVec::new(),
            sandboxed: false,
            event_seq: 0,
            output_buf: None,
        };

        self.silos.insert(id.sid, Box::new(silo));
        Ok(id)
    }

    /// Returns mut.
    fn get_mut(&mut self, id: u32) -> Result<&mut Silo, SyscallError> {
        self.silos
            .get_mut(&id)
            .map(Box::as_mut)
            .ok_or(SyscallError::BadHandle)
    }

    /// Performs the get operation.
    fn get(&self, id: u32) -> Result<&Silo, SyscallError> {
        self.silos
            .get(&id)
            .map(Box::as_ref)
            .ok_or(SyscallError::BadHandle)
    }

    /// Performs the push event operation.
    fn push_event(&mut self, ev: SiloEvent) {
        if self.events.is_full() {
            let _ = self.events.pop_front();
        }
        self.events
            .push_back(ev)
            .expect("silo event queue push must succeed after dropping oldest entry");
    }

    /// Maps task.
    fn map_task(&mut self, task_id: TaskId, silo_id: u32) {
        self.task_to_silo.insert(task_id, silo_id);
    }

    /// Unmaps task.
    fn unmap_task(&mut self, task_id: TaskId) {
        self.task_to_silo.remove(&task_id);
    }

    /// Performs the silo for task operation.
    fn silo_for_task(&self, task_id: TaskId) -> Option<u32> {
        if let Some(silo_id) = self.task_to_silo.get(&task_id).copied() {
            return Some(silo_id);
        }

        // Critical boot fallback: boot-time registration avoids BTreeMap inserts
        // while holding SILO_MANAGER to eliminate allocator re-entrancy risk on
        // the fragile early-init path.
        self.silos
            .iter()
            .find_map(|(sid, silo)| silo.tasks.iter().any(|tid| *tid == task_id).then_some(*sid))
    }
}

/// Performs the kernel check spawn invariants operation.
pub fn kernel_check_spawn_invariants(id: &SiloId, mode: &OctalMode) -> Result<(), SyscallError> {
    if id.tier == SiloTier::User && !mode.hardware.is_empty() {
        return Err(SyscallError::PermissionDenied);
    }
    if id.tier == SiloTier::User && !mode.control.is_empty() {
        return Err(SyscallError::PermissionDenied);
    }
    Ok(())
}

/// Performs the decode family operation.
fn decode_family(raw: u8) -> Result<StrateFamily, SyscallError> {
    match raw {
        0 => Ok(StrateFamily::SYS),
        1 => Ok(StrateFamily::DRV),
        2 => Ok(StrateFamily::FS),
        3 => Ok(StrateFamily::NET),
        4 => Ok(StrateFamily::WASM),
        5 => Ok(StrateFamily::USR),
        _ => Err(SyscallError::InvalidArgument),
    }
}

static SILO_MANAGER: SpinLock<SiloManager> = SpinLock::new(SiloManager::new());
static BOOT_REG_IN_PROGRESS: core::sync::atomic::AtomicBool =
    core::sync::atomic::AtomicBool::new(false);

const SILO_ADMIN_RESOURCE: usize = 0;
const MAX_SILO_CAPS: usize = 64;
const MAX_MODULE_BLOB_LEN: usize = 64 * 1024 * 1024; // 64 MiB for large preloaded user modules such as strate-wasm
const IPC_STREAM_DATA: u32 = 0xFFFF_FFFE;
const IPC_STREAM_EOF: u32 = 0xFFFF_FFFF;
const MODULE_FLAG_SIGNED: u32 = 1 << 0;
const MODULE_FLAG_KERNEL: u32 = 1 << 1;

/// Reads user config.
fn read_user_config(ptr: u64) -> Result<SiloConfig, SyscallError> {
    if ptr == 0 {
        return Err(SyscallError::Fault);
    }
    const SIZE: usize = core::mem::size_of::<SiloConfig>();
    let user = UserSliceRead::new(ptr, SIZE)?;
    let mut buf = [0u8; SIZE];
    user.copy_to(&mut buf);
    // SAFETY: We copied the exact bytes for SiloConfig from userspace.
    let config = unsafe { core::ptr::read_unaligned(buf.as_ptr() as *const SiloConfig) };
    Ok(config)
}

/// Reads caps list.
fn read_caps_list(ptr: u64, len: u64) -> Result<Vec<u64>, SyscallError> {
    if len == 0 {
        return Ok(Vec::new());
    }
    if len > MAX_SILO_CAPS as u64 {
        return Err(SyscallError::InvalidArgument);
    }
    let byte_len = len as usize * core::mem::size_of::<u64>();
    let user = UserSliceRead::new(ptr, byte_len)?;
    let bytes = user.read_to_vec();
    let mut out = Vec::with_capacity(len as usize);
    for chunk in bytes.chunks_exact(8) {
        let mut arr = [0u8; 8];
        arr.copy_from_slice(chunk);
        out.push(u64::from_le_bytes(arr));
    }
    Ok(out)
}

/// Reads module stream from port.
fn read_module_stream_from_port(
    port: &alloc::sync::Arc<port::Port>,
) -> Result<Vec<u8>, SyscallError> {
    let mut out = Vec::new();
    loop {
        let msg = port.recv().map_err(|_| SyscallError::BadHandle)?;

        if msg.msg_type == IPC_STREAM_EOF {
            break;
        }
        if msg.msg_type != IPC_STREAM_DATA {
            return Err(SyscallError::InvalidArgument);
        }
        if msg.flags != 0 {
            return Err(SyscallError::InvalidArgument);
        }

        let chunk_len = u16::from_le_bytes([msg.payload[0], msg.payload[1]]) as usize;
        if chunk_len == 0 {
            break;
        }
        if chunk_len > msg.payload.len() - 2 {
            return Err(SyscallError::InvalidArgument);
        }
        if out.len().saturating_add(chunk_len) > MAX_MODULE_BLOB_LEN {
            return Err(SyscallError::InvalidArgument);
        }

        out.extend_from_slice(&msg.payload[2..2 + chunk_len]);
    }
    Ok(out)
}

/// Parses module header.
fn parse_module_header(data: &[u8]) -> Result<Option<Strat9ModuleHeader>, SyscallError> {
    const MAGIC: [u8; 4] = *b"CMOD";
    let header_size = core::mem::size_of::<Strat9ModuleHeader>();

    if data.len() < MAGIC.len() {
        return Ok(None);
    }
    if data[0..4] != MAGIC {
        return Ok(None);
    }
    if data.len() < header_size {
        return Err(SyscallError::InvalidArgument);
    }

    // SAFETY: We checked length, and we read unaligned from a byte slice.
    let header = unsafe { core::ptr::read_unaligned(data.as_ptr() as *const Strat9ModuleHeader) };

    if header.version != 1 && header.version != 2 {
        return Err(SyscallError::InvalidArgument);
    }
    if header.cpu_arch != 0 {
        return Err(SyscallError::InvalidArgument);
    }

    let version = unsafe { core::ptr::addr_of!(header.version).read_unaligned() };
    let req = if version >= 2 {
        unsafe { core::ptr::addr_of!(header.cpu_features_required).read_unaligned() }
    } else {
        0
    };
    if req != 0 {
        let host = crate::arch::cpuid::host();
        let required = crate::arch::cpuid::CpuFeatures::from_bits_truncate(req);
        if !host.features.contains(required) {
            log::warn!(
                "[cmod] module requires CPU features {:#x} but host has {:#x}",
                req,
                host.features.bits()
            );
            return Err(SyscallError::InvalidArgument);
        }
    }

    let data_len = data.len() as u64;
    let code_end = header
        .code_offset
        .checked_add(header.code_size)
        .ok_or(SyscallError::InvalidArgument)?;
    let data_end = header
        .data_offset
        .checked_add(header.data_size)
        .ok_or(SyscallError::InvalidArgument)?;
    if code_end > data_len || data_end > data_len {
        return Err(SyscallError::InvalidArgument);
    }
    if header.entry_point >= header.code_size && header.code_size != 0 {
        return Err(SyscallError::InvalidArgument);
    }
    if header.export_table_offset > data_len
        || header.import_table_offset > data_len
        || header.relocation_table_offset > data_len
    {
        return Err(SyscallError::InvalidArgument);
    }

    // Segmentation rules: code/data must not overlap and must be page-aligned.
    const PAGE_SIZE: u64 = 4096;
    if header.code_size > 0 {
        if header.code_offset % PAGE_SIZE != 0 || header.code_size % PAGE_SIZE != 0 {
            return Err(SyscallError::InvalidArgument);
        }
    }
    if header.data_size > 0 {
        if header.data_offset % PAGE_SIZE != 0 || header.data_size % PAGE_SIZE != 0 {
            return Err(SyscallError::InvalidArgument);
        }
    }
    let code_range = header.code_offset..code_end;
    let data_range = header.data_offset..data_end;
    if code_range.start < data_range.end && data_range.start < code_range.end {
        return Err(SyscallError::InvalidArgument);
    }

    // Flags/signature checks (Ed25519 cryptographic verification).
    //
    // Security: the signed payload is code+data ONLY (after the header).
    // The header (containing key_id and signature) is NOT signed. This
    // prevents an attacker from embedding a known key_id to trick the
    // kernel into looking up a legitimate key while verifying a bad sig.
    if header.flags & MODULE_FLAG_SIGNED != 0 {
        // Compute offsets from the packed struct layout : never hardcode.
        let key_id_offset = core::mem::offset_of!(Strat9ModuleHeader, key_id);
        let sig_offset = core::mem::offset_of!(Strat9ModuleHeader, signature);
        let header_size = core::mem::size_of::<Strat9ModuleHeader>();

        // Payload = everything after the header (code + data sections).
        // This is what was actually signed.
        let payload = if data.len() > header_size {
            &data[header_size..]
        } else {
            return Err(SyscallError::InvalidArgument);
        };

        let result = crate::crypto::verify_cmod_signature(data, key_id_offset, sig_offset, payload);

        match result {
            crate::crypto::VerifyResult::Valid => {
                log::info!("[cmod] Ed25519 signature verified");
            }
            crate::crypto::VerifyResult::Unsigned => {
                log::warn!("[cmod] MODULE_FLAG_SIGNED set but signature is zero");
                return Err(SyscallError::PermissionDenied);
            }
            crate::crypto::VerifyResult::KeyNotFound => {
                log::warn!("[cmod] no trusted key for id {:02x?}", header.key_id);
                return Err(SyscallError::PermissionDenied);
            }
            crate::crypto::VerifyResult::InvalidSignature => {
                log::warn!("[cmod] Ed25519 verification FAILED");
                return Err(SyscallError::PermissionDenied);
            }
        }
    }
    if header.flags & MODULE_FLAG_KERNEL != 0 {
        // Kernel modules are allowed only when loaded by admin (already enforced).
    }

    Ok(Some(header))
}

/// Reads u32 le.
fn read_u32_le(data: &[u8], offset: usize) -> Result<u32, SyscallError> {
    if offset + 4 > data.len() {
        return Err(SyscallError::InvalidArgument);
    }
    let mut buf = [0u8; 4];
    buf.copy_from_slice(&data[offset..offset + 4]);
    Ok(u32::from_le_bytes(buf))
}

/// Reads u64 le.
fn read_u64_le(data: &[u8], offset: usize) -> Result<u64, SyscallError> {
    if offset + 8 > data.len() {
        return Err(SyscallError::InvalidArgument);
    }
    let mut buf = [0u8; 8];
    buf.copy_from_slice(&data[offset..offset + 8]);
    Ok(u64::from_le_bytes(buf))
}

/// Performs the resolve export offset operation.
fn resolve_export_offset(module: &ModuleImage, ordinal: u64) -> Result<u64, SyscallError> {
    let header = module.header.ok_or(SyscallError::InvalidArgument)?;
    if header.export_table_offset == 0 {
        return Err(SyscallError::NotFound);
    }
    let table_off = header.export_table_offset as usize;
    let count = read_u32_le(module.data.as_slice(), table_off)? as u64;
    if ordinal >= count {
        return Err(SyscallError::InvalidArgument);
    }
    // Layout: u32 count + u32 reserved, then u64 entries.
    let entries_off = table_off + 8;
    let entry_off = entries_off + (ordinal as usize * 8);
    let rva = read_u64_le(module.data.as_slice(), entry_off)?;
    Ok(rva)
}

/// Performs the require silo admin operation.
pub fn require_silo_admin() -> Result<(), SyscallError> {
    let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
    // SAFETY: Current task owns its capability table during syscall execution.
    let caps = unsafe { &*task.process.capabilities.get() };
    let required = CapPermissions {
        read: false,
        write: false,
        execute: false,
        grant: true,
        revoke: false,
    };

    if caps.has_resource_with_permissions(ResourceType::Silo, SILO_ADMIN_RESOURCE, required) {
        Ok(())
    } else {
        Err(SyscallError::PermissionDenied)
    }
}

/// Performs the resolve silo handle operation.
fn resolve_silo_handle(handle: u64, required: CapPermissions) -> Result<u32, SyscallError> {
    let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
    let caps = unsafe { &*task.process.capabilities.get() };
    let cap_id = CapId::from_raw(handle);
    let cap = caps.get(cap_id).ok_or(SyscallError::BadHandle)?;

    // Ensure this is a Silo capability and permissions are sufficient.
    if cap.resource_type != ResourceType::Silo {
        return Err(SyscallError::BadHandle);
    }

    if (!required.read || cap.permissions.read)
        && (!required.write || cap.permissions.write)
        && (!required.execute || cap.permissions.execute)
        && (!required.grant || cap.permissions.grant)
        && (!required.revoke || cap.permissions.revoke)
    {
        Ok(cap.resource as u32)
    } else {
        Err(SyscallError::PermissionDenied)
    }
}

// ============================================================================
// Module registry (temporary blob store for .cmod/ELF)
// ============================================================================

#[derive(Debug, Clone)]
enum ModuleData {
    Owned(Arc<[u8]>),
    Static(&'static [u8]),
}

impl ModuleData {
    fn as_slice(&self) -> &[u8] {
        match self {
            ModuleData::Owned(data) => data,
            ModuleData::Static(data) => data,
        }
    }

    fn len(&self) -> usize {
        self.as_slice().len()
    }
}

#[derive(Debug)]
struct ModuleImage {
    id: u64,
    data: ModuleData,
    header: Option<Strat9ModuleHeader>,
}

struct ModuleRegistry {
    modules: BTreeMap<u64, ModuleImage>,
    next_id: u64,
}

impl ModuleRegistry {
    /// Creates a new instance.
    const fn new() -> Self {
        ModuleRegistry {
            modules: BTreeMap::new(),
            next_id: 1,
        }
    }

    // Both storage paths share the same namespace. Never recycle IDs: stale
    // module capabilities must not resolve to a later registration.
    fn allocate_id(&mut self) -> Result<u64, SyscallError> {
        let id = self.next_id;
        self.next_id = id.checked_add(1).ok_or(SyscallError::OutOfMemory)?;
        Ok(id)
    }

    /// Performs the register operation.
    fn register(&mut self, data: Vec<u8>) -> Result<u64, SyscallError> {
        let header = parse_module_header(&data)?;
        let id = self.allocate_id()?;
        self.modules.insert(
            id,
            ModuleImage {
                id,
                data: ModuleData::Owned(Arc::from(data.into_boxed_slice())),
                header,
            },
        );
        Ok(id)
    }

    fn register_static(&mut self, data: &'static [u8]) -> Result<u64, SyscallError> {
        let header = parse_module_header(data)?;
        let id = self.allocate_id()?;
        self.modules.insert(
            id,
            ModuleImage {
                id,
                data: ModuleData::Static(data),
                header,
            },
        );
        Ok(id)
    }

    /// Performs the get operation.
    fn get(&self, id: u64) -> Option<&ModuleImage> {
        self.modules.get(&id)
    }

    /// Performs the remove operation.
    fn remove(&mut self, id: u64) -> Option<ModuleImage> {
        self.modules.remove(&id)
    }
}

static MODULE_REGISTRY: SpinLock<ModuleRegistry> = SpinLock::new(ModuleRegistry::new());

/// Charge memory usage against a task's silo quota (if any).
///
/// Uses `try_lock`: callers sit on memory-mapping paths that can execute
/// while `SILO_MANAGER` is held elsewhere on the same CPU (e.g. a snapshot
/// helper allocating under the lock). A blocking acquisition there would
/// self-deadlock the kernel; skipping accounting under contention is the
/// documented best-effort trade-off (same policy as
/// [`try_silo_id_for_task`]).
fn charge_task_silo_memory(task_id: TaskId, bytes: u64) -> Result<(), SyscallError> {
    if bytes == 0 {
        return Ok(());
    }
    let Some(mut mgr) = SILO_MANAGER.try_lock() else {
        return Ok(());
    };
    let Some(silo_id) = mgr.silo_for_task(task_id) else {
        return Ok(());
    };
    let silo = mgr.get_mut(silo_id)?;
    let next = silo
        .mem_usage_bytes
        .checked_add(bytes)
        .ok_or(SyscallError::OutOfMemory)?;
    if silo.config.mem_max != 0 && next > silo.config.mem_max {
        return Err(SyscallError::OutOfMemory);
    }
    silo.mem_usage_bytes = next;
    Ok(())
}

/// Release memory usage from a task's silo quota (if any).
///
/// Best-effort `try_lock`, mirroring [`charge_task_silo_memory`].
fn release_task_silo_memory(task_id: TaskId, bytes: u64) {
    if bytes == 0 {
        return;
    }
    let Some(mut mgr) = SILO_MANAGER.try_lock() else {
        return;
    };
    let Some(silo_id) = mgr.silo_for_task(task_id) else {
        return;
    };
    if let Ok(silo) = mgr.get_mut(silo_id) {
        silo.mem_usage_bytes = silo.mem_usage_bytes.saturating_sub(bytes);
    }
}

/// Charge memory usage against the current task's silo quota (if any).
///
/// Returns `OutOfMemory` when charging would exceed `SiloConfig.mem_max`.
/// Tasks that are not part of a silo are ignored.
pub fn charge_current_task_memory(bytes: u64) -> Result<(), SyscallError> {
    let Some(task) = crate::process::scheduler::current_task_clone_try() else {
        // Boot-time/kernel contexts may have no current task.
        // Also avoid deadlock when scheduler lock is already held in cleanup paths.
        return Ok(());
    };
    charge_task_silo_memory(task.id, bytes)
}

/// Release memory usage from the current task's silo quota (if any).
///
/// Tasks that are not part of a silo are ignored.
pub fn release_current_task_memory(bytes: u64) {
    if let Some(task) = crate::process::scheduler::current_task_clone_try() {
        release_task_silo_memory(task.id, bytes);
    }
}

/// Performs the extract strate label operation.
fn extract_strate_label(path: &str) -> Option<String> {
    let prefix = "/srv/strate-fs-";
    let rest = path.strip_prefix(prefix)?;
    let mut parts = rest.split('/').filter(|p| !p.is_empty());
    let _strate_type = parts.next()?;
    let label = parts.next()?;
    if label.is_empty() || parts.next().is_some() {
        return None;
    }
    Some(String::from(label))
}

/// Performs the sanitize label operation.
fn sanitize_label(raw: &str) -> String {
    let mut out = String::new();
    for b in raw.bytes().take(31) {
        let ok = (b as char).is_ascii_alphanumeric() || b == b'-' || b == b'_' || b == b'.';
        out.push(if ok { b as char } else { '_' });
    }
    if out.is_empty() {
        String::from("default")
    } else {
        out
    }
}

/// Returns whether valid label.
fn is_valid_label(raw: &str) -> bool {
    if raw.is_empty() || raw.len() > 31 {
        return false;
    }
    raw.bytes()
        .all(|b| (b as char).is_ascii_alphanumeric() || b == b'-' || b == b'_' || b == b'.')
}

/// Sets current silo label from path.
pub fn set_current_silo_label_from_path(path: &str) -> Result<(), SyscallError> {
    let Some(label) = extract_strate_label(path) else {
        return Ok(());
    };
    let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
    let mut mgr = SILO_MANAGER.lock();
    let Some(silo_id) = mgr.silo_for_task(task.id) else {
        return Ok(());
    };
    let silo = mgr.get_mut(silo_id)?;
    // Do not overwrite a label that was already set (e.g. by kernel_spawn_strate).
    // The spawner's requested label takes precedence over the default path-derived one.
    if silo.strate_label.is_none() {
        silo.strate_label = Some(label);
    }
    Ok(())
}

/// Performs the current task silo label operation.
pub fn current_task_silo_label() -> Option<String> {
    let task = current_task_clone()?;
    let mgr = SILO_MANAGER.lock();
    let silo_id = mgr.silo_for_task(task.id)?;
    let silo = mgr.get(silo_id).ok()?;
    silo.strate_label.clone()
}

/// Performs the list silos snapshot operation.
pub fn list_silos_snapshot() -> Vec<SiloSnapshot> {
    let mgr = SILO_MANAGER.lock();
    mgr.silos
        .values()
        .map(|s| SiloSnapshot {
            id: s.id.sid,
            tier: s.id.tier,
            name: s.name.clone(),
            strate_label: s.strate_label.clone(),
            state: s.state,
            task_count: s.tasks.len(),
            mem_usage_bytes: s.mem_usage_bytes,
            mem_min_bytes: s.config.mem_min,
            mem_max_bytes: s.config.mem_max,
            mode: s.config.mode,
            graphics_flags: s.config.flags
                & (SILO_FLAG_GRAPHICS
                    | SILO_FLAG_WEBRTC_NATIVE
                    | SILO_FLAG_GRAPHICS_READ_ONLY
                    | SILO_FLAG_WEBRTC_TURN_FORCE),
            graphics_max_sessions: s.config.graphics_max_sessions,
            graphics_session_ttl_sec: s.config.graphics_session_ttl_sec,
        })
        .collect()
}

/// Return silo identity + memory accounting for a task, if the task belongs to a silo.
///
/// Tuple layout:
/// - silo id (u32)
/// - optional label
/// - current usage bytes
/// - configured minimum bytes
/// - configured maximum bytes (0 = unlimited)
/// Best-effort, non-blocking silo lookup for allocator-internal accounting.
///
/// Uses `try_lock` so that callers running under IRQs-disabled conditions
/// (e.g. inside vmalloc) do not deadlock when SILO_MANAGER is already held
/// by an outer call on the same CPU.  Returns `None` if the lock is contended
/// or if the task is not registered in any silo.
pub fn try_silo_id_for_task(task_id: TaskId) -> Option<u32> {
    SILO_MANAGER.try_lock()?.silo_for_task(task_id)
}

pub fn silo_info_for_task(task_id: TaskId) -> Option<(u32, Option<String>, u64, u64, u64)> {
    let mgr = SILO_MANAGER.lock();
    let silo_id = mgr.silo_for_task(task_id)?;
    let silo = mgr.get(silo_id).ok()?;
    Some((
        silo.id.sid,
        silo.strate_label.clone(),
        silo.mem_usage_bytes,
        silo.config.mem_min,
        silo.config.mem_max,
    ))
}

/// Performs the resolve volume resource from dev path operation.
fn resolve_volume_resource_from_dev_path(dev_path: &str) -> Result<usize, SyscallError> {
    match dev_path {
        "/dev/sda" => ahci::get_device()
            .map(|d| d as *const _ as usize)
            .ok_or(SyscallError::NotFound),
        "/dev/vda" => virtio_block::get_device()
            .map(|d| d as *const _ as usize)
            .ok_or(SyscallError::NotFound),
        _ => Err(SyscallError::NotFound),
    }
}

/// Compute the effective XCR0 mask for a silo from its allowed CPU features.
fn compute_silo_xcr0(config: &SiloConfig) -> u64 {
    use crate::arch::cpuid::{xcr0_for_features, CpuFeatures};
    let allowed = CpuFeatures::from_bits_truncate(config.cpu_features_allowed);
    xcr0_for_features(allowed)
}

/// Performs the kernel spawn strate operation.
pub fn kernel_spawn_strate(
    elf_data: &[u8],
    label: Option<&str>,
    dev_path: Option<&str>,
) -> Result<u32, SyscallError> {
    let module_id = {
        let mut registry = MODULE_REGISTRY.lock();
        registry.register(elf_data.to_vec())?
    };

    let silo_id = {
        let mut mgr = SILO_MANAGER.lock();
        // For kernel_spawn_strate (manual command), we auto-assign SID > 1000.
        // In a production system, this would follow the "42" rule from Init.
        let mut sid = 1000u32;
        while mgr.silos.contains_key(&sid) {
            sid = sid.checked_add(1).ok_or(SyscallError::OutOfMemory)?;
        }

        let id = SiloId::new(sid);
        let requested_label = label
            .map(sanitize_label)
            .unwrap_or_else(|| alloc::format!("inst-{}", id.sid));

        if mgr
            .silos
            .values()
            .any(|s| s.strate_label.as_deref() == Some(requested_label.as_str()))
        {
            return Err(SyscallError::AlreadyExists);
        }

        let mut cfg = SiloConfig {
            sid: id.sid,
            mode: 0o000,
            family: StrateFamily::USR as u8,
            ..SiloConfig::default()
        };
        cfg.xcr0_mask = compute_silo_xcr0(&cfg);

        let silo = Silo {
            id,
            name: alloc::format!("silo-{}", id.sid),
            strate_label: Some(requested_label),
            state: SiloState::Ready,
            config: cfg,
            mode: OctalMode::from_octal(0),
            family: StrateFamily::USR,
            mem_usage_bytes: 0,
            flags: 0,
            module_id: Some(module_id),
            tasks: HVec::new(),
            granted_caps: HVec::new(),
            granted_resources: HVec::new(),
            unveil_rules: HVec::new(),
            sandboxed: false,
            event_seq: 0,
            output_buf: None,
        };

        mgr.silos.insert(id.sid, Box::new(silo));
        id.sid
    };

    let module_data = {
        let registry = MODULE_REGISTRY.lock();
        let module = registry.get(module_id).ok_or(SyscallError::BadHandle)?;
        module.data.clone()
    };

    let mut seed_caps = Vec::new();
    seed_caps.push(create_silo_admin_capability());
    if let Some(path) = dev_path {
        let resource = resolve_volume_resource_from_dev_path(path)?;
        let cap = get_capability_manager().create_capability(
            ResourceType::Volume,
            resource,
            CapPermissions {
                read: true,
                write: true,
                execute: false,
                grant: true,
                revoke: true,
            },
        );
        seed_caps.push(cap);
    }

    let display = {
        let mgr = SILO_MANAGER.lock();
        let silo = mgr.get(silo_id)?;
        silo.strate_label
            .clone()
            .unwrap_or_else(|| alloc::format!("silo-{}", silo.id.sid))
    };
    let task_name: &'static str =
        Box::leak(alloc::format!("silo-{}/strate-admin-{}", silo_id, display).into_boxed_str());
    let task =
        crate::process::elf::load_elf_task_with_caps(module_data.as_slice(), task_name, &seed_caps)
            .map_err(|_| SyscallError::InvalidArgument)?;
    let task_id = task.id;

    let mut mgr = SILO_MANAGER.lock();
    {
        let silo = mgr.get_mut(silo_id)?;
        if let Err(task) = silo.tasks.push(task_id) {
            log::error!(
                "[silo] tasks full (capacity=64), task {} not registered",
                task.0
            );
        }
        silo.state = SiloState::Running;
        let fpu_xcr0 = unsafe { (*task.fpu_state.get()).xcr0_mask };
        let effective_xcr0 = (silo.config.xcr0_mask & fpu_xcr0).max(0x3);
        task.xcr0_mask
            .store(effective_xcr0, core::sync::atomic::Ordering::Relaxed);
        // Propagate silo CPU affinity to task for scheduler placement.
        let affinity = silo.config.cpu_affinity_mask;
        if affinity != 0 {
            task.affinity_mask
                .store(affinity, core::sync::atomic::Ordering::Relaxed);
        }
    }
    mgr.map_task(task_id, silo_id);
    mgr.push_event(SiloEvent {
        silo_id: silo_id.into(),
        kind: SiloEventKind::Started,
        data0: 0,
        data1: 0,
        tick: crate::process::scheduler::ticks(),
    });
    drop(mgr);
    crate::process::add_task(task);
    Ok(silo_id)
}

/// Performs the resolve selector to silo id operation.
fn resolve_selector_to_silo_id(selector: &str, mgr: &SiloManager) -> Result<u32, SyscallError> {
    if let Ok(id) = selector.parse::<u32>() {
        if mgr.silos.contains_key(&id) {
            return Ok(id);
        }
        return Err(SyscallError::NotFound);
    }
    let mut found: Option<u32> = None;
    for s in mgr.silos.values() {
        if s.strate_label.as_deref() == Some(selector) {
            if found.is_some() {
                return Err(SyscallError::InvalidArgument);
            }
            found = Some(s.id.sid);
        }
    }
    found.ok_or(SyscallError::NotFound)
}

/// Performs the kernel stop silo operation.
pub fn kernel_stop_silo(selector: &str, force_kill: bool) -> Result<u32, SyscallError> {
    let (silo_id, tasks) = {
        let mut mgr = SILO_MANAGER.lock();
        let silo_id = resolve_selector_to_silo_id(selector, &mgr)?;
        let mut tasks = HVec::<TaskId, 64>::new();
        {
            let silo = mgr.get_mut(silo_id)?;
            match silo.state {
                SiloState::Running | SiloState::Paused => {
                    tasks = silo.tasks.clone();
                    silo.tasks.clear();
                    silo.state = if force_kill {
                        SiloState::Stopped
                    } else {
                        SiloState::Stopping
                    };
                }
                SiloState::Stopping => {
                    if force_kill {
                        silo.state = SiloState::Stopped;
                    }
                }
                SiloState::Stopped | SiloState::Created | SiloState::Ready => {}
                _ => return Err(SyscallError::InvalidArgument),
            }
        }
        for tid in &tasks {
            mgr.unmap_task(*tid);
        }
        mgr.push_event(SiloEvent {
            silo_id: silo_id as u64,
            kind: if force_kill {
                SiloEventKind::Killed
            } else {
                SiloEventKind::Stopped
            },
            data0: 0,
            data1: 0,
            tick: crate::process::scheduler::ticks(),
        });
        (silo_id, tasks)
    };
    for tid in tasks {
        crate::process::kill_task(tid);
    }
    Ok(silo_id)
}

/// Performs the kernel start silo operation.
pub fn kernel_start_silo(selector: &str) -> Result<u32, SyscallError> {
    let silo_id = {
        let mgr = SILO_MANAGER.lock();
        resolve_selector_to_silo_id(selector, &mgr)?
    };
    let _ = start_silo_by_id(silo_id)?;
    Ok(silo_id)
}

/// Performs the kernel destroy silo operation.
pub fn kernel_destroy_silo(selector: &str) -> Result<u32, SyscallError> {
    let (silo_id, module_id) = {
        let mut mgr = SILO_MANAGER.lock();
        let silo_id = resolve_selector_to_silo_id(selector, &mgr)?;
        let module_id = {
            let silo = mgr.get(silo_id)?;
            if !silo.tasks.is_empty() {
                return Err(SyscallError::InvalidArgument);
            }
            match silo.state {
                SiloState::Stopped | SiloState::Created | SiloState::Ready | SiloState::Crashed => {
                }
                _ => return Err(SyscallError::InvalidArgument),
            }
            silo.module_id
        };
        let _ = mgr.silos.remove(&silo_id);
        (silo_id, module_id)
    };
    if let Some(mid) = module_id {
        let mut reg = MODULE_REGISTRY.lock();
        let _ = reg.remove(mid);
    }
    Ok(silo_id)
}

/// Performs the kernel rename silo label operation.
pub fn kernel_rename_silo_label(selector: &str, new_label: &str) -> Result<u32, SyscallError> {
    if !is_valid_label(new_label) {
        return Err(SyscallError::InvalidArgument);
    }
    let mut mgr = SILO_MANAGER.lock();
    let silo_id = resolve_selector_to_silo_id(selector, &mgr)?;
    if mgr
        .silos
        .values()
        .any(|s| s.id.sid != silo_id && s.strate_label.as_deref() == Some(new_label))
    {
        return Err(SyscallError::AlreadyExists);
    }
    let silo = mgr.get_mut(silo_id)?;
    match silo.state {
        SiloState::Stopped | SiloState::Created | SiloState::Ready | SiloState::Crashed => {
            silo.strate_label = Some(String::from(new_label));
            Ok(silo_id)
        }
        _ => Err(SyscallError::InvalidArgument),
    }
}

/// Performs the register boot strate task operation.
pub fn register_boot_strate_task(task_id: TaskId, label: &str) -> Result<u32, SyscallError> {
    BOOT_REG_IN_PROGRESS.store(true, Ordering::Relaxed);
    let result = (|| -> Result<u32, SyscallError> {
        let sanitized = sanitize_label(label);
        let mgr = SILO_MANAGER.lock();
        let mut sid = 1u32;
        while mgr.silos.contains_key(&sid) {
            sid = sid.checked_add(1).ok_or(SyscallError::OutOfMemory)?;
        }
        if mgr
            .silos
            .values()
            .any(|s| s.strate_label.as_deref() == Some(sanitized.as_str()))
        {
            return Err(SyscallError::AlreadyExists);
        }
        drop(mgr);

        let id = SiloId::new(sid);
        let silo = Silo {
            id,
            name: alloc::format!("silo-{}", id.sid),
            strate_label: Some(sanitized),
            state: SiloState::Running,
            config: SiloConfig {
                sid: id.sid,
                mode: 0o777,
                family: StrateFamily::SYS as u8,
                ..SiloConfig::default()
            },
            mode: OctalMode::from_octal(0o777),
            family: StrateFamily::SYS,
            mem_usage_bytes: 0,
            flags: 0,
            module_id: None,
            tasks: {
                let mut v = HVec::new();
                let _ = v.push(task_id);
                v
            },
            granted_caps: HVec::new(),
            granted_resources: HVec::new(),
            unveil_rules: HVec::new(),
            sandboxed: false,
            event_seq: 0,
            output_buf: None,
        };

        let mut mgr = SILO_MANAGER.lock();
        if mgr.silos.contains_key(&id.sid) {
            return Err(SyscallError::Again);
        }
        if mgr
            .silos
            .values()
            .any(|s| s.strate_label.as_deref() == silo.strate_label.as_deref())
        {
            return Err(SyscallError::AlreadyExists);
        }
        mgr.silos.insert(id.sid, Box::new(silo));
        drop(mgr);
        Ok(id.sid)
    })();
    BOOT_REG_IN_PROGRESS.store(false, Ordering::Relaxed);
    result
}

/// Returns true while boot-time silo registration critical path is executing.
pub fn debug_boot_reg_active() -> bool {
    BOOT_REG_IN_PROGRESS.load(Ordering::Relaxed)
}

/// Performs the resolve module handle operation.
fn resolve_module_handle(handle: u64, required: CapPermissions) -> Result<u64, SyscallError> {
    let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
    let caps = unsafe { &*task.process.capabilities.get() };
    let cap_id = CapId::from_raw(handle);
    let cap = caps.get(cap_id).ok_or(SyscallError::BadHandle)?;

    if cap.resource_type != ResourceType::Module {
        return Err(SyscallError::BadHandle);
    }

    if (!required.read || cap.permissions.read)
        && (!required.write || cap.permissions.write)
        && (!required.execute || cap.permissions.execute)
        && (!required.grant || cap.permissions.grant)
        && (!required.revoke || cap.permissions.revoke)
    {
        Ok(cap.resource as u64)
    } else {
        Err(SyscallError::PermissionDenied)
    }
}

/// Grant the Silo Admin capability to a task (bootstrapping).
///
/// This should be called only for the initial admin task (e.g. "init").
pub fn create_silo_admin_capability() -> Capability {
    get_capability_manager().create_capability(
        ResourceType::Silo,
        SILO_ADMIN_RESOURCE,
        CapPermissions::all(),
    )
}

pub fn grant_silo_admin_to_task(task: &alloc::sync::Arc<Task>) -> CapId {
    let cap = create_silo_admin_capability();
    // SAFETY: Bootstrapping. Caller must ensure exclusive access.
    unsafe { (&mut *task.process.capabilities.get()).insert(cap) }
}

// ============================================================================
// Module syscalls (temporary blob loader)
// ============================================================================

/// Performs the sys module load operation.
pub fn sys_module_load(fd_or_ptr: u64, len: u64) -> Result<u64, SyscallError> {
    // Module loading is currently restricted to admin.
    require_silo_admin()?;

    // Transitional path: if len != 0, treat arg1 as a userspace blob pointer.
    if len != 0 {
        let len = len as usize;
        if len == 0 || len > MAX_MODULE_BLOB_LEN {
            return Err(SyscallError::InvalidArgument);
        }

        if len <= 4096 {
            let user = UserSliceRead::new(fd_or_ptr, len)?;
            if matches!(user.read_u8(0), Ok(b'/')) {
                let path_buf = user.read_to_vec();
                let path =
                    core::str::from_utf8(&path_buf).map_err(|_| SyscallError::InvalidArgument)?;
                let data = crate::vfs::get_initfs_file_bytes(path).ok_or_else(|| {
                    log::warn!("module_load: initfs path not found: '{}'", path);
                    SyscallError::NotFound
                })?;
                let mut registry = MODULE_REGISTRY.lock();
                let id = registry.register_static(data)?;
                drop(registry);

                let cap = get_capability_manager().create_capability(
                    ResourceType::Module,
                    id as usize,
                    CapPermissions::all(),
                );

                let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
                let cap_id = unsafe { (&mut *task.process.capabilities.get()).insert(cap) };
                return Ok(cap_id.as_u64());
            }
        }

        let user = UserSliceRead::new(fd_or_ptr, len)?;
        let data = user.read_to_vec();
        if data.len() >= 4 {
            log::debug!(
                "module_load: len={} magic={:02x}{:02x}{:02x}{:02x}",
                data.len(),
                data[0],
                data[1],
                data[2],
                data[3]
            );
        } else {
            log::debug!("module_load: len={} (too small)", data.len());
        }

        let mut registry = MODULE_REGISTRY.lock();
        let id = registry.register(data)?;
        drop(registry);

        let cap = get_capability_manager().create_capability(
            ResourceType::Module,
            id as usize,
            CapPermissions::all(),
        );

        let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
        let cap_id = unsafe { (&mut *task.process.capabilities.get()).insert(cap) };

        return Ok(cap_id.as_u64());
    }

    // TODO: Load from a file handle (fd) via VFS once the path exists.
    // For now, interpret `fd_or_ptr` as either:
    // - a File handle (read all), or
    // - an IPC port handle that streams the module bytes.
    //
    // Stream protocol:
    // - msg_type = IPC_STREAM_DATA, flags = payload length (0..48)
    // - msg_type = IPC_STREAM_EOF (or DATA with flags=0) ends the stream
    let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
    let caps = unsafe { &*task.process.capabilities.get() };
    let required = CapPermissions {
        read: true,
        write: false,
        execute: false,
        grant: false,
        revoke: false,
    };
    let cap = caps
        .get_with_permissions(CapId::from_raw(fd_or_ptr), required)
        .ok_or(SyscallError::PermissionDenied)?;
    let data = match cap.resource_type {
        ResourceType::File => {
            let fd = u32::try_from(cap.resource).map_err(|_| SyscallError::BadHandle)?;
            crate::vfs::read_all(fd)?
        }
        ResourceType::IpcPort => {
            let port_id = PortId::from_u64(cap.resource as u64);
            let port = port::get_port(port_id).ok_or(SyscallError::BadHandle)?;
            read_module_stream_from_port(&port)?
        }
        _ => return Err(SyscallError::BadHandle),
    };
    if data.len() > MAX_MODULE_BLOB_LEN {
        return Err(SyscallError::InvalidArgument);
    }

    let mut registry = MODULE_REGISTRY.lock();
    let id = registry.register(data)?;
    drop(registry);

    let cap = get_capability_manager().create_capability(
        ResourceType::Module,
        id as usize,
        CapPermissions::all(),
    );

    let cap_id = unsafe { (&mut *task.process.capabilities.get()).insert(cap) };

    Ok(cap_id.as_u64())
}

/// Performs the sys module unload operation.
pub fn sys_module_unload(handle: u64) -> Result<u64, SyscallError> {
    require_silo_admin()?;
    let required = CapPermissions {
        read: false,
        write: false,
        execute: false,
        grant: false,
        revoke: true,
    };
    let module_id = resolve_module_handle(handle, required)?;
    let mut registry = MODULE_REGISTRY.lock();
    registry.remove(module_id);
    Ok(0)
}

/// Performs the sys module get symbol operation.
pub fn sys_module_get_symbol(handle: u64, _ordinal: u64) -> Result<u64, SyscallError> {
    let required = CapPermissions {
        read: true,
        write: false,
        execute: false,
        grant: false,
        revoke: false,
    };
    let module_id = resolve_module_handle(handle, required)?;
    let registry = MODULE_REGISTRY.lock();
    let module = registry.get(module_id).ok_or(SyscallError::BadHandle)?;

    // The export table format is a simple array of u64 RVAs indexed by ordinal.
    let rva = resolve_export_offset(module, _ordinal)?;
    let header = module.header.ok_or(SyscallError::InvalidArgument)?;
    Ok(header.code_offset.saturating_add(rva))
}

/// Performs the sys module query operation.
pub fn sys_module_query(handle: u64, out_ptr: u64) -> Result<u64, SyscallError> {
    let required = CapPermissions {
        read: true,
        write: false,
        execute: false,
        grant: false,
        revoke: false,
    };
    let module_id = resolve_module_handle(handle, required)?;
    if out_ptr == 0 {
        return Err(SyscallError::Fault);
    }

    let registry = MODULE_REGISTRY.lock();
    let module = registry.get(module_id).ok_or(SyscallError::BadHandle)?;

    let (format, flags, version, cpu_arch, code_size, data_size, bss_size, entry_point) =
        if let Some(header) = module.header {
            (
                1u32,
                header.flags,
                header.version,
                header.cpu_arch,
                header.code_size,
                header.data_size,
                header.bss_size,
                header.entry_point,
            )
        } else {
            (0u32, 0u32, 0u16, 0u8, 0u64, 0u64, 0u64, 0u64)
        };

    let info = ModuleInfo {
        id: module.id,
        format,
        flags,
        version,
        cpu_arch,
        reserved: 0,
        code_size,
        data_size,
        bss_size,
        entry_point,
        total_size: module.data.len() as u64,
    };

    const INFO_SIZE: usize = core::mem::size_of::<ModuleInfo>();
    let user = UserSliceWrite::new(out_ptr, INFO_SIZE)?;
    let src =
        unsafe { core::slice::from_raw_parts(&info as *const ModuleInfo as *const u8, INFO_SIZE) };
    user.copy_from(src);
    Ok(0)
}

// ============================================================================
// Syscall handlers (kernel entry points)
// ============================================================================

/// Performs the sys silo create operation.
pub fn sys_silo_create(config_ptr: u64) -> Result<u64, SyscallError> {
    require_silo_admin()?;
    let config = read_user_config(config_ptr)?;
    config.validate()?;

    let mut mgr = SILO_MANAGER.lock();
    let id = mgr.create_silo(&config)?;
    drop(mgr);

    let cap = get_capability_manager().create_capability(
        ResourceType::Silo,
        id.sid as usize,
        CapPermissions::all(),
    );

    let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
    let cap_id = unsafe { (&mut *task.process.capabilities.get()).insert(cap) };

    Ok(cap_id.as_u64())
}

/// Performs the sys silo config operation.
pub fn sys_silo_config(handle: u64, res_ptr: u64) -> Result<u64, SyscallError> {
    require_silo_admin()?;
    let config = read_user_config(res_ptr)?;
    config.validate()?;
    let family = decode_family(config.family)?;

    let mut granted_caps = HVec::<u64, 64>::new();
    let mut granted_resources = HVec::<GrantedResource, 32>::new();
    if config.caps_len > 0 {
        let caps_list = read_caps_list(config.caps_ptr, config.caps_len)?;
        let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
        let caps = unsafe { &*task.process.capabilities.get() };

        for cap_handle in caps_list {
            let cap = caps
                .get(CapId::from_raw(cap_handle))
                .ok_or(SyscallError::BadHandle)?;
            if !cap.permissions.grant {
                return Err(SyscallError::PermissionDenied);
            }
            if !is_delegated_resource(cap.resource_type) {
                return Err(SyscallError::InvalidArgument);
            }
            if !granted_caps.contains(&cap_handle) {
                if let Err(cap) = granted_caps.push(cap_handle) {
                    log::warn!(
                        "[silo] granted_caps full (capacity=64), cap {} dropped",
                        cap
                    );
                }
            }
            add_or_merge_granted_resource(
                &mut granted_resources,
                GrantedResource {
                    resource_type: cap.resource_type,
                    resource: cap.resource,
                    permissions: cap.permissions,
                },
            );
        }
    }

    let sid = resolve_silo_handle(handle, CapPermissions::read_write())?;
    let mut mgr = SILO_MANAGER.lock();
    let silo = mgr.get_mut(sid as u32)?;

    let requested_mode = OctalMode::from_octal(config.mode);
    kernel_check_spawn_invariants(&silo.id, &requested_mode)?;
    if silo.sandboxed && !requested_mode.is_subset_of(&silo.mode) {
        return Err(SyscallError::PermissionDenied);
    }
    if silo.sandboxed && !requested_mode.registry.is_empty() {
        return Err(SyscallError::PermissionDenied);
    }

    // XCR0 is a kernel-computed derived value: never trust the
    // user-supplied field (kernel_spawn_strate already derives it).
    let mut config = config;
    config.xcr0_mask = compute_silo_xcr0(&config);

    silo.config = config;
    silo.mode = requested_mode;
    silo.family = family;
    silo.flags = config.flags as u32;
    silo.granted_caps = granted_caps;
    silo.granted_resources = granted_resources;
    Ok(0)
}

/// Performs the sys silo attach module operation.
pub fn sys_silo_attach_module(handle: u64, module_handle: u64) -> Result<u64, SyscallError> {
    require_silo_admin()?;
    let silo_id = resolve_silo_handle(handle, CapPermissions::read_write())?;

    let required = CapPermissions {
        read: true,
        write: false,
        execute: false,
        grant: false,
        revoke: false,
    };
    let module_id = resolve_module_handle(module_handle, required)?;

    let mut mgr = SILO_MANAGER.lock();
    let silo = mgr.get_mut(silo_id)?;

    match silo.state {
        SiloState::Created | SiloState::Stopped | SiloState::Ready => {
            silo.module_id = Some(module_id);
            silo.state = SiloState::Ready;
            Ok(0)
        }
        SiloState::Running | SiloState::Paused => {
            silo.module_id = Some(module_id);
            Ok(0)
        }
        _ => Err(SyscallError::InvalidArgument),
    }
}

/// Starts silo by id.
fn start_silo_by_id(silo_id: u32) -> Result<u64, SyscallError> {
    let (
        module_id,
        granted_caps,
        granted_resources,
        silo_flags,
        previous_state,
        can_start,
        within_task_limit,
        silo_name,
        silo_label,
    ) = {
        let mut mgr = SILO_MANAGER.lock();
        let silo = mgr.get_mut(silo_id)?;
        let previous_state = silo.state;
        let can_start = matches!(
            previous_state,
            SiloState::Ready | SiloState::Stopped | SiloState::Running
        );
        let within_task_limit = match silo.config.max_tasks {
            0 => true, // 0 = unlimited
            max => silo.tasks.len() < max as usize,
        };
        let module_id = silo.module_id;
        let granted_caps = silo.granted_caps.clone();
        let granted_resources = silo.granted_resources.clone();
        let silo_flags = silo.config.flags;
        let silo_name = silo.name.clone();
        let silo_label = silo.strate_label.clone();
        if can_start && within_task_limit {
            silo.state = SiloState::Loading;
        }
        (
            module_id,
            granted_caps,
            granted_resources,
            silo_flags,
            previous_state,
            can_start,
            within_task_limit,
            silo_name,
            silo_label,
        )
    };

    if !can_start {
        return Err(SyscallError::InvalidArgument);
    }
    if !within_task_limit {
        return Err(SyscallError::QueueFull);
    }

    let rollback_loading = |state: SiloState| {
        let mut mgr = SILO_MANAGER.lock();
        if let Ok(silo) = mgr.get_mut(silo_id) {
            if matches!(silo.state, SiloState::Loading) {
                silo.state = state;
            }
        }
    };

    let module_id = match module_id {
        Some(id) => id,
        None => {
            rollback_loading(previous_state);
            return Err(SyscallError::InvalidArgument);
        }
    };

    let mut seed_caps = {
        let task = match current_task_clone() {
            Some(t) => t,
            None => {
                rollback_loading(previous_state);
                return Err(SyscallError::PermissionDenied);
            }
        };
        let caps = unsafe { &mut *task.process.capabilities.get() };
        let mut out = Vec::with_capacity(granted_caps.len());
        for handle in granted_caps {
            // Enforce: caller must currently hold the capability.
            if !silo_has_capability(&task, handle) {
                rollback_loading(previous_state);
                return Err(SyscallError::PermissionDenied);
            }
            let Some(dup) = caps.duplicate(CapId::from_raw(handle)) else {
                rollback_loading(previous_state);
                return Err(SyscallError::PermissionDenied);
            };
            // Capability-confusion guard: granted_caps stores raw handle
            // slots recorded when the silo was configured (possibly by a
            // different process). Slot numbers are per-process: the starter
            // could hold an unrelated capability at the same slot. Verify
            // the duplicated capability actually matches a resource that
            // was explicitly granted to this silo before seeding it.
            let authorized = granted_resources
                .iter()
                .any(|g| g.resource_type == dup.resource_type && g.resource == dup.resource);
            if !authorized {
                log::warn!(
                    "[silo] start sid={}: cap handle {} does not match any \
                     granted resource (type={:?}, resource={:#x}) - denied",
                    silo_id,
                    handle,
                    dup.resource_type,
                    dup.resource
                );
                rollback_loading(previous_state);
                return Err(SyscallError::PermissionDenied);
            }
            out.push(dup);
        }
        out
    };
    if silo_flags & SILO_FLAG_ADMIN != 0 {
        seed_caps.push(create_silo_admin_capability());
    }

    let display = silo_label.unwrap_or(silo_name);
    let task_name_owned = if silo_flags & SILO_FLAG_ADMIN != 0 {
        alloc::format!("silo-{}/strate-admin-{}", silo_id, display)
    } else {
        alloc::format!("silo-{}/strate-{}", silo_id, display)
    };
    // Intentional leak: task names are expected to live for the task lifetime.
    // This avoids generic "silo" labels in process viewers.
    let task_name: &'static str = Box::leak(task_name_owned.into_boxed_str());

    let module_data = {
        let registry = MODULE_REGISTRY.lock();
        match registry.get(module_id) {
            Some(module) => module.data.clone(),
            None => {
                rollback_loading(previous_state);
                return Err(SyscallError::BadHandle);
            }
        }
    };

    let load_result =
        crate::process::elf::load_elf_task_with_caps(module_data.as_slice(), task_name, &seed_caps)
            .map_err(|err| {
                log::warn!(
                    "silo_start: sid={} module={} task='{}' load failed: {}",
                    silo_id,
                    module_id,
                    task_name,
                    err
                );
                map_elf_start_error(err)
            });

    let task = match load_result {
        Ok(task) => task,
        Err(e) => {
            rollback_loading(previous_state);
            return Err(e);
        }
    };
    let task_id = task.id;
    let task_pid = task.pid;

    // Give the silo an EOF stdin so that any read(0, …) returns 0 immediately
    // instead of EBADF (which can cause busy-loops) or blocking on the
    // keyboard (which would steal input from the foreground shell).
    let bg_stdin = crate::vfs::create_background_stdin();
    let fd_table = unsafe { &mut *task.process.fd_table.get() };
    fd_table.insert_at(crate::vfs::STDIN, bg_stdin);

    let mut mgr = SILO_MANAGER.lock();
    {
        let silo = match mgr.get_mut(silo_id) {
            Ok(silo) => silo,
            Err(e) => {
                return Err(e);
            }
        };
        if let Err(task) = silo.tasks.push(task_id) {
            log::error!(
                "[silo] tasks full (capacity=64), task {} not registered",
                task.0
            );
        }
        silo.state = SiloState::Running;
        let fpu_xcr0 = unsafe { (*task.fpu_state.get()).xcr0_mask };
        let effective_xcr0 = (silo.config.xcr0_mask & fpu_xcr0).max(0x3);
        task.xcr0_mask
            .store(effective_xcr0, core::sync::atomic::Ordering::Relaxed);
        // Propagate silo CPU affinity to task for scheduler placement.
        let affinity = silo.config.cpu_affinity_mask;
        if affinity != 0 {
            task.affinity_mask
                .store(affinity, core::sync::atomic::Ordering::Relaxed);
        }
    }
    mgr.map_task(task_id, silo_id);
    mgr.push_event(SiloEvent {
        silo_id: silo_id.into(),
        kind: SiloEventKind::Started,
        data0: 0,
        data1: 0,
        tick: crate::process::scheduler::ticks(),
    });
    drop(mgr);
    crate::process::add_task(task);
    Ok(task_pid as u64)
}

/// Performs the sys silo start operation.
pub fn sys_silo_start(handle: u64) -> Result<u64, SyscallError> {
    require_silo_admin()?;
    let required = CapPermissions {
        read: false,
        write: false,
        execute: true,
        grant: false,
        revoke: false,
    };
    let silo_id = resolve_silo_handle(handle, required)?;
    start_silo_by_id(silo_id)
}

/// Best-effort cleanup hook called by the scheduler when a task terminates.
///
/// Ensures `task_to_silo` mappings are removed even for normal exits and
/// transitions a running/paused silo to `Stopped` when its last task is gone.
pub fn on_task_terminated(task_id: TaskId) {
    let mut mgr = SILO_MANAGER.lock();
    let silo_id = match mgr.silo_for_task(task_id) {
        Some(id) => id,
        None => return,
    };
    mgr.unmap_task(task_id);

    let mut emit_stopped = false;
    if let Ok(silo) = mgr.get_mut(silo_id) {
        if let Some(pos) = silo.tasks.iter().position(|tid| *tid == task_id) {
            silo.tasks.swap_remove(pos);
        }
        if silo.tasks.is_empty() {
            match silo.state {
                SiloState::Running | SiloState::Paused | SiloState::Stopping => {
                    silo.state = SiloState::Stopped;
                    silo.event_seq = silo.event_seq.wrapping_add(1);
                    emit_stopped = true;
                }
                _ => {}
            }
        }
    }

    if emit_stopped {
        mgr.push_event(SiloEvent {
            silo_id: silo_id.into(),
            kind: SiloEventKind::Stopped,
            data0: 0,
            data1: 0,
            tick: crate::process::scheduler::ticks(),
        });
    }
}

/// Stops or kill silo by id.
fn stop_or_kill_silo_by_id(
    silo_id: u32,
    force_kill: bool,
    require_running: bool,
) -> Result<HVec<TaskId, 64>, SyscallError> {
    let mut mgr = SILO_MANAGER.lock();
    let tasks = {
        let silo = mgr.get_mut(silo_id)?;
        if force_kill {
            silo.state = SiloState::Stopped;
            let tasks = silo.tasks.clone();
            silo.tasks.clear();
            tasks
        } else {
            match silo.state {
                SiloState::Running | SiloState::Paused => {
                    silo.state = SiloState::Stopping;
                    let tasks = silo.tasks.clone();
                    silo.tasks.clear();
                    tasks
                }
                _ if require_running => return Err(SyscallError::InvalidArgument),
                _ => HVec::new(),
            }
        }
    };

    for tid in &tasks {
        mgr.unmap_task(*tid);
    }
    if !force_kill {
        if let Ok(silo) = mgr.get_mut(silo_id) {
            silo.state = SiloState::Stopped;
        }
    }
    mgr.push_event(SiloEvent {
        silo_id: silo_id.into(),
        kind: if force_kill {
            SiloEventKind::Killed
        } else {
            SiloEventKind::Stopped
        },
        data0: 0,
        data1: 0,
        tick: crate::process::scheduler::ticks(),
    });

    Ok(tasks)
}

/// Performs the sys silo stop operation.
pub fn sys_silo_stop(handle: u64) -> Result<u64, SyscallError> {
    require_silo_admin()?;
    let required = CapPermissions {
        read: false,
        write: false,
        execute: true,
        grant: false,
        revoke: false,
    };
    let silo_id = resolve_silo_handle(handle, required)?;
    let tasks = stop_or_kill_silo_by_id(silo_id, false, true)?;

    for tid in tasks {
        crate::process::kill_task(tid);
    }
    Ok(0)
}

/// Performs the sys silo kill operation.
pub fn sys_silo_kill(handle: u64) -> Result<u64, SyscallError> {
    require_silo_admin()?;
    let required = CapPermissions {
        read: false,
        write: false,
        execute: true,
        grant: false,
        revoke: false,
    };
    let silo_id = resolve_silo_handle(handle, required)?;
    let tasks = stop_or_kill_silo_by_id(silo_id, true, false)?;

    for tid in tasks {
        crate::process::kill_task(tid);
    }
    Ok(0)
}

/// Performs the silo has capability operation.
fn silo_has_capability(task: &Task, cap_id: u64) -> bool {
    let caps = unsafe { &*task.process.capabilities.get() };
    caps.get(CapId::from_raw(cap_id)).is_some()
}

/// Returns whether delegated resource.
fn is_delegated_resource(rt: ResourceType) -> bool {
    matches!(
        rt,
        ResourceType::Nic
            | ResourceType::FileSystem
            | ResourceType::Console
            | ResourceType::Keyboard
            | ResourceType::Volume
            | ResourceType::Namespace
            | ResourceType::Device
            | ResourceType::File
            | ResourceType::IoPortRange
            | ResourceType::InterruptLine
    )
}

/// Returns whether admin task.
fn is_admin_task(task: &Task) -> bool {
    let caps = unsafe { &*task.process.capabilities.get() };
    let required = CapPermissions {
        read: false,
        write: false,
        execute: false,
        grant: true,
        revoke: false,
    };
    caps.has_resource_with_permissions(ResourceType::Silo, SILO_ADMIN_RESOURCE, required)
}

/// Maps elf start error.
fn map_elf_start_error(err: &'static str) -> SyscallError {
    if err.contains("allocate")
        || err.contains("Out of memory")
        || err.contains("No virtual range")
        || err.contains("Failed to map page")
    {
        return SyscallError::OutOfMemory;
    }
    if err.contains("ELF")
        || err.contains("PT_")
        || err.contains("entry")
        || err.contains("relocation")
        || err.contains("Program header")
        || err.contains("x86_64")
        || err.contains("Unsupported")
    {
        return SyscallError::ExecFormatError;
    }
    SyscallError::InvalidArgument
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct GrantedResource {
    resource_type: ResourceType,
    resource: usize,
    permissions: CapPermissions,
}

/// Performs the merge permissions operation.
fn merge_permissions(a: CapPermissions, b: CapPermissions) -> CapPermissions {
    CapPermissions {
        read: a.read || b.read,
        write: a.write || b.write,
        execute: a.execute || b.execute,
        grant: a.grant || b.grant,
        revoke: a.revoke || b.revoke,
    }
}

/// Performs the permissions subset operation.
fn permissions_subset(requested: CapPermissions, allowed: CapPermissions) -> bool {
    (!requested.read || allowed.read)
        && (!requested.write || allowed.write)
        && (!requested.execute || allowed.execute)
        && (!requested.grant || allowed.grant)
        && (!requested.revoke || allowed.revoke)
}

/// Performs the add or merge granted resource operation.
fn add_or_merge_granted_resource(list: &mut HVec<GrantedResource, 32>, grant: GrantedResource) {
    for existing in list.iter_mut() {
        if existing.resource_type == grant.resource_type && existing.resource == grant.resource {
            existing.permissions = merge_permissions(existing.permissions, grant.permissions);
            return;
        }
    }
    if list.push(grant).is_err() {
        log::warn!("[silo] granted_resources full (capacity=32), resource dropped");
    }
}

/// Performs the register current task granted resource operation.
pub fn register_current_task_granted_resource(
    resource_type: ResourceType,
    resource: usize,
    permissions: CapPermissions,
) -> Result<(), SyscallError> {
    let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
    let mut mgr = SILO_MANAGER.lock();
    let silo_id = mgr
        .silo_for_task(task.id)
        .ok_or(SyscallError::PermissionDenied)?;
    let silo = mgr.get_mut(silo_id)?;
    add_or_merge_granted_resource(
        &mut silo.granted_resources,
        GrantedResource {
            resource_type,
            resource,
            permissions,
        },
    );
    Ok(())
}

/// Enforce that the current task may use a delegated capability.
pub fn enforce_cap_for_current_task(handle: u64) -> Result<(), SyscallError> {
    let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;

    // Admin tasks bypass delegated-cap enforcement.
    if is_admin_task(&task) {
        return Ok(());
    }

    let caps = unsafe { &*task.process.capabilities.get() };
    let cap = caps
        .get(CapId::from_raw(handle))
        .ok_or(SyscallError::BadHandle)?;

    if !is_delegated_resource(cap.resource_type) {
        return Ok(());
    }

    let mgr = SILO_MANAGER.lock();
    if let Some(silo_id) = mgr.silo_for_task(task.id) {
        if let Ok(silo) = mgr.get(silo_id) {
            for grant in &silo.granted_resources {
                if grant.resource_type == cap.resource_type && grant.resource == cap.resource {
                    if permissions_subset(cap.permissions, grant.permissions) {
                        return Ok(());
                    }
                    return Err(SyscallError::PermissionDenied);
                }
            }
        }
    }

    Err(SyscallError::PermissionDenied)
}

/// Performs the enforce registry bind for current task operation.
pub fn enforce_registry_bind_for_current_task() -> Result<(), SyscallError> {
    let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
    if is_admin_task(&task) {
        return Ok(());
    }
    let mgr = SILO_MANAGER.lock();
    let silo_id = mgr
        .silo_for_task(task.id)
        .ok_or(SyscallError::PermissionDenied)?;
    let silo = mgr.get(silo_id)?;
    if silo.sandboxed {
        return Err(SyscallError::PermissionDenied);
    }
    if silo.mode.registry.contains(RegistryMode::BIND) {
        Ok(())
    } else {
        Err(SyscallError::PermissionDenied)
    }
}

/// Enforce console access for the current task.
///
/// Only admin tasks or tasks holding a Console capability with write permission
/// can access the kernel console (SYS_WRITE fd=1/2).
pub fn enforce_console_access() -> Result<(), SyscallError> {
    let task = current_task_clone().ok_or(SyscallError::PermissionDenied)?;
    if is_admin_task(&task) {
        return Ok(());
    }
    let mgr = SILO_MANAGER.lock();
    if let Some(silo_id) = mgr.silo_for_task(task.id) {
        if let Ok(silo) = mgr.get(silo_id) {
            if matches!(silo.family, StrateFamily::SYS | StrateFamily::NET) {
                return Ok(());
            }
        }
    }
    drop(mgr);
    let caps = unsafe { &*task.process.capabilities.get() };
    let required = CapPermissions {
        read: false,
        write: true,
        execute: false,
        grant: false,
        revoke: false,
    };
    if caps.has_resource_type_with_permissions(ResourceType::Console, required) {
        Ok(())
    } else {
        Err(SyscallError::PermissionDenied)
    }
}

/// Performs the sys silo event next operation.
pub fn sys_silo_event_next(_event_ptr: u64) -> Result<u64, SyscallError> {
    require_silo_admin()?;
    if _event_ptr == 0 {
        return Err(SyscallError::Fault);
    }

    let event = {
        let mut mgr = SILO_MANAGER.lock();
        mgr.events.pop_front()
    };

    let event = match event {
        Some(e) => e,
        None => return Err(SyscallError::Again),
    };

    const EVT_SIZE: usize = core::mem::size_of::<SiloEvent>();
    let user = UserSliceWrite::new(_event_ptr, EVT_SIZE)?;
    let src =
        unsafe { core::slice::from_raw_parts(&event as *const SiloEvent as *const u8, EVT_SIZE) };
    user.copy_from(src);
    Ok(0)
}

/// Performs the sys silo suspend operation.
pub fn sys_silo_suspend(handle: u64) -> Result<u64, SyscallError> {
    require_silo_admin()?;
    let required = CapPermissions {
        read: false,
        write: false,
        execute: true,
        grant: false,
        revoke: false,
    };
    let silo_id = resolve_silo_handle(handle, required)?;

    // Lock is released before suspend_task (which takes the scheduler lock)
    // to avoid lock-ordering deadlock. Tasks added between the two locks
    // won't be suspended : acceptable best-effort trade-off.
    let tasks = {
        let mut mgr = SILO_MANAGER.lock();
        let silo = mgr.get_mut(silo_id)?;
        match silo.state {
            SiloState::Running => {
                silo.state = SiloState::Paused;
                silo.tasks.clone()
            }
            _ => return Err(SyscallError::InvalidArgument),
        }
    };

    for tid in &tasks {
        crate::process::suspend_task(*tid);
    }

    let mut mgr = SILO_MANAGER.lock();
    mgr.push_event(SiloEvent {
        silo_id: silo_id.into(),
        kind: SiloEventKind::Paused,
        data0: 0,
        data1: 0,
        tick: crate::process::scheduler::ticks(),
    });

    Ok(0)
}

/// Performs the sys silo resume operation.
pub fn sys_silo_resume(handle: u64) -> Result<u64, SyscallError> {
    require_silo_admin()?;
    let required = CapPermissions {
        read: false,
        write: false,
        execute: true,
        grant: false,
        revoke: false,
    };
    let silo_id = resolve_silo_handle(handle, required)?;

    let tasks = {
        let mut mgr = SILO_MANAGER.lock();
        let silo = mgr.get_mut(silo_id)?;
        match silo.state {
            SiloState::Paused => {
                silo.state = SiloState::Running;
                silo.tasks.clone()
            }
            _ => return Err(SyscallError::InvalidArgument),
        }
    };

    // Same lock-ordering pattern as sys_silo_suspend (see note there).
    for tid in &tasks {
        crate::process::resume_task(*tid);
    }

    let mut mgr = SILO_MANAGER.lock();
    mgr.push_event(SiloEvent {
        silo_id: silo_id.into(),
        kind: SiloEventKind::Resumed,
        data0: 0,
        data1: 0,
        tick: crate::process::scheduler::ticks(),
    });

    Ok(0)
}

// ============================================================================
// Kernel-side CLI helpers (no capability gate : shell runs in Ring 0)
// ============================================================================

pub fn kernel_suspend_silo(selector: &str) -> Result<u32, SyscallError> {
    let (silo_id, tasks) = {
        let mut mgr = SILO_MANAGER.lock();
        let silo_id = resolve_selector_to_silo_id(selector, &mgr)?;
        let silo = mgr.get_mut(silo_id)?;
        match silo.state {
            SiloState::Running => {
                silo.state = SiloState::Paused;
                let t = silo.tasks.clone();
                (silo_id, t)
            }
            _ => return Err(SyscallError::InvalidArgument),
        }
    };
    for tid in &tasks {
        crate::process::suspend_task(*tid);
    }
    let mut mgr = SILO_MANAGER.lock();
    mgr.push_event(SiloEvent {
        silo_id: silo_id.into(),
        kind: SiloEventKind::Paused,
        data0: 0,
        data1: 0,
        tick: crate::process::scheduler::ticks(),
    });
    Ok(silo_id)
}

pub fn kernel_resume_silo(selector: &str) -> Result<u32, SyscallError> {
    let (silo_id, tasks) = {
        let mut mgr = SILO_MANAGER.lock();
        let silo_id = resolve_selector_to_silo_id(selector, &mgr)?;
        let silo = mgr.get_mut(silo_id)?;
        match silo.state {
            SiloState::Paused => {
                silo.state = SiloState::Running;
                let t = silo.tasks.clone();
                (silo_id, t)
            }
            _ => return Err(SyscallError::InvalidArgument),
        }
    };
    for tid in &tasks {
        crate::process::resume_task(*tid);
    }
    let mut mgr = SILO_MANAGER.lock();
    mgr.push_event(SiloEvent {
        silo_id: silo_id.into(),
        kind: SiloEventKind::Resumed,
        data0: 0,
        data1: 0,
        tick: crate::process::scheduler::ticks(),
    });
    Ok(silo_id)
}

pub fn silo_detail_snapshot(selector: &str) -> Result<SiloDetailSnapshot, SyscallError> {
    let mgr = SILO_MANAGER.lock();
    let silo_id = resolve_selector_to_silo_id(selector, &mgr)?;
    let s = mgr.get(silo_id)?;
    Ok(SiloDetailSnapshot {
        base: SiloSnapshot {
            id: s.id.sid,
            tier: s.id.tier,
            name: s.name.clone(),
            strate_label: s.strate_label.clone(),
            state: s.state,
            task_count: s.tasks.len(),
            mem_usage_bytes: s.mem_usage_bytes,
            mem_min_bytes: s.config.mem_min,
            mem_max_bytes: s.config.mem_max,
            mode: s.config.mode,
            graphics_flags: s.config.flags
                & (SILO_FLAG_GRAPHICS
                    | SILO_FLAG_WEBRTC_NATIVE
                    | SILO_FLAG_GRAPHICS_READ_ONLY
                    | SILO_FLAG_WEBRTC_TURN_FORCE),
            graphics_max_sessions: s.config.graphics_max_sessions,
            graphics_session_ttl_sec: s.config.graphics_session_ttl_sec,
        },
        family: s.family,
        sandboxed: s.sandboxed,
        cpu_shares: s.config.cpu_shares,
        cpu_affinity_mask: s.config.cpu_affinity_mask,
        max_tasks: s.config.max_tasks,
        task_ids: s.tasks.iter().map(|t| t.as_u64()).collect(),
        unveil_rules: s
            .unveil_rules
            .iter()
            .map(|r| {
                let bits = (if r.rights.read { 4 } else { 0 })
                    | (if r.rights.write { 2 } else { 0 })
                    | (if r.rights.execute { 1 } else { 0 });
                (r.path.clone(), bits)
            })
            .collect(),
        granted_caps_count: s.granted_caps.len(),
        cpu_features_required: s.config.cpu_features_required,
        cpu_features_allowed: s.config.cpu_features_allowed,
        xcr0_mask: s.config.xcr0_mask,
        graphics_flags: s.config.flags
            & (SILO_FLAG_GRAPHICS
                | SILO_FLAG_WEBRTC_NATIVE
                | SILO_FLAG_GRAPHICS_READ_ONLY
                | SILO_FLAG_WEBRTC_TURN_FORCE),
        graphics_max_sessions: s.config.graphics_max_sessions,
        graphics_session_ttl_sec: s.config.graphics_session_ttl_sec,
    })
}

pub fn list_events_snapshot() -> Vec<SiloEventSnapshot> {
    let mgr = SILO_MANAGER.lock();
    mgr.events
        .iter()
        .map(|e| SiloEventSnapshot {
            silo_id: e.silo_id,
            kind: e.kind,
            data0: e.data0,
            data1: e.data1,
            tick: e.tick,
        })
        .collect()
}

pub fn list_events_for_silo(selector: &str) -> Result<Vec<SiloEventSnapshot>, SyscallError> {
    let mgr = SILO_MANAGER.lock();
    let silo_id = resolve_selector_to_silo_id(selector, &mgr)?;
    let sid64 = silo_id as u64;
    Ok(mgr
        .events
        .iter()
        .filter(|e| e.silo_id == sid64)
        .map(|e| SiloEventSnapshot {
            silo_id: e.silo_id,
            kind: e.kind,
            data0: e.data0,
            data1: e.data1,
            tick: e.tick,
        })
        .collect())
}

pub fn kernel_pledge_silo(selector: &str, mode_val: u16) -> Result<(u16, u16), SyscallError> {
    let new_mode = OctalMode::from_octal(mode_val);
    let mut mgr = SILO_MANAGER.lock();
    let silo_id = resolve_selector_to_silo_id(selector, &mgr)?;
    let silo = mgr.get_mut(silo_id)?;
    let old_raw = silo.config.mode;
    silo.mode.pledge(new_mode)?;
    silo.config.mode = mode_val;
    Ok((old_raw, mode_val))
}

pub fn kernel_unveil_silo(
    selector: &str,
    path: &str,
    rights_str: &str,
) -> Result<u32, SyscallError> {
    let rights = UnveilRights {
        read: rights_str.contains('r'),
        write: rights_str.contains('w'),
        execute: rights_str.contains('x'),
    };
    let mut mgr = SILO_MANAGER.lock();
    let silo_id = resolve_selector_to_silo_id(selector, &mgr)?;
    let silo = mgr.get_mut(silo_id)?;
    if let Some(rule) = silo.unveil_rules.iter_mut().find(|r| r.path == path) {
        rule.rights = rights;
    } else {
        if silo
            .unveil_rules
            .push(UnveilRule {
                path: String::from(path),
                rights,
            })
            .is_err()
        {
            log::warn!("[silo] unveil_rules full (capacity=128), rule dropped");
        }
    }
    Ok(silo_id)
}

pub fn kernel_sandbox_silo(selector: &str) -> Result<u32, SyscallError> {
    let mut mgr = SILO_MANAGER.lock();
    let silo_id = resolve_selector_to_silo_id(selector, &mgr)?;
    let silo = mgr.get_mut(silo_id)?;
    silo.sandboxed = true;
    crate::audit::log(
        crate::audit::AuditCategory::Security,
        0,
        silo_id,
        alloc::format!("silo sandboxed"),
    );
    Ok(silo_id)
}

/// Get the silo ID for a given task, if any.
pub fn task_silo_id(task_id: TaskId) -> Option<u32> {
    SILO_MANAGER.lock().silo_for_task(task_id)
}

/// Append data to a silo's output ring buffer (called from `sys_debug_log`).
pub fn silo_output_write(silo_id: u32, data: &[u8]) {
    let mut mgr = SILO_MANAGER.lock();
    if let Ok(silo) = mgr.get_mut(silo_id) {
        let buf = silo
            .output_buf
            .get_or_insert_with(|| Box::new(SiloOutputBuf::new()));
        buf.push(data);
    }
}

/// Drain the output buffer for a silo, returning accumulated bytes.
pub fn silo_output_drain(selector: &str) -> Result<Vec<u8>, SyscallError> {
    let mut mgr = SILO_MANAGER.lock();
    let silo_id = resolve_selector_to_silo_id(selector, &mgr)?;
    let silo = mgr.get_mut(silo_id)?;
    let mut buf = match silo.output_buf.take() {
        Some(buf) => buf,
        None => return Ok(Vec::new()),
    };
    let out = buf.drain();
    silo.output_buf = Some(buf);
    Ok(out)
}

/// Dynamically adjust resource quotas for a silo.
///
/// `key` can be: `mem_max`, `mem_min`, `max_tasks`, `cpu_shares`.
/// Values are parsed as u64 (bytes for memory, count otherwise).
pub fn kernel_limit_silo(selector: &str, key: &str, value: u64) -> Result<u32, SyscallError> {
    let mut mgr = SILO_MANAGER.lock();
    let silo_id = resolve_selector_to_silo_id(selector, &mgr)?;
    let silo = mgr.get_mut(silo_id)?;
    let mut next_mem_min = silo.config.mem_min;
    let mut next_mem_max = silo.config.mem_max;
    let mut next_max_tasks = silo.config.max_tasks;
    let mut next_cpu_shares = silo.config.cpu_shares;
    match key {
        "mem_max" => next_mem_max = value,
        "mem_min" => next_mem_min = value,
        "max_tasks" => {
            if value > u32::MAX as u64 {
                return Err(SyscallError::InvalidArgument);
            }
            next_max_tasks = value as u32;
        }
        "cpu_shares" => {
            if value > u32::MAX as u64 {
                return Err(SyscallError::InvalidArgument);
            }
            next_cpu_shares = value as u32;
        }
        _ => return Err(SyscallError::InvalidArgument),
    }
    if next_mem_max != 0 && next_mem_min > next_mem_max {
        return Err(SyscallError::InvalidArgument);
    }
    silo.config.mem_min = next_mem_min;
    silo.config.mem_max = next_mem_max;
    silo.config.max_tasks = next_max_tasks;
    silo.config.cpu_shares = next_cpu_shares;
    crate::audit::log(
        crate::audit::AuditCategory::Security,
        0,
        silo_id,
        alloc::format!("silo limit: {}={}", key, value),
    );
    Ok(silo_id)
}

// ============================================================================
// Fault handling (called from exception handlers)
// ============================================================================

/// Performs the dump user fault operation.
fn dump_user_fault(task_id: TaskId, reason: SiloFaultReason, extra: u64, subcode: u64, rip: u64) {
    let task_meta = crate::process::get_task_by_id(task_id).map(|task| {
        let state = task.get_state();
        let as_ref = task.process.address_space_arc();
        (
            task.pid,
            task.tid,
            task.name,
            state,
            as_ref.cr3().as_u64(),
            as_ref.is_kernel(),
        )
    });

    if let Some((pid, tid, name, state, as_cr3, as_is_kernel)) = task_meta {
        crate::serial_force_println!(
            "\x1b[31m[handle_user_fault]\x1b[0m task={} \x1b[36mpid={}\x1b[0m tid={} name='{}' state={:?} reason={:?} \x1b[35mrip={:#x}\x1b[0m \x1b[35mextra={:#x}\x1b[0m subcode={:#x} as_cr3={:#x} as_kernel={}",
            task_id.as_u64(),
            pid,
            tid,
            name,
            state,
            reason,
            rip,
            extra,
            subcode,
            as_cr3,
            as_is_kernel
        );
    } else {
        crate::serial_force_println!(
            "\x1b[31m[handle_user_fault]\x1b[0m task={} reason={:?} \x1b[35mrip={:#x}\x1b[0m \x1b[35mextra={:#x}\x1b[0m subcode={:#x} (task metadata unavailable)",
            task_id.as_u64(),
            reason,
            rip,
            extra,
            subcode
        );
    }

    if reason == SiloFaultReason::PageFault {
        let present = (subcode & 0x1) != 0;
        let write = (subcode & 0x2) != 0;
        let user = (subcode & 0x4) != 0;
        let reserved = (subcode & 0x8) != 0;
        let instr_fetch = (subcode & 0x10) != 0;
        let pkey = (subcode & 0x20) != 0;
        let shadow_stack = (subcode & 0x40) != 0;
        let sgx = (subcode & 0x8000) != 0;
        crate::serial_force_println!(
            "\x1b[31m[handle_user_fault]\x1b[0m \x1b[31mpagefault\x1b[0m \x1b[35maddr={:#x}\x1b[0m \x1b[35mrip={:#x}\x1b[0m ec={:#x} present={} write={} user={} reserved={} ifetch={} pkey={} shadow_stack={} sgx={}",
            extra,
            rip,
            subcode,
            present,
            write,
            user,
            reserved,
            instr_fetch,
            pkey,
            shadow_stack,
            sgx
        );
        if user && extra < 0x1000 {
            crate::serial_force_println!(
                "\x1b[31m[handle_user_fault]\x1b[0m \x1b[33mhint: low user address fault ({:#x}) -> probable NULL/near-NULL dereference\x1b[0m",
                extra
            );
        }
    } else {
        crate::serial_force_println!(
            "\x1b[31m[handle_user_fault]\x1b[0m \x1b[31mfault detail\x1b[0m \x1b[35mrip={:#x}\x1b[0m code={:#x}",
            rip,
            subcode
        );
    }
}

/// Handles user fault.
pub fn handle_user_fault(
    task_id: TaskId,
    reason: SiloFaultReason,
    extra: u64,
    subcode: u64,
    rip: u64,
) {
    // FORCE OUTPUT for user fault - bypasses normal logging mutexes
    crate::serial_force_println!(
        "\x1b[31;1m[handle_user_fault] CRITICAL FAULT\x1b[0m: tid={} reason={:?} rip={:#x} addr={:#x} err={:#x}",
        task_id.as_u64(),
        reason,
        rip,
        extra,
        subcode
    );

    dump_user_fault(task_id, reason, extra, subcode, rip);

    // Best-effort: map task to silo, mark crashed, emit event, kill tasks.
    let tasks = {
        let mut mgr = SILO_MANAGER.lock();
        let silo_id = match mgr.silo_for_task(task_id) {
            Some(id) => id,
            None => {
                crate::serial_force_println!(
                    "[handle_user_fault] Non-silo task {} crashed (reason={:?})! Killing it.",
                    task_id.as_u64(),
                    reason
                );
                drop(mgr);
                crate::process::kill_task(task_id);
                return;
            }
        };
        let mut tasks = HVec::<TaskId, 64>::new();
        {
            if let Ok(silo) = mgr.get_mut(silo_id) {
                silo.state = SiloState::Crashed;
                tasks = silo.tasks.clone();
                silo.tasks.clear();
                silo.event_seq = silo.event_seq.wrapping_add(1);
            }
        }
        for tid in &tasks {
            mgr.unmap_task(*tid);
        }
        mgr.push_event(SiloEvent {
            silo_id: silo_id.into(),
            kind: SiloEventKind::Crashed,
            data0: pack_fault(reason, subcode),
            data1: extra,
            tick: crate::process::scheduler::ticks(),
        });
        tasks
    };

    for tid in &tasks {
        crate::process::kill_task(*tid);
    }
    if !tasks.contains(&task_id) {
        crate::process::kill_task(task_id);
    }
}