9.2 KiB
M6.1 environmental units and coupling contract
Authority: ADR-0050, energy model, 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.
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 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.