Implement M5.5 atomic terrain excavation and debris accounting
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user