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

87 lines
4.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
[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.