Palladium

Palladium product code and operator-facing documentation live here. Handshake governance, planning, and dispatch tracking live in ../palladium-dev/.

Palladium is a high-performance, thread-per-core actor runtime engine implemented in Rust. It provides a robust framework for building distributed systems with a focus on predictable latency, strict resource isolation, and deterministic testing.

Phase 1 note: Palladium is intentionally off the embedded GraphRAG critical path. The current product-facing contract work focuses on stable replay and orchestration-adjacent surfaces that keep later bounded-cluster integration possible without forcing runtime adoption in the embedded evaluator phase. See Phase 1 Boundary and Phase 1 Closeout.

Phase 2 note: Sprint 4 extends those trust surfaces into support-band and release-gate guidance for adjacent teams without introducing bounded-cluster runtime behavior. See Phase 2 Release Gates and Phase 2 Handoff Requirements.

Phase 3 note: Sprint 6 promotes the first bounded-cluster control-plane integration boundary into the versioned pd start config contract for the reference topology. See Phase 3 Bounded-Cluster Boundary and Phase 3 Bounded-Cluster Posture.

Phase 4 note: Sprint 8 extends that posture into appliance and bounded-federation control-plane requirements for productization packaging. See Phase 4 Appliance Control-Plane Requirements.

Sprint 9 closeout note: the final support-band and control-plane release decision surface is captured in Phase 4 Support-Band Closeout.

Overview

Palladium implements a SeaStar-style architecture where each physical core runs an independent event loop (reactor). This design eliminates contention and the need for shared mutable state across cores, allowing for near-linear scaling on multi-core systems.

Core Architecture

Thread-per-core: One reactor per physical core, pinning schedulers to prevent OS context switching overhead.
Shared-nothing: Communication between cores occurs exclusively via lock-free SPSC queues.
Deterministic Simulation Testing (DST): All I/O, time, and scheduling are abstracted, enabling bit-perfect reproducibility of complex race conditions and failures in a single-threaded simulated environment.
Capability-based Security: Actors interact via typed, unforgeable capability handles (Addr<M>) rather than raw pointers or strings.

Subsystems

pd-actor: The core actor model definition, including the Actor trait and hierarchical addressing system.
pd-runtime: The execution engine, supporting both single-core and multi-core production modes, as well as a simulation mode for testing.
pd-transport: A transport-agnostic messaging layer supporting in-process delivery and remote network protocols.
pd-plugin: A sandboxed plugin system powered by WebAssembly (Wasmtime) and a stable C ABI for native extensions.
pd-federation: Multi-node clustering support with membership management and transparent remote messaging.
pd-cli: A control-plane interface for managing and inspecting running engines.

Key Features

Erlang-style Supervision: Hierarchical supervision trees with "let it crash" semantics and configurable restart intensity limits.
WASM Isolation: Third-party actors can be run in highly isolated WASM environments with fuel metering and memory limits.
High-Performance Messaging: Small Message Optimization (SMO) via a 128-byte envelope format and zero-copy delivery for intra-core messages.
Observability: Integrated structured logging, Prometheus-compatible metrics, and distributed tracing context propagation.

Documentation

For detailed information on how to use Palladium, including core concepts and illustrative examples, please refer to the Documentation Index.