139 lines
9.2 KiB
Markdown
139 lines
9.2 KiB
Markdown
# 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.
|