70 lines
3.2 KiB
Markdown
70 lines
3.2 KiB
Markdown
[Reviewed]
|
|
# 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.
|