Capstone C1 — a synthetic extension

This is the first of two graduation capstones. You’ve read the engine end to end and extended each of its seams in guided lessons; C1 asks you to do it unguided, end to end, with tests, against a fixed rubric. It is synthetic on purpose: the seam you target doesn’t move between clinker revisions, so the task is stable and reviewable the same way every time, with no dependency on the live issue backlog (that’s C2).

Prerequisites

• Plan a change without breaking a boundary

→

Leads to

• Capstone C2 — a real contribution

What this proves (graduation outcomes 4–6, 8 + test discipline): that you can add a real extension at the right seam, wire every site the change touches, reason about which ownership/borrowing the seam requires, distinguish what’s validated at planning vs run time, and prove the whole thing with tests at the boundary.

What you’ll be able to do

• Choose a real extension point in the engine and name the seam it plugs into: a CXL builtin’s two-table seam (add a CXL builtin) or a format’s trait + dispatch seam (add a reader/writer format).
• Wire every compiler-mandatory site the change touches, so the exhaustive matches you met earlier compile only once the change is complete.
• Write a test that exercises the new behavior through the public boundary (parse-to-eval for a builtin; read/round-trip for a format), not an internal helper in isolation.
• Distinguish a change that stays inside a seam from one that crosses an architectural boundary (a new dependency, a schema change, a clinker-plan → clinker-exec edge), and name which seam you stayed inside.
• Run the full gauntlet (fmt, both clippy passes, and cargo test --workspace) and read its result as the pass/fail signal it is.

New terms in this lesson (each is also expanded inline at the point you first need it):

• seam: the extension point a C1 change plugs into. Every earlier “add a …” lesson wired one.
• CXL: the engine’s expression language; Track A adds a method to it.
• DLQ: the dead-letter queue, re-tested below from the error-handling lesson.

Predict first

✋ Predict first

You take Track A and add the title_case() builtin: the registry entry in BuiltinRegistry::new() AND the dispatch_method arm. A reviewer runs your test program `emit out = "hello world".title_case()`. Before reading on — predict the printed value. Then predict what changes if you'd added ONLY the registry entry and forgotten the dispatch arm. Write both down first.

Decide on your answer before you open the reveal — committing a guess is what makes it stick.

Reveal the answer

With both halves wired, the program prints Hello World. The registry entry let the typechecker accept title_case() as a no-arg String→String method, and the dispatch arm supplied the runtime behavior. Parse → resolve → typecheck → eval all pass, and the test at the public boundary is green.

With only the registry entry, the program type-checks (the signature table says the method exists) but eval fails at runtime with an “unknown method” error: the dispatch_method arm that actually computes the result was never added. That split is the exact silent failure mode adding a CXL builtin named: a builtin lives in two separate tables keyed by the same string, and the compiler does not force you to update both. The capstone exists to make you wire every site, not just the one that satisfies the typechecker.

A common wrong mental model: “if it compiles, the builtin works.” Not here. The signature half makes it compile; only the eval half makes it run. That gap between compile-clean and behaviorally-correct is precisely what the boundary test catches.

The task: pick one track

Both tracks are real extension points with a clear analogue already in the source to read and copy. Track A is the lower-risk default; Track B is more end-to-end.

Track A (recommended): add a CXL builtin

Add a new scalar string method to CXL: title_case(), which upper-cases the first letter of each whitespace-separated word ("hello world".title_case() → "Hello World"). It is genuinely new (it is not among the 24 existing string methods), so there is no shortcut: you must wire both halves of the two-table seam from adding a CXL builtin.

The signature half is one entry in BuiltinRegistry::new() (no args, String receiver, returns String):

cxl ·builtins.rs ·BuiltinRegistry type @19acdcb4

// in BuiltinRegistry::new(), the String-method array:
s("title_case", vec![], 0, Some(0), TypeTag::String),

The implementation half is one arm in dispatch_method (reuse a string_op helper):

cxl ·builtins_impl.rs ·dispatch_method fn @19acdcb4

"title_case" => Ok(Some(string_op(receiver, span, |s| {
    let cased = s
        .split_whitespace()
        .map(|w| {
            let mut c = w.chars();
            match c.next() {
                Some(first) => first.to_uppercase().collect::<String>() + c.as_str(),
                None => String::new(),
            }
        })
        .collect::<Vec<_>>()
        .join(" ");
    Value::String(cased.into())
}))),

Before you wire it into the two tables, you can verify the algorithm in isolation: the same split_whitespace / upper-case-first-char logic, on a plain String, with no clinker machinery. Run it; confirm it does what the spec says; then port the closure body into the dispatch arm above.

rust // editable

reset ▶ run

// The title_case core, decoupled from CXL's eval machinery.
// Same logic the dispatch arm runs — verify it here, then wire it in.
fn title_case(s: &str) -> String {
  s.split_whitespace()
      .map(|w| {
          let mut c = w.chars();
          match c.next() {
              Some(first) => first.to_uppercase().collect::<String>() + c.as_str(),
              None => String::new(),
          }
      })
      .collect::<Vec<_>>()
      .join(" ")
}

fn main() {
  assert_eq!(title_case("hello world"), "Hello World");
  assert_eq!(title_case("ALREADY caps"), "ALREADY Caps"); // only the first char is forced up
  assert_eq!(title_case(""), "");                          // empty stays empty
  println!("{}", title_case("the synthetic capstone")); // The Synthetic Capstone
}

// The title_case core, decoupled from CXL's eval machinery. // Same logic the dispatch arm runs — verify it here, then wire it in. fn title_case(s: &str) -> String { s.split_whitespace() .map(|w| { let mut c = w.chars(); match c.next() { Some(first) => first.to_uppercase().collect::<String>() + c.as_str(), None => String::new(), } }) .collect::<Vec<_>>() .join(" ") } fn main() { assert_eq!(title_case("hello world"), "Hello World"); assert_eq!(title_case("ALREADY caps"), "ALREADY Caps"); // only the first char is forced up assert_eq!(title_case(""), ""); // empty stays empty println!("{}", title_case("the synthetic capstone")); // The Synthetic Capstone }

The proof is a parse-to-eval test in the style of string_methods, driving a whole program through parse → resolve → typecheck → eval:

cxl ·tests.rs ·string_methods test @19acdcb4

// assert that  emit out = s.title_case()  on "hello world"
// evaluates to Value::String("Hello World")

Track B: add a first-class format

Add a new FormatReader/FormatWriter and wire it through the config enum and the exhaustive dispatch matches (adding a reader/writer format). The two required methods per trait:

clinker-format ·traits.rs ·FormatReader trait @19acdcb4

pub trait FormatReader: Send {
    fn schema(&mut self) -> Result<Arc<Schema>, FormatError>;
    fn next_record(&mut self) -> Result<Option<Record>, FormatError>;
}

Architectural judgment is part of this track

The obvious candidate, a TSV format, is a trap worth thinking through. The CSV reader already accepts a configurable delimiter, and a tab delimiter is even a tested case:

clinker-format ·reader.rs ·test_csv_reader_tab_delimiter test @19acdcb4

#[test]
fn test_csv_reader_tab_delimiter() {
    let config = CsvReaderConfig { delimiter: b'\t', ..Default::default() };
    // ...reads tab-separated rows with the existing CSV reader
}

So a bare tsv alias would be redundant surface, exactly the kind of change planning a change safely says to question before adding. If you take Track B, either (a) choose a format that carries something CSV’s config genuinely cannot express, or (b) if you still add tsv, your design note must justify why a first-class format kind earns its keep over the existing delimiter option. Naming that trade-off is the assessment.

The proof is a round-trip test (read → write → read, assert fields survive), like CSV’s:

clinker-format ·writer.rs ·test_csv_roundtrip_lossless test @19acdcb4

#[test]
fn test_csv_roundtrip_lossless() {
    // read sample -> records, write -> bytes, read again -> assert equal
}

Acceptance criteria

A submission passes when all of these hold, on a branch in your own clinker checkout:

1. Every site is wired. Track A: the registry entry and the dispatch arm. Track B: the trait impl(s), the InputFormat/OutputFormat variant, the format_name arm, and the build_format_reader/build_format_writer dispatch arm. The compiler-mandatory matches do not compile until these exist.
2. Tested at the boundary. A test that exercises the new behavior through the public path (parse-to-eval for a builtin; read/round-trip for a format), not an internal helper in isolation.
3. The gauntlet is green. fmt, both clippy passes, and cargo test --workspace all pass (review & the gauntlet).
4. No boundary is crossed. No new dependency, no schema change, no clinker-plan → clinker-exec edge: the change stays inside the seam (planning a change safely). If you found yourself wanting any of those, that’s a C2/Decision-Gate situation, not C1.

Workflow

Work on a branch in the clinker checkout; clinker stays read-only as a source of truth and your branch is throwaway scratch:

git switch -c capstone/c1-title-case        # or c1-<your-format>
# ...make the change...
cargo test -p cxl --offline string_methods -- --exact   # Track A: your new test
ulimit -n 4096 && cargo test --workspace --locked --offline
cargo fmt --all --check
cargo clippy --workspace --locked --offline -- -D warnings
cargo clippy --workspace --all-targets --locked --offline -- -D warnings

The rubric

Score your own submission (and have a reviewer score it) against this fixed rubric. “Meets” is the graduation bar; “Exceeds” is the stretch.

Dimension	Below	Meets	Exceeds
Correctness	wrong behavior / tests fail	new behavior correct; targeted + workspace tests green	full gauntlet green incl. both clippy passes
Architectural fit	crosses a boundary unknowingly (new dep, schema, layering)	stays inside the seam; every dispatch site wired	names which seam it uses and why no boundary is touched
Tests & verification	no test, or tests an internal helper only	a test at the public boundary (parse-to-eval / round-trip)	adds an edge case or a property/oracle where apt
Review & conventions	ignores conventions	follows naming + test patterns of the existing analogue	a clean one-paragraph design note (what, where, why safe)

// quick check

For Track B you decide to add a `tsv` format. The CSV reader already supports a tab delimiter. What does the rubric expect of you?

• Nothing special — adding the format is automatically correct
• A design note that justifies why a first-class `tsv` kind earns its keep over the existing delimiter option (or a different format that CSV config genuinely can't express) — recognizing redundant surface is the architectural-fit dimension
• You must delete the CSV delimiter option so tsv is the only way to read tabs

Retrieval checkpoint

✓ Capstone C1 — self-assessment gate

💡 Hint 1

Stuck wiring Track A? Re-read adding a CXL builtin: a builtin is two edits keyed by the same string, the BuiltinDef in builtins.rs and the arm in dispatch_method. If eval says “unknown method,” you wrote the signature but not the arm.

💡 Hint 2

For Track B, lean on the analogue: copy the shape of CsvReader/CsvWriter, and let the wildcard-free build_format_reader / build_format_writer matches tell you the dispatch arms you still owe. The compile errors are your checklist.

What a passing submission looks like

Track A: a BuiltinDef entry for title_case in BuiltinRegistry::new() (String, 0 args, returns String), a "title_case" => ... arm in dispatch_method reusing string_op, and a parse-to-eval test asserting "hello world".title_case() is "Hello World". The whole gauntlet is green. The design note reads: “Added a scalar string builtin via the two existing tables (signature + eval arm); no new dependency, no schema change, no crate-layering edge; it lives entirely inside CXL.”

Track B: a FormatReader/FormatWriter impl (often reusing CSV machinery), a new InputFormat/OutputFormat variant, the format_name arm, and the build_format_reader/build_format_writer arms; a round-trip test. The design note confronts the delimiter question head-on, either justifying the new kind or choosing a format CSV config can’t express. Either track: the reviewer can see, from the diff alone, that no boundary was crossed.

// quick check

Spaced recall from the add-a-CXL-builtin lesson. A CXL builtin lives in two separate tables keyed by the same string. You add the BuiltinRegistry entry for title_case() but forget the dispatch_method arm. What happens?

• The crate won't compile — the registry entry forces the dispatch arm to exist
• It compiles and type-checks (the signature table knows the method), but eval fails at runtime with an 'unknown method' error
• Nothing — one table is enough; the second is just documentation

// quick check

Spaced recall from the error-handling lesson. Your new builtin's eval can fail on bad input (say a coercion error on one row). Under strategy: continue with a dlq, what happens to the run?

• The whole run aborts immediately — any eval error is fatal
• The failing record is routed to the dead-letter queue and the run continues; only an Internal-class error always aborts
• The record is silently dropped with no record of why it failed

// quick check

Two reviewers describe your title_case() submission. Which statement is the MISCONCEPTION to correct?

• A unit test on the title_case helper in isolation is weaker proof than a parse-to-eval test, because only the end-to-end test proves the builtin is actually reachable through dispatch
• Because the crate compiles cleanly after I added the registry entry, the builtin is done — a green compile proves the method works
• Adding a brand-new method (not aliasing an existing one) means there's no shortcut: both halves of the two-table seam genuinely have to be written

You should be able to:

• I added a real extension at a real seam (a CXL builtin or a format), not a toy
• Every site the change touches is wired, and the compiler-mandatory matches compile
• There is a test that exercises the new behavior at the public boundary
• fmt + both clippy passes + cargo test --workspace are green
• No new dependency, schema change, or layering violation, and I can name the seam I stayed inside
• I can write a one-paragraph design note: what I added, where, and why it's safe

Verify in the checkout:

cargo test -p cxl --offline string_methods -- --exact
ulimit -n 4096 && cargo test --workspace --locked --offline
cargo fmt --all --check
cargo clippy --workspace --locked --offline -- -D warnings
cargo clippy --workspace --all-targets --locked --offline -- -D warnings

When your synthetic extension is green and reviewed, you’re ready for the real thing: a genuine, potentially-mergeable contribution, scoped and planned the way the project actually works.

Go deeper on the Rust (optional, one-directional: the same concepts your C1 change leans on, taught from first principles in The Rust Book):

• Want the recoverable-vs-fatal split (Track A's eval errors) from first principles? Skip ahead →
• Adding a format on Track B and want traits + dispatch drilled standalone? Read the docs →

Glossary terms used: CXL, recoverable vs fatal, DLQ.

Mark this lesson complete