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

# Benchmark Format: the receipt (Katra3D §28, §39)

`katra-bench` produces a machine-readable receipt (JSON) and a
human-readable report (Markdown). The schema version is 1.

## Schema

```json
{
  "schema_version": 1,
  "workload": "demo:seed=7",
  "trace":    { "path", "event_count", "duration_ns", "overhead_ns", "dropped" },
  "system":   { "os", "kernel", "cpu_model", "cpu_cores", "ram_bytes",
                "gpu_vendor", "gpu_model", "driver" },
  "correctness": { "verdict": "pass|fail|not_measured", "detail" },
  "performance": { "avg_fps", "p1_low_fps", "p01_low_fps",
                   "p99_frame_time_ms", "p999_frame_time_ms",
                   "load_time_ms", "frame_count" },
  "cpu":      { "compat_cpu_us_per_frame", "storage_cpu_us_per_gib" },
  "memory":   { "bytes_copied", "allocations", "peak_staging" },
  "gpu":      { "queue_idle_pct", "submission_count", "pipeline_creations" },
  "storage":  { "iops", "queue_depth", "prefetch_accuracy_pct",
                "unused_prefetch_bytes", "latency_avoided_ns" },
  "power":    { "energy_j_per_frame", "perf_per_watt" },
  "coverage": { "katra_native_pct", "legacy_fallback_pct",
                "subsystems": [ { "subsystem", "state", "native", "fallback" } ] },
  "pareto_by_cost":      [ { "scope", "kind", "count", "total_ns", "avg_ns",
                             "p50_ns", "p95_ns", "p99_ns", "pct_of_total" } ],
  "pareto_by_frequency": [ ... ],
  "causality":   [ { "request_id", "root_kind",
                     "links": [ { "kind", "phase", "latency_ns", "cumulative_ns" } ],
                     "total_ns" } ],
  "critical_paths": [ { "epoch", "weight_ns",
                        "nodes": [ [kind, weight_ns, cumulative_ns] ] } ],
  "spans": { "span_count", "unmatched_begins", "unmatched_ends",
             "total_ns", "p50_ns", "p95_ns", "p99_ns" },
  "epochs": [ { "label", "ts_mono_ns", "ts_wall_ns" } ],
  "falsifiers": [ "..." ],
  "provenance": { "tool_version", "command", "created_wall_ns", "notes" },
  "measured":     ["metric names actually measured"],
  "not_measured": ["metric names explicitly null"]
}
```

## Honesty rules

* Every unmeasured value is `null` and listed in `not_measured`. **Never
  fabricated.**
* `compat_cpu_us_per_frame`, `energy_j_per_frame`, `perf_per_watt`, and GPU
  idle require external instrumentation (power hardware, GPU counters) —
  supplied via `--metrics <json>`; the receipt then records them as
  measured with their source.
* Percentages are always accompanied by raw values in the markdown table.
* Frame statistics come from Present intervals only; a run without presents
  reports `avg_fps: null`.

## What the trace itself measures

| Metric | Derivation |
|---|---|
| avg/p1/p01 FPS, p99/p999 frame time | Present-event intervals |
| load time | `loading_begin` → `loading_end` epoch markers |
| IOPS | IoRead count / session duration |
| queue depth | backend max queue depth |
| prefetch accuracy | `flow.matched` / `flow.predictions` counters |
| unused prefetch bytes, latency avoided | `flow.unused_bytes`, `flow.potential_saved_ns` |
| storage CPU/GiB | Σ IoRead latency / Σ bytes |
| bytes copied, allocations, peak staging | memory counters |
| submissions, pipeline creations | queue-submit / pipeline-create events |
| coverage | `KatraSubsystemState` events |

## Falsifiers

Every receipt carries statements that would falsify its claims (§25). If a
falsifier fires in a later run, that run fails and the evidence is kept.