Files
aevolution/docs/adr/0039-materialize-representatives.md
T
dingoandClaude Opus 5 14e0c1af5e An empty reservoir is not an unowned one
Two defects from review of 380d609.

Materialization treated an empty reservoir as available. A vacant cohort, or one
holding nothing, still owns its store, so a draw could credit it while the owning
record went on recording nothing: the same inventory in two places, reached from
the opposite direction to the destination defect in 1a59b63. Destinations are
checked against the registry's ownership now, not just their balance, and the
registry answers whether a reservoir is used rather than callers inferring it from
what the reservoir contains.

The same hole existed on the collapse side in a worse form, found by asking
whether the reported defect had a sibling. Nothing verified the destination was
unowned, so the shared-reservoir rule added in M4.3 would have refused the install
only after the transfer had run, leaving the members emptied and their biomass in
a reservoir nothing accounted for. That is exactly the stranding the M4.2 ordering
was chosen to prevent, defeated by a check that ran too late. Whichever registry
step follows a transfer is now proved to succeed before it, through may_install
and may_replace queries that install and replace delegate to, so there is one rule
and not a restatement that can drift.

The second finding was a functional gap the oscillation test hid by discarding its
registry each cycle. A full draw leaves a vacant record, which ADR-0036 retains
because absence is not extinction, and collapse then refused that habitat and
genome as occupied: a full materialization was a one-way door out of a habitat and
the lineage could never return. Collapse repopulates a vacant record in place now,
continuing its ownership and revision series rather than restarting them, and a
record still holding a population is refused, because merging two silently is not
a conversion. The test keeps one registry for all twelve cycles and asserts the
revision continues.

Four of the five new guards are load-bearing. The fifth is not and is recorded as
such: the may_replace pre-check in commit_materialize is unreachable given the
checks before it, since the installed record is already proved equal to the plan's
origin and the result differs only by a later revision. It is kept because it is
the right place for the guard and its collapse-side sibling is genuinely
reachable, not because it is exercised.

Release 37/37, analysis, ASan 37/37 and clang-format all ran and passed here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-24 17:47:37 -04:00

141 lines
8.2 KiB
Markdown

# 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.