Files
aevolution/docs/adr/0022-sequential-command-scheduler.md
T

69 lines
3.2 KiB
Markdown

# ADR-0022: Transactional sequential command scheduling
## Status
Adopted for the synthetic M1.6 proof only. No gameplay input or concurrency policy
is selected by this decision.
## Context
M1.5 retains the bounded row store. Before adding systems, replay needs an explicit
input cutoff, total order and failure boundary. The kernel cannot depend on packet
arrival order, clocks, threads or authenticated session state.
## Decision
Add `advance(world, target_tick, commands)` in a scheduler module. The target is
the next completed tick (`current_tick + 1`). Admit at most 1,024 immutable
commands, each with a nonzero host-assigned sequence unique within that tick.
Sort by sequence; reject duplicate sequences even if payloads match. Reject past
and future targets rather than queueing, retiming or rolling back. Sequences may
restart in a later tick; the pair (target tick, sequence) is the identity.
The phase DAG is admission → ordered lifecycle commands → synthetic movement →
tick commit → returned receipts. Commands wrap the existing create/remove API;
they are trusted host lifecycle operations, not player permissions or movement.
Receipts are sorted by sequence and contain the resulting affected entity ID.
Execute nonempty batches against a private copy; publish by noexcept move only
after every command, receipt allocation and tick succeeds. Any recoverable error
rejects the entire batch. Empty batches call the existing allocation-free tick.
No queue, callbacks, threads or job system are introduced. One owner calls the
kernel; direct lifecycle methods remain available for setup and existing callers.
## Alternatives Considered
Arrival-order mutation cannot replay reordered delivery. Per-command partial
success complicates recovery. Undo logs or staged component writes may eventually
reduce copy cost but require broader contracts. An extensible phase executor or
parallel task graph has no measured workload yet.
## Benefits
Stable ordering, atomic rejection, bounded admission and an explicit recovery
boundary without changes to the existing snapshot or no-input golden.
## Costs
Nonempty ticks copy all current rows and allocate receipts. The host must retain
the admitted command stream externally if it needs replay. Copy performance must
be measured before adopting this approach for a realtime server.
## Risks
These operations are not safe to expose directly to clients. A host must validate
authorization, assign ordering keys and bound ingress. A malformed batch can
reject otherwise valid work; host admission must isolate untrusted requests.
Synthetic tests do not validate parallel execution or crash durability.
## Consequences
Snapshots remain format/rules v1: no new persistent state or changed movement
laws. Scheduler contract v1 is identified separately; future command journals
must store it with admitted inputs. Checkpoint only at completed ticks, then
replay subsequent admitted batches. There is no pending input inside snapshots.
Future jobs must return immutable, stably keyed results and have explicit merge
conflict rules; implementing that executor remains deferred until actual work
exists. Test permutations, duplicate/late/future admission, lifecycle conflicts,
limits, exhaustion, rollback and restored continuation under NDEBUG.