docs(safety): document the unsafe contract end-to-end

After Opt #2 added six bounded `get_unchecked` blocks per chart, the
project's two "no unsafe" claims (README §"At a glance" + spec §11
rule 12) were stale, and there was no single place answering "how
do I know the unsafe is correct?".

This commit closes both gaps:

- New: docs/004. unsafe-safety-contract.md
  Inventories every unsafe site, names the predicate, names what
  establishes it (codegen-time guarantee), and lists the five
  layered checks (const-eval, debug_assert, miri, mutants, Creusot)
  with current status. Documents what's *not* yet covered (the
  16-of-53 missed mutants in the LCA depth walk are behavior, not
  safety; transition() codegen invariants are still Phase-4 for
  Creusot). Includes a maintenance checklist for future unsafe.

- README points at the doc and gives an honest one-paragraph
  summary instead of "no unsafe".

- Spec rule 12 rewritten from "no unsafe in generated code" to
  "bounded unsafe in generated code, none in user code" with a
  pointer to the audit.

- justfile gains `just safety` — runs const-eval (cargo check),
  debug_assert tests, miri, and mutants in one shot. Mirrors the
  doc's audit matrix so the doc never goes stale silently.
This commit is contained in:
swaits committed 2026-05-04 15:29:24 -06:00
1 parent 98352b0e4d
commit ad2aa6e04d
4 files changed
+224 -4

No files matched your search

+8 -3
View File
@@ -173,9 +173,14 @@ For nested-state hierarchies, `emit(...)`, `terminate`, and
alt-ergo + z3 discharge the proofs (`just verify`).
- **No heap, no dynamic dispatch.** Pure monomorphized code.
`no_std` clean by default. Designed to fit on a Cortex-M0+ under
embassy. The macro emits a small amount of `unsafe` (bounded
`get_unchecked` indexing into codegen-emitted tables whose layout
guarantees `idx < len` by construction); your code is `unsafe`-free.
embassy. The macro emits six bounded `unsafe { get_unchecked }`
blocks per chart for hot-path table indexing; their preconditions
are checked at build time by const-eval, in dev/test by
`debug_assert!`, and under `cargo +nightly miri test`. Full
inventory and audit in
[`docs/004. unsafe-safety-contract.md`](docs/004.%20unsafe-safety-contract.md).
Your chart, your action bodies, and your durings stay
`unsafe`-free.
## How a chart behaves — the rules