Add atomic conserved energy and elemental inventory ledger

This commit is contained in:
dingo
2026-09-19 19:42:29 -04:00
parent 7e0aa4d057
commit 8fd3591b0e
12 changed files with 517 additions and 7 deletions
+5 -1
View File
@@ -43,7 +43,7 @@ this proof. Production indexing awaits actual interaction workloads.
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|---|---|---|---|---|---|
| 2.1 Ratify accounting units and ledger | biology/energy, world/resources, ENERGY_MODEL | M1, units ADR | Energy/matter/nutrient units, transfer APIs, overflow/error budget explicit | Dimensional compile checks and conservation properties | Rounding creates resources |
| 2.1 Ratify accounting units and ledger | accounting/ledger.*, ENERGY_MODEL, ADR-0024 | M1, units ADR | Exact local units/ranges, finite inventories and atomic ordered transfers | Unit-type separation, rollback/overflow/replay, million-transaction independent balance checks | Mistaking conservation for valid biology |
| 2.2 Add abiotic source and producer | biology/metabolism, world/resources | 2.1 | Energy enters only through named source; uptake bounded by resources | Closed-box balance plus external source accounting | Arbitrary growth subsidies |
| 2.3 Add consumer intentions and ingestion | biology/digestion, simulation/spatial | 2.2, 1.7 | Shared validated action path transfers matter/energy | Predator/prey transfer and dead-action rejection | Consuming twice in same tick |
| 2.4 Death and decomposition | biology/lifecycle, ecology | 2.3 | Active capability ends; corpse pool transfers conserved nutrients | Death terminality, decomposition limits, ledger audit | Nutrients double counted |
@@ -52,6 +52,10 @@ this proof. Production indexing awaits actual interaction workloads.
M2 founder fixtures explicitly identify synthetic test-player origins; they do
not introduce unrelated wildlife into persistent worlds. Morphology is absent.
M2.1's transfer-only ledger is implemented separately from the particle world.
M2.2 must define finite source flux, process-specific restrictions, rate residuals
and the atomic boundary between biological state and its inventories. Snapshot
integration requires its own versioned format; it is not provided by M1's codec.
## M3 — Genome v0.1
+12 -3
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 23 ADRs.
diagrams, biological contracts, engineering constitution and 24 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).
@@ -61,8 +61,8 @@ for the bounded proof; the general production ECS remains a later measured choic
| Priority | Work | Completion evidence |
|---|---|---|
| 1 | M2.1 energy/matter ledger | Agreed units/ranges, atomic transfers, nonnegative balances and conservation tests before organisms |
| 2 | M2.2–2.6 first headless energy cycle | Explicit source → producer → consumer → death → decomposition → nutrients; seeded million-tick ledger evidence |
| 1 | M2.2 finite source and producer process contract | Finite flux, typed rates/residuals, restricted energy conversion and atomic inventory/process state |
| 2 | M2.3–2.6 first headless energy cycle | Producer → consumer → death → decomposition → nutrients; seeded million-tick ecosystem 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):
@@ -85,6 +85,15 @@ spatial index. See the spatial contract and validation report for scope/evidence
Native Release/ASan/analysis/format checks passed, as did all jobs in Gitea run
1409. All 72 Linux benchmark result checksums and match counts equal Windows.
M2.1 adds an independent finite-inventory accounting library (ADR-0024). Typed
picojoules and C/N/P/other femtograms transfer atomically across bounded local
reservoirs. Opening totals are checked, repeated action IDs rejected, and failures
leave both balances and action watermark unchanged. One million seeded transfers
are checked against independently maintained balances and recomputed totals.
No organisms, biochemical rates, external replenishment, world snapshot format
or deployment changes are included. Conservation does not establish valid
chemistry or reusable heat; process restrictions are M2.2 work.
Before biology, resolve the relevant heredity and energetic contracts rather
than treating proof particles as organisms. Exact game tick rate, NPC mutation,
logout treatment, species/extinction rules and multicellular transition remain
@@ -0,0 +1,77 @@
# ADR-0024: Conserved finite inventory ledger
## Status
Adopted for M2.1 synthetic accounting, not production biochemical scales.
## Context
Energy-model transfers must not create resources, overdraw a reserve or partially
fund reproduction. Before any organism implementation we need an exact bounded
accounting primitive. Its state is separate from the M1 particle snapshot.
## Decision
Add a dependency-free `evo::accounting` library. Energy uses u64 picojoules
(1e-12 J); elemental mass uses u64 femtograms (1e-18 kg). These are distinct
wrapper types, not a units algebra. A reservoir contains energy and four disjoint
mass inventories: carbon, nitrogen, phosphorus and other. All matter, including
unmodeled elements, belongs to exactly one category. Total biomass is derived,
never an additional balance. No chemical reaction or conversion is implemented.
One ledger contains 1–4,096 reservoirs created from explicit opening balances.
The sum of each channel across the ledger must fit u64. Energy therefore ranges
up to about 18.45 MJ and each mass category up to about 18.45 kg. This deliberately
bounds a local synthetic experiment, not a planet or large organism. There are
no floating conversions, rounding, rates or residuals in this transfer-only API.
A transaction has a strictly increasing nonzero u64 action ID and 1–256 ordered
transfer legs. Each leg debits and credits the same quantity bundle between two
different valid reservoirs. Earlier credits may fund later legs; intermediate
overdraft is rejected, even when a netted transaction would balance. Validate and
apply on a private copy, then commit by noexcept swap and advance the watermark.
On any failure balances and watermark remain unchanged. Accepted IDs cannot be
replayed; rejected IDs can be corrected and retried. IDs may have gaps.
Reservoir IDs are local 1-based stable indices; no deletion/reuse or implicit
creation. Copies are isolated experiment branches, never a second world owner.
Source inputs must come from a finite opening reservoir; dissipated energy moves
to a heat reservoir. There is no mint/burn API or perpetual light fixture.
## Alternatives Considered
Floating-point balances need error budgets and residual treatment. A general
units library (the mp-units candidate in ADR-0009) is appropriate to evaluate for
future dimensional equations, but these two opaque quantities need no algebra,
conversion or new dependency. Smaller quanta sacrifice local range; larger ones
lose small-cell resolution. Production precision must be measured separately.
Netting or undo logs reduce copying but complicate intermediate solvency rules.
## Benefits
Exact per-channel conservation, atomic bundled transfers, bounded allocation,
typed units and constant-size replay watermark without a growing ID history.
## Costs
O(reservoir count + legs) work per transaction and a copied balance vector.
Serialization, cross-ledger escrow, opening-balance provenance and replenishment
are not implemented. The host must impose deterministic transaction ordering.
## Risks
Increasing IDs do not authenticate a caller or establish durable exactly-once
execution. Cross-ledger identity is a host responsibility. Ledger conservation
does not validate chemistry, energy quality or fair resource allocation. Arbitrary
reservoir reassignment would misrepresent biology despite balanced quantities.
## Consequences
Keep immutable public balance inspection and no direct write access. No entity,
genome, metabolism, external service or kernel snapshot integration yet. Before
integrating persistent ecology, version and serialize inventories and watermark
together, implement named finite flux budgets, carried division residuals and
atomic lifecycle/accounting commits. Unit-library diagnostics/compiler trials
remain a gate before dimensional biological equations, not this transfer proof.
Test exact limits, rollback, competing consumers, stale IDs, seeded conservation
and million-transaction replay under NDEBUG and sanitizers.
+1
View File
@@ -16,6 +16,7 @@ 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.
0023 defines local periodic neighborhood queries and a measured linear baseline.
0024 adopts finite, typed energy/matter inventory transfers for M2.1.
Every dependency adoption records exact version/commit and integrity hash,
transitive license obligations, maintenance/security review, owner and removal
+4 -2
View File
@@ -47,6 +47,7 @@ the simulation state. Durable account references live in orchestration mapping.
|---|---|---|
| core | Value types, deterministic algorithms, explicit version constants | Global state, threads, I/O |
| simulation (`evo_simulation`, alias `evo::simulation`) | State, stable tick ordering, component lifecycle, pure restore validation | Wall clock, transport, database or rendering |
| accounting (`evo_accounting`, alias `evo::accounting`) | Typed finite inventories, atomic conserved transfers, in-memory action watermark | Chemistry, minting resources, entity lifecycle or durable storage |
| biology | Genotype → development → phenotype; energetic transfers | Account rewards, player/NPC subclasses |
| world | Procedural base identity, spatial/environmental fields | Dense planet allocation, gameplay authority |
| persistence | Durable metadata, snapshots, replay batches, migration | Per-tick simulation decisions |
@@ -54,8 +55,9 @@ the simulation state. Durable account references live in orchestration mapping.
| backend | Identity adapters, account/world metadata, history queries, directory/lease coordination | Every noun deployed as a service |
| app / server | Tick pacing, I/O ownership, durable outcome barrier, metrics export | Alternative biological implementation |
Only core, simulation, local snapshot codec and `evo-sim` are source modules in
the proof. Future rows are boundaries, not empty directories or dummy services.
Core, simulation, local snapshot codec, accounting and `evo-sim` are source modules
in the proof. Accounting has an independent tested contract; it is not yet wired
into particle state. Future rows are boundaries, not empty directories or dummy services.
Split a library when a real independently tested contract exists.
## Runtime topology and data flow (target)
+31
View File
@@ -86,3 +86,34 @@ competing consumers, long-run rounding, overflow/NaN rejection, cross-tier escro
and independently recomputed seeded totals. Baseline metabolism, efficiencies,
light attenuation, stoichiometry, heat fidelity and starvation rules remain open.
Conservation alone does not guarantee a stable or enjoyable ecosystem.
## Implemented M2.1 boundary
[ADR-0024](../adr/0024-conserved-inventory-ledger.md) scopes the initial
`evo::accounting` library. Its ledger is independent of particle world state.
Opening inventories are explicit; later operations only transfer quantities.
Energy is in integer picojoules, disjoint C/N/P/other masses in femtograms.
Other contains all unmodeled matter; this is not a complete biochemical basis.
All quantities and global per-channel sums must fit u64. No float conversion,
division or fractional-rate handling is exposed yet, so there is no rounding loss.
```cpp
// include/evo/accounting/ledger.hpp (contract sketch)
auto ledger = Ledger::create(opening_inventories);
auto result = ledger->transfer(action_id, ordered_legs);
```
Each leg transfers the same bundle between distinct reservoir IDs. Atomic commit
covers the entire ordered transaction and its monotonic action watermark. A
rejected transaction consumes nothing, including its ID. A duplicate/older
accepted ID is rejected. This is in-memory replay protection, not durable
exactly-once delivery. The owner assigns deterministic order; competing consumers
are first-funded, with no implicit fair-share or random priority rule.
Reservoir meaning is caller-owned: source, reserve, substrate, structure, corpse,
heat or escrow. The primitive does not enforce chemical reactions or prevent a
caller from misclassifying heat as usable energy. M2.2 must provide restricted
process operations and finite flux budgets. Never treat conservation as biological
validity. There is no import/mint API, organism lifecycle, persisted ledger codec
or cross-ledger transaction in M2.1. Persistent integration must checkpoint both
inventories and action watermark atomically; M1 snapshots do not include them.
+21
View File
@@ -181,3 +181,24 @@ All 72 spatial benchmark checksums and match counts agree with Windows.
Raw Linux measurements are in results/spatial-gcc142.jsonl; 24 native scenarios
also have identical checksums across their three repetitions. No deployment
manifest, rules version, snapshot format or golden was changed.
## M2.1 finite inventory ledger (2026-09-19)
Native Release, analysis and MSVC ASan each passed 6/6 CTests; formatting passed.
Commands: `tools/windows-check.ps1 -Preset <release|analysis|asan> -Action check`
and Release `-Action format`. Initial clang-tidy rejected the Element enum's
oversized base type; changed to u8 and reran all configurations successfully.
The new independent ledger test checks typed energy/mass separation, finite-source
exhaustion, explicit heat transfer, intermediate overdraft, whole-transaction
rollback, retry/duplicate action semantics, invalid reservoir IDs, maximum batch
and reservoir counts, opening-total overflow and exact u64-limit transfers.
32 seeded runs × 31,250 transactions = one million transactions, each checked
against independent reference balances, a replay branch and recomputed per-channel
totals. This is transfer replay, not serialized recovery or an ecosystem run.
Final ledger tests took 0.63s Release and 7.62s ASan locally; not controlled
performance measurements. Existing particle goldens remain unchanged.
Allocation-failure injection, durable ledger recovery and cross-ledger ownership
are not tested or implemented. Rates and conversions are absent, so rounding
residuals cannot occur in this transfer-only scope. Linux CI is pending source push.