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