Reference

This overview describes the current runtime contracts. Use the API and matching release documentation for exact signatures and schema compatibility; the public name Crucible does not rename anvil-sdk or its serialized contracts.

Event identity

The current EngineEvent has required run_id, seq, ts_utc, mono_ns and payload fields. Optional correlation_id, strategy_id, venue_id and instrument_id identify the relevant flow. event_type discriminates the payload. Replay order is defined by the per-run sequence, not wall-clock time.

The envelope rejects unknown fields. Do not add invented schema_version, prev_hash or state_hash fields to it: journal framing and checkpoint/state verification have their own contracts.

Event families

Events record run metadata, market input, strategy intents, risk decisions, execution commands and reports, fills, reconciliation, checkpoints and control state. Use the matching release's Payload type for the complete variant set. A variant count on a product page is not a version negotiation mechanism.

Journal and recovery

FerroJournal frames carry encoded Crucible events. NDJSON and CBOR are payload encoding choices; a journal file is not simply an arbitrary stream of JSON objects. Preserve the journal's identity metadata and external chain anchor alongside the file. Follow the release-specific recovery/backup procedure.

Integrity validation checks the journal chain and its trusted anchor. State verification checks replayed reducer state and checkpoint consistency. A valid hash does not certify market-data completeness, broker behavior or strategy profitability.

Replay requires the relevant retained events, accepted ordering, configuration and compatible code/schema identities. The runner compares live and replayed state at shutdown. Startup verifies the journal and handles a torn final frame according to the recovery contract. The lost suffix cannot be reconstructed from the surviving journal alone.

Monetary arithmetic

Monetary values use decimal-backed types. Accounting accepts addition, subtraction and multiplication only when intermediate values are exactly representable; unsupported operations return errors.

VWAP division is explicitly rounded: the accepted quotient must satisfy a half-ulp bound at its decimal scale. This does not promise exact cost-basis conservation across arbitrary sequences. Numeric types alone are not evidence of correct accounting, and the current crypto-oriented units do not establish options multiplier or settlement correctness.

Accounting failure and state integrity

The reviewed accounting contract prepares and validates affected financial entries before committing them. A failed financial update preserves serialized portfolio state, transient indexes and state/checkpoint hashes. The runner latches a reduction failure and blocks subsequent journal appends and new order submission, even if its caller catches the error.

The rejected event remains in the journal. Recovery must reconcile that failure; skipping the event would change the recorded trading history. An unchanged local portfolio does not undo an external fill that already occurred.

Evidence for this boundary combines selected formal accounting/commit models, independent rational-arithmetic reference cases, and implementation conformance checks. Production staging enforces atomic financial updates; the model proof does not verify the entire Rust control flow. This scope is the basis of the accounting example on the Crucible product page.

Assurance scope

Selected risk, order-lifecycle and accounting models have formal proofs. Independent arithmetic oracles, implementation conformance tests and rejection controls connect those models to specific Rust behavior. This is not a mechanized proof of the complete runtime, OS, storage, network or broker.

Composed strategy qualification separately checks input acceptance, strategy behavior, valuation, execution feedback, recovery and measured compute headroom.