Files
aevolution/docs/adr/0052-read-only-environment-views.md
T
2026-10-08 12:08:53 -04:00

3.5 KiB

[Reviewed]

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.