diff --git a/docs/adr/0101-cellular-microhabitat-resources.md b/docs/adr/0101-cellular-microhabitat-resources.md new file mode 100644 index 0000000..dc6a14e --- /dev/null +++ b/docs/adr/0101-cellular-microhabitat-resources.md @@ -0,0 +1,86 @@ +# 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. +- 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). diff --git a/docs/adr/README.md b/docs/adr/README.md index 6bdc27b..d783a65 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -1,6 +1,7 @@ # Architecture decision records - [ADR-0100: Primitive lives and persistent control](0100-primitive-lives-and-persistent-control.md) - accepted M11.2 direction: finite spawn pools, equal full-grown founders, new cellular checkpoint and atomic life publication. 11.2a adds in-memory funded creation; durability/integration follow. +- [ADR-0101: Cellular microhabitat resource sites](0101-cellular-microhabitat-resources.md) - accepted M11.3 direction for finite, conserved sub-voxel food patches; 1 mm pitch is a versioned exploratory tunable, with no meter-scale coupling yet. - [ADR-0058: Region durability contract](0058-region-durability-contract.md) - accepted M7.1 full checkpoint batches and explicit state closure; storage implementation follows. diff --git a/docs/engineering/M11_3_DELIVERY_PLAN.md b/docs/engineering/M11_3_DELIVERY_PLAN.md index 4fb3da6..77bf85e 100644 --- a/docs/engineering/M11_3_DELIVERY_PLAN.md +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -52,16 +52,16 @@ Starting thresholds marked tunable stay versioned and visible to playtesters. steering and local food choice meaningless. This is an architectural scale gap; do not change the shared world voxel contract to hide it. - **Recommended resolution for the cellular trial:** add a sparse, bounded - two-dimensional microhabitat whose independently stocked sites are 1,000 μm - across (50 founder extents), with explicit finite per-channel openings and - retained provenance. The pitch is a versioned tunable, not a final world - rule. Its opening is provisioned as part of the region; it has no automatic - replenishment. Later coupling to meter-scale world stores must be an explicit - conserved transfer between scales. Define the boundary policy, - contact/perception query and resource visibility alongside this profile. Do - not use the probe marker as an organism or expose unseen resources as client - knowledge. + **Resolution:** [ADR-0101](../adr/0101-cellular-microhabitat-resources.md) + selects a new sparse, bounded two-dimensional microhabitat, with independently + stocked 1,000 μm sites (50 founder extents), explicit finite per-channel + openings and retained provenance. The pitch is a versioned tunable, not a + final world rule. Its opening is provisioned as part of the region; it has no + automatic replenishment. Later coupling to meter-scale world stores must be an + explicit conserved transfer between scales. The implementation contract must + still define boundary behavior, contact/perception and resource visibility. + Do not use the probe marker as an organism or expose unseen resources as + client knowledge. 4. **Owner routing:** 11.2 still lacks authenticated routing/reconnect when an account's life is in another region. Resolve the ADR-0100 protocol gap (v6 owning-region response plus authoritative endpoint lookup, or server-side @@ -81,7 +81,7 @@ scoped change before starting the next segment. | Segment | Affected modules | Acceptance evidence | |---|---|---| -| 11.3a: cellular state and spatial contract | Biology public values; server lifecycle; checkpoint profile; schemas and architecture docs | Ratify the sparse microhabitat scale and boundary/perception contracts; explicit units, tick order, bounds and version allowlist; bounded canonical codec; hostile/truncated inputs refused before allocation; profile-3 compatibility; exact restore of every state field | +| 11.3a: cellular state and spatial contract | Biology public values; server lifecycle; checkpoint profile; schemas and architecture docs | Implement the ADR-0101 microhabitat; define boundary/perception contract, units, tick order, bounds and version allowlist; bounded canonical codec; hostile/truncated inputs refused before allocation; profile-3 compatibility; exact restore of every state field | | 11.3b: server-authoritative movement and perception | Biology adapter; spatial query; intent validation; network protocol/client session | Clients send only bounded movement/engulf intentions; server decides speed, position, contact and visible environment; range/speed forgery and stale intent tests; deterministic replay | | 11.3c: metabolism and finite transfers | Biology metabolism/development adapters; cellular field ledger; corpse/predation resolution | Intake and costs derived from phenotype; each resource channel conserves independently; contested stock has one winner; engulfed inventory moves once with excess detritus; starvation and death preserve all inventory | | 11.3d: durable tick publication and recovery | Primitive region host; persistence adapter/schema; session action outcomes; process tests | Checkpoint, habitat changes, terminal outcome and final action results publish atomically; exact retry after uncertain commit; kill/restart at publication boundaries; no offline progress; Linux/PostgreSQL CI qualification |