Files
aevolution/docs/world/TERRAIN_EDITS.md
T

97 lines
5.3 KiB
Markdown

# M5.5 transactional excavation
[ADR-0046](../adr/0046-transactional-excavation.md) scopes the first terrain edit to
excavation. Public contracts are in `evo/world/chunks.hpp`; implementation is in
`src/world/edits.cpp`. All calls require one sequential owner and stable request memory
through return. Inputs are intentions, never trusted geometry or authoritative balances.
## Request and atomic scope
An ExcavationRequest names a nonzero command ID, destination 1 (this store's debris),
a server-verified digest and 1..64 CellCuts. Cuts touch at most four loaded chunks in
one store. Each names chunk/local address, expected revision and removed fill in
[1,65535]. Sort lexicographically by chunk x/y/z, then X-fast local ordinal; duplicate
cells and inconsistent revisions within one chunk are rejected. No implicit load or
cross-store/world/region transaction occurs. No deposit, arbitrary replacement,
material transmutation, biological cost or external inventory is implemented.
```mermaid
sequenceDiagram
participant Host
participant Store
participant Prepared
Host->>Store: command + digest + ordered cuts + expected revisions
Store->>Store: Validate shape, digest, replay identity, ownership and revisions
Store->>Prepared: Copy logical cells and stage compact replacements
Store->>Store: Check source volume, debris capacity, old+new peak bytes
alt all checks and allocations succeed
Store->>Store: Publish all chunks + debris + revisions + replay receipt
Store-->>Host: receipt
else any refusal or allocation failure
Store-->>Host: error; original state remains intact
end
```
Published chunks get distinct increasing local revisions and dirty flags. Previous
views become stale; query `view` for current read tokens. The returned receipt lists
historical committed revisions and removed volume by material, not current live views.
Dirty chunks remain unevictable. Mutation of already-dirty chunks is allowed with
current revisions. Geometry and debris commit together without throwing; all fallible
allocations precede publication. Host must handle allocation exceptions. This is
in-process atomicity, not crash consistency, client authentication or a durable ACK.
## Volume conservation and explicit destination
`VolumeUnits{n}` means n/65535 cubic metres at the v1 1m pitch. A CellSample's fill
is already in these units. DebrisCapacity specifies independent uint64 capacities for
rock and regolith at store creation; defaults are zero and balances start empty.
Unknown destination IDs are rejected. No public capacity change, withdrawal or balance
setter exists. Material keys alone never grant debris supply.
For each material m and committed command:
`sum(terrain fill[m])_after + debris[m]_after = sum(terrain fill[m])_before + debris[m]_before`.
Partial excavation reduces fill with the same material ID. Removing the full fill
produces structurally valid void. Rock cannot credit regolith or vice versa. Compare
credits to capacity minus balance before adding, avoiding unsigned overflow. Bounded
commands remove at most 64*65535 units. Geometry of the removed sub-cell portion is
unknown; no collision shape or smooth surface is claimed.
These inventories are volume, not kg/femtograms. M6 must define density/composition
and reconcile them without double-counting before coupling to biology. No value in
the existing biological ledger is reinterpreted or modified by this gate.
## Retry identity and compatibility
The [request digest schema](../../schemas/world-edits.md) defines the explicit byte
order. FNV-1a is an accidental-corruption/identity aid, never security. Retained command
IDs compare all original fields as well as digest, so collisions cannot authorize a
changed request. For valid request shape and digest:
- Same retained ID and exact payload returns the original receipt without reapplying,
even after newer edits made its expected revisions stale.
- Same retained ID with different payload returns command_conflict.
- An ID <= the high-water mark with no retained record returns stale_command.
- A fresh ID must exceed the high-water mark; gaps are permitted. Failures consume no
ID and mutate no cells, debris, revision, dirty flag or history record.
Only the last 64 successful commands are retained in a fixed ring. This is bounded
local retry history, not event retention. M5.6/5.7 must persist geometry, debris,
capacities, revisions, command high-water and replay records consistently. A restart
that retains only geometry would duplicate or lose material and is not supported.
## Memory and tests
minimum_bytes now includes the fixed 64-record replay array and 32 KiB conservative
scratch reservation, superseding M5.4's 17 KiB allowance. New replacement payloads
must fit beside all old payloads; old storage is released only during commit. Unused
replay fields remain bounded metadata. No cache eviction occurs to accommodate edits.
Allocator/runtime overhead and caller buffers remain outside accounted bytes.
CTest world-edit-contracts covers a seam crossing, all four chunks/64 cuts, partial
fill, rock/regolith conservation, destination and second-replacement memory failures,
missing/stale/source failures, dirty eviction refusal, malformed request bounds,
same/changed retries and expiry after 65 commands. Existing generator and simulation
goldens remain active. Allocator fault injection and crash recovery remain future work.