# Architecture
## What this crate is
`tokitai-dl` is an additive Rust bridge crate that connects
`tokitai-operator` (a deep-learning kernel compiler with selected formal
checks, paper-artifact grade) and `god-graph` (DL model analysis toolbox,
v0.6.0-alpha). It keeps
`tokitai-operator` as a sibling path dependency and consumes a vendored
`god-graph` copy from `vendor/god-graph/`. It exposes translation code that turns a
`tokitai_operator::ir::SemanticGraph` into a
`god_graph::graph::Graph<String, ()>` so god-graph's full algorithm library
(BFS, DFS, topological sort, connected components, MST, PageRank, shortest
path, etc.) can inspect the operator-DAG shape. This bridge does not add a new
formal proof for those graph algorithms or their outputs.
## Position statement
`tokitai-dl` is **vendored, additive**. The public API remains an additive
bridge layer, but the dependency graph is no longer 100% non-invasive:
`god-graph` is checked in under `vendor/god-graph/` and resolved by path in
both manifests. `tokitai-operator` is still not vendored and remains a sibling
path dependency at `../tokitai-operator`.
The original non-invasive position is preserved in
[ADR-0001: non-invasive design](adr/0001-non-invasive-design.md), but that
ADR is **superseded**. The active position is
[ADR-0004: vendor god-graph](adr/0004-vendored-god-graph.md).
## Module map
Source modules under `src/`, with their feature gates as declared in
`src/lib.rs`:
| `lib.rs` | Crate root; defines `BridgeError`. | re-exports gated per child module |
| `op_dag_graph.rs` | `tokitai_operator::ir::SemanticGraph` -> `god_graph::graph::Graph`; pure-DAG metadata. | `operator` (+ `graph` for the `Graph` type) |
| `sheaf_partitioner.rs`| `tokitai_operator::object::sheaf::FiniteSite` partitioning. Ships a local `Partitioner` trait because god-graph's `pub mod parallel` is not yet exposed. | `operator` |
| `witness_bridge.rs` | god-graph `EditOperation` -> traceability `WitnessSample<i64>` with `observed == expected`; not proof of optimizer correctness. | `graph` + `operator` |
| `cad_bridge.rs` | god-graph `TopologyDefect` -> `tokitai_operator::verify::support_matrix::TheorySupportMatrixRow`. | `graph` + `operator` |
| `lean_proof_bridge.rs`| god-graph `TensorRingCompressor` -> synthetic Lean proof-obligation descriptor; only structurally validated here. | `graph` + `operator` |
| `llm_bridge.rs` | god-graph `ModelSwitch` (Safetensors loader) -> `tokitai_operator::backend::TensorStore<i64>` plus lossy-conversion diagnostics. | `llm` + `operator` |
## Feature matrix
Features are declared in `Cargo.toml`. The `mcp` feature is reserved
(defined as empty) for future MCP-server glue and currently pulls in
nothing.
| (none) | Nothing. `cargo build` of this crate alone completes in <1s. |
| `graph` | `god-graph` (default-features = false) with `tensor` and `transformer` re-exported. Brings in `Graph<T,E>`. |
| `operator` | `tokitai-operator` only. Upstream kernels + IR types, no `god-graph` dependency. |
| `graph` + `operator` | Both bridges. Required by the `witness_bridge`, `cad_bridge`, `lean_proof_bridge` modules and examples `01`, `02`, `04`, `05`. |
| `llm` | `graph` plus `god-graph?/safetensors`. Pulls in the Safetensors loader. Use with `operator` for `llm_bridge.rs` and example `03`.|
| `mcp` | Reserved; currently empty. |
Path dependencies (`god-graph`, `tokitai-operator`) are declared
`optional = true`, so each side can be opted out of independently.
`god-graph` resolves from `vendor/god-graph/`; `tokitai-operator` resolves
from `../tokitai-operator` in the default dev manifest. `Cargo.publish.toml`
is a publish-template manifest: it keeps the vendored `god-graph` path and
switches `tokitai-operator` to the crates.io version dependency. See
[ADR-0002: dual-manifest publish](adr/0002-dual-manifest-publish.md) for the
historical dual-manifest rationale and
[PUBLISHING.md](PUBLISHING.md) for the executable staging workflow.
For crates.io consumers, README examples should use the published version
dependency:
```toml
[dependencies]
tokitai-dl = { version = "0.1.2", features = ["graph", "operator"] }
```
The local `path = "../tokitai-dl"` form is only for sibling-checkout
development.
## Build & verification
`scripts/ci.sh` is the source of truth for how this crate is built and
tested. `.github/workflows/ci.yml` invokes it. The CI script exercises
the path-dep `Cargo.toml` (the local dev workflow) and does not run the
publish manifest by design. See
[ADR-0002: dual-manifest publish](adr/0002-dual-manifest-publish.md) for
the rationale.
Examples under `examples/` are gated by `required-features` in
`Cargo.toml`; they only build with the right feature combination turned
on. The repository root `Cargo.toml` has `publish = false`; publishing uses a
temporary staging directory where `Cargo.publish.toml` is copied to
`Cargo.toml` before `cargo package` / `cargo publish` runs.
docs.rs builds the crate uploaded to crates.io, not this sibling checkout. The
default feature set is empty, so a docs.rs default build avoids the `operator`
feature and does not need `../tokitai-operator`. Both source manifests keep the
docs.rs feature set explicit:
```toml
[package.metadata.docs.rs]
no-default-features = true
features = []
targets = ["x86_64-unknown-linux-gnu"]
```
Do not use `all-features = true` on docs.rs unless the staged publish package
has been checked with that exact feature set. In this crate, `operator` and
`llm` are optional integration surfaces and can make docs.rs depend on registry
availability and heavier god-graph features.
## Decision log
- [ADR-0001: non-invasive design](adr/0001-non-invasive-design.md) — the
superseded historical decision. It documents the original 100%
non-invasive design, which ADR-0004 deliberately replaced for
`god-graph`.
- [ADR-0002: dual-manifest publish](adr/0002-dual-manifest-publish.md) —
`Cargo.toml` (`publish = false`, local development) and
`Cargo.publish.toml` (publish template, no `publish = false`) are kept side
by side. Cargo still requires the actual manifest filename to be
`Cargo.toml`, so the publish template is copied into a staging directory
before `cargo package` / `cargo publish`.
- [ADR-0003: local `Partitioner` trait in `sheaf_partitioner`](adr/0003-local-partitioner-trait.md) —
`src/sheaf_partitioner.rs` ships a local `Partitioner` trait and
`FiniteSitePartitioner` newtype because god-graph's `pub mod parallel`
is on disk but not yet exposed; the migration to god-graph's trait is a
near-mechanical replacement once the upstream module becomes public.
- [ADR-0004: vendor god-graph](adr/0004-vendored-god-graph.md) — the active
position. `god-graph` is vendored under `vendor/god-graph/`;
`tokitai-operator` remains a sibling path dependency.
## Known limitations
The bridges ship a few shims where either upstream crate's public surface
is missing the type we need. Each shim has a documented migration path.
See [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md) for the full list
(includes the `parallel/` `pub mod` gap, the missing `TensorStore::len`,
the F32/F64-to-i64 quantisation in `load_model_as_tensor_store`, the
synthetic `EditOperation` in the S1 example, the test-time
Safetensors fixture, and the `tensor`/`transformer` bundling under
`graph`).
## Publish status
The default `Cargo.toml` has `publish = false` and must not be passed
directly to `cargo publish`. `Cargo.publish.toml` is a template, not a
direct Cargo manifest path for publishing: Cargo expects the manifest file to
be named `Cargo.toml`. The executable workflow is to create a temporary
staging directory, copy the repository contents, replace the staging
`Cargo.toml` with `Cargo.publish.toml`, then run `cargo package` /
`cargo publish` from that staging directory. See
[PUBLISHING.md](PUBLISHING.md).