2.8 KiB
Sequential scheduler contract v1
The independent M6 environmental fixture uses a separate bounded interval adapter in evo::processes. It does not change this particle scheduler's transaction or retry semantics.
This implements the scoped decision in ADR-0022. It is a synthetic lifecycle proof, not a player input protocol.
flowchart LR
H[Host: validate and assign sequence] --> A[Admit exact next tick / bounded batch]
A --> O[Sort unique sequences]
O --> C[Private candidate: ordered create/remove]
C --> S[Stable entity-order synthetic movement]
S --> P[Commit world and return ordered receipts]
A -->|invalid| R[Reject without changing world]
C -->|invalid| R
advance(SimulationWorld&, Tick target, span<const Command>) returns
expected<vector<CommandReceipt>, ScheduleError>. Errors distinguish admission
failures from command/tick failures; the latter include the existing Error cause
and command sequence (zero for the tick itself). No references to input survive
the call. The owner must not mutate world or input concurrently.
| Boundary | Invariant |
|---|---|
| Admission | Next completed tick only; at most 1,024 commands; nonzero unique sequence per tick |
| Ordering | Sequence alone defines execution; input span order cannot change results |
| Lifecycle | Create starts participating in movement this tick; removed entities do not move; IDs are never reused |
| Conflict | A second removal of the same entity rejects the entire batch, including earlier creations |
| Commit | Errors and allocation exceptions leave original world unchanged; successful call increments tick exactly once |
| Receipt | One affected entity ID per command, in sequence order, published only on success |
| Recovery | Snapshot after tick T plus admitted batches T+1 onward equals uninterrupted execution |
| Retry | Retrying a committed target is rejected; no durable exactly-once acknowledgment is claimed |
The host assigns sequences before dispatching any future immutable work. Completion order must not assign them. Permutation tests model reordered delivery, not concurrent execution. A host journals validated batches and durable outcomes at its later persistence boundary; it must never assume a returned receipt is durable. Future-target buffering, session deduplication, authorization and pacing remain outside this library. There is no player/NPC behavior or offline progression here.
Existing tick() means an empty input tick and preserves the frozen v1 golden.
Existing direct create/remove are setup/tool APIs; a replaying host must use a
single recorded mutation path. This phase chain is deliberately concrete; no
generic registration API or speculative thread pool is part of M1.6.