Reserved reference slots in the storage grid

[halaprix]

The defect

A mapping, dynamic array, bytes or string reserves a slot that the grid never
showed. uint256 a; mapping(address => uint256) balances; uint256 b; rendered
slots 0 and 2 with nothing between them — read the grid top to bottom and the
compiler appears to have skipped an address. buildRows built its slot list only
from materialized value cells, so the reserved slot survived as prose under a
"Not expanded" heading.

That was the one place the instrument was silent instead of honest, and it was
silent about the most-taught fact in Solidity storage: a mapping consumes a slot
it then never writes, because its entries live at keccak(key ‖ slot).

What this does

Every reserved slot gets its own labeled row, and the row says what the slot
actually holds — which differs by encoding, so one shared sentence would be a lie:

Encoding	Base slot holds	Row shows
mapping	nothing, ever — solc never writes the head	RESERVED · mapping, no value
dynamic_array	the length	LENGTH · array, length = N
bytes/string	the length and, under 32 bytes, the data itself	short form renders the value inline

After a run, the observed word renders in amber — and only there, per the identity
law that amber marks measured values. A nonzero mapping head is flagged as an
anomaly rather than presented as a value, since only inline assembly or a slot
collision can put one there.

Rows are gapless by construction, not by assertion: buildRows walks a sorted
list of slot claims, collapses an unexpanded multi-slot span into a single elided
range instead of thousands of rows, and fills any unclaimed run with an honest
slots N–M · no declared variable banner. A 300-run fast-check property holds the
invariant.

Notable decisions

• CollapsedStorageSpan carries solc's encoding. The UI previously decided a
  span was a mapping via typeLabel.startsWith('mapping') — a heuristic over a
  display string, which this codebase forbids. An encoding solc does not emit now
  throws rather than being treated as one of the four.
• The row shape stayed one shape. A discriminated row union was the obvious
  alternative and the wrong trade: roving focus, pinning, React keys and
  aria-rowcount all index through row.slot/row.segments. Adding endSlot
  plus two full-width segment kinds left all four untouched.
• Observations, not a state replay, feed the measured word — so a slot that was
  only read still shows a value, which is the only way pre-existing state becomes
  visible. Documented limit: these are last-observed words, not post-revert final
  state.
• The default editor source seeds from the golden fixture (App.tsx:16), so
  the fixture gains balances/history/note at slots 5–7 plus a constructor
  that fills two of them. This is the one deliberate golden change, made through
  the reviewed --update path. Every existing variable kept its exact slot and
  offset; sourceHash, expectedLayoutHash and expectedRelationHash moved,
  expectedInstructionHash did not.
• Keccak-derived slots stay out of the grid (slotscope-xu8, v1.4). A row for
  one would claim an adjacency near 2^256 that it does not have, and the gapless
  walk would need an elided range ~10^76 slots wide to reach it.

Also fixed

CodeMirror's floating widgets — the lint tooltip, the diagnostic list, the Ctrl-F
panel — were rendering with the library's light-theme defaults under the app's
light text, effectively unreadable. An app-level .cm-tooltip rule does not fix
it (CodeMirror injects its base styles as a StyleModule, so the rule ties on
specificity and loses on order — measured, the tooltip stayed
rgb(245, 245, 245)). They are themed through EditorView.theme marked dark.

Two things the gates caught

• The longer fixture pushed positionValue out of CodeMirror's virtualized
  viewport, so relations.spec.ts could not find the line it clicks. The new
  declarations moved below the function; declaration order still assigns slots
  5–7.
• decode.test.ts asserted items.every(kind === 'value') on the fixture, now
  false. Replaced with a stronger check: the three reference types collapse at
  slots 5–7 with the right compiler encodings.

Verification

Gate	Result
format:check, lint, typecheck	clean
test:unit	235/235, including the Forge 1.5.1 cross-check
fixtures:verify	no drift after the reviewed --update
test:e2e	61/61 — axe in both motion modes, roving focus, 200% zoom, pins
build + build:check	pass, 224 KB main entry
benchmark:v0.1	p95 225 ms action-to-paint, 657 ms cold start — PASS

Design spec: docs/design/reserved-slots-v1.2.md. Plan:
docs/plans/2026-07-30-reserved-reference-slots.md. Closes slotscope-zvd
(.1–.5) and slotscope-73y.

One thing worth a manual look: the Ctrl-F search panel is themed but no test
opens it.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
slotscope	Ready	Preview	Jul 30, 2026 1:02pm