openoutcry 0.1.0__tar.gz

openoutcry-0.1.0/PKG-INFO

@@ -0,0 +1,42 @@
+Metadata-Version: 2.4
+Name: openoutcry
+Version: 0.1.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: numpy>=1.21
+Requires-Dist: gymnasium>=1.0
+Requires-Dist: verifiers ; extra == 'verifiers'
+Provides-Extra: verifiers
+Summary: OpenOutcry — a leak-free, point-in-time Gym for trading agents (Python distribution).
+Keywords: trading,agent,environment,backtest,reinforcement-learning,gymnasium
+Author: General Liquidity, Inc.
+License: MIT OR Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# openoutcry (Python)
+
+Python distribution of **OpenOutcry** — a leak-free, point-in-time *Gym for trading
+agents*. A pyo3 binding over the Rust environment plus a `gymnasium`-compatible
+wrapper and a PrimeIntellect `verifiers` environment.
+
+```python
+from openoutcry import OpenOutcryEnv
+
+env = OpenOutcryEnv(n_symbols=4, n_days=120, seed=7)
+obs, info = env.reset()
+done = False
+while not done:
+    action = env.action_space.sample()      # target-weight vector
+    obs, reward, terminated, truncated, info = env.step(action)
+    done = terminated or truncated
+```
+
+The native binding (`openoutcry.openoutcry_py.TradingEnv`) exchanges the
+language-agnostic wire JSON at its boundary: `reset() -> str` and
+`step(decision_json) -> (obs_json, reward, done, info_json)`.
+
+Build from source with [maturin](https://www.maturin.rs): `python -m maturin develop`.
+

openoutcry-0.1.0/README.md

@@ -0,0 +1,23 @@
+# openoutcry (Python)
+
+Python distribution of **OpenOutcry** — a leak-free, point-in-time *Gym for trading
+agents*. A pyo3 binding over the Rust environment plus a `gymnasium`-compatible
+wrapper and a PrimeIntellect `verifiers` environment.
+
+```python
+from openoutcry import OpenOutcryEnv
+
+env = OpenOutcryEnv(n_symbols=4, n_days=120, seed=7)
+obs, info = env.reset()
+done = False
+while not done:
+    action = env.action_space.sample()      # target-weight vector
+    obs, reward, terminated, truncated, info = env.step(action)
+    done = terminated or truncated
+```
+
+The native binding (`openoutcry.openoutcry_py.TradingEnv`) exchanges the
+language-agnostic wire JSON at its boundary: `reset() -> str` and
+`step(decision_json) -> (obs_json, reward, done, info_json)`.
+
+Build from source with [maturin](https://www.maturin.rs): `python -m maturin develop`.

openoutcry-0.1.0/openoutcry/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "openoutcry"
+version = "0.1.0"
+edition = "2021"
+license = "MIT OR Apache-2.0"
+description = "OpenOutcry — leak-free point-in-time trading-agent environment (a Gym for trading agents)."
+repository = "https://github.com/general-liquidity/openoutcry"
+keywords = ["trading", "agent", "environment", "backtest", "simulation"]
+categories = ["science", "finance", "simulation"]
+readme = "README.md"
+
+[dependencies]
+sharpebench-sim = "0.0.7"
+sharpebench-protocol = "0.0.7"
+sharpebench-core = "0.0.7"
+
+[dev-dependencies]
+serde_json = "1"
+
+# Lints enforced by the manifest (not just CI's `-D warnings`), so a plain
+# `cargo clippy` fails the same way CI does. Crates opt in via `[lints] workspace = true`.
+[lints.clippy]
+all = { level = "deny", priority = -1 }
+todo = "deny"
+dbg_macro = "deny"

openoutcry-0.1.0/openoutcry/GOVERNANCE.md

@@ -0,0 +1,93 @@
+# OpenOutcry Agent Interface — Governance
+
+The contract is the product. Agents are **external** programs in any language that
+read a `MarketObservation` (JSON) and reply with a `Decision` (JSON). The whole
+adoption story is that this surface stays tiny and stable, so any vendor can build
+against it once and not have it move under them. This document is the promise that
+backs that.
+
+The authoritative artifacts are:
+
+- `contract/observation.schema.json` and `contract/decision.schema.json` — JSON
+  Schema (draft 2020-12) that non-Rust implementers validate against.
+- `src/contract.rs` — `CONTRACT_VERSION`, the single source of truth for the wire
+  version.
+- `contract/conformance/*.json` + `tests/conformance.rs` — the conformance kit.
+
+## 1. Additive-only evolution
+
+The contract evolves **additively**. The only backwards-compatible change is adding
+a **new field that is optional with a default** — every field a producer may omit
+must deserialize on the consumer to a sensible default, so an agent written against
+an older version keeps parsing newer observations and the harness keeps parsing
+older decisions.
+
+Concretely, in Rust this means the field carries `#[serde(default)]` (or
+`#[serde(default = "…")]`). Today's optional-with-default fields are `fundamentals`
+and `news` on `SymbolSnapshot`, `confidence` and `rationale` on `Order`, and
+`reasoning` on `Decision`. They are **not** in the schemas' `required` lists, by
+construction.
+
+The following are **breaking** and are forbidden on the v1 surface:
+
+- removing a field,
+- renaming a field,
+- retyping a field (e.g. `number` → `string`, widening an enum's existing variant),
+- making a previously optional field required, or
+- removing or renaming an `action` enum value.
+
+A breaking change does not mutate `MarketObservation` / `Decision` in place. It ships
+a **parallel namespace** — `ObservationV2` / `DecisionV2` with their own schemas and
+their own `CONTRACT_VERSION` major — and the two run side by side through the
+deprecation window below. Adding a *new* `action` variant is itself breaking for
+consumers that exhaustively match, so it also goes through V2, not an additive bump.
+
+## 2. `CONTRACT_VERSION` semantics
+
+`CONTRACT_VERSION` (currently `"1.0"`) versions the **wire shape only**. It is
+deliberately decoupled from the `openoutcry` crate version and the npm / PyPI package
+versions, which move on their own release cadence.
+
+- **Major** (`1.0` → `2.0`): a breaking change shipped as a parallel `…V2` namespace.
+- **Minor** (`1.0` → `1.1`): reserved for a *batch* of additive fields significant
+  enough to advertise. A single additive field needs no bump at all — existing agents
+  are unaffected by definition, and the conformance badge stays valid.
+
+A package release never, on its own, bumps `CONTRACT_VERSION`. Bug fixes, new baseline
+agents, docs, and extra re-exports change the package version and leave the contract
+version frozen.
+
+## 3. Deprecation window
+
+When a major (`V2`) lands, the previous major is **supported in parallel for at least
+two minor package releases (no less than 90 days)**, whichever is longer. During the
+window:
+
+1. both namespaces deserialize and run; the harness accepts either,
+2. the superseded version is marked `#[deprecated]` in Rust and flagged as deprecated
+   in the schema `description`, and
+3. the changelog states the removal release up front.
+
+Only after the window closes may the old namespace be removed — and that removal is
+itself a major package release.
+
+## 4. Conformance badge
+
+An implementation that passes the conformance kit
+(`contract/conformance/*.json` exercised by `tests/conformance.rs`, or the equivalent
+validation against the published JSON Schemas) may state:
+
+> **conforms to the OpenOutcry Agent Interface v1.0**
+
+To earn it, an agent must, for every observation in the kit:
+
+1. parse the `MarketObservation` against `observation.schema.json`,
+2. emit a `Decision` that validates against `decision.schema.json` — every `action`
+   in the enum, every `target_weight` finite, and every order `symbol` a subset of
+   the observed symbols, and
+3. round-trip the legacy decision shape (no `confidence` / `rationale` / `reasoning`)
+   without error, proving the additive-only discipline holds.
+
+The badge names the **contract** version it was earned against (`v1.0`), not the
+package version. It remains valid across additive (non-bumping) changes and must be
+re-earned against a new major.

openoutcry-0.1.0/openoutcry/README.md

@@ -0,0 +1,84 @@
+# OpenOutcry
+
+**A leak-free, point-in-time environment for trading agents — and the language-agnostic contract they speak.**
+
+OpenOutcry is the open-outcry trading floor for agents: the harness hands the agent a point-in-time
+`Observation`, the agent returns a `Decision`, repeat. Look-ahead is *structurally impossible* (the
+environment owns the time cursor and never hands out a future bar), and trajectories are
+recompute-from-raw-decisions, so an agent cannot lie about its returns.
+
+The strategic bet is **interface ownership**: if every trading agent in the open ecosystem conforms to
+the OpenOutcry `Observation`/`Decision` contract, then [SharpeBench](https://crates.io/crates/sharpebench-core)
+is the natural scorer and the whole funnel — env → trajectory → score → leaderboard — runs on one
+standard. The interface *is* the product; the simulator is the credibility behind it.
+
+## The agent contract (the standard)
+
+An agent is just a program that reads an `Observation` and writes a `Decision` — in any language, over
+stdio (newline-JSON) or HTTP (`POST /decide`):
+
+```jsonc
+// Observation (harness → agent)
+{ "date": "2025-01-02", "cash": 1.0,
+  "symbols": [{ "symbol": "AAPL", "close_history": [187.2, 188.0, 190.4] }],
+  "portfolio": [] }
+
+// Decision (agent → harness)
+{ "orders": [{ "symbol": "AAPL", "action": "buy", "target_weight": 0.5 }] }
+```
+
+The wire shape is versioned (`CONTRACT_VERSION`), evolves **additively only** (new fields are optional
+with defaults), and is pinned by published JSON Schemas + a conformance kit. See
+[`GOVERNANCE.md`](./GOVERNANCE.md) and [`contract/`](./contract/).
+
+## The Gym lifecycle
+
+The same engine SharpeBench runs *closed* (`run_backtest`), OpenOutcry exposes *open* — the caller drives it:
+
+```rust
+use openoutcry::{TradingEnv, Dataset, CostModel, Window, BuyAndHold, Agent};
+
+let data = Dataset::synthetic(4, 120, 1);
+let mut env = TradingEnv::new(data, Window { start: 20, end: 120 }, CostModel::default(), 7);
+let mut agent = BuyAndHold;
+let mut obs = env.reset();
+loop {
+    let decision = agent.decide(&obs);
+    let step = env.step(decision);   // -> { observation, reward, done, info }
+    obs = step.observation;
+    if step.done { break; }
+}
+```
+
+Both stepping surfaces call one shared `step_once` body, so a trajectory the env produces is
+**byte-identical** to the equivalent `run_backtest` (enforced by `env_step_matches_run_backtest`).
+
+## env → SharpeBench score
+
+Run with capture, hand the trajectory to a *separate verifier* that recomputes the submission from the
+raw decisions + frozen data alone, then score:
+
+```
+cargo run -p openoutcry --example score-a-trajectory
+```
+
+(see [`examples/score-a-trajectory.rs`](./examples/score-a-trajectory.rs)). Tamper with the trajectory
+and the honest replay recomputes to different returns — this is the trust hinge of the whole ecosystem.
+
+## Distribution
+
+OpenOutcry ships from one Rust engine to every surface, with a language-agnostic wire contract on top so
+agents can be written in anything:
+
+- **Rust** — `openoutcry` (this crate).
+- **TypeScript / npm** — `@general-liquidity/openoutcry` (the engine compiled to WASM).
+- **Python / PyPI** — `openoutcry`, with a `gymnasium.Env` adapter and a PrimeIntellect `verifiers`
+  environment so it plugs into the RL-training stacks directly.
+
+Reference agents in Rust, TypeScript, and Python double as the conformance smoke tests
+([`examples/`](./examples/)).
+
+## Status
+
+Incubating inside the SharpeBench workspace (it depends on the published `sharpebench-sim` engine).
+It graduates to its own repository at distribution time, consuming the engine as a versioned crate.

openoutcry-0.1.0/openoutcry/contract/conformance/empty-portfolio-start.json

@@ -0,0 +1,12 @@
+{
+  "name": "cold start: full cash, no holdings, snapshots omit optional fundamentals/news",
+  "observation": {
+    "date": "2025-01-02",
+    "cash": 1.0,
+    "symbols": [
+      { "symbol": "SPY", "close_history": [468.1, 470.0, 472.5] },
+      { "symbol": "QQQ", "close_history": [402.3, 404.9, 401.0] }
+    ],
+    "portfolio": []
+  }
+}

openoutcry-0.1.0/openoutcry/contract/conformance/legacy-decision-shape.json

@@ -0,0 +1,18 @@
+{
+  "name": "legacy decision shape: orders omit confidence/rationale and the decision omits reasoning",
+  "observation": {
+    "date": "2025-02-10",
+    "cash": 1.0,
+    "symbols": [
+      { "symbol": "GLD", "close_history": [188.0, 189.5, 190.1] },
+      { "symbol": "SLV", "close_history": [22.1, 22.4, 22.0] }
+    ],
+    "portfolio": []
+  },
+  "legacy_decision": {
+    "orders": [
+      { "symbol": "GLD", "action": "buy", "target_weight": 0.5 },
+      { "symbol": "SLV", "action": "close", "target_weight": 0.0 }
+    ]
+  }
+}

openoutcry-0.1.0/openoutcry/contract/conformance/normal-multi-symbol.json

@@ -0,0 +1,31 @@
+{
+  "name": "normal multi-symbol observation with fundamentals, news and held positions",
+  "observation": {
+    "date": "2025-03-14",
+    "cash": 1.0,
+    "symbols": [
+      {
+        "symbol": "AAPL",
+        "close_history": [186.4, 187.2, 188.0, 190.4, 191.1],
+        "fundamentals": { "pe": 28.4, "revenue_yoy": 0.06 },
+        "news": ["Apple unveils new chip", "Services revenue at record"]
+      },
+      {
+        "symbol": "MSFT",
+        "close_history": [402.1, 405.6, 409.0, 411.3, 408.7],
+        "fundamentals": { "pe": 35.1, "revenue_yoy": 0.12 },
+        "news": ["Azure growth accelerates"]
+      },
+      {
+        "symbol": "NVDA",
+        "close_history": [870.0, 905.4, 889.2, 921.0, 950.5],
+        "fundamentals": { "pe": 61.0, "revenue_yoy": 1.22 },
+        "news": []
+      }
+    ],
+    "portfolio": [
+      { "symbol": "AAPL", "shares": 1.5, "avg_price": 180.0 },
+      { "symbol": "MSFT", "shares": 0.8, "avg_price": 395.0 }
+    ]
+  }
+}

openoutcry-0.1.0/openoutcry/contract/conformance/signed-weight-short.json

@@ -0,0 +1,23 @@
+{
+  "name": "exercises the full decision surface: sell/hold actions and a signed (short) target weight",
+  "observation": {
+    "date": "2025-05-05",
+    "cash": 1.0,
+    "symbols": [
+      { "symbol": "TSLA", "close_history": [240.0, 235.5, 230.1] },
+      { "symbol": "F", "close_history": [12.1, 12.0, 11.8] },
+      { "symbol": "GM", "close_history": [44.0, 44.6, 45.2] }
+    ],
+    "portfolio": [
+      { "symbol": "TSLA", "shares": 0.5, "avg_price": 250.0 }
+    ]
+  },
+  "legacy_decision": {
+    "orders": [
+      { "symbol": "TSLA", "action": "sell", "target_weight": -0.3, "confidence": 0.7, "rationale": "downtrend" },
+      { "symbol": "F", "action": "hold", "target_weight": 0.0 },
+      { "symbol": "GM", "action": "buy", "target_weight": 0.5 }
+    ],
+    "reasoning": "tilt short autos ex-GM"
+  }
+}

openoutcry-0.1.0/openoutcry/contract/conformance/single-symbol.json

@@ -0,0 +1,17 @@
+{
+  "name": "single-symbol universe with one open position",
+  "observation": {
+    "date": "2025-06-20",
+    "cash": 0.25,
+    "symbols": [
+      {
+        "symbol": "BTC",
+        "close_history": [61000.0, 62450.0, 60900.5, 63100.0],
+        "news": ["ETF inflows continue"]
+      }
+    ],
+    "portfolio": [
+      { "symbol": "BTC", "shares": 0.012, "avg_price": 59000.0 }
+    ]
+  }
+}

openoutcry-0.1.0/openoutcry/contract/decision.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openoutcry.dev/contract/v1/decision.schema.json",
+  "title": "Decision",
+  "description": "What an agent returns at one decision step: per-instrument orders plus an optional free-text rationale. OpenOutcry Agent Interface v1.0.",
+  "type": "object",
+  "required": ["orders"],
+  "additionalProperties": false,
+  "properties": {
+    "orders": {
+      "type": "array",
+      "description": "Per-instrument instructions. May be empty (a hold).",
+      "items": { "$ref": "#/$defs/Order" }
+    },
+    "reasoning": {
+      "type": "string",
+      "description": "Free-text rationale captured into the trajectory. Optional; defaults to empty."
+    }
+  },
+  "$defs": {
+    "Order": {
+      "type": "object",
+      "required": ["symbol", "action", "target_weight"],
+      "additionalProperties": false,
+      "properties": {
+        "symbol": { "type": "string" },
+        "action": {
+          "description": "Discrete action label (sizing is carried by target_weight).",
+          "enum": ["buy", "sell", "hold", "close"]
+        },
+        "target_weight": {
+          "type": "number",
+          "description": "Target portfolio weight for this symbol, signed for shorts."
+        },
+        "confidence": {
+          "type": "number",
+          "description": "Stated conviction in [0, 1], scored for calibration. Optional; defaults to 0.5."
+        },
+        "rationale": {
+          "type": "string",
+          "description": "Optional one-line rationale for this order. Defaults to empty."
+        }
+      }
+    }
+  }
+}

openoutcry-0.1.0/openoutcry/contract/observation.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openoutcry.dev/contract/v1/observation.schema.json",
+  "title": "MarketObservation",
+  "description": "What an agent sees at one point-in-time decision step. All data is point-in-time: close_history, fundamentals and news only ever hold information available at or before `date`. OpenOutcry Agent Interface v1.0.",
+  "type": "object",
+  "required": ["date", "cash", "symbols", "portfolio"],
+  "additionalProperties": false,
+  "properties": {
+    "date": {
+      "type": "string",
+      "description": "ISO-8601 date of the decision point."
+    },
+    "cash": {
+      "type": "number",
+      "description": "Cash available to the agent."
+    },
+    "symbols": {
+      "type": "array",
+      "description": "Point-in-time snapshot per tradable instrument.",
+      "items": { "$ref": "#/$defs/SymbolSnapshot" }
+    },
+    "portfolio": {
+      "type": "array",
+      "description": "The agent's current holdings.",
+      "items": { "$ref": "#/$defs/PositionState" }
+    }
+  },
+  "$defs": {
+    "SymbolSnapshot": {
+      "type": "object",
+      "required": ["symbol", "close_history"],
+      "additionalProperties": false,
+      "properties": {
+        "symbol": { "type": "string" },
+        "close_history": {
+          "type": "array",
+          "description": "Trailing closes up to and including `date` (oldest first).",
+          "items": { "type": "number" }
+        },
+        "fundamentals": {
+          "type": "object",
+          "description": "Named fundamental fields (e.g. `pe`, `revenue_yoy`). Optional; defaults to empty.",
+          "additionalProperties": { "type": "number" }
+        },
+        "news": {
+          "type": "array",
+          "description": "Headlines published on or before `date`. Optional; defaults to empty.",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "PositionState": {
+      "type": "object",
+      "required": ["symbol", "shares", "avg_price"],
+      "additionalProperties": false,
+      "properties": {
+        "symbol": { "type": "string" },
+        "shares": { "type": "number" },
+        "avg_price": { "type": "number" }
+      }
+    }
+  }
+}

openoutcry-0.1.0/openoutcry/examples/reference-agent.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Reference OpenOutcry agent (Python) — the simplest thing that honors the contract.
+
+Transport: stdio. Reads one MarketObservation (JSON) per line on stdin and writes one
+Decision (JSON) per line on stdout. Strategy: equal-weight buy-and-hold — the baseline
+every real agent must beat. Fork it, replace ``decide``.
+
+    python examples/reference-agent.py   # then feed it MarketObservation JSON lines
+"""
+import json
+import sys
+
+
+def decide(obs):
+    """MarketObservation -> Decision. Replace this body with your strategy."""
+    symbols = obs["symbols"]
+    weight = 1.0 / max(len(symbols), 1)
+    orders = [
+        {"symbol": s["symbol"], "action": "buy", "target_weight": weight,
+         "confidence": 0.5, "rationale": "equal-weight hold"}
+        for s in symbols
+    ]
+    return {"orders": orders, "reasoning": "equal-weight buy-and-hold"}
+
+
+def main():
+    for raw in sys.stdin:
+        line = raw.strip()
+        if not line:
+            continue
+        try:
+            decision = decide(json.loads(line))
+        except Exception:
+            # Any bad input degrades to an empty-orders hold — never crashes the harness.
+            decision = {"orders": [], "reasoning": "parse error -> hold"}
+        sys.stdout.write(json.dumps(decision) + "\n")
+        sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()

openoutcry-0.1.0/openoutcry/examples/reference-agent.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Reference OpenOutcry agent (TypeScript) — the simplest thing that honors the contract.
+//
+// Transport: stdio. Reads one MarketObservation (JSON) per line on stdin and writes
+// one Decision (JSON) per line on stdout. Strategy: equal-weight buy-and-hold — the
+// baseline every real agent must beat. Fork it, replace `decide`.
+//
+//   node examples/reference-agent.ts   # then feed it MarketObservation JSON lines
+
+import { createInterface } from "node:readline";
+
+interface Order { symbol: string; action: string; target_weight: number; confidence: number; rationale: string; }
+interface Decision { orders: Order[]; reasoning: string; }
+
+/** MarketObservation -> Decision. Replace this body with your strategy. */
+function decide(obs: { symbols: { symbol: string }[] }): Decision {
+  const weight = 1.0 / Math.max(obs.symbols.length, 1);
+  const orders = obs.symbols.map((s) => ({
+    symbol: s.symbol, action: "buy", target_weight: weight, confidence: 0.5, rationale: "equal-weight hold",
+  }));
+  return { orders, reasoning: "equal-weight buy-and-hold" };
+}
+
+const rl = createInterface({ input: process.stdin });
+rl.on("line", (raw) => {
+  const line = raw.trim();
+  if (line === "") return;
+  let decision: Decision;
+  try {
+    decision = decide(JSON.parse(line));
+  } catch {
+    // Any bad input degrades to an empty-orders hold — never crashes the harness.
+    decision = { orders: [], reasoning: "parse error -> hold" };
+  }
+  process.stdout.write(JSON.stringify(decision) + "\n");
+});

openoutcry-0.1.0/openoutcry/examples/score-a-trajectory.rs

@@ -0,0 +1,48 @@
+//! The end-to-end ecosystem path: **env → trajectory → SharpeBench score.**
+//!
+//! Run an agent in OpenOutcry while capturing only its raw decisions, then hand the
+//! trajectory to a *separate verifier* that recomputes the submission from those
+//! decisions + the frozen data alone (the agent cannot lie about its returns), and
+//! finally score it with SharpeBench's `CompositeScore`.
+//!
+//! `cargo run -p openoutcry --example score-a-trajectory`
+
+use openoutcry::{
+    replay_submission, run_backtest_capture, AgentTrajectory, BuyAndHold, CostModel, Dataset,
+    Window, CONTRACT_VERSION,
+};
+use sharpebench_core::{score_agent, ScoreConfig};
+
+fn main() {
+    let data = Dataset::synthetic(4, 160, 7);
+    let window = Window {
+        start: 20,
+        end: 160,
+    };
+    let costs = CostModel::default();
+
+    // 1) env → trajectory: run the agent with capture — the artifact holds ONLY the
+    //    raw per-step decisions + the window/seed coordinates, no self-reported metric.
+    let (_run, run_traj) = run_backtest_capture(&data, &mut BuyAndHold, window, 1, costs);
+    let trajectory = AgentTrajectory {
+        agent_id: "buy-and-hold".to_string(),
+        runs: vec![run_traj],
+        in_sample_trials: 0,
+    };
+
+    // 2) verify: recompute the scoreable submission from the decisions + frozen data
+    //    alone. Tamper with the trajectory and this recomputes to different returns.
+    let submission = replay_submission(&data, &trajectory, costs);
+
+    // 3) score: deflated Sharpe / pass^k / process gate — the SharpeBench verdict.
+    let score = score_agent(&submission, &ScoreConfig::default());
+
+    println!(
+        "OpenOutcry contract v{CONTRACT_VERSION} — scored '{}':",
+        submission.agent_id
+    );
+    println!(
+        "{}",
+        serde_json::to_string_pretty(&score).expect("score serializes")
+    );
+}

openoutcry-0.1.0/openoutcry/src/contract.rs

@@ -0,0 +1,20 @@
+//! The frozen wire contract version.
+
+/// The version of the **OpenOutcry Agent Interface** — the JSON wire shape an
+/// agent and the harness exchange ([`MarketObservation`](crate::MarketObservation)
+/// in, [`Decision`](crate::Decision) out).
+///
+/// This is **not** the crate / npm / PyPI package version. It tracks only the
+/// *shape* of the contract and moves independently: shipping bug fixes, new
+/// baselines, or extra re-exports bumps the package version but leaves
+/// `CONTRACT_VERSION` untouched.
+///
+/// It bumps **only** on a breaking wire change. Additive changes — a new field
+/// that is optional-with-default, so every existing agent keeps parsing — do
+/// **not** bump it (that is the whole additive-only discipline; see
+/// `GOVERNANCE.md`). Removing or retyping a field is a major bump and requires a
+/// parallel `…V2` namespace rather than mutating this surface in place.
+///
+/// Implementers in any language target this version: passing the conformance kit
+/// earns "conforms to the OpenOutcry Agent Interface v1.0".
+pub const CONTRACT_VERSION: &str = "1.0";