property verification

Pre-Alpha. This page describes behavior that may change.

Property verification is the part of ze-chaos that turns "did the run finish without crashing" into something useful. While faults are being injected and peers are churning, a set of validators watches the state transitions and asserts protocol-level invariants that must hold regardless of the fault sequence. If any of them fails, the run fails, and the dashboard shows which property caught it.

The deeper material (each property's exact state machine, its violation conditions, and how new properties are added) lives in the source under main/internal/chaos/.

What a property is

A property is a function that receives every event from the reporter and maintains its own state. On every event it decides whether the invariant still holds. If it does not, it emits a violation with a reason, the peer involved, and the event that triggered it. The orchestrator collects the violations, the dashboard shows them live, and the run exits with a non-zero exit code at the end.

The function signature is stable: a property is a report.Consumer with an extra "violations" output. This means properties plug into the same event fan-out as the terminal dashboard, the JSON log, the Prometheus exporter, and the web dashboard. Everyone sees the same events.

The five day-one properties

ze-chaos --properties all enables every property. The list today.

Property	What it asserts
convergence-deadline	Every route that should reach a peer eventually reaches it, within the convergence deadline.
route-consistency	The RIB and every peer's Adj-RIB-Out agree after recovery.
no-duplicate-routes	No peer receives duplicate announcements for the same prefix.
hold-timer-enforcement	Hold timers are enforced correctly under fault conditions.
message-ordering	Messages are delivered in the correct order.

ze-chaos --properties list shows the current list from the running binary. Adding a property in code makes it appear here automatically, because the list is built from the registration and not from a static file.

Configuring the deadlines

A few of the properties take parameters. The most common is the convergence deadline.

ze-chaos --properties convergence-deadline --convergence-deadline 5s

Convergence uses the deadline as the upper bound on how long a route can take to reach every expected peer. A longer deadline catches fewer bugs but is more realistic for runs with high fault rates; a shorter deadline catches more bugs but produces false positives under heavy chaos. The default is tuned for --chaos-rate 0.1.

When a property fails

A failing property is the signal that the chaos run found something real. The failure appears in three places simultaneously: the dashboard property badge flips red, the stderr log prints a one-line violation, and the event log records the violation with full context.

The debugging loop is the one that makes the tool worth building:

1. Record the failing run with --event-log run.ndjson.
2. Replay it deterministically with --replay run.ndjson to confirm the failure reproduces.
3. Shrink it with --shrink run.ndjson to reduce the scenario to its minimal reproduction.
4. Commit the shrunk scenario as a test.
5. Fix the bug. The test stays in the suite.

Adding a new property

New properties live under main/internal/chaos/validation/. Each one implements the Property interface, registers itself in init(), and immediately appears in --properties list. The existing properties are the best reference for the shape of a new one.

The rules of thumb, from the existing code:

• A property must be cheap. It runs on the main event loop and cannot block on I/O or long computations.
• A property must be self-contained. It cannot reach into other properties' state or the orchestrator's internals.
• A property must emit a violation with enough context to reproduce the failure without needing the full event log.

See also

• Scenarios for how to configure and run property-validated scenarios.
• Dashboard for the live view of property state during a run.
• In-tree chaos testing guide for the current authoritative reference.
• main/internal/chaos/validation/property.go in the repo for the Property interface.