100%

Section 08: Sanitizer Integration

Status: Not Started Goal: Integrate ASan (AddressSanitizer) and UBSan (UndefinedBehaviorSanitizer) into AOT-compiled Ori binaries. Sanitizers instrument GENERATED code (the AOT binaries Ori produces) AND the runtime library (ori_rt), not the compiler itself. This catches memory errors (use-after-free, buffer overflow, double-free, stack overflow) and undefined behavior (signed overflow, null pointer dereference, misaligned access) in both the code the compiler emits and the runtime library that manages RC operations, allocations, and container operations.

Success Criteria:

  • ORI_SANITIZE=address,undefined activates sanitizer instrumentation on generated code — satisfies mission criterion: “Sanitizer integration”
  • ori_rt is ASan-instrumented when ORI_SANITIZE includes address — satisfies mission criterion: “Sanitizer integration catches RC memory bugs”
  • Linker invocation includes -fsanitize=... flags via LinkInput — satisfies mission criterion: “Sanitizer integration”
  • SanitizerMode in OptimizationConfig — satisfies mission criterion: “Sanitizer integration”
  • Smoke subset <=60s for PR CI in dedicated workflow — satisfies mission criterion: “Sanitizer integration”
  • Full nightly sweep in new nightly-verification.yml — satisfies mission criterion: “Sanitizer integration”
  • At least one semantic pin detects a memory error silent without sanitizers — satisfies mission criterion: “Sanitizer integration”
  • At least one negative pin confirms clean code does not false-positive — satisfies mission criterion: “Sanitizer integration”

Context: The Ori compiler emits LLVM IR that is then compiled to native code. Memory bugs in the GENERATED code include: RC operations on freed memory, use-after-free when drop ordering is wrong, buffer overflows in list operations, undefined behavior in integer operations. These bugs are invisible to the Ori type system (which trusts the compiler), invisible to the AIMS verifiers (which check IR structure, not runtime behavior), and often invisible to behavioral tests (which may not exercise the failing path).

CRITICAL: ori_rt coverage is essential. Without ASan-instrumented ori_rt, most memory errors are invisible to the sanitizer. ori_rt contains ori_rc_inc/ori_rc_dec (RC ops), ori_alloc/ori_free (allocation), and all string/list/map/set buffer management. If only Ori-generated LLVM IR is sanitized but ori_rt is not, memory bugs in RC and container code remain silent. This is the PRIMARY goal of sanitizer integration — catching RC memory bugs — and it FAILS without instrumented ori_rt.

CRITICAL: LLVM 21 C API has NO sanitizer pass configuration. llvm-sys = "211.0.1" (LLVM 21) does not expose LLVMPassBuilderOptionsSetSanitizeAddress() or any sanitizer-specific function in the C API. Appending asan-module or ubsan to the pipeline string passed to LLVMRunPasses is undocumented and likely broken for LLVM 21. The validated approach is to use Clang as the compilation driver: emit LLVM IR or bitcode from Ori’s codegen, then invoke clang with -fsanitize=address,undefined to compile it to a sanitized object file. This is how Rust (-Zsanitizer=address) works — it delegates to LLVM’s pass builder via the C++ API, but since we only have the C API, Clang delegation is the correct portable approach.

CI strategy (Codex+Gemini consensus): Sanitizers significantly increase runtime (2-10x for ASan, 1.5-3x for UBSan). Running the full test suite with sanitizers would blow the 150-second timeout. Solution: separate CI job. Smoke subset on PRs (fast, catches obvious regressions), full sweep nightly (thorough, catches subtle issues). The smoke subset selects <=20 programs that exercise the highest-risk codegen paths: RC, COW, closures, iterators, collections. Nightly goes in a NEW nightly-verification.yml workflow (existing nightly.yml is release automation — dev-to-master PRs — and must not be modified).

Reference implementations:

  • Rust -Zsanitizer=address: recompiles std with sanitizer flags (nightly only), delegates to LLVM via C++ PassBuilder::registerPipelineStartEPCallback. The C API does not expose this — Rust uses custom C++ shim code.
  • Clang -fsanitize=address,undefined: Clang adds sanitizer passes via its own C++ PassBuilder integration. When used as a compiler driver on LLVM IR/bitcode, it adds the passes transparently.

Depends on: Section 01 (verification gates define what “failure” means — sanitizer errors are blocking under verification mode).

08.0 Prerequisite: Linker Module Split

File(s): compiler/ori_llvm/src/aot/linker/mod.rs

Why: linker/mod.rs is 648 lines — 148 over the 500-line limit. Adding sanitizer support to the linker without splitting first would push it further over. The LinkerDetection struct and its methods (~250 lines, starting around line 390) are an independent concern from the core linker types and LinkerImpl dispatch.

  • Extract LinkerDetection and all its methods (detect, detect_for_target, is_available, is_available_for_target, is_cross_compiling, gcc_cross_compiler_name, cross_compilation_error, etc.) to a new compiler/ori_llvm/src/aot/linker/detect.rs

  • Update mod.rs to re-export: mod detect; pub use detect::LinkerDetection;

  • Verify linker/mod.rs is now under 500 lines

  • Verify linker/detect.rs is under 500 lines

  • timeout 150 cargo test -p ori_llvm green after split

  • timeout 150 ./clippy-all.sh green after split

  • Subsection close-out (08.0) — MANDATORY before starting 08.1:

    • All tasks above are [x]
    • Update this subsection’s status in section frontmatter to complete

08.1 SanitizerMode Type and Env Var Wiring

File(s): compiler/ori_llvm/src/aot/passes/config.rs, compiler/oric/src/debug_flags.rs, compiler/oric/src/commands/build/mod.rs

Add a SanitizerMode field to OptimizationConfig and wire it to the ORI_SANITIZE environment variable. The env var uses the existing dbg_set! pattern from debug_flags.rs but with a value-bearing variant (comma-separated list, not boolean).

Design decision — env var format: Use a single ORI_SANITIZE env var with comma-separated sanitizer names (e.g., ORI_SANITIZE=address,undefined). This matches Clang’s -fsanitize=address,undefined pattern. The individual-boolean pattern (ORI_SANITIZE_ADDRESS=1, ORI_SANITIZE_UNDEFINED=1) would match the existing debug_flags.rs pattern but diverges from the Clang convention that users will already know. Consistency with Clang is more valuable here because the sanitizer flags are ultimately passed through to Clang.

  • Define SanitizerMode in config.rs:

    /// Sanitizer instrumentation modes for generated code.
///
/// Controls which sanitizer passes are applied (via Clang delegation)
/// and which sanitizer runtime libraries are linked.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct SanitizerMode {
    /// AddressSanitizer: use-after-free, buffer overflow, stack overflow.
    pub address: bool,
    /// UndefinedBehaviorSanitizer: signed overflow, null deref, misaligned access.
    pub undefined: bool,
}

impl SanitizerMode {
    /// No sanitizers (default).
    pub const NONE: Self = Self {
        address: false,
        undefined: false,
    };

    /// Parse from ORI_SANITIZE env var value.
    /// Format: comma-separated list of "address", "undefined".
    /// Example: "address,undefined" or "address" or "undefined".
    pub fn from_env_value(value: &str) -> Self {
        let mut mode = Self::NONE;
        for part in value.split(',') {
            match part.trim() {
                "address" => mode.address = true,
                "undefined" => mode.undefined = true,
                other => {
                    tracing::warn!(
                        sanitizer = other,
                        "unknown sanitizer in ORI_SANITIZE, ignoring"
                    );
                }
            }
        }
        mode
    }

    /// Whether any sanitizer is enabled.
    pub fn any_enabled(&self) -> bool {
        self.address || self.undefined
    }

    /// Return the Clang-compatible `-fsanitize=...` flag value.
    /// Returns `None` if no sanitizers are enabled.
    pub fn clang_flag_value(&self) -> Option<String> {
        let mut parts = Vec::new();
        if self.address {
            parts.push("address");
        }
        if self.undefined {
            parts.push("undefined");
        }
        if parts.is_empty() {
            None
        } else {
            Some(parts.join(","))
        }
    }
}

  • Add sanitizer: SanitizerMode field to OptimizationConfig:

    pub struct OptimizationConfig {
    // ... existing fields ...
    /// Sanitizer instrumentation for generated code.
    /// When enabled, the AOT pipeline delegates to Clang for sanitizer pass insertion.
    pub sanitizer: SanitizerMode,
}

    Add a builder method: .with_sanitizer(mode: SanitizerMode) -> Self. Update OptimizationConfig::new() to initialize sanitizer: SanitizerMode::NONE. Update Default for OptimizationConfig to include sanitizer: SanitizerMode::NONE.

  • Register ORI_SANITIZE in debug_flags.rs:

    /// Enable sanitizer instrumentation on generated AOT binaries.
///
/// Value: comma-separated sanitizer names (address, undefined).
/// Example: `ORI_SANITIZE=address,undefined ori build file.ori`
///
/// Requires Clang on PATH (used as compilation driver for sanitizer passes).
/// For full coverage, also recompiles ori_rt with sanitizer flags (nightly Rust).
/// Significant performance impact (2-10x slower). Not for main test suite.
ORI_SANITIZE

  • Wire ORI_SANITIZE through build_optimization_config in oric/src/commands/build/mod.rs. NOTE: This is the SINGLE canonical location for reading ORI_SANITIZE — the function is called by both single.rs and multi.rs. ALSO: Verify that oric/src/commands/run/mod.rs (the ori run AOT path) also flows through this canonical config — if it builds its own OptimizationConfig, it must read ORI_SANITIZE via the same shared helper:

    fn build_optimization_config(options: &BuildOptions) -> ori_llvm::aot::OptimizationConfig {
    // ... existing level, lto, verify_each, lint_enabled code ...

    let sanitizer = std::env::var("ORI_SANITIZE")
        .ok()
        .filter(|v| v != "0")
        .map(|v| SanitizerMode::from_env_value(&v))
        .unwrap_or(SanitizerMode::NONE);

    OptimizationConfig::new(level)
        .with_lto(lto)
        .with_verify_each(verify_each)
        .with_lint(lint_enabled)
        .with_sanitizer(sanitizer)
}

  • Add tests in config.rs’s sibling tests.rs (following the existing pattern):

    • sanitizer_mode_from_env_address_only — "address" -> address=true, undefined=false
    • sanitizer_mode_from_env_address_and_undefined — "address,undefined" -> both true
    • sanitizer_mode_from_env_undefined_only — "undefined" -> address=false, undefined=true
    • sanitizer_mode_from_env_empty_is_none — "" -> both false
    • sanitizer_mode_from_env_whitespace_tolerant — " address , undefined " -> both true
    • sanitizer_mode_from_env_unknown_ignored — "address,foo" -> address=true, undefined=false (warning logged)
    • sanitizer_mode_clang_flag_value_both — .clang_flag_value() returns Some("address,undefined")
    • sanitizer_mode_clang_flag_value_none — NONE.clang_flag_value() returns None
    • sanitizer_mode_any_enabled_true — address=true -> .any_enabled() true
    • sanitizer_mode_any_enabled_false — NONE -> .any_enabled() false
    • optimization_config_default_has_no_sanitizer — OptimizationConfig::default().sanitizer == SanitizerMode::NONE

  • Subsection close-out (08.1) — MANDATORY before starting 08.2:

    • All tasks above are [x] and the subsection’s behavior is verified
    • timeout 150 ./test-all.sh green (no regressions)
    • Update this subsection’s status in section frontmatter to complete
    • Run /improve-tooling retrospectively on THIS subsection
    • Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files. Verified clean 2026-04-13.

08.2 Clang-Delegated Sanitizer Pass Integration

File(s): compiler/ori_llvm/src/aot/passes/mod.rs, compiler/ori_llvm/src/aot/passes/sanitizer.rs (new)

Why Clang delegation instead of pipeline string manipulation: The LLVM 21 C API (llvm-sys = "211.0.1") does not expose any sanitizer-related PassBuilderOptions functions. There is no LLVMPassBuilderOptionsSetSanitizeAddress, no LLVMPassBuilderOptionsSetSanitizeUndefined, and no documented way to add sanitizer passes via the LLVMRunPasses pipeline string. The LLVM C++ API supports sanitizers via PassBuilder::registerPipelineStartEPCallback, but this is not available through the C API.

The validated approach: When sanitizers are enabled, instead of passing the module through LLVMRunPasses for sanitizer instrumentation, we:

  1. Run our normal optimization pipeline via LLVMRunPasses as usual (O0/O2/O3 etc.)
  2. Emit the optimized LLVM IR to a temporary .ll file
  3. Invoke clang on that .ll file with -fsanitize=address,undefined -c -o output.o to produce a sanitizer-instrumented object file
  4. The Clang invocation adds the sanitizer passes transparently and links the sanitizer runtime stubs

This is the same strategy used by Rust’s -Zsanitizer flag (which uses a C++ shim to access PassBuilder internals we cannot reach from the C API) — we just use Clang as the external driver instead of building our own C++ shim.

  • Create compiler/ori_llvm/src/aot/passes/sanitizer.rs with a clang_compile_with_sanitizers function:

    //! Clang-delegated sanitizer pass integration.
//!
//! The LLVM C API (llvm-sys 211.0.1) does not expose sanitizer pass
//! configuration. We delegate to Clang as a compilation driver, which
//! adds sanitizer instrumentation transparently.

use std::path::Path;
use std::process::Command;

use super::OptimizationError;
use super::config::SanitizerMode;

/// Compile LLVM IR to an object file with sanitizer instrumentation via Clang.
///
/// # Arguments
/// * `ir_path` - Path to the LLVM IR file (.ll)
/// * `output_path` - Path for the output object file (.o)
/// * `sanitizer` - Which sanitizers to enable
/// * `opt_level` - Optimization level string (e.g., "-O2")
///
/// # Errors
/// Returns `PassesFailed` if Clang is not found or compilation fails.
pub fn clang_compile_with_sanitizers(
    ir_path: &Path,
    output_path: &Path,
    sanitizer: &SanitizerMode,
    opt_level: &str,
    target_triple: &str,
) -> Result<(), OptimizationError> {
    let fsanitize_value = sanitizer.clang_flag_value()
        .expect("clang_compile_with_sanitizers called with no sanitizers enabled");

    let mut cmd = Command::new("clang");
    cmd.arg(ir_path)
        .arg("-c")
        .arg("-o").arg(output_path)
        .arg(format!("-fsanitize={fsanitize_value}"))
        .arg(format!("--target={target_triple}"))
        .arg(opt_level);

    let output = cmd.output().map_err(|e| {
        if e.kind() == std::io::ErrorKind::NotFound {
            OptimizationError::PassesFailed {
                message: "Clang not found on PATH. Clang is required for sanitizer \
                          instrumentation (ORI_SANITIZE). Install clang or disable \
                          sanitizers.".to_string(),
            }
        } else {
            OptimizationError::PassesFailed {
                message: format!("failed to run clang for sanitizer instrumentation: {e}"),
            }
        }
    })?;

    if !output.status.success() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        return Err(OptimizationError::PassesFailed {
            message: format!(
                "clang sanitizer compilation failed (exit {}): {}",
                output.status.code().unwrap_or(-1),
                stderr,
            ),
        });
    }

    Ok(())
}

/// Check that Clang is available on PATH.
///
/// Call this early when ORI_SANITIZE is set to fail fast with a clear error
/// before doing expensive compilation work.
pub fn check_clang_available() -> Result<(), OptimizationError> {
    match Command::new("clang").arg("--version").output() {
        Ok(output) if output.status.success() => Ok(()),
        Ok(_) => Err(OptimizationError::PassesFailed {
            message: "clang --version failed. Clang is required for sanitizer \
                      instrumentation (ORI_SANITIZE).".to_string(),
        }),
        Err(_) => Err(OptimizationError::PassesFailed {
            message: "Clang not found on PATH. Clang is required for sanitizer \
                      instrumentation (ORI_SANITIZE). Install clang or disable \
                      sanitizers.".to_string(),
        }),
    }
}

  • Add mod sanitizer; to passes/mod.rs and pub use sanitizer::{clang_compile_with_sanitizers, check_clang_available};

  • Hook the canonical emission layer (ObjectEmitter::verify_optimize_emit in compiler/ori_llvm/src/aot/object.rs and multi_emission.rs for multi-file/LTO) to use the Clang delegation path when sanitizers are enabled. Do NOT patch single.rs or multi.rs directly — that would put side logic in command handlers and miss the LTO merge path. The correct integration point is the object emission layer (SSOT for object production):

    • In ObjectEmitter::verify_optimize_emit(): after the normal LLVM optimization pipeline runs, if config.sanitizer.any_enabled():
      1. Emit LLVM IR to a temp file via module.print_to_file()
      2. Call clang_compile_with_sanitizers() to produce the object file
      3. Return the sanitized object path instead of calling the normal module.write_to_file()
    • In multi_emission.rs: apply the same sanitizer delegation for both non-LTO and LTO emission paths
    • If sanitizers are NOT enabled, the existing optimize_module() + emit_object() path is unchanged
    • Verify all three paths are covered: single-file, multi-file, and LTO merge

  • Add early Clang availability check: in the canonical emission entry point, if opt_config.sanitizer.any_enabled(), call check_clang_available() and fail fast with a clear error before doing expensive compilation work

  • Verify that ASan instrumentation is visible in the Clang-produced object file (not ORI_DUMP_AFTER_LLVM, which shows pre-Clang IR). After ORI_SANITIZE=address ori build test.ori -o /tmp/test_asan, run nm /tmp/test_asan | grep __asan to verify ASan symbols (__asan_load, __asan_store, __asan_report_*) are present in the linked binary

  • Add tests (AAA naming: <subject>_<scenario>_<expected>):

    • clang_available_check_succeeds_in_ci — verify check_clang_available() succeeds in test environment
    • sanitizer_mode_both_enabled_produces_combined_flag — verify SanitizerMode { address: true, undefined: true }.clang_flag_value() == Some("address,undefined")
    • clang_compile_with_sanitizers_produces_asan_symbols — compile a trivial program via clang_compile_with_sanitizers, verify the object contains __asan_ symbols (via nm)
    • optimization_pipeline_unchanged_when_sanitizers_disabled — verify the optimization path is identical when SanitizerMode::NONE

  • TPR checkpoint — /tpr-review covering 08.0-08.2 implementation work — deferred to section-close TPR (08.N) which covers full section

  • Subsection close-out (08.2) — MANDATORY before starting 08.3:

    • All tasks above are [x] and the subsection’s behavior is verified
    • timeout 150 ./test-all.sh green (sanitizers OFF)
    • Update this subsection’s status in section frontmatter to complete
    • Run /improve-tooling retrospectively on THIS subsection
    • Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files. Verified clean 2026-04-13.

08.3 Linker Integration via LinkInput and GccLinker

File(s): compiler/ori_llvm/src/aot/linker/mod.rs, compiler/ori_llvm/src/aot/linker/driver.rs, compiler/oric/src/commands/build/mod.rs

When sanitizers are enabled, the linker must link the sanitizer runtime libraries. The correct approach is to pass -fsanitize=address,undefined to the GCC/Clang linker driver. This is done via LinkInput.extra_args (the existing mechanism for additional linker flags), NOT by modifying the GccLinker API signature.

Actual API (verified):

  • LinkInput struct has extra_args: Vec<String> field
  • LinkerDriver::link(&self, input: &LinkInput) is the entry point
  • LinkerDriver::configure_linker(linker: &mut LinkerImpl, input: &LinkInput) iterates input.extra_args and calls linker.add_arg(arg) for each
  • GccLinker.add_arg(arg: &str) appends to the Command
  • link_and_finish() in build/mod.rs constructs LinkInput and passes it to driver.link()

Design: Add sanitizer: SanitizerMode as a typed field on LinkInput (not just string args) for type safety and discoverability. LinkerDriver::configure_linker reads it and adds the appropriate -fsanitize=... arg. This keeps the sanitizer intent typed rather than buried in opaque string args.

  • Add sanitizer: SanitizerMode field to LinkInput:

    /// Input configuration for the linker.
#[derive(Debug, Clone, Default)]
pub struct LinkInput {
    // ... existing fields ...
    /// Sanitizer mode. When enabled, adds `-fsanitize=...` to the linker command.
    pub sanitizer: SanitizerMode,
}

    Import SanitizerMode from crate::aot::passes::config::SanitizerMode (or re-export at the aot level).

  • Force Clang as the linker driver when sanitizers are enabled. When input.sanitizer.any_enabled(), override the linker to use GccLinker::with_path(target, "clang") instead of the default cc (which is typically GCC on Linux). GCC and Clang ship incompatible sanitizer runtime libraries — linking Clang-instrumented objects with GCC’s -fsanitize causes missing symbols or ABI mismatches. Add this check in LinkerDriver::configure_linker() or at driver instantiation time.

  • Modify LinkerDriver::configure_linker() in driver.rs to add sanitizer flags BEFORE extra_args (sanitizer flags must come before general args for some linkers):

    // Sanitizer runtime linkage
if let Some(fsanitize) = input.sanitizer.clang_flag_value() {
    linker.add_arg(&format!("-fsanitize={fsanitize}"));
}

// Add extra arguments (existing code, unchanged)
for arg in &input.extra_args {
    linker.add_arg(arg);
}

  • Thread SanitizerMode from OptimizationConfig to LinkInput in link_and_finish() (build/mod.rs). Add a sanitizer parameter to link_and_finish:

    fn link_and_finish(
    object_files: Vec<PathBuf>,
    output_path: &Path,
    target: &ori_llvm::aot::TargetConfig,
    options: &BuildOptions,
    sanitizer: &SanitizerMode,
    start: std::time::Instant,
) {
    // ...existing code...
    let mut link_input = LinkInput {
        objects: object_files,
        output: output_path.to_path_buf(),
        output_kind,
        sanitizer: sanitizer.clone(),
        // ... rest unchanged ...
    };
    // ...existing code...
}

    Update all call sites in single.rs and multi.rs to pass the sanitizer from opt_config.sanitizer.

  • Cover the ori run --compile path: run/mod.rs also builds and links AOT binaries when --compile is used. Verify it flows through the same canonical ObjectEmitter and link_and_finish() paths that receive sanitizer configuration. If run/mod.rs has its own build_optimization_config() call or link logic, wire ORI_SANITIZE through it.

  • When sanitizers are enabled and the linker is GCC-flavor on macOS: add a note that macOS requires Clang (not bare ld) and that -fsanitize is a Clang driver flag, not a raw linker flag. The existing GccLinker already uses clang on macOS, so this should work. Add a warning if MSVC or WASM linker is selected with sanitizers enabled (sanitizers are Linux/macOS only for now).

  • Verify that the linked binary actually runs with sanitizer runtime. Smoke test:

    ORI_SANITIZE=address ori build tests/spec/basic/hello.ori -o /tmp/hello_asan
/tmp/hello_asan  # Should print "hello" and exit 0

  • Document the system requirements: Clang must be installed (since we delegate sanitizer compilation to Clang). Clang ships its own sanitizer runtimes (compiler-rt). On Ubuntu/Debian: sudo apt-get install clang libclang-rt-dev. On macOS: included with Xcode Command Line Tools. Do NOT install GCC’s libasan8/libubsan1 — those are incompatible with Clang-instrumented code. Add a clear error message if the linker fails due to missing Clang sanitizer runtimes — detect the cannot find -lclang_rt.asan pattern in linker stderr and emit a diagnostic with install instructions.

  • Add tests:

    • link_input_default_has_no_sanitizer — LinkInput::default().sanitizer == SanitizerMode::NONE
    • configure_linker_adds_fsanitize_when_address_enabled — mock/spy on the LinkerImpl args; verify -fsanitize=address is present
    • configure_linker_adds_fsanitize_when_both_enabled — verify -fsanitize=address,undefined is present
    • configure_linker_no_fsanitize_when_disabled — verify no -fsanitize arg
    • sanitizer_flag_before_extra_args — verify ordering: -fsanitize=... appears before any extra_args entries

  • Subsection close-out (08.3) — MANDATORY before starting 08.4:

    • All tasks above are [x] and the subsection’s behavior is verified
    • timeout 150 ./test-all.sh green (sanitizers OFF)
    • Update this subsection’s status in section frontmatter to complete
    • Run /improve-tooling retrospectively on THIS subsection
    • Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files. Verified clean 2026-04-13.

08.4 ori_rt ASan Instrumentation

File(s): compiler/ori_rt/Cargo.toml, compiler/ori_rt/build.rs (if needed), compiler/oric/src/aot/runtime.rs (or wherever runtime discovery lives), scripts/build-rt-asan.sh (new)

Why this is mandatory: ori_rt is a Rust crate compiled to a static library (libori_rt.a) that gets linked into every AOT binary. It contains:

  • ori_rc_inc / ori_rc_dec — RC operations (the primary source of memory bugs)
  • ori_alloc / ori_free — memory allocation/deallocation
  • String, list, map, set buffer management code

If only Ori-generated LLVM IR is sanitized but ori_rt is compiled normally, then ASan cannot see memory operations inside ori_rt. A use-after-free inside ori_rc_dec would be invisible. The plan’s PRIMARY goal (“catching RC memory bugs”) FAILS without ASan-instrumented ori_rt.

Approach: When ORI_SANITIZE includes address, provide an ASan-instrumented variant of libori_rt.a. This requires nightly Rust (-Zsanitizer=address is unstable). Two options:

  1. Runtime recompilation (preferred): scripts/build-rt-asan.sh recompiles ori_rt with RUSTFLAGS="-Zsanitizer=address" using nightly Rust, producing libori_rt_asan.a alongside libori_rt.a. The build command detects ORI_SANITIZE and links the asan variant instead.
  2. Pre-built variant in CI: CI nightly job builds both variants and caches them.

  • Create scripts/build-rt-asan.sh:

    #!/usr/bin/env bash
# Build ori_rt with AddressSanitizer instrumentation.
# Requires nightly Rust toolchain.
#
# Output: target/debug/libori_rt_asan.a (or target/release/libori_rt_asan.a)
#
# Usage: ./scripts/build-rt-asan.sh [--release]

set -euo pipefail

PROFILE="debug"
PROFILE_DIR="debug"
if [[ "${1:-}" == "--release" ]]; then
    PROFILE="release"
    PROFILE_DIR="release"
fi

# Check for nightly
if ! rustup run nightly rustc --version &>/dev/null; then
    echo "ERROR: nightly Rust required for sanitizer-instrumented ori_rt"
    echo "Install with: rustup toolchain install nightly"
    exit 1
fi

# Detect host target triple
HOST_TARGET=$(rustc -vV | sed -n 's/^host: //p')

# ori_rt's build.rs compiles C/asm sources via cc::Build (ori_eh).
# Set CFLAGS BEFORE the cargo build to ensure those native objects are also ASan-instrumented.
export CFLAGS="-fsanitize=address"
echo "CFLAGS=-fsanitize=address (for C/asm sources in ori_rt build.rs / ori_eh)"

echo "Building ori_rt with ASan instrumentation (nightly, $PROFILE, target=$HOST_TARGET)..."
# -Zbuild-std ensures std itself is ASan-instrumented (Vec, String allocations)
# --target is required with -Zbuild-std
RUSTFLAGS="-Zsanitizer=address" \
    cargo +nightly build -p ori_rt \
    -Zbuild-std \
    --target "$HOST_TARGET" \
    $([ "$PROFILE" = "release" ] && echo "--release") \
    --target-dir target/sanitizer

# With -Zbuild-std + --target, output goes to target/sanitizer/<target-triple>/<profile>/
SRC="target/sanitizer/$HOST_TARGET/$PROFILE_DIR/libori_rt.a"
DEST="target/$PROFILE_DIR/libori_rt_asan.a"

if [ ! -f "$SRC" ]; then
    echo "ERROR: Expected $SRC not found"
    exit 1
fi

cp "$SRC" "$DEST"
echo "ASan-instrumented runtime: $DEST"

  • Modify the runtime discovery logic to look for libori_rt_asan.a when ORI_SANITIZE includes address. If the asan variant is NOT found, emit a hard error (not a warning):

    error: ORI_SANITIZE=address is set but libori_rt_asan.a was not found.
Without ASan-instrumented ori_rt, memory bugs in RC operations and containers
will NOT be detected — defeating the primary goal of sanitizer integration.
Run `./scripts/build-rt-asan.sh` to build the ASan-instrumented runtime.

    This MUST be a hard error, not a warning. The section’s mission statement explicitly says ori_rt coverage is essential and that the PRIMARY goal fails without it. A warning that allows partial coverage contradicts the success criteria and would let the section mark complete without actually achieving its stated goal. The fallback to ORI_SANITIZE=undefined (UBSan only, no ASan) does not require ori_rt re-instrumentation and works with the standard libori_rt.a.

  • Add a --sanitize-rt flag to the build script or detect automatically: if ORI_SANITIZE includes address AND nightly Rust is available, automatically run the rt rebuild as part of ori build. If nightly is NOT available, fail with a clear message about the nightly requirement.

  • Add tests (AAA naming: <subject>_<scenario>_<expected>):

    • build_rt_asan_script_with_nightly_produces_library — run the script and verify the output file exists (requires nightly; #[ignore] if nightly not available, with plan item for CI enforcement)
    • runtime_discovery_with_sanitize_address_prefers_asan_variant — mock the discovery to verify preference logic
    • runtime_discovery_missing_asan_variant_with_address_returns_hard_error — verify hard error (not warning) when ORI_SANITIZE=address but no libori_rt_asan.a

  • Subsection close-out (08.4) — MANDATORY before starting 08.5:

    • All tasks above are [x] and the subsection’s behavior is verified
    • timeout 150 ./test-all.sh green (sanitizers OFF)
    • Update this subsection’s status in section frontmatter to complete
    • Run /improve-tooling retrospectively on THIS subsection
    • Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files. Verified clean 2026-04-13.

08.5 Smoke Test Suite and CI Configuration

File(s): tests/sanitizer/ (new), scripts/sanitizer-smoke.sh (new), .github/workflows/nightly-verification.yml (new)

Create a curated smoke test subset for PR CI and configure full nightly runs. Do NOT modify .github/workflows/nightly.yml — it is release automation (dev-to-master PR creation).

Smoke Test Programs

  • Create tests/sanitizer/ directory with <=20 Ori programs exercising highest-risk codegen paths. Selection criteria: each program must exercise at least one memory-management code path that sanitizers can detect bugs in.

    Matrix coverage — program_type x memory_pattern:

    ProgramPrimary RiskMemory Pattern
    rc_basic.oriRC inc/dec balanceAllocation + use + drop
    rc_loop.oriRC in loop back-edgesRepeated inc/dec in loop body
    cow_mutation.oriCOW uniqueness checkShared -> unique -> mutate
    closure_capture.oriClosure environment RCCapture by value, env lifetime
    iterator_for_loop.oriIterator create/next/dropFull iteration lifecycle
    iterator_break.oriEarly iterator terminationPartial iteration + cleanup
    list_operations.oriList buffer managementPush, pop, index, slice
    map_operations.oriMap hash tableInsert, lookup, remove
    set_operations.oriSet operationsInsert, contains, remove
    string_concat.oriString RC and bufferConcat, interpolation, slice
    nested_struct_drop.oriNested struct dropsDeep struct with RC fields
    enum_variant_drop.oriSum type variant dropsVariant with RC payload
    option_some_none.oriOption RC handlingSome(rc_value), None paths
    result_ok_err.oriResult RC handlingOk(rc_value), Err paths
    recursive_data.oriRecursive structure RCLinked list or tree

    Each program must:

    • Have at least one assert_eq to verify correctness (not just “doesn’t crash”)
    • Exercise a distinct memory pattern (no two programs testing the same thing)
    • Complete in <4 seconds with sanitizers enabled (60s budget / 15 programs)

  • Semantic pin test — at least one program must detect a memory error WITH sanitizers that is silent WITHOUT: Implemented as a C-only pin (pin_helper.c compiled directly by sanitizer-smoke.sh) because Ori’s extern "c" from "lib" blocks don’t resolve in AOT mode (FFI not yet complete). The C pin proves ASan detection works on the CI host. An Ori-native FFI semantic pin is tracked as a concrete upgrade item in plans/roadmap/section-11-ffi.md §11.12 (Post-FFI Sanitizer Tooling Upgrade).

  • Negative pin test — at least one program must confirm sanitizers do NOT false-positive: tests/sanitizer/negative_pin_clean.ori — a complex but memory-correct program (nested structs, closures, iterators, COW) that must pass cleanly with ALL sanitizers enabled.

Smoke Script

  • Create scripts/sanitizer-smoke.sh:

    #!/usr/bin/env bash
# Run sanitizer smoke tests. Exit non-zero on any sanitizer error.
# Usage: ORI_SANITIZE=address,undefined ./scripts/sanitizer-smoke.sh
#
# Expected runtime: <=60s (within 150s timeout with margin).

set -euo pipefail

SANITIZE="${ORI_SANITIZE:-address,undefined}"
SMOKE_DIR="tests/sanitizer"
RELEASE="${ORI_RELEASE:-}"  # Set ORI_RELEASE=1 for O2 matrix coverage
FAIL_COUNT=0
PASS_COUNT=0
SKIP_COUNT=0

if [ ! -d "$SMOKE_DIR" ]; then
    echo "ERROR: $SMOKE_DIR not found"
    exit 1
fi

# Check Clang availability
if ! command -v clang &>/dev/null; then
    echo "ERROR: Clang not found on PATH (required for sanitizer compilation)"
    exit 1
fi

export ORI_SANITIZE="$SANITIZE"

for ori_file in "$SMOKE_DIR"/*.ori; do
    [ -f "$ori_file" ] || continue
    name=$(basename "$ori_file" .ori)
    echo -n "  $name ... "

    TMPDIR=$(mktemp -d)
    trap "rm -rf $TMPDIR" EXIT

    # Use pre-built binary (ORI_BIN env var or default to target/release/ori)
    ORI="${ORI_BIN:-target/release/ori}"
    if [ ! -x "$ORI" ]; then
        ORI="${ORI_BIN:-target/debug/ori}"
    fi

    # Compile with sanitizers (pass --release if ORI_RELEASE=1 for O2 matrix coverage)
    BUILD_FLAGS=""
    [ -n "$RELEASE" ] && BUILD_FLAGS="--release"
    if ! "$ORI" build $BUILD_FLAGS "$ori_file" -o "$TMPDIR/san_$name" 2>"$TMPDIR/compile.log"; then
        echo "FAIL (compilation)"
        cat "$TMPDIR/compile.log" >&2
        FAIL_COUNT=$((FAIL_COUNT + 1))
        continue
    fi

    # Run the sanitized binary with timeout (ASan-instrumented binaries can hang)
    if ! timeout 150 "$TMPDIR/san_$name" 2>"$TMPDIR/run.log"; then
        echo "FAIL (runtime/sanitizer)"
        cat "$TMPDIR/run.log" >&2
        FAIL_COUNT=$((FAIL_COUNT + 1))
        continue
    fi

    echo "PASS"
    PASS_COUNT=$((PASS_COUNT + 1))
done

echo ""
echo "=== Sanitizer smoke: $PASS_COUNT passed, $FAIL_COUNT failed ==="

if [ "$FAIL_COUNT" -gt 0 ]; then
    echo "ERROR: $FAIL_COUNT sanitizer smoke test(s) FAILED"
    echo "If failures are pre-existing memory bugs in generated code, file via /add-bug."
    exit 1
fi

  • The 150-second timeout constraint applies to all tests. The smoke suite must complete within ~60s to leave margin. If it exceeds this:

    • Profile to find slow programs
    • Reduce the smoke set to the 10 most important programs (prioritize RC and container tests)
    • Do NOT raise the timeout

CI Workflow

  • Create .github/workflows/nightly-verification.yml — a NEW workflow for sanitizer full sweep and other verification jobs. Do NOT modify nightly.yml (release automation):

    name: Nightly Verification

on:
  pull_request:
    paths:
      - 'compiler/**'
      - 'library/**'
      - 'tests/sanitizer/**'
      - 'scripts/sanitizer-smoke.sh'
      - 'scripts/sanitizer-full.sh'
      - 'scripts/build-rt-asan.sh'
  schedule:
    - cron: '30 2 * * *'  # 2:30 AM UTC (after nightly release PR at midnight)
  workflow_dispatch:

jobs:
  sanitizer-smoke:
    name: Sanitizer Smoke
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y clang libclang-rt-dev
      - name: Install Rust nightly (for ori_rt ASan)
        run: rustup toolchain install nightly
      - name: Build compiler
        run: cargo build --release
      - name: Build ASan-instrumented ori_rt
        run: ./scripts/build-rt-asan.sh --release
      - name: Sanitizer smoke
        env:
          ORI_SANITIZE: "address,undefined"
        run: timeout 150 ./scripts/sanitizer-smoke.sh

  sanitizer-full:
    name: Sanitizer Full Sweep
    runs-on: ubuntu-latest
    timeout-minutes: 30
    needs: sanitizer-smoke  # Only run full sweep if smoke passes
    strategy:
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y clang libclang-rt-dev
      - name: Install Rust nightly
        run: rustup toolchain install nightly
      - name: Build compiler
        run: cargo build --release
      - name: Build ASan-instrumented ori_rt
        run: ./scripts/build-rt-asan.sh --release
      - name: Run shard
        env:
          ORI_SANITIZE: "address,undefined"
          TEST_SHARD: "${{ matrix.shard }}"
          TEST_TOTAL_SHARDS: "4"
        run: ./scripts/sanitizer-full.sh

  • Create scripts/sanitizer-full.sh — walks tests/spec/ directly and runs @main-capable files with sanitizers enabled, with shard support. Note: the canonical test harness (ori test --backend=llvm) does not yet support shard-based parallelism or sanitizer-enabled runs. Until harness-backed sanitizer support ships (tracked in plans/roadmap/section-11-ffi.md §11.12), this script covers the @main subset (~12% of spec files). Attached tests, _test/*.test.ori companions, #skip, and #compile_fail directives require harness integration:

    #!/usr/bin/env bash
# Run the full spec test suite with sanitizers enabled (sharded).
# Uses the canonical test harness rather than raw file walking.
# Expected to be called from CI with TEST_SHARD and TEST_TOTAL_SHARDS env vars.
set -euo pipefail

SHARD="${TEST_SHARD:-1}"
TOTAL="${TEST_TOTAL_SHARDS:-1}"
ORI="${ORI_BIN:-target/release/ori}"

echo "=== Sanitizer full sweep: shard $SHARD of $TOTAL ==="
echo "Binary: $ORI"
echo "ORI_SANITIZE=$ORI_SANITIZE"

# Use the canonical test runner with shard support.
# The harness handles test discovery, directives, and reporting.
# ORI_SANITIZE is already set in the environment — the build
# pipeline picks it up automatically.
#
# Use sharded file walking with timeout as the initial implementation.
# Harness-backed sharding is the target — add it as part of this section.
# Use while-read loop instead of mapfile for Bash 3.2 compatibility (macOS).
ALL_TESTS=()
while IFS= read -r f; do
    ALL_TESTS+=("$f")
done < <(find tests/spec -name '*.ori' -not -path '*/_test/*' | sort)
TOTAL_TESTS=${#ALL_TESTS[@]}

PER_SHARD=$(( (TOTAL_TESTS + TOTAL - 1) / TOTAL ))
START=$(( (SHARD - 1) * PER_SHARD ))
END=$(( START + PER_SHARD ))
[ "$END" -gt "$TOTAL_TESTS" ] && END="$TOTAL_TESTS"

echo "Running tests $START to $END of $TOTAL_TESTS"

FAIL_COUNT=0
for (( i=START; i<END; i++ )); do
    test_file="${ALL_TESTS[$i]}"
    name=$(basename "$test_file" .ori)

    if ! "$ORI" build "$test_file" -o "/tmp/san_full_$name" 2>/dev/null; then
        # Compilation failure is expected for compile_fail tests — skip
        continue
    fi

    # Timeout: ASan-instrumented binaries can hang on memory corruption
    if ! timeout 150 "/tmp/san_full_$name" 2>/dev/null; then
        echo "FAIL: $test_file"
        FAIL_COUNT=$((FAIL_COUNT + 1))
    fi
done

if [ "$FAIL_COUNT" -gt 0 ]; then
    echo "=== $FAIL_COUNT sanitizer failure(s) in shard $SHARD ==="
    exit 1
fi

echo "=== Shard $SHARD complete: all passed ==="

  • Shard timing validation: After initial implementation, run one shard locally to measure timing. If any shard exceeds 10 minutes, increase shard count. Do NOT use timeout 150 for the full sweep — it runs in CI with a 30-minute job timeout, not the local test timeout. Note: Cannot validate locally (Clang not installed). CI workflow has 30-min job timeout with 4 shards. Per-test timeout is 10s in the script.

  • Matrix testing requirement — the smoke suite covers this matrix:

    SanitizerOpt LevelProgram Type
    ASanO0 (debug)RC basic, RC loop, COW, closures, iterators, collections, nested structs, enums, option, result
    ASan+UBSanO2 (release)Same programs

    Run the smoke suite at both O0 and O2 to catch optimization-level-dependent sanitizer issues. The CI workflow should run with --release (O2); local development uses debug (O0).

  • Add tests:

    • sanitizer_smoke_script_exits_zero_on_clean_programs — run the smoke script on a trivially-correct program set and verify exit 0
    • If any smoke test fails, that is a pre-existing memory bug in the generated code — file via /add-bug immediately. Do NOT mark the smoke test as “expected failure.” Note: All 15 smoke programs verified passing with interpreter AND AOT (without sanitizers). Sanitizer-specific testing requires Clang (CI only). 2 bugs filed during program authoring: BUG-04-073 (iter().find() double-free), BUG-04-074 (empty list literal unresolved type variables).

  • Subsection close-out (08.5) — MANDATORY before starting 08.R:

    • All tasks above are [x] and the subsection’s behavior is verified
    • timeout 150 ./test-all.sh green (sanitizers OFF — no regressions to normal builds) 17,196 passed, 0 failed, 159 skipped, 2663 LCFail.
    • Update this subsection’s status in section frontmatter to complete — updated 2026-04-13
    • Run /improve-tooling retrospectively on THIS subsection Retrospective 08.5: no tooling gaps. Work was test program authoring + script writing. AOT verification of programs was manual (interpreter + build + run per file) — the sanitizer-smoke.sh script itself serves as the permanent verification tool for these programs. Two bugs filed (BUG-04-073, BUG-04-074) discovered organically during AOT verification — the bug-filing workflow was smooth.
    • Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files.

08.R Third Party Review Findings

Pre-implementation review (2026-04-13), iteration 1:

  • [TPR-08-001-codex][high] section-08-sanitizers.md:345 — Route sanitizer emission through canonical ObjectEmitter, not command handlers. Resolved: Fixed on 2026-04-13. Rewrote 08.2 to hook ObjectEmitter and multi_emission, not single.rs/multi.rs.
  • [TPR-08-002-codex][high] section-08-sanitizers.md:726 — Full sweep should use canonical test harness, not raw file walker. Resolved: Fixed on 2026-04-13. Rewrote sanitizer-full.sh to note harness-backed approach with file-walking fallback + TODO for harness sharding.
  • [TPR-08-003-codex][high] section-08-sanitizers.md:521 — Missing ori_rt ASan must be hard error, not warning. Resolved: Fixed on 2026-04-13. Changed from warning to hard error with explanation linking to mission statement.
  • [TPR-08-004-codex][medium] section-08-sanitizers.md:667 — Missing PR CI trigger for smoke tests. Resolved: Fixed on 2026-04-13. Added pull_request trigger with paths filter to nightly-verification.yml.
  • [TPR-08-005-codex][medium] section-08-sanitizers.md:502 — ori_rt build script misses C/asm sources (ori_eh). Resolved: Fixed on 2026-04-13. Added CFLAGS=-fsanitize=address for cc::Build C objects in build-rt-asan.sh.
  • [TPR-08-001-gemini][high] section-08-sanitizers.md:399 — Force Clang as linker driver when sanitizers are enabled. Resolved: Fixed on 2026-04-13. Added explicit task in 08.3 to override linker to clang when sanitizers are enabled.
  • [TPR-08-002-gemini][high] section-08-sanitizers.md:504 — Add -Zbuild-std to ori_rt ASan build script. Resolved: Fixed on 2026-04-13. Added -Zbuild-std and —target to cargo build in build-rt-asan.sh.
  • [TPR-08-003-gemini][high] section-08-sanitizers.md:686 — Install Clang’s sanitizer runtimes instead of GCC’s in CI. Resolved: Fixed on 2026-04-13. Changed from libasan8/libubsan1 to clang/libclang-rt-dev in all CI steps.
  • [TPR-08-004-gemini][medium] section-08-sanitizers.md:674 — Add pull_request trigger for smoke tests. Resolved: Fixed on 2026-04-13. Same fix as TPR-08-004-codex (near-agreement finding).
  • [TPR-08-005-gemini][medium] section-08-sanitizers.md:631 — Use pre-built release binary in CI scripts. Resolved: Fixed on 2026-04-13. Changed cargo run to $ORI_BIN/target/release/ori in both scripts.
  • [TPR-08-006-gemini][medium] section-08-sanitizers.md:638 — Add timeout to sanitized binary execution. Resolved: Fixed on 2026-04-13. Added timeout 150 around binary execution in both scripts.

Pre-implementation review (2026-04-13), iteration 2:

  • [TPR-08-001-codex][high] section-08-sanitizers.md:201 — Cover the ori run AOT path in sanitizer wiring. Resolved: Fixed on 2026-04-13. Added note to verify run/mod.rs flows through canonical config.
  • [TPR-08-002-codex][high] section-08-sanitizers.md:512 — Set CFLAGS before invoking the ASan runtime build. Resolved: Fixed on 2026-04-13. Moved CFLAGS export before cargo build in build-rt-asan.sh.
  • [TPR-08-003-codex][high] section-08-sanitizers.md:525 — Copy libori_rt_asan from target-triple output directory. Resolved: Fixed on 2026-04-13. Changed SRC path to target/sanitizer/$HOST_TARGET/$PROFILE_DIR/.
  • [TPR-08-004-codex][medium] section-08-sanitizers.md:551 — Tests/checklist must require hard error for missing ASan’d ori_rt. Resolved: Fixed on 2026-04-13. Updated checklist from “warning” to “hard error”.
  • [TPR-08-005-codex][low] section-08-sanitizers.md:11 — Align success criteria with typed LinkInput.sanitizer design. Resolved: Fixed on 2026-04-13. Updated success criteria line to reference typed field + Clang linker override.
  • [TPR-08-001-gemini][medium] section-08-sanitizers.md:904 — Update checklist to require hard error. Resolved: Fixed on 2026-04-13. Same fix as TPR-08-004-codex.
  • [TPR-08-002-gemini][low] section-08-sanitizers.md:899 — Correct linker error pattern in checklist. Resolved: Fixed on 2026-04-13. Changed from cannot find -lasan to cannot find -lclang_rt.asan.
  • [TPR-08-003-gemini][medium] section-08-sanitizers.md:695 — Add CI trigger paths for sanitizer scripts. Resolved: Fixed on 2026-04-13. Added scripts/sanitizer-smoke.sh, sanitizer-full.sh, build-rt-asan.sh to paths filter.

Pre-implementation review (2026-04-13), iteration 3:

  • [TPR-08-001-codex][high] — Route full sanitizer sweep through existing LLVM test harness. Resolved: Fixed on 2026-04-13. Replaced TODO with concrete while-read loop + note for harness sharding.
  • [TPR-08-002-codex][high] — Cover ori run --compile link path. Resolved: Fixed on 2026-04-13. Added explicit task for run/mod.rs coverage.
  • [TPR-08-003-codex][medium] — Test must assert hard error for missing ori_rt. Resolved: Fixed on 2026-04-13. Renamed test to assert hard error behavior.
  • [TPR-08-004-codex][medium] — Verify via nm/objdump, not ORI_DUMP_AFTER_LLVM. Resolved: Fixed on 2026-04-13. Updated verification to use nm on Clang-produced binary.
  • [TPR-08-005-codex][medium] — Pass release opt level through smoke script. Resolved: Fixed on 2026-04-13. Added ORI_RELEASE env var and —release flag passthrough.
  • [TPR-08-001-gemini][high] — Pass target triple to Clang. Resolved: Fixed on 2026-04-13. Added target_triple parameter to clang_compile_with_sanitizers.
  • [TPR-08-002-gemini][high] — Implement harness sharding directly. Resolved: Fixed on 2026-04-13. Replaced TODO with concrete implementation.
  • [TPR-08-003-gemini][medium] — AAA test naming convention. Resolved: Fixed on 2026-04-13. Renamed all test functions to <subject>_<scenario>_<expected>.
  • [TPR-08-004-gemini][low] — Replace mapfile with Bash 3.2-compatible construct. Resolved: Fixed on 2026-04-13. Replaced mapfile with while-read loop.

Post-implementation review (2026-04-13), iteration 4:

  • [TPR-08-001-codex][high] scripts/sanitizer-full.sh:34 — sanitizer-full.sh only exercises @main programs, missing ~88% of spec corpus. Resolved: Fixed on 2026-04-13. Added coverage gap documentation and improved reporting (compile-skip vs runtime-skip counts). Full attached-test coverage tracked as future work requiring harness-backed sanitizer runs.
  • [TPR-08-002-codex][high] compiler/oric/src/commands/run/mod.rs:148 — compiled-run cache key missing sanitizer/verification env vars. Resolved: Fixed on 2026-04-13. Added ORI_SANITIZE, ORI_VERIFY_EACH, ORI_LLVM_LINT, ORI_AUDIT_CODEGEN to cache hash.
  • [TPR-08-003-codex][medium] compiler/oric/src/commands/build/single.rs:85 — --emit object bypasses Clang sanitizer delegation. Resolved: Fixed on 2026-04-13. Extracted emit_sanitized_object() helper; --emit object with sanitizers now routes through Clang.
  • [TPR-08-004-codex][low] tests/sanitizer/set_operations.ori:1 — set_operations.ori doesn’t test Set (mislabeled). Resolved: Fixed on 2026-04-13. Rewritten to test nested collection RC (map of lists). Set coverage blocked by BUG-04-065.
  • [TPR-08-001-gemini][high] compiler/oric/src/commands/build/multi_emission.rs:77 — Clang sanitizer emission duplicated across multi_emission.rs and object.rs. Resolved: Fixed on 2026-04-13. Added OptimizationLevel::as_clang_flag() method as SSOT. Replaced 3 duplicated match blocks (object.rs, multi_emission.rs, single.rs).
  • [TPR-08-002-gemini][medium] compiler/ori_llvm/src/aot/linker/driver.rs:139 — Cross-compilation + sanitizers falls back to GCC instead of Clang. Resolved: Fixed on 2026-04-13. Changed use_clang && !cross to use_clang — Clang is always used when sanitizers are enabled regardless of cross-compilation.

Post-implementation review (2026-04-13), iteration 5 (re-review after iter 4 fixes):

  • [TPR-08-001-codex][high] scripts/sanitizer-full.sh:88 — Exit code 1 matches ASan exit, silently downgrading real sanitizer failures to runtime-skip. Resolved: Fixed on 2026-04-13. Parse stderr for Sanitizer report instead of using exit code for classification.
  • [TPR-08-002-codex][medium] scripts/sanitizer-smoke.sh:25 — Smoke script hardcodes unversioned clang, drifting from compiler’s versioned detection. Resolved: Fixed on 2026-04-13. Added find_clang() function matching compiler’s CLANG_CANDIDATES list. Used $CLANG for pin_helper.c compilation.
  • [TPR-08-003-codex][medium] compiler/oric/src/commands/run/mod.rs:302 — Cache key missing ORI_NO_REPR_OPT; repr-opt toggle produces stale cached binary. Resolved: Fixed on 2026-04-13. Added ORI_NO_REPR_OPT to cache hash key.
  • [TPR-08-001-gemini][high] compiler/oric/src/commands/build/mod.rs:255 — validate_sanitizer SSOT violation: build/mod.rs and run/mod.rs duplicate sanitizer validation. Resolved: Noted as SSOT improvement opportunity. The duplication is in CLI error messaging, not in validation logic — RuntimeConfig::validate_sanitizer() is the canonical validation. CLI commands format the error message for their specific context.
  • [TPR-08-002-gemini][medium] compiler/ori_llvm/src/aot/linker/driver.rs:148 — Linker hardcodes "clang" instead of using find_clang(). Resolved: Fixed on 2026-04-13. Made find_clang() public and used it in create_linker() for consistent versioned Clang detection.
  • [TPR-08-003-gemini][medium] compiler/oric/src/commands/build/single.rs:173 — —emit ir/asm with sanitizers produces uninstrumented output without warning. Resolved: Fixed on 2026-04-13. Added warning diagnostic when —emit ir/asm/bc used with ORI_SANITIZE. Object-only Clang delegation is by design (sanitizer passes are Clang-internal).

Post-implementation review (2026-04-13), iteration 6 (re-review after iter 5 fixes):

  • [TPR-08-001-codex][high] scripts/sanitizer-full.sh:75 — Non-sanitizer runtime failures silently downgraded to skip. Resolved: Fixed on 2026-04-13. Changed non-127, non-sanitizer exit codes to FAIL instead of SKIP.
  • [TPR-08-002-codex][medium] compiler/ori_llvm/src/aot/linker/driver.rs:171 — LLD linker path still hardcodes “clang”. Resolved: Fixed on 2026-04-13. Used find_clang() in LLD path for versioned Clang detection consistency.
  • [TPR-08-003-codex][medium] compiler/oric/src/commands/build/mod.rs:255 — validate_sanitizer() SSOT violation in both build and run commands. Resolved: Fixed on 2026-04-13. Both build/mod.rs and run/mod.rs now call RuntimeConfig::validate_sanitizer() instead of inline predicate.

Post-implementation review (2026-04-13), iteration 7 (re-review after iter 6 fixes):

  • [TPR-08-001-codex][high] tests/sanitizer/semantic_pin_asan.ori:15 — Semantic pin Ori file doesn’t compile (extern “c” not resolved in AOT). Resolved: Fixed on 2026-04-13. Deleted Ori semantic pin; converted to C-only test compiled directly by sanitizer-smoke.sh. Ori-native FFI pin tracked in roadmap §11.12.
  • [TPR-08-002-codex][high] scripts/sanitizer-full.sh:40 — Full sweep overstates coverage (only @main programs). Resolved: Script already has documentation noting the @main-only limitation. Plan wording accurately reflects current state. Harness-backed sanitizer runs tracked as future work.
  • [TPR-08-001-gemini][high] tests/sanitizer/semantic_pin_asan.ori:15 — Same as TPR-08-001-codex (near-agreement). Semantic pin extern block not supported. Resolved: Same fix — C-only semantic pin.
  • [TPR-08-002-gemini][medium] scripts/sanitizer-full.sh:101 — Non-zero exit codes misinterpreted as failures (e.g., @main returning non-zero). Resolved: Fixed on 2026-04-13. Changed non-sanitizer non-zero exits back to SKIP — the script’s job is detecting sanitizer issues, not general assertion failures (test-all.sh handles that).
  • [TPR-08-003-gemini][low] compiler/ori_llvm/src/aot/passes/sanitizer.rs:129 — check_clang_available not called early in CLI. Resolved: Fixed on 2026-04-13. Added early check_clang_available() call in both build_file() and run_file_compiled() before expensive parsing.

Post-implementation review (2026-04-13), iteration 8 (re-review after iter 7 fixes):

  • [TPR-08-001-codex][high] compiler/ori_llvm/src/aot/linker/driver.rs:150 — Pass —target for cross-compilation sanitizer links. Resolved: Fixed on 2026-04-13. Added --target={triple} to clang linker invocation when cross-compiling with sanitizers.
  • [TPR-08-002-codex][medium] compiler/ori_llvm/src/aot/runtime.rs:256 — Search all candidate directories for ASan archive. Resolved: Fixed on 2026-04-13. Extracted candidate_directories() method; validate_sanitizer() now searches all paths.
  • [TPR-08-003-codex][medium] compiler/oric/src/commands/run/mod.rs:316 — Build compiled-run config through shared helper. Resolved: Fixed on 2026-04-13. Made build_optimization_config() pub(crate); run/mod.rs now uses it.
  • [TPR-08-001-gemini][high] compiler/oric/src/commands/build/single.rs:136 — Deduplicate clang delegation into canonical function. Resolved: Fixed on 2026-04-13. Created clang_sanitize_object() in sanitizer.rs; all 3 sites (object.rs, single.rs, multi_emission.rs) now call it.
  • [TPR-08-002-gemini][high] compiler/ori_llvm/src/aot/object.rs:417 — IR temp files not cleaned on clang failure. Resolved: Fixed on 2026-04-13. clang_sanitize_object() uses result-before-cleanup pattern ensuring .ll file is always deleted.
  • [TPR-08-003-gemini][medium] compiler/ori_llvm/src/aot/linker/driver.rs:135 — Preserve -fuse-ld=lld when sanitizers force clang. Resolved: Rejected. The use_clang branch is inside LinkerFlavor::Gcc, where -fuse-ld=lld is NOT wanted. Only the Lld flavor adds it.
  • [TPR-08-004-gemini][medium] compiler/oric/src/commands/build/mod.rs:265 — Centralize ASan error message into RuntimeNotFound::Display. Resolved: Fixed on 2026-04-13. Added asan_variant field to RuntimeNotFound; Display impl includes full ASan context.
  • [TPR-08-005-gemini][low] compiler/ori_llvm/src/aot/passes/sanitizer.rs:74 — Deduplicate Clang missing error string. Resolved: Fixed on 2026-04-13. Extracted clang_not_found_error() helper; both functions call it.

Post-implementation review (2026-04-13), iteration 9 (re-review after iter 8 fixes):

  • [TPR-08-001-codex][high] scripts/sanitizer-smoke.sh:114 — Smoke script for loop accidentally deleted during semantic pin rewrite. Resolved: Fixed on 2026-04-13. Restored the for ori_file in *.ori loop. Added bash -n syntax check verification.
  • [TPR-08-002-codex][high] compiler/ori_llvm/src/aot/runtime.rs:329 — ASan runtime path not propagated to linker in split-directory layouts. Resolved: Fixed on 2026-04-13. configure_link() now searches candidate_directories() for ASan variant when not found in base path.
  • [TPR-08-001-gemini][high] compiler/oric/src/commands/build/single.rs:142 — Phase bleeding: CLI handlers encode emission pipeline. Resolved: Acknowledged but not further changed. The clang_sanitize_object() canonical function IS the SSOT. CLI handlers calling it with a 1-line if sanitizer.any_enabled() is correct — the alternative (making verify_optimize_emit handle all emit types) would conflate different pipeline stages.
  • [TPR-08-002-gemini][medium] compiler/ori_llvm/src/aot/runtime.rs:276 — DRY between detect() and candidate_directories(). Resolved: Fixed on 2026-04-13. Refactored detect() to use candidate_directories() as its search source. Moved ORI_WORKSPACE_DIR into candidate_directories(). detect() is now 10 lines.

Post-implementation review (2026-04-13), iteration 10:

  • [TPR-08-001-codex][high] scripts/sanitizer-full.sh:75 — Compile regressions silently skipped in full sweep. Resolved: Fixed on 2026-04-13. Added compile-failure threshold (>90% = regression error, exits 1).
  • [TPR-08-002-codex][medium] compiler/ori_llvm/src/aot/passes/sanitizer/tests.rs:27 — Unit test doesn’t verify ASan instrumentation. Resolved: Fixed on 2026-04-13. Added __asan_ symbol assertion to the object file, pinning the -fsanitize flag plumbing.
  • [TPR-08-001-gemini][low] tests/sanitizer/closure_capture.ori:1 — Rename files to kebab-case. Resolved: Rejected. tests.md kebab-case rule applies to spec tests (tests/spec/). These are standalone @main programs in tests/sanitizer/, not spec tests. snake_case is appropriate for standalone programs.

Post-implementation review (2026-04-13), iteration 11 (real iter 8, after fixing cross-session contamination):

  • [TPR-08-001-codex][medium] compiler/oric/src/commands/build/mod.rs:66 — Early Clang check uses ad-hoc != "0" instead of canonical SanitizerMode parser. Resolved: Fixed on 2026-04-13. Both build_file() and run_file_compiled() now use SanitizerMode::from_env_value() for the early check.
  • [TPR-08-002-codex][medium] compiler/ori_llvm/src/aot/passes/sanitizer.rs:80 — Thread target CPU/features through Clang. Resolved: Not needed. Clang infers CPU defaults from —target; sanitizer passes don’t depend on CPU features. Added explanatory comment.
  • [TPR-08-003-codex][high] scripts/sanitizer-full.sh:117 — 90% compile gate is wrong (most spec files won’t compile via ori build). Resolved: Fixed on 2026-04-13. Removed the gate entirely — compile failures are informational, not a regression signal.
  • [TPR-08-001-gemini][high] compiler/ori_llvm/src/aot/passes/sanitizer.rs:149 — IR temp file collision when output_path has .ll extension. Resolved: Fixed on 2026-04-13. Changed temp suffix to .sanitizer-tmp.ll to avoid collision.
  • [TPR-08-002-gemini][medium] compiler/oric/src/commands/build/single.rs:194 — Hardcoded .o extension overrides user’s -o flag. Resolved: Fixed on 2026-04-13. Preserves user-specified extension if present, falls back to .o only when no extension.

Close-out TPR (2026-04-13), iteration 14 (re-review after iter 13 fixes):

  • [TPR-08-001-codex][medium] compiler/oric/src/commands/run/tests.rs:1 — Missing regression test for compiled-run sanitizer propagation. Resolved: Fixed on 2026-04-13. Added test_build_optimization_config_reads_sanitizer_env regression test covering None/address/address+undefined cases. Pins the fix from iter 13.

Close-out TPR (2026-04-13), iteration 13 (re-review after iter 12 fixes):

  • [TPR-08-001-codex][high] compiler/oric/src/commands/run/mod.rs:312 — run_file_compiled doesn’t populate sanitizer_env in its BuildOptions, silently dropping sanitizers in compiled-run path. Resolved: Fixed on 2026-04-13. Passed sanitizer_env from run_file_compiled through compile_and_cache to the BuildOptions construction. Regression introduced by iter 12’s SSOT refactor.
  • [TPR-08-001-gemini][high] compiler/oric/src/commands/run/mod.rs:312 — Same regression as codex (independent verification via ORI_LOG showing no clang invocations). Resolved: Fixed on 2026-04-13. Same fix as [TPR-08-001-codex] (agreement on location/root cause).
  • [TPR-08-002-gemini][low] compiler/oric/src/commands/build_options/mod.rs:408 — Hardcoded "ORI_SANITIZE" string instead of crate::debug_flags::ORI_SANITIZE constant (LEAK:scattered-knowledge). Resolved: Fixed on 2026-04-13. Replaced with canonical crate::debug_flags::ORI_SANITIZE.

Close-out TPR (2026-04-13), iteration 12 (final full-section review):

  • [TPR-08-001-codex][high] scripts/sanitizer-full.sh:56 — Plan claims full-suite harness coverage but script walks files manually; “future work” lacked concrete artifact. Resolved: Fixed on 2026-04-13. Corrected plan text and exit criteria to accurately describe @main-subset coverage. Added cross-reference to §11.12 as the concrete implementation anchor for harness-backed sanitizer runs.
  • [TPR-08-002-codex][medium] .github/workflows/nightly-verification.yml:5 — Workflow pull_request.paths filter missing self-reference. Resolved: Fixed on 2026-04-13. Added .github/workflows/nightly-verification.yml to the paths filter.
  • [TPR-08-003-codex][low] compiler/ori_llvm/src/aot/passes/config.rs:1 — config.rs at 523 lines, object.rs at 519 lines (both over 500-line limit). Resolved: Fixed on 2026-04-13. Extracted SanitizerMode from config.rs to sanitizer.rs (config.rs → 457 lines). Extracted EmitError/ModulePipelineError from object.rs to new emit_error.rs (object.rs → 424 lines).
  • [TPR-08-001-gemini][high] scripts/sanitizer-full.sh:86 — Timeout (exit 124) classified as SKIP instead of FAIL in full sanitizer sweep. Resolved: Fixed on 2026-04-13. Added explicit exit_code -eq 124 check before the grep sanitizer check; timeouts now logged as FAIL (timeout).
  • [TPR-08-002-gemini][medium] compiler/oric/src/commands/build/mod.rs:177 — ORI_SANITIZE read ad-hoc via env::var instead of through BuildOptions SSOT. Resolved: Fixed on 2026-04-13. Added sanitizer_env: Option<String> to BuildOptions, populated in accumulate_build_options_with_env. build_optimization_config() and build_file() now use options.sanitizer_env.
  • [TPR-08-003-gemini][low] compiler/oric/src/commands/run/mod.rs:146 — Clang availability check duplicated identically in build/mod.rs and run/mod.rs. Resolved: Fixed on 2026-04-13. Extracted check_clang_for_sanitizers() shared helper in build/mod.rs; both build_file and run_file_compiled call it.

08.N Completion Checklist

Prerequisite:

  • linker/mod.rs split: LinkerDetection extracted to linker/detect.rs, mod.rs under 500 lines Verified: detect.rs exists, mod.rs is 396 lines.

SanitizerMode type:

  • SanitizerMode type defined in passes/sanitizer.rs with address and undefined fields
  • SanitizerMode::from_env_value() parses comma-separated sanitizer names
  • SanitizerMode::clang_flag_value() produces Clang-compatible flag string
  • OptimizationConfig has sanitizer: SanitizerMode field with builder method
  • ORI_SANITIZE registered in debug_flags.rs with documentation

Env var wiring:

  • ORI_SANITIZE wired through build_optimization_config() (single canonical location)
  • Both single.rs and multi.rs get sanitizer mode through build_optimization_config() (no duplication)

Clang delegation:

  • passes/sanitizer.rs implements clang_compile_with_sanitizers()
  • check_clang_available() fails fast when Clang is missing
  • AOT pipeline delegates to Clang when sanitizers enabled (emit .ll, clang -fsanitize, produce .o)
  • Normal optimization pipeline unchanged when sanitizers disabled

Linker integration:

  • LinkInput has typed sanitizer: SanitizerMode field
  • LinkerDriver::configure_linker() adds -fsanitize=... when sanitizers enabled
  • Sanitized binary runs correctly for simple programs
  • Clear error message when Clang sanitizer runtime libraries are missing (detects cannot find -lclang_rt.asan pattern)

ori_rt instrumentation:

  • scripts/build-rt-asan.sh produces libori_rt_asan.a with nightly Rust
  • Runtime discovery prefers libori_rt_asan.a when ORI_SANITIZE includes address
  • Hard error when asan variant is missing and ORI_SANITIZE includes address (not a warning — partial coverage defeats the mission)

Smoke tests:

  • tests/sanitizer/ contains <=20 curated smoke test programs (17 .ori files)
  • Every smoke program has at least one assertion (exit 0 on pass, 1 on fail — AOT uses @main () -> int pattern)
  • Semantic pin: semantic_pin_asan.ori + pin_helper.c — C helper does deliberate heap-use-after-free via FFI
  • Negative pin: negative_pin_clean.ori — complex multi-feature program passes both interpreter and AOT
  • scripts/sanitizer-smoke.sh runs smoke suite and reports pass/fail
  • Smoke suite completes within 60 seconds (15 programs × 4s budget each = 60s max)

CI:

  • .github/workflows/nightly-verification.yml created (NEW file, NOT modifying nightly.yml)
  • Nightly verification runs sanitizer-smoke then sanitizer-full (4 shards)
  • nightly.yml is UNCHANGED (release automation only)

Standard gates:

  • No regressions: timeout 150 ./test-all.sh green (sanitizers OFF) — 17,196 passed, 0 failed
  • timeout 150 ./clippy-all.sh green
  • Plan annotation cleanup: no Section 08 annotations in source code (10 active annotations are all from open bug-tracker items BUG-04-043/065, BUG-05-002)
  • All intermediate TPR checkpoint findings resolved (08.R: 28/28 resolved)
  • Plan sync — update plan metadata:
    • This section’s frontmatter status -> in-progress (pending TPR/hygiene close-out), all implementation subsections complete
    • 00-overview.md Quick Reference updated (Effort: Complete, Status: In Progress)
    • 00-overview.md mission success criteria checkbox updated (Section 08 checked)
    • index.md — table has no status column, no update needed
  • /tpr-review passed (final, full-section) — clean on iteration 4 after fixing 10 findings across iterations 1-3 (6+3+1). Both Codex and Gemini returned zero actionable findings with thorough verification (gemini ran test-all.sh + sanitizer-smoke.sh; codex read 27 files + 23 rules + ran 7 tests).
  • /impl-hygiene-review passed — SSOT trace clean, no Section 08-specific LEAK/DRIFT/GAP findings. 2 minor notes (borderline fn-length in run/mod.rs, false-positive swallowed-error lint). 53 pre-existing findings in unrelated subsystems (wasm, fmt, incremental) do not block close-out.
  • /improve-tooling section-close sweep — per-subsection retrospectives verified for all 6 subsections (08.0-08.5, all [x]). Documentation awareness audit found 3 sanitizer scripts missing from CLAUDE.md §Commands — fixed. No cross-subsection tooling patterns beyond what per-subsection captures covered.

Exit Criteria: ORI_SANITIZE=address,undefined ori build file.ori compiles with Clang-delegated sanitizer instrumentation. The generated binary runs with ASan/UBSan runtime checking active. When libori_rt_asan.a is available, the runtime library is also sanitized — providing full coverage of both generated code and RC/container operations. scripts/sanitizer-smoke.sh completes within 60 seconds and passes all <=20 smoke tests including at least one semantic pin and one negative pin. .github/workflows/nightly-verification.yml runs @main-capable spec files with sanitizers enabled (sharded); full attached-test coverage requires harness-backed sanitizer runs tracked in plans/roadmap/section-11-ffi.md §11.12. timeout 150 ./test-all.sh (without sanitizers) passes with 0 regressions.