# M6.1 environmental units and coupling contract Authority: [ADR-0050](../adr/0050-environmental-units-and-coupling.md), [energy model](../biology/ENERGY_MODEL.md), ADR-0024 and ADR-0046. This is a bounded local experiment. Physical coefficients require separately versioned fixtures. ## Inventory basis and ranges | Quantity | Representation / range | Ownership and meaning | |---|---|---| | Energy | u64 picojoules, 1 pJ = 1e-12 J | Finite incident source, usable reserve, chemical potential, heat, export compartments; each joule counted once | | Matter | u64 femtograms, 1 fg = 1e-18 kg | Disjoint C, N, P, other; total mass is their sum, not another account | | Water | fg of water in a dedicated compartment | Entire simplified water mass is `other`; not a fifth additive element | | Dissolved nutrients | fg of elemental N and P in named compartments | Not kilograms of unspecified salts; counterions, when introduced, require explicit other mass | | Organic matter | C/N/P/other bundle plus separately owned chemical energy | Biomass is a derived sum; no second spendable biomass field | | Mineral matter | C/N/P/other bundle only after explicit conversion | Rock/regolith ID is not nutrient availability or mass | | Habitat geometry | integer micrometres, extents 1..1,000,000 each | Effective volume = width * height * depth, 1..1e18 um^3 (1e-18..1 m^3) | | Concentration | exact fg / um^3 rational | Read-only derived value; zero mass valid, zero volume invalid | | Moisture | exact water mass / water capacity rational, 0..1 | Capacity is a fixture property, not supply; excess needs another compartment, not clamping | | Temperature | kelvin, future validated field | Intensive; does not mint energy; thermal capacity/heat model deferred | The u64 ceiling is 18,446,744,073,709,551,615. ADR-0024 requires the global sum of each channel in a ledger to fit, including finite sources, sinks, organisms, corpses and escrow. This is about 18.45 MJ and 18.45 kg per mass channel, not a whole-world range. Computing a total across channels also requires checked sums. No saturation or silent wrap is permitted. Unavailable fields are errors/absence, never zero or infinite supply. Public aggregate wrappers do not validate construction; helpers do. Water/organic/mineral tags partition existing elemental balances. A transfer must validate both the elemental bundle and compartment identity. Water cannot be spent as organic `other`, nor can dissolved N be obtained merely by retagging rock. M6 does not model splitting water or chemical reactions. Water uptake/return is an explicit transfer of the same water; it stays in conservation totals while inside an organism. Destruction, conversion and phase change require their own contracts. ## Mapping 2D habitat to 3D ownership For M6, a habitat descriptor identifies world/frame, voxel, local origin in integer micrometres, width/height/effective depth, mapping version and owner. Axes align with local X/Y/Z, +Z up. Every origin is in [0,1,000,000); every half-open box must fit in its 1m voxel. `measure_habitat` validates the local box; voxel/world identity and reservation overlap belong to the future field owner. The returned area is width * height; volume is area * effective depth. No camera size or organism count changes that volume. This is ecological sampling geometry, not shared collision physics. ```mermaid flowchart LR V[Finite environment owner] -->|reserve disjoint inventory share| H[2D habitat with explicit depth] H -->|balanced transfer| O[Organism inventories] O -->|death and bounded decay| V V -. concentration and moisture views .-> H ``` Multiple habitats may read the same environment, but must either contend for the same owner or own nonoverlapping reserved inventory shares. A copied view cannot authorize a debit. Refinement partitions existing inventory; coarsening sums it. Changing depth or area is a mapping transaction, not `concentration * new volume` credited as new supply. Reject cross-voxel mappings in this version. M6.4 must commit source debit, destination credit, mapping/revisions and retry outcome together. Example: width=1000 um, height=2000 um, depth=10 um gives area=2,000,000 um^2 and volume=20,000,000 um^3 = 2e-11 m^3. A fixture density of 1000 kg/m^3 would give 20,000,000 fg of water. This is an illustrative density, not an adopted universal coefficient or opening-balance factory. 200 fg N in that volume is 1/100000 fg/um^3 = 0.01 kg/m^3. A water mass of 5,000,000 fg against capacity 20,000,000 fg yields moisture 1/4. Dry with positive capacity is zero; zero capacity is undefined and rejected even when dry. Supersaturation must use explicit free water, not clipping. This concentration uses the full effective habitat volume (a bulk concentration), not solvent volume or molarity. A future dissolved-phase query must name its own positive solvent volume explicitly; drying cannot silently switch denominators. ## Energy, intervals and residuals Incident power has dimensions J/(m^2 s). Integrate over explicit projected capture area and the world's fixed interval; shadow/efficiency cannot increase the input. Overlapping surfaces cannot each claim the same photons. M6.5 must derive an area-budgeted rational pJ/tick rate; it is not a second independent energy source. For example 1 W/m^2 * 2e-6 m^2 * 0.05 s = 100000 pJ per interval. `integrate_energy(rate, ticks, residual)` computes `(rate.numerator * ticks + r) / d` and its remainder, where rate is rational pJ/tick and `0 <= r < d`, `d > 0`. Inputs and numerator intermediate must fit u64. Zero rate/ticks is valid. Reject overflow before multiplication/addition, including cases whose final quotient could fit. Output is a proposal, not credited energy. A changed denominator invalidates the old residual unless explicitly converted with exact accounting. The future source owner persists denominator, numerator, residual, last integrated tick and version; a caller cannot reset residual on restart, duplicate an interval or reuse it under another source. If the transfer cannot be funded, commit neither the proposed new residual nor the interval watermark; no repeated retries accrue supply. At 5/3 pJ/tick, six ticks yield 10 pJ exactly; six single ticks yield the same result with carried remainders. Fractional remainder r/d is sub-quantum unissued entitlement against the same finite source, not extra energy added to source+destination totals. Splitting/refining a source must partition that entitlement exactly. M6.1's helper does not own or persist it; M6.2/6.7 must not omit it from their state contracts. For a closed system, sum E and each element over all owners at end equals start. With boundaries: `E_end = E_start + imports - exports`; similarly for each element. Heat is an owned sink or an explicit export, never both. Capture transfers finite incident energy to usable energy + heat/unabsorbed outputs. Chemosynthesis consumes owned chemical potential, never free energy inferred from material presence. Example: source=100 pJ, reserve=0, heat=0; capture transfers 30 to reserve and 20 to heat, leaving source=50. All three sum to 100. An imported 7 raises the open-system total to 107 only with a recorded boundary import (not exposed by the current ledger). ## Terrain conversion boundary M5 volume unit = 1/65535 m^3. With an explicitly supplied density rho kg/m^3, mass in fg is `volume_units * rho * 1e18 / 65535`. Density and elemental composition must be versioned rational values with exact carried residuals per material owner. Converting each cut independently and discarding its remainder is forbidden. For rho=1000, one volume unit corresponds to 15259021896696421 fg plus 49765/65535 fg; 65535 units together give 1e21 fg, beyond a single M2 channel. This overflow is a scope boundary, not permission to clamp or change units. M6 has no converter yet. Terrain/debris volume and converted mass are alternate representations of the same matter: an eventual conversion must remove/escrow the converted volume and atomically credit its mass/composition, including residuals. It cannot leave the debris spendable. Initial environmental field inventories are explicit, finite, separately attributed openings (e.g. pore water); they cannot also be counted in a converted solid density. Generator material IDs alone provide neither opening supply nor regeneration rights. ## Implemented versus deferred `include/evo/world/environment_units.hpp` exposes pure local box measurement, exact concentration/moisture views and checked energy-rate integration. Tests check units, limits, split intervals and independently balanced examples under NDEBUG. These functions grant no access to stocks, create no field pages and change no snapshots. M6.2 introduces optional fields, explicit initial inventories and versioned persistence; M6.3 read views; M6.4 coordinated ownership/transfer validation; M6.5-6.8 integrated processes, source budgets and replay. Density/composition conversion, chemical reactions, global atmosphere/hydrology and cross-region transfer remain unsupported. M6.2 now implements [optional fields](ENVIRONMENTAL_FIELDS.md) and independent field snapshots under ADR-0051. Incident energy is finite stock only; no configured rates or fractional source state exist in field format v1. Enabling rates will require explicit versioned residual/interval persistence before any integration can commit.