From e9ea388cef7814a39e3fe9580cdff52c4eddd4ec Mon Sep 17 00:00:00 2001 From: dingo Date: Sun, 27 Sep 2026 09:39:51 -0400 Subject: [PATCH] Define M6.5b environmental process conversions and ownership --- docs/ROADMAP.md | 6 + docs/STATUS.md | 18 +- .../0055-environmental-process-contract.md | 73 +++++++ docs/adr/README.md | 1 + docs/architecture/SYSTEM_OVERVIEW.md | 9 + docs/biology/ENERGY_MODEL.md | 10 + docs/biology/ENVIRONMENTAL_PROCESS.md | 201 ++++++++++++++++++ docs/engineering/VALIDATION.md | 14 ++ 8 files changed, 330 insertions(+), 2 deletions(-) create mode 100644 docs/adr/0055-environmental-process-contract.md create mode 100644 docs/biology/ENVIRONMENTAL_PROCESS.md diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 8598a06..422260e 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -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. diff --git a/docs/STATUS.md b/docs/STATUS.md index 8354c55..161bb13 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -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. diff --git a/docs/adr/0055-environmental-process-contract.md b/docs/adr/0055-environmental-process-contract.md new file mode 100644 index 0000000..4ded9fd --- /dev/null +++ b/docs/adr/0055-environmental-process-contract.md @@ -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. diff --git a/docs/adr/README.md b/docs/adr/README.md index 35362a4..4d54fce 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -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. diff --git a/docs/architecture/SYSTEM_OVERVIEW.md b/docs/architecture/SYSTEM_OVERVIEW.md index 9ee63d5..fb92fbd 100644 --- a/docs/architecture/SYSTEM_OVERVIEW.md +++ b/docs/architecture/SYSTEM_OVERVIEW.md @@ -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. diff --git a/docs/biology/ENERGY_MODEL.md b/docs/biology/ENERGY_MODEL.md index 85b690d..b1dc32d 100644 --- a/docs/biology/ENERGY_MODEL.md +++ b/docs/biology/ENERGY_MODEL.md @@ -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. diff --git a/docs/biology/ENVIRONMENTAL_PROCESS.md b/docs/biology/ENVIRONMENTAL_PROCESS.md new file mode 100644 index 0000000..c751409 --- /dev/null +++ b/docs/biology/ENVIRONMENTAL_PROCESS.md @@ -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. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index a6be337..f4bf5ef 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -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.