Update Noir #1

.claude/settings.json

@@ -0,0 +1,30 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "mcp__claudebox__create_pr|mcp__claudebox__update_pr",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'cd $(git rev-parse --show-toplevel) && ./.githooks/pre-commit'"
+          },
+          {
+            "type": "command",
+            "command": "bash -c 'cd $(git rev-parse --show-toplevel) && echo \"refs/heads/hook $(git rev-parse HEAD) refs/heads/hook 0000000000000000000000000000000000000000\" | ./.githooks/pre-push'"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'FILE=$(jq -r \".tool_input.file_path\"); if [[ \"$FILE\" == *.rs ]]; then cargo fmt -- \"$FILE\" 2>/dev/null; fi'"
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/bisect-ssa-pass/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: bisect-ssa-pass
+description: Workflow for debugging SSA pass semantic preservation using the noir-ssa CLI. Use when a program's behavior changes incorrectly during the SSA pipeline - bisects passes to identify which one breaks semantics. The `pass_vs_prev` fuzzer finds such issues automatically.
+allowed-tools: Bash, Read, Grep, Glob, Write
+---
+
+# Noir SSA Bisection Debugging
+
+Use this skill when debugging SSA optimization bugs - situations where an SSA pass fails to preserve program semantics. This workflow bisects SSA passes to identify which one introduces the behavioral change.
+
+Common scenarios:
+- **Fuzzer failures**: The `pass_vs_prev` fuzzer found a program that produces different results after some SSA pass
+- **Test failures**: An existing test started failing after changes to an SSA pass
+- **Manual discovery**: A program produces incorrect results and you suspect an optimization bug
+
+Helper scripts are in the `scripts/` directory of this skill.
+
+## Prerequisites
+
+You need a Noir project with a `Prover.toml` containing inputs that trigger the suspected issue. The program should produce incorrect results or exhibit unexpected behavior when executed.
+
+## 1. Compiling and Splitting SSA Passes
+
+Compile with `--show-ssa` to output SSA after each optimization pass:
+
+```bash
+# Basic compilation (add -Zenums if using match expressions)
+nargo compile --show-ssa 2>&1 | tee ssa_output.txt
+```
+
+**Important**: Do not pipe the output through `head` or other truncating commands (e.g., `| tee ssa_output.txt | head -50`). This truncates the file before all passes are written. Inspect the file separately after compilation completes.
+
+Verify the output captured all passes (~49 expected):
+```bash
+grep -E "^After " ssa_output.txt
+```
+
+### Split into separate files
+
+Use the provided script to split the output into one file per pass:
+
+```bash
+./scripts/split-ssa-passes.sh ssa_output.txt ssa_passes
+```
+
+Then clean up headers and diagnostics:
+
+```bash
+./scripts/clean-ssa-files.sh ssa_passes
+```
+
+This creates files like:
+```
+ssa_passes/01_Initial_SSA.ssa
+ssa_passes/02_black_box_bypass_(1)_(step_1).ssa
+ssa_passes/03_expand_signed_checks_(1)_(step_2).ssa
+...
+```
+
+## 2. Using noir-ssa CLI to Bisect Failures
+
+Build the SSA CLI tool (if not already built):
+```bash
+cargo build --release -p noir_ssa_cli
+```
+
+The binary is at `target/release/noir-ssa`.
+
+### Bisecting to Find the Failing Pass
+
+Use the bisect script to run interpretation on each pass:
+
+```bash
+./scripts/bisect-ssa.sh 'v0 = "-92"' ssa_passes /path/to/noir-ssa
+```
+
+**Input format**: SSA parameters are named `v0`, `v1`, etc. based on their order. Convert your Prover.toml inputs accordingly (e.g., `a = "-92"` becomes `v0 = "-92"`). Use `;` to separate multiple inputs.
+
+Example output:
+```
+01_Initial_SSA.ssa: Ok(i8 1)
+...
+06_Inlining_simple_functions_(1)_(step_5).ssa: Ok(i8 1)
+07_Mem2Reg_(1)_(step_6).ssa: Err(Reference value `*v8 = None` loaded before it was first stored to)
+...
+
+First failure: 07_Mem2Reg_(1)_(step_6).ssa
+```
+
+This identifies **Mem2Reg (step 6)** as the pass that introduced the bug.
+
+### Manual Interpretation
+
+You can also run interpretation manually on individual files:
+
+```bash
+noir-ssa interpret --source-path ssa_passes/06_Inlining_simple_functions_*.ssa --input-toml 'v0 = "-92"'
+noir-ssa interpret --source-path ssa_passes/07_Mem2Reg_*.ssa --input-toml 'v0 = "-92"'
+```
+
+Additional options:
+- `--trace`: Enable execution tracing
+- `--input-path`: Read inputs from a TOML file instead of inline
+
+### Comparing SSA Before/After
+
+Once you identify the failing pass, compare the SSA files:
+```bash
+diff ssa_passes/06_*.ssa ssa_passes/07_*.ssa
+```
+
+Or read both files and look for the specific difference that causes the failure.
+
+## 3. Creating Regression Tests
+
+Once you've identified the failing pass, create a unit test to prevent regression. **Use the actual SSA from the `ssa_passes/` directory** rather than trying to manually simplify or recreate the pattern.
+
+### Why use the SSA files directly?
+
+- The SSA in `ssa_passes/` is the exact input that triggers the bug
+- Manually simplifying can accidentally remove the triggering pattern
+- Complex inputs (like arrays of references) are difficult to construct programmatically
+- The SSA parser accepts the exact format already present in the files
+
+### Creating the test
+
+1. Read the SSA file from the pass **before** the failure (the last working pass):
+   ```bash
+   cat ssa_passes/06_Inlining_simple_functions_*.ssa
+   ```
+
+2. Extract the relevant function(s) that exhibit the bug
+
+3. Add a test to the appropriate pass's test module (e.g., `compiler/noirc_evaluator/src/ssa/opt/mem2reg.rs`):
+
+```rust
+#[test]
+fn regression_test_name() {
+    let src = r#"
+    // Paste the SSA function(s) from the ssa_passes file here
+    brillig(inline) fn func_1 f0 {
+      b0(v2: [&mut u1; 3]):
+        // ... exact SSA from the file
+        return v19
+    }
+    "#;
+
+    // Choose the appropriate assertion based on the bug:
+    let ssa = Ssa::from_str(src).unwrap();
+    let result = ssa.mem2reg();
+    // Then verify the result maintains correctness
+}
+```
+
+### Test approaches
+
+- **Interpret before and after**: Run the SSA interpreter on the SSA before and after the pass with the same inputs, and verify both produce the same result. This is a good general approach since optimization passes should preserve semantics.
+- `assert_normalized_ssa_equals(src, expected)` — Verifies exact SSA output after transformation
+- `assert_ssa_does_not_change(src, pass_fn)` — Verifies the pass doesn't modify the SSA (useful when a pass incorrectly removes instructions it shouldn't)
+
+### Using `#[should_panic]` for known bugs
+
+If documenting a bug that hasn't been fixed yet, use `#[should_panic(expected = "...")]` with a specific expected string from the assertion. This:
+- Documents the bug exists
+- Causes the test to fail (alerting you) once the bug is fixed
+- Reminds you to convert it to a proper passing test
+
+## Common Failure Patterns
+
+- **"Reference value loaded before it was first stored to"**: An optimization pass incorrectly removed a `store` instruction, leaving a reference uninitialized
+- **Different return values**: An optimization changed program semantics
+- **Panic/crash**: Invalid SSA was generated
+
+## Common Pitfalls
+
+- **Do not pipe `tee` through `head`**: Running `| tee file.txt | head -50` truncates the file. Always let `tee` complete, then inspect the file separately.
+- **Noir package names must use underscores**: Use `nargo new my_package`, not `my-package`.
+- **SSA parameters are positional**: The first parameter becomes `v0`, second `v1`, etc. Map your `Prover.toml` inputs accordingly.
+
+## Other noir-ssa Commands
+
+```bash
+# List available SSA passes
+noir-ssa list
+
+# Parse and validate SSA (prints normalized form)
+noir-ssa check --source-path file.ssa
+
+# Transform SSA by applying passes
+noir-ssa transform --source-path file.ssa --passes "Mem2Reg,Simplifying"
+```

.claude/skills/bisect-ssa-pass/scripts/bisect-ssa.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Bisect SSA passes to find where a failure is introduced.
+# Usage: bisect-ssa.sh <input_toml> [ssa_dir] [noir_ssa_binary]
+#
+# Example: bisect-ssa.sh 'v0 = "-92"'
+#          bisect-ssa.sh 'v0 = "42"; v1 = "100"' ssa_passes /path/to/noir-ssa
+
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+    echo "Usage: $0 <input_toml> [ssa_dir] [noir_ssa_binary]" >&2
+    echo "" >&2
+    echo "Arguments:" >&2
+    echo "  input_toml      Input values in TOML format (use ; for multiple lines)" >&2
+    echo "  ssa_dir         Directory containing .ssa files (default: ssa_passes)" >&2
+    echo "  noir_ssa_binary Path to noir-ssa binary (default: noir-ssa in PATH)" >&2
+    exit 1
+fi
+
+input_toml="$1"
+ssa_dir="${2:-ssa_passes}"
+noir_ssa="${3:-noir-ssa}"
+
+if [[ ! -d "$ssa_dir" ]]; then
+    echo "Error: Directory '$ssa_dir' not found" >&2
+    exit 1
+fi
+
+if ! command -v "$noir_ssa" &>/dev/null; then
+    echo "Error: noir-ssa binary not found at '$noir_ssa'" >&2
+    echo "Build it with: cargo build --release -p noir_ssa_cli" >&2
+    exit 1
+fi
+
+last_result=""
+first_failure=""
+
+for f in "$ssa_dir"/*.ssa; do
+    [[ -f "$f" ]] || continue
+
+    filename=$(basename "$f")
+
+    if result=$("$noir_ssa" interpret --source-path "$f" --input-toml "$input_toml" 2>&1); then
+        is_error=false
+    else
+        is_error=true
+    fi
+
+    output=$(echo "$result" | grep -E "^(Ok|Err)" | head -1)
+    echo "$filename: $output"
+
+    # Track first failure based on output starting with "Err"
+    if [[ "$output" == Err* && -z "$first_failure" ]]; then
+        first_failure="$filename"
+    fi
+
+    last_result="$output"
+done
+
+echo ""
+if [[ -n "$first_failure" ]]; then
+    echo "First failure: $first_failure"
+else
+    echo "All passes succeeded"
+fi

.claude/skills/bisect-ssa-pass/scripts/clean-ssa-files.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Clean SSA files by removing headers and diagnostics.
+# Usage: clean-ssa-files.sh [ssa_dir]
+#
+# Removes:
+#   - "After ..." header lines from all files
+#   - Compiler diagnostics (warnings/errors) from the final file
+
+set -euo pipefail
+
+ssa_dir="${1:-ssa_passes}"
+
+if [[ ! -d "$ssa_dir" ]]; then
+    echo "Error: Directory '$ssa_dir' not found" >&2
+    exit 1
+fi
+
+# Strip header lines from all files
+for f in "$ssa_dir"/*.ssa; do
+    [[ -f "$f" ]] || continue
+    tail -n +2 "$f" | sed '/^$/N;/^\n$/d' > "$f.tmp" && mv "$f.tmp" "$f"
+done
+echo "Stripped headers from all .ssa files"
+
+# Strip diagnostics from the final file
+last_file=$(ls "$ssa_dir"/*.ssa 2>/dev/null | tail -1)
+if [[ -n "$last_file" && -f "$last_file" ]]; then
+    awk '/^warning:|^error:/ {exit} {print}' "$last_file" > "$last_file.tmp" && mv "$last_file.tmp" "$last_file"
+    echo "Stripped diagnostics from $(basename "$last_file")"
+fi

.claude/skills/bisect-ssa-pass/scripts/split-ssa-passes.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Split SSA output into separate files, one per pass.
+# Usage: split-ssa-passes.sh <ssa_output_file> [output_dir]
+#
+# The output directory defaults to "ssa_passes".
+# Files are named with numeric prefixes to preserve pass order.
+
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+    echo "Usage: $0 <ssa_output_file> [output_dir]" >&2
+    exit 1
+fi
+
+input_file="$1"
+output_dir="${2:-ssa_passes}"
+
+mkdir -p "$output_dir"
+
+awk -v outdir="$output_dir" '
+BEGIN { file_num = 0; current_file = "" }
+/^After / {
+    if (current_file != "") close(current_file)
+    file_num++
+    pass_name = $0
+    gsub(/^After /, "", pass_name)
+    gsub(/:$/, "", pass_name)
+    gsub(/[^a-zA-Z0-9_() -]/, "", pass_name)
+    gsub(/ +/, "_", pass_name)
+    current_file = sprintf("%s/%02d_%s.ssa", outdir, file_num, pass_name)
+    print "Created: " current_file > "/dev/stderr"
+}
+{ if (current_file != "") print > current_file }
+' "$input_file"
+
+echo "Split into $output_dir/"