3.9 KiB
[Reviewed]
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.