feat(eval): information-disclosure difficulty axis (obs richness x regime grid)

Orthogonal to regime-based difficulty: ObservationRichness (DataPoor/Standard/DataRich)
parameterizes lookback + fundamentals/news disclosure to measure information efficiency /
data-poverty robustness. Fully additive (default byte-identical, no CONTRACT_VERSION bump),
leak-free preserved under every tier. From the EdgeBench/SForge scan.

Author: ReverseZoom2151

EVALUATION.md

@@ -81,6 +81,38 @@ within-tier gap cannot see. The Rust core exposes the protocol primitive
 sibling of `train_test_split`). Reporting a `calm -> hard` and a `calm -> extreme` transfer
 gap alongside the within-tier generalization gap is strictly stronger evidence of robustness.
 
+## Information disclosure (an orthogonal difficulty axis)
+
+`distribution_mode` sets how adversarial the price *path* is; it says nothing about how
+much of that market the agent is allowed to *see*. Those are independent axes. A Calm panel
+shown through a 3-bar window with no fundamentals or news can be genuinely harder than an
+Extreme panel shown through a 50-bar history with full context: the first measures
+**information efficiency** and robustness to **data poverty** (the real trading axis of
+"information edge") which the regime tiers structurally cannot probe. A scenario is
+therefore a point on a 2-D grid: `(distribution_mode × observation_richness)`.
+
+The shared-book market (`PyMarketClearing` / `EndogenousMarketEnv`) takes a `richness`
+tier orthogonal to `distribution_mode`:
+
+| Tier | Trailing lookback | Fundamentals | News |
+|---|---|---|---|
+| `data_poor` | 3 bars | no | no |
+| `standard` | 20 bars | no | no |
+| `data_rich` | 50 bars | yes | yes |
+
+`standard` is the historical default disclosure, so a scenario built without a `richness`
+setting is byte-identical to `standard`: the axis is strictly additive (no
+`CONTRACT_VERSION` bump). Richer disclosure only ever surfaces **more past / contextual**
+information: the extra bars, the derived `fundamentals` (`trailing_return`, `window_high`,
+`window_low`), and the `news` headline are all computed from the same leak-free trailing
+closes (`<= t`), so the point-in-time invariant holds at every tier, and no tier reveals a
+future bar. Sweeping the same regime across the three tiers isolates how much of an agent's
+edge is real signal-processing versus a dependence on being handed a rich observation; a
+policy whose deflated Sharpe collapses from `data_rich` to `data_poor` on an otherwise
+identical panel is riding disclosure, not skill. Report the tier alongside the
+`distribution_mode` (Rust: `MarketClearing::from_dataset_with_richness` /
+`RichnessTier`; Python: `PyMarketClearing(..., richness=...)`).
+
 ## Statistical confidence (is A > B beyond seed noise?)
 
 Deflation handles overfit-luck and pass^k handles per-run reliability, but a leaderboard has

crates/openoutcry-py/python/openoutcry/market_env.py

@@ -43,7 +43,11 @@
 small documented JSON interface:
 
 * ``PyMarketClearing(n_symbols, n_days, seed, n_agents, capital, kyle_lambda, eta,
-  volume_scale, distribution_mode)``
+  volume_scale, distribution_mode, richness)``. ``richness`` (``data_poor`` | ``standard``
+  | ``data_rich``) is the information-disclosure difficulty axis, orthogonal to
+  ``distribution_mode``: it sets how much of the market each observation surfaces (trailing
+  lookback + optional fundamentals/news), never revealing a future bar. ``standard`` is the
+  historical default disclosure.
 * ``reset_market() -> json``: ``{symbols, n_agents, n_bars, start_bar, cursor, capital,
   observations:[MarketObservation, ...]}`` (observations in canonical agent order).
 * ``step_market(orders_json) -> json``: ``orders_json`` is a JSON array of shape
@@ -120,6 +124,7 @@ def __init__(
         volume_scale: float = 1.0,
         vol_scale: float = 0.0,
         distribution_mode: str = "calm",
+        richness: str = "standard",
         max_weight: float = 1.0,
         allow_short: bool = True,
     ) -> None:
@@ -141,6 +146,7 @@ def __init__(
         self._volume_scale = float(volume_scale)
         self._vol_scale = float(vol_scale)
         self._distribution_mode = str(distribution_mode)
+        self._richness = str(richness)
         self._max_weight = float(max_weight)
         self._allow_short = bool(allow_short)
 
@@ -174,17 +180,32 @@ def _build_market(self) -> None:
             volume_scale=self._volume_scale,
             vol_scale=self._vol_scale,
             distribution_mode=self._distribution_mode,
+            richness=self._richness,
         )
         try:
             self._market = PyMarketClearing(**kwargs)
+            return
         except TypeError:
-            # The native binding predates the vol_scale param (parallel-build interim). Fall
-            # back to the legacy signature only when vol scaling is off, so default behavior
-            # is unchanged; a requested vol_scale > 0 still surfaces the error.
-            if self._vol_scale != 0.0:
-                raise
-            kwargs.pop("vol_scale")
+            pass
+        # An older native binding may predate the newest optional params (richness, then
+        # vol_scale). Drop them only when they sit at their defaults, so default behavior is
+        # unchanged; a non-default request for a missing param still surfaces the error.
+        if self._richness != "standard":
+            raise TypeError(
+                "the native binding predates the 'richness' parameter (needs a rebuild)"
+            )
+        kwargs.pop("richness")
+        try:
             self._market = PyMarketClearing(**kwargs)
+            return
+        except TypeError:
+            pass
+        if self._vol_scale != 0.0:
+            raise TypeError(
+                "the native binding predates the 'vol_scale' parameter (needs a rebuild)"
+            )
+        kwargs.pop("vol_scale")
+        self._market = PyMarketClearing(**kwargs)
 
     def _build_spaces(self) -> None:
         if not _HAS_GYM:  # pragma: no cover - gymnasium is a hard dep of the package

crates/openoutcry-py/src/lib.rs

@@ -13,7 +13,7 @@ use openoutcry::market::{MarketClearing, MarketParams};
 use openoutcry::vec_env::AutoresetMode;
 use openoutcry::{
     generate_scenario, CostModel, Dataset, Decision, DistributionMode, LaneConfig, Mandate,
-    ScenarioSpec, TradingEnv as CoreEnv, VecTradingEnv as CoreVecEnv, Window,
+    RichnessTier, ScenarioSpec, TradingEnv as CoreEnv, VecTradingEnv as CoreVecEnv, Window,
 };
 use pyo3::exceptions::PyValueError;
 use pyo3::prelude::*;
@@ -36,6 +36,20 @@ fn parse_distribution_mode(mode: &str) -> PyResult<DistributionMode> {
     }
 }
 
+/// Parse the wire `richness` label into a [`RichnessTier`], the information-disclosure
+/// difficulty axis orthogonal to `distribution_mode`. `standard` is the historical default
+/// disclosure, so an unset richness reproduces the prior observations byte-for-byte.
+fn parse_richness_tier(richness: &str) -> PyResult<RichnessTier> {
+    match richness {
+        "data_poor" => Ok(RichnessTier::DataPoor),
+        "standard" => Ok(RichnessTier::Standard),
+        "data_rich" => Ok(RichnessTier::DataRich),
+        other => Err(PyValueError::new_err(format!(
+            "unknown richness {other:?} (expected data_poor | standard | data_rich)"
+        ))),
+    }
+}
+
 /// Build the synthetic dataset for a tier: `Calm` is the mild panel; `Hard`/`Extreme`
 /// post-process that same seeded panel (see `openoutcry::generate_scenario`).
 fn build_dataset(n_symbols: usize, n_days: usize, seed: u64, mode: DistributionMode) -> Dataset {
@@ -608,6 +622,7 @@ impl PyMarketClearing {
         volume_scale = 1.0,
         vol_scale = 0.0,
         distribution_mode = "calm",
+        richness = "standard",
     ))]
     #[allow(clippy::too_many_arguments)]
     fn new(
@@ -621,13 +636,16 @@ impl PyMarketClearing {
         volume_scale: f64,
         vol_scale: f64,
         distribution_mode: &str,
+        richness: &str,
     ) -> PyResult<Self> {
         if n_agents < 1 {
             return Err(PyValueError::new_err("n_agents must be >= 1"));
         }
         let mode = parse_distribution_mode(distribution_mode)?;
+        let tier = parse_richness_tier(richness)?;
         let data = build_dataset(n_symbols, n_days, seed, mode);
-        let inner = MarketClearing::from_dataset(&data, n_agents, capital);
+        let inner =
+            MarketClearing::from_dataset_with_richness(&data, n_agents, capital, tier.richness());
         let params = MarketParams {
             lambda: kyle_lambda,
             eta,
@@ -646,6 +664,19 @@ impl PyMarketClearing {
         self.seed
     }
 
+    /// The active observation-richness disclosure as a JSON object
+    /// `{lookback, fundamentals, news}`, the information-poverty difficulty axis.
+    #[getter]
+    fn richness(&self) -> String {
+        let r = self.inner.richness();
+        serde_json::json!({
+            "lookback": r.lookback,
+            "fundamentals": r.fundamentals,
+            "news": r.news,
+        })
+        .to_string()
+    }
+
     #[getter]
     fn symbols(&self) -> Vec<String> {
         self.inner.symbols().to_vec()

crates/openoutcry-py/tests/test_richness.py

@@ -0,0 +1,98 @@
+"""The information-disclosure difficulty axis (observation richness).
+
+These exercise the native ``PyMarketClearing`` directly (no pettingzoo needed): the
+``richness`` tier is orthogonal to ``distribution_mode`` and controls how much of the
+market each observation surfaces. ``standard`` must reproduce the historical disclosure
+byte-for-byte; ``data_poor`` withholds bars and optional fields; ``data_rich`` surfaces
+more bars plus fundamentals and news. None of them ever reveal a future bar.
+"""
+
+import json
+
+import pytest
+
+from openoutcry.openoutcry_py import PyMarketClearing
+
+
+def _rollout(market, orders, steps=6):
+    """The reset observations plus each step's observations, as parsed JSON."""
+    log = [json.loads(market.reset_market())["observations"]]
+    for _ in range(steps):
+        result = json.loads(market.step_market(json.dumps(orders)))
+        log.append(result["observations"])
+        if result["done"]:
+            break
+    return log
+
+
+def _flat_orders(n_agents, n_symbols):
+    return [[0.0] * n_symbols for _ in range(n_agents)]
+
+
+def test_default_richness_is_standard_and_byte_identical():
+    """Omitting ``richness`` and passing ``standard`` clear a byte-identical stream."""
+    common = dict(n_symbols=3, n_days=60, seed=4, n_agents=2, capital=1.0)
+    orders = [[0.3, 0.3, 0.3], [0.3, 0.3, 0.3]]
+    default_market = PyMarketClearing(**common)
+    standard_market = PyMarketClearing(**common, richness="standard")
+    assert _rollout(default_market, orders) == _rollout(standard_market, orders)
+
+
+def test_richness_getter_reports_the_active_disclosure():
+    poor = json.loads(PyMarketClearing(n_symbols=2, n_days=40, richness="data_poor").richness)
+    std = json.loads(PyMarketClearing(n_symbols=2, n_days=40, richness="standard").richness)
+    rich = json.loads(PyMarketClearing(n_symbols=2, n_days=40, richness="data_rich").richness)
+    assert poor == {"lookback": 3, "fundamentals": False, "news": False}
+    assert std == {"lookback": 20, "fundamentals": False, "news": False}
+    assert rich == {"lookback": 50, "fundamentals": True, "news": True}
+
+
+def test_data_poor_withholds_bars_and_optional_fields():
+    market = PyMarketClearing(n_symbols=2, n_days=60, seed=7, n_agents=2, richness="data_poor")
+    obs = json.loads(market.reset_market())["observations"]
+    for agent_obs in obs:
+        for snap in agent_obs["symbols"]:
+            assert len(snap["close_history"]) <= 3
+            assert snap["fundamentals"] == {}
+            assert snap["news"] == []
+
+
+def test_data_rich_surfaces_more_bars_and_populates_fields():
+    rich = PyMarketClearing(n_symbols=2, n_days=120, seed=9, n_agents=2, richness="data_rich")
+    standard = PyMarketClearing(n_symbols=2, n_days=120, seed=9, n_agents=2, richness="standard")
+    rich_obs = json.loads(rich.reset_market())["observations"]
+    std_obs = json.loads(standard.reset_market())["observations"]
+    for ro, so in zip(rich_obs, std_obs):
+        for rs, ss in zip(ro["symbols"], so["symbols"]):
+            assert len(rs["close_history"]) > len(ss["close_history"])
+            assert len(rs["close_history"]) <= 50
+            assert set(rs["fundamentals"]) == {"trailing_return", "window_high", "window_low"}
+            assert len(rs["news"]) == 1
+            assert rs["symbol"] in rs["news"][0]
+
+
+def test_every_tier_is_leak_free_last_close_is_this_bars_cleared_mid():
+    """Under every tier the last surfaced close equals this bar's cleared mid (never a
+    future bar), and the surfaced window never exceeds the cleared-bar count."""
+    for tier in ("data_poor", "standard", "data_rich"):
+        market = PyMarketClearing(
+            n_symbols=3, n_days=80, seed=2, n_agents=2, richness=tier
+        )
+        meta = json.loads(market.reset_market())
+        cleared_bars = meta["start_bar"]
+        orders = _flat_orders(2, 3)
+        while True:
+            result = json.loads(market.step_market(json.dumps(orders)))
+            cleared_bars += 1
+            mids = result["cleared_mids"]
+            for agent_obs in result["observations"]:
+                for s, snap in enumerate(agent_obs["symbols"]):
+                    assert snap["close_history"][-1] == mids[s]
+                    assert len(snap["close_history"]) <= cleared_bars
+            if result["done"]:
+                break
+
+
+def test_unknown_richness_raises():
+    with pytest.raises(ValueError, match="unknown richness"):
+        PyMarketClearing(n_symbols=2, n_days=40, richness="bogus")

crates/openoutcry/src/lib.rs

@@ -33,6 +33,11 @@ pub use scenario_gen::{
     ScenarioSpec,
 };
 
+// --- Information-disclosure difficulty (the axis orthogonal to the regime tiers) -----------
+
+pub mod richness;
+pub use richness::{ObservationRichness, RichnessTier, DEFAULT_LOOKBACK};
+
 // --- Adaptive difficulty-targeting curriculum (Prioritized Level Replay) -------------------
 
 pub mod curriculum;