Local simulation v3 → v4¶
Client v4 changes local simulation contracts. Live protocol layouts, server sources and live SDK methods are not changed by this release. Test downstream simulator users against a pinned wheel before upgrading their environments.
| v3 behavior | v4 contract |
|---|---|
next_turn / submit_turn(agent_id, action) |
next_decision / submit_decision(decision_id, actions) |
| Turn advances time exclusively | Computation/commands overlap on a chronological calendar |
| Submission returns immediate fills/account deltas | Submission returns a pending ticket; later requests contain delivered events |
compute_ns=0 selects a default |
None selects a default; explicit zero is rejected |
| Configured wake gap could be bypassed | Minimum wake gap is enforced |
| Flat MARL observation | observation["assets"][asset_id] plus agent-local cursor/events |
Agent-local observation configuration with ineffective fields |
Explicit asset publication/depth and world history-capacity configuration |
| Synthetic filled/partial-fill ACKs | Executions are fills; resting remainder gets New; IOC ACK filled_volume is zero |
| Multiple books share inventory | Explicit per-asset endowments, accounts and lifecycle |
| Unrestricted seeding | seed_book requires diagnostic mode |
| 14 order-flow counters | All 18 counters, with command-level counts and aggressor-side continuous volume |
| Clock overflow saturates | Invalid time operations return errors |
| Python metadata says 3.10 | Python ≥3.13, matching the actual abi3 build |
Synchronous SimExchange order methods still execute immediately; the time-aware
contract is MarlSimEnv. Existing single-asset constructor defaults remain useful.
Transition through Suspended and Auction before Trade; a direct BookOnly →
Trade call was already invalid in the previous strict simulator.
Read fills independently of ACKs. For rewards, consume the recipient's delivered events and changes since the preceding decision. A passive fill is not caused by the agent's next no-op just because it is first read then.
The research history buffer now holds detailed trace records. It is privileged
evaluator data, not an agent's public market feed. Use drain_trace() to stream
it and events_since() for an agent-local observation history.
Checkpoints are versioned and include pending work. They do not serialize an arbitrary external Python learner. Restore the corresponding learner artifact alongside the environment. The native reference learner supplies its own hooks.
Rust public simulator structs were revised for checked results, indexed books, isolated engines and event-time requests. Use constructors/config builders rather than relying on v3 mutable-field layouts. The default SDK dependency graph still does not link the live engine or protocol-admin.