Files
aevolution/docs/world/LOCAL_VOXEL_CONTRACT.md
T

88 lines
4.2 KiB
Markdown

# 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.