Documentation
¶
Overview ¶
Package chaos is a deterministic crash-injection benchmark for agent runtimes: it drives a NON-IDEMPOTENT side effect through a fault schedule and checks it fires at most once.
It's the exportable form of Bide' internal DST — point it at any SDK by implementing System (wire that SDK to do one non-idempotent side effect against a fault-injectable, resumable store). The harness is what proves — or disproves — an at-most-once guarantee: a loop that relies on at-least-once + idempotency double-fires here, visibly. See Bide for the reference adapter that passes.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Report ¶
type Report struct {
Name string
Sweeps int // crash points swept exhaustively
Schedules int // total crash schedules exercised (sweep + randomized)
MaxFired int // worst side-effect count observed (want 1)
Violations int // schedules where the side effect fired more than once
}
Report is the outcome of a chaos run against one System.
func Verify ¶
Verify runs an exhaustive crash-point sweep plus `seeds` randomized multi-crash schedules against sys, and returns a Report. The invariant checked is that the non-idempotent side effect fires at most once, no matter where or how often it crashes.
type Run ¶
Run is one scenario instance: a fresh store + zeroed side-effect counter. Step runs or resumes one attempt, injecting a crash at the crashAt-th durable write (0 = no crash); it returns crashed=true if that crash aborted the attempt (call Step again to resume), false when the attempt reaches a terminal state. Fired reports how many times the non-idempotent side effect actually executed across all Steps so far.
type System ¶
System is one SDK under test: it builds fresh Runs and reports the number of durable writes in a clean run (the crash-sweep upper bound).
func Bide ¶
func Bide() System
Bide is the reference System: Bide' durable loop wired to charge once. It is expected to PASS (at-most-once) under any crash schedule.
func NaiveReference ¶
func NaiveReference() System
NaiveReference is a deliberately-simple at-least-once loop: it journals tool results and replays them, but a tool whose result isn't journaled is simply RE-RUN — no attempt marker, no halt-on-unknown-outcome. So a crash after the side effect but before its result persists causes a DOUBLE-FIRE. This is the common "just make your side effects idempotent" design; it is the baseline an SDK must beat on this benchmark, and it makes the harness demonstrably non-vacuous (a correct loop passes it; this one fails).
Source Files