Files
aevolution/docs/adr/0026-shared-feeding-community.md
T
2026-10-08 12:08:53 -04:00

4.4 KiB
Raw Blame History

[Reviewed]

ADR-0026: Shared synthetic feeding community

Status

Adopted for bounded M2.3 process fixtures; not biological classes or live-world organism rules. Extends ADR-0025's isolated ownership with one community owner.

Context

Copying producer balances into a consumer ledger would duplicate resources. Producer progress and feeding must commit against one inventory owner.

Decision

FeedingCommunity privately owns one ProducerProcess and 1–16 configured consumer capabilities sharing its ledger. A narrow friend boundary permits this owner to construct the larger ledger and orchestrate transfers; no mutable ledger escapes. The standalone producer API and four-reservoir fixture remain compatible. Producer stepping uses the next ledger action watermark rather than assuming one ledger action per tick. The community clock remains the producer's logical tick.

Reservoirs 1–4 retain source/nutrients/producer/heat. Consumer reservoirs follow; one final reservoir holds unassimilated matter. Process IDs: producer=1, consumers =2 onward. These IDs are fixture identities, not entity handles, species or classes. Opening consumer inventories are explicit experimental budgets; no persistent world founder or biomass is automatically created.

Each exact-next-tick call accepts at most 16 immutable FeedIntent records, with nonzero unique host sequences. Sort by sequence; at most one feeding request per consumer per tick. This prevents splitting an intake limit into multiple requests. Requests name a distinct active target (producer or another consumer), a nonzero inventory bundle and an active consumer. Each channel must fit the configured intake cap and current target balance. No silently reduced bite. First ordered request gets first access; later overdraft rejects the entire tick.

Run producer capture/growth first if active, then feeding on a private community copy. Assimilated energy and matter use a fixed configured fraction in thousandths; floor each channel independently with overflow-safe quotient decomposition. Energy remainder goes to heat, matter remainder to waste. This split deliberately has no fractional entitlement carried between bites: integer waste is real inventory. It cannot create an advantage by splitting, but its small-quantity bias must be reviewed before biological tuning. An efficiency of 1000 transfers all, 0 transfers all energy to heat and all matter to waste.

A target whose entire inventory becomes zero due to feeding becomes terminally inactive. It cannot act, be targeted again or resume capture/growth. This is a synthetic depletion trigger, not a chosen health/starvation rule. Empty opening fixtures may be active; only actual feeding causes this transition. Partial injury, corpses and decomposition remain M2.4. Inactive producer ticks advance the shared clock without advancing its fractional capture/growth state.

Any invalid command, stale tick, overflow or allocation failure rejects the whole candidate. Publish inventories, activity flags, producer remainders and sorted receipts via noexcept moves only. No current operation resurrects a process.

Alternatives Considered

Separate ledgers need escrow and cross-owner transactions; unjustified locally. Public mutation access could recycle heat. Partial per-request commits complicate replay. A generic ECS rewrite or service boundary has no benefit for this fixture.

Benefits

One conserved source of truth, bounded input, deterministic contention, shared capture/feeding atomicity and explicit terminal activity.

Costs

Whole-community copies and small fixed actor/command limits. No spatial gate is implemented: requests are trusted co-located fixture intentions, not network input. Body reserve and material are independently requested, not a complete digestion model.

Risks

This fairness, rounding and depletion policy must not become gameplay by accident. No lineage, perception, authorization or collision rule is implied. A later corpse model must preserve inventories when death occurs before complete depletion.

Consequences

Test order permutations, whole-tick rollback including producer progress, competing feeders, intake bounds, invalid/self/dead targets, terminal actors, heat/waste, efficiency endpoints, arithmetic extremes and repeated conservation/replay. No snapshot, database, renderer or deployment changes. M2.4 must extend this shared ownership model for terminal death with remaining resources and decomposition.