Files
aevolution/schemas/coupled-resources.md

2.3 KiB

Coupled resource snapshot v1 (M6.5a)

Little endian, bounded to 72 MiB, corruption checksum FNV-1a-64 (not authentication). No native layouts or pointers. Nested terrain and field codecs retain their versions. This format has no source rates or biological process state: it must not be used to resume a rate-enabled fixture. M6.5c requires a new complete fixture envelope.

Header: magic u64 0x31504c43564f4541, format u32=1, total length u32, world u64, frame u64, adoption command watermark u64, account count u32, history count u32, terrain payload length u32, field payload length u32. Then terrain bytes, field bytes, accounts and chronological retained history; finally checksum u64 over all preceding bytes. Account: ID u64, ten u64 balances, ten u64 capacities (Field order). History: command u64, tick u64, leg count u32; each leg is voxel x/y/z i64 (two's complement), organism ID u64, field u8, direction u8, amount u64. No ring position or unused entries are serialized. Restore packs history in order.

Require 1..64 sorted unique accounts, 0..64 histories, 1..32 legs per history. Commands strictly increase above adoption watermark; last equals the field command (or adoption equals field command if empty). Validate every endpoint/tag/amount. Reverse the retained legs from current stocks to verify supplies and capacities of each prior state. This establishes plausible retained transfers, not authentic history. Revalidate field/terrain identity and mapped substrate; all mapped chunks must be present in the nested terrain snapshot. Query tokens never survive restore.

Restore receives total-owner, field and terrain budgets. Charge owner/scratch first, then fields, then terrain under remaining total allowance. Input/output buffers and nested codec decode scratch follow the existing codec exclusions; fixed reverse-audit scratch is bounded to 32KiB and runs separately from transfer staging. Allocation failures propagate before any returned owner. Failure leaves the caller's existing owner untouched.

Snapshot/restore are pure buffer operations with exclusive host access. They do not publish files, fence duplicate processes or acknowledge durability. Tests must cover canonical bytes, exact/changed retries after restore, continuation, ring wrap, truncation/corruption, recomputed-checksum malformed state, identity and budgets.