Files
aevolution/docs/adr/0171-retained-plan-exact-populations.md
dingo a898a35e1b
Foundation / checks (ecs) (push) Successful in 2m26s
Foundation / checks (deploy) (push) Successful in 4m57s
Foundation / checks (network) (push) Successful in 20m53s
Foundation / checks (client) (push) Successful in 22m12s
Foundation / checks (tsan) (push) Successful in 39m45s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (postgres) (push) Canceled after 45m41s
Foundation / checks (checks) (push) Canceled after 45m43s
feat(lifecycle): preserve inherited plans in exact populations
2026-10-19 15:19:43 -04:00

3.3 KiB

ADR-0171: Retained-plan exact populations

Status and scope

Accepted portable M12 population integration, 2026-10-19. Extends ADR-0139/0140/0165/0169. No approximate aggregation, durable admission, automatic upgrade, cross-region migration, new controller or live/default rule change.

Decision

Population envelope 3 (AEVOPOP3) contains exactly owner 8/rules 10. Retain the existing header/member layout, complete nested biological snapshot, policy and conversion sequence. Membership still tags whole eligible wildlife groups by their expressed genome. It never groups away or replaces individual offspring plans, revisions, body/reserve, age, growth or identity. References own no stock.

An explicit detached no-tick envelope-2/rules-9 inheritance upgrade preserves all tags, policy and sequence while invoking the exact nested owner upgrade. Old envelopes retain their precise meaning and reject the new nested owner. Repeated and skipped upgrades refuse. A raw inherited owner can be wrapped portably; that does not authorize a database profile transition or create durable ownership.

Population batch 3 (AEVOPBT3) pairs only with envelope 3 and nested raw trace 4. Keep the existing bounded recorded intentions and exact membership boundaries. Unattended intervals still require fully suspended controlled cells, frozen-only controlled intentions and no birth requests or mutation selections. Wildlife uses its unchanged shared controller during recording and retained intentions during replay. Real funded wildlife births inherit their stored plans through the same kernel; tags own no additional organisms or inventory. No controller rerun, resampling, or restoration-time policy evaluation is introduced.

Projection 2 additionally supports envelope 3. Tag classification determines the existing resident and plan-holder kind independently of the expressed/plan genome row. Raw and cohort observations may share an exact owner/rules/projection cut. Living plans remain references, dead plans history, and unsupported evidence never supplies terminal extinction. Projection 1 retains its old domain.

Alternatives, consequences and qualification

Reusing envelope 2 would reinterpret its nested-format contract. Grouping by an average plan discards inherited diversity; treating plan references as members invents organisms. Exact retained members avoid both errors, without a speedup or compression claim. The existing capacity ceiling and disabled policy default remain; target-host cost is still unqualified.

Require real earned structural plans and funded children, unchanged expressed parents, subsequent plan changes, active and suspended raw/cohort equality, whole-group conversion, exact per-kind census, snapshot/trace restoration, mid-interval refusal and fresh-process continuation. Mutated outer versions, wrong raw trace pairings, altered membership boundaries and controlled activity must refuse without changing the source. Preserve all old goldens. Qualify Release/NDEBUG, clang-tidy, formatting and relevant ASan/UBSan before committing.

SQL and checkpoint population mappings remain unchanged. New envelope/trace readers alone cannot publish or migrate this owner. A later durable segment must bind its exact tuple, upgrade, trace and recovered result through existing fences/journals, with faults and retries, before population publication is admitted.