Files
aevolution/docs/adr/0166-retained-plan-replay-traces.md
dingo c0c66fa11a
Foundation / checks (ecs) (push) Successful in 2m23s
Foundation / checks (deploy) (push) Successful in 4m29s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (network) (push) Canceled after 12m39s
Foundation / checks (client) (push) Canceled after 12m44s
Foundation / checks (checks) (push) Canceled after 12m48s
Foundation / checks (tsan) (push) Canceled after 10m18s
Foundation / checks (postgres) (push) Canceled after 12m44s
feat(lifecycle): replay retained offspring plans with explicit trace version
2026-10-19 14:04:52 -04:00

3.8 KiB

ADR-0166: Retained-plan replay traces

Status and scope

Accepted portable replay segment of ADR-0163/0165, 2026-10-19. No new biology, durable bundle, SQL admission, worker default, control handoff or UI contract.

Context

Owner format 8/rules 10 retains inherited plans separately from expressed bodies. Trace 3 describes the earlier in-life mutation path. Admitting the new owner under that trace would make the same recorded selection have two meanings. Matching an inherited offer to the expressed genome would also reject legitimate later plan selections. Portable replay is needed before durable qualification.

Decision

Add explicit raw cellular trace format 4, paired exclusively with owner format 8/rules 10. Keep formats 1-3 and the default trace-3 constant unchanged. Trace 4 uses the same bounded header, life/birth/selection layouts and canonical ordering as trace 3, but its selections edit inherited plans under rules 10. No client supplies the selected genome or biological outcome. Mixed/unknown owner/trace versions refuse, including action matching; in-memory replay must enforce the same version-specific payload shape as the codec.

Replay restores a detached predecessor, applies each complete tick and derives actual plan selection outcomes, funded births, archive history and inventory. Selection precedes budding; allocator-authorized primitive births remain after the tick. Return the complete candidate and mutation outcomes only on full success. Any later refusal leaves the predecessor unchanged and clears the outcome vector, rather than exposing a partial accepted prefix. This tightens failure reporting for earlier traces without changing successful old bytes or biology. Outcomes are derived, not trusted trace assertions.

Reuse the existing canonical action blocks. Authoritative accounts, exact standing offers, event/offer tick, operators and reserved identities remain required. Under rules 10, match the offer parent to the retained offspring plan; earlier owners fall back to their expressed genome. Choices must already be available at the predecessor cut, as in the existing action contract. This does not authorize choices for offers first earned midway through a recorded batch.

Existing SQL publishers/bundles, population traces, census and migration remain unchanged and refuse this new combination. Portable decoding/replay is not publication authority; result 4 (offspring_plan_applied) is not admitted by the old durable result contract. Durable support requires a later explicit versioned upgrade, retained-source replay, fences and fault qualification.

Alternatives, consequences and risks

Reusing trace 3 would overload saved meaning. Changing its default would silently move existing callers onto an unsupported durable version. Duplicating the entire codec would add two implementations of identical bounded fields. A new semantic version with shared field handling preserves compatibility at small cost.

Risks include accidental durable admission, mismatched action authority and partial results surviving a failed replay. Exact allowlists, complete candidate comparison and adversarial multi-tick tests address those risks. This supplies replay evidence only; it does not supply account control succession or NPC policy.

Qualification

Require direct-versus-recorded equality for earned structural selections, selection plus same-tick funded offspring, later plan changes, declines and active offspring with a suspended parent. Test action mismatches after a plan differs from the body, malformed codecs, both cross-version directions, stale choices and a failure after a successful selection prefix. A fresh process must restore the predecessor, decode the trace and reproduce complete expected bytes. Run Release/NDEBUG, analysis/formatting and ASan/UBSan; preserve all old goldens.