Files
aevolution/schemas/region-commit.md
T
dingoandClaude Opus 5.5 a2c4543df2 Complete M7.4b lineage checkpoint profile; M7.4 done
ADR-0062 adds a canonical LineageArchive codec (parents before children,
organisms by id, FNV) that decodes by replaying admit/record_birth/
record_death and requires byte-identical re-encoding; it never overwrites
an existing archive. LineageRegion binds the environmental producer and
consumer accounts to archived organisms with identity high-waters,
enforces closure (lifecycle vs deaths, exact living set, tick bounds)
and records deaths in the tick that causes them.

Checkpoint profile 2 (environmental-lineage-v1, history profile 1)
publishes that container; schema v4 admits it with a 4,268,144-byte cap
and requires each commit to keep its predecessor's profile, RNG, history
and durability declarations. Linux adds provision/publish/recover for
the profile on the shared publication path.

Qualification found WSL2 stepping CLOCK_REALTIME back ~0.5 s every ~32 s,
which made two 1 s-lease tests flaky under ASan. Tests now wait on
database-time expiry; ADR-0060 records the slewed-clock requirement.

Validated: Windows CTest 57/57; Linux GCC Debug/Release, clang-tidy and
ASan/UBSan CTest 57/57 each; PostgreSQL suites 2x Release, 2x analysis,
5x ASan; SQL and C++ mutations each caught. No Docker/Gitea CI, remote
store, process kill or deployment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-28 16:43:10 -04:00

114 lines
7.6 KiB
Markdown

# 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, 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) |
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.
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.