49 lines
2.8 KiB
Markdown
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.
|