Complete M6.3 read-only environment views

This commit is contained in:
dingo
2026-09-27 07:50:21 -04:00
parent 52af3bd0b4
commit 965a33ca48
14 changed files with 657 additions and 4 deletions
+5
View File
@@ -315,6 +315,11 @@ material capacity defaults, bounded sparse pages, same-field local relocation an
canonical field snapshot v1 under ADR-0051. Rate-driven sources and combined
terrain/biology persistence are not provided by this independent codec. Next: M6.3.
M6.3 implements [read-only environment views](world/ENVIRONMENT_VIEWS.md) under
ADR-0052: bounded canonical voxel footprints, exact typed derived values, explicit
absence and tick/field/chunk freshness checks. No implicit terrain load or inventory
authorization occurs. Next: M6.4 atomic coordinated transfers.
## M7 - Persistent region server
**Goal:** a disposable authoritative headless process can recover a bounded region
+13 -2
View File
@@ -7,7 +7,7 @@ persistent simulation server. The founding vision remains unchanged.
## Completed implementation
- Vision, architectural pillars, risks, open-question register, architecture
diagrams, biological contracts, engineering constitution and 51 ADRs.
diagrams, biological contracts, engineering constitution and 52 ADRs.
Proposed/deferred choices remain distinct from accepted proof decisions.
- M0–M4 task breakdowns with dependencies, acceptance evidence and risks,
plus M5–M14 gates in [ROADMAP.md](ROADMAP.md).
@@ -61,7 +61,7 @@ for the bounded proof; the general production ECS remains a later measured choic
| Priority | Work | Completion evidence |
|---|---|---|
| 1 | M6.3 read-only environment views | Footprint queries with explicit units, availability, tick and revision validity |
| 1 | M6.4 coordinated environmental transfers | Atomic organism/environment debits and credits, fresh-view checks and retry identity |
| Research | Improve aggregate fidelity and measure Linux/target-host costs | M4.6 found no qualifying width; see the aggregate budget report |
| 2 | Revisit the ADR-0031/0032 reproduction cost model | Reproduction is affordable only at the genome schema's floor; decide whether that is intended before M4 builds cohorts on it |
| Delivery gate | Add/update the dev workload when a deployable increment needs it; Argo is ready | Observe Job/pod completion separately from image publication; no World0 changes |
@@ -630,3 +630,14 @@ restore does not regenerate supplies. [Contract and memory evidence](world/ENVIR
and the byte schema document trust, budget and compatibility limits. M5 terrain
formats remain unchanged; combined terrain/biology durability and rate sources are
not implemented. Next: M6.3 read-only derived environment views.
## M6.3 read-only environment views (2026-09-27)
Added [bounded footprint queries](world/ENVIRONMENT_VIEWS.md) under ADR-0052.
Views copy typed quantities, exact concentration/moisture and terrain samples with
habitat resolution, logical tick, field watermark and sampled chunk revisions.
Missing fields are distinct from zero; absent habitats/chunks fail without loading.
Freshness validation rejects wrong stores, changed tick/field state and stale chunk
tokens, including eviction/reload. No persistent format or simulation rule changed.
Views grant no inventory reservation; coherent tick/store pairing remains a host
responsibility. Next: M6.4 coordinated environmental transfers.
@@ -0,0 +1,62 @@
# ADR-0052: Read-only environment footprint views
## Status
Accepted for M6.3 single-owner local queries. No transfer authorization or new format.
## Context
Scalar field reads do not identify habitat volume, missing data, sampling tick or
terrain freshness. M6.4 needs a bounded, immutable planning input without implicit
loading or supply creation. Field and terrain stores are not yet a durable bundle.
## Decision
Add `query_environment(fields, terrain, tick, footprint, mask)` in evo::world.
The footprint contains 1..256 unique voxel addresses; order is canonicalized before
querying. Each address selects its complete mapped habitat, not a geometric overlap
integral. Unknown sites/chunks fail the entire query. Requested absent fields stay
explicitly absent, distinct from present zero. No mutation or loading occurs.
Return an owned read-only EnvironmentView with world/frame from FieldStore, caller
tick, requested mask, field command watermark, and samples ordered by voxel. Each
sample contains mapping/volume, field substrate, copied terrain cell and its chunk
revision, typed mass/energy values, exact bulk mass concentration and water saturation
with explicit undefined/missing status. Resolution is the 1m terrain pitch plus the
actual micrometre habitat box; no physical accuracy claim follows from exact ratios.
Views retain non-owning store identities and private ChunkView tokens. Both stores
must outlive validation. `validate_environment` checks the same objects, same tick,
unchanged global field watermark and all sampled chunk tokens. Unrelated field
transfers conservatively invalidate the view; unrelated terrain chunks do not.
Eviction/reload and restored clones cannot revive old views. Failed commands do not
invalidate them. There is no serializable capability, network trust or permission
to consume from a copied result. Validation and commit must eventually share the
single-owner phase; a check followed by concurrent writes is invalid usage.
The host supplies a coherent tick/store pairing. ChunkStore has no bound WorldIdentity,
so this gate cannot authenticate that terrain and fields belong to the same world.
Substrate and terrain material are reported separately, never silently reconciled.
M6.4/6.8 must define coupled ownership and persistence before biological commits.
## Alternatives Considered
Returning zero for missing data manufactures environmental knowledge. Partial-volume
interpolation needs explicit density/overlap rules and can imply false precision.
Per-site field revisions reduce invalidation but require persisted state changes;
the existing nonwrapping watermark safely supplies a conservative version now.
Implicit chunk loads would turn reads into state/resource changes.
## Benefits
Deterministic bounded queries, dimensional results and testable stale-data rejection.
Existing field and terrain snapshots/goldens remain unchanged.
## Costs
Each response copies up to 256 samples and tokens; buffers are outside store budgets.
Global field invalidation may cause extra replanning. No concurrent readers/writers.
## Risks
A dishonest host tick or mismatched stores cannot be detected fully here. A current
view is not a reservation. Restored stores must reacquire views. Fine-grained geometry,
cross-region queries and aggregation need later contracts.
## Consequences
Test signed chunk seams, canonical order, absence versus zero, zero water capacity,
invalid footprints, stale field/chunk/tick/owner, eviction/reload and unchanged
snapshot bytes after reads. No deployment, scheduler or biological action added.
+1
View File
@@ -58,3 +58,4 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0049: Bounded world proof](0049-bounded-world-proof.md) - accepted for M5.8 restart regression and cost evidence.
- [ADR-0050: Environmental units and coupling](0050-environmental-units-and-coupling.md) - accepted for M6's bounded habitat/accounting contract; no field storage or terrain conversion yet.
- [ADR-0051: Optional environmental fields](0051-optional-environmental-fields.md) - accepted for M6.2 finite sparse pages, local transfers and field snapshot v1.
- [ADR-0052: Environment views](0052-read-only-environment-views.md) - accepted for M6.3 bounded read-only footprint queries and freshness validation.
+10
View File
@@ -173,3 +173,13 @@ sparse scalar pages. Its versioned codec retains all field state and local trans
watermark, without relying on procedural resource regeneration. M5 LocalWorldFiles
still publishes only terrain state: integrated terrain/fields/biology recovery must
use a later version bundle. No cross-store biological transfer is authorized here.
## M6.3 environment reads
[ADR-0052](../adr/0052-read-only-environment-views.md) adds
[environment views](../world/ENVIRONMENT_VIEWS.md) across a bounded voxel footprint.
Samples carry exact typed field quantities, habitat volume, terrain chunk revision
and an explicit host tick. Queries never load chunks or mutate inventories. A
separate validator rejects stale ticks, field watermarks, foreign store instances
and stale sampled chunk tokens. Coherent store pairing and single-owner scheduling
remain host obligations; M6.4 must validate and commit in one ownership phase.
+34
View File
@@ -1738,3 +1738,37 @@ or new sanitizer claims. Local Docker CLI exists, but docker version could not c
because the dockerDesktopLinuxEngine named pipe is absent. Consequently the corrected
Linux TSan container invocation requires confirmation in Gitea CI; it was not run
locally. No application deployment or World0 changes.
## M6.3 read-only environment views - 2026-09-27
Added ADR-0052 and a bounded canonical footprint query with typed mass/energy,
exact concentration/moisture, habitat resolution, explicit caller tick, field
watermark and sampled chunk revisions. FieldStore gained read-only identity and
capacity accessors. Views own copied samples and retain private non-owning store/
chunk tokens for freshness checks. Existing formats, versions and goldens are unchanged.
Executed on Windows x64 / MSVC 19.44:
- `tools/windows-check.ps1 -Preset release -Action check`: 51/51 passed on final code.
- `tools/windows-check.ps1 -Preset analysis -Action check`: clang-tidy 19 and
51/51 passed. Removed an ineffective move of a trivially copyable sample after
the initial analysis diagnostic.
- `tools/windows-check.ps1 -Preset asan -Action check`: 51/51 passed on final code.
- `tools/windows-check.ps1 -Preset release -Action format`: passed.
- `git diff --check`: passed.
Tests cover negative/positive chunk seams, input permutation, missing site/chunk,
absent versus zero/unrequested fields, all moisture statuses, invalid masks and
footprints, exact quantities/ratios, maximum 256-site footprint with all ten fields,
and unchanged terrain/field snapshots after queries. Freshness checks cover changed
tick, restored foreign stores, successful versus rejected field transfers, global
field invalidation, unrelated terrain activity, sampled dirty marking, excavation
and eviction/reload. The query never loads missing chunks or authorizes consumption.
Linux/UBSan/TSan and cluster execution were not run locally; existing CI includes
the new CTest without additional scratch mounts (this test writes no files).
Host tick/store pairing and single-owner execution are explicit preconditions.
ChunkStore does not yet bind a world identity, so coherent field/terrain pairing
cannot be independently authenticated by this view. Combined ownership, reservation,
atomic inventory transfer and retry outcomes remain M6.4. No deployment or World0
operation occurred.
+3 -1
View File
@@ -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
+69
View File
@@ -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.