feat: document trace layout constants using insta snapshots

air/Cargo.toml

@@ -46,4 +46,6 @@ p3-merkle-tree.workspace = true
 serde.workspace = true
 
 [dev-dependencies]
+criterion.workspace = true
+insta.workspace = true
 proptest.workspace = true

air/src/trace/mod.rs

@@ -3,19 +3,19 @@ use core::ops::Range;
 use chiplets::hasher::RATE_LEN;
 use miden_core::utils::range;
 
+pub mod aux_trace;
 pub mod chiplets;
 pub mod decoder;
+pub mod main_trace;
 pub mod range;
+pub mod rows;
 pub mod stack;
 
-mod rows;
-pub use rows::{RowIndex, RowIndexError};
-
-mod main_trace;
-pub use main_trace::{MainTrace, MainTraceRow};
-
-mod aux_trace;
 pub use aux_trace::AuxTraceBuilder;
+pub use main_trace::{MainTrace, MainTraceRow};
+pub use rows::{RowIndex, RowIndexError};
+#[cfg(test)]
+mod tests;
 
 // CONSTANTS
 // ================================================================================================

air/src/trace/snapshots/miden_air__trace__tests__ace_chiplet_layout.snap

@@ -0,0 +1,34 @@
+---
+source: air/src/trace/tests.rs
+expression: layout
+---
+ACE CHIPLET LAYOUT
+=====================
+
+Chiplet Selectors:
+  Number of ACE selectors: 4
+
+Column Indices (ordered by index):
+  - 0: Selector start
+  - 1: Selector block
+  - 2: Context
+  - 3: Pointer
+  - 4: Clock
+  - 5: Eval operation
+  - 6: ID 0
+  - 7: Value 0_0
+  - 8: Value 0_1
+  - 9: ID 1
+  - 10: Value 1_0
+  - 11: Value 1_1
+  - 12: ID 2
+  - 12: Read num eval
+  - 13: Value 2_0
+  - 14: Value 2_1
+  - 14: Multiplicity 1
+  - 15: Multiplicity 0
+
+Other Constants:
+  Number of columns: 16
+  ACE init label: 8
+  Instruction ID2 offset: 1152921504606846976

air/src/trace/snapshots/miden_air__trace__tests__all_chiplet_column_ranges.snap

@@ -0,0 +1,34 @@
+---
+source: air/src/trace/tests.rs
+expression: layout
+---
+ALL CHIPLET COLUMN RANGES
+================================
+
+Chiplet Selector Counts:
+  - Hasher selectors: 1
+  - Bitwise selectors: 2
+  - Memory selectors: 3
+  - ACE selectors: 4
+  - Kernel ROM selectors: 5
+
+Hasher Chiplet:
+  Trace offset: 52
+  Selector range: 52..55 (width 3)
+  State range: 55..67 (width 12)
+  Capacity range: 55..59 (width 4)
+  Rate range: 59..67 (width 8)
+  Node index: 67
+
+Bitwise Chiplet:
+  Trace offset: 53
+  Selector index: 53
+  Input A range: 56..60 (width 4)
+  Input B range: 60..64 (width 4)
+  Trace range: 53..66 (width 13)
+
+Memory Chiplet:
+  Trace offset: 54
+  Value range: 61..65 (width 4)
+
+Note: All column indices are relative to the main trace (not relative to the chiplet trace).

air/src/trace/snapshots/miden_air__trace__tests__aux_trace_layout.snap

@@ -0,0 +1,39 @@
+---
+source: air/src/trace/tests.rs
+expression: layout
+---
+AUXILIARY TRACE LAYOUT
+==========================
+
+Decoder Auxiliary Trace:
+  Offset: 0
+  Width: 3
+  Range: 0..3
+
+Stack Auxiliary Trace:
+  Offset: 3
+  Width: 1
+  Range: 3..4
+
+Range Check Auxiliary Trace:
+  Offset: 4
+  Width: 1
+  Range: 4..5
+
+Hasher/Kernel ROM Virtual Table Auxiliary Trace:
+  Offset: 5
+  Width: 1
+  Range: 5..6
+
+Chiplets Bus Auxiliary Trace:
+  Offset: 6
+  Width: 1
+  Range: 6..7
+
+ACE Chiplet Wiring Bus:
+  Offset: 7
+  Width: 1
+  Range: 7..8
+
+Total Auxiliary Trace Width: 8
+Auxiliary Trace Random Elements: 16

air/src/trace/snapshots/miden_air__trace__tests__bitwise_chiplet_layout.snap

@@ -0,0 +1,30 @@
+---
+source: air/src/trace/tests.rs
+expression: layout
+---
+BITWISE CHIPLET LAYOUT
+===========================
+
+Chiplet Selectors:
+  Number of bitwise selectors: 2
+  Trace offset: 53
+  Selector column index: 53
+
+Input Columns:
+  Input A column index: 54
+  Input B column index: 55
+  Input A bit decomposition range: 56..60
+  Input B bit decomposition range: 60..64
+
+Output Columns:
+  Previous output column index: 64
+  Output column index: 65
+
+Trace Range:
+  Bitwise trace range: 53..66
+
+Other Constants:
+  Number of selectors: 1
+  Trace width: 13
+  Operation cycle length: 8
+  Number of decomposed bits per row: 4

air/src/trace/snapshots/miden_air__trace__tests__decoder_trace_layout.snap

@@ -0,0 +1,39 @@
+---
+source: air/src/trace/tests.rs
+expression: layout
+---
+DECODER TRACE LAYOUT
+======================
+
+Hasher State:
+  Offset: 8
+  Number of columns: 8
+  Range: 8..16
+
+Operation Bits:
+  Offset: 1
+  Number of bits: 7
+  Range: 1..8
+
+Operation Bits Extra Columns (for degree reduction):
+  Offset: 22
+  Number of columns: 2
+  Range: 22..24
+
+User Operation Helpers:
+  Offset: 10
+  Number of helpers: 6
+
+Operation Batch Flags:
+  Offset: 19
+  Number of flags: 3
+  Range: 19..22
+
+Column Indices (ordered by index):
+  - 12: Is loop body flag
+  - 13: Is loop flag
+  - 14: Is call flag
+  - 15: Is syscall flag
+  - 16: In span column
+  - 17: Group count column
+  - 18: Operation index column

air/src/trace/snapshots/miden_air__trace__tests__hasher_chiplet_layout.snap

@@ -0,0 +1,32 @@
+---
+source: air/src/trace/tests.rs
+expression: layout
+---
+HASHER CHIPLET LAYOUT
+==========================
+
+Chiplet Selectors:
+  Number of hasher selectors: 1
+  Trace offset: 52
+  Selector column range: 52..55
+
+Hasher State:
+  State width: 12
+  State column range: 55..67
+
+Capacity Portion (RPO):
+  Capacity length: 4
+  Capacity column range: 55..59
+  Capacity domain index: 1
+
+Rate Portion (RPO):
+  Rate length: 8
+  Rate column range: 59..67
+
+Other Constants:
+  Digest length: 4
+  Number of rounds: 7
+  Hash cycle length: 8
+  Number of selectors: 3
+  Hasher trace width: 16
+  Node index column: 67

air/src/trace/snapshots/miden_air__trace__tests__kernel_rom_chiplet_layout.snap

@@ -0,0 +1,14 @@
+---
+source: air/src/trace/tests.rs
+expression: layout
+---
+KERNEL ROM CHIPLET LAYOUT
+================================
+
+Chiplet Selectors:
+  Number of kernel ROM selectors: 5
+
+Other Constants:
+  Trace width: 5
+  Kernel procedure call label: 0b001111 + 1 (16)
+  Kernel procedure init label: 0b101111 + 1 (48)

air/src/trace/snapshots/miden_air__trace__tests__main_trace_layout.snap

@@ -0,0 +1,40 @@
+---
+source: air/src/trace/tests.rs
+expression: layout
+---
+MAIN TRACE LAYOUT
+===================
+
+Minimum trace length: 2048
+
+System Trace:
+  Offset: 0
+  Width: 6
+  Range: 0..6
+  - Clock column index: 0
+  - Context column index: 1
+  - Function hash offset: 2
+  - Function hash range: 2..6
+
+Decoder Trace:
+  Offset: 6
+  Width: 24
+  Range: 6..30
+
+Stack Trace:
+  Offset: 30
+  Width: 19
+  Range: 30..49
+
+Range Check Trace:
+  Offset: 49
+  Width: 2
+  Range: 49..51
+
+Chiplets Trace:
+  Offset: 51
+  Width: 20
+  Range: 51..71
+
+Total Trace Width: 71
+Padded Trace Width: 72

air/src/trace/snapshots/miden_air__trace__tests__memory_chiplet_layout.snap

@@ -0,0 +1,25 @@
+---
+source: air/src/trace/tests.rs
+expression: layout
+---
+MEMORY CHIPLET LAYOUT
+==========================
+
+Chiplet Selectors:
+  Number of memory selectors: 3
+  Trace offset: 54
+  Trace width: 15
+
+Column Indices (ordered by index):
+  - 54: Is read column
+  - 55: Is word access column
+  - 56: Context column
+  - 57: Word column
+  - 58: Index 0 column
+  - 59: Index 1 column
+  - 60: Clock column
+  - 61..65: Value columns
+  - 65: Delta 0 column
+  - 66: Delta 1 column
+  - 67: Delta inverse column
+  - 68: Same context and word flag

air/src/trace/snapshots/miden_air__trace__tests__range_check_trace_layout.snap

@@ -0,0 +1,19 @@
+---
+source: air/src/trace/tests.rs
+expression: layout
+---
+RANGE CHECK TRACE LAYOUT
+============================
+
+Main Trace:
+  Offset: 49
+  Width: 2
+  Range: 49..51
+  - M column (multiplicity): 49
+  - V column (values being range-checked): 50
+
+Auxiliary Trace:
+  Offset: 4
+  Width: 1
+  Range: 4..5
+  - B column (running product): 4

air/src/trace/snapshots/miden_air__trace__tests__stack_trace_layout.snap

@@ -0,0 +1,15 @@
+---
+source: air/src/trace/tests.rs
+expression: layout
+---
+STACK TRACE LAYOUT
+====================
+
+Stack Top:
+  Offset: 0
+
+Helper Columns:
+  Number of helper columns: 3
+  - b0 column (stack depth): 16
+  - b1 column (overflow table address): 17
+  - h0 column (1 / (b0 - 16)): 18