Files
aevolution/docs/adr/0050-environmental-units-and-coupling.md
2026-10-08 12:08:53 -04:00

3.5 KiB

[Reviewed]

ADR-0050: Bounded environmental units and ecological coupling

Status

Accepted for M6's local experiment. Habitat size, depth, material coefficients and source strengths are fixture inputs, not locked biological or planetary rules.

Context

M5 conserves terrain volume. M2 accounts in picojoules and femtograms of C/N/P/other. Neither concentration nor a material identifier is an owned supply. A 2D habitat needs explicit depth before it can exchange quantities with 3D environmental stores. The ledger's roughly 18.45 kg per-channel bound cannot cover planetary rock masses.

Decision

Adopt ENVIRONMENTAL_UNITS.md. Retain M2 quanta for the bounded environmental experiment, with disjoint water, dissolved N/P, organic and mineral compartments. Tags partition inventories; they never add a second mass. Water belongs to other in this simplified basis and cannot be relabeled as edible other matter. No water chemistry or automatic extraction from rock is authorized.

Use integer micrometre extents and explicit effective depth, giving cubic-micrometre habitat volume. Initial mapping is one axis-aligned box inside one local 1m voxel; larger/cross-cell mappings require a later extension with explicit disjoint shares. Read concentration and saturation as exact rational views, never spendable balances. Carry fractional source-rate residuals under the source/interval owner; integrated energy is a requested transfer from a finite source, never permission to mint energy.

Implement only pure checked geometry/ratio/energy-integration helpers in evo::world and dimensional tests now. No field pages, organism adapter, rate scheduler, density conversion or new snapshot format. M6.2 owns field persistence; M6.4 owns atomic transfers. M5 geometry/debris remain separate until an explicit versioned density, composition and conversion transaction can debit one representation and credit the other together. Reject unsupported conversions rather than invent coefficients.

Alternatives Considered

Area-only coupling manufactures volume; arbitrary density-to-balance writes duplicate supply. Floating balances need tolerance/error accounting. A general units library remains an evaluation under ADR-0009; a few opaque quantities with explicit functions need no new dependency. Kilogram-scale coarse ledgers are appropriate later, but silently changing M2 units would invalidate existing biology and snapshots.

Benefits

Explicit dimensions, exact conservation, bounded arithmetic and no implicit resource creation. The small API can be tested independently of field storage and biology.

Costs

The proof cannot model a full voxel of dense rock in one ledger. Sub-micrometre geometry, arbitrary rotations, cross-cell habitats and reactions remain unsupported. Source integration conservatively rejects overflowing numerator intermediates even when division could have reduced the result; callers must use bounded intervals.

Risks

Conserved C/N/P/other does not establish chemical feasibility. Reusing other without compartment validation could make water edible. Overlapping habitat reservations or discarding fractional state could create supply despite dimensionally correct code.

Consequences

Public contracts distinguish computations from authorization. M6.2-6.4 must persist units/version, mapping, compartments, source residuals and ownership atomically, and reject mismatched versions or incomplete fields. No existing golden, generator, simulation law or world format changes in M6.1.