Skip to content

lidarslam_ros2 v0.9 roadmap — product foundation

Status: direction approved 2026-07-27; Phase 0 and Phase 1 complete; Phase 2 in progress (installed CLI, clean-prefix validation, versioned Humble/Jazzy GHCR release images with attestations, and source-prefix v0.6.0 upgrade/fresh-install parity landed; ROS buildfarm flagship packaging and package-manager upgrades remain open); Phase 3 in progress (SIGINT/SIGTERM process-group cleanup, recoverable terminal evidence, and the pinned nightly MID-360 real-data E2E gate landed; deterministic storage refusal and disk-exhaustion failure injection, fixed-duration soak profiles, and periodic in-iteration storage telemetry and auditable machine/input/software provenance plus a bounded per-iteration timeout landed; named-hardware one-hour and eight-hour executions passed; bounded PointCloud2/Imu header timestamp-order preflight landed; the bounded-filesystem workflow and evidence contract are implemented and its exact-revision local execution and first public post-integration artifact passed); Phase 4 intake tooling landed (structured independent-user issue form, schema-validated evidence ledger, duplicate-evidence rejection, and a strict three-user readiness command), but accepted external validation remains 0/3). This roadmap turns the existing benchmark-heavy map-authoring stack into a product-level OSS project. It does not replace the evidence-driven capability roadmaps; it defines the stable product surface they must integrate with.

The machine-readable cross-phase status is the v1.0 readiness audit. Run python3 scripts/check_v1_readiness.py --require-complete for the final fail-closed gate; the tracked snapshot is currently NOT_READY with 8/10 gates complete.

0. Product decision

The product is an offline rosbag2-to-map authoring workflow, not a general collection of SLAM experiments:

A third party can start from the public documentation, run one official command, obtain a verified Autoware-compatible point-cloud map bundle, and diagnose a failure without reading the implementation.

The authoritative scope and compatibility promises are in docs/product-contract.md.

Research tracks remain valuable, but they are not allowed to expand the beginner surface, silently change defaults, or block product hardening.

1. Measurable v1.0 readiness targets

Dimension Readiness gate
First success A clean-machine user can complete the Docker demo from README alone; a source user can build and start the fixed quickstart from Getting Started
Official surface No more than three beginner-facing entrypoints; every other path is labelled advanced, benchmark or research
Diagnosability Unsupported input, missing topics, missing calibration prerequisites and invalid output return an actionable error or diagnosis artifact
Reproducibility Fixed demo inputs and parameters are pinned; offline determinism and map verification gates remain green
Distribution Versioned GHCR image and source install work on supported platforms; the rosdistro/RKO-LIO packaging decision is resolved and documented
Reliability Corrupt bag, missing TF, time disorder, output collision, disk pressure and interrupted-run behaviors have automated coverage
Compatibility Product flags, output schema and deprecation policy are documented and tested
OSS operations Security, support, conduct, governance, citation, issue templates and release ownership are public
External adoption At least three independent users complete first-map validation from public docs, with findings recorded before v1.0

Targets are evidence requirements, not marketing estimates. A readiness item is incomplete until the command, artifact or external report proving it is available.

2. Phase 0 — Product Foundation

Deliverables:

  • publish the product contract and explicit non-goals;
  • identify exactly three official entrypoints;
  • add security, support, conduct, governance and citation policies;
  • add structured bug, feature and sensor-support issue forms;
  • reconcile README, docs navigation, release links and VERSION;
  • encode the above as documentation regression tests.

Gate:

  • mkdocs build --strict succeeds;
  • documentation and metadata tests succeed;
  • all policy links resolve locally;
  • historical release pages remain available but are not described as current;
  • no runtime algorithm or default changes in this phase.

3. Phase 1 — Golden-path UX

Build one stable command surface over the existing runners:

./scripts/lidarslam doctor <bag>
./scripts/lidarslam run <bag> --profile <profile>
./scripts/lidarslam inspect <output>

The implementation may initially be a Python console package delegating to the proven scripts. The public contract is the command behavior, exit codes and artifacts—not the internal wrapper language.

The Phase 1 repo-local spelling remains supported. Phase 2 installs the same contract as lidarslam-map and ros2 run lidarslam lidarslam-cli, while preserving the historical ros2 run lidarslam lidarslam C++ node.

Deliverables:

  • versioned preflight/diagnosis JSON schemas;
  • deterministic execution plan with explicit selected profile and parameters;
  • run_manifest.json containing input identity, Git/package versions, commands, timing, completion state and output checksums;
  • atomic output creation, collision protection and resumable stages;
  • actionable error taxonomy and stable non-zero exit codes;
  • user-facing success summary with map, diagnosis and viewer paths.

Gate:

  • unit tests cover planning, schema, errors and resume state;
  • the machine-readable CLI option inventory matches every flag exposed by command help;
  • fixed demo and own-bag dry-run exercise the same product core;
  • clean Docker and source-workspace usability trials are recorded.

The maintainer-operated Docker first-map trial found and closed the nested-bag discovery blocker and unified the default container command with the versioned product CLI. It does not count toward the three independent-user reports required in Phase 4.

The CLI v1 installed-prefix validation also passed for non-symlinked Humble and Jazzy package installs. It covers the option contract, optional viewer command, compatibility aliases, and Bash completion; full matrix CI remains authoritative for repository-wide builds.

4. Phase 2 — Distribution and compatibility

Deliverables:

  • resolve the flagship packaging mismatch: either release the maintained rko_lio fork for Humble/Jazzy or make the binary product path and product claim explicitly use a frontend available from the same distribution;
  • converge the required NDT APIs upstream and consume the collision-free canonical ndt_omp package before releasing dependent packages;
  • publish versioned GHCR tags in addition to moving convenience tags;
  • generate an SBOM and provenance for release images and bundles;
  • document amd64 as a tested target and assign an explicit support tier to arm64/Jetson;
  • test install/upgrade paths, not only source builds.
  • embed deterministic source revision metadata in installed source and container products, and reject mismatches in official image smoke tests.

Gate:

  • one documented install command reaches the same golden-path behavior on each supported ROS distribution;
  • package contents include every runtime resource and exclude research media or generated artifacts not needed at runtime;
  • installation evidence is attached to the release candidate.

Source-prefix upgrade status (2026-07-28): v0.6.0 to clean candidate debbf78beda219c61b06a66d082d568eb979c246 passed on Humble and Jazzy. Upgraded and fresh prefixes each contained the same 104 package-owned files with zero stale, missing or normalized-text mismatches; all 11 behavioral and compatibility checks passed. Debian package-manager upgrade evidence remains open until buildfarm packages exist.

Fresh-terminal source-install activation now has a local dual-distro all-source follow-up. The absolute installed launcher activates only its matching aggregate workspace setup for child processes, and the clean-prefix checker removes all inherited ROS/Python/library path variables before its real-bag diagnosis. Network-disabled Humble and Jazzy executions each built the exact six maintained packages from a read-only candidate mount, retained the six-package install index, selected the maintained RKO-LIO profile, reached the calibration-review dry-run without a remembered source step, and passed the complete installed contract. Build-time and runtime Python cache leakage was also removed; each prefix stayed at zero cache artifacts across final validation. A cold-machine dependency bootstrap, public comparable onboarding row, and normal package-manager installation remain open gates. See the all-source evidence.

The clean-machine source-row observer now has a separate no-write public preflight. It requires the exact six-package inventory, explicit package selection, repository-only dependency helper, tests-disabled build, canonical Getting Started route, and matching VERSION from one immutable GitHub commit. The quickstart repeats the inventory check with colcon list before rosdep or build, and a mismatch survives the private-log boundary as a stable bounded finding. The public base 3f4dd70c...c41eba8 correctly reports NOT_READY because it predates scripts/source_quickstart.sh; no private source is used as a fallback. See the public preflight evidence.

Dependency status (rechecked 2026-08-12): official PRBonn RKO-LIO 0.3.2-1 passed the pinned golden-path E2E on Humble and Jazzy and is now declared as rko_lio >= 0.3.2; Humble main now carries 0.3.2 while Jazzy main still carries 0.2.0, so normal Jazzy apt resolution waits for the sync. ndt_omp_ros2 remains absent from rosdistro. Its 0.1.0 tag, installed-consumer tests, and Bloom-generated Humble/Jazzy Debian gates exist at 8b77fa5, but a human review exposed co-installation collisions with Humble's existing ndt_omp. The parent repository now detects that unanswered review and both exact PR heads have one failed stale-base rosdep check, so the parent now reports BLOCKED while preserving both review actions. An upstream API patch based on exact commit 5495fd9, parent PCL-pointer modernization, and a complete five-file canonical transition for both direct consumers now pass network-isolated Humble and Jazzy builds. A fail-closed contract also checks every consumer reference, patch hash, exact upstream base, focused API test, exact candidate commit/parent/subject/diff, current fork and branch state, semantic duplicate PRs, and external authority boundary. Its live 30/30 READY_FOR_DRAFT_PR result remains read-only. Remaining work is approval and upstream review of that patch (or a fully isolated replacement if declined), a current-base green rosdistro registration, the Jazzy RKO-LIO main sync, and only then the package-manager E2E. The schema-backed package-manager workflow is also implemented for exact Humble/Jazzy clean installs, main-to-testing upgrades, stale-path detection, installed CLI contracts, and the pinned real-map E2E. It remains evidence-open: run it only after lidarslam packages exist in testing, capture the upgrade before the two-version apt window closes, and repeat clean installation after the target syncs to main. The live v1 audit now recognizes completion only from an exact v<version>/main/clean-install workflow identity whose Humble and Jazzy jobs both succeeded; the workflow definition or a manually changed gate state is not accepted as execution evidence.

5. Phase 3 — Operational reliability

Deliverables:

  • failure-injection fixtures for corrupt metadata, missing TF, timestamp reversal, disk exhaustion, termination and partial output;
  • one-hour and eight-hour soak profiles with peak RSS, wall time, output size and dropped-input counters;
  • nightly fixed real-bag E2E with pinned input identity;
  • output schema compatibility tests and migration tooling;
  • release rollback and last-known-good image instructions.

Named-hardware status (2026-07-28): the v4 one-hour and eight-hour profiles passed on the recorded Jazzy i5-1145G7 machine at clean merged commit 0ec55575ffc16eb008e9f24bd6c6f24700bf2f8a. The one-hour run completed 86/86 iterations in 3,638.645 seconds; the eight-hour run completed 671/671 iterations in 28,834.115 seconds. Both had zero documented drop signatures and passed their wall-time, per-iteration, RSS, output, free-space and provenance checks. See the named-hardware evidence ledger. Timestamp reversal now fails closed before launch through preflight schema v3. Inspect-only v1-to-v2 migration and digest-pinned rollback planning are now implemented and exercised by source and clean-install contracts. The bounded-filesystem workflow and evidence contract are implemented, and the exact-revision local execution passed all ten checks. The exact-revision public workflow then passed on merge commit 4151bf5. The first tagged publication of the new rollback assets remains open, so Phase 3 remains in progress. The release workflow now ends with a fail-closed published-release audit that validates the stable release, tag commit, both image/rollback pairs, applied promotion, and every bundled file hash; implementation is not substituted for the still-missing live run.

Gate:

  • every failure either completes successfully or exits with a documented, recoverable state;
  • resource budgets are measured on named hardware;
  • no open release-blocking defect remains.

6. Phase 4 — v1.0 validation

Deliverables:

  • publish v0.9 as a stable release candidate, not only a prerelease;
  • run the external first-map validation with at least three independent users;
  • resolve or document every reported onboarding failure;
  • publish a v1.0 migration guide, support matrix and compatibility policy;
  • complete the full real-data release gate and security/release checklist.

External-validation intake status (2026-07-29): the public report form, acceptance contract, machine-readable ledger, and check_external_first_map_readiness.py --require-complete gate are available. The ledger honestly reports NOT_READY at 0/3; maintainer demos, CI runs, duplicate reporters, failed runs, and unreviewed submissions cannot satisfy the gate.

Current product runs now emit a schema-validated, privacy-bounded first_map_validation_receipt.{json,md} that binds the final manifest, diagnosis, and Autoware verifier log without exposing map geometry, private paths, or the exact command. This removes manual status/hash transcription from the external validator journey; genuine independent reports are still required and remain 0/3.

The current candidate metadata, four core package versions, changelogs, citation, comparison page, and release notes are aligned at 0.9.1. The release workflow classifies v0.9.x and later as normal stable publications while preserving prerelease behavior below v0.9. The historical v0.9.0 tag and successful publication run remain immutable and are recorded in the published-release evidence. No v0.9.1 tag or release exists until the exact candidate passes public CI and the separate publication procedure is authorized.

Gate:

  • all readiness rows in §1 have direct evidence;
  • GitHub release, documentation, image tags and package metadata agree;
  • the maintainer signs off the release according to GOVERNANCE.md.

7. Parallel capability track

Degeneracy handling, map refinement, multi-session mapping, dynamic removal, colouring and optional loop detectors continue under separate evidence roadmaps. They follow four rules:

  1. default-off until an adoption gate passes;
  2. no new beginner entrypoint;
  3. real-data positive and negative checks;
  4. promotion updates the product contract only when support responsibility is accepted.

8. Execution order

  1. Phase 0 Product Foundation.
  2. Phase 1 manifest/doctor core before adding more wrapper features.
  3. Phase 2 packaging decision early enough to expose dependency blockers.
  4. Phase 3 reliability gates on the final command surface.
  5. Phase 4 external validation and v1.0 release.

Do not mark this roadmap complete because individual code paths exist. Each phase closes only when its stated gate has authoritative evidence.