64 lines
3.5 KiB
Markdown
64 lines
3.5 KiB
Markdown
[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.
|