# Katra3D
**Performance-first native Rust Windows gaming runtime for Linux.**
Katra3D is not a Wine fork, not a Rust transliteration of Wine, not a
vkd3d-proton rewrite, and not another compatibility layer that attempts API
completeness before usefulness. Katra3D has one disciplined objective:
> **Find the smallest set of hot compatibility paths whose native Rust
> reconstruction produces the largest measurable improvement in Windows-game
> performance, latency, frame pacing, loading behavior, CPU efficiency, and
> performance-per-watt on Linux.**
The core hypothesis: *a disproportionately small percentage of the
Wine/Proton/vkd3d execution surface accounts for a disproportionately large
percentage of compatibility-layer overhead.* Katra3D exists to test that
hypothesis with measurement, not belief.
**Behavioral compatibility without architectural inheritance.** Wine,
Proton, vkd3d-proton, DXVK, NTSYNC, Vulkan, and the kernel remain as
fallbacks, behavioral oracles, and differential-testing targets — they are
not architectural templates.
## Repository layout
```text
crates/ — modular runtime crates (no cross-crate FFI chatter)
tools/ — katra-prof, katra-report, katra-replay, katra-bench,
workload-demo (the synthetic baseline workload)
adapters/ — thin C adapters for Wine/Proton/vkd3d/dxvk (libkatra3d ABI)
courts/ — falsifiable test/corpus definitions (storage, graphics, sync,
games, performance, power)
docs/ — architecture, decisions (ADRs), standards, performance,
compatibility
evidence/ — machine-readable benchmark receipts and traces
```
## Status (honest)
| Trace capture | `katra-prof` / `katra-trace` | `native_default` | zero-alloc hot path; <500 ns/event target |
| Report engine | `katra-report` | `native_default` | Pareto, causality, receipts |
| Replay/verify/compare | `katra-replay` | `native_default` | deterministic; causal graphs |
| Semantic graph | `katra-graph` | `native_default` | arena DAG; CPM critical path |
| KatraFlow | `katra-flow` | `shadow` | Modes 0–1 implemented; 2–3 gated |
| Katra I/O | `katra-io` | `native_experimental` | sync pool + io_uring backends |
| Staging arenas | `katra-memory` | `native_experimental` | epoch recycling |
| Sync domain | `katra-sync` | `native_experimental` | fences, events, joins |
| Scheduler | `katra-schedule` | `shadow` | deadline-aware, conservative |
| DirectStorage frontend | `katra-dstorage` | `native_experimental` | CPU path complete; GPU path defined |
| Shader service | `katra-shader` | `observe` | layered cache architecture |
| Layered cache | `katra-cache` | `observe` | content-addressed, atomic |
| D3D12 hot paths | `katra-d3d12` | `fallback` | **all paths fall back to vkd3d-proton until evidence** |
| Vulkan integration | `katra-vulkan` | `observe` | capability model + policy |
| Courts | `katra-courts` | `native_default` | 11 built-in courts, all passing |
| C ABI | `katra-abi` | `native_default` | `libkatra3d`, opaque handles |
Everything in this repository was built in the phased sequence of
`docs/standards/promotion-gates.md`. No subsystem claims a state it has not
earned.
## Quickstart
```sh
cargo build --workspace
cargo test --workspace # includes the full court suite
cargo clippy --workspace --all-targets # must be warning-free
# One command: workload → trace → receipt → courts → replay (§39)
cargo run -p katra-bench -- --out evidence/0001-demo-mixed
# The observatory tools
cargo run -p katra-prof-tool -- self-test
cargo run -p katra-report-tool -- evidence/0001-demo-mixed/run-7-60f-32a.katra
cargo run -p katra-replay-tool -- verify evidence/0001-demo-mixed/run-7-60f-32a.katra
```
See `docs/QUICKSTART.md` for the guided tour.
## First evidence
`evidence/0001-demo-mixed/` contains the first machine-readable receipt,
generated from the deterministic synthetic workload. It proves the full
pipeline (trace → verify → report → replay → courts → receipt) and the
first honest KatraFlow shadow numbers. It is **synthetic**: no number there
is a claim about any real game. Real titles replace it through the same
instrumentation contract (`KATRA_TRACE_OUT` / LD_PRELOAD of `libkatra3d`).
## The Katra3D thesis
> A modern Windows gaming compatibility runtime does not need to replace
> every legacy subsystem to become substantially faster. Preserve mature
> compatibility where it works, reconstruct high-cost paths natively,
> eliminate expensive historical boundaries, and let measurement
> continuously decide what becomes Katra next.
> DirectStorage-capable games provide explicit streaming intent. KatraFlow
> learns equivalent intent for games that do not. Both feed the same
> high-performance Linux-native execution graph.
## License
MIT OR Apache-2.0.