feat!: model cycle overflows as persistent fixed points

[diegonehab]

Problem

Machine and microarchitecture cycle limits were not handled consistently across execution, logging, verification, and
hash collection.

In particular, reaching a cycle limit needed to produce a fixed point without requiring an additional machine-state
transition. Calls targeting the current cycle also always reported that they had reached the target, even when the
current state already implied overflow, halt, or yield.

Solution

This PR models machine and microarchitecture cycle overflow as derived, state-preserving fixed points.

• Machine overflow is derived from mcycle and imcyclemax.
• Microarchitecture overflow is derived from uarch_cycle and UARCH_CYCLE_MAX.
• A machine at either limit does not advance further.
• Overflow takes precedence over halt, manual yield, and reaching the target cycle.
• Calls targeting the current cycle return the break reason implied by the current state.
• Hash collectors return the same break reason that the corresponding run operation would return.
• imcyclemax is updated when an accepted advance-state input starts a new processing interval.
• Rollup limits are centralized under ROLLUP_* constants.

The microarchitecture step now reads uarch_cycle before checking uarch_halt. After executing an instruction, it
checks overflow immediately after incrementing the cycle, before reporting a halt produced by that instruction. This
keeps the emulator, recorded access logs, replay verification, and Solidity step verifier aligned.

API changes

This PR adds explicit machine and microarchitecture overflow break reasons across the C++, C, Lua, and JSON-RPC APIs.

Notable renames include:

• uarch_halt_flag to uarch_halt
• configuration field halt_flag to halt
• reached_target_cycle to reached_target_uarch_cycle
• cycle_overflow to uarch_cycle_overflow
• CM_CMIO_LOG2_MAX_OUTPUT_COUNT to CM_ROLLUP_LOG2_MAX_OUTPUT_COUNT

The obsolete halt-value constants used to distinguish ordinary halt from cycle overflow were removed.

Testing

The updated tests cover:

• Machine and microarchitecture overflow fixed points
• Overflow precedence over halt and manual yield
• Calls targeting the current cycle
• Logging and verification at cycle limits
• Machine-cycle and microarchitecture-cycle hash collection
• Local and remote machine APIs
• C, Lua, and JSON-RPC break-reason mappings
• Microarchitecture access-log ordering

[mpernambuco]

LGTM

[Copilot]

Pull request overview

This PR makes cycle overflow semantics consistent across execution, logging/verification, and hash collection by modeling both machine-cycle (mcycle/imcyclemax) and microarchitecture-cycle (uarch_cycle/UARCH_CYCLE_MAX) overflow as derived, state-preserving fixed points with defined precedence.

Changes:

• Introduces imcyclemax and mcycle_overflow and wires them through interpreter/run paths and hash collectors so same-target calls report the current fixed-point reason without forcing a transition.
• Renames and reshapes uarch halt/cycle concepts (uarch_halt_flag → uarch_halt, reached_target_*, *_cycle_overflow) and updates C/C++/Lua/JSON-RPC APIs accordingly.
• Centralizes rollup limits under ROLLUP_* constants and propagates them into the public C API (CM_ROLLUP_*) and Lua bindings.

Reviewed changes

Copilot reviewed 59 out of 59 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
uarch/compute-uarch-pristine-hash.cpp	Updates pristine uarch state initialization to use the renamed halt register/init constant.
tests/misc/test-machine-c-api.cpp	Adds/updates C API tests for rollup constants, new registers (IMCYCLEMAX), and renamed uarch break reasons/registers.
tests/lua/uarch-riscv-tests.lua	Updates Lua tests to use uarch_halt and correct yield/response setup for logging.
tests/lua/spec-verify-uarch-failure.lua	Renames uarch halt register usage in verification-failure tests.
tests/lua/spec-machine-api.lua	Adds imcyclemax to machine API register coverage and renames uarch_halt_flag mapping.
tests/lua/spec-hash-tree-lua.lua	Switches from CMIO constant to rollup output-count constant.
tests/lua/spec-collect-hashes.lua	Aligns hash collection expectations with fixed-point/overflow semantics and updated uarch reset padding behavior.
tests/lua/spec-cm-cli.lua	Updates CLI proof expectations to use rollup output-count constant.
tests/lua/mcycle-overflow.lua	Adds extensive regression coverage for overflow fixed points and precedence across run/log/verify/uarch-step.
tests/lua/machine-bind.lua	Updates Lua binding tests for new constants, imcyclemax, renamed uarch register/break reasons, and new semantics.
tests/lua/cartesi-machine-tests.lua	Updates tests to use uarch_halt register semantics.
tests/fuzz/gen-seed-corpus.lua	Adjusts assumed shadow-register block size to match the new register layout.
tests/fuzz/fuzz-interpret-step.cpp	Updates fuzz target to read the renamed uarch halt register.
src/uarch-step.hpp	Renames uarch step status enum value to UArchCycleOverflow and updates docs/wording.
src/uarch-step.cpp	Implements overflow-precedence logic in uarch stepping and renames halt accessor usage.
src/uarch-state-access.hpp	Renames uarch halt accessors and maps to the new halt field.
src/uarch-solidity-compat.hpp	Renames halt wrappers and adds mcycle/imcyclemax wrappers for Solidity-converted code.
src/uarch-interpret.hpp	Renames interpreter break reasons for uarch to *_uarch_cycle / uarch_cycle_overflow.
src/uarch-interpret.cpp	Enforces overflow/halt/same-target precedence in uarch interpreter and updates break-reason mapping.
src/uarch-defines.h	Centralizes uarch constants (halt/pc/cycle init; max-cycle derived from rollup constants).
src/uarch-constants.hpp	Introduces uarch init constants and switches machine-state address mapping to shadow-register enums.
src/state-access.hpp	Adds imcyclemax read/write support to state access layer.
src/shadow-uarch-state.hpp	Renames uarch halt field and updates register enum/name mapping.
src/shadow-registers.hpp	Adds imcyclemax to shadow registers and updates size/static asserts and name mapping.
src/send-cmio-response.hpp	Replaces local CMIO constant usage with rollup constants include.
src/send-cmio-response.cpp	Updates imcyclemax when sending an advance-state response (with saturating limit).
src/rollup-defines.h	Adds centralized rollup limit macros.
src/rollup-constants.hpp	Adds centralized rollup limit constants for C++ consumers.
src/riscv-constants.hpp	Adds IMCYCLEMAX_INIT and removes uarch init constants now housed in uarch headers.
src/replay-send-cmio-state-access.hpp	Extends replay state-access to read mcycle and write imcyclemax for send-cmio replay.
src/record-send-cmio-state-access.hpp	Extends record state-access to read mcycle and write imcyclemax for send-cmio logging.
src/processor-state.hpp	Adjusts padding to preserve page alignment after shadow register expansion.
src/Makefile	Bumps emulator minor version.
src/machine.hpp	Documents overflow precedence and adds get_state_break_reason helper for consistent behavior.
src/machine.cpp	Implements imcyclemax register plumbing, new break-reason derivation, and updated hash-collection fixed-point semantics.
src/machine-reg.hpp	Adds imcyclemax and renames uarch halt register enum.
src/jsonrpc-machine.cpp	Updates default uarch break reason to the renamed reached_target_uarch_cycle.
src/jsonrpc-discover.json	Extends JSON-RPC schema with imcyclemax, mcycle_overflow, and renamed uarch fields/break reasons.
src/json-util.cpp	Adds imcyclemax reg name mapping and updates (de)serialization for renamed uarch fields/break reasons.
src/interpret.hpp	Adds mcycle_overflow interpreter break reason.
src/interpret.cpp	Enforces overflow fixed-point precedence and clamps effective target cycle to imcyclemax.
src/i-uarch-state-access.hpp	Renames uarch halt accessor macros.
src/i-state-access.hpp	Adds imcyclemax accessor macros.
src/i-machine.hpp	Updates collect_uarch_cycle_root_hashes API documentation for revised tail/fixed-point rules.
src/htif-address-range.cpp	Adds include needed after new register/init usage.
src/collect-uarch-cycle-hashes-state-access.hpp	Updates static-assert assumptions for renamed first uarch shadow register.
src/collect-mcycle-hashes-state-access.hpp	Adds imcyclemax read/write support for hash collection state access.
src/cm.h	Updates public C API with rollup constants, CM_UARCH_CYCLE_MAX semantics, new break reasons, and new registers.
src/cm.cpp	Adds static asserts for rollup constants and maps new/renamed registers.
src/clua-i-machine.cpp	Adds Lua-C register mapping for imcyclemax and exposes mcycle_overflow break reason.
src/clua-cartesi.cpp	Exposes rollup constants and new overflow/uarch-break constants to Lua.
src/cartesi-machine.lua	Updates CLI script logic to use rollup constants and renamed uarch halt/break reason symbols.
doc/recipes/run-rolling-calculator-output-proofs.lua	Updates recipe to use rollup output-count constant.
doc/recipes/rootfs-docs.ext2	Updates LFS pointer for docs rootfs image.
doc/recipes/rolling-verification-game.lua	Updates recipe to use rollup output-count constant.
doc/recipes/find-uarch-putchar-ecall.lua	Updates recipe to use renamed uarch halt register.
doc/README.md.template	Updates template docs for new constants/registers and revised semantics.
doc/README.md	Updates generated docs/examples for new constants/registers, renamed uarch fields, and revised semantics/hashes.
CHANGELOG.md	Documents new overflow break reasons, rollup constants rename, and hash-collection behavior fix.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 132 out of 136 changed files in this pull request and generated 1 comment.

[mpernambuco]

what will the backup_closer do after this for ends with active backup_machine, revert? should we commit()?

[diegonehab]

Very nice catch. In these weird error conditions, the computation hash is perfectly defined: they are sticky fixed points that will never change (send_cmio_response is a noop on them). This is true of an unexpected manual yield, an mcycle overflow, halt, or exception. We should commit. Will do.