# Energy and matter accounting Locked: explicit biological costs and conservation. Ledger structure is recommended; coefficients/solvers are experiments, not claims of biochemical accuracy. M0 particles do not implement this model. | Quantity | Convention | |---|---| | Usable/source/work/heat energy | J inventories; W reported rates; explicit fixed-point quantum if adopted | | Material | kg or scaled mass; validated element composition | | Elements/nutrients | kg of specified element; mol requires explicit identity and conversion | | Temperature | K; intensive state, not conserved inventory | | Population | Nonnegative integer individuals or separately typed expected count | Material and its element composition are two views of the same matter, not additive inventories. Conserve an explicit 'other' component if the chemical basis is simplified. Reserve and structural chemical energy must not double count ingestible energy. Work may immediately become heat in a simplified model; it then cannot also remain available as mechanical energy. For each closed accounting interval: `E_end = E_start + external_input - exported_energy - unmodeled_heat_loss`. If heat is modeled, include its reservoir in E_end instead of that loss term. For every element k: `M_end[k] = M_start[k] + imported[k] - exported[k]`. Totals include environment, organisms, eggs/spores/cohorts, corpses, transfer escrow and suspended organisms. Death/reproduction/conversion are transfers. Atmospheric release is a transfer when atmosphere is modeled, otherwise an explicit boundary export. Light/geothermal flux is finite per area/interval; chemosynthesis consumes finite potential or recorded geological replenishment. `reserve_next = reserve + assimilation + capture - maintenance - locomotion - construction - reproduction - exported_reserve`. Every term has a counterpart. Unmet costs trigger the defined starvation policy, never a negative reserve or implicit loan. Overflow/excess follows named outputs. ```mermaid sequenceDiagram participant B as Biology participant L as Tick ledger participant R as Inventory owners B->>L: Propose(action ID, debits, credits, costs) L->>L: Validate dimensions, composition, bounds and phase L->>R: Reserve balances in stable order alt Sufficient resources L->>R: Commit balanced transfer exactly once L-->>B: Outcome and phenotype/lifecycle changes else Insufficient or stale L-->>B: Reject or explicitly quantified partial consumption end ``` The ledger is an in-process deterministic buffer, not a remote service or database write per transfer. Initial canonical entity/action allocation order introduces priority bias: measure against fair-share alternatives before tuning. Randomized fairness requires a purpose-specific recorded stream. Costs and outputs commit together; retries cannot double-spend. Partial ingestion is a declared quantity, not partially published offspring. Checked integer arithmetic carries division residuals. Floating-point solvers require finite checks, fixed reduction order and declared absolute/relative error budgets. Never conceal failed conservation by clamping balances. A density field is a view of owned finite inventory; consumers contend for that inventory. | Process | Debit → credit / limitation | |---|---| | Capture | finite flux + substrate → reserve/production + loss; area/efficiency bound | | Feeding | prey/resource matter + reserve → assimilation + waste + heat; ingestion bound | | Maintenance/movement | reserve → work/heat; phenotype demand and fixed interval | | Growth | material + reserve → structure + heat; developmental plan | | Reproduction | funded parent/environment inventory → offspring investment + heat | | Death | live compartments → corpse/detritus exactly once | | Decomposition | detritus + reactants → nutrients/chemical outputs/heat; rate/reactant bound | M2 uses explicitly synthetic founder fixtures, not unrelated wildlife in a persistent world. A simplified decomposition basis must balance completely; scalar biomass-to-nutrients is not full elemental chemistry. Expose source inputs, inventory/sink totals, unmet maintenance, failed transfers and per-element residuals. Distinguish cumulative quantities/rates; IDs are not metric labels. Tests: closed-box conservation, finite-source exhaustion, predation with waste, starvation nonnegativity, reproduction rollback, exactly-once death/decomposition, competing consumers, long-run rounding, overflow/NaN rejection, cross-tier escrow 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. ## Implemented M2.2 synthetic producer [ADR-0025](../adr/0025-finite-producer-process.md) defines the independent `evo::processes::ProducerProcess` fixture. It owns four reservoirs and exposes only read-only balances and exact-next-tick advancement. Source energy and C/N/P/other substrates are finite opening inventories. Capture divides actual source uptake between reserve and heat. Growth moves a configured whole recipe from substrates to structure and its energy cost from reserve to heat. The API cannot reuse heat. ```mermaid flowchart LR S[Finite source energy] -->|rate-limited capture| R[Producer reserve] S -->|conversion loss| H[Heat] N[Finite substrates] -->|funded recipe units| B[Producer structure] R -->|growth energy cost| H ``` Rates are rational inventories/recipe units per integer tick count. Independent carried remainders preserve capture, growth and efficiency fractions. Unfunded whole quotas expire; no starvation debt or future burst accumulates. Remainders and tick advance only after the ledger transaction succeeds. Arithmetic uses quotient/remainder decomposition, not overflow-prone numerator multiplication. This is a synthetic process, not a biological founder or organism. Its parameters do not select photosynthetic chemistry, area, metabolic efficiency, world time or the final units library. No producer state is attached to the particle world, serialized, connected to PostgreSQL or deployed. Later persistent integration must include config, reservoirs, tick and all three remainders in one checkpoint. ## Implemented M2.3 shared feeding fixture [ADR-0026](../adr/0026-shared-feeding-community.md) introduces `FeedingCommunity`, owning one producer and up to 16 consumer capabilities in a single ledger. The producer's standalone interface remains unchanged. A narrow private ownership boundary permits orchestration without exposing arbitrary inventory writes. Each tick stages producer activity, then at most one feeding request per consumer in ascending host sequence. Intake limits apply per inventory channel, and a request must be fully available. Assimilated quantities go to the consumer, unassimilated energy to heat, and unassimilated matter to a finite waste reservoir. Every quantity has a counterpart. Floor rounding in feeding goes to real waste/ heat, unlike the producer's carried capture entitlement; see the ADR for scope. A depleted target becomes inactive only when all its inventory is consumed. It cannot act, be targeted or restart capture. This is a terminal synthetic trigger, not a biological death model. Whole-community staging ensures failed feeding rolls back producer progress, earlier bites, terminal flags and ledger outcomes. The host submits trusted co-located intentions; spatial reach, authenticated input, partial injury, corpses, decomposition and actual organism ancestry are absent. ```mermaid flowchart LR P[Producer or consumer target] -->|assimilated energy and matter| C[Consumer] P -->|unassimilated energy| H[Heat] P -->|unassimilated matter| W[Waste inventory] ``` ## Implemented M2.4 terminal inventory and decomposition [ADR-0027](../adr/0027-terminal-inventory-and-decomposition.md) extends community ticks with trusted terminal facts before producer activity. The dead process's existing inventory becomes its corpse; no extra copy is created or discarded. `corpse(id)` exposes a value only for inactive process IDs. Dead actors never capture, grow or feed again, and their identity remains after decomposition. After feeding, inactive reservoirs in ID order and then waste share one configured per-tick inventory budget. Drained energy goes to heat and each elemental mass goes unchanged to nutrients. Zero caps disable channels. This is a synthetic transport model, not decomposition chemistry or an autonomous microbial lineage. Returned nutrients can fund producer growth next tick. Default caps are zero, preserving earlier fixture behavior; all new state participates in tick rollback. ```mermaid flowchart LR A[Active process inventory] -->|terminal state, same owner| C[Corpse inventory] C -->|bounded energy release| H[Heat] C -->|bounded elemental return| N[Nutrients] W[Waste] -->|remaining shared budget| N N -->|next tick growth| P[Living producer structure] ``` Host terminal events do not define health, starvation, combat, age or player death causes. Corpse scavenging, live-world lineage history, persistence and reproduction remain outside this increment. No physical inventory disappears on death. ## Implemented M2.5 funded reproduction [ADR-0028](../adr/0028-funded-reproduction.md) closes the fixture cycle. A bounded list of trusted `ReproduceIntent` records runs after feeding and before decomposition, so a consumer can fund offspring with what it ingested in the same tick and a process terminated in that tick cannot reproduce at all. The intent names a withdrawal from the parent reservoir. A fixed construction fraction in thousandths splits it with the same quotient decomposition feeding uses: the quotient endows the child, the energy remainder becomes heat and the matter remainder becomes waste. Construction overhead is owned inventory, not rounding loss. Nothing is credited from outside the community, so the conserved totals are identical before and after a birth. Reserved slots are allocated at creation and hold empty reservoirs until a funded birth activates the lowest-numbered one. Capacity exhaustion rejects the tick; it never funds a smaller child. A slot never returns to the unborn state, so process identities are not reused and a parent reference plus origin tick outlives both organisms and survives decomposition of the corpse. ```mermaid flowchart LR F[Ingested matter and energy] --> R[Parent reservoir] R -->|endowment| C[Child reservoir] R -->|construction overhead| H[Heat] R -->|construction overhead| W[Waste] C -->|next tick| A[Feeding, death and decomposition] ``` A child duplicates the configuration of its parent because no genome exists yet. This is duplication, not heredity, and no trait varies between generations. Reproductive strategy, fecundity, juvenile viability, gestation, spatial placement and account ownership are not defined here. No inventory is created on birth. ## Implemented M2.6 measured episodes [ADR-0029](../adr/0029-ecosystem-driver-and-episodes.md) adds `EcosystemEpisode`, a deterministic driver that owns one community and one seeded stream, holds no inventory and performs no transfers. It reads committed state and emits the terminal, feeding and reproduction intents the earlier increments already accept. No simulation contract changed to make the cycle run unattended. Two limits shape the harness. Identities are never reused and slots are capped, so one community supports a bounded number of consumer lifetimes and is not a population. No maintenance cost exists, so a consumer that is never eaten never dies. The harness therefore measures many bounded episodes rather than one long community, and mortality comes only from predation, where a bite takes a target's whole remaining balance, and from a configured lifespan delivered as a host terminal fact. Lifespan bounds the episode; it is not senescence or a death cause. ```mermaid flowchart LR N[Nutrients] --> P[Producer structure] P -->|bite| C[Consumer reserve] C -->|funded endowment| O[Offspring] C -->|lifespan or predation| D[Corpse] O --> C D -->|bounded decay| N C -->|assimilation loss| W[Waste and heat] W --> N ``` The driver must never submit a batch the community rejects, so it probes a discarded copy to size bites against the state feeding will actually see, claims each target for one feeder, and excludes a bitten consumer from acting that tick. A rejected tick is reported as a driver defect rather than absorbed as ecology. Conservation is checked at every tick across seeded ensembles, and each episode reports births, both mortality paths, extinction tick, surviving lineages and a fingerprint. Conservation holding over a million ticks demonstrates arithmetic, not ecological plausibility. Strategy constants, lifespans and the targeting rule are chosen inputs, not derived biology, and must not become gameplay by having been measured. Real populations still require M4 aggregation. ## M5.5 terrain volume boundary [Transactional excavation](../world/TERRAIN_EDITS.md) conserves occupied volume by material between terrain fill and a finite debris inventory. VolumeUnits uses 1/65535 m^3 at the experimental 1m pitch, not femtograms. No conversion into the biological ledger is allowed until M6 specifies density/composition and reconciles both representations. Debris is the destination of removed terrain, not new matter. ## M6.1 environmental units contract [ADR-0050](../adr/0050-environmental-units-and-coupling.md) and [ENVIRONMENTAL_UNITS.md](../world/ENVIRONMENTAL_UNITS.md) ratify the bounded M6 basis: pJ, fg of disjoint C/N/P/other, explicit water/organic/mineral compartments, exact derived concentrations/moisture, and a 2D habitat's explicit effective depth. Checked geometry and energy integration helpers own no stock. Finite source budgets, residual ownership, interval identity and atomic debit/credit remain obligations of M6.2-6.7. Water is conserved `other` in a distinct compartment; this does not authorize converting it into edible material or modeling reactions. Bulk terrain-to-mass conversion remains unsupported pending density/composition and an atomic representation transfer. No existing ledger or biological rules change. M6.2 [optional fields](../world/ENVIRONMENTAL_FIELDS.md) now hold explicit water, dissolved N/P, organic matter/energy, incident-energy and heat inventories. Material defaults provide capacity, never supply. Local transfers can only relocate the same channel; water cannot become organic other. Field snapshots preserve depletion. No rate source, biochemical conversion or transfer to organisms exists yet. ## Environmental transfer boundary (M6.4) The [coupled owner](../world/ENVIRONMENTAL_TRANSFERS.md) retains ten resource tags across environment and organism endpoints. Its Inventory is a derived report, not another spendable ledger. Water cannot turn into organic matter, and incident energy or heat cannot turn into usable energy through this adapter. M6.5 must supply explicit biological conversion rules and lifecycle validation; M2 Ledger invariants remain intact. ## M6.5b specified conversions [Environmental process v1](ENVIRONMENTAL_PROCESS.md) specifies capture, synthetic growth and feeding against tagged world stocks. Dissolved N/P may be incorporated into the matching organic element; water stays water. Carbon/other are prepaid organic inputs, not inferred atmospheric or geological supply. Source quota failure freezes its residual while the outer tick may report resource-limited progress. No maintenance, reproduction or starvation mortality rule is added. This is a contract for M6.5c, not an implemented live-world biological process.