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:
4 files changed
+224
-4
No files matched your search
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user