# 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, agent profile, baked mesh, links, bounds, and diagnostics.

The scene crate owns fingerprinting, bake artifact IO, and validation. The game crate owns artifact
loading and path queries. Editor bake controls, overlays, and path preview call those shared/game
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.

## 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.
- 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.