scan rain interpreter bytecode for ops present/reachable

[thedavidmeister]

The library scans EVM bytecode for ops present (scanEVMOpcodesPresentInBytecode) and reachable (scanEVMOpcodesReachableInBytecode).

Add an analogous scanner for rain interpreter bytecode (the format the rain interpreter executes, not EVM bytecode).

Use case: a contract that delegates to a rain expression can be audited statically for which rain ops the expression uses, in the same way that EVM op scanning is used to audit deployed implementations.

[thedavidmeister]

Verified against main @ 32f7325

The premise holds. src/lib/LibExtrospectBytecode.sol has scanEVMOpcodesPresentInBytecode and
scanEVMOpcodesReachableInBytecode; there is no rain-bytecode handling anywhere in src/, and none of the
twelve functions on IExtrospectV1 touch the rain format. Baseline for this checkout, excluding the
fork-only file test/src/lib/LibExtrospectBytecode.checkCBORTrimmedBytecodeHash.t.sol (needs
ARBITRUM_RPC_URL, absent here): 307 passed / 0 failed / 0 skipped, 26 suites.

Not implementing this. Not because it is hard — the return shape carries over cleanly — but because
every implementable definition of "which rain ops does this expression use" reaches a different verdict
about the same expression, and that is a call for you, not for me.

What the format actually constrains

From rain.interpreter.interface src/lib/bytecode/LibBytecode.sol and rain.interpreter
src/lib/eval/LibEval.sol, both @ main:

1. Layout. 1 byte source count; then count x 2-byte relative offsets; then each source is a 4-byte
   header (opsCount, stackAllocation, inputs, outputs) followed by opsCount x 4-byte ops. Each op
   is 1 byte opcode index + 3 bytes operand (evalLoop: byte(0, word) and
   and(shr(0xe0, word), 0xFFFFFF)).
   So the opcode index is a uint8 and the uint256 bitmap return shape transfers from the EVM scanners
   with nothing lost. The return type is not the problem.

2. There is no intra-source reachability question. evalLoop executes every op of a source top to
   bottom. There is no jump, no halt, no conditional skip — if and conditions are eager value selects,
   not branches. Present-in-a-source is executed-when-the-source-is-entered. The EVM library's
   present/reachable split has no intra-source analogue.

3. The only cross-source transfer is call. LibOpCall.run is the only place state.sourceIndex is
   written outside eval4; there is no do-while or loop-n op in the current 72-op table. Its target is the
   low 16 bits of its operand, so it is statically readable — if you know which index is call.

4. call's index is not stable. LibAllStandardOps pins only the first four as "stable well known
   indexes" (stack=0, constant=1, extern=2, context=3); everything after is alphabetical. call is
   11 today and moves the moment an alphabetically-earlier op is added.

5. The byte in the bytecode is not necessarily the op that runs. evalLoop dispatches
   mod(byte(0, word), fsCount), with fsCount = ALL_STANDARD_OPS_LENGTH = 72 today.
   LibIntegrityCheck does reject opcodeIndex >= fsCount — but integrity is a deploy-time step and
   eval4 does not run it. For any bytecode that never passed integrity against the interpreter it is
   handed to, byte 83 executes op 11 (call) and byte 74 executes op 2 (extern). Untrusted bytecode
   is precisely this library's remit.

6. Some ops resolve through data outside the bytecode. extern, context, constant, get/set
   resolve via the constants array, context grid and store — none of which are in the bytes being scanned.
   An index bitmap can say "this expression reaches an extern", never which extern.

7. fsCount is obtainable, but not from IInterpreterV4. That interface exposes only eval4.
   RainlangInterpreter implements IOpcodeToolingV1.buildOpcodeFunctionPointers() as public view and
   advertises it via ERC165, so fsCount = buildOpcodeFunctionPointers().length / 2 is readable onchain
   from that implementation — but it is not part of the interpreter interface contract, so it is not
   guaranteed for an arbitrary interpreter.

8. No rain-format dependency exists here today. foundry.toml carries forge-std, rain-solmem,
   rain-math-binary, rain-deploy. rain-interpreter-interface is on soldeer (latest 0.1.2).

The option space

Each of these is a different answer to "does this expression use op X". They are mutually exclusive.

A. Structure-walking scan of the raw index bytes

scanRainOpcodesPresentInBytecode(bytes) -> uint256. Walk source count, offsets and headers; OR
1 << byte for each op. Needs a checkNoOOBPointers equivalent first or it reads past the array.

• Newly accepts: every expression whose op bytes are >= fsCount on the interpreter it will actually
  run on. Byte 0x53 scans as bit 83 and executes as call. An auditor asking "does this expression call
  other sources?" is told no about bytecode that calls.
• Newly rejects: nothing structurally. But it reports index numbers, and index-to-name is
  interpreter-version-specific, so any consumer that hard-codes "bit 11 means call" mis-reports silently
  against a future op table.
• Who that affects: anyone auditing bytecode that did not come from the deployer/parser paired with the
  target interpreter — the untrusted-bytecode case, i.e. the reason to have this at all.

B. Interpreter-parameterised scan

scanRainOpcodesPresentInBytecode(bytes bytecode, uint256 fsCount) -> uint256, bitmapping
byte % fsCount. Caller sources fsCount from IOpcodeToolingV1 (7 above).

• Newly rejects: every alias. Byte 83 at fsCount 72 sets bit 11, so aliased call/extern stop
  hiding.
• Newly accepts: nothing beyond A.
• Who that affects: every caller, who must now name the interpreter. The library stops answering "what
  does this bytecode do" and answers "what does this bytecode do on that interpreter" — which is the
  only question the format lets it answer honestly. Cost: an expression scanned against the wrong fsCount
  gets a confidently wrong bitmap, so the parameter moves the failure from silent to caller-visible rather
  than removing it.

C. Flat 4-byte stride, no structure walk

Cheapest, cannot read OOB.

• Newly rejects: almost everything, spuriously. The source-count byte, the 2-byte offsets and the 4-byte
  headers are all small integers that collide with the four stable indexes. A 2-source expression sets bit
  2 from its source-count byte alone, so "uses extern" is true of essentially every expression.
• Newly accepts: nothing.
• Who that affects: it destroys the signal for exactly the four ops whose indexes are guaranteed.
  Listed so the cheap option is on the record as unusable, not to be picked.

D. Reachable scan

scanRainOpcodesReachableInBytecode(bytes bytecode, uint256 entrypoint, uint256 callOpIndex) -> uint256,
unioning the transitive call closure from entrypoint.

• Newly accepts: ops appearing only in sources no call reaches from that entrypoint. This is real
  signal — an unreferenced source genuinely never runs for that entrypoint.
• Newly rejects: nothing beyond A/B at the same entrypoint.
• Who that affects: the entrypoint is chosen by the calling contract at eval4 time and is not
  encoded in the bytecode, so a result at entrypoint 0 says nothing about the same bytecode dispatched at
  entrypoint 1. Anyone reading "reachable" as unqualified — the way the README's EVM reachable scan can be
  read — gets a stronger claim than the function makes. And callOpIndex must be an argument: hard-coding
  11 bakes today's op table into a CREATE2-pinned contract (4 above).

E. Decline

Close this; keep the library EVM-only and do rain-op auditing offchain, where the op table and
functionPointers are free to read and versioned alongside the interpreter.

• Newly accepts / rejects: nothing. No verdict surface added.
• Who that affects: the use case in the issue body stays offchain-only.

Consequence that lands whichever you pick (A, B or D)

Extrospect is CREATE2-pinned. EXTROSPECT_CREATION_BYTECODE_V1, EXTROSPECT_ZOLTU_ADDRESS_V1 and
EXTROSPECT_RUNTIME_CODEHASH_V1 are asserted in test/src/concrete/Extrospect.constants.t.sol. Anything
added to IExtrospectV1 changes all three and needs a new address and a redeploy. This is the concrete
reason the version-dependent inputs in B and D should be arguments, not constants: an argument keeps the
pinned deployment valid when the op table moves, a constant forces a redeploy every time it does.

Also required either way: a decision on depending on rain-interpreter-interface for the layout readers
versus reimplementing them here. Depending means the format has one owner and this repo tracks it;
reimplementing means two copies of a format this repo does not own, free to drift.