FT-070 memory: a source range names its document by index (Cluster 88 -> 56 B, -105 MiB at 2 MB)

[GoKubar]

FT-070 follow-up 2 of the three #232 ranked. Independent of #283 (follow-up 1):
both branch from the same base, and either can land first.

Based on #232's branch (41fee414) with current main merged in — #232 is
not on main yet, and neither is #206's harness, which #232's branch carries.
Every number here is against a control run at that same base.

What it does

SourceRange carried path: Rc<str> — a 16-byte fat pointer, per cluster, to
one of a handful of strings. A 2 MB document has 1.5 M clusters, so the pointers
cost far more than the paths they point at, and a cluster is the structure that
dominates per-glyph memory.

The index already existed. Span::document is the compiler's index into the
request's document list, and the display list's documents array is that same
list in that same order — source_of was resolving that index to a string once
per glyph. A range now carries the index instead:

SourceRange { document: DocId(u32), start_byte: u32, end_byte: u32 }

12 bytes, and Copy. The paths live in one DocumentPaths table per display
list, shared by every page behind an Rc. The wire format is unchanged: the
serialisers resolve through the table, so the JSON still carries paths, and the
delta digest still hashes the path string rather than the index.

Two smaller changes fall out, and they are what take a cluster below 64 bytes:

• Provenance's rare arms are boxed behind thin pointers
  (Sources(Box<Vec<..>>), Synthetic(Box<String>)). Both are rare — one is
  reserved and unused — and inline they widened every cluster to carry a
  Vec/String header.
• Cluster's text_start_byte/text_end_byte are u32. They index the
  run's text, which is one word at most.

	before	after
SourceRange	32	12
Provenance	40	16
Cluster	88	56
Item	200	184

56, not the 64 this was ranked at — boxing the rare arms lets Provenance
pack to 16 rather than 24.

The index has to survive a reordered document list

This is the part worth reviewing. It is a per-request index, not a global
identity, and the incremental cache outlives a request: a cached block's ranges
name documents as the request that built it listed them, and a later request
may list the same documents in a different order. A path string was
self-describing; an index is not. So placement remaps it.

Relocate { from: DocId, to: DocId, delta: isize }

Ranges in from become ranges in to with offsets shifted by delta; ranges
in any other document are untouched. AssembledBlock records the DocId it was
assembled against, so from is known. This is the old "shift the offsets of
ranges whose path matches" rule restated in indices, plus the remap the string
form did not need.

Both relocation sites take it — place_item when a cached block's line is
placed, relocate_block when a cached block is reused. Both used to return
early on delta == 0; they now return early only when the relocation is a
no-op in both halves, because the document index can move while the byte
offsets do not. That early return is the one place this could have gone quietly
wrong.

delta.rs compares a base page against a new one across two display lists whose
tables may differ in order, so ranges_match compares resolved paths rather
than indices — the same comparison it made before.

\input chains need nothing special: every document of a project is in the
request's list, and a block whose items straddle two documents is never cached
(block_origin refuses it), so a cached block has exactly one document to remap.

Memory, measured

memprofile from #232, against a control at the same base:

case	live before	live after	VmRSS before	VmRSS after
synthetic-500kb, 385 pages	367.8 MiB	341.8	651.2 MiB	625.9
synthetic-2mb, 1507 pages	1458.4 MiB	1352.9	2569.5 MiB	2466.2

At 2 MB: −105.5 MiB live, −103.3 MiB resident. It lands on both copies of
every cluster — the walked display list falls 270.0 → 218.3 MiB and the render
cache 693.6 → 639.5 MiB. Allocator retention is unmoved (1111.2 → 1113.3 MiB).

More than the ~35 MiB this was ranked at, because that estimate counted the
cached copy only.

These two follow-ups are not additive. #283 removes the display list's copy
of every cluster; this shrinks each cluster in both copies. Measured separately
against the same control they are −244 and −105 MiB, but together the
display-list half of this one is already gone, so expect roughly −244 and then
the cache half of this, about −54 MiB, not −350. Whichever lands first, the
second should be re-measured rather than assumed.

Gates

All against a control run at the same base, this machine (NixOS, loaded —
memory and digests are load-independent, so no timing claims here):

gate	control	this branch
perf-bench digests, 14 fixtures	106	106 identical, 0 differing
harness diagnostic notes	—	identical set, both runs
amsmath oracle	59/59 within 0.5 bp	59/59
HW1 / HW2	3 pages, 0 errors, 0 overfull	3 pages, 0 errors, 0 overfull
font diagnostics	0	0
render-pipeline suite	202 passed / 0 failed / 1 ignored	202 / 0 / 1
the ignored slow one: 30 edits of a 107-page document, byte-identical	—	passes

Digest identity is the gate that matters most here, because a path now
round-trips through a table on its way to the wire: 106 identical digests say
it comes back as the same string. The 30-edit test is what exercises the
Relocate remap through real cache reuse.

Follow-up 3 (a byte budget on the render cache) is untouched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Xd5Hmwh5GHNTiAmHUJ1MZu

[GoKubar]

Backlog triage: the dependency this was waiting on has landed. #232 is now on main (2d1b517, "FT-070 memory: measure the breakdown, derive the per-glyph carets (Cluster 160 -> 88 B)"), and #206's harness with it (fe9bc43). This PR's own change is not on main — checked by content, not ancestry (main has no pub items: Rc<crate::display::LineItems> / pub block: std::rc::Rc<LineItems>) — so the work is still wanted.

Not closing: rebase onto current main and the numbers can be re-measured against the committed baseline instead of against a branch control. One caveat for whoever picks it up: the perf gate's output-identity check is a hard fail, so re-record crates/perf-bench/baselines/linux-x86_64-ryzen7-7800x3d.json on the reference host if the change moves any digest.