format: count segment offsets from the most significant byte

[gnidan]

The segment schema said offset: 0 is "the start of the specified slot" without saying which end of the word that is. It is the most significant byte: a slot's value is its $wordsize-byte big-endian word, and byte 0 is the first byte of that word. The reference implementation (packages/evm storage reads, packages/pointers segment resolution, including the carry) and bugc's packed storage access already work this way, so this changes no behavior.

The offset description now says this plainly and gives the conversion for layouts that count from the low-order end, such as Solidity's packed storage: a value of n bytes that sits o bytes from the low-order end is at offset $wordsize - o - n. An emitter can write that as a literal number, which is simplest to read and resolve, or as an expression such as { "$difference": ["$wordsize", { "$sum": [o, { ".length": "$this" }] }] }, which can take n from the region's own length, keeps the layout's own numbers visible, needs no arithmetic in the emitter, and does not depend on a fixed word size.

The segment schema gains packed examples that model Solidity's address owner; uint32 count; sharing one slot: a 20-byte address at the low-order end of slot 2 ("offset": 12) and a four-byte uint32 just above it ("offset": 8), each written once with literal offsets and once with the $difference form, taking n from the region's own length. segment.examples.test.ts in @ethdebug/pointers resolves each of them against a slot with a known word and checks the literal forms yield the address and the uint32, and that each expression form yields the same bytes as its literal twin. The pointer concepts page gets a one-sentence note, and the spec CHANGELOG has an entry.

Fixes #307

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-30 17:56 UTC