Add an end-to-end walkthrough of mutability, from CHL source to operators - #97
Open
dpmills wants to merge 2 commits into
Open
Add an end-to-end walkthrough of mutability, from CHL source to operators#97dpmills wants to merge 2 commits into
dpmills wants to merge 2 commits into
Conversation
Contributor
Author
|
This change is part of the following stack: Change managed by git-spice. |
This was referenced Aug 13, 2026
dpmills
force-pushed
the
dmills/mutability-walkthrough
branch
from
August 13, 2026 22:42
4c9e9d8 to
5b74039
Compare
dpmills
force-pushed
the
dmills/mutability-walkthrough
branch
from
August 13, 2026 23:42
5b74039 to
8b39439
Compare
dpmills
force-pushed
the
dmills/mutability-walkthrough
branch
from
August 14, 2026 19:49
8b39439 to
92e4a8a
Compare
dpmills
force-pushed
the
dmills/mutability-walkthrough
branch
from
August 14, 2026 21:34
92e4a8a to
bec98c8
Compare
dpmills
force-pushed
the
dmills/mutability-walkthrough
branch
2 times, most recently
from
August 15, 2026 00:59
ee1ecdc to
2f083d7
Compare
dpmills
force-pushed
the
dmills/mutability-walkthrough
branch
4 times, most recently
from
August 15, 2026 03:50
2b0125a to
f7fb851
Compare
dpmills
force-pushed
the
dmills/mutability-walkthrough
branch
5 times, most recently
from
August 17, 2026 18:24
c9efd6e to
592f045
Compare
dpmills
force-pushed
the
dmills/mutability-walkthrough
branch
3 times, most recently
from
August 17, 2026 19:35
1233639 to
adcc7cf
Compare
dpmills
force-pushed
the
dmills/mutability-walkthrough
branch
from
August 17, 2026 23:42
adcc7cf to
b3d0c7a
Compare
dpmills
force-pushed
the
dmills/mutability-walkthrough
branch
2 times, most recently
from
August 19, 2026 17:38
a4bbc6c to
31ee2a4
Compare
dpmills
force-pushed
the
dmills/mutability-walkthrough
branch
from
August 19, 2026 18:15
31ee2a4 to
1948608
Compare
dpmills
changed the base branch from
dmills/tile-only-writer-input
to
dmills/mutability-vocab-cleanup
August 19, 2026 18:15
dpmills
force-pushed
the
dmills/mutability-walkthrough
branch
from
August 19, 2026 18:34
1948608 to
f794a3c
Compare
dpmills
force-pushed
the
dmills/mutability-walkthrough
branch
from
August 19, 2026 18:46
f794a3c to
0870580
Compare
dpmills
force-pushed
the
dmills/mutability-walkthrough
branch
from
August 19, 2026 18:54
0870580 to
584b1e0
Compare
dpmills
marked this pull request as ready for review
August 20, 2026 00:45
dpmills
force-pushed
the
dmills/mutability-walkthrough
branch
from
August 20, 2026 18:39
584b1e0 to
37c12a4
Compare
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
force-pushed
the
dmills/mutability-walkthrough
branch
from
August 20, 2026 18:47
37c12a4 to
098a561
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Mutability is the one part of Cambra with no path through it.
src/ccl/design/mutability.mdand 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,
Mutas a type, the pipeline phase by phase, two worked examples, the engines, and the edges.Reviewing it
The stage listings are real
RUST_LOG=debugoutput, 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 (6and35) now thatawait_finalcompiles 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
FanOutrather than walking back into the store it wraps. They describe the drive/store split asInductionDriveandTransactDriveimplement 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 asUnbound variable, a diagnostic gap now stated as one; lowering makes one classification choice, not two, and the loop is where it decides nothing; andtransact_phasewas missing from the pipeline block.type-inference.mdgets a matching one: its "three sites" that contribute to a variable's value type are three rules, and the third — aTransactkey's seed — is the same rule shape one variable over, not a third input to the same join.