docs(assembly): clarify div vs u32div semantics

CHANGELOG.md

@@ -5,6 +5,8 @@
 #### Bug Fixes
 
 - Reverted `InvokeKind::ProcRef` back to `InvokeKind::Exec` in `visit_mut_procref` and added an explanatory comment (#2893).
+- Fixed `FastProcessor` so `after_exit` trace decorators execute when tracing is enabled without debug mode, and added a tracing-only regression test.
+- Strengthened assembly docs to clarify that `div` is field division and to cross-reference `u32div` for integer floor division (#2911).
 #### Changes
 
 - [BREAKING] Sync execution and proving APIs now require `SyncHost`; async `Host`, `execute`, and `prove` remain available ([#2865](https://github.com/0xMiden/miden-vm/pull/2865)).

docs/src/user_docs/assembly/field_operations.md

@@ -28,14 +28,16 @@ The message is hashed and turned into a field element. If the error code is omit
 
 ### Arithmetic and Boolean operations
 
-The arithmetic operations below are performed in a 64-bit [prime field](https://en.wikipedia.org/wiki/Finite_field) defined by modulus $p = 2^{64} - 2^{32} + 1$. This means that overflow happens after a value exceeds $p$. Also, the result of divisions may appear counter-intuitive because divisions are defined via inversions.
+The arithmetic operations below are performed in a 64-bit [prime field](https://en.wikipedia.org/wiki/Finite_field) defined by modulus $p = 2^{64} - 2^{32} + 1$. This means that overflow happens after a value exceeds $p$.
+
+**Important:** `div` is field division, i.e. $a \cdot b^{-1} \mod p$, not integer floor division. For integer division, use [`u32div`](./u32_operations.md#arithmetic-operations) (or [`u32divmod`](./u32_operations.md#arithmetic-operations)).
 
 | Instruction                                                                    | Stack_input | Stack_output  | Notes                                                                                                        |
 | ------------------------------------------------------------------------------ | ----------- | ------------- | ------------------------------------------------------------------------------------------------------------ |
 | add <br /> - *(1 cycle)*  <br /> add.*b* <br /> - *(1-2 cycle)*                      | [b, a, ...] | [c, ...]      | $c \leftarrow (a + b) \mod p$                                                                                |
 | sub <br /> - *(2 cycles)*  <br /> sub.*b* <br /> - *(2 cycles)*                      | [b, a, ...] | [c, ...]      | $c \leftarrow (a - b) \mod p$                                                                                |
 | mul <br /> - *(1 cycle)*  <br /> mul.*b* <br /> - *(2 cycles)*                       | [b, a, ...] | [c, ...]      | $c \leftarrow (a \cdot b) \mod p$                                                                            |
-| div <br /> - *(2 cycles)*  <br /> div.*b* <br /> - *(2 cycles)*                      | [b, a, ...] | [c, ...]      | $c \leftarrow (a \cdot b^{-1}) \mod p$ <br /> Fails if $b = 0$                                                 |
+| div <br /> - *(2 cycles)*  <br /> div.*b* <br /> - *(2 cycles)*                      | [b, a, ...] | [c, ...]      | $c \leftarrow (a \cdot b^{-1}) \mod p$ <br /> Fails if $b = 0$ <br /> For integer floor division, use [`u32div`](./u32_operations.md#arithmetic-operations).                                                 |
 | neg <br /> - *(1 cycle)*                                                         | [a, ...]    | [b, ...]      | $b \leftarrow -a \mod p$                                                                                     |
 | inv <br /> - *(1 cycle)*                                                         | [a, ...]    | [b, ...]      | $b \leftarrow a^{-1} \mod p$ <br /> Fails if $a = 0$                                                           |
 | pow2 <br /> - *(16 cycles)*                                                      | [a, ...]    | [b, ...]      | $b \leftarrow 2^a$ <br /> Fails if $a > 63$                                                                    |

docs/src/user_docs/assembly/u32_operations.md

@@ -95,7 +95,7 @@ The message is hashed and turned into a field element. If the error code is omit
 | u32wrapping_mul <br /> - *(2 cycles)* <br /> u32wrapping_mul.*b* <br /> - *(3-4 cycles)*        | [b, a, ...]    | [c, ...]      | $c \leftarrow (a \cdot b) \mod 2^{32}$ <br /> Undefined if $max(a, b) \ge 2^{32}$                                                                                                        |
 | u32widening_madd <br /> - *(1 cycle)*                                                      | [b, a, c, ...] | [d, e, ...]   | $d \leftarrow (a \cdot b + c) \mod 2^{32}$ <br /> $e \leftarrow \lfloor(a \cdot b + c) / 2^{32}\rfloor$ <br /> Undefined if $max(a, b, c) \ge 2^{32}$                                      |
 | u32wrapping_madd <br /> - *(3 cycles)*                                                      | [b, a, c, ...] | [d, ...]      | $d \leftarrow (a \cdot b + c) \mod 2^{32}$ <br /> Undefined if $max(a, b, c) \ge 2^{32}$                                                                                                 |
-| u32div <br /> - *(2 cycles)* <br /> u32div.*b* <br /> - *(3-4 cycles)*      | [b, a, ...]    | [d, c, ...]   | $c \leftarrow \lfloor a / b\rfloor$ <br /> $d \leftarrow a \mod b$ <br /> Fails if $b = 0$ <br /> Undefined if $max(a, b) \ge 2^{32}$                                                        |
+| u32div <br /> - *(2 cycles)* <br /> u32div.*b* <br /> - *(3-4 cycles)*      | [b, a, ...]    | [d, c, ...]   | $c \leftarrow \lfloor a / b\rfloor$ <br /> $d \leftarrow a \mod b$ <br /> Fails if $b = 0$ <br /> Undefined if $max(a, b) \ge 2^{32}$ <br /> For field division in $\mathbb{F}_p$, use [`div`](./field_operations.md#arithmetic-and-boolean-operations).                                                        |
 | u32mod <br /> - *(3 cycles)* <br /> u32mod.*b* <br /> - *(4-5 cycles)*      | [b, a, ...]    | [c, ...]      | $c \leftarrow a \mod b$ <br /> Fails if $b = 0$ <br /> Undefined if $max(a, b) \ge 2^{32}$                                                                                                 |
 | u32divmod <br /> - *(1 cycle)* <br /> u32divmod.*b* <br /> - *(2-3 cycles)* | [b, a, ...]    | [d, c, ...]   | $c \leftarrow \lfloor a / b\rfloor$ <br /> $d \leftarrow a \mod b$ <br /> Fails if $b = 0$ <br /> Undefined if $max(a, b) \ge 2^{32}$                                                        |