Add exact periodic neighborhood queries and measured scan baseline

This commit is contained in:
dingo
2026-09-19 19:21:45 -04:00
parent be4382472c
commit 9b19509673
15 changed files with 442 additions and 7 deletions
@@ -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.
+1
View File
@@ -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