Benchmark and verify durable programs

Trigora can profile the cost of durability and verify recovery at committed continuation boundaries.

Use trigora bench for a healthy local run. Use trigora verify to inject crashes after committed boundaries, resume, and check that recovery matches the baseline.

Both commands compile the program and run it in-process on a temporary SQLite host. They do not start trigora dev, call Trigora Cloud, or run the host conformance suite.

trigora bench my-program
trigora bench my-program --out bench.json
trigora verify my-program
trigora verify my-program --faults all
trigora verify my-program --faults all --out verify.json

--input is the same JSON argument vector as trigora start: JSON text, or a path to a JSON file. A JSON array is the ordered arguments. A single JSON value is one argument. Omitting it sends {}.

What bench measures

trigora bench runs the program once, to completion, with no crash armed. The report describes that healthy run:

• how many durable boundaries the run committed
• healthy runtime, with sleep delays excluded
• checkpoint time and continuation size
• continuation restore latency
• effect calls, reused effects, events awaited, and CPU time

What verify proves

trigora verify takes the same healthy baseline, then crashes after selected committed boundaries and resumes. The crash is in-process: the host stops after persisting checkpoint N (after_persist_checkpoint:N) and does not kill the process.

A passing check means every tested fault point recovered, the terminal status and result matched the baseline, and completed effects were not repeated or dropped. The process exits non-zero when a recovery fails, the result differs, an effect runs twice, or an effect is missing.

The printed verdict is one line: ✔ Recovery verified at every checkpoint, or ✔ Recovery verified at N sampled checkpoints.

Two different latency measurements

Continuation restore latency and recovery latency are different measurements. Do not treat one as the other.

Continuation restore latency is the time to decode one committed continuation and construct the resumed engine state with Engine::resume. It does not include executing the recovered suffix. trigora bench reports it as continuation_restore_ms.

Recovery latency is the time to resume a run that has already crashed after a committed boundary and bring that run to the baseline state. trigora verify reports it as recovery_ms. It covers the recovery, not the decode-and-resume sample above.

The restore sample is taken from continuation bodies saved during the healthy run. The clock stops when resume returns, before the host callback and before any later copy of the continuation.

Fault points

--faults sample is the default. It checks up to 8 boundaries, spread from the first checkpoint to the last. If the run has 8 or fewer boundaries, sample checks all of them.

--faults all checks every committed boundary.

Effects

A program with durable effects is refused unless you explicitly provide effect results or opt into live baseline execution.

--effects fixtures.json is a JSON object of effect key to result. Those results are used for the baseline and for fault runs.

With --effects live, live handlers run only during the healthy baseline. Fault-injection runs reuse the baseline’s recorded results and do not call the handlers again.

Events and sleeps

--events is a JSON object of event name to payload, or to an array of payloads. The host queues those payloads and delivers them. An awaited event with no queued payload is delivered as "ok". Sleeps are fast-forwarded. Healthy runtime does not include sleep delays.

Reports

--out writes a JSON report with schema_version 1. Percentiles are nearest-rank. The report includes the program, engine version, host protocol version, artifact hash, the healthy baseline, per-checkpoint samples, and, for verify, a fault_injection object.