Files
aevolution/schemas/cellular-region-batch-v4.md
T
dingo 39509ecd40
Foundation / checks (ecs) (push) Successful in 2m51s
Foundation / checks (deploy) (push) Successful in 5m18s
Foundation / checks (network) (push) Successful in 25m49s
Foundation / checks (client) (push) Successful in 26m34s
Foundation / checks (tsan) (push) Successful in 37m12s
Foundation / postgres-tools (push) Canceled after 0s
Foundation / server-image (push) Canceled after 0s
Foundation / image (push) Canceled after 0s
Foundation / checks (checks) (push) Canceled after 47m59s
Foundation / checks (postgres) (push) Canceled after 47m53s
feat(persistence): define retained-plan checkpoint upgrade candidates
2026-10-19 14:17:41 -04:00

62 lines
3.5 KiB
Markdown

# Cellular region batch trace 4: retained offspring plans
Authority: [ADR-0166](../docs/adr/0166-retained-plan-replay-traces.md). This is a
portable raw-owner trace, paired exclusively with owner format 8/rules 10.
[Portable bundle 12](cellular-inheritance-upgrade.md) names this raw checkpoint;
existing SQL bundles and population traces do not admit it. The default
cellular trace remains format 3. Formats 1-3 keep their successful canonical
bytes and earlier biological meanings.
All integers are little-endian. The layout is identical to
[trace 3](cellular-region-batch-v3.md) except the format field is 4:
| Offset | Bytes | Field |
|---:|---:|---|
| 0 | 8 | Magic `EVLCBT01` |
| 8 | 4 | Format 4 |
| 12 | 4 | Raw cellular profile discriminator 4 |
| 16 | 24 | World, region and frame, three u64s |
| 40 | 16 | Nonzero predecessor commit |
| 56 | 32 | Nonzero predecessor manifest digest |
| 88 | 16 | Begin/end ticks, two u64s |
| 104 | 4 | Tick count, 1 through 64, exactly end minus begin |
| 108 | 4 | Reserved zero |
| 112 | variable | Complete consecutive tick records |
Each tick starts with u32 counts for life intentions, allocator births and
mutation selections, then a zero u32. Arrays follow in that order: existing
24-byte intentions, 40-byte births and 40-byte selections. A selection records
life, event index, offer tick and reserved successor ID as u64s, operator as u16
and six zero bytes. Operator zero declines. Inputs contain no trusted biological
outcome, child genome payload, construction price or parent body replacement.
Use the existing per-tick life bounds and `max_cellular_batch_bytes`; check every
encoded count against remaining bytes before allocation. Refuse unknown formats,
reserved bits, unordered/duplicate keys, cross-tick allocator identity or birth
account reuse, cross-selection successor reuse, truncation and trailing bytes.
The codec and in-memory replay enforce the same version-specific payload shape:
trace 1 has no births/selections; trace 2 has no selections.
Replay binds world/region/frame/begin tick to the predecessor and restores a
detached owner. Only trace 4 with owner 8/rules 10 is accepted; both cross-version
directions refuse before execution, including both action matchers. Apply the
normal rules-10 step, selections and funded budding, then allocator-authorized
primitive births. Existing phase ordering and closure remain mandatory. A later
failed tick/birth returns no candidate or partial mutation outcomes; the input
owner stays byte-identical. Successful outcomes are derived in tick/life order.
The new `offspring_plan_applied` enum value is 4; historical values remain 0-3.
This derived result is not admitted by the old durable result-byte contract.
Canonical movement and mutation action blocks retain their existing layouts.
They must match the authenticated predecessor account/life and exact recorded
input. Mutation selections must match the standing offer's event, tick, operator
and inherited plan, even when that plan differs from the expressed genome.
Offers first earned inside the batch cannot be authorized by that predecessor.
Allocator authority and exact successor reservation binding still belong to
the eventual durable publisher; these portable functions do not grant them.
Before publication, a later bundle must bind manifests, input digests, actions,
reservations, replayed results and the entire final checkpoint under the proper
head/lease fence, with retained-source upgrade and crash/retry qualification.
Merely decoding trace 4 grants no database, worker, migration or census admission.