Files
aevolution/docs/adr/0046-transactional-excavation.md
2026-10-08 12:08:53 -04:00

3.9 KiB

[Reviewed]

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.