feat(analysis): settle what peak-footprint claims, and make the claim true

[zhen8838]

Why

analyze reports # peak-footprint=<level>:<bytes> and refuses a program whose
peak exceeds the capacity a target states (src/tilefoundry/analysis/memory.py:391-395).
The name says "peak", but what is computed is the sum of the bytes live at the worst
point of the program (memory.py:363-380) — a lower bound on what an allocator
would need, because it accounts for neither placement nor fragmentation.

Nothing in this repository allocates buffers: grep -rn 'lifetime\|liveness\|reuse\|binpack' src/tilefoundry/codegen/
returns nothing, and codegen/cuda/tir/memory/alloc_tensor.py emits a declaration.
So the number is a self-standing estimate that no later stage is obliged to meet.

That is sound in one direction and silent in the other:

• A refusal is trustworthy. If even the optimistic sum exceeds capacity, the program
  cannot fit, whatever the allocator does. No false refusals come from fragmentation.
• An acceptance is not. A program that fits only under a packing nobody performs is
  accepted, and a program whose fragmentation pushes it over capacity is accepted too.

What

Decide what peak-footprint claims, and make the claim true.

Either:

• Keep the lower bound and say so. Rename the reported quantity and the refusal
  so a reader knows it is a necessary, not a sufficient, condition, and state in
  docs/spec/cli.md that acceptance means "not provably too large".
• Make it the allocated peak. Assign every buffer a lifetime, solve the packing
  (a CP-SAT bin-pack, as buffer schedulers such as nncase's do), and report the
  peak that solution reaches. This is only meaningful if codegen then allocates
  under the same policy: an allocated peak that codegen does not follow is a second
  account of the same quantity, and the two will disagree.

Contract

docs/spec/cli.md currently states neither what the number means nor which of the
two readings the refusal carries. Whichever way this is settled, that section is the
place it gets written down.

Risk

The second option is the larger one and it does not stand alone: it needs a codegen
allocation contract to be worth reporting. Filing this separately from the
lifetime-accounting fix below, which is a bug under the current reading and is being
fixed on its own.

Related: the lifetimes feeding today's number are built on a flattened value list
(memory.py:250-276, fed by memory.py:307) that carries no loop nesting, so a
loop-carried value's residency is under-counted. That is a defect under either
reading and is being fixed separately.

[zhen8838]

A neighbouring clause is already unimplemented, and it prescribes half of the answer.

docs/spec/analysis.md:574-577:

One value exceeding an explicit level's capacity MUST raise AnalysisError. An aggregate explicit peak or an authored-loop access footprint exceeding an implicit cache capacity MUST instead produce an advisory and MUST NOT fail the call.

The first sentence is now honoured again. The second is not: grep -rn "advisory" src/tilefoundry/analysis/ returns nothing, so there is no advisory mechanism for an aggregate peak to be reported through. A program whose simultaneously-live set does not fit is therefore silent today — neither refused nor flagged.

Measured example: Stage2_Sharded in docs/tutorial/authoring.ipynb at ctx_len=1816 reports peak-footprint=…,smem:472160 against a stated per-CTA capacity of 232448 B, and is answered without comment.

So whichever way this issue is settled, the aggregate case has a stated destination already: an advisory, not a failure. What is missing is the mechanism to carry one.

[zhen8838]

Measured what a scope-aware peak buys, since PR #147 briefly carried one and then took it back out.

_lifetimes builds every lifetime on one flat value sequence: MemoryVisitor appends each Call and Constant into a single list, and visit_GridRegionExpr hands a loop body its parent list, so the nesting the Scope tree already records never reaches the peak computation. Composing the peak over that tree instead — a scope on top of what its enclosing scopes hold at the point it occupies, a loop counted once — changes two of the six programs in docs/tutorial/authoring.ipynb, by 136 B each:

                        flat            over the scope tree
Stage0_Naive            gmem:10945036   same
Stage2_Sharded          gmem:10945036   same
Stage3_Fused            smem:33408      smem:33544   +136
Stage4_WeightPrepared   smem:16960      same
Stage5_CachePrepared    smem:33536      smem:33672   +136

Both +136 are acc 128 + m 4 + l 4: the three loop-carried values of the online softmax. They are defined in the enclosing scope and read by the loop body, so on a sequence with no nesting their interval ends before the loop begins and their residency during it is not counted.

So the flat accounting under-reports, and the correction is real but small here — 0.4% on a 33 KB footprint against a 232448 B capacity, nowhere near changing what the refusal decides. That is why it was pulled out of that PR rather than shipped inside a fix(cli) change: it belongs with whatever this issue settles about what the number claims, and it wants a title of its own.

The implementation that produced the right column is recoverable from PR #147's history (the _Residency / _read_below / _rows / _residency / _peak shape). Whoever takes this issue should not need to rediscover it.