Files
aevolution/docs/architecture/SCHEDULER_CONTRACT.md
T

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.