Files
aevolution/schemas/region-commit.md
T
dingoandClaude Opus 5.5 5d4f59f901 Implement M7.4a checkpoint publication and verified recovery
ADR-0061 publishes environmental-v1 full checkpoints. Manifest v1 is a
fixed 280-byte record (identity, chain, lease, versions, build, zero
RNG/history declarations, durability policy, payload length/SHA-256)
that PostgreSQL parses and digests itself. Schema v3 adds region_commits
with a digest CHECK and a composite head FK, owner-managed retained
builds, fenced publish/load functions and owner-only genesis; it drops
the bare v2 head kernel and fails closed while v2 heads exist.

Linux evo::region_store adds OpenSSL SHA-256, an immutable
content-addressed filesystem object store (temp+fsync+link, no
overwrite/delete, O_NOFOLLOW exact-length verified reads), and
publication (validate -> upload -> read back -> fenced transaction ->
receipt check) and recovery (re-digest, allowlist, verify, full restore).
Portable evo::region_checkpoint holds the codec and payload validation.

Validated: Windows CTest 56/56; WSL Release, clang-tidy and ASan/UBSan
private-PostgreSQL suites; four SQL and one host mutation each caught.
M7.4 stays open for 7.4b (lineage archive codec and history binding).
No Docker/Gitea CI, remote store, process kill or deployment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 15:25:27 -04:00

7.3 KiB

Region commit manifest contract v1 (M7.1 design, M7.4a encoding)

Canonical manifest encoding v1 (ADR-0061)

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
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 (no genome/lineage state)
236 4 durability_policy = 1 (single-volume development)
240 8 payload_bytes (1..1 MiB)
248 32 payload SHA-256 (nonzero)

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. 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.

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.