format, pointers, bugc: specify and implement two-sorted (integer/bytes) expression evaluation

[gnidan]

Pointer expressions had an unstated gap: the width of a value was undefined for numeric literals, arithmetic results, and odd-digit hex, yet $concat and $keccak256 depend on operand widths — so a compiler and a debugger could legitimately disagree on the bytes produced. This specifies the evaluation model and brings the reference implementation, the compiler, and the docs along with it.

Semantics

Expressions evaluate to a value of one of two sorts:

• an integer — an unbounded, non-negative integer with no width;
• bytes — a finite byte sequence with a definite width.

The forms are sorted accordingly. Integers: a JSON-number literal, $wordsize, a variable or lookup, arithmetic ($sum/$difference/$product/$quotient/$remainder), and an odd-digit hex literal (which has no whole-byte width). Bytes: an even-digit hex literal (width = bytes written), $read (width = region length), $sizedN/$wordsized (width = N / word size), $keccak256 (width 32), and $concat (width = sum of operand widths).

Coercion runs one way. Where an integer is expected — arithmetic operands, a list count, a segment slot/offset/length — a bytes value is read as the non-negative integer its bytes encode (big-endian). Where bytes are expected — the operands of $concat and $keccak256 — the operand must be width-bearing; a bare integer there is an error and must be given a width with $sizedN/$wordsized first. The resize forms are the only bridge from an integer to bytes; there is no implicit widening.

This codifies what the mapping/string pointer examples already do (they word-size a key and slot before hashing). Two schema examples that hashed bare integers are corrected: the keccak256 definition's example and the expression schema's root-level example.

Reference implementation

@ethdebug/pointers now evaluates to a tagged Value — integer or bytes — with the sort rules above, coerces where an integer is expected, and throws on a bare-integer operand to $concat or $keccak256 with a message naming the operand and suggesting $wordsized/$sizedN. Variables carry the sort of their defining expression. This is package-internal: evaluate is not exported from the package index, and the public Cursor.Region shape is unchanged, so no consumers needed edits. The previous single-width implementation gave a JSON-number literal minimal width (literal 0 was zero bytes), so a $keccak256 over a bare slot silently hashed the wrong preimage; that can no longer happen.

The evaluator's previously skipped keccak test is reinstated, and the evaluator test file now covers every sort rule, both coercion directions, and the error cases. A new test evaluates every $keccak256/$concat occurrence in the pointer schema examples so an example without operand widths fails the suite.

Compiler

bugc's slot-computation helpers emitted $keccak256 with a bare slot operand. They now word-size it, with a nested $keccak256 passed through since it is already 32-byte bytes. These helpers have no production callers today — bugc emits a mapping variable as its base slot — so emitted debug info was already valid; the helpers and their pinned tests are corrected so that any future use is too.

Docs

The expression spec page no longer says values are "assumed to be left-padded to the bytes width appropriate for the context"; it states the two sorts, the even/odd hex rule, and the width-bearing requirement. The pointer expressions guide gains an "Integers and bytes" section and word-sizes the operands in its hashing examples. The evaluation implementation guide follows the new evaluator's shape.

Note: the integer/bytes sorting discipline is meant to carry over into a future extraction of the expression language into a shared facility.

[github-actions]

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