118 lines
6.8 KiB
Markdown
118 lines
6.8 KiB
Markdown
# 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.
|