# Region commit manifest contract v1 (M7.1 design, M7.4a encoding) ## Canonical manifest encoding v1/v2 (ADR-0061, ADR-0063) The encoder, decoder and `supported()` check live in `src/persistence/region_checkpoint.cpp`; `evolution.parse_checkpoint_manifest` mirrors them in SQL. The record is exactly 280 bytes, all integers little-endian, with no padding or trailing checksum. The commit digest is SHA-256 of the whole record, and each commit row stores it. | Offset | Size | Field | |---|---|---| | 0 | 8 | magic `AEVORCM1` | | 8 | 4 | manifest_version = 1 (other values are unsupported) | | 12 | 4 | profile: 1 = environmental-v1, 2 = environmental-lineage-v1 (ADR-0062) | | 16 | 24 | world, region, frame (nonzero u64 each) | | 40 | 16 | commit_id (nonzero; globally unique in the database) | | 56 | 8 | commit_sequence | | 64 | 16 | predecessor_commit_id (zero only at genesis; never equal to commit_id) | | 80 | 32 | predecessor manifest SHA-256 (zero only at genesis) | | 112 | 16 | begin_tick, end_tick (genesis 0/0; otherwise 1..64 tick delta) | | 128 | 16 | lease holder (zero only at genesis) | | 144 | 8 | lease epoch (0 only at genesis) | | 152 | 8 | tick_microseconds (nonzero; fixed for the region) | | 160 | 36 | nine u32 versions: rules 2, envelope 2, resources/fields/terrain/coordinate/generator/material/interval-adapter 1 | | 196 | 32 | retained build identity (nonzero; `retained_builds` row required) | | 228 | 4 | rng_streams = 0 (these rules use no randomness) | | 232 | 4 | history_profile: 0 with profile 1; 1 (lineage archive 1 + genome schema 1) with profile 2 | | 236 | 4 | durability_policy = 1 (single-volume development) | | 240 | 8 | payload_bytes: profile 1 is 1..1 MiB; profile 2 is 1..4,268,144 | | 248 | 32 | payload SHA-256 (nonzero) | | 280 | 8 | v2: trace bytes, exactly 96 + 304·(end_tick − begin_tick); 0 at genesis | | 288 | 32 | v2: trace SHA-256 (nonzero except at genesis) | | 320 | 4 | v2: decision count 0..8 | | 324 | 4 | v2: reserved, must be 0 | | 328 | 32 | v2: decision block SHA-256, all zero exactly when the count is 0 | A structurally invalid record is malformed (SQL 22023). A record that parses but has an unsupported version, profile, RNG, history or durability declaration is unsupported (EVL06). Values above 255 are never truncated onto a supported enum. Profile 2 payloads are schemas/environmental-lineage-v1.md containers. A region never changes profile, history, RNG or durability declarations; schema v4 enforces this against the predecessor. For profile 1, the payload is the exact environmental envelope format 2; its object key is the hex payload SHA-256 in the region's namespace. Decisions, trace and outbox are not encoded here: M7.5 adds them under a new manifest version. Manifest v2 (M7.5) is 360 bytes. Offset 8 holds 2, and the v1 fields keep their offsets. v1 records from M7.4 remain decodable but are never written again, and schema v5 admits only v2 for new commits and genesis. The trace object and decision block are defined in schemas/region-batch.md. Publication sends the manifest and the exact decision block together. The database records the decisions and their outbox rows in the same statement as the head. An identical retry of a committed ID returns the original receipt. **Clone genesis (M7.9, schema v7, ADR-0067).** Sequence 0 may name an origin, in manifest v2 only: - Offsets 64 and 80 hold the source commit ID and the SHA-256 of the source manifest. Both are nonzero, and the commit ID differs from this one. - begin_tick = end_tick = the source end tick. - Holder, epoch and trace are zero. - Offsets 320/328 count and digest the inherited decision block (0..8 records, ticks 1..end_tick, same encoding as schemas/region-batch.md). - World differs from the source world. Profile, versions, quantum, frame and build equal the source's. A provisioned genesis still has zero origin fields, tick 0/0 and no decisions. A half-present origin is malformed. The payload is the source payload re-identified to the clone's world. The source world and region are recorded in the target database's `region_origins`, not in the manifest. Authority: ADR-0058 and docs/architecture/REGION_DURABILITY.md. Logical schema, not an implemented wire codec, SQL migration or permission to serialize structs. M7.2 chooses concrete storage types preserving these domains; M7.4 specifies canonical byte encoding and tests before publication. No format may silently truncate u64 to a signed database integer. No credentials or executable URLs. | Field | Domain / invariant | |---|---| | manifest_version | Exactly 1 | | world_id, region_id, frame_id | Nonzero u64; durable provisioned identities | | profile | Explicit enum: environmental-v1 initially; unknown values reject | | commit_id | Opaque globally unique 128-bit request identity, immutable across retries | | commit_sequence | u64; genesis 0, otherwise predecessor+1 without wrap | | predecessor_commit_id / digest | Absent only for genesis; otherwise exact committed head | | begin_tick / end_tick | u64; begin equals predecessor end; 1..64 tick delta except genesis 0/0 | | holder / epoch | Unique holder identity and nonzero u64 acquisition epoch; checked in DB | | tick_microseconds | Positive u64 matching nested immutable config | | version_bundle | Exact required rule/schema/generator/coordinate/material versions plus retained build artifact identity | | payload_key | Opaque immutable store key resolved only in configured namespace | | payload_bytes / sha256 | Positive length <=1MiB for environmental-v1; 32-byte strong content digest | | canonical_request / request_sha256 | <=160KiB canonical publication metadata, trace and ordered decisions; binds payload digest and predecessor; SHA-256 is not authentication | | validation_trace | Complete ordered EnvironmentalInput/Report pairs for each tick in this batch, <=64; included in canonical request identity; <=64KiB separately from decision bytes | | decisions | <=64, sorted unique durable request IDs, canonical input/result and outcome type; combined request/result <=64KiB | | history/outbox rows | Deterministically derived from decisions; same transaction and commit reference, stable event IDs | | durability_policy | Explicit configured profile verified at deployment; no assumed host-loss guarantee | The commit digest is SHA-256 of canonical publication metadata and ordered decisions (excluding the digest itself and DB timestamps). Payload SHA-256 covers the exact uncompressed payload bytes. It is distinct from nested FNV checksums. Use a vetted digest provider selected/pinned in M7.2, never implement crypto here. The build identity refers to an immutable retained artifact and is part of the allowlist; a semver string alone cannot authorize recovery. Initial payload: complete M6 environmental envelope, rules=2/format=2; nested coupled resources/fields/terrain formats=1 and coordinate/generator/material=1; interval adapter=1 has no payload state. Outer world/frame/end tick must equal nested identity/tick/field revision. Region mapping is manifest-owned and immutable within the provisioned region. Both organism account IDs remain local to that region; a future globally bound profile requires explicit ownership mapping. environmental-v1 refuses player sessions, reproduction, genome/lineage bindings, population ownership and external transfers. Its permanent outcomes are only the two fixture terminal transitions, identified by region+actor, and recorded atomically with checkpoint state. Ordered accepted host input identifies the cause/request; depletion-derived death uses a deterministic region/tick/actor event identity. The committed predecessor's terminal state cannot become active. Every new terminal transition in the admitted batch requires exactly one outcome; no unchanged/dead actor may yield a new death event. Verify the batch input/report trace against the predecessor during staging and compare its resulting bytes to the uploaded candidate. At <=64 ticks this trace is bounded; this is commit validation, not a retained recovery replay tail. Opaque caller-supplied events alone cannot validate a checkpoint. Persist canonical causal requests in receipts. Lineage-capable profiles remain unassigned: they require a complete archive codec, organism/genome mappings, allocator state, all phenotype/development progress and random streams actually used. Their durable history includes extinct genomes; they cannot reuse environmental-v1 with missing sections. Implement this extension before claiming the M7 retained-ancestry exit criterion. Database commit operation: lock lease row; validate holder/epoch/unexpired authority; check commit-ID deduplication and exact canonical bytes; validate expected head; insert manifest + decisions/history/outbox and advance head atomically. For exact previously committed IDs, resolution can return the original immutable receipt without new mutation even under a later epoch. A stale writer cannot use that receipt to obtain current readiness. Changed bytes conflict. No decision may reference a future or uncommitted manifest. One in-flight commit and fixed metadata/input bounds avoid unbounded ambiguity queues. Genesis uses a distinct provisioning operation, never ordinary recovery. Objects cannot be collected merely because they precede the current head; decision records, archives, clones and backups may still reference them. No GC in initial M7.