NODEDC_MISSION_CORE/docs/audits/2026-09-21-map-reference-version-admission.md

Explicit map-reference version admission

Outcome and boundary

The reviewed smooth ring correction now has a separately sealed, content-addressed map bundle and an offline adapter to the existing planning-source interface. The whole corrected route was assembled by the unchanged build_reference_map consumer. This is data-path admission, not independent localization acceptance.

The adapter is deliberately not installed in the web composition. No source session, active reference, stored draft, live run, matcher policy or viewer was changed. The ordinary get(session_id) still returns the original source; a candidate requires its exact derivative generation. Nothing chooses “latest”.

The next integration must add an explicit version choice and matching corrected preview in the existing planner. Selecting a corrected trajectory while showing the raw session's overview would be a contract error. Live field instructions are deferred until that coherent selection/preview path is verified.

Implementation and provenance

• reconstruction/map_version.py owns missioncore.map-reference-version/v1, full artifact hashing, exclusive staging, idempotent publication and projections. It has no SciPy, device-plugin, session-store, viewer or hardware dependency.
• missions/versioned_sources.py composes the original provider with one explicitly pinned candidate. A source generation/digest mismatch or artifact corruption fails closed; it never falls back to different geometry under the same identity.
• experiments/package_recorded_map_version.py is the bounded K1 experiment adapter. It reads the canonical source API and checks native transport, receipt index, frozen capture clock and origin. It never imports or writes the web app.
• A reviewed evidence-seal SHA binds the original experiment code, correction, geometry and measured reports. Packaging adds its own producer/contract hashes and frame-reproduction receipt without rewriting those reports.

The bundle preserves full-resolution corrected XYZ, unchanged cached intensities, pose orientations, original frame offsets/counts/sequences and receipt chronology. Its manifest binds the original physical session, source generation and every source-artifact digest. Separate map frame identity prevents confusing corrected coordinates with the raw scanner frame.

The trajectory contract explicitly distinguishes source_distance_m (the smooth field's original traversal parameter) from recomputed corrected distance_m. Drafts and route tiling consume the latter. No first/last pose equality is added.

Multi-tile preparation uses one verified private bundle snapshot and checks the original and derivative again before the complete map may be returned. Failure, cancellation and exceptions clean only that temporary snapshot. Existing source evidence and earlier versions remain untouched.

Measured execution

On the existing ring, all 5,178 full-resolution cloud frames / 17,669,672 points were reproduced from the frozen correction field and compared bit-for-bit after float32 serialization. All 5,182 corrected positions and orientations were checked, as were source pose indices, distances and receipt times.

The canonical source generation remained unchanged. The original trajectory is 579.797271 m; the corrected trajectory is 579.982703 m. The existing reference-map builder assembled 15 route tiles and 694,420 voxel-retained registration points. The packaging plus full-route assembly check took 10.36 seconds on the local CPU. This is one measured execution, not a throughput benchmark or a scalability claim.

The source/model fidelity and held-out registration findings remain those in 2026-09-21-smooth-map-correction.md; packaging did not refit or remeasure them. The full candidate map includes all source frames. Its assembly therefore must not be reported as an additional held-out localization score.

Extraction has a declared, separate numerical profile (120 uniformly selected frames per interval, 0.25 m voxel, 20 m radius and relative height −3…6 m), matching the current recorded reference extraction settings. Presentation uses an 80 m radius and no vertical crop. These are derived preparation profiles, not raw capture limits, and the full stored bundle is not thinned. Convergence, loss/recovery, quality thresholds and acquisition remain unchanged.

Validation and limitations

Tests cover idempotency, separate source/version generations and draft geometry, corrected distance calculation, raw default selection, source/frame ownership, no second cloud transform, presentation/numerical separation, every artifact's hash, wrong parent, unsafe paths/symlinks, nonfinite data, bad frame indices, invalid quaternions, cancellation, exception cleanup and changes during assembly.

The focused suite passed 61 tests, including the existing source preparation, draft and registration regressions and the correction solver tests. Ruff and diff whitespace checks passed. Frontend code/build and web composition were not changed or restarted for this offline increment.

The packaging adapter initially rejected the real source because its provisional mapping swapped capture-clock and receipt-index artifact names. Inspection of the plugin's actual source contract corrected that mapping; a dedicated regression now checks the frozen capture clock separately from the mutable current timeline. No recorded bytes or source metadata were changed to make admission pass.

The original correction still has only one accepted closure and a smoothness prior. Same-source held-out tests do not establish independent positioning truth, and numerical GICP sensitivity remains an open issue. No new field acceptance, automatic arbitrary-loop discovery, online SLAM replacement or navigation/safety authority is claimed.

Ops and local runtime

Ops access instructions, granted projects and Mission Core project context respond. Card discovery did not recover: a full list and searches for planning and кольц each timed out after 60 seconds. The earlier совмещение search returned no rows. No issue was guessed, duplicated or overwritten, and no raw-API fallback was used. The structured engineering update remains pending card access.

Local memory was 39% free before the sequential checks; no Docker workload or parallel heavy validation ran. The canonical operator service on 8000 was retained. The package and detailed private receipt remain under ignored .runtime/analysis.

Subsequent view-only admission

The same reviewed candidate is now available for explicit Original/Corrected comparison in the existing session overview. See 2026-09-21-map-comparison-view.md for the separate paired-preview contract, source identity checks, UI placement and acceptance. This does not change the reference-promotion or independent-validation boundaries documented below.