Define M5.1 local voxel contract and expand M5-M9 gates
This commit is contained in:
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user