Files
aevolution/docs/world/ENVIRONMENT_VIEWS.md
T

74 lines
4.4 KiB
Markdown

# M6.3 read-only environment views
[ADR-0052](../adr/0052-read-only-environment-views.md) defines the implemented local
query in `include/evo/world/environment.hpp`. FieldStore gains read-only identity
and per-site capacity accessors; neither changes field snapshot v1.
```cpp
auto view = query_environment(fields, terrain, tick, voxel_footprint, requested_mask);
// Plan from view->samples(), then under the same single-owner phase:
auto current = validate_environment(*view, fields, terrain, tick);
// A successful check is NOT an inventory reservation or transfer.
```
## Selection and response
The footprint is 1..256 unique voxel addresses in the existing local coordinate
contract. Input permutations produce the same sorted samples. Invalid/duplicate
addresses, empty/oversized footprints and zero/unknown mask bits reject. Every voxel
must have a FieldSite and an already loaded terrain chunk; otherwise the complete
query fails with `missing_site` or `missing_chunk`. Reads never regenerate or load.
The selected region is the site's full HabitatBox. There is no partial-box sampling,
weighted overlap, smoothing or summing concentrations across different volumes.
Requested fields are bits 0..9 in Field enum order. Each sample has ten optional
slots: unrequested slots are empty, requested missing slots are empty, present zero
slots hold a typed zero. The view's mask distinguishes unrequested from missing.
Mass channels return Femtograms and reduced fg/um^3 bulk concentration; energy
channels return Picojoules. Ratios refer to the habitat's effective volume, not
solvent volume. Moisture status is explicitly not_requested, missing_water,
zero_capacity or available; only available carries WaterSaturation. No values are
inferred from material IDs.
Each sample records voxel, chunk address/revision, FieldSite (including substrate),
copied terrain CellSample, effective area/volume and water capacity. The view records
world/frame from fields, logical tick, field watermark and request mask. Resolution
is explicit: terrain pitch 1000mm, habitat coordinates/extents in um. Rational
derivations have zero rounding error relative to stored integer inventories; physical
resolution and unmodeled sub-habitat variation remain limitations, not zero error.
Field substrate and terrain material can differ: both are reported without converting
inventory or changing capacities. M6.4 must decide valid binding before consuming.
## Freshness, ownership and failure
Samples are privately owned and exposed as const spans. Copies are informational.
Validation requires original stores alive at their original addresses, equal caller
tick, the same field watermark and current tokens for every sampled terrain chunk.
Any successful field transfer invalidates every prior view, even an unrelated one.
Edits or first dirty marking in a sampled chunk invalidate; so does clean eviction
and reload. Unrelated terrain activity does not invalidate the sampled chunks.
Rejected commands leave views current. A restored identical store is a different
owner; obtain a fresh view. Do not use a moved-from view except for reassignment
or destruction; validators reject empty moved-from results defensively.
No library clock advances here. The host passes the committed logical tick and
guarantees single-owner access with no mutation during query or between final
validation and future commit. Views must not outlive either store when validated.
The terrain API currently has no bound world/frame identity; pairing it correctly
with fields is a trusted host responsibility, not something this query verifies.
No pointer/token is persisted or sent as a client authority token.
Query failures return typed errors and publish no partial view. Allocation exceptions
propagate to the host. A query owns at most 256 samples, tokens and sorted addresses;
those buffers and allocator metadata are outside store resident budgets. Work is
bounded by footprint size, field count and ChunkStore's bounded lookup. No new spatial
index or concurrency is justified at this gate.
Existing geometry/field formats, versions and goldens are unchanged. Later combined
snapshots must restore the stores first and reacquire views. Next: M6.4 coordinated
environmental transfers, including inventory ownership and retry semantics.
M6.4 implements the validation-and-publication ownership phase in
[EnvironmentalTransfers](ENVIRONMENTAL_TRANSFERS.md). A view alone never grants
mutation authority; the owner checks the request, both endpoints and capacity.