Files
aevolution/docs/adr/0102-cellular-spatial-trial.md
T
dingo c552eb3250
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m53s
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 (client) (push) Canceled after 3m14s
Foundation / checks (checks) (push) Canceled after 3m19s
Foundation / checks (network) (push) Canceled after 1m19s
Add channel-limited cellular uptake proposal
2026-10-10 21:11:00 -04:00

94 lines
4.9 KiB
Markdown

# 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 to 1,000,000 μm per axis in this trial. 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 * ceil_sqrt(dx²+dy²) / per_tick_speed)`. The
distance rounds up so the discrete approximation cannot undercharge motion.
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, then transfers the spent energy to the heat sink in the
same candidate state. This resolver does not also spend maintenance, which
remains a separate tick-ordered cost from reserve to heat.
- 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.