4.4 KiB
M6.3 read-only environment views
ADR-0052 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.
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. A view alone never grants mutation authority; the owner checks the request, both endpoints and capacity.