Add atomic conserved energy and elemental inventory ledger
This commit is contained in:
+5
-1
@@ -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
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user