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
+5
View File
@@ -61,3 +61,8 @@ apply backpressure rather than dropping state. Larger workloads require measurem
Test far-apart chunks, uniform/palette/dense equality, exact budget boundaries,
slot exhaustion, invalid input, stale/foreign views and dirty eviction refusal.
Retain existing generator goldens and simulation formats. Next is M5.5.
## M5.5 follow-up
ADR-0046 adds atomic excavation and fixed replay metadata. Its 32 KiB scratch
reservation supersedes the original 17 KiB allowance; dirty clearing remains absent.
+67
View File
@@ -0,0 +1,67 @@
# ADR-0046: Atomic local excavation and material volume accounting
## Status
Accepted for M5.5 bounded excavation only. Not mass, energy, chemistry or durability.
## Context
Cell fill denotes volume, not kilograms. Excavation must not erase occupied material.
M5.4 owns immutable chunks and rejects dirty eviction; transactions can prepare new
payloads before publishing. Distributed edits and persistence are later boundaries.
## Decision
Implement excavation only, with 1..64 unique ordered cuts touching at most four loaded
chunks in one store. Each cut names chunk, local cell, expected local revision and
positive removed fill numerator. Require lexicographic chunk order then X-fast cell
ordinal, no duplicates. Coordinates, fill bounds, material membership, revision and
source supply are checked. No implicit loading, deposits, conversions or unbounded edits.
One named destination (debris=1) is owned by each store. Creation specifies separate
finite rock/regolith capacities, initially empty; defaults are zero. Credit exactly
removed fill units by material. One unit is 1/65535 cubic metre at the v1 1m pitch.
No density/mass conversion is assumed, and debris is not a second copy of terrain.
Invariant per material: occupied volume + debris volume unchanged by every commit.
M6 must explicitly reconcile these inventories with its material/density/composition
model; no biological ledger femtogram values are fabricated from volume.
Request carries nonzero monotonically increasing command ID, destination, cuts and
server-verified FNV-1a request digest over explicit fields (see contract). This is not
cryptography/authentication. Retain 64 successful requests and receipts, including
full payload equality so hash collisions cannot authorize changed-payload retries.
Same retained ID/exact request returns the original receipt before checking now-stale
revisions; changed payload is rejected. IDs <= high-water mark outside retention
are stale, never executed again. Failed requests consume no ID; no out-of-order commits.
Prepare all compact replacement chunks and validate destination capacity and peak
budget while originals remain owned. Publish geometry, debris, revisions, dirty flags,
high-water mark and replay record in one nonthrowing single-owner phase. Allocation
failure before publish leaves state intact. Every touched chunk gets a new revision
and becomes dirty. No durable acknowledgement or dirty clearing is introduced.
Charge the fixed replay directory plus a conservative 32 KiB scratch allowance
(replacing 17 KiB), and all old plus new payloads at preparation peak. No automatic
cache eviction on memory failure. Caller buffers and allocator overhead remain excluded.
Retain current tokens only by re-query; receipts contain historical revisions.
## Alternatives Considered
A sink destroys matter. A client-owned destination cannot be atomically credited with
private chunk state. Reusing the biological mass ledger would invent a density model.
Generic deposit/replacement edits enlarge the first mutation surface without evidence.
Digest-only replay is unsafe even with a strong hash; exact payloads are bounded here.
## Benefits
Real multi-chunk excavation, conserved typed volume and atomic failure/retry behavior.
No persistence fiction or cross-domain unit conversion.
## Costs
Bounded fixed replay metadata, conservative peak memory, ordered commands and only one
destination. Same-store single owner only. Debris cannot be withdrawn in this gate.
## Risks
Crashes lose this entire in-memory state; M5.6/5.7 must persist debris, revisions,
command high-water/retention and geometry consistently. FNV is not authentication.
Allocation exceptions still require host handling; budgets are not RSS limits.
## Consequences
Test seam-crossing cuts, partial fill, capacity/source/stale failure with no partial
publication, same/changed retries, retention expiry, unknown destination/material,
invalid/duplicate/order/size requests and peak-memory rejection. Keep existing goldens.
+2
View File
@@ -49,3 +49,5 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0044: Abiotic generation](0044-abiotic-generation.md) - accepted for M5.3 synthetic integer base, version retention and material table.
- [ADR-0045: Bounded chunk ownership](0045-bounded-chunk-ownership.md) - accepted for M5.4 local memory, revision tokens and dirty eviction guards.
- [ADR-0046: Transactional excavation](0046-transactional-excavation.md) - accepted for M5.5 atomic local volume transfers and bounded exact-request replay.