Files
aevolution/docs/world/LOCAL_VOXEL_CONTRACT.md
T

4.2 KiB

Local voxel contract v1 (M5.1)

This is the scoped experiment in ADR-0042. Public API: include/evo/world/coordinates.hpp. It implements pure address mapping and logical cell validation, not a world container or a persistent file format.

Frames and units

Right-handed Cartesian frame, +Z up, X cross Y = Z. VoxelAddress contains signed cell indices, not metres. ChunkAddress contains signed chunk indices. LocalCell contains unsigned cell offsets within a chunk. MetricCorner contains named signed millimetres. No implicit conversion to the old periodic 2D particle coordinates exists. The 2D habitat/effective-depth mapping waits for M6.1.

Per-axis voxel range is [-1,048,576, 1,048,576). Cell v owns the metric interval [v*1000, (v+1)*1000) mm. The positive outer face exists geometrically but is not another addressable cell. There is no wraparound or clamping. Negative Z is ordinary volume, so the contract is not a surface heightfield. No origin shift is implicit.

Mapping and failure contract

Callers explicitly pass edge N in {8,16,32,64}. M5.2 will compare those candidates; there is no default chunk size. Valid chunk axes are [-1,048,576/N, 1,048,576/N). Offsets satisfy 0 <= local < N. Each chunk covers exactly N cubed disjoint cells.

voxel --split(edge)--> {chunk, local} --join(edge)--> same voxel
local --ordinal(edge)--> x + N*(y + N*z) --local_from_ordinal(edge)--> same local
voxel --lower_corner_mm()--> signed metric corner

For edge 16, on any axis:

Voxel Chunk Local
-17 -2 15
-16 -1 0
-1 -1 15
0 0 0
15 0 15
16 1 0

All functions return std::expected and leave arguments unchanged. Invalid edge is reported before address validation; join checks chunk before local coordinates. Metric conversion validates voxel bounds before multiplying. Accepted ordinal range is [0,N cubed). Max N cubed is 262,144; all intermediate arithmetic is bounded. Inputs at INT64_MIN/MAX and UINT32_MAX must fail safely, not overflow.

Error Meaning
invalid_edge Candidate edge not supported
voxel_out_of_range Any signed voxel axis outside the local envelope
chunk_out_of_range Any signed chunk axis outside the edge-specific envelope
local_out_of_range Any local offset >= edge
ordinal_out_of_range Ordinal >= edge cubed
invalid_cell Fill >65,535 or void/material-fill mismatch

Logical cell and identity boundaries

CellSample::create(MaterialId, fill) produces a validated value. Material zero and fill zero denote void. Nonzero material requires positive fill. Fill/65,535 is an exact rational fraction of the 1m-cubed cell; integer volume/mass conversion must carry remainders under a later accounting contract. No geometry shape, material density, light, moisture, nutrients or energy are inferred from this value.

An unknown nonzero material key is structurally valid here; M5.3's versioned table must resolve it or reject it. Native sizeof/alignment is not an encoded layout. Palette compression, uniform storage and varying pages belong to M5.2. Smooth meshing needs additional geometry information and a separate comparison/ADR.

A chunk is storage addressing, a region is simulation authority, and an ecological cell is a resource/model domain. They are not interchangeable IDs. M5.1 functions operate in one caller-selected frame; no function compares coordinates from different worlds or frames. Persisting/exchanging keys requires those identities and versions in the enclosing schema. No coordinate or material key allocates resident data.

Acceptance and next step

Tests must prove floor mapping against an independently constructed interval oracle, not merely split(join(x)); exhaust every ordinal for every candidate edge; test all axes, seams, envelope corners and invalid extremes. M5.1 is complete when those contracts build and pass. M5.2 next compares compact chunk layouts and sizes; it must not infer a preferred storage representation from these C++ value types.

M5.2 follow-up: ADR-0043 now selects edge 16 and uniform/palette/dense geometry for the bounded M5 world. This does not remove the explicit candidate edges from the coordinate API or define a wire format.