Files
aevolution/docs/architecture/SCHEDULER_CONTRACT.md
T

49 lines
2.8 KiB
Markdown

# Sequential scheduler contract v1
The independent M6 environmental fixture uses a separate
[bounded interval adapter](ENVIRONMENTAL_SCHEDULING.md) in evo::processes. It
does not change this particle scheduler's transaction or retry semantics.
This implements the scoped decision in [ADR-0022](../adr/0022-sequential-command-scheduler.md).
It is a synthetic lifecycle proof, not a player input protocol.
```mermaid
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.