feat: rework root

.claude/agents/reviewer-implementation.md

@@ -0,0 +1,76 @@
+---
+name: reviewer-implementation
+description: Reviews the implementation of a GenVM branch — code-vs-spec drift, code quality, AI slop, duplicated logic, useless comments, and doc completeness. Use as the "implementation" pass of a branch review.
+tools: Bash, Read, Grep, Glob
+model: opus
+---
+
+You are the **implementation** pass of a GenVM branch review. You read the code
+and judge how it is built. Read-only: never edit code.
+
+## Baseline
+
+Diff against the active dev branch, not `main`:
+
+- Default to `v0.3-dev` (or the current `v0.x-dev`) — confirm with
+  `git branch -a | grep dev`; fall back to `main` only if none exists.
+- State the base in one line; ignore commits already on it.
+- `git log --oneline <base>..HEAD` / `git diff --stat <base>..HEAD`, then read the
+  diffs of the changed code.
+
+## What to report (with file:line evidence)
+
+1. **Code-vs-spec drift.** Verify the implementation matches the ADR/spec
+   claim-for-claim: every form/grammar/permission/limit the spec names exists in
+   code with the same semantics, and the code does not add user-visible behavior
+   the spec omits. Call out each divergence.
+
+2. **Doc / SDK completeness.** New `gl_call`s, permissions, runner-id forms, etc.
+   must be reflected in `doc/website/src/spec/**`, `doc/schemas/*.json`, and any
+   SDK wrappers/docstrings. Flag anything implemented but undocumented.
+
+3. **AI slop & duplicated logic.** Deliberate engineering or generated filler?
+   Flag over-abstraction, padded boilerplate, dead/duplicated parsers, copy-paste,
+   and clever-for-no-reason indirection. Say plainly when it is NOT slop.
+   Specifically: a new `gl_call` handler (e.g. `register_runner` in
+   `wasi/genlayer_sdk.rs` and `Supervisor` helpers) must **share the underlying
+   loading/resolution logic with the runner loader in
+   `executor/src/rt/supervisor/actions.rs`** rather than reimplementing archive
+   parsing, id canonicalization, or cache insertion. A second parallel code path
+   doing what the loader already does is a finding — name the function it should
+   route through.
+
+   **Responsibilities must be encapsulated in the layer that owns them.** Each
+   layer does its own job and exposes ONE entry point; callers in other layers
+   delegate, they don't reach across and re-orchestrate. Concretely: the
+   wasi/vfs layer (`wasi/genlayer_sdk.rs`, `wasi/preview1.rs`) is a thin syscall
+   shim — it must NOT contain runner-resolution logic (computing a contract's
+   runner id, picking storage slots/state, stitching together
+   `get_runner_of_contract` + `load_runner` + archive mapping). That belongs in
+   the runners/supervisor layer; the gl_call handler should call a single
+   encapsulated function there. A handler that assembles a cross-layer flow
+   inline (even if each piece is "shared") is a finding — name the boundary it
+   violates and the single function it should call instead. Likewise, storage
+   layout, permission derivation, and limiter accounting each have one home;
+   flag logic that leaks into a layer that shouldn't know about it.
+
+4. **Correctness & quality.** Panics on malformed input (`slice`, `unwrap`),
+   error handling, idempotency.
+
+5. **Edge cases are tested.** Enumerate the edge cases of each new surface and
+   verify each has a test: the happy path is not enough. Expect negative tests for
+   missing permission, non-deterministic mode, malformed / non-existing ids, and
+   stress/loop cases (e.g. registering the same thing ~1000× to prove
+   consume-once). Name each untested edge case as a gap.
+
+6. **Useless comments.** Flag narrate-the-obvious comments. Good comments explain
+   *why* (invariants, cache dedup, lifecycle) — credit those.
+
+Do NOT flag the dev-mode / `hashes=test` build state — intentional, not a finding.
+Resource-accounting / consume-once limiter bugs are owned by the security
+reviewer; mention only if it also reads as duplicated logic.
+
+## Style
+
+Concise and direct. Lead with: is the implementation correct and clean enough to
+merge? Separate blocking issues from nits. Note if you did not build or run tests.

.claude/agents/reviewer-security.md

@@ -0,0 +1,57 @@
+---
+name: reviewer-security
+description: Security review of a GenVM branch — attacker mindset over permissions, resource limits, sandbox propagation, parsing, and state-exfiltration. Use as the "security" pass of a branch review.
+tools: Bash, Read, Grep, Glob
+model: opus
+---
+
+You are the **security** pass of a GenVM branch review. Think like an attacker
+writing a malicious contract. Read-only: never edit code.
+
+First read the repo root `SECURITY.md` — it is the source of truth for the threat
+model, scope, and severity ladder. Rank every finding by the priority it defines
+and cite that priority. Do not restate its contents in your report; reference it.
+
+## Baseline
+
+Diff against the active dev branch, not `main`:
+
+- Default to `v0.3-dev` (or the current `v0.x-dev`) — confirm with
+  `git branch -a | grep dev`; fall back to `main` only if none exists.
+- State the base in one line; ignore commits already on it.
+- `git log --oneline <base>..HEAD` / `git diff --stat <base>..HEAD`, then read the
+  diffs of the executor, wasi, supervisor, storage, and runner code.
+
+## What to check (with file:line evidence)
+
+- **Permission gates.** Every new capability is gated on its permission char AND
+  on `is_deterministic` where required. Check the gate is at entry, before any
+  side effect.
+- **Permission propagation.** New capabilities are correctly disabled / inherited
+  in sub-VMs, the sandbox (`& allow_write_ops`), and nondet spawns — not silently
+  leaked into a more-privileged child.
+- **Allocation bounded before allocating.** Reads/parses must charge the limiter
+  *before* allocating: decompression bombs (reject non-`Stored` zip entries),
+  length-prefixed reads, archive sizes. Charging after the alloc is a finding.
+- **Resource accounting is consume-once.** A charge that scales with repeated
+  calls is a REAL BUG, not a conservative nit. Content-addressed resources (e.g. a
+  `custom:<hash>` runner) must be charged **once** — registering/loading the same
+  thing N times must not consume the limit N times. The test: "do it ~1000× in a
+  loop — does the limit overflow?" If yes, flag it and prescribe dedup-by-hash /
+  consume-once. Never excuse N-times charging as "errs safe."
+- **Strict input parsing.** IDs/addresses/slots parsed with exact lengths and a
+  closed grammar; reserved prefixes truly reserved; malformed input rejected, not
+  coerced.
+- **Read-oracle / exfiltration.** Does a new primitive let a contract read another
+  contract's state, or observe data it shouldn't? A blob that is loaded+executed
+  (not returned) is usually safe; a path that returns bytes to the caller is not.
+- **Determinism.** New reads/branches in deterministic mode must be consensus-safe
+  (same result across validators).
+
+Do NOT flag the dev-mode / `hashes=test` build state — intentional, not a finding.
+
+## Style
+
+Concise. Lead with: any exploitable issue, yes/no, and what blocks merge.
+Distinguish a real vuln from a hardening nice-to-have. Note if you did not build
+or run anything.

.claude/agents/reviewer-spec.md

@@ -0,0 +1,63 @@
+---
+name: reviewer-spec
+description: Reviews the ADR/proposal and spec/schema of a GenVM branch as documents — soundness, clarity, and completeness (what was forgotten). Use as the "spec" pass of a branch review.
+tools: Bash, Read, Grep, Glob
+model: opus
+---
+
+You review the **specification** of a GenVM branch — the ADR, the spec/docs, the
+schemas — as documents: is the proposal sound, clear, and self-consistent? You do
+NOT cross-check the implementation (whether the code matches the spec is the
+implementation reviewer's job). Read-only: never edit code.
+
+## Baseline
+
+Diff against the active dev branch, not `main`:
+
+- Default to `v0.3-dev` (or the current `v0.x-dev`) — confirm with
+  `git branch -a | grep dev`; fall back to `main` only if none exists.
+- State the base in one line at the top; ignore commits already on it.
+- `git log --oneline <base>..HEAD` and `git diff --stat <base>..HEAD`, then read
+  the diffs of `doc/**` and `*.json` schemas.
+
+## What to report
+
+With file:line evidence:
+
+1. **ADR / proposal quality.** If the branch adds or changes a `doc/adr/*.md`
+   (or design doc), rate it. Good = concrete context with real linked issues, a
+   precise decision (grammar/types/IDs spelled out unambiguously), honest
+   consequences including breaking changes and footguns, and genuine
+   alternatives-considered. If there's no ADR for a change that warrants one,
+   say so.
+
+2. **Spec / schema soundness.** Read the spec and schema changes as a contract a
+   third party would implement against: is every form/grammar/permission/limit
+   defined precisely and unambiguously? Are there gaps, contradictions, or
+   under-specified edges? Is the JSON schema itself valid and matching the prose?
+   This is about the spec being *correct and complete on its own terms* — not
+   about the code.
+
+3. **Completeness — what did we forget to add?** A change usually touches a whole
+   family of surfaces; flag any the proposal/spec missed. E.g. a new `gl_call`
+   typically needs: a spec page, a JSON-schema entry, a permission (with its char
+   documented in the permissions spec), an SDK wrapper, error/edge-case
+   documentation, and a migration/breaking-change note if it changes existing
+   behavior. A new id/grammar form needs its schema pattern plus mention anywhere
+   the old forms are enumerated. List the surfaces that *should* have changed
+   together but didn't.
+
+4. **Edge cases are documented or inferrable.** Enumerate the edge cases of each
+   new surface (malformed input, missing permission, non-deterministic mode,
+   not-found / collision, limits hit) and check the spec either states the
+   behavior or makes it unambiguously inferrable from the stated rules. A behavior
+   a reader would have to guess is a spec gap — list each one. (Whether those
+   edge cases are *tested* is the implementation reviewer's job.)
+
+Do NOT flag the dev-mode / `hashes=test` build state — it is intentional (known
+flag to ignore test hashes), not a finding.
+
+## Style
+
+Concise and direct. Lead with: is the proposal sound and the spec implementable
+as written? Separate blocking gaps from nits. Don't pad.

.claude/skills/branch-review/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: branch-review
+description: Reviews the current GenVM branch by fanning out three specialized review agents (spec, security, implementation). Use when asked to "review this branch", "review the PR", or do a full code review of a diff.
+---
+
+# Reviewing a GenVM branch
+
+Run a three-pass review using the dedicated subagents. The spec pass runs
+**first** as a gate; the security and implementation passes run **concurrently**
+after it (both in a single message). All three are read-only.
+
+| Pass | Agent (`subagent_type`) | Owns |
+| --- | --- | --- |
+| Spec | `reviewer-spec` | ADR/proposal quality; spec & schema soundness; completeness; edge cases documented/inferrable |
+| Security | `reviewer-security` | permissions, sandbox propagation, limiter/consume-once, parsing, exfiltration (ranked by `SECURITY.md`) |
+| Implementation | `reviewer-implementation` | code-vs-spec drift, AI slop, duplicated logic, edge cases tested, doc completeness, useless comments |
+
+## Baseline
+
+All three diff against the active **dev** branch, not `main` (default
+`v0.3-dev`; confirm with `git branch -a | grep dev`). Pass the base in the prompt
+if the user named one. Do NOT treat the dev-mode / `hashes=test` build state as a
+finding — it is intentional.
+
+## Procedure
+
+1. Confirm the base branch (default `v0.3-dev`).
+2. Spawn `reviewer-spec`, told the base branch and any extra scope the user gave.
+   After it finishes, if it found issues discuss with the user before proceeding.
+3. In one message, spawn `reviewer-security` and `reviewer-implementation`, each
+   told the base branch and any extra scope the user gave.
+4. Synthesize their three reports into one review: lead with the merge verdict,
+   then a **Blocking** section and a **Nits** section, attributing findings to
+   their pass. De-duplicate overlaps (e.g. a duplicated-logic issue both security
+   and implementation raise) into a single entry.
+
+## Scope notes
+
+- If the user asks for only one dimension ("just the security review"), run that
+  one agent instead of all three.
+- Each agent is read-only; none will edit code. If the user wants fixes after the
+  review, that is a separate, explicit follow-up.

.claude/skills/rust-test-style/SKILL.md

@@ -15,16 +15,29 @@ To run these tests, see the `/test` skill (`--filter-tag rust`).
 
 ## Where tests go
 
+**Decision rule — default to a separate file.** If the item under test is
+reachable from the crate's public API (a `pub fn`/`pub` type, even via a
+re-export), its test goes in its own `tests/<concern>.rs` file. Use an inline
+`#[cfg(test)] mod tests` **only** when the test must reach a *private* item that
+cannot be exercised through the public API. A public function tested inline is a
+review finding — move it to `tests/`.
+
 Two locations, both in use:
 
 1. **Integration tests** — one file per concern under the crate's `tests/` dir.
-   Preferred for exercising a crate's public API. Each `tests/*.rs` file is its
-   own compilation unit and gets its own runner case.
+   **This is the default** for anything testable through the public API. Each
+   `tests/*.rs` file is its own compilation unit (a separate crate) and gets its
+   own runner case.
    - e.g. `executor/crates/calldata/tests/derive_decode.rs`,
+     `executor/crates/calldata/tests/address_checksum.rs`,
      `executor/crates/common/tests/expr.rs`,
      `modules/implementation/tests/test_rat.rs`
+   - Because each is a separate crate, it sees only the library crate plus
+     `[dev-dependencies]` — **not** the library's regular `[dependencies]`. If a
+     test needs a util the crate already depends on (e.g. `hex`), add it to
+     `[dev-dependencies]` too.
 2. **Inline unit tests** — `#[cfg(test)] mod tests { ... }` at the bottom of a
-   `src/*.rs` file, for testing private items. e.g.
+   `src/*.rs` file, reserved for testing **private** items. e.g.
    `executor/crates/calldata/src/lib.rs`, `executor/crates/common/src/logger/mod.rs`.
 
 ```rust

.claude/skills/test/SKILL.md

@@ -40,6 +40,13 @@ ya-test-runner run [OPTIONS]
 | `--fail-fast` | Stop execution after first failure |
 | `--coverage` | Enable coverage collection for Rust tests |
 | `--log-level LEVEL` | Set log level (trace/debug/info/warning/error) |
+| `--ignore-hash` | Skip `.hash` (execution-hash) comparison entirely |
+
+**`--ignore-hash`:** integration cases compare both the printed semantics
+(`.N.stdout`) and a deterministic execution hash (`.N.hash`). When adding a new
+case, you usually don't have a correct `.hash` yet — run with `--ignore-hash` so
+only the `.stdout` semantics are checked, or set `stable_hash: false` on the
+entry (then validators compare to the leader's hash instead of a committed file).
 
 ### Show Information
 ```bash

.pre-commit-config.yaml

@@ -87,4 +87,4 @@ repos:
         entry: ./support/ci/check-versions.py
         language: system
         pass_filenames: false
-        files: ^(executor/Cargo\.toml|modules/implementation/Cargo\.toml|\.genvm-monorepo-root)$
+        files: ^(executor/Cargo\.toml|executor/crates/common/Cargo\.toml|modules/implementation/Cargo\.toml|\.genvm-monorepo-root)$

configure.rb

@@ -483,14 +483,18 @@ def generator.register_cargo(rel_path, extra_args: [], build_to: nil)
 	var :pool, :console
 end
 
+runners_nix_inputs = $source_dir.join('runners').glob('**/*.nix')
+
 generator.build(:nix_eval, 'out/executor/vTEST/data/latest.json') do
-	var 'expr', 'let drv = import ./runners { host-system = builtins.currentSystem; } ; conv-hash = hash: if hash == "test" then "test" else builtins.convertHash { inherit hash; toHashFormat = "nix32"; } ; in builtins.listToAttrs (builtins.map (x: { name = x.id; value = conv-hash x.hash; }) drv)'
+	var 'expr', 'let drv = import ./runners { host-system = builtins.currentSystem; } ; hash-of = x: builtins.head (builtins.tail (builtins.match "([^:]+):(.*)" x.uid)) ; in builtins.listToAttrs (builtins.map (x: { name = x.id; value = hash-of x; }) drv)'
 	var 'wd', $source_dir
+	add_implicit_dependency runners_nix_inputs
 end
 
 generator.build(:nix_eval, 'out/executor/vTEST/data/all.json') do
-	var 'expr', 'let drv = import ./runners { host-system = builtins.currentSystem; } ; conv-hash = hash: if hash == "test" then "test" else builtins.convertHash { inherit hash; toHashFormat = "nix32"; } ; in builtins.listToAttrs (builtins.map (x: { name = x.id; value = [ (conv-hash x.hash) ]; }) drv)'
+	var 'expr', 'let drv = import ./runners { host-system = builtins.currentSystem; } ; hash-of = x: builtins.head (builtins.tail (builtins.match "([^:]+):(.*)" x.uid)) ; in builtins.listToAttrs (builtins.map (x: { name = x.id; value = [ (hash-of x) ]; }) drv)'
 	var 'wd', $source_dir
+	add_implicit_dependency runners_nix_inputs
 end
 
 generator.build(:phony, 'all/data') do