97 lines
5.3 KiB
Markdown
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.
|