katra3d 0.1.0

Katra3D: performance-first native Rust Windows gaming runtime for Linux. Behavioral compatibility without architectural inheritance.
Documentation
# Performance-Per-Watt (Katra3D §29)

Constrained hardware matters. A CPU optimization can produce value without
increasing FPS: less CPU time → more idle → lower power → more thermal
headroom → longer battery life.

## Metrics

```text
J/frame · CPU energy/frame · GPU energy/frame · load energy · performance/W
```

These require power instrumentation (RAPL for CPU; GPU power via driver
counters or external meters) — they are **not fabricated**; receipts report
them only when supplied via `--metrics`.

## How the architecture serves power

* **Fewer wakeups** — batched io_uring submissions, cross-domain joins that
  replace polling with notification;
* **Fewer copies** — buffer ownership handed through completions, staging
  reuse via lifetime-aware arenas;
* **Better residency** — no redundant uploads, conservative RAM budgets on
  unified-memory hardware (§30);
* **Speculative work gated by budget** — KatraFlow prefetch never starves
  foreground work and yields under device pressure;
* **Idle-friendly scheduling** — deadline classes keep background work from
  delaying frame-critical work.

## Hardware-adaptive policy (§30)

| Hardware | Staging strategy |
|---|---|
| Unified-memory APU | shared memory, fewer copies, conservative RAM budgets |
| Discrete GPU + ReBAR/host-visible VRAM | large upload arenas, deep async storage, overlap |
| Discrete GPU without | GPU-side decompression where useful |

Policy is separate from mechanism (§44): capability discovery
(`katra-vulkan::VulkanCaps`) feeds policy, policy feeds budgets, budgets
are enforced by courts and runtime gates.