Complete M6.3 read-only environment views
This commit is contained in:
@@ -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
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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