# Local voxel contract v1 (M5.1) This is the scoped experiment in [ADR-0042](../adr/0042-local-voxel-contract.md). 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](../adr/0043-chunk-layout.md) 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.