Files
aevolution/docs/adr/0101-cellular-microhabitat-resources.md
T
dingo 1787718383
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m56s
Foundation / checks (postgres) (push) Canceled after 0s
Foundation / checks (tsan) (push) Canceled after 0s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 2m39s
Foundation / checks (client) (push) Canceled after 2m38s
Foundation / checks (network) (push) Canceled after 36s
Add finite cellular habitat snapshot
2026-10-10 21:13:51 -04:00

93 lines
5.0 KiB
Markdown

# ADR-0101: Cellular microhabitat resource sites
## Status
Accepted direction for the M11.3 exploratory cellular trial (2026-10-10).
The maintainer authorized recommendations and implementation choices for later
review. The spatial pitch is a versioned tunable, not a final world rule.
## Context
The primitive founder has a 20 μm body extent. World voxels have a 1 m pitch,
and M6 `FieldStore` permits one field site per voxel. A `HabitatBox` may be much
smaller than its voxel, but every query still returns that site's one stock
bundle; independent nearby food patches cannot coexist in one voxel. Treating
voxel sites as the food map would make movement and local feeding choice
ineffective at cellular scale.
M6's field and transfer contracts remain valid for their declared scope. They
must not be silently widened or copied into gameplay with different addressing.
M11 needs finite, conserved environmental stocks that cells can actually
navigate between. The cellular presentation and biology stay headless and do
not depend on graphics, networking or database code.
## Decision
- M11.3 introduces a region-owned, sparse, bounded two-dimensional cellular
microhabitat. Its independently stocked square patches are 1,000 μm wide for
the first trial, or 50 founder extents. Patch pitch and layout are explicit,
versioned rule inputs that later playtest evidence may change.
- Patch identity is the region/frame plus signed integer micrometre position;
coordinates and stock amounts are serialized explicitly. The host validates
domain bounds, unique patch addresses, counts and total byte budget before
publishing a habitat.
- Every patch's finite resource opening is supplied by explicit region
provisioning with source provenance. No absent value, terrain material or
substrate capacity creates stock. There is no automatic refill in M11.3.
- Transfers among patch stock, organism compartments and corpses are one
server-owned atomic operation. C, N, P, other and energy remain separate
conserved channels. Any conversion between tags needs an explicit biological
rule; water, incident energy and heat are not edible reserve by relabeling.
- An absorption proposal moves each acquired channel into the living cell's
reserve, not directly into its fully formed body or growth state. Food matter
remains there for later funded development/reproduction; usable energy is
available for movement and maintenance. Absorption alone builds no tissue.
- The habitat opening, depletion, organism balances and transfer/retry state
belong to the cellular checkpoint closure. A crash cannot publish only one
side of a transfer. Profile-3 creation checkpoints and M6 field snapshots
remain byte-compatible and are not reinterpreted.
- M11.3 does not claim coupling between this fine-scale habitat and meter-scale
world fields. Such coupling requires a separate, versioned transfer that
debits one owner and credits the other atomically. The initial exploratory
region uses a finite explicit opening and can be reviewed without changing
World0 or persistent-world generation.
The bounded patch count, geometry, boundary behavior, movement law, perception
range and uptake rates are part of the M11.3 cellular rule/profile contract;
this ADR fixes only the resource addressing and ownership direction. Values
marked tunable remain reviewable with playtest evidence.
## Alternatives considered
- **Use one M6 field site per meter voxel:** rejected for cellular movement;
nearby stocks cannot vary independently at founder scale.
- **Change the shared world voxel pitch:** rejected because it changes the M5/M6
address and storage contract for unrelated world systems.
- **Re-use a separate `FieldStore` for every sub-voxel patch:** rejected because
stores have independent identity and ownership, so this would fragment
contention and atomic conservation across food sites.
- **Seed an unlimited or automatically replenished food field:** rejected;
it hides resource creation and makes feeding cost impossible to assess.
## Benefits
Cells can encounter distinct, finite food patches at a scale where movement is
visible. The existing world voxel and environmental fixture formats retain their
meaning, and all starting matter is explicit and auditable.
## Costs and risks
The region gains another bounded persistent resource representation and an
explicit provisioning surface. The initial 1 mm pitch may make food too sparse
or too uniform; it is a versioned experiment. Cross-scale replenishment is not
available until its conservation transaction is designed and tested.
## Consequences
M11.3 adds a pure cellular habitat/resource owner and server adapter rather than
expanding `FieldStore` or `EnvironmentalTransfers`. Required evidence and the
remaining spatial, persistence and server work are tracked in the
[M11.3 delivery plan](../engineering/M11_3_DELIVERY_PLAN.md). The habitat-only
codec is specified in [cellular-habitat-v1.md](../../schemas/cellular-habitat-v1.md);
it is not yet an admitted region checkpoint profile.