Codebase map

This map groups the Cacheon source by authority boundary. File names are links to the current code repository; source remains authoritative when details change.

Read by authority, not import depth

The easiest way to get lost in Cacheon is to follow imports as though every module had the same trust level. Start from the decision whose authority you are trying to understand:

The local branch is useful to contributors but cannot crown anything. The intake, arena, qualification, settlement, and weight branch owns hostile evaluation and economic state. A sealed direct artifact enters qualification through the registered prebuild/runtime boundary; after integration review, its sealed native publication is bound to the reviewed integrated source.

Contribution contract

Area	Primary source
Bundle parsing and path rules	`manifest.py`
Slot ABI and trusted references	`slots.py`
Target identity and composition	`target_catalog.py`
Typed tensor/output boundary	`tensor_spec.py`
Static policy	`sandbox.py`
Tracing-JIT admission	`dsl_jit_policy.py`
Local and distributed verification	`verify.py`, `verify_collective.py`
SGLang dispatch	`dispatch.py`, `seams.py`
Scheduler-role candidate load	`seam.py`, `sglang_scheduler_gate.py`

Sealed direct artifacts

Area	Primary source
Closed provider policy	`artifact_provider.py`
Slot call ABI, resources, and lifecycle	`artifact_abi.py`, `artifact_runtime.py`
Canonical direct-execution identity	`artifact_identity.py`, `artifact_resource_identity.py`
Declarative device launch	`artifact_device_launch.py`
CUBIN ABI and Driver admission	`cuda_cubin.py`, `cuda_launch.py`
Parameter, TMA, and FastDivmod materialization	`cuda_materialize.py`
CuTe compiler boundary and sealed index	`cute_aot.py`, `cute_cubin.py`
Measured compile profile	`eval/native_compile_profile.py`
Registered build patcher	`patchers/build_cute_cubin.py`
Rank-local post-CUDA binding	`integrations/sglang_artifact_context.py`

Intake and referee

Area	Primary source
Chain-facing commands	`cli.py`
Miner S3-compatible publication	`chain/publish.py`
Miner commit-reveal submission	`chain/submit.py`, `chain/payload.py`
Eval-cost quote and payment verify	`chain/eval_cost.py`, `chain/eval_cost_payment.py`
Finalized intake and SQLite state	`chain/intake.py`
Hardened archive fetch	`chain/fetch.py`
Validator loop	`chain/validator_loop.py`
One-shot evaluation-lease operations	`chain/evaluation_lease_operator.py`
Remote worker registration authority	`chain/remote_worker_registration.py`
Durable transport spool schemas	`chain/remote_worker_spool.py`
CPU SSH shuttle and spool transport	`chain/ssh_worker_transport.py`
Pod worker service	`chain/remote_worker_pod_service.py`
Remote transport CLI composition	`chain/remote_worker_service.py`
Standing CPU supervisor daemon	`chain/standing_cpu_supervisor.py`
Screen dispatch config and builder	`chain/mainnet_screen_dispatcher.py`
B300 pod evaluation adapter	`eval/b300_remote_worker_adapter.py`
Redacted chain journal	`chain/audit_log.py`
Private validator snapshot/restore	`chain/archive.py`
Injected arena boundary	`arena_service.py`
Qualification schema and regrading	`eval/qualification.py`
Resident routing screen	`eval/oci_resident_session.py`, `eval/resident_queue.py`, `eval/resident_screen_lane.py`
Adaptive two-lane qualification	`eval/crossover_runtime.py`, `eval/qualification_runner.py`
Standing qualification composition	`eval/b300_qualification_deployment.py`, `eval/b300_registered_qualification.py`
Sealed qualification input authorities	`eval/b300_registered_qualification_inputs.py`
Physical qualification lane pair	`eval/b300_qualification_lanes.py`
Remote qualification evidence products	`chain/remote_qualification_evidence.py`
Remote qualification adapter	`eval/b300_remote_qualification_adapter.py`
Standing resident-pair lifecycle	`eval/resident_evaluation_pair.py`
Bundle and committed-source identity	`bundle_hash.py`
Host audit grading	`audit_gate.py`
OCI lifecycle and protocol	`eval/oci_backend.py`, `eval/oci_session_protocol.py`
Current speed substrates	v7 standing-pair B/C/[B′] in `eval/resident_pair_crossover.py`; v8 two-process B/C/B′ in `eval/crossover_runtime.py` and `eval/oci_outer_session.py`
Immutable native prebuild	`eval/oci_prebuild.py`
Device conditioning/cleanup	`eval/device_state.py`
Compile-profile and multi-architecture prebuild	`eval/native_compile_profile.py`, `eval/oci_prebuild.py`

State, economics, and weights

Area	Primary source
Evaluation/release stack identities	`stack_manifest.py`
Transactional settlement state	`chain/intake.py`
Pure emissions projection	`economics.py`
Weight publication reconciliation	`chain/weights.py`
Reserved V2 durable schema	`chain/reserved_schema.py`
Copy and attribution evidence	`copy_fingerprint.py`

Engine integration

Area	Primary source
Deterministic Engine tree	`engine_tree.py`
Model provisioning	`model_provision.py`

Compatibility

Area	Primary source
SGLang pin and canary	`compat.py`
Bittensor SDK canary	`chain_canary.py`

Follow a concrete task

“Why was this bundle rejected?”

Read in this order:

manifest.py for exact TOML shape and contained-path rules;
sandbox.py and dep_policy.py for observed source/build features;
target_catalog.py for target resolution and admitted features;
artifact_provider.py and artifact_abi.py when the row declares direct exports;
slots.py and tensor_spec.py for callable/output semantics; and
verify.py or verify_collective.py for executable correctness.

This ordering separates syntax, capability admission, ABI, and numerical failure. They are different diagnoses even when the CLI reports them in one run.

“How did a finalized reveal become a crown?”

Start at chain/intake.py, then follow chain/fetch.py and chain/publication.py into chain/validator_loop.py. The loop resolves the closed ArenaServiceRegistry, receives screening and qualification work, persists evidence references, and invokes transactional settlement. Read eval/qualification_runner.py alongside eval/qualification.py: the runner orchestrates work; the schema and regrader define what counts as authority.

The first matching PASS leaves reproduction pending. A second distinct, matching PASS may settle the contribution and advance the evaluation stack. Console output and evaluator summary text are never the settlement input.

“Why did weight publication remain pending?”

Read economics.py first: it computes the pure global projection from reopened active contribution state. Then read chain/weights.py: it refreshes the live metagraph, journals intent before submission, records SDK results without treating them as confirmation, and reconciles later chain observation. The journal stores status/chronology metadata and a projection digest, not raw pre/post readback vectors. --dry-run creates no journal intent, while reconciliation and submission have different durable states.

“What exactly ships?”

Follow stack_manifest.py into engine_tree.py and model_provision.py. The selected payload remains bound to its crowned digest; later materialization owns deterministic module namespaces and packaging. The signed chain-independent release product (release.py, release_runtime.py, release_host.py, release-verify/release-context) was removed on 2026-08-19: no release has ever been produced or consumed, and the subnet does not need it to run.

State and evidence locations

Object	Owner	Identity / persistence rule
Parsed bundle	Contributor/diagnostic process	Content hash over the admitted bundle tree
Finalized publication	Intake controller	Validator-owned immutable worker publication
Qualification evidence	External evidence root plus deployment-owned expected plan/provider context	Typed attempt and referenced artifacts; full regrade additionally requires reconstructed `CausalQualificationInput`, while settlement restart performs narrower byte/PASS authentication
Evaluation stack	Referee state	Canonical manifest that may reference hostile proposals
Settlement and weight state	Chain-scoped SQLite controller	Transactional single-writer state plus projection-linked intent/status journal; live readback vectors are not serialized
Validator recovery snapshot	Private S3-compatible object store	Consistent SQLite image plus database-referenced publications/evidence, redacted journal, and explicit sealed inputs under a closed digest-bound manifest; staged restore never replaces live state
Integrated source	Reviewed source control	Full reviewed commit plus selected-payload and attribution digests

Paths are deliberately not identities. A local directory name, URL, database row number, or registry tag cannot replace the corresponding digest-bound object.

Tests as executable maps

Tests mirror the authority boundaries rather than one monolithic integration fixture:

test_static.py and test_target_catalog.py cover hostile input and target admission;
test_artifact_abi.py, test_artifact_device_launch.py, test_artifact_runtime.py, test_cuda_cubin.py, test_cuda_materialize.py, and test_cute_cubin.py cover the sealed direct-artifact boundary;
test_stack_manifest.py, stack-planning tests, and test_engine_tree.py cover canonical composition and integration materialization;
qualification, OCI, audit, and reference-protocol tests cover current v7 resident B/C/[B′], v8 two-process B/C/B′, registered eager audit A, and pristine T, while historical-policy tests preserve older witness shapes;
chain-intake, settlement, economics, and weight-publication tests cover durable economic transitions;
test_chain_publish.py and test_chain_archive.py cover public proposal transport and private digest-bound recovery respectively; and
release, runtime, registry, and host tests cover the signed serving boundary.

When learning a type, search for both its successful construction and its rejection tests. The negative cases usually reveal which fields are security inputs rather than descriptive metadata.

Production authority entry points

Development helpers and test fixtures are not alternate qualification authorities. Audit production intake from the validator loop and durable intake store, then follow the registered arena, qualification runner, settlement transition, and weight-publication journal. A path that does not emit and reopen the typed products for those boundaries cannot substitute for them.

Tests are organized under tests/ by the same boundaries. Contract tests are often the clearest executable examples because they build exact typed objects and assert fail-closed behavior.

On this page