tokitai-operator 0.1.0

# Tokitai Operator

A Rust-based mathematical operator compiler that treats algebraic
laws, valuation, locality, and precision as first-class scheduling
inputs. The crate is an SCI-Q2 paper artifact; see
[`ARCHITECTURE.md`](ARCHITECTURE.md) for the module map and
[`ARTIFACT.md`](ARTIFACT.md) for the reviewer-facing reproduction
guide.

## Quick links (one-liners)

- [`ARCHITECTURE.md`](ARCHITECTURE.md) — module map, the 8-layer
  architecture, and the IR / planner / executor split.
- [`ARTIFACT.md`](ARTIFACT.md) — what the paper claim depends on;
  what counts as a release-gate violation.
- [`CLAIMS.md`](CLAIMS.md) — the 8 `*_claim_allowed` flags. Do not
  edit the flags without a P-number trace entry.
- [`docs/observability.md`](docs/observability.md) — the 3
  observability commands and what to grep for.
- [`docs/operators.md`](docs/operators.md) — the public operator
  surface index.
- [`docs/module_index.md`](docs/module_index.md) — top-level docs
  index (40+ docs grouped into 6 buckets).
- [`examples/book/README.md`](examples/book/README.md) — the
  8-chapter tutorial walkthrough.

## One-command reproduce

To verify the project builds and the tutorial chapter 1 runs:

```bash
cargo run --offline --example book_01_hello_tensor
```

To run the full default test suite (693 tests, ~30s on a laptop):

```bash
cargo test --offline
```

## One-command health check

To run the 8 paper-hygiene and observability checks (P387):

```bash
bash scripts/health_check.sh
```

The script is informational and exits 0 even on a partial
failure; the summary line is `tokitai_health: N of 8 checks
passed, F failed`.

## One-command submission verdict

To see whether the project is submission-ready (P373):

```bash
cargo run --offline --example submission_readiness
```

The verdict is `submission_readiness: YES|NO`. As of the most
recent release, it is `NO` because 7 of 8 claim flags are still
`false` (the 7 require external evidence: P374-P380).

## One-command claim-status report

To see the 8 claim flags and their preconditions (P366):

```bash
cargo run --offline --example claim_status_report
```

The output is greppable: `rg 'claim_allowed=false'` on the output
returns 7 (the 7 blocked flags).

## Repository layout

| Path | What it contains |
|------|------------------|
| `src/` | Library + binaries (8-layer architecture, 33k lines) |
| `tests/` | Integration tests (one file per surface, 135 files) |
| `examples/` | Runnable demos (8-chapter book + 9 standalone) |
| `docs/` | 40+ docs (see `module_index.md`) |
| `docs/paper/` | Paper artifacts (manuscript, submission packet) |
| `scripts/` | Theorem / Lean / paper-artifact checkers |
| `lean/Tokitai/` | Lean proof skeleton (`Ultrametric.lean`, P372) |

## Public API

The only entry point a user needs is `Tokitai`:

```rust
use tokitai_operator::facade::Tokitai;

let cpu = Tokitai::cpu_only();
let out = cpu.graph(|g| {
    let a = g.input_tensor(tensor_a)?;
    let b = g.input_tensor(tensor_b)?;
    g.op(tokitai_operator::op::AddOp, &[a, b])
})?;
```

The facade is the only module the public API exposes directly;
internal types are re-exported only when they are part of the
public surface (`OpSignature`, `LayerBehavior`, etc.).

## Default vs. ROCm/HIP build

The default build is CPU-only and includes every op family, the
full planner, and the full verifier surface. The `--features
rocm-hip` build adds the `hip_*` backends and the 0.7B MoE
training project. Most reviewer checks run under default
features; the ROCm/HIP paths are opt-in and require the local
AMD HIP toolchain.

## License and citation

Apache-2.0 — see [`LICENSE`](LICENSE) and [`CITATION.cff`](CITATION.cff).
For the 7-step contributor process for adding a new op, see
[`CONTRIBUTING.md`](CONTRIBUTING.md).