Files
aevolution/schemas/region-commit.md
T
dingo 7b6f722b1b
Foundation / checks (deploy) (push) Successful in 5s
Foundation / checks (ecs) (push) Successful in 1m59s
Foundation / checks (client) (push) Successful in 12m24s
Foundation / checks (network) (push) Successful in 13m51s
Foundation / checks (tsan) (push) Successful in 8m7s
Foundation / checks (checks) (push) Successful in 33m53s
Foundation / checks (postgres) (push) Successful in 46m23s
Foundation / server-image (push) Successful in 24s
Foundation / postgres-tools (push) Successful in 1m36s
Foundation / image (push) Successful in 2m45s
Declare portable primitive checkpoint profile (M11.2c-2b)
2026-10-10 05:00:15 -04:00

148 lines
9.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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. Its history, versions, payload and trace rules differ from the
environmental profiles below. Schema v15 does not yet admit profile 3; guarded
atomic publication is a separate migration requirement.
## 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.