From 0b607bae53b46d6ce743e569689396f69bd76ac9 Mon Sep 17 00:00:00 2001 From: dingo Date: Sat, 10 Oct 2026 21:01:19 -0400 Subject: [PATCH] Define bounded cellular motion trial --- docs/adr/0102-cellular-spatial-trial.md | 90 +++++++++++++++++++++++++ docs/adr/README.md | 1 + docs/engineering/M11_3_DELIVERY_PLAN.md | 11 +-- 3 files changed, 97 insertions(+), 5 deletions(-) create mode 100644 docs/adr/0102-cellular-spatial-trial.md diff --git a/docs/adr/0102-cellular-spatial-trial.md b/docs/adr/0102-cellular-spatial-trial.md new file mode 100644 index 0000000..dbf7acb --- /dev/null +++ b/docs/adr/0102-cellular-spatial-trial.md @@ -0,0 +1,90 @@ +# ADR-0102: Bounded cellular space and locomotion trial + +## Status + +Accepted direction for M11.3 (2026-10-10). The maintainer authorized +recommendations and implementation choices for later review. Arena dimensions +and the patch pitch from ADR-0101 are versioned trial inputs, not locked world +geometry. + +## Context + +ADR-0098 selects movement and engulf intentions and requires server resolution +of contact, motion, perception and intake. It does not adopt the M10 marker's +speed or periodic 2D particle arena as organism physics. ADR-0101 supplies +finite, independently stocked food patches at cellular scale. M11.3 needs a +bounded spatial contract that connects a founder's micrometre location to those +patches without client authority over speed or position. + +## Decision + +- A cellular trial domain is a finite, axis-aligned 2D rectangle in one + region/frame, expressed in integer micrometres. Its width and height are + positive multiples of ADR-0101's patch pitch; the provisioned extent is + explicit and bounded. There is no wraparound. A body cannot leave the + rectangle; a movement step that reaches an edge is clamped there. +- An organism's position is the lower-left corner of its square footprint, + matching the existing primitive spawn-site overlap convention. Current + phenotype extent determines that square. Spawn/restore rejects positions + where the full footprint would leave the domain. M11.3 adds no obstacle, + facing or collision response beyond bounded organism contact. +- Movement intention is a signed X/Y vector in [-1000, 1000], with squared + Euclidean norm <= 1,000,000. It is a direction/magnitude request only. The + server derives speed from the current phenotype and the 50 ms world tick; + speed capacity rounds down under ADR-0099. Each axis displacement is the + signed integer truncation of `component * per_tick_speed / 1000`, followed by + boundary clamping. The resulting displacement never exceeds the derived + speed capacity. Invalid or stale intentions do not alter state. +- Movement energy is derived from `MetabolicBudget::movement`, proportional to + actual displacement relative to the full-speed tick distance and rounded up: + `ceil(full_speed_tick_cost * floor_sqrt(dx²+dy²) / per_tick_speed)`. Checked + quotient/remainder arithmetic is required; overflow refuses the whole step. + A zero per-tick speed or zero displacement costs zero. The movement resolver + reports a proposed cost; the state owner applies the move only if the reserve + can fund that cost. This resolver does not also spend maintenance, which + remains a separate tick-ordered biological cost. +- The body footprint determines which patch squares it overlaps. Contact + candidates are returned in canonical patch-address order; an exact boundary + touch counts as contact. Feeding limits, simultaneous claims, predation + threshold details and the tick order remain in the cellular-step contract, + not in this geometry helper. +- Spatial position, intent watermark, tick and selected cellular rule version + are checkpoint data. The server resolves movement before publishing final + outcomes. The M10 probe marker + and its prediction code remain a separate experiment. + +The pure spatial/motion API belongs to the headless biology/server boundary. It +has no transport, filesystem, database, renderer, wall clock or hidden random +state. The region host owns one writer and supplies the explicit tick and +authenticated intention. + +## Alternatives considered + +- **Reuse M10 probe motion:** rejected; it moves a non-biological marker at an + engineering speed and has no costs, phenotype, contact or durability. +- **Wrap at the domain edge:** rejected for this trial; it would make opposite + edges adjacent without a world-topology decision. +- **Accept client position or speed:** rejected because the client supplies + intentions only and the server owns biological outcomes. +- **Charge full-speed movement while stationary:** rejected; stationary + maintenance and movement are distinct budgets. + +## Benefits + +The motion rule is simple to audit and replay, uses genome-derived capability, +and permits short sessions in a finite provisioned habitat without claiming +planetary coordinates or full collision physics. + +## Costs and risks + +Integer component truncation makes very slow or diagonal movement coarse. Edge +clamping can feel artificial. Both are visible in the exploratory trial and +may be revised with a new rule/profile version; neither is a balance conclusion. + +## Consequences + +Add an integer-exact motion resolver and contact query with independent tests. +The cellular checkpoint and protocol carry the selected rule version, position +and intention watermark. ADR-0101 and the +[M11.3 delivery plan](../engineering/M11_3_DELIVERY_PLAN.md) continue to govern +resource-site ownership and persistence. diff --git a/docs/adr/README.md b/docs/adr/README.md index d783a65..7fdcacb 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -2,6 +2,7 @@ - [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-0102: Bounded cellular space and locomotion trial](0102-cellular-spatial-trial.md) - accepted M11.3 trial direction for finite 2D region bounds, phenotype-limited movement and organism contact; tunable arena dimensions are not world geometry. - [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 77bf85e..3f8959d 100644 --- a/docs/engineering/M11_3_DELIVERY_PLAN.md +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -58,10 +58,11 @@ Starting thresholds marked tunable stay versioned and visible to playtesters. 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. + explicit conserved transfer between scales. [ADR-0102](../adr/0102-cellular-spatial-trial.md) + now defines bounded non-wrapping motion and footprint contact. The cellular + profile must still define perception range 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 +82,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 | 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.3a: cellular state and spatial contract | Biology public values; server lifecycle; checkpoint profile; schemas and architecture docs | Implement ADR-0101/0102 microhabitat, movement and contact; define perception range, resource visibility, units, tick order 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 |