sptos-nucleus

Integration crate for SPTOS Cognition Kernel with syscall dispatch and deterministic replay

Overview

sptos-nucleus is the top-level integration crate that brings all SPTOS subsystems together. It provides the syscall dispatch table for all 12 ADR-087 syscalls, the unified Kernel struct coordinating all managers, deterministic checkpoint/restore replay, and an optional in-kernel debug shell. This is the crate that applications instantiate to run SPTOS.

Key Features

• 12-syscall dispatch — Complete syscall table covering regions, capabilities, queues, vectors, graphs, proofs, scheduling, and SPF mounting
• Unified Kernel struct — Single entry point coordinating RegionMgr, CapMgr, QueueMgr, Scheduler, ProofEngine, VectorStore, GraphStore, and WitnessLog
• Deterministic replay — Checkpoint/restore support for reproducing exact kernel execution sequences
• Witness logging — Every mutation is recorded with a typed witness record
• Optional debug shell — Integrate sptos-shell backend for runtime inspection

Dependencies

Key internal dependencies:

• sptos-types — All kernel type definitions
• sptos-region — Memory region management
• sptos-cap — Capability enforcement
• sptos-queue — Inter-task IPC
• sptos-sched — Task scheduling
• sptos-vecgraph — Vector and graph stores
• sptos-proof — Proof verification engine
• sptos-shell (optional) — Debug shell backend

Usage

use sptos_nucleus::{Kernel, KernelConfig, Syscall};
use sptos_types::RegionPolicy;

let mut kernel = Kernel::new(KernelConfig::default());

let result = kernel.dispatch(Syscall::RegionMap {
    size: 4096,
    policy: RegionPolicy::AppendOnly { max_size: 4096 },
    cap: root_cap,
});

API Reference

Core Types

Type	Description
Kernel	Top-level kernel struct coordinating all subsystems
KernelConfig	Configuration for all kernel subsystems
Syscall	Enum of all 12 SPTOS syscalls
SyscallResult	Result type returned by syscall dispatch
Checkpoint	Serializable kernel state snapshot
ReplayEngine	Deterministic replay from checkpoint
WitnessLog	Append-only mutation record log
WitnessRecord	Individual witness entry with kind and payload