# 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](documentation/PHASE_1_BOUNDARY.md) and
[Phase 1 Closeout](documentation/PHASE_1_CLOSEOUT.md).
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](documentation/PHASE_2_RELEASE_GATES.md) and
[Phase 2 Handoff Requirements](documentation/PHASE_2_HANDOFF_REQUIREMENTS.md).
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](documentation/PHASE_3_BOUNDED_CLUSTER_BOUNDARY.md)
and
[Phase 3 Bounded-Cluster Posture](documentation/PHASE_3_BOUNDED_CLUSTER_POSTURE.md).
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](documentation/PHASE_4_APPLIANCE_CONTROL_PLANE_REQUIREMENTS.md).
Sprint 9 closeout note: the final support-band and control-plane release
decision surface is captured in
[Phase 4 Support-Band Closeout](documentation/PHASE_4_SUPPORT_BAND_CLOSEOUT.md).
## 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](documentation/README.md).
## License
Private and Proprietary. All rights reserved.