@vigolium/piolium 0.0.1

package/skills/zeroize-audit/references/compile-commands.md

@@ -0,0 +1,231 @@
+# Working with compile_commands.json
+
+This reference covers how to generate and use `compile_commands.json` for the zeroize-audit IR/ASM analysis pipeline. Read this before running Step 7 (IR comparison) or Step 8 (assembly analysis) in `task.md`.
+
+---
+
+## Structure
+
+`compile_commands.json` is a JSON array where each entry describes the exact compiler invocation for one translation unit (TU):
+
+```json
+[
+  {
+    "directory": "/path/to/project/build",
+    "arguments": [
+      "clang", "-std=c11", "-I../include", "-DNDEBUG", "-Wall",
+      "-c", "../src/crypto.c", "-o", "crypto.c.o"
+    ],
+    "file": "../src/crypto.c"
+  },
+  {
+    "directory": "/path/to/project/build",
+    "command": "clang++ -std=c++17 -I../include -DNDEBUG -c ../src/aead.cpp -o aead.cpp.o",
+    "file": "../src/aead.cpp"
+  }
+]
+```
+
+**`arguments` vs `command`**: Some tools produce an `arguments` array (preferred); others produce a `command` string. `extract_compile_flags.py` handles both forms transparently.
+
+**`directory`**: The working directory for the invocation. All relative paths in `arguments`/`command` and `file` are resolved against this field — **not** against the current working directory when running analysis. `extract_compile_flags.py` handles this automatically; manual invocations must account for it.
+
+---
+
+## Generating compile_commands.json
+
+### CMake (C/C++)
+
+```bash
+cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+# Output: build/compile_commands.json
+```
+
+**Constraints**: Works only with Makefile and Ninja generators. Does not work with Xcode or MSVC generators. Run from the project root and point `--compile-db` at `build/compile_commands.json`.
+
+### Bear (any Make-based build system)
+
+Bear intercepts compiler invocations at the OS level. Works with any `make`-based or custom build system:
+
+```bash
+# Install: apt install bear  OR  brew install bear
+bear -- make clean all    # clean build recommended for accuracy
+# Output: compile_commands.json in the current directory
+```
+
+Use `make clean all` rather than `make` alone to ensure all TUs are recompiled and captured. Incremental builds will only record the files that were actually recompiled.
+
+### intercept-build (LLVM scan-build companion)
+
+```bash
+intercept-build make
+# Output: compile_commands.json in the current directory
+```
+
+### Rust / Cargo
+
+Cargo does not natively emit `compile_commands.json`. Two options:
+
+```bash
+# Option 1: Bear with cargo check (faster — avoids linking)
+bear -- cargo check
+bear -- cargo build   # if cargo check is insufficient
+
+# Option 2: compiledb
+pip install compiledb
+compiledb cargo build
+```
+
+**Critical limitation for Rust**: Bear captures `rustc` invocations, not `clang` invocations. `emit_ir.sh` (which calls `clang`) **will not work** directly on Rust TUs. Use `cargo rustc` instead to emit IR and assembly directly:
+
+```bash
+# Preferred: use the emit scripts which handle CARGO_TARGET_DIR isolation:
+{baseDir}/tools/emit_rust_ir.sh --manifest Cargo.toml --opt O0 --out /tmp/crate.O0.ll
+{baseDir}/tools/emit_rust_ir.sh --manifest Cargo.toml --opt O2 --out /tmp/crate.O2.ll
+
+# Manual alternative (output goes to an isolated temp dir, not target/debug/deps):
+CARGO_TARGET_DIR=/tmp/zir cargo rustc -- --emit=llvm-ir -C opt-level=0
+CARGO_TARGET_DIR=/tmp/zir cargo rustc -- --emit=llvm-ir -C opt-level=2
+
+# Assembly for Rust (use instead of emit_asm.sh):
+cargo rustc -- --emit=asm -C opt-level=2
+# Output: target/release/deps/*.s
+```
+
+Pass the resulting `.ll` and `.s` files directly to `diff_ir.sh` and `analyze_asm.sh`.
+
+---
+
+## End-to-End Pipeline
+
+The canonical pipeline for C/C++ analysis. Always use a hash of the source path as `<tu_hash>` (not the raw filename) to avoid collisions during parallel TU processing. Clean up temp files on completion or failure.
+
+```bash
+mkdir -p /tmp/zeroize-audit/
+
+# Step 1: Extract build-relevant flags for the TU (as a bash array)
+FLAGS=()
+while IFS= read -r flag; do FLAGS+=("$flag"); done < <(
+  python {baseDir}/tools/extract_compile_flags.py \
+    --compile-db /path/to/build/compile_commands.json \
+    --src /path/to/src/crypto.c --format lines)
+
+# Step 2: Emit IR at each level in opt_levels (always include O0 as baseline)
+{baseDir}/tools/emit_ir.sh \
+  --src /path/to/src/crypto.c \
+  --out /tmp/zeroize-audit/<tu_hash>.O0.ll --opt O0 -- "${FLAGS[@]}"
+
+{baseDir}/tools/emit_ir.sh \
+  --src /path/to/src/crypto.c \
+  --out /tmp/zeroize-audit/<tu_hash>.O1.ll --opt O1 -- "${FLAGS[@]}"
+
+{baseDir}/tools/emit_ir.sh \
+  --src /path/to/src/crypto.c \
+  --out /tmp/zeroize-audit/<tu_hash>.O2.ll --opt O2 -- "${FLAGS[@]}"
+
+# Step 3: Diff across all levels — O1 is the diagnostic level for simple DSE;
+#         O2 catches more aggressive eliminations
+{baseDir}/tools/diff_ir.sh \
+  /tmp/zeroize-audit/<tu_hash>.O0.ll \
+  /tmp/zeroize-audit/<tu_hash>.O1.ll \
+  /tmp/zeroize-audit/<tu_hash>.O2.ll
+
+# Step 4: Emit assembly at O2 for register-spill and stack-retention analysis
+{baseDir}/tools/emit_asm.sh \
+  --src /path/to/src/crypto.c \
+  --out /tmp/zeroize-audit/<tu_hash>.O2.s --opt O2 -- "${FLAGS[@]}"
+
+# Step 5: Analyze assembly output
+{baseDir}/tools/analyze_asm.sh /tmp/zeroize-audit/<tu_hash>.O2.s
+
+# Cleanup
+rm -rf /tmp/zeroize-audit/<tu_hash>.*
+```
+
+Refer to the IR analysis reference (loaded separately from SKILL.md) for how to interpret IR diffs and identify wipe elimination patterns.
+
+---
+
+## Flags Stripped by extract_compile_flags.py
+
+These flags are removed because they are irrelevant to or break single-file IR/ASM emission:
+
+| Flag(s) | Reason stripped |
+|---|---|
+| `-o <file>` | Emission tools supply their own `-o` |
+| `-c` | IR/ASM emission uses `-S -emit-llvm` / `-S` instead |
+| `-MF`, `-MT`, `-MQ` (+ argument) | Dependency file generation — irrelevant for analysis |
+| `-MD`, `-MMD`, `-MP`, `-MG` | Dependency generation side-effects |
+| `-pipe` | OS pipe between compiler stages; not meaningful for direct calls |
+| `-save-temps` | Saves intermediate files; produces clutter |
+| `-gsplit-dwarf` | Splits debug info to `.dwo`; incompatible with single-file emission |
+| `-fcrash-diagnostics-dir=...` | Crash report output; irrelevant |
+| `-fmodule-file=...`, `-fmodules-cache-path=...` | Clang module paths; may confuse single-TU invocation |
+| `--serialize-diagnostics` | Clang diagnostic binary output; not needed |
+| `-fdebug-prefix-map=...` | Debug info path remapping; harmless to strip |
+| `-fprofile-generate`, `-fprofile-use=...` | PGO instrumentation; distorts IR for analysis |
+| `-fcoverage-mapping` | Coverage instrumentation; alters IR structure |
+
+Flags that are **kept** (build-relevant):
+
+| Pattern | Reason kept |
+|---|---|
+| `-I`, `-isystem`, `-iquote` | Include paths required to parse the TU |
+| `-D`, `-U` | Preprocessor defines/undefines that affect code paths |
+| `-std=<val>` | Language standard — affects syntax and semantics |
+| `-f*` security/codegen flags | e.g., `-fstack-protector`, `-fPIC`, `-fno-omit-frame-pointer` |
+| `-m<arch>` | Target architecture flags (e.g., `-m64`, `-march=x86-64`, `-mthumb`) |
+| `-W*` | Warning flags — harmless to pass through |
+| `-pthread` | Threading model; affects macro definitions |
+| `--sysroot=`, `-isysroot` | System root for cross-compilation |
+| `-target <triple>` | Cross-compilation target triple; must be preserved |
+
+---
+
+## Common Pitfalls
+
+### 1. Relative paths and the `"directory"` field
+
+`"file": "../src/crypto.c"` is relative to `"directory"`, not to the CWD when running analysis. Always resolve file paths using `"directory"`. `extract_compile_flags.py` does this automatically; be explicit if invoking `clang` manually.
+
+### 2. Multiple entries for the same file
+
+Some build systems emit duplicate entries (e.g., with and without a precompiled header). `extract_compile_flags.py` returns the **first** match. If that entry includes `-fpch-preprocess`, the PCH must exist in the build directory for compilation to succeed. Either regenerate the PCH or strip PCH-related flags manually.
+
+### 3. Stale or incomplete compile DB (most common failure)
+
+If `bear` or CMake was run on an incremental build, only recompiled TUs are recorded. TUs compiled in a previous run may be missing or have outdated flags. **Always generate the compile DB from a clean build** (`make clean all`, `cargo clean && cargo build`) to ensure all TUs are captured with current flags.
+
+`extract_compile_flags.py` exits with code 2 if a source file is not found in the DB. Common causes:
+- Header-only files (no TU entry — expected)
+- Files added after the last `bear`/CMake run
+- Symlinked paths that resolve differently than recorded
+
+Regenerate the compile DB if entries are missing.
+
+### 4. Generated source files
+
+Entries may point to generated files in the build directory (e.g., `build/generated/config.c`) that don't exist in a clean checkout. Run the build system to generate them before running analysis. Preflight (Step 1 in `task.md`) will catch this if trial compilation is attempted.
+
+### 5. Cross-compilation targets
+
+If the compile DB was generated for a cross-compilation target (e.g., `-target aarch64-linux-gnu` or `-target thumbv7m-none-eabi`), emitted IR and assembly will be for that target, not x86-64. This affects analysis in two ways:
+
+- **IR diffs**: Only compare IR files emitted for the same target. Do not mix targets across opt levels.
+- **Assembly analysis**: `analyze_asm.sh` adapts register patterns by target:
+  - x86-64: callee-saved registers are `rbx`, `r12`–`r15`; spills use `movq`/`movdqa` to `[rsp+N]`
+  - AArch64: callee-saved registers are `x19`–`x28`; spills use `str`/`stp` to `[sp, #N]`
+  - Thumb/ARM: callee-saved registers are `r4`–`r11`; spills use `str`/`stm` to `[sp, #N]`
+
+Ensure `--target` is preserved in the stripped flags (it is, per the kept-flags table above).
+
+### 6. `extract_compile_flags.py` exit codes
+
+| Exit code | Meaning |
+|---|---|
+| 0 | Flags extracted successfully; output on stdout |
+| 1 | Compile DB not found or not readable |
+| 2 | Source file not found in compile DB |
+| 3 | Compile DB is malformed JSON |
+
+Check the exit code before passing flags to emission tools. An empty `FLAGS` array will silently produce incorrect IR.

package/skills/zeroize-audit/references/detection-strategy.md

@@ -0,0 +1,191 @@
+# Detection Strategy
+
+Read this during execution to guide per-step analysis. Steps 1–6 are Phase 1 (source-level); Steps 7–12 are Phase 2 (compiler-level).
+
+---
+
+## Phase 1 — Source-Level Analysis
+
+### Step 1 — Preflight Build Context (mandatory)
+- Verify `compile_db` exists and is readable.
+- Verify compile database entries point to existing files/working directories.
+- Verify the codebase is compilable with the captured commands (or equivalent build invocation).
+- Fail fast if preflight fails; do not continue with partial/source-only analysis.
+
+### Step 2 — Identify Sensitive Objects
+
+Scan all TUs for objects matching these heuristics. Each heuristic has a confidence level that propagates to findings.
+
+**Name patterns (low confidence)** — match substrings case-insensitively:
+`key`, `secret`, `seed`, `priv`, `sk`, `shared_secret`, `nonce`, `token`, `pwd`, `pass`
+
+**Type hints (medium confidence)** — byte buffers, fixed-size arrays, or structs whose names or fields match name patterns above.
+
+**Explicit annotations (high confidence)**:
+- Rust: `#[secret]`, `Secret<T>` patterns (configurable)
+- C/C++: `__attribute__((annotate("sensitive")))`, `SENSITIVE` macro (configurable via `explicit_sensitive_markers` in `{baseDir}/configs/default.yaml`)
+
+Record each sensitive object with: name, type, location (file:line), confidence level, and the heuristic that matched.
+
+### Step 3 — Detect Zeroization Attempts
+
+For each sensitive object identified in Step 2, check whether a call to an approved wipe API (see Approved Wipe APIs in SKILL.md) exists within the same scope or a cleanup function reachable from that scope.
+
+Record: wipe API used, location, and whether the wipe was found at all.
+
+### Step 4 — MCP Semantic Pass (when available)
+
+Run this step **before** correctness validation so that resolved types, aliases, and cross-file references are available to Steps 5 and 6. Skip and continue if MCP is unavailable in `prefer` mode (see Confidence Gating in SKILL.md).
+
+- Run `{baseDir}/tools/mcp/check_mcp.sh` to confirm MCP is live. If it fails and `mcp_mode=require`, stop the run.
+- Activate the project with `activate_project` (pass the repository root path). This must succeed before any other Serena tool can be used. If activation fails, treat MCP as unavailable.
+- For each sensitive object and wipe call, resolve symbol definitions using `find_symbol` (by name, with `include_body: true` for type details) and collect cross-file references using `find_referencing_symbols`.
+- Trace callers and cleanup paths using `find_referencing_symbols` on wipe wrapper functions. For outgoing calls, read the function body from `find_symbol` output and resolve called symbols.
+- Use `get_symbols_overview` to get a high-level view of symbols in a file when exploring unfamiliar TUs.
+- Normalize all MCP output: `python {baseDir}/tools/mcp/normalize_mcp_evidence.py`.
+
+Prioritize `find_symbol` queries by sensitive-object name first, then wipe wrapper names. Score confidence: name match alone → `needs_review`; name + type resolved → `likely`; name + type + call chain confirmed → `confirmed`.
+
+### Step 5 — Validate Correctness
+
+For each sensitive object with a detected wipe, use type and alias data from Step 4 (if available) to validate:
+- **Size correct**: wipe length matches `sizeof(object)`, not `sizeof(pointer)`. MCP-resolved typedefs and array sizes take precedence over source-level estimates.
+- **All exits covered** (heuristic): wipe is present on normal exit, early return, and error paths visible in source. Flag `NOT_ON_ALL_PATHS` if any path appears uncovered.
+- **Ordering correct**: wipe occurs before `free()` or scope end, not after.
+
+Emit `PARTIAL_WIPE` for incorrect size. Emit `NOT_ON_ALL_PATHS` for missing paths (heuristic; CFG analysis in Step 10 provides definitive results).
+
+### Step 6 — Data-Flow and Heap Checks
+
+Use cross-file reference data from Step 4 (if available) to extend tracking beyond the current TU.
+
+**Data-flow (produces `SECRET_COPY`):**
+- Detect `memcpy()`/`memmove()` copying sensitive buffers.
+- Track struct assignments and array copies of sensitive objects.
+- Flag function arguments passed by value (copies on stack).
+- Flag secrets returned by value.
+- Emit `SECRET_COPY` when any of the above copies exist and no approved wipe is tracked for the copy destination.
+
+**Heap (produces `INSECURE_HEAP_ALLOC`):**
+- Detect `malloc`/`calloc`/`realloc` used to allocate sensitive objects.
+- Check for `mlock()`/`madvise(MADV_DONTDUMP)` — note absence as a warning.
+- Recommend secure allocators: `OPENSSL_secure_malloc`, `sodium_malloc`.
+
+---
+
+## Phase 2 — Compiler-Level Analysis
+
+All steps in Phase 2 require a valid compile DB and a working `clang` installation. Skip Phase 2 findings if Phase 1 preflight failed.
+
+### Step 7 — IR Comparison (produces `OPTIMIZED_AWAY_ZEROIZE`)
+
+For each TU containing sensitive objects:
+
+```bash
+FLAGS=()
+while IFS= read -r flag; do FLAGS+=("$flag"); done < <(
+  python {baseDir}/tools/extract_compile_flags.py \
+    --compile-db <compile_db> --src <file> --format lines)
+
+{baseDir}/tools/emit_ir.sh --src <file> \
+  --out /tmp/zeroize-audit/<tu_hash>.O0.ll --opt O0 -- "${FLAGS[@]}"
+
+{baseDir}/tools/emit_ir.sh --src <file> \
+  --out /tmp/zeroize-audit/<tu_hash>.O1.ll --opt O1 -- "${FLAGS[@]}"
+
+{baseDir}/tools/emit_ir.sh --src <file> \
+  --out /tmp/zeroize-audit/<tu_hash>.O2.ll --opt O2 -- "${FLAGS[@]}"
+
+{baseDir}/tools/diff_ir.sh \
+  /tmp/zeroize-audit/<tu_hash>.O0.ll \
+  /tmp/zeroize-audit/<tu_hash>.O1.ll \
+  /tmp/zeroize-audit/<tu_hash>.O2.ll
+```
+
+Use `<tu_hash>` (a hash of the source path) to avoid collisions when processing multiple TUs.
+`diff_ir.sh` outputs a unified diff to stdout; a non-zero exit code means divergence was detected.
+Clean up `/tmp/zeroize-audit/` on completion or failure.
+
+**Interpretation:**
+- Wipe present at O0, absent at O1 → simple dead-store elimination. Flag `OPTIMIZED_AWAY_ZEROIZE`.
+- Wipe present at O1, absent at O2 → aggressive optimization. Flag `OPTIMIZED_AWAY_ZEROIZE`.
+- Include the IR diff as mandatory evidence in the finding.
+
+Key IR patterns: `store volatile i8 0` is the primary wipe signal; its absence at O2 when present at O0 is DSE. `@llvm.memset` without the volatile flag is elidable. `alloca` with `@llvm.lifetime.end` and no `store volatile` in the same function indicates stack retention.
+
+### Step 8 — Assembly Analysis (produces `STACK_RETENTION`, `REGISTER_SPILL`)
+
+Skip if `enable_asm=false`.
+
+```bash
+{baseDir}/tools/emit_asm.sh --src <file> \
+  --out /tmp/zeroize-audit/<tu_hash>.O2.s --opt O2 -- "${FLAGS[@]}"
+
+{baseDir}/tools/analyze_asm.sh \
+  --asm /tmp/zeroize-audit/<tu_hash>.O2.s \
+  --out /tmp/zeroize-audit/<tu_hash>.asm-analysis.json
+```
+
+`analyze_asm.sh` outputs annotated findings to stdout.
+
+Check for:
+- **Register spills**: `movq`/`movdqa` of secret values to stack offsets → flag `REGISTER_SPILL`.
+- **Callee-saved registers**: `rbx`, `r12`–`r15` (x86-64) pushed to stack containing secret values → flag `REGISTER_SPILL`.
+- **Stack retention**: stack frame size and whether secret bytes are cleared before `ret` → flag `STACK_RETENTION`.
+
+Include the relevant assembly excerpt as mandatory evidence.
+
+### Step 9 — Semantic IR Analysis (produces `LOOP_UNROLLED_INCOMPLETE`)
+
+Skip if `enable_semantic_ir=false`.
+
+Parse LLVM IR structurally (do not use regex on raw IR text):
+- Build function and basic block representations.
+- Track memory operations in SSA form after the `mem2reg` pass.
+- Detect loop-unrolled zeroization: 4 or more consecutive zero stores.
+- Verify unrolled stores target the correct addresses and cover the full object size.
+- Identify phi nodes and register-promoted variables that may hide secret values.
+
+Flag `LOOP_UNROLLED_INCOMPLETE` when unrolling is detected but does not cover the full object.
+
+### Step 10 — Control-Flow Graph Analysis (produces `MISSING_ON_ERROR_PATH`, `NOT_DOMINATING_EXITS`)
+
+Skip if `enable_cfg=false`.
+
+Build a CFG from source or LLVM IR:
+- Enumerate all execution paths from function entry to exits.
+- Compute dominator sets for all nodes.
+- Verify that a wipe node dominates all exit nodes. If not, flag `NOT_DOMINATING_EXITS`.
+- Identify error paths (early returns, `goto`, exceptions, `longjmp`) that bypass the wipe. Flag `MISSING_ON_ERROR_PATH` for each such path.
+
+This step produces definitive results replacing the heuristic `NOT_ON_ALL_PATHS` finding from Step 5. If both are emitted for the same object, keep only the CFG-backed finding.
+
+### Step 11 — Runtime Validation Test Generation
+
+Skip if `enable_runtime_tests=false`.
+
+For each confirmed finding, generate:
+- A C test harness that allocates the sensitive object and verifies all bytes are zero after the expected wipe point.
+- A MemorySanitizer test (`-fsanitize=memory`) to detect reads of uninitialized or un-zeroed memory.
+- A Valgrind invocation target for leak and memory error detection.
+- A stack canary test to detect stack retention after function return.
+
+Output a `Makefile` in `{baseDir}/generated_tests/` that builds and runs all tests with appropriate sanitizer flags.
+
+### Step 12 — PoC Generation (mandatory)
+
+Generate proof-of-concept C programs for all findings regardless of confidence. Each PoC exits 0 (exploitable) or 1 (not exploitable):
+
+```bash
+python {baseDir}/tools/generate_poc.py \
+  --findings <findings_json> \
+  --compile-db <compile_db> \
+  --out <poc_output_dir> \
+  --categories <poc_categories> \
+  --config <config> \
+  --no-confidence-filter
+```
+
+After generation, review PoCs for `// TODO` comments and fill them in using source context. Compilation and validation are handled by the orchestrator in Phase 5 (interactive).
+
+Key PoC strategies: `OPTIMIZED_AWAY_ZEROIZE` — compile with and without `-O2`, compare memory dumps; `STACK_RETENTION` — call the target function, read stack memory after return; `MISSING_SOURCE_ZEROIZE` — verify bytes are non-zero at function exit. C/C++ findings support all categories. Rust findings support `MISSING_SOURCE_ZEROIZE`, `SECRET_COPY`, and `PARTIAL_WIPE` via `cargo test`; all other Rust categories are marked `poc_supported: false`.

package/skills/zeroize-audit/references/ir-analysis.md

@@ -0,0 +1,252 @@
+# LLVM IR Analysis for Zeroization Auditing
+
+This reference covers multi-level IR analysis for detecting compiler-optimized zeroization (dead-store elimination of wipes) and interpreting results. Read this during Step 7 (IR comparison) and Step 9 (semantic IR analysis) in `task.md`. For flag extraction and pipeline setup, refer to the compile-commands reference (loaded separately from SKILL.md).
+
+---
+
+## Optimization Level Semantics
+
+| Level | What changes | Relevance to zeroization |
+|---|---|---|
+| **O0** | No optimization. All stores kept. | Baseline — wipe always present if written in source |
+| **O1** | Basic optimizations. Simple dead-store elimination begins. | Diagnostic level: if wipe vanishes here, it's simple DSE. Fix is straightforward. |
+| **O2** | Full DSE, inlining, SROA, alias analysis. | Most production builds. Most non-volatile wipes removed here. |
+| **O3** | Aggressive vectorization, loop transforms, more inlining. | Rarely removes more wipes than O2, but can for loop-based wipes. |
+| **Os/Oz** | Size-optimized. May collapse wipe loops into `memset`. | Verify wipe survives after size optimization; collapsed `memset` may become DSE-vulnerable. |
+
+**Always include O0 as the unoptimized baseline**, regardless of the `opt_levels` input. O1 is the diagnostic level — if the wipe disappears there, the cause is simple DSE and the fix is straightforward. If the wipe only disappears at O2 or O3, proceed to the multi-level root cause analysis below.
+
+---
+
+## Emitting IR at Multiple Levels
+
+Extract flags once, then emit IR for each level in `opt_levels`. Use `<tu_hash>` (a hash of the source path) to avoid collisions during parallel TU processing. Always clean up temp files on completion or failure.
+
+```bash
+mkdir -p /tmp/zeroize-audit/
+
+FLAGS=()
+while IFS= read -r flag; do FLAGS+=("$flag"); done < <(
+  python {baseDir}/tools/extract_compile_flags.py \
+    --compile-db build/compile_commands.json \
+    --src src/crypto.c --format lines)
+
+# Emit IR for each level in opt_levels (O0 always included as baseline)
+for OPT in O0 O1 O2; do
+  {baseDir}/tools/emit_ir.sh \
+    --src src/crypto.c \
+    --out /tmp/zeroize-audit/<tu_hash>.${OPT}.ll \
+    --opt ${OPT} -- "${FLAGS[@]}"
+done
+
+# Diff all levels — prints pairwise diffs and a WIPE PATTERN SUMMARY
+{baseDir}/tools/diff_ir.sh \
+  /tmp/zeroize-audit/<tu_hash>.O0.ll \
+  /tmp/zeroize-audit/<tu_hash>.O1.ll \
+  /tmp/zeroize-audit/<tu_hash>.O2.ll
+
+# Cleanup
+rm -f /tmp/zeroize-audit/<tu_hash>.*.ll
+```
+
+For Rust TUs, `emit_ir.sh` does not apply. Use `cargo rustc -- --emit=llvm-ir -C opt-level=N` instead and pass the resulting `.ll` files directly to `diff_ir.sh`. Use `bear -- cargo build` to generate `compile_commands.json` for Rust projects.
+
+---
+
+## LLVM IR Zeroization Patterns
+
+### DSE-safe patterns (survive optimization)
+
+These indicate a secure wipe the compiler cannot remove.
+
+**Volatile memset intrinsic** — the `i1 true` (volatile) flag prevents DSE:
+```llvm
+call void @llvm.memset.p0i8.i64(i8* volatile %ptr, i8 0, i64 32, i1 true)
+```
+
+**Volatile zero stores** — volatile side effects must be preserved:
+```llvm
+store volatile i8 0, i8* %ptr, align 1
+store volatile i64 0, i64* %ptr, align 8
+```
+
+**Opaque wipe function calls** — DSE cannot remove calls to external functions with unknown side effects:
+```llvm
+call void @explicit_bzero(i8* %key, i64 32)
+call void @sodium_memzero(i8* %key, i64 32)
+call void @OPENSSL_cleanse(i8* %key, i64 32)
+call void @SecureZeroMemory(i8* %key, i64 32)
+```
+
+**`memset_s`** — defined by C11 to be non-optimizable:
+```llvm
+call i32 @memset_s(i8* %key, i64 32, i32 0, i64 32)
+```
+
+**Rust `zeroize` crate** — emits volatile stores via the `Zeroize` trait; look for:
+```llvm
+store volatile i8 0, i8* %ptr, align 1   ; repeated per byte, or as unrolled loop
+```
+
+---
+
+### DSE-vulnerable patterns (may be removed at O1 or O2)
+
+**Non-volatile memset intrinsic** — `i1 false` is the most common `OPTIMIZED_AWAY_ZEROIZE` pattern:
+```llvm
+call void @llvm.memset.p0i8.i64(i8* %ptr, i8 0, i64 32, i1 false)
+```
+
+**Non-volatile zero stores** — any non-volatile store to a dead location is DSE-eligible:
+```llvm
+store i8 0, i8* %ptr, align 1
+store i64 0, i64* %ptr, align 8
+store i32 0, i32* %ptr, align 4
+```
+
+**Standard `memset` inlined to non-volatile intrinsic** — `memset(key, 0, 32)` in source is lowered by Clang to `@llvm.memset ... i1 false`. The source used `memset` but the IR form is DSE-vulnerable. This is the most frequent source of confusion.
+
+---
+
+## Reading an IR Diff: Concrete Before/After Example
+
+**Source (C):**
+```c
+void handle_request(uint8_t session_key[32]) {
+    // ... use session_key ...
+    memset(session_key, 0, 32);  // intended cleanup
+}
+```
+
+**O0 IR — wipe present:**
+```llvm
+define void @handle_request(i8* %session_key) {
+entry:
+  ; ... computation uses session_key ...
+  call void @llvm.memset.p0i8.i64(i8* %session_key, i8 0, i64 32, i1 false)
+  ret void
+}
+```
+
+**O2 IR — wipe removed by DSE:**
+```llvm
+define void @handle_request(i8* %session_key) {
+entry:
+  ; ... computation ...
+  ; llvm.memset REMOVED — no read from session_key after the store;
+  ; optimizer treats it as a dead store and eliminates it.
+  ret void
+}
+```
+
+**`diff_ir.sh` output:**
+```
+=== DIFF: O0.ll vs O2.ll ===
+-  call void @llvm.memset.p0i8.i64(i8* %session_key, i8 0, i64 32, i1 false)
+
+=== WIPE PATTERN SUMMARY ===
+O0.ll: WIPE PRESENT
+O1.ll: WIPE PRESENT
+O2.ll: WIPE ABSENT  <-- first disappearance
+```
+
+Lines starting with `-` are present in the lower-opt file but absent in the higher-opt file. A `-` line containing any of the following tokens is direct evidence of `OPTIMIZED_AWAY_ZEROIZE`:
+
+`llvm.memset`, `store i8 0`, `store i64 0`, `store i32 0`, `@explicit_bzero`, `@sodium_memzero`, `@OPENSSL_cleanse`, `@SecureZeroMemory`
+
+---
+
+## Multi-Level Root Cause Analysis
+
+The level at which the wipe first disappears narrows the root cause and determines the appropriate fix:
+
+```
+O0 → WIPE PRESENT   (baseline — wipe was written in source)
+O1 → WIPE ABSENT    → Simple dead-store elimination (basic DSE pass)
+                       Fix: replace memset with explicit_bzero or volatile wipe loop
+O2 → WIPE ABSENT    → One or more of:
+(first disappearance)    • DSE + inlining: wipe is in a helper inlined into caller,
+                           becomes dead store in caller's context
+                         • SROA: struct/array promoted to scalars; individual
+                           zero stores become DSE-eligible
+                         • Alias analysis: proves no live uses after the wipe
+                       Fix: use explicit_bzero; ensure wipe is not inside
+                       an inlined callee (see Inlining section below)
+O3 → WIPE ABSENT    → Aggressive loop transforms or vectorization eliminated
+(only here)            a loop-based wipe
+                       Fix: replace wipe loop with explicit_bzero or volatile loop
+```
+
+If the wipe disappears at O1, a simple `explicit_bzero` or `volatile` qualifier is sufficient. If it only disappears at O2 due to inlining, also ensure the wipe is not inside a callee that gets inlined at the call site.
+
+---
+
+## Advanced IR Analysis Scenarios
+
+### Inlining and cross-function DSE
+
+When a cleanup wrapper (e.g., `zeroize_key()`) is inlined into a caller, the wipe may become a dead store in the caller's context even if it survives in the callee's IR. Always emit IR for the **calling** TU — this is where inlining occurs:
+
+```bash
+# zeroize_key() defined in utils.c, called from crypto.c
+# Emit IR for the caller — inlining happens here:
+FLAGS=()
+while IFS= read -r flag; do FLAGS+=("$flag"); done < <(
+  python {baseDir}/tools/extract_compile_flags.py \
+    --compile-db build/compile_commands.json --src src/crypto.c --format lines)
+
+{baseDir}/tools/emit_ir.sh \
+  --src src/crypto.c \
+  --out /tmp/zeroize-audit/<tu_hash>.O2.ll --opt O2 -- "${FLAGS[@]}"
+```
+
+If the wipe is present in `utils.c` IR but absent in `crypto.c` IR at O2, the cause is cross-function DSE after inlining. Mark the `OPTIMIZED_AWAY_ZEROIZE` finding on the call site in `crypto.c`, not on `utils.c`.
+
+### SROA (Scalar Replacement of Aggregates)
+
+At O1+, SROA promotes small structs and arrays to individual scalar SSA values (registers). A `memset` of a struct may become a series of individual `store i32 0` / `store i8 0` instructions per field — each then eligible for DSE independently. In the diff, look for:
+- O0: single `llvm.memset` covering the struct
+- O1/O2: the `memset` is replaced by per-field zero stores, then those stores are removed
+
+This means the wipe may partially survive SROA (some fields zeroed, others eliminated). Check that **all** fields of a sensitive struct are covered, not just the first.
+
+### Loop unrolling of wipe loops
+
+A manual wipe loop:
+```c
+for (int i = 0; i < 32; i++) key[i] = 0;
+```
+may be unrolled at O2 into 32 consecutive `store i8 0` instructions. If unrolling is incomplete (e.g., only 16 of 32 iterations unrolled and the remainder is a DSE-eligible tail), flag `LOOP_UNROLLED_INCOMPLETE`. Use `{baseDir}/tools/analyze_ir_semantic.py` for automated detection — do not use regex on raw IR text. The semantic tool builds a proper basic block representation and counts consecutive zero stores with address verification.
+
+### Phi nodes and register-promoted secrets
+
+After `mem2reg`, secret values that were stack-allocated may be promoted to SSA values tracked through phi nodes. A wipe of the original stack slot may not reach all SSA uses. Look for:
+```llvm
+%key.0 = phi i64 [ %loaded_key, %entry ], [ 0, %cleanup ]
+```
+If `%key.0` is used after the phi but the `0` arm is only reached on one path, the secret may persist in the non-zero arm. Flag as `NOT_DOMINATING_EXITS` if CFG analysis confirms it.
+
+---
+
+## Populating `compiler_evidence` in the Report
+
+For each `OPTIMIZED_AWAY_ZEROIZE` finding, populate the output schema fields as follows. `OPTIMIZED_AWAY_ZEROIZE` is **never valid without IR diff evidence** — do not emit this finding from source-level analysis alone.
+
+```json
+{
+  "category": "OPTIMIZED_AWAY_ZEROIZE",
+  "compiler_evidence": {
+    "opt_levels": ["O0", "O1", "O2"],
+    "o0": "call void @llvm.memset.p0i8.i64(i8* %session_key, i8 0, i64 32, i1 false) present at line 88.",
+    "o1": "WIPE PRESENT at O1.",
+    "o2": "llvm.memset call absent at O2 — dead store eliminated after SROA promotes session_key to registers.",
+    "diff_summary": "Wipe first disappears at O2. Non-volatile memset(session_key, 0, 32) eliminated by DSE after SROA. Fix: replace memset with explicit_bzero."
+  }
+}
+```
+
+Field usage notes:
+- `opt_levels`: list every level that was emitted, not just the levels where the wipe changed.
+- `o0` through `o2` (and `o1`, `o3` if analyzed): state explicitly whether the wipe is PRESENT or ABSENT at each level, with a short IR excerpt if present.
+- If the wipe only disappears at O3 but is present at O2: set `o2` to `"WIPE PRESENT at O2"` and document the O3 removal in `diff_summary`.
+- `diff_summary`: always identify the first disappearance level and the most likely optimization pass responsible (DSE, inlining, SROA, alias analysis, loop transform).