Complete M6.3 read-only environment views
This commit is contained in:
@@ -46,7 +46,9 @@ Restore additionally uses at most 327680 bytes of dense field staging, a second
|
||||
outside the resident budget. All counts are bounded before those allocations.
|
||||
|
||||
`read(site, channel)` returns the owned scalar in that channel's units; it grants
|
||||
no consumption permission. M6.3 will add derived footprint/tick/revision views.
|
||||
no consumption permission. M6.3 adds [derived footprint/tick/revision views](ENVIRONMENT_VIEWS.md).
|
||||
Read-only `identity()` and checked `water_capacity(site)` accessors support those
|
||||
queries without exposing writable metadata or changing field snapshot v1.
|
||||
`transfer(action, channel, from, to, amount)` moves a positive quantity between
|
||||
distinct sites within one present field. It checks source, overflow, water capacity,
|
||||
fresh nonzero command and replacement budget before publishing. Rejection preserves
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user