Complete M6.1 environmental units and coupling contract
This commit is contained in:
@@ -305,6 +305,11 @@ later client, but no rendering is required. Ecological results and failure regim
|
||||
are reported separately from arithmetic. Unsupported distributed transfers remain
|
||||
rejected rather than simulated with untracked remote credits.
|
||||
|
||||
M6.1 ratifies [environmental units and coupling](world/ENVIRONMENTAL_UNITS.md)
|
||||
under ADR-0050. Pure checked habitat/ratio/energy-integration helpers and dimensional
|
||||
tests are implemented. No environmental stock, field codec, source scheduler or
|
||||
terrain-to-biological-mass converter is implemented by this gate. Next: M6.2.
|
||||
|
||||
## M7 - Persistent region server
|
||||
|
||||
**Goal:** a disposable authoritative headless process can recover a bounded region
|
||||
|
||||
+15
-3
@@ -1,13 +1,13 @@
|
||||
# Project status and next steps
|
||||
|
||||
Updated 2026-09-26. The repository contains an engineering foundation and a
|
||||
Updated 2026-09-27. The repository contains an engineering foundation and a
|
||||
deterministic headless proof. It does not yet contain cellular gameplay or a
|
||||
persistent simulation server. The founding vision remains unchanged.
|
||||
|
||||
## Completed implementation
|
||||
|
||||
- Vision, architectural pillars, risks, open-question register, architecture
|
||||
diagrams, biological contracts, engineering constitution and 49 ADRs.
|
||||
diagrams, biological contracts, engineering constitution and 50 ADRs.
|
||||
Proposed/deferred choices remain distinct from accepted proof decisions.
|
||||
- M0–M4 task breakdowns with dependencies, acceptance evidence and risks,
|
||||
plus M5–M14 gates in [ROADMAP.md](ROADMAP.md).
|
||||
@@ -61,7 +61,7 @@ for the bounded proof; the general production ECS remains a later measured choic
|
||||
|
||||
| Priority | Work | Completion evidence |
|
||||
|---|---|---|
|
||||
| 1 | M6.1 environmental units and coupling contract | Define habitat mapping, resource units and volume-to-matter accounting before biological coupling |
|
||||
| 1 | M6.2 optional environmental fields | Finite versioned inventories, sparse field pages and round-trip persistence without regenerated supply |
|
||||
| Research | Improve aggregate fidelity and measure Linux/target-host costs | M4.6 found no qualifying width; see the aggregate budget report |
|
||||
| 2 | Revisit the ADR-0031/0032 reproduction cost model | Reproduction is affordable only at the genome schema's floor; decide whether that is intended before M4 builds cohorts on it |
|
||||
| Delivery gate | Add/update the dev workload when a deployable increment needs it; Argo is ready | Observe Job/pod completion separately from image publication; no World0 changes |
|
||||
@@ -606,3 +606,15 @@ clean regeneration checks pass. [Measured costs and reproduction](engineering/WO
|
||||
record five Windows Release runs and explicit accounting/durability limits.
|
||||
No world format or simulation version changed. Next: M6.1 environmental units and
|
||||
coupling contract; Linux golden execution remains a CI confirmation.
|
||||
|
||||
## M6.1 environmental units and habitat coupling (2026-09-27)
|
||||
|
||||
ADR-0050 and [the units contract](world/ENVIRONMENTAL_UNITS.md) define bounded
|
||||
inventories, compartment identity, derived concentration/moisture, explicit habitat
|
||||
depth and residual ownership. Pure checked helpers measure one-voxel habitat boxes,
|
||||
form rational views and integrate energy-rate proposals without creating supply.
|
||||
Dimensional examples, invalid conversions, overflow, split intervals, closed/open
|
||||
accounting and refusal rollback are tested. Windows Release, clang-tidy and ASan
|
||||
suites pass; see VALIDATION.md for exact checks. Existing formats/goldens are unchanged.
|
||||
No fields or biological coupling are implemented yet. Next: M6.2 optional finite
|
||||
environmental fields with versioned persistence and explicit opening inventories.
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
# 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](../world/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.
|
||||
@@ -56,3 +56,4 @@ design. No unadopted candidate is a link dependency of the proof.
|
||||
|
||||
- [ADR-0048: Local publication](0048-local-publication.md) - accepted for M5.7 single-writer snapshot/journal publication and recovery.
|
||||
- [ADR-0049: Bounded world proof](0049-bounded-world-proof.md) - accepted for M5.8 restart regression and cost evidence.
|
||||
- [ADR-0050: Environmental units and coupling](0050-environmental-units-and-coupling.md) - accepted for M6's bounded habitat/accounting contract; no field storage or terrain conversion yet.
|
||||
|
||||
@@ -153,3 +153,13 @@ file publication and compaction; no production persistence dependency was added.
|
||||
M5.8 validates the local stack through separate prepare/compact/verify processes; see
|
||||
[bounded world proof and measurements](../engineering/WORLD_PROOF.md). This adds no
|
||||
production ownership or biological resource conversion contract.
|
||||
|
||||
## M6.1 environmental coupling boundary
|
||||
|
||||
[ADR-0050](../adr/0050-environmental-units-and-coupling.md) scopes a one-voxel,
|
||||
axis-aligned habitat with explicit micrometre depth. The
|
||||
[units contract](../world/ENVIRONMENTAL_UNITS.md) defines finite extensive stocks,
|
||||
derived concentrations/moisture, dimensional examples, closed/open accounting,
|
||||
rate residual ownership and rejection of unsupported terrain mass conversions.
|
||||
The implemented helpers are pure computations. Inventory pages, reservations,
|
||||
ownership enforcement, transfer commits and persistence follow in M6.2-6.4.
|
||||
|
||||
@@ -284,3 +284,16 @@ material between terrain fill and a finite debris inventory. VolumeUnits uses
|
||||
1/65535 m^3 at the experimental 1m pitch, not femtograms. No conversion into the
|
||||
biological ledger is allowed until M6 specifies density/composition and reconciles
|
||||
both representations. Debris is the destination of removed terrain, not new matter.
|
||||
|
||||
## M6.1 environmental units contract
|
||||
|
||||
[ADR-0050](../adr/0050-environmental-units-and-coupling.md) and
|
||||
[ENVIRONMENTAL_UNITS.md](../world/ENVIRONMENTAL_UNITS.md) ratify the bounded M6 basis:
|
||||
pJ, fg of disjoint C/N/P/other, explicit water/organic/mineral compartments, exact
|
||||
derived concentrations/moisture, and a 2D habitat's explicit effective depth.
|
||||
Checked geometry and energy integration helpers own no stock. Finite source
|
||||
budgets, residual ownership, interval identity and atomic debit/credit remain
|
||||
obligations of M6.2-6.7. Water is conserved `other` in a distinct compartment;
|
||||
this does not authorize converting it into edible material or modeling reactions.
|
||||
Bulk terrain-to-mass conversion remains unsupported pending density/composition
|
||||
and an atomic representation transfer. No existing ledger or biological rules change.
|
||||
|
||||
@@ -1649,3 +1649,37 @@ turn did not execute Linux, UBSan, physical power-cut, target-server or cluster
|
||||
checks. ASan is not UBSan. Process restarts are graceful; M5.7 fault injection
|
||||
remains separate coverage. No production durability or planet capacity claim.
|
||||
No Argo or World0 operation occurred. Next: M6.1 units and environmental coupling.
|
||||
|
||||
## M6.1 environmental units and coupling - 2026-09-27
|
||||
|
||||
Added ADR-0050, ENVIRONMENTAL_UNITS.md, checked local habitat geometry, exact mass
|
||||
concentration/water saturation and rational pJ/tick integration helpers. No field
|
||||
storage, density converter, source scheduler, gameplay or snapshot format changed.
|
||||
Terrain volume still cannot be credited as biological mass.
|
||||
|
||||
Executed on Windows x64 / MSVC 19.44:
|
||||
|
||||
- `tools/windows-check.ps1 -Preset release -Action check`: 49/49 passed.
|
||||
- `tools/windows-check.ps1 -Preset analysis -Action check`: clang-tidy 19 and
|
||||
49/49 passed.
|
||||
- `tools/windows-check.ps1 -Preset asan -Action check`: 49/49 passed.
|
||||
- After strengthening independent balance sums, open-boundary and rollback tests,
|
||||
reconfigured each preset, rebuilt `evo-environment-units-tests`, and ran
|
||||
`ctest --test-dir build/<preset> -R '^environment-units-contracts$' --output-on-failure`:
|
||||
passed in Release, analysis and ASan. Final code-only adjustment was an explicit
|
||||
cstddef include; CTest registration was grouped with other world tests.
|
||||
- `tools/windows-check.ps1 -Preset release -Action format`: passed.
|
||||
- `git diff --check`: passed.
|
||||
|
||||
Coverage includes each invalid box axis, zero/maximum inputs, exact dimensional
|
||||
examples, concentration/type separation, dry/saturated/excess water, multiplication
|
||||
and addition overflow, invalid denominators/residuals, and 78,660 repeated-addition
|
||||
oracle comparisons of split versus combined intervals. The closed/open accounting
|
||||
example uses a finite boundary reservoir, independently sums balances and verifies
|
||||
rejected overdraft leaves all balances unchanged. Documentation's large terrain
|
||||
mass example was checked using exact BigInteger division (1e21 / 65535).
|
||||
|
||||
Linux/UBSan and target-cluster checks were not executed locally; existing CI includes
|
||||
the new CTest. There is no new concurrency requiring TSan work. Helpers do not enforce
|
||||
owner identity, interval deduplication or residual persistence; those remain explicit
|
||||
M6.2-6.7 obligations. No deployment or World0 operation occurred. Next: M6.2.
|
||||
|
||||
@@ -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