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