feat!: derive uarch cycle overflow from machine state

Regenerate the Solidity uarch transition and constants to make cycle
overflow a state-preserving fixed point derived from uarch.cycle.

Check overflow before halt, remove the encoded halt-reason constants,
and update tests and replay artifacts for the new access order and
break-reason precedence.

Update emulator tag.

Author: diegonehab

CHANGELOG.md

@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- Changed microarchitecture cycle overflow into a state-preserving fixed point derived from `uarch.cycle`
+- Changed microarchitecture cycle overflow to take precedence over halt
+
 ## [0.14.0] - 2026-04-13
 ### Added
 - Added `advanceStatus` to return advance status (accepted, rejected, exception)

Makefile

@@ -4,7 +4,7 @@ DOWNLOADDIR := downloads
 SRC_DIR := src
 
 EMULATOR_VERSION ?= v0.21.0
-EMULATOR_TAG ?= -test4
+EMULATOR_TAG ?= -test5
 
 SOLIDITY_VERSION ?= 0.8.30
 

helper_scripts/generate_EmulatorConstants.lua

@@ -28,8 +28,6 @@ out:write('    uint64 constant ROLLUP_LOG2_MAX_ADVANCE_STATES_PER_EPOCH = ' ..
     cartesi.ROLLUP_LOG2_MAX_ADVANCE_STATES_PER_EPOCH .. ';\n')
 out:write('    uint64 constant UARCH_HALT_ADDRESS = 0x' ..
     hex(cartesi.machine:get_reg_address("uarch_halt")) .. ';\n')
-out:write('    uint64 constant UARCH_HALT_HALTED = ' .. cartesi.UARCH_HALT_HALTED .. ';\n')
-out:write('    uint64 constant UARCH_HALT_CYCLE_OVERFLOW = ' .. cartesi.UARCH_HALT_CYCLE_OVERFLOW .. ';\n')
 out:write('    uint64 constant UARCH_PC_ADDRESS = 0x' .. hex(cartesi.machine:get_reg_address("uarch_pc")) .. ';\n')
 out:write('    uint64 constant UARCH_X0_ADDRESS = 0x' .. hex(cartesi.machine:get_reg_address("uarch_x0")) .. ';\n')
 out:write('    uint64 constant UARCH_SHADOW_START_ADDRESS = 0x' .. hex(cartesi.UARCH_SHADOW_START_ADDRESS) .. ';\n')

shasum-download

@@ -1,2 +1,2 @@
-fc0090028ceed1e3e7d30e953a20b7d77708b3df705ea8ef9aba1e343997a32b  downloads/machine-emulator-tests-data.deb
-f07140bbd5f1e1279d95fbe6fa31e7a9fc7e00c39eee7205aff9d4abae40fa33  downloads/uarch-riscv-tests-json-logs.tar.gz
+182c7a57481daa4076a488b1c3f0b8ba01d0271c267f79c9f5ecb947cac6bd50  downloads/machine-emulator-tests-data.deb
+79e0797c4a30c6a3f2523353006db0b8b99b6a6cdf17670634c6befa024905bf  downloads/uarch-riscv-tests-json-logs.tar.gz

src/EmulatorConstants.sol

@@ -25,16 +25,14 @@ library EmulatorConstants {
     // START OF AUTO-GENERATED CODE
 
     bytes32 constant UARCH_PRISTINE_STATE_HASH =
-        0x05dda45cb12872b018f3857a528439b1d1100bcd3fa019a9745ad436de9a4698;
+        0xfecd1447b18725c91ba909a13b3d059d3628a625f668ce991e6ab7c901a65d2c;
     uint64 constant UARCH_CYCLE_ADDRESS = 0x400008;
     uint64 constant UARCH_CYCLE_MAX = 0xfffff;
     uint64 constant ROLLUP_LOG2_MAX_MCYCLES_PER_ADVANCE_STATE = 48;
     uint64 constant ROLLUP_LOG2_MAX_UARCH_CYCLES_PER_MCYCLE = 20;
     uint64 constant ROLLUP_LOG2_MAX_OUTPUT_COUNT = 63;
     uint64 constant ROLLUP_LOG2_MAX_ADVANCE_STATES_PER_EPOCH = 24;
     uint64 constant UARCH_HALT_ADDRESS = 0x400000;
-    uint64 constant UARCH_HALT_HALTED = 1;
-    uint64 constant UARCH_HALT_CYCLE_OVERFLOW = 3;
     uint64 constant UARCH_PC_ADDRESS = 0x400010;
     uint64 constant UARCH_X0_ADDRESS = 0x400018;
     uint64 constant UARCH_SHADOW_START_ADDRESS = 0x400000;

src/UArchStep.sol

@@ -32,16 +32,6 @@ library UArchStep {
         UArchHalted // microarchitecture reached or was already at its halted fixed point
     }
 
-    function uarch_halt_to_step_status(uint64 halt)
-        private
-        pure
-        returns (UArchStepStatus)
-    {
-        return halt == EmulatorConstants.UARCH_HALT_CYCLE_OVERFLOW
-            ? UArchStepStatus.UArchCycleOverflow
-            : UArchStepStatus.UArchHalted;
-    }
-
     // Memory read/write access
 
     function readUint64(AccessLogs.Context memory a, uint64 paddr)
@@ -1082,8 +1072,7 @@ library UArchStep {
         // return value is in a0 (and maybe also in a1)
         uint64 fn = EmulatorCompat.readX(a, 17); // a7 contains the function number
         if (fn == EmulatorConstants.UARCH_ECALL_FN_HALT) {
-            return
-                EmulatorCompat.writeHalt(a, EmulatorConstants.UARCH_HALT_HALTED);
+            return EmulatorCompat.writeHalt(a, 1);
         }
         if (fn == EmulatorConstants.UARCH_ECALL_FN_PUTCHAR) {
             uint64 c = EmulatorCompat.readX(a, 10); // a0 contains the character to print
@@ -1328,38 +1317,29 @@ library UArchStep {
         pure
         returns (UArchStepStatus)
     {
-        // Report existing halt fixed point
-        uint64 halt = EmulatorCompat.readHalt(a);
-        if (halt != 0) {
-            return uarch_halt_to_step_status(halt);
-        }
-        // Report existing overflow fixed point if the cycle is at or beyond its limit
+        // Report the derived overflow fixed point before all other break reasons.
         uint64 cycle = EmulatorCompat.readCycle(a);
         if (cycle >= EmulatorConstants.UARCH_CYCLE_MAX) {
-            EmulatorCompat.writeHalt(
-                a, EmulatorConstants.UARCH_HALT_CYCLE_OVERFLOW
-            );
             return UArchStepStatus.UArchCycleOverflow;
         }
+        // Report an existing ordinary halt fixed point.
+        if (EmulatorCompat.readHalt(a) != 0) {
+            return UArchStepStatus.UArchHalted;
+        }
         // Execute next instruction
         uint64 pc = EmulatorCompat.readPc(a);
         uint32 insn = readUint32(a, pc);
         executeInsn(a, insn, pc);
         cycle = cycle + 1;
         EmulatorCompat.writeCycle(a, cycle);
-        // Materialize overflow immediately when this step reaches the cycle limit
+        // Overflow has precedence when this step reaches the cycle limit.
         if (cycle >= EmulatorConstants.UARCH_CYCLE_MAX) {
-            EmulatorCompat.writeHalt(
-                a, EmulatorConstants.UARCH_HALT_CYCLE_OVERFLOW
-            );
             return UArchStepStatus.UArchCycleOverflow;
         }
-        // ECALL is the only instruction that can halt the uarch. Overflow was handled above,
-        // so a non-zero halt value here can only report a normal halt.
+        // ECALL is the only instruction that can halt the uarch.
         if (insn == uint32(0x73)) {
-            halt = EmulatorCompat.readHalt(a);
-            if (halt != 0) {
-                return uarch_halt_to_step_status(halt);
+            if (EmulatorCompat.readHalt(a) != 0) {
+                return UArchStepStatus.UArchHalted;
             }
         }
         return UArchStepStatus.Success;

test/UArchInterpret.t.sol

@@ -115,23 +115,30 @@ contract UArchInterpretTest is Test {
             EmulatorConstants.UARCH_CYCLE_MAX,
             "step should not advance when cycle is at its maximum"
         );
-        assertEq(
-            EmulatorCompat.readHalt(a),
-            EmulatorConstants.UARCH_HALT_CYCLE_OVERFLOW,
-            "halt flag should record cycle overflow"
-        );
+        assertEq(EmulatorCompat.readHalt(a), 0, "overflow should preserve halt");
 
         // reset cycle to 0
         EmulatorCompat.writeCycle(a, 0);
         // set machine to halt
-        EmulatorCompat.writeHalt(a, EmulatorConstants.UARCH_HALT_HALTED);
+        EmulatorCompat.writeHalt(a, 1);
 
         status = UArchInterpret.interpret(a);
 
         assertTrue(
             status == UArchStep.UArchStepStatus.UArchHalted,
             "machine should halt"
         );
+
+        // overflow takes precedence over halt
+        EmulatorCompat.writeCycle(a, EmulatorConstants.UARCH_CYCLE_MAX);
+
+        status = UArchInterpret.interpret(a);
+
+        assertTrue(
+            status == UArchStep.UArchStepStatus.UArchCycleOverflow,
+            "machine should be cycle overflow"
+        );
+        assertEq(EmulatorCompat.readHalt(a), 1, "overflow should preserve halt");
     }
 
     function testIllegalInstruction() public {
@@ -146,6 +153,34 @@ contract UArchInterpretTest is Test {
         ExternalUArchInterpret.interpret(a);
     }
 
+    function testHaltEcallReachesCycleLimit() public {
+        AccessLogs.Context memory a = newAccessLogsContext();
+        a.buffer.data = bytes.concat(a.buffer.data, new bytes(8));
+
+        EmulatorCompat.writePc(a, EmulatorConstants.UARCH_RAM_START_ADDRESS);
+        EmulatorCompat.writeWord(
+            a, EmulatorConstants.UARCH_RAM_START_ADDRESS, 0x73
+        );
+        EmulatorCompat.writeX(a, 17, EmulatorConstants.UARCH_ECALL_FN_HALT);
+        EmulatorCompat.writeCycle(a, EmulatorConstants.UARCH_CYCLE_MAX - 1);
+
+        UArchStep.UArchStepStatus status = UArchStep.step(a);
+
+        assertTrue(
+            status == UArchStep.UArchStepStatus.UArchCycleOverflow,
+            "cycle overflow should take precedence over halt"
+        );
+        assertEq(
+            EmulatorCompat.readCycle(a),
+            EmulatorConstants.UARCH_CYCLE_MAX,
+            "step should reach the cycle limit"
+        );
+        assertTrue(
+            EmulatorCompat.readHalt(a) != 0,
+            "halt ECALL should set a non-zero halt value"
+        );
+    }
+
     function testRemovedMarkDirtyPageEcall() public {
         // function code 3 was the mark_dirty_page ecall and has been removed, so the
         // binary that issues it must now revert as an unsupported ecall