Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m59s
Foundation / checks (checks) (push) Failing after 2m10s
Foundation / checks (postgres) (push) Failing after 10m34s
Foundation / checks (network) (push) Failing after 12m19s
Foundation / checks (tsan) (push) Failing after 2m14s
Foundation / checks (client) (push) Successful in 15m7s
Foundation / postgres-tools (push) Skipped
Foundation / server-image (push) Skipped
Foundation / image (push) Skipped
171 lines
11 KiB
Markdown
171 lines
11 KiB
Markdown
# Region commit manifest contract v1 (M7.1 design, M7.4a encoding)
|
||
|
||
M11.2 adds the portable [primitive creation profile 3](primitive-checkpoint-v1.md)
|
||
using manifest v2. M11.3 adds profile 4, the
|
||
[cellular lives profile v1](cellular-lives-v1.md), with its own version bundle,
|
||
payload bound and restore validator. M11.4 adds the compatible cellular-v2
|
||
[checkpoint](cellular-lives-v2.md) and its explicit no-tick version migration
|
||
(ADR-0119). M11.4c adds cellular-v3
|
||
[checkpoints](cellular-lives-v3.md) 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](cellular-lives-v1.md).
|
||
Version bundle 2 is `(2,2,1,1,1,2,1,1,1)` and uses
|
||
[cellular-lives-v2](cellular-lives-v2.md); the ninth slot pins mutation state.
|
||
Version bundle 3 is `(2,3,1,1,1,2,1,2,1)` and uses
|
||
[cellular-lives-v3](cellular-lives-v3.md); 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.
|