# ADR 0032: Versioned Navigation Bake And Runtime Query

## Status

Accepted

## Context

Blacksite needs a production navigation workflow on Bevy 0.19. Current high-level Bevy navigation
plugins target older Bevy releases, while baking and pathfinding are difficult, established domains
that should not be reimplemented locally. The editor also cannot own the runtime query contract:
packaged games and headless validation must consume the same data and behavior.

## Decision

Use the engine-independent Rerecast crate for deterministic 3D walkable-surface generation and
Polyanya for any-angle path queries. Blacksite owns reflected authoring components and a versioned
generated artifact under `assets/navigation/generated/`. The artifact records the source scene,
source fingerprint, exact generator/toolchain ID, agent profile, baked mesh, links, bounds, polygon
count, authored validation samples, a self-verifying payload hash, and raw/effective
disconnected-island diagnostics. Bounds do not inject fallback geometry.
Each bounds actor owns one artifact path derived from its stable `ActorId` when created or
duplicated. Artifact paths remain inside `assets/navigation/generated/`; duplicate ownership is a
blocking authoring error rather than last-writer-wins bake behavior.

The scene crate owns fingerprinting, bake artifact IO, the engine-independent query runtime, and
validation. The game crate provides the Bevy `Vec3` adapter and renderer-free validation CLI.
Editor bake controls, overlays, path preview, headless baking, and project validation call the same
resolver/query contracts and keep all visual helpers transient. Relevant authored geometry changes
mark the artifact stale; V1 debounces a full deterministic rebuild and reports the affected region
until Rerecast provides production-ready tiled regeneration.

The authoritative resolver expands visible scene composition and recursively linked prefab sources
from the project root. Repeated contributors receive qualified source identities. Full-value
navigation-relevant prefab component overrides are applied deterministically. Property overrides
apply only while their serialized source base remains current; drifted property layers and
structural overrides are rejected with a rebase/apply/unpack repair action. Bounds inside prefabs
are rejected so one level-scene actor remains the unambiguous artifact owner.

## Consequences

- Navigation remains usable on Bevy 0.19 without forking an older Bevy integration crate.
- Rerecast and Polyanya versions become explicit serialized-artifact compatibility inputs; schema
  migration or rebaking is required when their representation changes.
- Runtime queries resolve vertically overlapping surfaces by endpoint height and may traverse an
  ordered graph of multiple explicit links; reported distance is measured along the 3D route.
- Enabled named path samples become deterministic release assertions evaluated by the same query
  core used by the editor and game.
- Static navigation and explicit links ship first. Runtime obstacle carving, crowd avoidance, and
  partial tile rebuilding remain future work.
- Primitive and additive-brush triangles are deterministic source geometry. Imported static meshes
  use authored navigation obstacles until their normalized artifacts expose collision triangles.
- Runtime code never depends on editor UI state, and authored scenes never contain bake visualizers.