Expand description
The language-agnostic agent ⇄ harness protocol.
Agents are external — a container or HTTP endpoint, in any language — not
Rust code. Each decision step the harness sends a MarketObservation (JSON)
and the agent replies with a Decision (JSON). Keeping this surface tiny and
stable is what lets any vendor compete (and is the whole adoption story).
All observations are point-in-time: close_history, fundamentals and
news only ever contain information available at or before date.
§The wire contract is closed (breaking for entrants as of 0.11.0)
Every wire type carries #[serde(deny_unknown_fields)]. An agent that emits
a key the contract does not define is rejected at the transport boundary and
scored as an agent protocol fault, not silently accepted. This is a
deliberate departure from the additive-only discipline the rest of the
artifact formats follow: an attested benchmark cannot let an unread field
carry meaning the scorer never saw.
The authoritative machine-readable definition of the closed contract is
published as JSON Schema (draft 2020-12) alongside this crate:
schema/decision.schema.json and schema/observation.schema.json. Both set
additionalProperties: false to mirror deny_unknown_fields, and a
bidirectional drift guard (tests/schema_drift.rs) fails the build if the
schema and the Rust types disagree in either direction.
Entrants migrating from 0.10.x: drop any extra keys, or move them under
reasoning (free text) or cost (structured spend). decision_from_wire
produces the diagnostic that names the offending field.
Structs§
- Agent
Trajectory - An agent’s full captured trajectory: every (window × seed) run’s raw decisions. Serde-(de)serializable to JSON; this is the on-disk artifact a separate verifier ingests to recompute the score from raw decisions alone.
- Decision
- What the agent returns.
- Decision
Cost - An agent’s self-reported spend to produce one decision. Every field defaults to
zero so a partial report (e.g. tokens only, no dollar figure) still deserializes.
The engine reduces this to a single scalar via
DecisionCost::billable_units. - Decision
Step - One captured decision step of a single backtest run: the agent’s raw output
at one point-in-time observation. This is the persisted artifact — it holds the
agent’s
Decision(orders, sizing, conviction, reasoning) tagged with the observation it was made against, and deliberately stores no returns, NAV, or any self-reported metric. The score is recomputed by replaying these decisions through the engine, never read from the agent’s word. - Market
Observation - What the agent sees at one decision point.
- Order
- A single per-instrument instruction.
- Position
State - The agent’s current holding in one instrument.
- RunTrajectory
- One captured backtest run (a single window × seed): the ordered sequence of the agent’s raw decision steps, plus the (window, seed) coordinates needed to replay it through the identical point-in-time engine path.
- Symbol
Snapshot - Point-in-time data for one instrument.
- Trajectory
Contract - Trajectory
Window - Identity of the execution environment that produced a raw-decision trajectory. The score configuration is intentionally absent: a trajectory may be regraded under a newer scorer, but it must not be replayed against different market data, costs, or engine semantics while being described as the original run.
Enums§
- Action
- Discrete action label (sizing is carried by
target_weight). - Declared
Mandate - The mandate an agent declares at submission: which reliability verdict it asks to be judged under. Opt-in and additive: a submission with no declaration is scored exactly as before.
Constants§
- DECISION_
SCHEMA_ PATH - Where an entrant finds the authoritative, machine-readable contract. Quoted into every wire-shape diagnostic so a failing agent is one link from the fix.
Functions§
- decision_
from_ wire - Deserialize a
Decisionfrom the wire, turning a contract violation into a diagnostic an entrant can act on.