Files

17 KiB

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.

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

// 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 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.

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

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

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

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

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 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 and 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 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 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 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.