Add deterministic transactional lifecycle command scheduler

This commit is contained in:
dingo
2026-09-19 16:35:46 -04:00
parent 20e609d05b
commit b620edfd6f
12 changed files with 375 additions and 13 deletions
+4 -3
View File
@@ -28,13 +28,14 @@ independent reviews; dependent tasks begin after their contracts are settled.
| 1.3 Canonical local snapshot and restore | simulation/snapshot.cpp, schemas/proof-snapshot.md | 1.2, ADR-0008 | Bounded versioned byte format; validate before publish | Round trip, corruption, overflow, truncation, version rejection | Unsafe parsing, native padding |
| 1.4 Freeze deterministic reference result | tests/simulation_tests.cpp | 1.3 | Continuous and restored runs match agreed fingerprint | Golden fingerprint and seeded property ensembles | Test only comparing same broken implementation |
| 1.5 Evaluate mature ECS adoption | experiments/ecs/, ADR-0005, ADR-0021 | 1.2, biological component workload sketch | Measured iteration/lifecycle/serialization cost and scoped choice | Opt-in row/EnTT sparse/dense/churn comparison with canonical equality; production decision needs richer biology | Premature general framework |
| 1.6 Establish scheduler and input phases | simulation/scheduler/, core/time/ | 1.4–1.5 | Explicit phase DAG, one writer, immutable jobs and stable merge | Reordered completion gives equal state; command ordering tests | Hidden concurrency nondeterminism |
| 1.6 Establish scheduler and input phases | simulation/scheduler.*, ADR-0022 | 1.4–1.5 | Sequential phase DAG, one writer, immutable bounded commands and atomic commit; parallel jobs deferred | Permuted delivery gives equal state; admission, rollback and recovery tests | Hidden ordering and partial mutation |
| 1.7 Add spatial contract | simulation/spatial/, units ADR | 1.5–1.6 | Local coordinates and bounded neighborhood queries | Boundary/wrap/precision properties and brute-force comparison | Planet precision leaking into local physics |
The first increment implements 1.1–1.4 as a proof. M1.5 now has an isolated
comparison and scoped recommendation; see engineering/ECS_EVALUATION.md for
measured versus still-unmeasured coverage. M1.6–1.7 remain separate work; no
scheduler or generic ECS placeholder is counted as completion.
measured versus still-unmeasured coverage. M1.6 implements the sequential command
boundary in ADR-0022; no parallel job execution is claimed. M1.7 spatial queries
are next. A generic ECS or job framework is not required to complete this proof.
## M2 — Minimal energy ecosystem
+18 -8
View File
@@ -7,7 +7,7 @@ persistent simulation server. The founding vision remains unchanged.
## Completed implementation
- Vision, architectural pillars, risks, open-question register, architecture
diagrams, biological contracts, engineering constitution and 21 ADRs.
diagrams, biological contracts, engineering constitution and 22 ADRs.
Proposed/deferred choices remain distinct from accepted proof decisions.
- M0–M4 task breakdowns with dependencies, acceptance evidence and risks,
plus M5–M14 gates in [ROADMAP.md](ROADMAP.md).
@@ -37,8 +37,9 @@ Windows checks also pass; full commands and intermediate CI failures are recorde
in the validation report. M0's engineering proof is verified; dev cluster
execution is the remaining delivery check, not a claim of persistent-world readiness.
The maintainer reports Argo is configured. This workspace has no kubeconfig;
the app/source mapping and completed dev Job are not yet independently verified.
The maintainer confirms Argo is configured and deployment additions will sync
when a pod workload is ready. This workspace has no kubeconfig, so completed dev
Job execution is not independently verified. This is not a blocker for M1.
The repository supplies a restricted dev Job and bootstrap examples; image
publication does not demonstrate a Kubernetes rollout or world recovery.
@@ -58,11 +59,20 @@ for the bounded proof; the general production ECS remains a later measured choic
| Priority | Work | Completion evidence |
|---|---|---|
| 1 | Verify the existing dev Argo mapping and sync the pinned, validated image | Dev Job Complete with replay_verified=true; no World0 changes |
| 2 | M1.6 scheduler/input contract: ratify phase order and command admission before implementing a sequential scheduler | Stable input order, one writer, deterministic merges and replay equivalence |
| 3 | M1.7 local spatial contract | Neighborhood queries checked against brute force, wrap/boundary/unit tests and measured workload |
| 4 | M2.1 energy/matter ledger | Agreed units/ranges, atomic transfers, nonnegative balances and conservation tests before organisms |
| 5 | M2.2–2.6 first headless energy cycle | Explicit source → producer → consumer → death → decomposition → nutrients; seeded million-tick ledger evidence |
| 1 | M1.7 local spatial contract | Neighborhood queries checked against brute force, wrap/boundary/unit tests and measured workload |
| 2 | M2.1 energy/matter ledger | Agreed units/ranges, atomic transfers, nonnegative balances and conservation tests before organisms |
| 3 | M2.2–2.6 first headless energy cycle | Explicit source → producer → consumer → death → decomposition → nutrients; seeded million-tick ledger evidence |
| Delivery gate | Add/update the dev workload when a deployable increment needs it; Argo is ready | Observe Job/pod completion separately from image publication; no World0 changes |
M1.6 now implements [the sequential scheduler contract](architecture/SCHEDULER_CONTRACT.md):
exact-tick admission, bounded ordered lifecycle commands, receipts and atomic
rollback on rejection. Windows Release, clang-tidy, ASan and formatting checks
pass. Permutations across 32 seeds, restored continuation, duplicate/late/future
inputs, limits and exhaustion are covered. The no-input golden and snapshot v1
are unchanged. Linux CI evidence is recorded in the validation report after push.
Nonempty batches copy world state; this favors a clear transaction boundary for
the proof, not a measured realtime performance claim. No thread pool or gameplay
input protocol is introduced.
Before biology, resolve the relevant heredity and energetic contracts rather
than treating proof particles as organisms. Exact game tick rate, NPC mutation,
@@ -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.
+1
View File
@@ -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
+44
View File
@@ -0,0 +1,44 @@
# Sequential scheduler contract v1
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.
@@ -67,6 +67,10 @@ simulation rules change.
## Scheduling and pacing
The sequential lifecycle scheduler and atomic input boundary are specified in
[SCHEDULER_CONTRACT.md](SCHEDULER_CONTRACT.md) and ADR-0022. The input-free tick
remains unchanged; lifecycle commands are synthetic host operations only.
The kernel accepts no `deltaTime` argument. The executable advances an exact
requested number of ticks. A future realtime host converts monotonic wall time
into tick debt; it must cap catch-up work, emit overload metrics and shed region
+17
View File
@@ -130,3 +130,20 @@ results/ecs-gcc142.jsonl; all 56 fingerprints match corresponding Windows sample
No production rule or snapshot-format change occurred. This supersedes the
pending Linux experiment note above. The final follow-up edits only record
results and decision scope; production ECS adoption remains deferred.
## M1.6 sequential scheduler (2026-09-19)
Native commands: `tools/windows-check.ps1 -Preset release -Action configure`,
clang-format on changed C++ files, `cmake --build --preset release`,
`ctest --preset release`; then `tools/windows-check.ps1 -Preset analysis -Action check`,
`tools/windows-check.ps1 -Preset asan -Action check` and Release `-Action format`.
All three configurations passed 5/5 CTests; clang-tidy and format-check passed.
Tests execute under NDEBUG and cover six batch permutations across 32 seeds,
an independent direct-lifecycle reference, ordered receipts, restore continuation,
rejected conflicts and malformed admission, the 1,024-command boundary, full entity
capacity and tick/ID exhaustion. Golden `d61ad5bf0c928c76` remains unchanged.
The copy-and-commit implementation allocates before publishing world state and
statically checks noexcept publication/receipt moves. Allocation-failure injection
was not run. No scheduler throughput claim, concurrency validation, durable input
journal or Kubernetes execution is implied. Linux CI is pending this source push.