Next/3.0

.claude/skills/add-e2e-scenario/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: add-e2e-scenario
+description: Add or wire a new e2e test scenario for the PRT rollups harness (test/e2e/rollups). Use when creating a scenario, adding a sybil scenario, or wiring an existing scenario into suites, CI, or the battery.
+---
+
+# Add an e2e scenario
+
+Full harness context: `docs/test-harness.md` (anatomy, oracle doctrine,
+patch chains, kill markers). The wiring checklist, complete:
+
+1. Pick or build a machine program under `test/programs/` (see its
+   justfile). Existing: echo, yield, honeypot; `compute` builds but is
+   not yet wired into any scenario.
+2. Write `test/e2e/rollups/scenarios/<name>.lua`: require `test_env`,
+   spawn blockchain and node, drive epochs with `run_epoch` or
+   hand-rolled sybils with patch lists. Copy the shape of a sibling
+   scenario (`simple.lua` for honest runs, `kill_*.lua` for kill points,
+   `multi_sybil.lua` for concurrent matches).
+3. Wire a justfile alias if it should run in a suite
+   (`test/e2e/rollups/justfile`). Give the recipe a self-contained
+   final comment line - `just --list` shows only that line.
+4. Add it to `battery.sh`'s `SCENARIOS` array if it should run in the
+   full parallel battery. The array is independent of the justfile
+   aliases and does not inherit from them; a scenario missing here is
+   omitted from execution and produces only a non-fatal warning. If the
+   scenario is deliberately excluded, add its bare script name to
+   `EXCLUDED_SCENARIOS` and put the reason in an adjacent comment.
+5. If it should gate PRs, add the just target to
+   `.github/workflows/build.yml` - CI calls just targets by name, never
+   inline commands.
+
+Run it: `just rollups-tests::test <program> <name>`, or with
+`TEST_INSTANCE=<free port>` for an isolated parallel lane. Read
+results honestly with `just logged`. Use the same `TEST_INSTANCE=<id>`
+when running `just view-rollups-logs`; without it, that recipe follows
+the default `dave.log`. Sweep with `just rollups-tests::sweep` after
+reading results.

.claude/skills/contract-change-gate/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: contract-change-gate
+description: Pre- and post-change gate for production Solidity changes under prt/contracts or cartesi-rollups/contracts. Use before editing any src/ contract file there, and again before declaring the change done.
+---
+
+# Contract change gate
+
+The authoritative context is the directory's `AGENTS.md`
+(`prt/contracts/AGENTS.md` or `cartesi-rollups/contracts/AGENTS.md`):
+its reading table, invariants, and guardrails. This skill is the
+mechanical checklist wrapped around them.
+
+Before editing:
+
+1. Read the directory's `AGENTS.md` reading-table rows for your change
+   type, and the docs they name.
+2. For `prt/contracts`: run
+   `just prt-contracts::compatibility-hashes` and save the output.
+
+After editing, before declaring done:
+
+1. `prt/contracts`: re-run `just prt-contracts::compatibility-hashes`
+   and inspect EVERY difference against the change's intent. Hashes are
+   comparison aids, not approval to update a snapshot mechanically.
+2. Run the directory's gate:
+   - `just prt-contracts::check-fmt` and `just prt-contracts::test-all`
+     (or the focused suites the AGENTS.md lists), or
+   - `just rollups-contracts::check-fmt` and
+     `just rollups-contracts::test`.
+3. Match the change to its required extra evidence (from AGENTS.md):
+   Clock changes need the one-clock tests, the MatchClocks matrix, and
+   Tournament composition; Match changes need white-box representation tests
+   and an independent oracle; gas-affecting changes need the
+   gas-calibration skill; geometry changes need the whole-table
+   validator plus coordinated cross-implementation work.
+4. If the ABI, events, errors, or clone-argument encoding changed, stop and
+   confirm the task explicitly authorizes a new deployment generation;
+   regenerate bindings (`just bind`) and deployment artifacts. If storage or
+   raw Match or Clock encodings changed, inspect the impact and update
+   white-box probes without treating the old representation as a
+   wire-compatibility promise.
+5. Cross-implementation seams (state transition, commitment geometry,
+   provider behavior): confirm the Rust node, the Lua client, and the
+   docs were updated in the same change, or say explicitly why not.

.claude/skills/doc-drift-check/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: doc-drift-check
+description: Verify a documentation file against the code it describes and fix pointer rot. Use when asked to review, audit, or update docs, after a refactor that renamed modules or functions, or periodically as maintenance.
+---
+
+# Doc drift check
+
+The repo's docs state invariants (stable) and reference code by path,
+symbol, and count (volatile). Empirically, the invariants hold and the
+pointers rot - so check the pointers.
+
+Procedure, per document:
+
+1. Extract every pointer-type claim: file paths, module names, function
+   and type names, table/schema lists, command names, counts ("21
+   scenarios"), and cross-references to other docs.
+2. Verify each against the tree (Glob/Grep, `just --list`). For claims
+   about behavior shape (control flow, gating, ordering), read the
+   named code - do not trust the doc's paraphrase.
+3. Fix what drifted. Prefer fixes that cannot rot again: replace counts
+   with "see <file> for the current list", link the authoritative file
+   instead of restating its contents.
+4. Check status headers: a plan whose own completion criteria are met
+   should be marked frozen per the policy in `docs/README.md`; a
+   "known debts" entry describing code that no longer exists should be
+   marked retired with the date, matching the sibling entries' style.
+5. For invariant-type claims that look wrong, do not silently "fix" the
+   doc: the code is the source of truth, but a disagreement may be a
+   code bug. Verify deeply, then either fix the doc with evidence or
+   raise the discrepancy.
+
+Sweep order when doing general maintenance: the AGENTS.md files, then
+docs/README.md's reading list, then the doc nearest the most recent
+refactor (git log tells you where the churn was).
+
+Conventions for any doc fix: ASCII only, concise, state invariants and
+reasons rather than restating code structure, and update docs in the
+same change as the code that invalidated them.

.claude/skills/gas-calibration/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: gas-calibration
+description: Run or validate PRT refund-gas calibration. Use when changing Gas.sol allocations, Bond.sol formulas, anything that shifts measured action gas (contract logic on refunded paths), or when a gas witness test fails. Also when asked to "calibrate gas" or "measure gas".
+---
+
+# PRT refund-gas calibration
+
+The maintained procedure is `docs/runbooks/prt-refund-gas-calibration.md`.
+Read it before acting; this skill only routes and states the gate.
+
+Non-negotiables:
+
+- A gas-affecting change must follow the runbook even when the selected
+  allocation remains unchanged. Never calibrate under coverage
+  instrumentation.
+- The accepted gate is `just measure-prt-gas` under the pinned release
+  environment the runbook describes. It combines the PRT Tournament-only
+  matrix with the serialized full-stack FFI leaf-proof matrix.
+- Witness validation (fast, no re-measurement): `just test-prt-gas`.
+- Trace any allocation change through `Bond.sol` into bonds and
+  deployment artifacts; the runbook shows how.
+- Accepted calibrations are archived as dated records under
+  `docs/reviews/` (see the 2026-07-23 gas-calibration records for the
+  expected shape of the evidence).
+
+Use `just logged <file> <cmd...>` for the measurement runs so a display
+pipeline cannot hide the real exit code.

.dockerignore

@@ -6,7 +6,11 @@
 
 **/target/
 
-**/_state/
+**/_state*/
+**/_oracle*/
+**/_battery/
+**/dave*.log*
+**/anvil*.log*
 **/snapshots/
 **/compute_data/
 **/rollups_data/
@@ -21,9 +25,6 @@ test/programs/**/machine-image/
 cartesi-rollups/contracts/bindings-rs/src/contract/
 prt/contracts/bindings-rs/src/contract/
 
-prt/tests/compute/outputs/
-prt/tests/compute/pixels/
-
 machine/emulator/**/*.o
 machine/emulator/**/*.swp
 machine/emulator/**/*.d

.github/actions/cartesi-machine/action.yml

@@ -4,7 +4,7 @@ inputs:
   version:
     description: 'Version of Cartesi Machine to install'
     required: false
-    default: 0.19.0
+    default: 0.21.0
   suffix-version:
     description: 'Suffix of Cartesi Machine to install'
     required: false
@@ -13,10 +13,18 @@ inputs:
     description: 'Architecture of Cartesi Machine to install'
     required: false
     default: 'amd64'
+  archive-sha256:
+    description: 'SHA-256 of the Cartesi Machine Debian package; override with version, suffix, or arch'
+    required: false
+    default: '5f13034f43454c340062c677146daabe77c587cee1bd60342c95b8ad8f1463a3'
   xgenext2fs-version:
     description: 'Version of xgenext2fs to install'
     required: false
     default: '1.5.6'
+  xgenext2fs-sha256:
+    description: 'SHA-256 of the xgenext2fs Debian package; override with version or arch'
+    required: false
+    default: '996e4e68a638b5dc5967d3410f92ecb8d2f41e32218bbe0f8b4c4474d7eebc59'
 runs:
   using: composite
   steps:
@@ -28,13 +36,14 @@ runs:
       run: |
         sudo apt-get update
         sudo apt-get install -y --no-install-recommends \
-            build-essential git wget \
+            build-essential curl git wget \
             libslirp-dev \
             libclang-dev \
             liblua5.4-dev lua5.4 \
             xxd jq sqlite3 libc6 clang libarchive13
 
           wget -O xgenext2fs.deb https://github.com/cartesi/genext2fs/releases/download/v${XGENEXT2_VERSION}/xgenext2fs_${ARCH}.deb
+          echo "${{ inputs.xgenext2fs-sha256 }}  xgenext2fs.deb" | sha256sum --check
           sudo apt-get install -y ./xgenext2fs.deb
           rm ./xgenext2fs.deb
           xgenext2fs --version
@@ -43,10 +52,15 @@ runs:
       shell: bash
       run: |
         curl -fsSL https://github.com/cartesi/machine-emulator/releases/download/v${{ inputs.version }}${{ inputs.suffix-version }}/machine-emulator_${{ inputs.arch }}.deb -o /tmp/cartesi-machine.deb
+        echo "${{ inputs.archive-sha256 }}  /tmp/cartesi-machine.deb" | sha256sum --check
 
     - name: Install Cartesi Machine
       shell: bash
       run: |
         sudo apt-get install -y /tmp/cartesi-machine.deb
         rm -v /tmp/cartesi-machine.deb
         cartesi-machine --version
+        test -f /usr/lib/libcartesi.a
+        test -f /usr/include/cartesi-machine/cm.h
+        echo "LIBCARTESI_PATH=/usr/lib" >> "$GITHUB_ENV"
+        echo "INCLUDECARTESI_PATH=/usr/include/cartesi-machine" >> "$GITHUB_ENV"

.github/actions/setup-tools/action.yml

@@ -8,15 +8,13 @@ inputs:
   rust-version:
     description: 'Rust version to install (if Rust is setup)'
     required: false
-    default: '1.86'
-  foundry-version:
-    description: 'Foundry version to install'
-    required: false
-    default: 'v1.4.3'
+    # Keep in step with the release container (rust:1.90-trixie in
+    # build.yml); the workspace uses post-1.86 std APIs.
+    default: '1.90'
   setup-qemu:
     description: 'Whether to setup QEMU for riscv support'
     required: false
-    default: 'true'
+    default: 'false'
   setup-rust:
     description: 'Whether to setup Rust'
     required: false
@@ -29,40 +27,35 @@ runs:
   using: composite
   steps:
     - name: Set up QEMU for riscv support
-      uses: docker/setup-qemu-action@v3
+      uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4.2.0
       if: ${{ inputs.setup-qemu == 'true' }}
 
     - name: Install Rust
-      uses: actions-rust-lang/setup-rust-toolchain@v1
+      uses: actions-rust-lang/setup-rust-toolchain@166cdcfd11aee3cb47222f9ddb555ce30ddb9659 # v1.17.0
       if: ${{ inputs.setup-rust == 'true' }}
       with:
-        components: rustfmt
+        components: rustfmt,clippy
         target: ${{ inputs.target }}
         toolchain: ${{ inputs.rust-version }}
         cache-on-failure: false
         cache-bin: false
 
+    - name: Install just
+      uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4.0.0
+      with:
+        # Pinned like the other toolchain components: a floating "latest"
+        # upgrades CI's toolchain silently mid-week (1.56 -> 1.57
+        # landed between two runs of this workflow and muddied a
+        # two-day CI hunt). Bump deliberately.
+        just-version: "1.57.0"
+
     - name: Set Foundry version
       id: set-foundry-version
       shell: bash
       run: |
-        echo "version=${{ inputs.foundry-version }}" >> $GITHUB_OUTPUT
+        echo "version=$(just print-foundry-version)" >> "$GITHUB_OUTPUT"
 
     - name: Install Foundry
-      uses: foundry-rs/foundry-toolchain@v1
+      uses: foundry-rs/foundry-toolchain@908c540300062bd5a7e473851cdb4282204cee09 # v1.9.1
       with:
         version: ${{ steps.set-foundry-version.outputs.version }}
-
-    - name: Install just
-      uses: extractions/setup-just@v3
-
-    - name: Install pnpm
-      uses: pnpm/action-setup@v4
-      with:
-        package_json_file: 'prt/contracts/package.json'
-
-    - uses: actions/setup-node@v4
-      with:
-        node-version: 22
-        cache: 'pnpm'
-        cache-dependency-path: 'prt/contracts/pnpm-lock.yaml'