# Navigation Authoring Evaluation

> **Evidence record — not current product guidance.** Use the [documentation index](../../../README.md) for current behavior and architecture.

Date: 2026-07-12
Branch: `codex/renderer-material-component-foundation`

This record captures implementation evidence for deterministic navigation authoring, composed
source resolution, persisted path samples, bake diagnostics, and shared editor/game/headless path
queries. The permanent contract lives in [ADR 0032](../../../adr/0032-versioned-navigation-bake-and-runtime-query.md),
and the user workflow lives in the [navigation authoring guide](../../navigation-authoring.md).

## Live editor evidence

The images below are native Wayland captures from the debug editor running the isolated
`Blacksite Navigation QA` project. The QA project is temporary; no acceptance interaction changes
the repository scene.

### Bounds, sources, diagnostics, and validation samples

![Selected Navigation Bounds with the truthful world-space overlay and complete authoring controls](navigation-authoring-overview.png)

The selected bounds owns its generated artifact, exposes the complete agent profile, reports
current/stale state, and shows its persisted validation sample. Bounds, obstacle, area, and link
visualizers match the world-axis-aligned volumes and endpoints consumed by the bake.

### Shared runtime path preview

![Polyanya path preview crossing the authored off-mesh link](navigation-path-preview.png)

**Test Path** uses the same height-aware, multi-link query core as project validation and the game
adapter. The live query returned an 8.20 m, six-waypoint route through
`navigation-link-center`; a subsequent editor bake regenerated 26 polygons and the same query
remained valid. Pinning a second sample immediately marked the artifact stale and disabled path
testing; undo restored the current one-sample state. The transient route, endpoints, baked mesh,
and visualizers do not enter scene serialization.

## Acceptance results

| Area | Result | Evidence |
|------|--------|----------|
| Designer workflow | Pass | Typed bounds/obstacle/area/link actors, Bake, overlay, Test Path, and persisted sample controls |
| Source fidelity | Pass | Active unsaved snapshot plus visible subscene and recursive prefab resolution; exact affine transforms; no synthetic floor |
| Stale-state scope | Pass | Each bounds fingerprint includes only overlapping geometry/volumes and relevant links/samples; external artifact replacement is polled |
| Diagnostics | Pass | Invalid agents, grid budgets, links, duplicate artifact owners, prefab drift/structure, empty bakes, and unreachable named samples identify owners and repairs |
| Runtime parity | Pass | One scene-owned Polyanya query core drives editor preview, game `Vec3` adapter, link/sample validation, and the renderer-free validation CLI |
| Artifact integrity | Pass | Schema 2, exact generator identity, deterministic fresh-bake comparison, self-verifying payload hash, and atomic replacement |
| Serialization boundary | Pass | Viewport meshes, lines, markers, routes, and cache state remain transient |
| Packaged/release acceptance | Deferred | Explicitly deferred by project-owner direction; no packaged test is claimed in this record |

## Automated verification

| Command/suite | Result |
|---------------|--------|
| Affected source test matrix (`shared`, `scene`, `game`, `editor`, `blacksite_surface`, `xtask`) | 390 passed; 1 intentional manual migration test ignored |
| `cargo clippy -p shared -p scene -p game -p editor -p xtask --all-targets -- -D warnings` | Pass |
| `cargo bake-navigation --project . --check` | 1 deterministic artifact current |
| `cargo validate-levels` | 59 dependencies, 5 non-blocking findings, 0 blocking errors |
| `cargo fmt --all` / `git diff --check` | Pass |

## Deliberate boundaries

V1 applies blocked areas and retains walkable cost metadata until Polyanya exposes a suitable
per-polygon cost callback. Imported static-mesh manifests do not yet contain normalized navigation
triangles. Runtime obstacle carving, crowd avoidance, and partial tile rebuilds remain future work;
V1 uses a debounced deterministic rebuild scoped by each bounds fingerprint.