Skip to content

feat: add causal quote and trade replay #109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fallblu merged 1 commit into from
Aug 22, 2026
Merged

feat: add causal quote and trade replay #109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@

## Unreleased

- Add causal quote/trade replay with displayed-liquidity capacity, aggressor-qualified passive
fills, maker/taker fee attribution, and economic event timestamps.
- Publish scenario/journal contract v14 and external strategy protocol v12 while preserving v13
and protocol v11 as frozen compatibility contracts.
- Add conservative next-open and adverse-touch completed-bar execution models with strict fixed
spread and linear participation-impact configuration, explicit missing-volume policy,
tick-aligned prices, and separate price-component audit attribution.
Expand Down
28 changes: 15 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,10 +61,12 @@ scenario slices and scheduled or external intents
fee-component attribution
- Deterministic event IDs, ordered causal references, and order-creation attribution
- Contract-selected compiled execution modules with versioned model-owned configuration and
capability descriptors; v13 adds next-open and adverse-touch models while freezing
`completed_bar_v1`
capability descriptors; v13 adds conservative bar models and v14 adds causal quote/trade replay
while freezing `completed_bar_v1`
- Tick-aligned fixed-spread and participation-impact execution costs with separate reference,
spread, impact, and final-price audit attribution
- Causally ordered quotes and aggressor-classified trades with displayed-liquidity limits,
maker/taker attribution, and event-time fills
- Strict batch JSON and bounded-memory JSON Lines scenario parsing with JSON Schemas
- Versioned synchronous JSON Lines strategy processes with per-request timeouts and strict
lifecycle supervision
Expand Down Expand Up @@ -94,23 +96,23 @@ Validate the included scenario with an in-memory replay:

```sh
opam exec -- dune exec trading-engine -- \
--input contracts/v13/fixtures/demo.scenario.json \
--input contracts/v14/fixtures/demo.scenario.json \
--validate-only
```

Run it and create a journal:

```sh
opam exec -- dune exec trading-engine -- \
--input contracts/v13/fixtures/demo.scenario.json \
--input contracts/v14/fixtures/demo.scenario.json \
--journal demo.journal.jsonl
```

For larger histories, validate and replay the equivalent stream one slice at a time:

```sh
opam exec -- dune exec trading-engine -- \
--input contracts/v13/fixtures/demo.scenario.jsonl \
--input contracts/v14/fixtures/demo.scenario.jsonl \
--input-format jsonl \
--journal demo.journal.jsonl
```
Expand All @@ -119,7 +121,7 @@ Run an external strategy against an empty-schedule scenario:

```sh
opam exec -- dune exec trading-engine -- \
--input contracts/strategy/v11/fixtures/external.scenario.json \
--input contracts/strategy/v12/fixtures/external.scenario.json \
--journal external.journal.jsonl \
--strategy-executable ./my-strategy \
--strategy-arg=config.toml \
Expand Down Expand Up @@ -234,19 +236,19 @@ do not provide reducer snapshots or restart recovery.
- [Diagnostic contract](docs/diagnostics.md)
- [Scenario contract](docs/scenario.md)
- [Contract conformance corpus](contracts/conformance/README.md)
- [Current contract v13 and conformance fixtures](contracts/v13/README.md)
- [Current contract v14 and conformance fixtures](contracts/v14/README.md)
- [Frozen contract v2](contracts/v2/README.md)
- [Historical contract v1](contracts/v1/README.md)
- [Scenario JSON Schema](contracts/v13/scenario.schema.json)
- [Scenario stream record JSON Schema](contracts/v13/scenario-stream.schema.json)
- [Journal record JSON Schema](contracts/v13/journal.schema.json)
- [External strategy protocol v11](contracts/strategy/v11/README.md)
- [Scenario JSON Schema](contracts/v14/scenario.schema.json)
- [Scenario stream record JSON Schema](contracts/v14/scenario-stream.schema.json)
- [Journal record JSON Schema](contracts/v14/journal.schema.json)
- [External strategy protocol v12](contracts/strategy/v12/README.md)
- [Historical strategy protocol v3](contracts/strategy/v3/README.md)
- [Historical strategy protocol v2](contracts/strategy/v2/README.md)
- [Historical strategy protocol v1](contracts/strategy/v1/README.md)
- [Persistra compatibility](docs/persistra.md)
- [Strategy message JSON Schema](contracts/strategy/v11/message.schema.json)
- [Strategy transcript JSON Schema](contracts/strategy/v11/transcript.schema.json)
- [Strategy message JSON Schema](contracts/strategy/v12/message.schema.json)
- [Strategy transcript JSON Schema](contracts/strategy/v12/transcript.schema.json)
- [Execution model](docs/execution-model.md)
- [OCaml coverage](docs/coverage.md)
- [Continuous integration and portability matrix](docs/continuous-integration.md)
Expand Down
178 changes: 163 additions & 15 deletions contracts/conformance/cases.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -847,7 +847,9 @@
"kind": "strategy_response",
"source": "strategy/v9/fixtures/external.strategy.jsonl",
"record": 2,
"extract": ["message"],
"extract": [
"message"
],
"expected_sequence": "1",
"protocol_version": "9",
"mutations": [],
Expand All @@ -861,7 +863,9 @@
"kind": "strategy_response",
"source": "strategy/v9/fixtures/external.strategy.jsonl",
"record": 4,
"extract": ["message"],
"extract": [
"message"
],
"expected_sequence": "2",
"protocol_version": "9",
"mutations": [],
Expand All @@ -875,7 +879,9 @@
"kind": "strategy_response",
"source": "strategy/v9/fixtures/external.strategy.jsonl",
"record": 14,
"extract": ["message"],
"extract": [
"message"
],
"expected_sequence": "7",
"protocol_version": "9",
"mutations": [],
Expand All @@ -889,12 +895,28 @@
"kind": "strategy_response",
"source": "strategy/v9/fixtures/external.strategy.jsonl",
"record": 14,
"extract": ["message"],
"extract": [
"message"
],
"expected_sequence": "7",
"protocol_version": "9",
"mutations": [
{ "op": "replace", "path": ["message_type"], "value": "error" },
{ "op": "replace", "path": ["payload"], "value": { "message": "fixture failure" } }
{
"op": "replace",
"path": [
"message_type"
],
"value": "error"
},
{
"op": "replace",
"path": [
"payload"
],
"value": {
"message": "fixture failure"
}
}
],
"schema_expectation": "accept",
"runtime_expectation": "accept",
Expand Down Expand Up @@ -1177,7 +1199,10 @@
"code": "strategy.protocol",
"phase": "strategy",
"message": "strategy initialization: invalid strategy response JSON",
"context": { "json_path": "$", "sequence": "1" },
"context": {
"json_path": "$",
"sequence": "1"
},
"cause": null
},
"evidence": {
Expand Down Expand Up @@ -1216,7 +1241,10 @@
"strategy_protocol_version": "10",
"strategy_sequence": "1",
"message_type": "ready",
"payload": { "strategy_name": "conformance", "strategy_version": null }
"payload": {
"strategy_name": "conformance",
"strategy_version": null
}
},
"mutations": [],
"schema_expectation": "accept",
Expand All @@ -1230,7 +1258,9 @@
"strategy_protocol_version": "10",
"strategy_sequence": "2",
"message_type": "intents",
"payload": { "intents": [] }
"payload": {
"intents": []
}
},
"mutations": [],
"schema_expectation": "accept",
Expand All @@ -1244,7 +1274,9 @@
"strategy_protocol_version": "10",
"strategy_sequence": "7",
"message_type": "error",
"payload": { "message": "fixture failure" }
"payload": {
"message": "fixture failure"
}
},
"mutations": [],
"schema_expectation": "accept"
Expand All @@ -1262,7 +1294,10 @@
"code": "strategy.protocol",
"phase": "strategy",
"message": "strategy initialization: invalid strategy response JSON",
"context": { "json_path": "$", "sequence": "1" },
"context": {
"json_path": "$",
"sequence": "1"
},
"cause": null
},
"evidence": {
Expand Down Expand Up @@ -1300,7 +1335,10 @@
"strategy_protocol_version": "11",
"strategy_sequence": "1",
"message_type": "ready",
"payload": { "strategy_name": "conformance", "strategy_version": null }
"payload": {
"strategy_name": "conformance",
"strategy_version": null
}
},
"mutations": [],
"schema_expectation": "accept",
Expand All @@ -1314,7 +1352,9 @@
"strategy_protocol_version": "11",
"strategy_sequence": "2",
"message_type": "intents",
"payload": { "intents": [] }
"payload": {
"intents": []
}
},
"mutations": [],
"schema_expectation": "accept",
Expand All @@ -1328,7 +1368,9 @@
"strategy_protocol_version": "11",
"strategy_sequence": "7",
"message_type": "error",
"payload": { "message": "fixture failure" }
"payload": {
"message": "fixture failure"
}
},
"mutations": [],
"schema_expectation": "accept"
Expand All @@ -1346,7 +1388,113 @@
"code": "strategy.protocol",
"phase": "strategy",
"message": "strategy initialization: invalid strategy response JSON",
"context": { "json_path": "$", "sequence": "1" },
"context": {
"json_path": "$",
"sequence": "1"
},
"cause": null
},
"evidence": {
"encoding": "hex",
"prefix": "7b",
"observed_bytes": 1,
"truncated": false
}
},
"mutations": [],
"schema_expectation": "accept"
},
{
"name": "scenario-v14-valid",
"artifact": "scenario-v14",
"kind": "scenario",
"source": "v14/fixtures/demo.scenario.json",
"mutations": [],
"schema_expectation": "accept",
"parser_expectation": "accept"
},
{
"name": "scenario-v14-quote-trade-valid",
"artifact": "scenario-v14",
"kind": "scenario",
"source": "v14/fixtures/quote-trade.scenario.json",
"mutations": [],
"schema_expectation": "accept",
"parser_expectation": "accept"
},
{
"name": "scenario-stream-v14-valid",
"artifact": "scenario-stream-v14",
"kind": "scenario_stream",
"source": "v14/fixtures/quote-trade.scenario.jsonl",
"mutations": [],
"schema_expectation": "accept",
"parser_expectation": "accept"
},
{
"name": "strategy-ready-valid-v12",
"artifact": "strategy-message-v12",
"instance": {
"strategy_protocol_version": "12",
"strategy_sequence": "1",
"message_type": "ready",
"payload": {
"strategy_name": "conformance",
"strategy_version": null
}
},
"mutations": [],
"schema_expectation": "accept",
"parser_expectation": "accept",
"parser_expected": "ready"
},
{
"name": "strategy-intents-valid-v12",
"artifact": "strategy-message-v12",
"instance": {
"strategy_protocol_version": "12",
"strategy_sequence": "2",
"message_type": "intents",
"payload": {
"intents": []
}
},
"mutations": [],
"schema_expectation": "accept",
"parser_expectation": "accept",
"parser_expected": "intents"
},
{
"name": "strategy-error-valid-v12",
"artifact": "strategy-message-v12",
"instance": {
"strategy_protocol_version": "12",
"strategy_sequence": "7",
"message_type": "error",
"payload": {
"message": "fixture failure"
}
},
"mutations": [],
"schema_expectation": "accept"
},
{
"name": "strategy-v12-rejected-response-branch",
"artifact": "strategy-transcript-v12",
"instance": {
"strategy_diagnostic_version": "1",
"transcript_sequence": "2",
"record_type": "rejected_strategy_response",
"expected_strategy_sequence": "1",
"diagnostic": {
"diagnostic_version": "1",
"code": "strategy.protocol",
"phase": "strategy",
"message": "strategy initialization: invalid strategy response JSON",
"context": {
"json_path": "$",
"sequence": "1"
},
"cause": null
},
"evidence": {
Expand Down
Loading
Loading