Files
aevolution/docs/adr/0039-materialize-representatives.md
T
dingoandClaude Opus 5 380d609f06 Round shares down and ages up, so a round trip never pays
M4.4 turns whole members of a cohort back into identified individuals, and does
nothing else: no habitat transfer, no persistence, no resolution-equivalence
claim. Materialization is instantaneous at the cohort's current tick, because
advancing time is M4.3's interval.

The named risk is that re-materialization becomes free healing, and it has two
separable sources. The arithmetic one is closed outright. A drawn member gets its
class share by integer division rounded down, because rounding up would create
biomass, and a class drawn empty hands over everything it held because a class
with no members may keep no reserve. A residual is never drawable, so an expected
density cannot become an individual.

Age is taken as the oldest the class admits. The exact age is unrecoverable, so
the question is only 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. Both of these are the risk rather than ordinary
validation, and both mutations are detected: rounding the share up, and drawing
the age from the class floor.

The second source is the declared resolution itself and is stated rather than
mitigated. Members inside a class are indistinguishable by construction, so
collapsing a starving member with a well-provisioned one and materializing both
returns two average members, healing the first at the second's expense. The tests
demonstrate both halves instead of only the flattering one: a round trip is exact
when each class holds one member, and a coarse class conserves the total while
averaging the individuals. Conservation of the total is not evidence that any
individual is right, and the mitigation is the caller's choice of classes when it
collapses, not anything this code can recover.

Materialization produces exactly the record a collapse consumes, so the two
compose and are tested against each other rather than described as inverses. The
oscillation test runs twelve cycles and asserts every cycle that the conserved
total never moves, nobody holds more than the richest starting member held, and
nobody is younger than last cycle; it ends by asserting everyone has been pushed
to a class ceiling, which records the cost of the age rule rather than claiming
it away.

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 15:41:49 -04:00

7.5 KiB

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.

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 repeated reservoir, a stale view and a wrong owner are each refused, and that every rejection leaves the ledger and the registry unchanged. No genome schema, mutation catalog, archive, ledger, episode driver, ensemble, cohort record, collapse, interval accounting, renderer or deployment changes.