katra3d 0.1.0

Katra3D: performance-first native Rust Windows gaming runtime for Linux. Behavioral compatibility without architectural inheritance.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

# Quickstart — the guided tour

This document walks a skeptical engineer through Katra3D: build, validate,
run the pipeline, and inspect the evidence. Everything here is reproducible.

## 1. Build

```sh
cargo build --workspace
# io_uring backend (optional; the sync backend is the default oracle):
cargo build --workspace --features katra-io/io-uring
```

## 2. Validate

```sh
cargo test --workspace
cargo clippy --workspace --all-targets
cargo fmt --all --check
```

`cargo test` includes the full court suite (11 falsifiable courts) as a
test gate: `katra-courts::tests::all_builtin_courts_pass`.

## 3. The one-command benchmark (§39)

```sh
cargo run -p katra-bench -- --out evidence/0001-demo-mixed \
    --seed 7 --frames 120 --assets 64 --court all
```

This produces, in `evidence/0001-demo-mixed/`:

| File | Contents |
|---|---|
| `run-*.katra` | the correlated event trace |
| `run-*.receipt.json` | machine-readable benchmark receipt (§28/§39 schema) |
| `run-*.md` | human-readable report (Valve-grade presentation) |
| `run-*.courts.json` | court results (falsifiers + evidence) |
| `run-*.replay.json` | replay summary (semantic graph, critical path) |
| `run-*.pak` | the deterministic synthetic asset archive |

The receipt's `not_measured` list is as important as `measured`: Katra3D
never fabricates a value.

## 4. The observatory tools

```sh
# Capture overhead self-test (budget §32):
cargo run -p katra-prof-tool -- self-test

# Inspect a trace header + record counts:
cargo run -p katra-prof-tool -- stats evidence/0001-demo-mixed/run-7-60f-32a.katra

# Verify all trace invariants:
cargo run -p katra-replay-tool -- verify evidence/0001-demo-mixed/run-7-60f-32a.katra

# Replay with the semantic graph + critical path:
cargo run -p katra-replay-tool -- replay evidence/0001-demo-mixed/run-7-60f-32a.katra

# Determinism: run the same seed twice and compare:
cargo run -p katra-replay-tool -- compare \
    evidence/0001-demo-mixed/run-7-60f-32a.katra \
    evidence/0001-demo-mixed/run-7-60f-32a.katra

# Report generation (receipt + markdown):
cargo run -p katra-report-tool -- evidence/0001-demo-mixed/run-7-60f-32a.katra \
    --out /tmp/receipt.json --md /tmp/report.md
```

## 5. The workload

```sh
cargo run -p workload-demo -- --seed 7 --frames 60 --assets 32 --out /tmp/demo.katra
```

`workload-demo` is the honest, deterministic stand-in for "one initial game
workload" (§52). It performs real file I/O through `katra-io`, real gzip
decompression, modeled uploads/barriers/draws/presents, and runs KatraFlow
in shadow mode. It is synthetic by design; the receipt records that fact.

## 6. Profiling a real workload

The instrumentation contract for real games:

1. `KATRA_TRACE_OUT=<path>` — any process whose instrumentation installs the
   Katra profiler writes its trace there.
2. Future: `LD_PRELOAD=libkatra3d.so` for Win32/Proton capture without game
   changes (the boring C ABI in `crates/katra-abi/include/katra3d.h` is the
   boundary; see `docs/ffi-policy.md` and `adapters/`).

```sh
cargo run -p katra-prof-tool -- capture --out /tmp/game.katra --workload proton \
    -- <command-that-runs-the-game>
```

## 7. Where to look next

- `docs/architecture/overview.md` — the architecture
- `docs/architecture/semantic-request-graph.md` — the center of it all
- `docs/standards/promotion-gates.md` — how a subsystem earns its state
- `docs/decisions/` — the decision record (why, not just what)
- `evidence/` — the receipts