Files
aevolution/docs/adr/0039-materialize-representatives.md
T
2026-10-08 12:08:53 -04:00

142 lines
8.2 KiB
Markdown

[Reviewed]
# ADR-0039: Materializing representatives without making a round trip profitable
## Status
Adopted for M4.4. It turns whole members of a cohort back into identified
individuals and does nothing else: no transfer between habitats, no persistence,
and no resolution-equivalence claim, which is M4.5. No M1 to M3 contract changes,
and ADR-0036, ADR-0037 and ADR-0038 are unchanged.
## Context
M4.2 goes one way. Without the other, a collapsed cohort is a dead end and nothing
can check that collapsing was faithful. The risk named for this step is that
re-materialization becomes free healing, and ECOLOGY_MODEL adds the related
prohibitions: a conversion may not reset age, injury, fertility or incubation, an
expected fractional density is not an available individual, and materialization
stays bounded by funded biomass.
Free healing has two quite different sources and they need separating. One is
arithmetic: handing out more than is debited, or rounding a share upward. That is
preventable outright. The other is the declared resolution itself: members inside
one class are indistinguishable by construction, so collapsing a starving member
together with a well-provisioned one and materializing both returns two average
members. The starving one has been healed at the other's expense. No accounting
can recover what the resolution discarded, and pretending otherwise would be worse
than saying so.
## Decision
Materialization is instantaneous. It happens at the cohort's current tick and
never advances it, because advancing time is ADR-0038's interval and this is not
one. The revision still advances, so the registry's ordering rules apply
unchanged.
Only whole members materialize. A residual is a fraction that is owed and not
present, so it can never become an individual; it stays with the cohort. This is
ECOLOGY_MODEL's rule that an expected fractional density differs from an available
individual, enforced rather than described.
A drawn member receives its class's share, computed as integer division of the
class reserve by the class count, per channel, rounded down. Rounding down is the
whole point: rounding up would create biomass, and a share is never more than the
class held. The remainder stays with the class, except where a class is drawn
empty, in which case it hands over everything it held, one extra unit each to the
first members, because a class with no members may not keep a reserve and leaving
it would be biomass owned by nobody. A full draw therefore yields at most one unit
per member more than a partial one; that is an ordering artifact, it is bounded by
the class count, and it can never exceed what the class held.
Age is taken as the oldest the class admits, not the youngest and not a seeded
choice within it. The exact age is not recoverable, so the question is which
direction to be wrong in, and every other answer makes oscillation profitable: a
member re-materialized at the bottom of its class is younger than it was, and
repeating that is immortality. Taking the top means a round trip can only age
someone. Oscillation is then strictly lossy in age rather than free, which is the
behaviour to want from an exploit.
Conservation runs through the ledger, as in ADR-0037 and ADR-0038. One atomic
transaction debits the cohort's reservoir and credits each member's, and each
member's reservoir must be empty first, so a member's reserve is the whole of what
backs it rather than a part sharing a store with inventory nobody counted. That is
the same rule the destination of a collapse has.
Emptiness is not availability, and that distinction had to be added after review. A
vacant cohort, or one simply holding nothing, still owns its reservoir, so crediting
it would put inventory there that the owning record does not account for: the same
inventory in two places, arrived at from the other direction. Every destination is
therefore checked against the registry's ownership as well as against its balance,
and the registry answers whether a reservoir is used rather than callers guessing
from what it contains.
What the resolution discards is stated, not mitigated. A round trip is exact when
each class holds one member and smooths within a class otherwise, and the tests
demonstrate both rather than only the flattering one. The available mitigation is
the declared resolution itself: a caller that needs a member's own reserve
preserved declares narrower classes when it collapses.
## Alternatives Considered
Choosing an age with a seeded draw inside the class is what ECOLOGY_MODEL's
"seeded rule" suggests for counts, and it is average-neutral, but it lets an
adversary who controls when to convert re-roll towards youth; the conservative
bound does not. Rounding shares to nearest would sometimes hand out more than was
debited. Handing the remainder to the last drawn member rather than spreading it
concentrates an arbitrary advantage. Refusing to draw a class empty unless its
reserve divides exactly would make ordinary states unconvertible. Letting a
fraction materialize as a member with a proportional share would turn an expected
density into an individual, which the model forbids. Reconstructing a member's
original reserve from provenance would require keeping per-member records, which
is the individual representation a cohort exists to replace.
## Benefits
A round trip can never return more than was debited, in any channel, and never
returns anyone younger. Materialization produces exactly the record a collapse
consumes, so the two compose and can be tested against each other directly. The
smoothing that the declared resolution causes is measurable and named rather than
hidden, and a caller can eliminate it by choosing its classes.
## Costs
Round-tripping ages members by up to the width of their class, which is a real
distortion in the conservative direction. A full draw yields slightly more per
member than a partial one. Ages are drawn from class bounds, so repeated
conversion pushes a population towards class ceilings. The caller supplies one
empty reservoir per materialized member, which is bookkeeping it has to do. Nothing
reconstructs injury, fertility or incubation, because a cohort never carried them.
## Risks
Materialization is not the inverse of collapse and this ADR does not claim it is.
Within a class the two are lossy in both directions, and conservation of the total
is not evidence that any individual is right; M4.5 is where matched ensembles are
compared. The conservative age rule is a defence against oscillation, not a model
of ageing, and it will make a population look older than it is under repeated
conversion. A materialized member carries the cohort's genome and its provenance
and nothing else, so it has no parentage, no history and no condition, and none of
that may be invented later from a statistical membership. Ownership remains a
single-process invariant and nothing is serialized.
## Consequences
Test that a drawn member receives the floor share and that the remainder stays
with the class, that a class drawn empty hands over everything it held, and that
neither a residual nor a fraction of a member can be drawn. Test that ages come
from the top of the class and that a round trip never returns anyone younger. Test
that a round trip is exact when each class holds one member, and that with a
coarse class the total is conserved while individual reserves are smoothed, so the
loss is demonstrated rather than implied absent. Test repeated oscillation over
many cycles: the conserved total never moves, no member ever holds more than the
largest starting member held, and ages never decrease. Test scarcity, where a
class holding nothing materializes members holding nothing rather than refusing or
inventing. Test that drawing more than a class holds, an unknown or repeated class,
a reservoir that is not empty, a reservoir another cohort owns however empty, a
repeated reservoir, a stale view and a wrong owner are each refused, and that every
rejection leaves the ledger and the registry unchanged. Test the round trip through
one registry that is never discarded, so a full draw and the collapse that follows
it have to work against the record the draw left behind. No genome schema, mutation catalog, archive, ledger, episode driver,
ensemble, cohort record, collapse, interval accounting, renderer or deployment
changes.