fix(cli): make the release surface and its tutorial pages executable - #147
Merged
Conversation
Footprint took the whole tensor's bytes and divided by the topology's unit count, while traffic asked the local projection what one unit holds; the two disagreed in the same report by the ratio between a value's shard factor and that count. Both now read `local_type_of`, and the divisor is gone. Lifetimes were built on one flat sequence because `replace` handed a loop body its parent's list, so the nesting the Scope tree already records never reached the peak. Values are now collected per scope and the peak is composed over that tree: a scope's own worst point on top of what the enclosing scopes hold where it sits, sequential scopes taking the greater rather than the sum, and a loop counted once rather than once per trip. Refusal returns to one value against its level's capacity, which is what `docs/spec/analysis.md` states; the working-set sum refuses programs a shared budget accepts.
The renderer had its own extraction of the programs a page teaches, and the page carried a second one in a markdown cell that never ran. Nothing proved the two produced the same bytes, and the filename was typed in three places that derived from nothing. The page's first block is now the extraction command and the renderer executes it: rendering happens in two passes, the first laying the page down with no outputs where that command can read it, and prose and code blocks are byte-identical across both. A source block's tag carries the file it belongs to, so one notebook can write several and a later block can overwrite an earlier one's. The renderer walks `docs/tutorial/*.ipynb`, so a new page needs no edit here. The guard is `test_a_reader_reproduces_the_page_from_the_page`: it does what the page tells a reader to do, in an installation with no checkout to import, and requires every block's output to be exactly what the page shows, in place. It replaces an assertion that read the page for a string it never ran.
The two workflow pages were never executed. A reader following `optimize` hit
five errors in a row, and `migrate` spliced a declaration out of a shipped model
through a template mechanism only that one page used. Neither page ever ran
`check`, which is the product's central claim.
Both are notebooks now, rendered by executing their own blocks: one example
carried across them -- RMS-normalize a row, take a blockwise absolute maximum,
quantize to fp8. `migrate` builds the published side from the real
`transformers` class with the epsilon, block width and format the model's own
`config.json` states, authors the step with the scaling on the wrong side of the
bf16 landing, and shows `check` refusing it; a second extraction block writes the
one-line fix over the same file and the same command passes. `optimize` prices
the same step with a `@func` boundary in the middle and without, then checks a
runtime twin against the authored program.
`index` is one figure and three sentences. The `{{fixture:}}` mechanism has no
page left to serve and goes, with the assertions that watched it.
`--source` said where a checkout's file list came from by appending it to the
directory line, so standard output's first line stopped being a path. One line
cannot serve a reader and a caller at once: `sed -n '1p'` took the note along
with the path, and `awk 'NR==1 {print $1}'` breaks the moment the path has a
space in it.
The note moves to standard error, unchanged in condition: a checkout says it, an
installation says nothing. Standard output is now a path and one line per file in
either world, so reading the first line as a path is correct again and the
specification promises that rather than a field layout.
The extraction block took the first whitespace-separated field to get past a note that is no longer there, and a path with a space in it would have broken that. `sed -n '1p'` is the honest reading now, with standard error dropped because a checkout says on it where its file list came from and an installation says nothing: leaving it captured would put a line in the page that only one of the two worlds produces.
The optimize page taught making a step fast and then showed a twin written in torch, which is a second reference rather than a fast implementation. It is one Triton kernel now, a row per program with the whole step fused into it, and it holds bit-exactly: `equal` on the fp8 output reports 0 of 14336 mismatched, so the row reduction lands on the same values the interpreter does. `step` said nothing, so the kernel is `rms_norm_quant` across both pages, in the file name, the module entry and the `@func`. The `@func`s gain the outer `cta` mesh every other placed program in the tree has; it changes no measured number. The index lists the pages it has and nothing else -- pointing at `spec` and `check --help` is the tutorial's obligation, and the pages that teach a step are where it lands, so that assertion moves onto them. The annotation-marker lint now covers `docs/tutorial/` as well, with the interface-block rules left to specification pages: a tutorial fence is a program that runs, where a decorator and a module docstring are correct.
Two independent defects were fixed in one rewrite. The first is the one that mattered: footprint took the whole tensor's bytes and divided by the topology's unit count while traffic asked the local projection what one unit holds, so the same report disagreed with itself by a value's shard factor, and a program that does not fit was answered instead of refused. That fix is twelve lines, and it stays. The second built the lifetimes over the Scope tree so a loop's carried values stay resident across it. It is correct — a flat sequence ends their intervals before the loop begins — but it is about a hundred and fifty lines and it moves two numbers in six programs, by 136 B each: `acc` plus `m` plus `l`, the online softmax's carried state. Nothing downstream turns on 136 B against a 232 KB capacity, and a change that size deserves its own title rather than a paragraph in a release-surface change. It goes to the issue that owns what a peak claims, where the measurement and the shape of the implementation are recorded. So the lifetimes are flat again, the specification's three rows say so, and the two stages with a loop report the smaller peak.
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
1 participant
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.
Why
until they could not run.
authoring.mdhas been unrenderable since feat(parser): make authored expression gates work and show themselves #124: adisplay cell searched the report for
"matmul(hidden, w_q)", feat(parser): make authored expression gates work and show themselves #124 gavematmulan
a_layout/b_layoutannotation, andnext()raisedStopIteration. refactor(analysis): unify analysis structure and fix cross-scope and symbolic-offset analysis #126stacked two more: five
# advisory=lines the code no longer emits and a movedgmempeak.optimize.mdwas broken too.What
_Parserare gone, so--helpis argparse's and the introduction has one copy;
--versionis added, usage errorsprint usage before the error, and
models --sourceprints a path on stdout withthe provenance on stderr. An unknown document name is refused the same way at
every kind.
memorymeasured residency twice and disagreed with itself bythe ratio between a value's own shard factor and the topology's declared unit
count, so a program that does not fit was answered rather than refused. It now
reads the same
local_type_ofprojection traffic reads, and refusal is per valueagain. What a peak should claim across a loop is issue feat(analysis): settle what peak-footprint claims, and make the claim true #146.
the first being the extraction command.
migrateandoptimizeare new and shareone example;
migrateshowscheckrefusing an authored step, then passing aftera one-line fix -- the same command both times.
indexis one figure and{{fixture:}}goes. One installed test does what a page tells a reader to do andrequires each block's output to be the page's own.
Deliveredsections must state their change as a diff.Contract
docs/spec/cli.md: naming no command prints that level's--helpbyte for byte,exit 0; a usage error prints usage before the error;
--versionand the projectsummary come from distribution metadata;
--source's first line MUST be the pathalone with provenance on stderr; an unknown document name is refused uniformly
across kinds; a page with programs MUST open with its extraction command and a
rendered page MUST equal executing its own blocks; the page list gains
authoring.docs/spec/analysis.mdis unchanged, because bothanalysischanges arerestorations, not new behaviour: the specification already required that one
value exceeding a level's capacity raise
AnalysisError, and thatValueLifetime.bytesproject the Type through the splits at or coarser than thelevel's
owner. refactor(analysis): unify analysis structure and fix cross-scope and symbolic-offset analysis #126 changed the code, not the spec.Risk
peak-footprintclaims: the largest sum of simultaneouslylive bytes, a lower bound on an allocation peak. Nothing allocates a buffer, so
the real peak needs a codegen allocation contract.
analysis.md:575-577alsorequires an advisory when an aggregate peak exceeds an implicit cache capacity;
analysis/has none.pass.
Stage2_Shardedatctx_len=1816is that case; a test pins the cost.