Error codes

Every failure this harness can raise carries a stable machine-readable code alongside its human-readable message. The reporting layer classifies outcomes by code, the JUnit and Markdown renderers group by it, and scenario assertions branch on it, so the code — not the message text — is the interface.

Two properties this document exists to guarantee:

• Every code the harness can raise is listed here, so a consumer that observes one in a report can look up what it means without reading the source.
• Every code listed here exists, because a stale table is worse than no table: consumers trust it.

Both are enforced by scripts/check-error-codes.py, which discovers every crate’s code() method, extracts the codes it can return, and compares them against the tables below. It runs in CI, so drift is a build failure.

Naming, and how it differs from the simulator

Codes here are UPPER_SNAKE_CASE (ASSERTION_TYPE_MISMATCH). The crucible-simulator domain codes are snake_case (insufficient_balance), and those codes pass through this harness unchanged — an adapter never re-codes a simulator failure, so one condition always reports one code.

The two conventions are currently a family inconsistency rather than a deliberate distinction; harmonising them is tracked separately. Until then, treat an UPPER_SNAKE_CASE code as a harness failure (this repository’s own machinery: definitions, fixtures, adapters, assertions, the runner) and a snake_case code as a domain failure reported by the system under test.

The stability contract

• Never rename a code. Reporting, classification and consumer match statements depend on the string.
• Never reuse a retired code for a different condition.
• An unrecognised code means “a failure I do not specifically classify” and must be reported as such, not treated as a panic or an unreachable branch.

Harness definitions and registry

scenario-core

Definition-time validation: a scenario, its metadata, or its environment is structurally wrong, so it is rejected before anything executes.

scenario-registry

Runner

scenario-runner

Execution, lifecycle, and isolation failures. These describe the harness’s own behaviour around a scenario, not a verdict about the system under test.

Assertions and fixtures

assertions

fixtures

Adapters

Adapters translate the harness’s operation vocabulary into a backing surface. A translation failure is an adapter fault: it means the operation could not be expressed, which is a different finding from the surface rejecting it.

adapters/simulator

adapters/prover

adapters/soroban

adapters/testnet

Codes shared across crates

Two codes appear in more than one module on purpose: the same condition has the same name wherever it surfaces, so a consumer never has to special-case which crate produced it.

Using codes

#![allow(unused)]
fn main() {
if outcome.code() == "CONFIDENTIAL_PUBLIC_INPUT" {
    // A privacy guard tripped: this is a finding about the scenario, not a
    // flaky run, so it must never be retried or classified as infrastructure.
    report(Classification::PrivacyViolation);
}
}

Prefer the typed error variant inside Rust, where match is exhaustive and the compiler enforces it. Codes exist for the surfaces a type cannot reach: the JSON report, the JUnit XML a CI server ingests, the Markdown summary, and the exit code of the CLI.