curayious Language Lab

Deepening a Track — the Enrichment Pass

A track is done when verify.py prints PASS. The deepening pass is the second stage: the runbook below, run once per track, takes a passing README/NOTES pair to publishable rigor — cited sources, self-derived figures, and prose that asserts rather than performs.

The reference implementation is tracks/10-c. Read its README and NOTES before starting any other track. What follows is the process that produced them; when this document and 10-c disagree, 10-c is right and this document is stale.

Inputs

Read, in order, before touching the track:

1. 00-method.md — the ten questions are fixed. The pass deepens answers; it never reorders, renames, or adds headings.
2. bench/SPEC.md — the program the track answers to.
3. The track's README.md, NOTES.md, and the logagg source itself. The source is the ground truth for every technical claim and every diagram.
4. tracks/10-c/README.md and NOTES.md — the exemplar.

Step 1 — Source pass

Extract every load-bearing claim in the track: numbers, historical assertions, "everyone knows" facts, comparative claims about other languages. Attach a citation to each, from the source pyramid, best first:

1. Primary — the language's spec or standard, the original paper, the RFC.
2. Official — vendor docs, man pages, the project's own site.
3. Canonical artifact — the source file itself (link the repo, pinned to a stable branch), the canonical book.
4. Reputable secondary — named-author engineering blogs (Regehr, Lattner, Boehm), conference talks.

Rules:

• Fetch every link before citing it. Record which resolve. Some good sources gate bots — SQLite's Fossil tree does — in which case link the official mirror (for SQLite, github.com/sqlite/sqlite) and say so.
• Cite paywalled sources where canonical. A DOI behind a paywall is still the right pointer; note it plainly ("paywalled at the DOI; the citation is how you find the mirrored copies").
• Replace hedged numbers with cited numbers. "Roughly two-thirds of CVEs" becomes "about 70% — Chromium's analysis, and Microsoft's same figure" — or the claim comes out.
• Per section: claims cited inline where they live, plus a Further reading: block of three to five whole-topic sources at the end. Citation names the work and the venue, not just a bare URL, so the reference survives link rot.
• Prefer durable URLs: rfc-editor.org, man7.org, open-std.org drafts, docs.* and *.dev official docs, GitHub blob/<default-branch> paths. Avoid URL-shortened or campaign links entirely.

Done when: no number and no named claim in the README lacks a source, and every link in the file has been fetched and seen to resolve.

Step 2 — Figure pass

• SVG figures, drawn with the shared kit. Each track has a fig/ directory: the committed .svg files, and a fig/draw.py that regenerates them from tools/figkit.py. Reference a figure from the Markdown as ![alt text](fig/name.svg "caption"). The alt text describes what the figure shows, for a reader who cannot see it; the caption says what to notice.
• One visual grammar across tracks. Grey boxes are stages, values, or memory regions. The accent fill marks the thing the figure is about, or an owned value. A dashed accent line is a borrow or a boundary that constrains borrows. Dashed red is the version the compiler or the spec rejects. Code identifiers are monospace; notes are muted sans-serif, in a right-hand column. The kit's docstring is the full list. A figure that needs a new mark adds it to the kit, not to one file.
• Why not ASCII any more. Box-drawing characters depend on the font and the line height. On the generated site the vertical strokes broke into dashes, ⋮ shifted the right-hand border, and the right side of every wide diagram scrolled off a phone screen. The SVGs scale with the page, and tools/build_site.py inlines them so they follow the site's light and dark colour tokens. The same files render on GitHub and in Obsidian through their own <style> block. ASCII stays acceptable for program output and compiler errors, which are text.
• 3–6 per track, budgeted where structure is doing the talking: memory layout, data-structure shape, build pipelines, concurrency dataflow, failure states. A build pipeline uses the kit's pipeline() so that every track's Q2 figure has the same shape and can be compared stage by stage.
• Self-derived, not generic. A figure earns its place only if it depicts this program's structure. The 10-c address-space figure places fields[], line.buf and the reason strings where logagg.c puts them; the textbook version with empty segments was decoration.
• Check every figure in the generated page (site/<slug>.html) at desktop width and at phone width, in light and dark mode.

Done when: every figure shows structure the prose cannot carry alone, uses the kit's classes only, and reads correctly in the generated page in both colour schemes.

Step 3 — Per-question upgrade

What "SWE level" means, per question. These are the 10-c patterns generalised — apply the ones that fit the language; a track with no build step does not get a pipeline diagram.

Q	Deepen with
Q1 Origin	The lineage and the constraint that produced it; the standardisation arc (which versions exist and what -std= / edition pins); who pays for it today, named concretely
Q2 Build	What a build is in this toolchain — the pipeline, the unit of compilation, the artifact that ships; the dependency manager reality, including what is absent
Q3 Types/memory	The "what is a variable" answer; the language's own taxonomy of the unspecified (C: implementation-defined / unspecified / undefined — find the equivalent); a layout or ownership diagram derived from logagg
Q4 Abstraction	The unit of abstraction and the idiom that scales it — for C, the vtable struct; name the production-scale pattern, not just the toy
Q5 Errors	The full mechanism list, including the escape hatch the language keeps but discourages; the SPEC 1 ordered-reason tie-in; the cross-track comparison row
Q6 Concurrency	The primitive plus what it costs; the --shard N dataflow diagram; what the language makes easy to get wrong, stated as a mechanism, not a warning
Q7 Idiom	The line-accounting table against sibling tracks; the data-structure diagram; the two or three decisions only this language forced
Q8 Failures	Ranked by professional cost, not tutorial frequency; cited industry figures where they exist; the tooling layer — this language's equivalents of sanitizers, race detector, static analysis, fuzzing — because "how it fails" professionally includes "what catches it"
Q9 Real code	One real file, correctly linked and correctly described (the 10-c draft linked util.c under the label sqlite3.c — check); why this file, plus a shorter alternative
Q10 Transfers	Named, portable ideas — each stated so it could be pasted into another track's Q5/Q6/Q10 verbatim

Done when: every section's technical claims would survive review by a practitioner of that language.

Step 4 — De-slop pass

Hunt this list, in the track's README and anywhere else you touched:

• Superlative assertion: "the single biggest", "the entire motivation for X". State the size or the consequence.
• Stacked "not X — it is Y" antitheses. One per document, where load-bearing.
• Bolded punchline sentences at paragraph end. A true sentence does not need the emphasis.
• Hedged or vague quantity: "essentially all", "roughly", "most". Source the number or cut the claim.
• Inflation adverbs in a row: essentially, actually, genuinely, fundamentally. Each instance must survive a "delete it and re-read" test.
• Rhetorical setups: "That sentence explains nearly everything." State the explanation directly.
• "Which is why" / "it is also why" chains. One per section, maximum.

The test that covers all of it: the claim asserts; it does not perform. Keep the dry, opinionated voice — every track has it — and keep NOTES in lab-log voice. Rigor in NOTES means links and diagrams on the bugs, not polish on the prose.

Done when: the hunt list finds nothing, and the file still sounds like a person who ran the thing.

Step 5 — Verify and ship

1. python tools/build_site.py — regenerates cleanly; check the track's generated page for link rewrites (.md → .html) and diagram alignment.
2. python programming/bench/verify.py — all tracks still PASS. You changed no code; this is a cheap guard against accidents.
3. Spot-check two external links in the generated HTML.
4. git status — commit only the track's README.md/NOTES.md and its generated site/<slug>.html pages. Anything else in the working tree belongs to someone else's change; leave it.
5. Commit message: terse imperative title in the repo's style, then bullets naming what was added, what was corrected, and what was de-slopped.

Done when: the commit contains exactly the track's files and its generated pages, and the working tree's unrelated changes are untouched.

Definition of done

• [ ] Every load-bearing claim cited; every link fetched and resolving
• [ ] 3–6 self-derived SVG figures from fig/draw.py, checked in the rendered page
• [ ] Per-question upgrades applied where they fit
• [ ] De-slop hunt list clean; voice intact
• [ ] build_site.py clean; verify.py PASS
• [ ] Commit scoped to the track's files only

Per-language source starters

The canonical primary sources per track — the pyramid's top two rungs, pre-resolved. Extend as new tracks land.

Track	Primary sources to start from
10-c (done)	Ritchie's HOPL paper; N1570; comp.lang.c FAQ; CERT C; Levine; pthreads(7); RFC 9923
20-java8	JLS (§8 classes, §15.27 lambdas, §17.4 memory model); JSR-133 and JSR-335; OpenJDK source (java.util.ArrayList, ConcurrentHashMap); Java Concurrency in Practice (book)
30-python	Python language reference (datamodel chapter); CPython source (Objects/dictobject.c, Lib/dataclasses.py); PEP 703 (free-threading); docs.python.org glossary for the GIL
40-go	The Go spec; go.dev/ref/mem; Effective Go; the blog classics ("Share Memory by Communicating", "Errors are values", "Defer, Panic, and Recover"); go.dev/doc race-detector page
51-elixir (done)	Valim's design goals; the v1.17 and v1.20 release posts (set-theoretic types); The BEAM Book; HexDocs for GenServer/Supervisor/Task; Discord's scaling write-up; Armstrong's thesis (shared with 50)
50-erlang	erlang.org docs; Armstrong's thesis (Making reliable distributed systems…, free PDF); Learn You Some Erlang
60-cobol	The mainframe-lab repo itself; GnuCOBOL docs; the ANSI standard via summary sources
70-sql	The SQL standard via a draft (e.g. SQL:2016 preliminaries); the database you ran (PostgreSQL docs); Codd's 1970 paper
80-lisp	The HyperSpec (Common Lisp) or R⁷RS (Scheme); SICP; the implementation's own source
12-rust (done)	The book; the Reference; RFC 2094 (NLL), RFC 560 (overflow), RFC 3151 (scoped threads); rustc dev guide; RustBelt (POPL 2018); Rust Atomics and Locks; library/alloc/src/io/read.rs
90-ocaml (done)	A History of OCaml; Leroy, A modular module system (JFP 10(3), 2000); Sivaramakrishnan et al., Retrofitting Effect Handlers onto OCaml (PLDI 2021); the OCaml Manual; stdlib/hashtbl.ml; Real World OCaml

Guardrails

• Depth is not padding. A section with nothing to add stays short. The pass fails if the file got longer without getting more informative.
• Moderate expansion: target ~+40–60% words. Diagrams add lines but few words, so line counts overstate growth — count words.
• One track per run. The pass is written to execute once, cleanly, without context from any previous conversation. If the track isn't PASS yet, the pass does not start — deepen nothing that isn't verified correct.