ADR-0058 — Replay sweep orchestration boundary v1¶
Status: ACCEPTED Date: 2026-10-04
Context¶
HistoricalReplayRuntime.run() is deterministic for one complete
ReplaySpec, but it owns no sweep/worker lifecycle and returns a
ReplayResult, not an Experiment RunIdentity, metric projection, or durable
attempt record. I02/I03 already provide race-safe PostgreSQL state
transitions and full-population accounting, but they do not define which
replay result metrics constitute a trial attempt. ReplaySpec also binds no
Decimal-context policy, while Decimal arithmetic may be process-local.
Adding workers directly would therefore require guessing three semantic contracts: replay-result-to-metric projection, a process-safe data/runtime factory, and worker ownership of experiment persistence.
Decision¶
- Parallelism may range only over independent, complete replay attempts. A
stateful replay is never partitioned by day, time window, or temporal shard:
positions, cooldowns, sessions, ledger state, fills, and outcomes remain
one
HistoricalReplayRuntime.run()invocation. - This issue introduces no executor yet. A future sweep request must bind,
per member, a
ReplaySpec, aRunIdentity, a declared metric projection, a serializable runtime/data factory, and a Decimal-context policy. None is inferable from the current public runtime objects. - Workers may return immutable success/failure envelopes only. A single
coordinator registers every planned member before dispatch and records each
terminal result through I02/I03 in stable
RunIdentityorder. Failed or aborted members remainFAILEDwith provenance; they may not disappear from the comparable population or lower an effective trial count by omission. - A process worker must initialize the declared Decimal context before it constructs its runtime. Process workers are preferred only after the factory/context contract is executable; thread workers are not authorized as an implicit alternative.
- Future acceptance must prove one-worker and N-worker runs return identical per-spec result identities and registry ordering, plus explicit failed and aborted attempt records. It must also prove that no temporal-split option exists.
Consequences¶
- Existing replay semantics and experiment accounting remain unchanged.
- The safe unit of future parallelism is an entire independent attempt, not a time slice.
- The implementation is deliberately deferred until its missing identity, metric, factory, persistence, and Decimal-context inputs are defined.
Out of scope¶
- faster replay internals, summary mode, D05 representation input, and a second execution/fill/ledger implementation;
- a scheduler, job service, thread-pool fallback, or executor code.
Acceptance evidence¶
Existing tests/test_replay_v1.py proves repeatability of a complete replay;
tests/test_experiment_accounting_v1.py proves failed attempts stay visible in
closed-population comparison; and tests/test_experiment_persistence_v1.py
proves durable run-state transitions. They do not prove cross-process sweep
equivalence, which remains the required evidence for the follow-up slice.
Related¶
Parent tracking: #232. Closes issue #237.