Add deterministic transactional lifecycle command scheduler
This commit is contained in:
+4
-3
@@ -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
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user