docs(corelib): document sortedness precondition for sorted array operations

Author: giwaov

CHANGELOG.md

@@ -10,6 +10,7 @@
 - Reverted `InvokeKind::ProcRef` back to `InvokeKind::Exec` in `visit_mut_procref` and added an explanatory comment (#2893).
 #### Changes
 
+- Documented sortedness precondition more prominently for sorted array operations (#2832).
 - Documented that enum variants are module-level constants and must be unique within a module (#2932).
 - [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)).
 - [BREAKING] `miden_processor::execute()` and `execute_sync()` now return `ExecutionOutput`; trace building remains explicit via `execute_trace_inputs*()` and `trace::build_trace()` ([#2865](https://github.com/0xMiden/miden-vm/pull/2865)).

crates/lib/core/asm/collections/sorted_array.masm

@@ -9,14 +9,17 @@ const LOWERBOUND_KEY_VALUE_EVENT = event("miden::core::collections::sorted_array
 
 #! Finds a value in a sorted array of words.
 #!
-#! This function will crash if the following conditions aren't met:
-#! - words must be sorted in non-decreasing order,
-#! - start_ptr, end_ptr are word-aligned
-#! - `start_ptr <= end_ptr`
+#! **The input array must be sorted in non-decreasing lexicographic order.** The host event handler validates this and will return an error if the array is not sorted.
 #!
 #! Input:  [VALUE, start_ptr, end_ptr]
 #! Output: [is_value_found, value_ptr, start_ptr, end_ptr]
 #!
+#! # Panics
+#!
+#! Panics if:
+#! - start_ptr, end_ptr are not word-aligned
+#! - `start_ptr > end_ptr`
+#!
 #! Cycles:
 #!   Value exists: 46 cycles
 #!   Value doesn't exist and the array is empty: 25 cycles
@@ -146,20 +149,18 @@ end
 
 #! Finds a key in a sorted array of (key, value) word tuples.
 #!
+#! **The keys in the array must be sorted in non-decreasing lexicographic order.** The host event handler validates this and will return an error if the keys are not sorted.
+#!
 #! Inputs:  [KEY, start_ptr, end_ptr]
 #! Outputs: [is_key_found, key_ptr, start_ptr, end_ptr]
 #!
 #! # Panics
 #!
 #! Panics if:
-#! - keys are not sorted in non-decreasing order,
 #! - start_ptr is not word-aligned
 #! - end_ptr is not double-word-aligned with the start_ptr:
 #!     - `(end_ptr - start_ptr)` must be divisible by 8
 #! - `start_ptr > end_ptr`
-#!
-#! Inputs: [KEY, start_ptr, end_ptr]
-#! Output: [is_key_found, key_ptr, start_ptr, end_ptr]
 pub proc find_key_value
     push.1
     # => [use_full_key = 1, KEY, start_ptr, end_ptr]
@@ -176,13 +177,14 @@ end
 #! Half-key means that, out of the keys in the array, only half of the key - the most significant
 #! element (prefix) and the second most significant element (suffix) - need to match.
 #!
+#! **The keys in the array must be sorted in non-decreasing lexicographic order.** The host event handler validates this and will return an error if the keys are not sorted.
+#!
 #! Inputs: [key_suffix, key_prefix, start_ptr, end_ptr]
 #! Output: [is_key_found, key_ptr, start_ptr, end_ptr]
 #!
 #! # Panics
 #!
 #! Panics if:
-#! - keys are not sorted in non-decreasing order,
 #! - start_ptr is not word-aligned
 #! - end_ptr is not double-word-aligned with the start_ptr:
 #!     - `(end_ptr - start_ptr)` must be divisible by 8
@@ -211,13 +213,14 @@ end
 #!   upon loading the key for comparison, its two least significant elements are zeroized.
 #!   This effectively means that only a match on the two most significant elements is required.
 #!
+#! **The keys in the array must be sorted in non-decreasing lexicographic order.** The host event handler validates this and will return an error if the keys are not sorted.
+#!
 #! Input:  [KEY, start_ptr, end_ptr, use_full_key]
 #! Output: [is_key_found, key_ptr, start_ptr, end_ptr]
 #!
 #! # Panics
 #!
 #! Panics if:
-#! - keys are not sorted in non-decreasing order,
 #! - start_ptr is not word-aligned
 #! - end_ptr is not double-word-aligned with the start_ptr:
 #!     - `(end_ptr - start_ptr)` must be divisible by 8

crates/lib/core/docs/collections/sorted_array.md

@@ -2,6 +2,6 @@
 ## miden::core::collections::sorted_array
 | Procedure | Description |
 | ----------- | ------------- |
-| find_word | Finds a value in a sorted array of words.<br /><br />This function will crash if the following conditions aren't met:<br />- words must be sorted in non-decreasing order,<br />- start_ptr, end_ptr are word-aligned<br />- `start_ptr <= end_ptr`<br /><br />Input:  [VALUE, start_ptr, end_ptr]<br />Output: [is_value_found, value_ptr, start_ptr, end_ptr]<br /><br />Cycles:<br />Value exists: 46 cycles<br />Value doesn't exist and the array is empty: 25 cycles<br />Value doesn't exist and is smaller than all elements: 151 cycles<br />Value doesn't exist and is larger than all elements: 149 cycles<br />Value doesn't exist: 286 cycles<br /> |
-| find_key_value | Finds a key in a sorted array of (key, value) word tuples.<br /><br />Inputs:  [KEY, start_ptr, end_ptr]<br />Outputs: [is_key_found, key_ptr, start_ptr, end_ptr]<br /><br /># Panics<br /><br />Panics if:<br />- keys are not sorted in non-decreasing order,<br />- start_ptr is not word-aligned<br />- end_ptr is not double-word-aligned with the start_ptr:<br />- `(end_ptr - start_ptr)` must be divisible by 8<br />- `start_ptr > end_ptr`<br /><br />Inputs: [KEY, start_ptr, end_ptr]<br />Output: [is_key_found, key_ptr, start_ptr, end_ptr]<br /> |
-| find_half_key_value | Finds a half-key in a sorted array of (key, value) word tuples.<br /><br />Half-key means that, out of the keys in the array, only half of the key - the most significant<br />element (prefix) and the second most significant element (suffix) - need to match.<br /><br />Inputs: [key_suffix, key_prefix, start_ptr, end_ptr]<br />Output: [is_key_found, key_ptr, start_ptr, end_ptr]<br /><br /># Panics<br /><br />Panics if:<br />- keys are not sorted in non-decreasing order,<br />- start_ptr is not word-aligned<br />- end_ptr is not double-word-aligned with the start_ptr:<br />- `(end_ptr - start_ptr)` must be divisible by 8<br />- `start_ptr > end_ptr`<br /> |
+| find_word | Finds a value in a sorted array of words.<br /><br />**The input array must be sorted in non-decreasing lexicographic order.** The host event handler validates this and will return an error if the array is not sorted.<br /><br />Input:  [VALUE, start_ptr, end_ptr]<br />Output: [is_value_found, value_ptr, start_ptr, end_ptr]<br /><br /># Panics<br /><br />Panics if:<br />- start_ptr, end_ptr are not word-aligned<br />- `start_ptr > end_ptr`<br /><br />Cycles:<br />Value exists: 46 cycles<br />Value doesn't exist and the array is empty: 25 cycles<br />Value doesn't exist and is smaller than all elements: 151 cycles<br />Value doesn't exist and is larger than all elements: 149 cycles<br />Value doesn't exist: 286 cycles<br /> |
+| find_key_value | Finds a key in a sorted array of (key, value) word tuples.<br /><br />**The keys in the array must be sorted in non-decreasing lexicographic order.** The host event handler validates this and will return an error if the keys are not sorted.<br /><br />Inputs:  [KEY, start_ptr, end_ptr]<br />Outputs: [is_key_found, key_ptr, start_ptr, end_ptr]<br /><br /># Panics<br /><br />Panics if:<br />- start_ptr is not word-aligned<br />- end_ptr is not double-word-aligned with the start_ptr:<br />- `(end_ptr - start_ptr)` must be divisible by 8<br />- `start_ptr > end_ptr`<br /> |
+| find_half_key_value | Finds a half-key in a sorted array of (key, value) word tuples.<br /><br />Half-key means that, out of the keys in the array, only half of the key - the most significant<br />element (prefix) and the second most significant element (suffix) - need to match.<br /><br />**The keys in the array must be sorted in non-decreasing lexicographic order.** The host event handler validates this and will return an error if the keys are not sorted.<br /><br />Inputs: [key_suffix, key_prefix, start_ptr, end_ptr]<br />Output: [is_key_found, key_ptr, start_ptr, end_ptr]<br /><br /># Panics<br /><br />Panics if:<br />- start_ptr is not word-aligned<br />- end_ptr is not double-word-aligned with the start_ptr:<br />- `(end_ptr - start_ptr)` must be divisible by 8<br />- `start_ptr > end_ptr`<br /> |