Define M6.5b environmental process conversions and ownership

This commit is contained in:
dingo
2026-09-27 09:39:51 -04:00
parent 53e4037587
commit e9ea388cef
8 changed files with 330 additions and 2 deletions
+6
View File
@@ -445,3 +445,9 @@ Accepted 2026-09-27: ADR-0054 brings coupled snapshot/restore into M6.5. M6.5a's
resource codec is implemented; the earlier pending-scope statement is superseded.
Next are 6.5b conversions, 6.5c complete rate/biology persistence and fixture, and
6.5d qualification. M6.8 retains the full decomposition/regrowth ecology gate.
M6.5b design complete (2026-09-27): [ADR-0055](adr/0055-environmental-process-contract.md)
and the [process contract](biology/ENVIRONMENTAL_PROCESS.md) specify conversions,
source residual policy, temperature gates, synthetic depletion and private resource
checkpoints with process retry history. Next: M6.5c implementation/persistence,
then M6.5d qualification. No rate-enabled runtime exists yet.
+16 -2
View File
@@ -7,7 +7,7 @@ persistent simulation server. The founding vision remains unchanged.
## Completed implementation
- Vision, architectural pillars, risks, open-question register, architecture
diagrams, biological contracts, engineering constitution and 54 ADRs (including the proposed M6.5 prerequisite).
diagrams, biological contracts, engineering constitution and 55 ADRs (including the accepted M6.5 persistence and process contracts).
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.5 couple producer/consumer biology | Finite environmental supply, explicit conversions and lifecycle checks through the coupled owner |
| 1 | M6.5c implement persisted producer/consumer fixture | Complete rate/biology envelope, then atomic process stepping under ADR-0055 |
| 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 |
@@ -677,3 +677,17 @@ Next: M6.5b explicit capture/growth/feeding conversion contract, followed by M6.
complete source-rate/biology envelope and M6.5d qualification. No rates are enabled
by the resource codec; no source progress is invented during restore. M6.5 as a
whole remains incomplete. Durable publication and region recovery remain M7.
## M6.5b process contract (2026-09-27)
Completed the design segment under ADR-0055 and
[ENVIRONMENTAL_PROCESS.md](biology/ENVIRONMENTAL_PROCESS.md). The contract defines
finite area-bounded capture, explicit nutrient incorporation, retained water,
organic feeding with heat/waste, exact source/growth residual policies and the
process-owned checkpoint/retry boundary. Hand-calculated vectors make each flow
reviewable. No new runtime code, executable rate integration or schema changed.
Next: M6.5c implements the fixture and complete source-rate/biology snapshot before
exposing advance; M6.5d qualifies it. M6.5 remains incomplete. M2/M3 maintenance,
reproduction and mortality behavior is unchanged; resource starvation is reported
without inventing a new death policy.
@@ -0,0 +1,73 @@
# ADR-0055: Bounded environmental producer/consumer contract
## Status
Accepted for the M6.5b design segment, 2026-09-27. Rules version 1 is a synthetic
fixture, not gameplay chemistry, a species classification or live-world founder policy.
Runtime implementation and complete process persistence are M6.5c; qualification is
M6.5d. No existing M2/M3 implementation or simulation version changes here.
## Context
ADR-0053 moves identical compartments only. Producer capture needs an explicit
incident-energy conversion, growth incorporates dissolved nutrients, and feeding
moves owned biomass between organisms. Merely copying balances into M2's Ledger
would duplicate spendable inventory. Its untagged `other` also cannot distinguish
water from food. ADR-0054 requires the entire process state to be restorable before
rate-driven execution. M6.5a resource snapshots provide a foundation, not that state.
## Decision
Adopt [ENVIRONMENTAL_PROCESS.md](../biology/ENVIRONMENTAL_PROCESS.md). Add a separate
bounded process owner in evo::processes, depending on evo::world and existing biology
contracts. The world library must not depend on process, genome or lifecycle types.
Retain one authoritative set of resources, with detached candidates only while a
whole tick is prepared. Expose read-only resource views, never a mutable owner.
Use one habitat, one configured producer capability and one configured consumer
capability for this fixture. All opening inventory and source identity are explicit.
Use prepaid organic carbon/other and dissolved N/P for a synthetic growth recipe;
this is not complete photosynthesis. Water is taken up and retained separately.
Capture converts finite incident energy into organic reserve and heat. Feeding
consumes only organic compartments, with M2's declared assimilation/waste split.
The source's rate is area-bounded, rational and immutable. A positive quota that
cannot be fully funded does not change its residual or last funded interval. The
outer tick may still commit other work and a source-unfunded report; it never
catches up the rejected source interval. This explicitly scoped rate policy differs
from M2's min(quota, stock) capture; M2 remains unchanged.
No maintenance debit, starvation mortality, reproduction, mutation, decomposition,
thermal injury or player logout policy is added in M6.5. Preserve existing budget
helpers as pure proposals. Source starvation means measured lack of capture/growth,
not an invented terminal transition. The fixture is autonomous experimental biology,
not a host for offline player organisms. M6.6 adds terminal events and corpse decay.
## Alternatives Considered
A public generic retag operation could turn water into food or recycle heat.
Independent field and process commits risk double-spending. Reusing M2's ledger as
a cache creates two authoritative inventories. Adding dissolved carbon or complete
redox chemistry is premature for this integration gate. Using preallocated organic
carbon is explicit and testable, with its biological limitation clearly named.
M6.4 transfer history cannot generally be reversed through subsequent conversions.
Keep process retry history in a versioned outer envelope and use private resource
checkpoints without claiming that old transfer-only receipts describe process ticks.
Do not weaken the M6.5a history validator to accept impossible transfer histories.
## Benefits
Finite, conserved, tagged flows; exact rounding; clear persistence and ownership;
existing producer/feeding behavior remains independently reproducible.
## Costs
A new restricted process transaction and outer codec are necessary. Synthetic
prepaid carbon is not a self-sustaining autotrophic carbon cycle. One habitat and
two actors cannot establish scalable ecology or fairness.
## Risks
Conservation does not imply chemical plausibility. Coefficients, temperature bounds
and area choices could be mistaken for game laws. Every fixture stores a rules
version and explicit config; no default wildlife or hidden resource supply.
## Consequences
M6.5c must implement and test the full envelope before exposing advance. M6.5d must
check source-off, resource limits, temperature boundaries, retries, rollback and
restored seeded continuation. Durable publication remains M7. No dependency or
schema implementation is introduced merely to make the repository appear complete.
+1
View File
@@ -61,3 +61,4 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0052: Environment views](0052-read-only-environment-views.md) - accepted for M6.3 bounded read-only footprint queries and freshness validation.
- [ADR-0053: Atomic environmental transfers](0053-atomic-environmental-transfers.md) - accepted for M6.4 tagged resource ownership, atomic local batches and bounded exact retries.
- [ADR-0054: M6.5 source persistence prerequisite](0054-m65-source-persistence-prerequisite.md) - accepted: coupled codec brought forward into M6.5; M6.5a implemented, rate/biology envelope follows.
- [ADR-0055: Environmental process contract](0055-environmental-process-contract.md) - accepted M6.5b synthetic conversions, source interval policy and process checkpoint boundary; implementation follows in M6.5c.
+9
View File
@@ -103,3 +103,12 @@ tracing are measured outside the simulation.
explicit operations requirement, not a benefit Kubernetes provides by itself.
See persistence, network and infrastructure architecture for detailed contracts.
## M6.5b environmental process boundary
[ADR-0055](../adr/0055-environmental-process-contract.md) specifies a separate
process fixture that privately owns tagged world resources and process progress.
The process library may depend on world; world must not depend on process or genome
code. Only constrained process operations may create private resource checkpoints.
Complete rate/biology persistence precedes executable stepping in M6.5c. Existing
M2 process interfaces and results remain unchanged.
+10
View File
@@ -311,3 +311,13 @@ across environment and organism endpoints. Its Inventory is a derived report, no
another spendable ledger. Water cannot turn into organic matter, and incident energy
or heat cannot turn into usable energy through this adapter. M6.5 must supply explicit
biological conversion rules and lifecycle validation; M2 Ledger invariants remain intact.
## M6.5b specified conversions
[Environmental process v1](ENVIRONMENTAL_PROCESS.md) specifies capture, synthetic
growth and feeding against tagged world stocks. Dissolved N/P may be incorporated
into the matching organic element; water stays water. Carbon/other are prepaid
organic inputs, not inferred atmospheric or geological supply. Source quota failure
freezes its residual while the outer tick may report resource-limited progress.
No maintenance, reproduction or starvation mortality rule is added. This is a
contract for M6.5c, not an implemented live-world biological process.
+201
View File
@@ -0,0 +1,201 @@
# M6.5 environmental process contract v1
Authority: ADR-0055, ADR-0054, environmental units (ADR-0050), and the scoped
producer/feeding rules (ADRs 0025/0026). **Specified, not implemented.** M6.5b is a
contract segment. M6.5c must implement this contract and the complete buffer codec
before advance is enabled. Coefficients below are fixture inputs, not game rules.
## Ownership and interface boundary
One `EnvironmentalCommunity` (working name) owns one coupled resource owner,
immutable configuration, progress and process retry receipts. Admission supports
one habitat site and exactly two sorted nonzero actor IDs. Producer and consumer
are configured capabilities, not inheritance classes or permanent species.
Resource state contains the ten existing Field compartments at the site and in
each actor. Heat and waste reside in the environment. No balances live in another
Ledger. Accounts cannot be removed or reset; all openings have explicit provenance.
Require all ten fields present, valid material binding and capacities, and a fresh
resource owner (command/adoption watermark zero and no history). Reject adopting a
previously advanced independent resource owner: migration is not implied.
Conceptual API, to be finalized with callers/tests in M6.5c:
- create(config, exclusively owned resources, total peak byte budget) -> expected owner;
- advance(exact next tick, immutable tick input) -> expected report;
- snapshot() -> complete canonical process envelope;
- restore(bytes, expected world, budgets) -> detached validated owner;
- inspect() -> read-only values/views, invalidated at publication.
No mutable resource getter, user-supplied resource delta, commit callback, external
credit/debit or independent process-state setter. Host access is single-writer.
The fixture does not admit player sessions; player suspension requires a later
explicit adapter and may not be treated as autonomous progress.
```mermaid
sequenceDiagram
participant H as Host
participant P as Process owner
participant C as Detached candidate
H->>P: exact tick + bounded input
P->>P: resolve retained exact retry or reject conflict
P->>C: clone complete owned state within peak budget
C->>C: capture then growth then feeding
C->>C: validate conservation, capacity, progress and report
P->>P: publish resources + progress + retry history (noexcept)
P-->>H: original or newly committed report
```
World code validates finite inventories, units/tags, endpoint membership and budgets.
Process code validates the permitted conversions, capability, phase and lifecycle.
A narrow private transaction boundary may accept only the named operations below;
it must not grant a public arbitrary retagging primitive. Use a bounded detached
candidate and nonthrowing publication as the correctness baseline. Charge old and
candidate resources, history, codec buffers used for cloning and scratch at peak.
Read views bind to the current owner; replacement invalidates old views. A failed
candidate leaves original owner identity, bytes, progress and receipts unchanged.
## Inputs and declared parameters
Config includes rules version, world/frame/site, actor IDs, source ID, positive
fixed tick duration in microseconds, projected capture area in square micrometres,
irradiance as rational pJ/(um^2 tick), capture efficiency in [0,1000], growth units
per positive tick denominator, positive growth energy cost, and a recipe of water
plus C/N/P/organic-other femtograms per unit. Require positive water, C, N and P
recipe amounts; organic-other may be zero. Require capture area >0 and <= habitat
area. One producer owns this area entitlement; no second overlapping source claim.
The integrated source rate is irradiance numerator * capture area / denominator.
Check multiplication before use; denominator is positive and remains unchanged.
Tick duration is metadata of the irradiance interval, not another multiplier.
Dimensional calibration: 1 W/m^2 = 1 pJ/(um^2 second). At 50000 us/tick over
2000000 um^2, rate = 100000 pJ/tick. Snapshot both primitive config and residual;
restore recomputes derived rate and rejects incompatible versions or overflow.
Tick input contains temperature in positive integer millikelvin, a source-enabled
flag, and zero or one consumer bite. These trusted fixture inputs are recorded in
full retry identity. They are not authenticated network commands. A bite requests
organic energy and C/N/P/other, never water, incident energy, heat or dissolved
nutrients. Require a nonzero bundle, each channel <= configured intake limit, and
sufficient producer stocks. Consumer assimilation is in [0,1000].
Temperature bounds are explicit inclusive fixture config with min<=max. Outside
bounds, skip capture/growth and freeze their residuals; do not infer heat, damage or
death. Consumer feeding is also disabled outside its declared bounds; a requested
bite then rejects the tick. This is a fixture capability gate, not an amendment to
M3's thermal-shortfall reporting. Config and rates cannot change during a run.
## Conversion table
Let E be captured pJ, q growth units, a assimilation fraction in thousandths.
All quantities are checked u64; globally summed energy/C/N/P/other must fit.
| Operation | Debit | Credit / rule |
|---|---|---|
| Capture | environment incident_energy E | producer organic_energy R; environment heat E-R |
| Growth carbon | environment organic_carbon q*C | producer organic_carbon q*C |
| Growth N/P | environment dissolved nitrogen/phosphorus q*N/P | producer organic_nitrogen/phosphorus q*N/P |
| Growth other | environment organic_other q*O | producer organic_other q*O |
| Growth water | environment water q*W | producer water q*W; stays water |
| Growth work | producer organic_energy q*cost | environment heat q*cost |
| Feeding organic energy | producer organic_energy B | consumer organic_energy floor(B*a/1000); environment heat remainder |
| Feeding each organic element | producer organic element B | same consumer organic element floor(B*a/1000); same environmental organic element remainder |
No incident-energy or heat compartment can directly fund growth or feeding. No
rock extraction, water splitting, element conversion or inorganic-carbon fixation.
Organic reserve includes all ingestible energy; there is no second structural-energy
balance. Growth units are an output counter, not additional spendable biomass or
M3 GrowthState. Structural M3 integration must account for its body transition and
rounding release separately, rather than relabel this recipe as a developed body.
Use quotient/remainder decomposition for efficiency arithmetic, avoiding B*a overflow.
Capture carries an efficiency remainder in [0,999], updated from funded capture only:
R=(E/1000)*a+((E%1000)*a+old_remainder)/1000. Store the new remainder modulo 1000.
The emitted E-R is heat. Feeding rounds down independently per channel, as ADR-0026;
all integer remainders are real waste/heat, not future entitlement.
## Interval and resource limitations
First outer tick is 1; accept only previous+1, reject exhaustion without wrap.
For enabled, temperature-eligible capture, integrate exactly one source interval
with the stored rate remainder. If E<=incident stock, transfer E (including zero),
commit the new source remainder and record this outer tick as last funded interval.
If E>stock, report source_unfunded and leave source remainder, efficiency remainder
and last funded interval unchanged. No partial capture. No stored debt/catch-up:
a later tick attempts one interval using the retained residual. Disabled or gated
capture also freezes source state. The outer tick can still perform affordable growth
or feeding from previously held inventory. Duplicate outer ticks never reintegrate.
This may strand stock smaller than a quota; report it rather than silently changing
rates. It is a declared synthetic limitation, not an energy loss.
Eligible growth derives quota/remainder as ADR-0025, then chooses the minimum of:
whole quota, producer reserve / cost, each available environmental recipe component
/ its positive recipe amount, and each remaining actor capacity / recipe amount.
Skip zero recipe components. Unmet whole units expire; fractional growth remainder
advances for eligible growth. Heat capacity is u64; conserved global energy bounds
its increase. Preflight products/sums and the complete candidate before mutation.
No maintenance or movement charge is added, and no reproduction action exists.
Producer capture/growth precedes the one consumer bite, as in M2. Insufficient bite
stock, invalid input, unsupported versions, arithmetic/budget failure or capacity
overflow rejects the entire tick, including earlier capture and growth. Feeding is
never silently reduced. Source-unfunded and nutrient-limited growth are reports,
not failed commands. Resource exhaustion alone causes no death: M2/M3 have not
selected a starvation mortality policy. M6.5d's source-starvation test checks zero
capture/affordable growth without negatives, heat recycling or invented death.
For the existing M2 depletion trigger, only an actual bite leaving **all ten**
producer compartments zero makes it terminal. Retained water can prevent complete
depletion; do not discard it to force a death. Terminal actors never capture, grow
or feed again. M6.6 adds host terminal events with retained corpse inventories and
decomposition; no resurrection or automatic replacement exists.
## Persistence and retry boundary
Use a distinct outer format/rules version, containing primitive config, both actor
states, outer tick, source residual and last funded interval, capture efficiency
residual, growth residual, owned resources and the last 64 complete input/report
pairs. Report includes captured/retained/heat, growth and unmet quota, source status,
feeding assimilation/waste and terminal transition. Snapshot is one consistency cut.
Process conversions invalidate the interpretation of old same-tag transfer history.
The sealed resource owner therefore exposes no M6.4 commit while attached. Each
successful process tick publishes a private validated resource checkpoint with
field command = adoption watermark = outer tick and an empty transfer-only history.
The process history is authoritative for retries. This checkpoint operation remains
private to the constrained process transaction; it cannot clear user histories on
an arbitrary imported owner. Never weaken the M6.5a reverse-history validator.
After restore, fresh query views are required. For retained ticks, compare full
original input before executing; identical input returns the saved report, changed
input conflicts, older evicted ticks reject. New ticks must be contiguous. Validate
history order/count, latest tick, endpoint/rules references, residual bounds and
resource checkpoint watermark. Reject a bare resource snapshot as a process snapshot.
Do not synthesize absent source or lifecycle state from defaults.
M6.5c must define exact byte fields, bounds and malformed-input validation before
exposing advance. Nothing here grants restart fencing, durable ACKs, disk publication
or host-loss recovery; those remain M7/M8.
## Hand-checkable acceptance vectors
1. Rate 5/3, remainder 0, incident 10: funded one-tick quotas 1,2,2; remainder
sequence 2,1,0. At efficiency 600, retained 0,1,2; efficiency residual 600,800,0;
heat 1,1,0. Total captured 5 = retained 3 + heat 2.
2. Rate 5/3, remainder 2, incident 1: next quota 2 cannot be funded. Stock remains
1, source remainder remains 2, and last funded interval stays unchanged. The
next outer tick is not a two-tick catch-up attempt.
3. Growth quota 2, cost 3, recipe W/C/N/P/O=2/4/1/1/0, stocks=4/8/1/2/0,
reserve 10: grow 1; move water2+C4+N1+P1 to producer, reserve becomes7,
heat gains3. One unit is unmet due to N. No second water/biomass credit.
4. Bite C/N/P/O/E=5/3/1/0/7 at assimilation600: consumer gets3/1/0/0/4;
environmental organic waste gets2/2/1/0, heat gets3. Water unchanged.
5. A valid capture/growth followed by an oversized bite rejects the whole tick;
canonical process snapshot, both histories and all residuals equal their before
values. Retry with corrected input can use the same uncommitted next tick.
M6.5c/d tests additionally cover inclusive temperature endpoints, source disabled,
zero efficiency, all capacity/overflow bounds, exact retry after restore, more than
64 ticks, malformed snapshots, deterministic seeded input streams and independent
per-channel accounting. No stochastic fairness or RNG is required in the engine;
seeded test drivers record their full input sequence.
+14
View File
@@ -1825,3 +1825,17 @@ error enum entries; corrected before the passing runs above.
No Linux/UBSan/TSan, disk crash, allocation-failure injection or cluster validation
was performed locally. Buffer round trips are not durable publication. M6.5b-d remain.
## M6.5b process contract - 2026-09-27
Documentation-only segment: accepted ADR-0055 and ENVIRONMENTAL_PROCESS.md define
versioned fixture conversions and the narrow process/world ownership boundary.
Inspected M2 producer/feeding implementations, their tests and ADRs, M3 metabolic
budget contract, and M6 resource APIs before specifying the adapter.
Executed independent PowerShell arithmetic checks for the documented fractional
capture/efficiency sequence, nutrient-limited growth and per-channel feeding split;
all passed. `git diff --check` passed. These are specification checks, not runtime
integration tests. No C++/CMake/schema change; builds, CTest and sanitizers were not
rerun for this documentation segment. M6.5c/d must supply executable evidence for
rollback, source exhaustion, temperature limits, lifecycle and restored replay.