74 lines
4.4 KiB
Markdown
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.
|