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
@@ -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