Add exact periodic neighborhood queries and measured scan baseline
This commit is contained in:
@@ -0,0 +1,58 @@
|
||||
# ADR-0023: Local periodic neighborhood queries
|
||||
|
||||
## Status
|
||||
|
||||
Adopted for the bounded M1.7 proof; production spatial indexing deferred.
|
||||
|
||||
## Context
|
||||
|
||||
Interactions need a tested definition of proximity before an acceleration
|
||||
structure. The current synthetic domain is a 1,024 mm square torus, not a planet
|
||||
projection or organism scale. The existing world bounds entity count at 100,000.
|
||||
|
||||
## Decision
|
||||
|
||||
Expose a read-only `query_neighbors(world, center, radius)` function. Positions
|
||||
must be inside the domain. Radius uses the existing unsigned millimetre wrapper;
|
||||
all its values are valid. Use shortest periodic displacement independently per
|
||||
axis and an inclusive Euclidean circle. Return unique entity IDs in ascending
|
||||
order, including entities exactly at the center. No implicit self exclusion.
|
||||
|
||||
Start with a linear scan of current component rows, no cached index or copied
|
||||
world. Compute squared distance and radius in unsigned 64-bit arithmetic; even
|
||||
the maximum u32 radius squared fits. No square roots or floating point are used.
|
||||
The caller owns simulation access and must not mutate concurrently. Results own
|
||||
their IDs and represent only the state at the call; they are not live handles.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
Uniform grids are plausible for local uniform density but add rebuild/update
|
||||
cost and periodic-cell deduplication. Trees may suit nonuniform density but add
|
||||
maintenance and traversal complexity. A persistent index would need an explicit
|
||||
invalidation contract for direct lifecycle operations, ticks and restore.
|
||||
|
||||
## Benefits
|
||||
|
||||
Small exact baseline, stable order, no stale cache, no changes to authoritative
|
||||
state or snapshots. An independent nine-image oracle validates periodic geometry.
|
||||
|
||||
## Costs
|
||||
|
||||
O(N) distance checks per query, O(K) result space for K matches. All-entity queries
|
||||
per tick remain O(N squared). The result vector allocates; this is not a realtime
|
||||
performance promise. Benchmark sparse, clustered, narrow and world-wide queries.
|
||||
|
||||
## Risks
|
||||
|
||||
Accidentally treating returned IDs as guaranteed still alive, confusing this
|
||||
synthetic torus with future region boundaries, or shipping quadratic interaction
|
||||
loops without measurement. Allocation failures propagate at the host boundary.
|
||||
|
||||
## Consequences
|
||||
|
||||
Keep index details out of the API. Compare total index maintenance plus query
|
||||
cost when interaction workloads exist. Neither sensory perception, network
|
||||
interest management, collision geometry nor spherical coordinates are selected.
|
||||
No rules/snapshot version bump: queries cannot affect state or PRNG streams.
|
||||
Tests cover seams, corners, inclusive edges, antipodes, zero/maximum radii,
|
||||
invalid centers, lifecycle and restore, with an independent periodic-image oracle.
|
||||
@@ -15,6 +15,7 @@ infrastructure and voxels. 0020 scopes Gitea delivery and the stateless dev Job.
|
||||
Each record has the eight required sections.
|
||||
0021 authorizes the opt-in ECS comparison only, not a production dependency.
|
||||
0022 adopts the bounded sequential lifecycle-command scheduler for the proof.
|
||||
0023 defines local periodic neighborhood queries and a measured linear baseline.
|
||||
|
||||
Every dependency adoption records exact version/commit and integrity hash,
|
||||
transitive license obligations, maintenance/security review, owner and removal
|
||||
|
||||
Reference in New Issue
Block a user