Files
aevolution/docs/biology/ENVIRONMENTAL_PROCESS.md
T

14 KiB

M6.5 environmental process contract v1

M6.7 exposes immutable tick_microseconds() and a stateless bounded schedule_environment adapter. See scheduling for admission, partial progress, pause/resume and resource revision contracts.

M6.6 adds opt-in rules 2 under ADR-0056. The public config adds decay[10] in fg/pJ per tick; input adds terminal[2] flags in actor order. Progress adds consumer_terminal; reports add consumer_transition and decomposed[10] source-channel totals. Terminal facts precede capture/growth, then feeding, then bounded corpse decay. Original accounts retain remaining inventory. All phases share one rollback and persisted retry boundary. The v1 contract below and its bytes remain unchanged. See the envelope schema for v2.

Authority: ADR-0055, ADR-0054, environmental units (ADR-0050), and the scoped producer/feeding rules (ADRs 0025/0026). Implemented in M6.5c; natively qualified in M6.5d. M6.5b is a contract segment. M6.5c implements the runtime and complete buffer codec together. Coefficients below are fixture inputs, not game rules.

Ownership and interface boundary

One EnvironmentalCommunity 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.

Public API in include/evo/processes/environmental_community.hpp:

  • 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;
  • resources()/progress() -> read-only resource access and copied progress; views require freshness validation.

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.

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: stage scalar balances and progress 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 defines exact byte fields and validation in the envelope schema. 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.

M6.5c implementation detail

For one site, field channels are uniform scalars. Stage all 30 balances, progress, report and the historical audit anchor in bounded arrays. A private world checkpoint validates conserved totals and capacities then replaces baselines without allocation; process progress/history publish immediately afterward without throwing. Terrain is unchanged. There is no full terrain clone or codec round trip in advance. This refines the initial cloning baseline above while retaining detached candidate semantics.

Restore replays the 64-tick receipt window from a persisted historical anchor and compares all reports and final state. The anchor is not spendable. The consumer is always active in rules v1 (no consumer-death operation exists); producer terminal state is serialized explicitly. Frame/site, account IDs, source identity and primitive rate config come from the complete envelope, never missing-state defaults.

M6.5d now provides native qualification and cost evidence. The report distinguishes verified synthetic conservation/replay from ecological stability, gameplay mortality and deployment capacity. No rules changed in M6.5d.