journal + determinism tests + Creusot verification scaffolding
Phase 1 — semantics doc
docs/002. hsmc-semantics-formal.md
Phase 2 — deterministic execution journal
hsmc/src/journal.rs (TraceEvent, JournalSink, ActionKind)
hsmc-macros: __chart_journal! emission at every observable site
(entry/exit/action/transition/timer arm-cancel-fire/during/emit/
event delivery/terminate). Per-state during count helpers, stable
chart-hash via FNV-1a. Action observation moved out of run_action
and into call sites so ActionKind is accurate.
Public API on the generated machine: journal(), take_journal(),
clear_journal(), CHART_HASH.
Phase 3 — verification crate (Creusot scaffolding)
verification/{Cargo.toml,mise.toml,requirements.txt,INVARIANTS.md}
verification/src/{event_queue.rs,timer_table.rs} — Pearlite
contracts on simplified mirrors of the runtime types. cargo
creusot generates Coma IR cleanly; VCs not yet discharged.
Correspondence tests drive the verified mirror and the runtime
type with the same op sequences and assert observable parity.
Tests — 113 deterministic-flow tests across 22 files. Each compares a
hand-built expected journal byte-for-byte against actual, anchored
to a spec section: initial entry, lateral/self/up transitions,
bubbling, timers, emit, ordering, durings, step/dispatch
equivalence, root-targeting, current_state, termination.
Tooling — mise.toml (root): stable Rust + cargo subcommands.
verification/mise.toml: pinned nightly-2025-11-13 + opam + python
venv + uv. just verify is fully self-installing.
Bug fix — root state targetable by the chart's own name (e.g.
`on(Trig) => ChartName;`) per spec §"How transitions work".
CHART_HASH — stable FNV-1a fingerprint over the chart's structural
definition; mismatch on replay = different chart.
This commit is contained in:
55 files changed
+6476
-151
No files matched your search
@@ -0,0 +1,133 @@
|
||||
//! Correspondence test: the verified [`EventQueue`] mirror behaves
|
||||
//! identically to the real runtime [`hsmc::__private::EventQueue`] under
|
||||
//! the same sequence of operations.
|
||||
//!
|
||||
//! Why this test exists: the verified mirror lives in this crate with
|
||||
//! Pearlite contracts. The real runtime queue lives in hsmc and ships
|
||||
//! to users. If the two ever drift apart, the proofs become wrong even
|
||||
//! though Creusot still passes — we'd be proving the wrong thing.
|
||||
//! This test is the seam that keeps them locked together.
|
||||
|
||||
use hsmc::__private::EventQueue as RealQueue;
|
||||
use hsmc_verification::event_queue::{EventQueue as MirrorQueue, QueueFull};
|
||||
|
||||
/// A small DSL of operations exercised against both queues.
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
enum Op {
|
||||
Push(u32),
|
||||
Pop,
|
||||
Clear,
|
||||
IsEmpty,
|
||||
}
|
||||
|
||||
/// Drive both queues with the same op sequence and assert observable
|
||||
/// behavior (return values + length) match at every step.
|
||||
fn assert_corresponds<const CAP: usize>(ops: &[Op]) {
|
||||
let mut real: RealQueue<u32, CAP> = RealQueue::new();
|
||||
let mut mirror: MirrorQueue<u32, CAP> = MirrorQueue::new();
|
||||
|
||||
for (i, op) in ops.iter().enumerate() {
|
||||
match op {
|
||||
Op::Push(v) => {
|
||||
let r = real.push(*v);
|
||||
let m = mirror.push(*v);
|
||||
let r_full = matches!(r, Err(hsmc::HsmcError::QueueFull));
|
||||
let m_full = matches!(m, Err(QueueFull));
|
||||
assert_eq!(
|
||||
r_full, m_full,
|
||||
"step {i} Push({v}): real-full {r_full}, mirror-full {m_full}"
|
||||
);
|
||||
}
|
||||
Op::Pop => {
|
||||
let r = real.pop();
|
||||
let m = mirror.pop();
|
||||
assert_eq!(r, m, "step {i} Pop: real {r:?} vs mirror {m:?}");
|
||||
}
|
||||
Op::Clear => {
|
||||
real.clear();
|
||||
mirror.clear();
|
||||
}
|
||||
Op::IsEmpty => {
|
||||
assert_eq!(
|
||||
real.is_empty(),
|
||||
mirror.is_empty(),
|
||||
"step {i} IsEmpty mismatch"
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_basic_push_pop() {
|
||||
assert_corresponds::<8>(&[
|
||||
Op::IsEmpty,
|
||||
Op::Push(1),
|
||||
Op::Push(2),
|
||||
Op::Push(3),
|
||||
Op::IsEmpty,
|
||||
Op::Pop,
|
||||
Op::Pop,
|
||||
Op::Pop,
|
||||
Op::IsEmpty,
|
||||
Op::Pop,
|
||||
]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_overflow() {
|
||||
// Capacity 4: fifth push must fail in both implementations.
|
||||
assert_corresponds::<4>(&[
|
||||
Op::Push(10),
|
||||
Op::Push(20),
|
||||
Op::Push(30),
|
||||
Op::Push(40),
|
||||
Op::Push(50), // overflow
|
||||
Op::Pop,
|
||||
Op::Push(60), // succeeds again after pop
|
||||
Op::Push(70), // overflow
|
||||
]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_clear_empties() {
|
||||
assert_corresponds::<8>(&[
|
||||
Op::Push(1),
|
||||
Op::Push(2),
|
||||
Op::Push(3),
|
||||
Op::Clear,
|
||||
Op::IsEmpty,
|
||||
Op::Pop,
|
||||
Op::Push(99),
|
||||
Op::Pop,
|
||||
]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_alternating() {
|
||||
// Wrap-around stress test: push and pop interleave so the ring
|
||||
// buffer's head index wraps multiple times.
|
||||
let mut ops = Vec::new();
|
||||
for i in 0..50u32 {
|
||||
ops.push(Op::Push(i));
|
||||
ops.push(Op::Push(i + 100));
|
||||
ops.push(Op::Pop);
|
||||
}
|
||||
assert_corresponds::<8>(&ops);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_fill_drain_repeat() {
|
||||
// Fill to capacity, drain fully, repeat 5 times.
|
||||
let mut ops = Vec::new();
|
||||
for round in 0..5 {
|
||||
for i in 0..8u32 {
|
||||
ops.push(Op::Push(round * 100 + i));
|
||||
}
|
||||
for _ in 0..8 {
|
||||
ops.push(Op::Pop);
|
||||
}
|
||||
}
|
||||
ops.push(Op::IsEmpty);
|
||||
assert_corresponds::<8>(&ops);
|
||||
}
|
||||
@@ -0,0 +1,190 @@
|
||||
//! Correspondence test: verified [`TimerTable`] mirror vs the real
|
||||
//! runtime [`hsmc::__private::TimerTable`].
|
||||
//!
|
||||
//! Same idea as `correspondence_event_queue.rs` — drive both with the
|
||||
//! same op sequence and assert observable parity.
|
||||
|
||||
use hsmc::__private::TimerTable as RealTable;
|
||||
use hsmc_verification::timer_table::TimerTable as MirrorTable;
|
||||
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
enum Op {
|
||||
Start { state: u16, trigger: u16, ns: u128 },
|
||||
CancelState(u16),
|
||||
CancelOne { state: u16, trigger: u16 },
|
||||
Decrement(u128),
|
||||
PopExpired,
|
||||
MinRemaining,
|
||||
Len,
|
||||
}
|
||||
|
||||
fn assert_corresponds<const CAP: usize>(depth: &[u8], ops: &[Op]) {
|
||||
let mut real: RealTable<CAP> = RealTable::new();
|
||||
let mut mirror: MirrorTable<CAP> = MirrorTable::new();
|
||||
|
||||
for (i, op) in ops.iter().enumerate() {
|
||||
match op {
|
||||
Op::Start { state, trigger, ns } => {
|
||||
real.start(
|
||||
*state,
|
||||
*trigger,
|
||||
core::time::Duration::from_nanos(*ns as u64),
|
||||
);
|
||||
mirror.start(*state, *trigger, *ns);
|
||||
}
|
||||
Op::CancelState(s) => {
|
||||
real.cancel_state(*s);
|
||||
mirror.cancel_state(*s);
|
||||
}
|
||||
Op::CancelOne { state, trigger } => {
|
||||
real.cancel_one(*state, *trigger);
|
||||
mirror.cancel_one(*state, *trigger);
|
||||
}
|
||||
Op::Decrement(elapsed) => {
|
||||
real.decrement(core::time::Duration::from_nanos(*elapsed as u64));
|
||||
mirror.decrement(*elapsed);
|
||||
}
|
||||
Op::PopExpired => {
|
||||
let r = real.pop_expired(depth);
|
||||
let m = mirror.pop_expired(depth);
|
||||
assert_eq!(r, m, "step {i} PopExpired: real {r:?} vs mirror {m:?}");
|
||||
}
|
||||
Op::MinRemaining => {
|
||||
let r = real.min_remaining().map(|d| d.as_nanos());
|
||||
let m = mirror.min_remaining();
|
||||
assert_eq!(r, m, "step {i} MinRemaining: real {r:?} vs mirror {m:?}");
|
||||
}
|
||||
Op::Len => {
|
||||
assert_eq!(
|
||||
real.entries.len(),
|
||||
mirror.len(),
|
||||
"step {i} Len mismatch"
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_timer_start_replaces_in_place() {
|
||||
// Re-starting (1, 10) must not duplicate; the table has one entry for it.
|
||||
assert_corresponds::<8>(
|
||||
&[0, 1, 1, 1, 1, 1, 1, 1],
|
||||
&[
|
||||
Op::Start { state: 1, trigger: 10, ns: 100 },
|
||||
Op::Len,
|
||||
Op::Start { state: 1, trigger: 10, ns: 500 },
|
||||
Op::Len, // still 1 entry
|
||||
Op::MinRemaining,
|
||||
],
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_timer_cancel_state_removes_only_matching() {
|
||||
assert_corresponds::<8>(
|
||||
&[0, 1, 1, 2],
|
||||
&[
|
||||
Op::Start { state: 1, trigger: 10, ns: 100 },
|
||||
Op::Start { state: 1, trigger: 20, ns: 200 },
|
||||
Op::Start { state: 2, trigger: 10, ns: 300 },
|
||||
Op::CancelState(1),
|
||||
Op::Len, // only state-2 survives
|
||||
Op::PopExpired, // none expired
|
||||
],
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_timer_cancel_one_targets_exact_pair() {
|
||||
assert_corresponds::<8>(
|
||||
&[0, 1, 1, 2],
|
||||
&[
|
||||
Op::Start { state: 1, trigger: 10, ns: 100 },
|
||||
Op::Start { state: 1, trigger: 20, ns: 200 },
|
||||
Op::Start { state: 2, trigger: 10, ns: 300 },
|
||||
Op::CancelOne { state: 1, trigger: 10 },
|
||||
Op::Len,
|
||||
],
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_timer_decrement_to_zero_then_pop() {
|
||||
assert_corresponds::<8>(
|
||||
&[0, 1, 1, 1],
|
||||
&[
|
||||
Op::Start { state: 1, trigger: 10, ns: 500 },
|
||||
Op::Decrement(200),
|
||||
Op::MinRemaining, // 300
|
||||
Op::Decrement(400), // saturates to 0
|
||||
Op::MinRemaining, // 0
|
||||
Op::PopExpired, // returns (1, 10)
|
||||
Op::Len, // 0
|
||||
Op::PopExpired, // None
|
||||
],
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_timer_pop_picks_deepest() {
|
||||
// Two expired timers at different depths. depth[1]=1, depth[2]=3.
|
||||
// pop_expired must pick state 2 first (deeper).
|
||||
assert_corresponds::<8>(
|
||||
&[0, 1, 3, 0],
|
||||
&[
|
||||
Op::Start { state: 1, trigger: 100, ns: 0 },
|
||||
Op::Start { state: 2, trigger: 200, ns: 0 },
|
||||
Op::PopExpired, // (2, 200)
|
||||
Op::PopExpired, // (1, 100)
|
||||
Op::PopExpired, // None
|
||||
],
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_timer_pop_breaks_tie_by_declaration_order() {
|
||||
// depth[1]=2, depth[2]=2: equal depth, first-declared (1, 100) wins.
|
||||
assert_corresponds::<8>(
|
||||
&[0, 2, 2, 0],
|
||||
&[
|
||||
Op::Start { state: 1, trigger: 100, ns: 0 },
|
||||
Op::Start { state: 2, trigger: 200, ns: 0 },
|
||||
Op::PopExpired, // (1, 100)
|
||||
Op::PopExpired, // (2, 200)
|
||||
],
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_timer_min_remaining_is_smallest() {
|
||||
assert_corresponds::<8>(
|
||||
&[0, 1, 1, 1],
|
||||
&[
|
||||
Op::Start { state: 1, trigger: 1, ns: 9_999 },
|
||||
Op::Start { state: 2, trigger: 2, ns: 100 },
|
||||
Op::Start { state: 3, trigger: 3, ns: 5_000 },
|
||||
Op::MinRemaining, // 100
|
||||
],
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn corr_timer_complex_sequence() {
|
||||
assert_corresponds::<8>(
|
||||
&[0, 1, 1, 2, 2, 3],
|
||||
&[
|
||||
Op::Start { state: 1, trigger: 1, ns: 1_000 },
|
||||
Op::Start { state: 2, trigger: 1, ns: 2_000 },
|
||||
Op::Start { state: 3, trigger: 1, ns: 3_000 },
|
||||
Op::Decrement(1_500),
|
||||
Op::MinRemaining, // 0 (state 1 hit zero)
|
||||
Op::PopExpired, // (1, 1) — only one expired
|
||||
Op::Decrement(600),
|
||||
Op::PopExpired, // (2, 1) — now expired
|
||||
Op::Len, // 1
|
||||
Op::CancelState(3),
|
||||
Op::Len, // 0
|
||||
],
|
||||
);
|
||||
}
|
||||
Reference in new issue
Block a user