Files
aevolution/schemas/cellular-lives-v2.md
dingo d652291126
Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 1m56s
Foundation / checks (postgres) (push) Canceled after 0s
Foundation / checks (tsan) (push) Canceled after 0s
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 5m28s
Foundation / checks (checks) (push) Canceled after 7m39s
Foundation / checks (client) (push) Canceled after 7m39s
Persist fed mutation offers in cellular v2
2026-10-11 04:51:55 -04:00

5.4 KiB

Cellular lives checkpoint v2

Authority: ADR-0108, ADR-0109, ADR-0110, ADR-0119 and ADR-0120. This is checkpoint profile 4, envelope version 2. Version 1 remains decodable and unchanged; ordinary successors retain the exact version bundle. A live v1 head reaches v2 only through the explicit no-tick migration in ADR-0119.

Envelope and closure

All integers are little-endian. The v2 envelope keeps the v1 header offsets and canonical habitat/archive nesting. Its magic is ASCII AEVCLV02; format is 2 and cellular rules are 2. The ninth manifest cellular-version slot is mutation_state=1. The other slots are rules 2, envelope 2, habitat 1, coordinate 1, genome 1, development 2, founder 1 and archive 1. The tick stays 50 ms. The complete payload remains bounded by 16 MiB.

The header and the 8-byte spawn-site records are byte-for-byte the v1 shape, except for the v2 magic and version words. Living records are 480 bytes. Corpse records remain 100 bytes. The exact length is 220 + 8*spawn_site_count + 480*living_count + 100*corpse_count + habitat_bytes + archive_bytes + 8. The final eight bytes remain the FNV-1a64 accidental-corruption check; the manifest SHA-256 binds the immutable object.

All conservation, identity, archive, habitat, placement and canonical-restore rules from v1 continue unchanged. Mutation counters and offer metadata are non-inventory life state: they do not enter the conserved energy/matter totals.

Living record

The first 168 bytes are exactly the v1 living record. The v2 mutation block follows at offset 168:

Offset Width Field Contract
168 8 fed_energy_credit Successfully patch-acquired energy retained after the tick; remainder and already-earned surplus, in pJ
176 8 mutation_event_index Number of offers issued for this life; no wrap
184 8 offer_tick Tick when the outstanding offer identity was created; zero when no offer is outstanding
192 8 offer_parent_genome Parent genome identity bound by the offer; zero without an offer
200 8 offer_parent_digest Parent genome digest bound by the offer; zero without an offer
208 8 context_seed Recorded M3 seed; zero without an offer
216 4 context_stream Recorded M3 stream; zero without an offer
220 8 context_event_index Must equal mutation_event_index for an outstanding offer
228 2 candidate_count 0 without an offer; otherwise 1..3 and equal to the encoded candidate count
230 2 reserved Zero
232 4 context_growth_realized Recorded growth at offer creation
236 4 context_growth_damage Recorded damage at offer creation
240 4 context_temperature Recorded millikelvin environment
244 4 reserved Zero
248 40 context_available Recorded five-channel development environment inventory
288 192 candidates Eight 24-byte candidate slots; unused slots are all zero

Each candidate slot stores operator id (u16), capability target (u8), effect (u8), successor parameter (u32), derived maintenance (u64) and derived total mass (u64). Used slots are the exact canonical M3 output in operator-id order. Restore recomputes the candidates from the archived parent genome and recorded context and requires exact equality; a list cannot be rewritten independently of its seed. No ranking is encoded.

The context's requested candidate count is three under cellular rules version 2. M3 may return fewer when fewer than three operators apply; an empty result does not consume fed credit or an event index. Restore recomputes with the requested count of three and requires exact equality with the encoded 1..3 candidate list.

The offer identity is (life_id, mutation_event_index, offer_tick). A current simulation tick later than offer_tick does not itself invalidate the offer; the client must echo the recorded offer identity. Selection still checks that the parent's current genome and the recorded context match. The offer is rejected if either changed or if the identity was already consumed.

With no outstanding offer, every offer-specific field and candidate slot is zero. With an offer, the tick, parent genome identity/digest, seed, stream and event index are nonzero; candidate count equals the recorded context count; reserved fields and padding are zero. An outstanding offer's event index is the record's mutation_event_index. Event index overflow refuses the complete candidate tick.

Mutation credit and migration

Credit increases only by the energy actually acquired from a provisioned food patch and retained in that committed tick's reserve. Opening reserve and energy from other owners do not count. One committed tick contributes once, regardless of action retry. One event is earned per 60 seconds of the life's current per-second maintenance energy, with exact checked integer arithmetic and a carried remainder. At most one offer is outstanding; further earned credit is retained until the next offer can be created. This cadence is a versioned trial value under ADR-0120.

The explicit v1-to-v2 migration copies the complete v1 region closure, changes no tick, inventory, life/genome/archive/habitat/corpse identity or transfer, and sets fed_energy_credit=0, mutation_event_index=0, offer_tick=0 and all offer fields to zero for every living life. It creates no action, birth, death, history event or outbox row. See ADR-0119 for the manifest/database/replay link.