Define M5.1 local voxel contract and expand M5-M9 gates

This commit is contained in:
dingo
2026-09-26 10:06:22 -04:00
parent c237e4da97
commit 69bbf364a9
14 changed files with 778 additions and 12 deletions
+70
View File
@@ -0,0 +1,70 @@
# ADR-0042: Bounded local voxel addresses and logical cells
## Status
Accepted for M5.1 only. No chunk storage, generator, persistence, mesher, spherical
planet mapping or world-size choice is adopted. ADR-0019 remains proposed for those
choices. Existing particle coordinates and snapshot formats are unchanged.
## Context
M5.2 must compare layouts against a stable logical domain. C++ integer division
truncates toward zero, which assigns negative cells to the wrong chunk unless the
mapping explicitly uses floor division. Unbounded signed arithmetic also risks
undefined behavior before an invalid address can be rejected.
## Decision
Use a right-handed local Cartesian frame: +Z up and X cross Y = Z. Signed voxel
coordinates identify lower corners of half-open cells. All axes are in
[-1,048,576, 1,048,576); one cell spans 1,000 millimetres for this experiment. The
address envelope is an arithmetic guard, not allocated space or a planet extent.
The initial storage experiment should touch roughly 100 cells per axis.
Chunk edge is explicit, with candidates 8, 16, 32 and 64 cells. No default or
preferred candidate is selected before M5.2 measures them. All divide the domain
exactly. Chunk coordinates are floor(voxel/edge), local offsets are nonnegative
remainders. Join validates edge, chunk and local bounds before multiplication.
Logical ordinal order is X-fastest, then Y, then Z. It is an enumeration convention,
not a mandated physical layout. Mapping functions allocate nothing, perform no I/O,
and use checked integer bounds with typed recoverable errors.
A logical cell has a 16-bit material key and unsigned fill numerator over 65,535.
Material key zero means void and must have zero fill; a nonzero key requires positive
fill. The containing material table is versioned later; this layer validates only
structural consistency, not material existence. Fill denotes occupied volume fraction,
not a signed distance, density, chemical inventory, collision shape or mesh sample.
Sub-cell placement is unknown. A change in fill does not itself authorize matter
creation/destruction; edits must supply material accounting in M5.5/M6.
The coordinate contract is local version 1. A future world key must include world
and frame identity and all layout/generator/material versions. Changing edge or
resolution is an explicit repartition/migration, never reinterpretation of stored
chunk keys. Region ownership and ecological cell boundaries are separate mappings.
## Alternatives Considered
Truncating division breaks negative seams. Unsigned-only positions hide origin
crossings. Unbounded 64-bit addresses invite accidental overflow and imply unsupported
scope. Fixing edge 32 now would pre-empt M5.2's comparison. Signed distance fields
would bias future meshers; material-only blocks cannot express partial occupied
volume. Full chemistry or a generic dimensional algebra is outside this increment.
## Benefits
Negative boundaries and exact round trips are testable independently of storage.
Extreme input is rejected before arithmetic. Logical occupancy does not select a
renderer or a planetary topology; sparse layouts can share the same fixtures.
## Costs
Explicit edge arguments and validation cost a few integer operations. Full signed
input types carry values outside the valid domain. The bounded domain, candidate
edges and 1m pitch are experiments and need version review before extension.
## Risks
Fill alone cannot reconstruct smooth geometry or conserve constituent mass. Material
keys without their future table cannot be interpreted. Domain size must not be
mistaken for supported memory or production scale. Raw logical structs are not a
wire format and may not be serialized by copying native bytes.
## Consequences
Expose a dependency-free evo::world target. Test independent negative-floor oracles,
axis independence, signed extrema, bounds, all local ordinal positions, metric
corners, invalid edges and cell consistency in Release and sanitizers. No new
third-party dependency or existing simulation golden changes. M5.2 selects actual
storage and chunk dimensions through measured alternatives.
+2
View File
@@ -41,3 +41,5 @@ benchmarked. Primary sources were reviewed during the initial September 2026
design. No unadopted candidate is a link dependency of the proof.
- [ADR-0041: Aggregate cost and fidelity budget](0041-aggregate-budget.md) - M4.6 measurement only.
- [ADR-0042: Local voxel contract](0042-local-voxel-contract.md) - accepted for M5.1; layout and planet mapping deferred.