Files

5.3 KiB

M5.5 transactional excavation

ADR-0046 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.

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 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.