Engine Track — overview

The Engine Track is clinker-first. The Clinker engine is the textbook, and each Rust concept is introduced exactly where the engine forces it: you learn a piece of Rust because the engine needs it, then read the real source, work through the architectural reasoning, and exercise it in a live checkout.

The shape of the curriculum

A hybrid end-to-end + concentric progression — a shallow pass through the whole engine first, then concentric passes at increasing depth. Full design in the planning corpus under docs/curriculum-planning/.

Phase 0 — Orientation: build & run Clinker, the compiler loop, workspace navigation.
Phase 1 — A Record’s Journey: follow one record end-to-end, shallow.
Phase 2 — Data & Representation: Value, Record, ownership, lifetimes, zero-copy.
Phase 3 — Planning & Expressions: the plan→runtime boundary, traits, error taxonomy, CXL.
Phase 4 — Execution & Memory: enum dispatch, the DAG executor, memory arbitration, spill.
Phase 5 — Extending & Contributing: add an operator / reader / CXL builtin; review; capstones.

The architectural spine is grounded in real, revision-pinned source — for instance the plan→runtime proof boundary, the typed handle the executor accepts instead of raw YAML:

clinker-plan ·compiled.rs ·CompiledPlan type @47d2e12

pub struct CompiledPlan {
    dag: ExecutionPlanDag,        // the lowered execution graph
    config: PipelineConfig,       // the validated configuration
    artifacts: CompileArtifacts,  // typechecked CXL, bound schemas
    // ...
}

Start here

All six phases are written and ready — begin with 0.1 · Build & run Clinker:

Phase 0 · Orientation — build the engine, run a real pipeline, work the compiler loop, navigate the crates, read an execution plan.
Phase 1 · A Record’s Journey — follow one record end to end: what a record is, how YAML becomes a plan, how a record moves through the DAG, and a full traced journey.
Phase 2 · Data & Representation — the first deep pass: the 32-byte Value, exhaustive match, ownership and borrowing, Option/Result, provenance, collections, smart pointers, and the lifetimes behind zero-copy reads.
Phase 3 · Planning & Expressions — up a layer: the two dispatch strategies (trait objects vs generics), the typed proof handles (ValidatedPath, the strict spanned parse, CompiledPlan), the PipelineError taxonomy, and CXL as a staged parse→typecheck→eval language.
Phase 4 · Execution & Memory — the deepest pass: closed-enum node dispatch, one-thread-per-source ingest with bounded channels, buffers that spill, the MemoryArbitrator’s interior mutability, bounded-memory policy, the unsafe FieldStr, and how the engine benchmarks and measures it all.
Phase 5 · Extending & Contributing — turn from reading to contributing: the test strategy that proves a change, then adding a CXL builtin, a reader/writer format, and a DAG operator — followed by the review gauntlet and how to plan a change without breaking an architectural boundary.