Skip to content

Add an end-to-end walkthrough of mutability, from CHL source to operators - #97

Open
dpmills wants to merge 2 commits into
dmills/mutability-vocab-cleanupfrom
dmills/mutability-walkthrough
Open

Add an end-to-end walkthrough of mutability, from CHL source to operators#97
dpmills wants to merge 2 commits into
dmills/mutability-vocab-cleanupfrom
dmills/mutability-walkthrough

Conversation

@dpmills

@dpmills dpmills commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

Mutability is the one part of Cambra with no path through it. src/ccl/design/mutability.md and the spec are organised by mechanism and answer questions you already know to ask; someone working on the system who does not know the induction/transaction layer deeply has nowhere to start. This adds docs/mutability-walkthrough.md — a conceptual tour that follows two programs from CHL source to operators, keeping the design docs as the authority and linking out rather than restating.

Written for the reader who knows Cambra but not this layer: the model (a mutable variable is a function from a sequencing domain to a value), why induction and transactions are asymmetric, what a programmer writes, Mut as a type, the pipeline phase by phase, two worked examples, the engines, and the edges.

Reviewing it

The stage listings are real RUST_LOG=debug output, regenerated against this branch's tip rather than written by hand — so read them for drift from the compiler, not for prose. If they are stale, the fix is to re-run the program, and the two programs are in the doc verbatim. Both still answer as the doc says (6 and 35) now that await_final compiles to a sample of the key's carried value rather than a reduction of its history, and the listings carry that shape: pool ▷ final_read, no seed operand.

§8's operator diagrams are the exception and the part most likely to be wrong: they are hand-drawn, because the graph renderer stops at a cyclic FanOut rather than walking back into the store it wraps. They describe the drive/store split as InductionDrive and TransactDrive implement it.

The design-doc fixes it carries

Writing the tour surfaced four defects in src/ccl/design/mutability.md, fixed here rather than left for later: a variable's domain comes from the context that writes it, not from where it is introduced; the block-introduction case has no gate of its own and is rejected as Unbound variable, a diagnostic gap now stated as one; lowering makes one classification choice, not two, and the loop is where it decides nothing; and transact_phase was missing from the pipeline block. type-inference.md gets a matching one: its "three sites" that contribute to a variable's value type are three rules, and the third — a Transact key's seed — is the same rule shape one variable over, not a third input to the same join.

@dpmills

dpmills commented Aug 13, 2026

Copy link
Copy Markdown
Contributor Author

@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch from 4c9e9d8 to 5b74039 Compare August 13, 2026 22:42
@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch from 5b74039 to 8b39439 Compare August 13, 2026 23:42
@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch from 8b39439 to 92e4a8a Compare August 14, 2026 19:49
@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch from 92e4a8a to bec98c8 Compare August 14, 2026 21:34
@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch 2 times, most recently from ee1ecdc to 2f083d7 Compare August 15, 2026 00:59
@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch 4 times, most recently from 2b0125a to f7fb851 Compare August 15, 2026 03:50
@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch 5 times, most recently from c9efd6e to 592f045 Compare August 17, 2026 18:24
@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch 3 times, most recently from 1233639 to adcc7cf Compare August 17, 2026 19:35
@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch from adcc7cf to b3d0c7a Compare August 17, 2026 23:42
@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch 2 times, most recently from a4bbc6c to 31ee2a4 Compare August 19, 2026 17:38
@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch from 31ee2a4 to 1948608 Compare August 19, 2026 18:15
@dpmills
dpmills changed the base branch from dmills/tile-only-writer-input to dmills/mutability-vocab-cleanup August 19, 2026 18:15
@dpmills dpmills changed the title A walkthrough of mutability, end to end Add an end-to-end walkthrough of mutability, from CHL source to operators Aug 19, 2026
@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch from 1948608 to f794a3c Compare August 19, 2026 18:34
@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch from f794a3c to 0870580 Compare August 19, 2026 18:46
@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch from 0870580 to 584b1e0 Compare August 19, 2026 18:54
@dpmills
dpmills marked this pull request as ready for review August 20, 2026 00:45
@dpmills
dpmills requested a review from a team as a code owner August 20, 2026 00:45
@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch from 584b1e0 to 37c12a4 Compare August 20, 2026 18:39
The rewrite of that bullet reintroduced the word the vocabulary retirement had
just taken out: `A register with a single contribution therefore keeps its
refinement`. The sentence names the same thing the two before it call a mutable
variable.
@dpmills
dpmills force-pushed the dmills/mutability-walkthrough branch from 37c12a4 to 098a561 Compare August 20, 2026 18:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant