# 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](../v1-readiness.md). 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`](../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:

```text
./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](../evidence/docker-first-map-2026-07-28.md) 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](../evidence/cli-v1-install-2026-07-28.md)
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;
- release `ndt_omp_ros2` before packages that declare it;
- 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.

Dependency status (rechecked 2026-07-30): 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`; the main indexes still carry Humble `0.3.0` and Jazzy
`0.2.0`, so normal apt resolution waits for the sync. `ndt_omp_ros2` remains
absent from rosdistro, but its `0.1.0` release metadata, installed-consumer
tests, and Bloom-generated Humble/Jazzy Debian gates are green at `8b77fa5`.
The parent repository now pins that release-ready commit. Remaining external
steps are the NDT tag/Bloom/rosdistro submission and the RKO-LIO main sync.
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](../evidence/real-data-soak-2026-07-28.md).
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](../evidence/bounded-filesystem-exhaustion-2026-07-29.md)
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 repository metadata, four core package versions, changelogs, citation,
comparison page, and release notes are aligned at `0.9.0`. The release
workflow now classifies v0.9.x and later as normal stable publications while
preserving prerelease behavior below v0.9. The immutable `v0.9.0` tag and
successful publication run completed on 2026-07-31 and are recorded in the
[published-release evidence](../evidence/published-release-v0.9.0-2026-07-31.md).

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.