Add deterministic transactional lifecycle command scheduler
This commit is contained in:
@@ -0,0 +1,68 @@
|
||||
# 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.
|
||||
@@ -14,6 +14,7 @@ messaging and metrics. 0016–0019 cover durability/ownership, networking/securi
|
||||
infrastructure and voxels. 0020 scopes Gitea delivery and the stateless dev Job.
|
||||
Each record has the eight required sections.
|
||||
0021 authorizes the opt-in ECS comparison only, not a production dependency.
|
||||
0022 adopts the bounded sequential lifecycle-command scheduler for the proof.
|
||||
|
||||
Every dependency adoption records exact version/commit and integrity hash,
|
||||
transitive license obligations, maintenance/security review, owner and removal
|
||||
|
||||
Reference in New Issue
Block a user