233 lines
14 KiB
Markdown
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.
|