ADR-0176 and schema 57 admit raw cellular bundle 13 (rules 11 on owner format 9) through parser-local normalization to bundle 12, and a fenced no-tick 12 -> 13 upgrade that declares the region's light; recovery reads the light from the target and re-derives the whole target from the source. The resumable cellular-v8 opening provisions a cellular-v7 genesis, one empty tick and the durable upgrades to bundle 13. Session v12 adds the owner's captured light and the producers it can see to its perception, and lets offers name photosynthesis; older sessions keep their layouts and never receive photosynthesis candidates. The client draws chloroplasts by efficiency, shows sunlight in the HUD and offers photosynthesis cards. DEV now provisions and serves region 9 with the trial light; region 8 stays stored but unserved. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
14 KiB
Region commit manifest contract v1 (M7.1 design, M7.4a encoding)
M12.5/schema 57 adds raw cellular bundle 13 (11,9,2,1,1,5,4,2,1): rules 11 on owner
format 9 with declared light, history 4, trace 4, profile 4 only. It arises only from the
fenced no-tick 12 -> 13 upgrade, whose light recovery reads from the target and re-derives
from the source. See ADR-0176.
M12.5c/schema 56 adds profile 6, cellular_environment_v1, with history profile 6.
Its payload is the joint envelope nesting population
envelope 2 (bundles 10 and 11 only), capped at 16,782,416 bytes. A nonempty trace is
a joint batch of 184..1,971,480 bytes, a multiple
of 8; an empty trace with equal ticks is the explicit one-way, no-tick 5 -> 6
transition. Genesis and cloning are refused. Ordinary continuation keeps profile and
bundle. See ADR-0174.
M12.4f adds the portable bundle-10 declaration (8,7,2,1,1,4,3,2,1) for
owner-7 boundary accounting, with unchanged rules 8. Profile 4 uses raw owner 7
and history 4; profile 5 uses population envelope 2, batch 2 and history 5.
An explicit bundle-9 to 10 upgrade preserves the representation and biological
tick, advances sequence and retains its predecessor digest; trace/decisions are
zero. Bundle-10 genesis is forbidden. Ordinary continuation and representation
transitions preserve the exact bundle. Retained bundle 9 keeps envelope/batch 1.
These portable readers and candidate constructors grant no database authority:
SQL schema 45 still rejects bundle 10. See ADR-0145.
M12.4g/schema 46 subsequently admits that tuple through the fenced version-upgrade
publisher and its immutable cellular_profile_migrations evidence, for either
profile. The profile is unchanged across an upgrade; profile transitions retain
their separate journal and require the same tuple on both ends. Pending intervals
block a new upgrade. Bundle 10 binds population trace 2; bundle 9 still binds
trace 1. Recovery rederives the entire source/target upgrade, not merely its stock
totals. No paired biological migration trace is admitted by this schema. See
ADR-0146.
M11.2 adds the portable primitive creation profile 3 using manifest v2. M11.3 adds profile 4, the cellular lives profile v1, with its own version bundle, payload bound and restore validator. M11.4 adds the compatible cellular-v2 checkpoint and its explicit no-tick version migration (ADR-0119). M11.4c adds cellular-v3 checkpoints for append-only genome revision history (ADR-0122), with a separate no-tick v2-to-v3 migration. 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 cellular-v1/v2; 4 with cellular-v3 |
| 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 in the first eight u32 version slots. Version bundle 1 is
(1,1,1,1,1,2,1,1,0) and uses cellular-lives-v1.
Version bundle 2 is (2,2,1,1,1,2,1,1,1) and uses
cellular-lives-v2; the ninth slot pins mutation state.
Version bundle 3 is (2,3,1,1,1,2,1,2,1) and uses
cellular-lives-v3; its archive slot selects revision
history format 2. The tick quantum remains 50,000 μs. All three bundles use the
bounded profile-4 trace and bind their decision blocks transactionally. A
region's ordinary successor keeps its exact version bundle. Only the explicit
leased migration commits in ADR-0119 and ADR-0122 may transition v1 to v2 or v2
to v3 at an unchanged tick, with immutable source and target links; generic
cellular publication cannot change versions or publish a zero-tick commit.
Profile-4 clone genesis remains unsupported until cellular identity remapping
is specified. Migration 18 admits profile 4, and the dedicated cellular
publisher binds 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.