# Tokitai Examples
A guided index to every standalone example in `examples/`. The 11
book chapters (P391-P403) live under [`book/`](book/) and have
their own [`book/README.md`](book/README.md); this file covers
the 18 standalone examples only.
## When to Read Which Example
- **Just exploring the public API** — start with `public_api`,
then jump to the book.
- **Wanting to see the claim/release surface** — `claim_status_report`,
`submission_readiness`, `fail_closed_audit`.
- **Reproducing a paper artifact** — `paper_benchmarks` (this is
what the paper scripts call).
- **Debugging a real failure** — `dev_failure_recovery` pairs
with book chapter 7.
- **Quick perf sanity check** — `dev_perf_smoke` (not a benchmark;
see `benches/` for stable numbers).
- **End-to-end pipeline walkthrough** — `end_to_end_workflow`.
- **ROCm/HIP** (requires `--features rocm-hip`) — the 7
`rocm_*` examples.
## Public API and Book Index
- `public_api` — the public API surface called by every test
and example; the canonical "this is the supported entry point"
reference.
- `book_index` — prints a 1-line summary of each of the 11 book
chapters; pairs with `book/README.md`.
## Observability and Release
- `claim_status_report` — parses `CLAIMS.md` and prints the 8
`*_claim_allowed` flags; this is what the CI claim-status
check greps.
- `submission_readiness` — prints the 9 artifact checks that
gate `submission_readiness_claim_allowed` (currently NO).
- `fail_closed_audit` — walks the fail-closed guarantee of the
verifier; pairs with `tests/fail_closed_audit.rs`.
- `audit_traces` — dumps the audit-trace format that the
verifier emits alongside the audit report.
- `proof_replay_witnesses` — the 3rd observability command
(P347/P348): prints the witness-type listing and runs
cover-glue inference on a small cover side-by-side. Added
in P440.
## Workflow and Dev Examples
- `end_to_end_workflow` — build → plan → execute → verify, on
a tiny integer graph. Pairs with book chapter 10.
- `dev_failure_recovery` — concrete recovery code for each
`tokitai_operator::Error` variant. Pairs with book chapter 7.
- `dev_perf_smoke` — single-shot perf timings for 5 small ops
(informational; NOT a benchmark and does NOT enable
`production_speedup_claim_allowed`).
- `paper_benchmarks` — regenerates the `target/paper-results/*`
artifacts cited by the paper; called by
`scripts/regenerate_paper_artifacts.sh`.
## ROCm / HIP (require `--features rocm-hip`)
These are gated on the `rocm-hip` feature. On a non-ROCm machine
they appear in `cargo build` as no-op targets.
- `rocm_capabilities` — prints the local ROCm/HIP detection
result (driver, runtime, hardware).
- `rocm_benchmarks` — runs the cross-backend conformance
benchmarks on the local ROCm/HIP device.
- `rocm_dense_pilot` — the dense i32 add/mul/matmul pilot.
- `rocm_padic_valuation` — the ROCm/HIP p-adic valuation-skip
lowering example.
- `rocm_padic_stratified_matmul` — the ROCm/HIP valuation-
stratified p-adic matmul example.
- `rocm_padic_stratified_benchmarks` — the stratified p-adic
benchmark on the local ROCm/HIP device.
- `rocm_sheaf_locality` — the ROCm/HIP sheaf-locality lowering
example.
## How to Run
```bash
# Run any example by its file stem.
cargo run --offline --example claim_status_report
cargo run --offline --example end_to_end_workflow
cargo run --offline --example dev_perf_smoke
# ROCm/HIP examples need the feature flag.
cargo run --offline --features rocm-hip --example rocm_capabilities
```
The book chapter examples are documented in
[`book/README.md`](book/README.md) and run with the same
`--example book_NN_...` pattern.