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