Files
aevolution/docs/biology/ENVIRONMENTAL_PROCESS.md
T

233 lines
14 KiB
Markdown

# M6.5 environmental process contract v1
M6.7 exposes immutable `tick_microseconds()` and a stateless bounded
`schedule_environment` adapter. See [scheduling](../architecture/ENVIRONMENTAL_SCHEDULING.md)
for admission, partial progress, pause/resume and resource revision contracts.
M6.6 adds opt-in rules 2 under [ADR-0056](../adr/0056-environmental-terminal-decay.md).
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.
```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: 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](../../schemas/environmental-community.md). 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](../engineering/ENVIRONMENTAL_QUALIFICATION.md).
The report distinguishes verified synthetic conservation/replay from ecological
stability, gameplay mortality and deployment capacity. No rules changed in M6.5d.