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

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)

Subsystem	Crate	Promotion state	Notes
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

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.