docs: binary safety checks design — ARM + RISC-V opt-in safety profiles

[avrabe]

Summary

• Adds docs/binary-safety-design.md (842 lines) covering eight categories of opt-in runtime safety guards for synth's ARM Cortex-M and RISC-V RV32 targets.
• Specifies a unified --safety <profile> CLI surface (none / fuzz / rtos / asil-d / paranoid) plus fine-grained --safety-bounds, --safety-stack, --safety-cfi-fwd, --safety-cfi-bwd, --safety-prologue, --safety-poison, --safety-cm-types, --safety-spectre-v1 overrides.
• For each check, documents the threat model, the hardware-assisted fast path (MPU/PMP, MSPLIM/PSPLIM, BTI, PAC, Zicfilp/Zicfiss, index masking), the software fallback with cycle costs, the per-target applicability matrix (M3..M85, RV32I..RV32GC), the synth code locations that need to change, and the Rocq verification impact.
• Phase 5 roadmap proposes parameterising coq/Synth/Compilation.v by SafetyProfile so existing T1/T2 lemmas can be re-proven per profile.

Checks covered

1. Memory bounds (MPU / PMP / software / mask) — generalises the existing --bounds-check flag.
2. Integer divide-by-zero — existing trap is documented and the RV32 gap is called out.
3. Signed-division overflow (INT_MIN / -1) — existing trap is documented and the i64/RV32 gap is called out.
4. Stack overflow (ARMv8-M MSPLIM/PSPLIM hardware path, software canary fallback).
5. CFI forward-edge (BTI on M55/M85, Zicfilp on RV32, software table fallback).
6. CFI backward-edge (PAC on M85, Zicfiss on RV32, software shadow stack fallback).
7. AAPCS prologue/epilogue invariants (compiler-bug canary; motivated by PR fix(opt): systematic AAPCS-clobber audit — sweep all hardcoded R0..R3 usages #108).
8. Linear-memory poisoning (zero-on-boot, MSan-style shadow as fuzz-only path C).
9. Component-model type confusion (safe_lift_* family in synth-abi).

Test plan

• No code changes — design document only. cargo build / cargo test unaffected.
• Cross-references docs/spectre-policy.md (existing) and docs/design/MEMORY_ARCHITECTURE.md (existing) — links verified to existing files.
• Cited synth source locations (line numbers in instruction_selector.rs, mpu.rs, pmp.rs) verified against current HEAD on main.
• References to ARM ARM, RISC-V manual, CompCert, Cranelift, V8, Crocus, Blade cited with retrievable URLs / DOIs.
• Reviewer pass for: completeness of the per-target matrix, accuracy of cycle-cost claims, and Rocq proof impact in §5.

Open questions for reviewers

The document lists 8 open questions in §6, including:

• Should the trap handler be unified (one callback) or demuxed by check class?
• On RV32, should s10 be reserved for a stack-limit pointer when --safety-bounds=soft?
• Profile-vs-target precedence: warn + fall back, or refuse to compile, when a profile asks for hardware that doesn't exist on the target?
• PAC key strategy on Cortex-M85: per-boot from TRNG (non-reproducible) vs per-firmware (extractable)?

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!