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.

crates.io

The whole workspace is published to crates.io. The umbrella crate katra3d re-exports every Katra library crate — one dependency, the whole runtime:

[dependencies]
katra3d = "0.1"

use katra3d::prelude::*;                 // core vocabulary + common types
let g = katra3d::graph::Graph::new();    // namespaced modules

All 24 crates (katra3d, katra-core, katra-graph, katra-prof, katra-trace, katra-report, katra-replay, katra-flow, katra-io, katra-memory, katra-sync, katra-schedule, katra-dstorage, katra-d3d12, katra-vulkan, katra-shader, katra-cache, katra-courts, katra-abi, the five CLI tools, and workload-demo) are published at 0.1.0, each with its own description, keywords, categories, and license. Docs: https://docs.rs/katra3d.

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.