Implement M5.5 atomic terrain excavation and debris accounting

This commit is contained in:
dingo
2026-09-26 14:56:44 -04:00
parent 25ac646f93
commit 8b5bf48795
19 changed files with 770 additions and 30 deletions
+7 -7
View File
@@ -14,7 +14,7 @@ The owning unique_ptr may move, but the store itself cannot move or copy.
| Operation | Success | Refusal / invariant |
|---|---|---|
| minimum_bytes(slots) | Store object + fixed directory + 17 KiB scratch reservation | Invalid slot count rejected before multiplication |
| minimum_bytes(slots) | Store object + fixed directory + replay records + 32 KiB scratch reservation | Invalid slot count rejected before multiplication |
| create | Empty store with validated descriptor | Invalid config/version/budget before directory allocation |
| load(address) | Return current token or regenerate and publish one base chunk | Invalid address, slot or byte exhaustion, revision exhaustion; no existing state changes |
| view(address) | Token for loaded address | Missing is explicit; no implicit load |
@@ -29,7 +29,7 @@ an object later allocated at the same address. They cannot authorize persistence
cross-process operations. Epoch exhaustion is checked before increment; no wraparound.
Dirty marking currently changes only lifecycle metadata, not geometry. There is no
clear-dirty or cell-edit API. M5.5 must introduce accounted edit transactions; M5.6/5.7
clear-dirty API. M5.5 now adds [accounted excavation](TERRAIN_EDITS.md); M5.6/5.7
must establish durable revision coverage before permitting cleanup. Destruction at
host shutdown frees memory and is not a save operation. No production host should
use this in-memory store as its sole durable copy of changes.
@@ -62,8 +62,8 @@ not a wire format. M5.6 must specify canonical serialization independently.
Fixed directory bytes include optional payload objects and lifecycle metadata for
all configured slots, occupied or not. Accounted bytes add exact allocated payload
array element sizes plus a permanent 17 KiB allowance for load construction scratch:
4096 logical words and 256 palette keys. Load generates through point queries to avoid
array element sizes plus a permanent 32 KiB conservative scratch allowance and fixed replay records
under ADR-0046. Loads use 4096 logical words and 256 palette keys. Load generates through point queries to avoid
an extra dense vector, computes required payload before allocation, then publishes
without throwing. On allocator failure existing state is unchanged; allocation
exceptions propagate to the host. Clean eviction subtracts payload only.
@@ -84,6 +84,6 @@ tokens, conservative dirty pinning and rejection without changing resident state
Existing generator goldens remain active. Counter exhaustion is guarded in code but
not forced via a public test-only state injection API.
M5.5 adds transaction IDs, payload identity, expected revisions, material destinations
and atomic edits. No transactional edit, snapshot, crash recovery, threading, automatic
LRU, renderer or Kubernetes integration is provided by M5.4.
M5.5 now adds transaction IDs, full request identity, expected revisions, a finite debris
destination and atomic excavation; see TERRAIN_EDITS.md. Snapshot/crash recovery,
threading, automatic LRU, renderer and Kubernetes integration remain later work.
+96
View File
@@ -0,0 +1,96 @@
# 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.