Files
aevolution/docs/adr/0042-local-voxel-contract.md
2026-10-08 12:08:53 -04:00

4.1 KiB

[Reviewed]

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.