Complete M6.1 environmental units and coupling contract
This commit is contained in:
@@ -0,0 +1,133 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user