100%

Section 02: Enhance diagnose-aot.sh

Status: Complete Goal: Make diagnose-aot.sh the definitive single-command AOT diagnostic — currently it misses codegen-audit, ARC IR, release builds, and ARC verification. After this section, running diagnose-aot.sh --both-builds --valgrind file.ori exercises every diagnostic layer available.

Success Criteria:

  • Codegen-audit runs as section 6 of the 9-section diagnostic battery
  • ARC IR dump runs as a section, saving ARC IR alongside LLVM IR
  • --release flag builds/runs against release binary
  • --both-builds runs the FULL battery twice (debug + release) and highlights divergences
  • ORI_VERIFY_ARC=1 is enabled during compilation by default
  • Satisfies mission criterion: “diagnose-aot.sh runs codegen-audit, dumps ARC IR, supports —release and —both-builds”

Context: diagnose-aot.sh is documented as the “first tool to reach for on any AOT bug” (README.md line 11). But it never runs codegen-audit.sh, never dumps ARC IR (even though arc-dump.sh exists), never checks release builds (where FastISel bugs live), and never enables ORI_VERIFY_ARC. This means the “first tool” misses 3 of the 5 most common AOT failure modes.

Depends on: None.

02.1 Add codegen-audit and ARC IR sections

File(s): diagnostics/diagnose-aot.sh

Add two new sections to the 7-section diagnostic battery, making it 9 sections (numbered sequentially 1-9).

  • Add Section 6: Codegen Audit after LLVM IR (Section 5):

    • Run codegen-audit.sh --no-color "$FILE" (or --color based on color mode)
    • Capture exit code and output
    • Map: exit 0 = PASS (no findings), exit 1 = WARN (findings detected), exit 2 = FAIL (compilation or infrastructure failure — surface the error, do not skip)
    • Display findings inline

  • Add Section 7: ARC IR after Codegen Audit:

    • Run arc-dump.sh --raw "$FILE" to capture ARC IR
    • Save to $tmpdir/arc-${basename_file%.ori}.txt
    • Report line count (INFO status, same pattern as LLVM IR section)

  • Renumber existing Section 6 (Valgrind) → Section 8 and Section 7 (Disassembly) → Section 9 (sequential numbering, no gaps)

  • Update all [N/M] labels from [N/7] to [N/9] to reflect new total (9 sections)

  • Update section_names array in the summary block to include new sections and new numbering

  • Enable ORI_VERIFY_ARC=1 during the compilation step (Section 1) to catch ARC IR verification failures

  • Verify: diagnostics/diagnose-aot.sh diagnostics/fixtures/simple.ori shows all sections including new ones

  • Subsection close-out (02.1) — MANDATORY before starting 02.2:

    • All tasks above are [x] and verified
    • Update this subsection’s status in section frontmatter to complete
    • Run /improve-tooling retrospectively on THIS subsection

02.2 Add release build and ORI_VERIFY_ARC support

File(s): diagnostics/diagnose-aot.sh, diagnostics/_common.sh

  • Add --release flag: uses target/release/ori instead of target/debug/ori

    • Check that the release binary exists; if not, suggest cargo b --release

  • Add --both-builds flag: runs the FULL diagnostic battery twice (debug then release)

    • Print a clear separator between debug and release runs
    • On completion, highlight any sections where debug and release produced different results (different exit codes, different leak counts, different RC balance)
    • Exit code: 0 if both clean, 1 if either has failure

  • Use find_ori_bin_profile() and require_both_builds() from _common.sh (added by Section 01.2) for --release and --both-builds binary resolution — no new binary-discovery logic needed here

  • Update diagnostics/self-test.sh with tests for --release flag (at minimum: --help output includes --release)

  • Verify: diagnostics/diagnose-aot.sh --both-builds diagnostics/fixtures/clean.ori runs both builds and shows comparison

  • Subsection close-out (02.2) — MANDATORY before starting 02.R:

    • All tasks above are [x] and verified
    • Update this subsection’s status in section frontmatter to complete
    • Run /improve-tooling retrospectively on THIS subsection

02.R Third Party Review Findings

  • [TPR-02-001-codex][high] diagnostics/diagnose-aot.sh:303 — Propagate the selected build profile into helper diagnostics. Resolved: Fixed on 2026-04-09. Added export ORI_BIN="$ORI" after binary resolution so all helper scripts use the same binary.
  • [TPR-02-001-gemini][high] diagnostics/diagnose-aot.sh:176 — Export ORI_BIN to sub-scripts to ensure binary consistency. Resolved: Fixed on 2026-04-09. Same root cause as [TPR-02-001-codex] — export ORI_BIN="$ORI" added.
  • [TPR-02-002-codex][medium] diagnostics/diagnose-aot.sh:155 — Compare section results instead of only top-level exit codes. Resolved: Fixed on 2026-04-09. Added per-section structured results file via _DIAGNOSE_AOT_RESULTS env var; —both-builds now compares section-by-section.
  • [TPR-02-003-codex][medium] diagnostics/self-test.sh:245 — Add regression tests that pin the new release-path behavior. Resolved: Fixed on 2026-04-09. Added tests for (release) header presence and COMPARISON block in —both-builds output.
  • [TPR-02-002-gemini][high] diagnostics/diagnose-aot.sh:354 — Propagate failures from Codegen Audit errors to overall battery status. Resolved: Fixed on 2026-04-09. Codegen-audit exit=1 now checks for “error:” in output — errors set has_failure=1, warnings-only remain WARN.
  • [TPR-02-003-gemini][medium] diagnostics/diagnose-aot.sh:135 — Pass all arguments through to recursive —both-builds calls. Resolved: Fixed on 2026-04-09. Reconstructed passthrough flags from parsed state instead of whitelist.
  • [TPR-02-004-gemini][low] diagnostics/self-test.sh:143 — grep -qF — fix for pattern parsing. Resolved: Already included in the reviewed commit. No additional action needed.

02.N Completion Checklist

  • All subsections (02.1, 02.2) complete
  • diagnostics/self-test.sh passes (37/37)
  • diagnose-aot.sh --help shows new options
  • timeout 150 ./test-all.sh green — no regressions (16,927 passed)
  • /tpr-review passed — 3 iterations: 7 findings fixed (iter 1), 3 compiler fixes (iter 2), 3 doc fixes (iter 3)
  • /impl-hygiene-review passed — shell scripts + small macro change, no compiler hygiene issues
  • /improve-tooling section-close sweep — this section IS tooling improvement; retrospective: grep -qF fix in self-test, release phase dump enablement in compiler