Files
aevolution/schemas/region-commit.md
T
dingo b25787f8e6
Foundation / checks (client) (push) Successful in 5s
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (checks) (push) Failing after 38s
Foundation / checks (postgres) (push) Failing after 52s
Foundation / checks (tsan) (push) Failing after 33s
Foundation / checks (ecs) (push) Successful in 2m3s
Foundation / postgres-tools (push) Skipped
Foundation / server-image (push) Skipped
Foundation / image (push) Skipped
Allow cellular profile in checkpoint parser
2026-10-10 22:49:09 -04:00

10 KiB
Raw Blame History

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

M11.2 adds the portable primitive creation profile 3 using manifest v2. M11.3 adds profile 4, the cellular lives profile, with its own version bundle, payload bound and restore validator. These formats do not change profiles 1–3. PostgreSQL admission and atomic publication are separate migration requirements.

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, 3 = primitive-lives-v1, 4 = cellular-lives-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: environmental/primitive bundles as below; profile 4 has cellular rules, envelope, habitat, coordinate, genome, development, founder, archive, then reserved zero
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 with profile 2; 2 with profile 3; 3 with profile 4
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; profile 3 is 1..3,266,800; profile 4 is 1..16 MiB
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 4 pins cellular rules/envelope/habitat/coordinate/genome/development/ founder/archive as eight u32s, with the ninth version word zero. Its tick quantum is 50,000 μs; its v2 trace retains the standard 96 + 304·tick encoding, and its decision block is transactionally bound like other progressing profiles. Profile 4 clone genesis is unsupported until cellular identity remapping is specified. Migration 18 accepts and classifies this profile, but a database trigger currently rejects every progressing profile-4 commit until the dedicated cellular publisher atomically records its tick evidence. Profile 3 retains its creation-only trace and zero-decision rules. 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.