Validate pinned navigation install and release manifest evidence

.gitattributes

@@ -0,0 +1,3 @@
+*.sh text eol=lf
+*.py text eol=lf
+/evidence/** -text

.github/workflows/navigation-install.yml

@@ -0,0 +1,37 @@
+name: Navigation pinned install
+on:
+  pull_request:
+    paths:
+      - navigation-install-manifest.json
+      - navigation-install-test-config.json
+      - scripts/**
+      - tests/**
+      - .github/workflows/navigation-install.yml
+  push:
+    branches: [main]
+    paths:
+      - navigation-install-manifest.json
+      - navigation-install-test-config.json
+      - scripts/**
+      - tests/**
+      - .github/workflows/navigation-install.yml
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  install:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - name: Check release manifest integration
+        run: python3 -m unittest discover -s tests -v
+      - name: Verify pinned install and consumers
+        run: python3 scripts/validate_navigation_install.py --evidence evidence/navigation-install
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        if: always()
+        with:
+          name: navigation-pinned-install-evidence
+          path: evidence/navigation-install/
+          include-hidden-files: true
+          if-no-files-found: error

.gitignore

@@ -6,3 +6,15 @@ dist/
 input/
 dist/
 release-test/
+
+# Keep compact install evidence in Git; full artifacts remain local/Actions outputs.
+evidence/**/*.tar.gz
+evidence/**/*.zip
+evidence/**/producer-log/
+evidence/**/consumer-log/
+__pycache__/
+evidence/navigation-install-20261006/
+docs/evidence/*.zip
+docs/evidence/*.zip.sha256
+evidence/**/verification-tools/
+evidence/navigation-install/

README.md

@@ -1,5 +1,9 @@
 # OpenAMRobot v0.0.1
 
+For the pending navigation release-install gate, see
+[pinned installation and troubleshooting](docs/navigation-install.md).
+This candidate validation does not change the historical v0.0.1 release.
+
 The first public release of the OpenAMRobot platform.
 
 This release is a frozen snapshot of the OpenAMRobot ecosystem, containing all repositories required to study, build, modify, reproduce, and extend the platform.

RELEASE_PROCESS.md

@@ -1,19 +1,24 @@
 # OpenAMRobot Release Process
 
+For navigation package pinning, clean install evidence, and candidate manifest
+validation, follow [the navigation install gate](docs/navigation-install.md).
+`navigation-install-test-config.json` is a navigation-only test fixture,
+not a product release configuration. PR #12 owns rc.1 source selection.
+
 This repository builds a product-level OpenAMRobot release from the project's distributed repositories.
 
 ## Directory Structure
 
 ```text
 openamrobot-release/
-├── input/                 # Component ZIP archives; ignored by Git
-├── dist/                  # Generated release assets; ignored by Git
-├── release-metadata/      # Product-level README and release documents
-├── scripts/
-│   ├── build_release.py
-│   └── validate_release.py
-├── release-config.json
-└── RELEASE_PROCESS.md
+├── input/                 # Component ZIP archives; ignored by Git
+├── dist/                  # Generated release assets; ignored by Git
+├── release-metadata/      # Product-level README and release documents
+├── scripts/
+│   ├── build_release.py
+│   └── validate_release.py
+├── release-config.json
+└── RELEASE_PROCESS.md
 ```
 
 ## 1. Prepare Component Archives

docs/issue-5-update.md

@@ -0,0 +1,29 @@
+# Proposed update for release issue #5
+
+Release-level pinned-install validation is complete locally for
+`openamrobot-interfaces@fa7c438e33bd807c174fa0747119d7d627faa3bf`,
+`openamr_nav_msgs` package `0.0.0`, runtime contract `1`.
+
+Two clean producer/consumer pairs passed on digest-pinned Ubuntu 24.04 /
+ROS 2 Jazzy. Each downstream container received only the ordinary install
+tarball and test fixtures, with no producer source/build tree or developer
+overlay. All 11 generated messages loaded and serialized successfully;
+the independent C++ consumer built and ran. The absent-install negative
+control failed as expected. The 159 generated header/IDL hashes and resolved
+dependency inventories matched between runs.
+
+The release-owned installation manifest records the exact pin and versions.
+A navigation-only test builder configuration carries them into `MANIFEST.json` together
+with install-artifact digests and verification evidence. Builder tests reject
+failing evidence and pin/archive/package/contract mismatches; all eight tests
+pass. A separate integration check used the actual validated source archive.
+
+Installation and troubleshooting instructions, exact Docker arguments,
+verifier source references, full logs, dependency inventories, and
+checksums are retained in workflow artifacts; compact evidence remains in Git. See
+[the evidence index](navigation-install-evidence.md) and
+[installation instructions](navigation-install.md).
+
+This is source-install evidence, not a published binary or complete product
+release. Hosted CI and reviewer acceptance remain pending. Please review
+the prepared changes and evidence before closing issue #5.

docs/navigation-builder-tests.log

@@ -0,0 +1,14 @@
+Command argv: ["C:\\Python314\\python.exe", "-m", "unittest", "discover", "-s", "tests", "-v"]
+test_different_archive_bytes_are_rejected (test_navigation_release.NavigationManifestTests.test_different_archive_bytes_are_rejected) ... ok
+test_different_evidence_pin_is_rejected (test_navigation_release.NavigationManifestTests.test_different_evidence_pin_is_rejected) ... ok
+test_failed_install_is_rejected (test_navigation_release.NavigationManifestTests.test_failed_install_is_rejected) ... ok
+test_legacy_configuration_still_builds_without_install_evidence (test_navigation_release.NavigationManifestTests.test_legacy_configuration_still_builds_without_install_evidence) ... ok
+test_validated_pin_and_contract_reach_product_manifest (test_navigation_release.NavigationManifestTests.test_validated_pin_and_contract_reach_product_manifest) ... ok
+test_wrong_archive_commit_is_rejected (test_navigation_release.NavigationManifestTests.test_wrong_archive_commit_is_rejected) ... ok
+test_wrong_contract_version_is_rejected (test_navigation_release.NavigationManifestTests.test_wrong_contract_version_is_rejected) ... ok
+test_wrong_package_version_is_rejected (test_navigation_release.NavigationManifestTests.test_wrong_package_version_is_rejected) ... ok
+
+----------------------------------------------------------------------
+Ran 8 tests in 3.209s
+
+OK

docs/navigation-install-evidence.md

@@ -0,0 +1,91 @@
+# Release issue #5: local pinned-install evidence
+
+Validated **6 October 2026** on a Windows host using fresh Linux amd64
+containers, Ubuntu 24.04 and ROS 2 Jazzy. Final result: **PASS**, twice.
+
+| Identifier | Recorded value |
+|---|---|
+| Interfaces source commit | `fa7c438e33bd807c174fa0747119d7d627faa3bf` |
+| Package | `openamr_nav_msgs` |
+| Package version | `0.0.0` |
+| Runtime contract version | `1` |
+| Base image | `ros@sha256:c3706ef0a0aa45413c07803cf433602f543b22e45b4855f6fca955c2d8ecc4e8` |
+| Source archive SHA-256 | `692f105fd5415ea2203e95ab31f954412a0ba1451249e31136b94d7c3f22bb73` |
+
+## Results
+
+Both ordinary source builds produced install tarballs. Each was consumed by
+a separate fresh container receiving **only the install tarball and test
+fixtures**. No interfaces source or producer build tree was available to it.
+All 11 generated messages passed lookup, import and native serialization.
+Both C++ consumers configured, built, linked and ran. Both absent-install
+negative controls failed as expected with `openamr_nav_msgs` unavailable.
+
+The **159** generated header/IDL hashes, expanded message definitions, and
+resolved producer and consumer dependency inventories matched between runs.
+Install tarballs have independent recorded digests; compiled binary or tarball
+byte reproducibility is not claimed.
+
+Eight release-builder regression tests pass. A separate integration fixture
+using the **actual validated source archive** also passed and emitted the
+[pinned component entry](navigation-manifest-component.json). That fixture is
+not a complete product build; [its command/output](navigation-manifest-integration.log)
+is recorded separately.
+
+## Exact commands
+
+From `openamrobot-release`, on this Windows host:
+
+```powershell
+python scripts/validate_navigation_install.py --evidence evidence/navigation-install-20261006-final
+python -m unittest discover -s tests -v
+python -m compileall -q scripts tests
+& 'C:\Program Files\Git\bin\bash.exe' -n scripts/nav-install/producer.sh
+& 'C:\Program Files\Git\bin\bash.exe' -n scripts/nav-install/consumer.sh
+git diff --check
+```
+
+The workflow YAML was parsed with PyYAML. No hosted Actions run is claimed.
+The validation runner's exact Docker arguments are included below. Verifier
+sources are referenced at their recorded Git commit rather than copied. An earlier run in
+`evidence/navigation-install-20261006` also passed, but mounted the producer
+artifact directory read-only. The final run tightened this to the install
+tarball alone and saved the verifier sources. Final evidence is authoritative
+for this change; the earlier run is retained locally.
+
+## Reviewable files
+
+- [Machine-readable result](../evidence/navigation-install-20261006-final/result.json)
+- [Manifest snapshot](../evidence/navigation-install-20261006-final/manifest.json)
+- [Docker command arguments](../evidence/navigation-install-20261006-final/commands.json)
+- [Evidence checksums](../evidence/navigation-install-20261006-final/checksums.sha256)
+- [First producer log](../evidence/navigation-install-20261006-final/first/producer/validation.log)
+- [First consumer log](../evidence/navigation-install-20261006-final/first/consumer/validation.log)
+- [Second producer log](../evidence/navigation-install-20261006-final/second/producer/validation.log)
+- [Second consumer log](../evidence/navigation-install-20261006-final/second/consumer/validation.log)
+- [Generated file inventory](../evidence/navigation-install-20261006-final/first/consumer/generated.sha256)
+- [Expanded message definitions](../evidence/navigation-install-20261006-final/first/consumer/interfaces.txt)
+- [Resolved consumer dependencies](../evidence/navigation-install-20261006-final/first/consumer/dependencies.txt)
+- [Install and troubleshooting instructions](navigation-install.md)
+
+Full colcon logs, install tarballs and source ZIPs belong in the
+`navigation-pinned-install-evidence` workflow artifact. The full ZIP formerly
+under `docs/evidence/` has been removed from Git. The compact checksum index
+now covers only the retained Git evidence files, including
+[verifier provenance](../evidence/navigation-install-20261006-final/verification-source.json).
+Historical tools can be read from
+[scripts/nav-install at f44f69e](https://github.com/openAMRobot/openamrobot-release/tree/f44f69e1b580a2ee3db4709082e69be62261feca/scripts/nav-install).
+Original outcome logs and the recorded October 6 image remain historical;
+the October 22 review rerun uses the current shared CI base digest.
+
+## Scope and remaining review
+
+This proves the pinned navigation **source install** and installed-package
+consumption. It does not publish a binary package or certify whole-product
+readiness, semantic interoperability, or hardware safety. The navigation-only test configuration does not select a product release;
+rc.1 source selection belongs to PR #12. The historical v0.0.1 configuration and
+earlier evidence are preserved.
+
+The October 6 run above is local evidence. Hosted workflow results and
+the October 22 review rerun are reported in the PR description; this record
+does not claim a new hosted pass. No merge, tag or release is performed.

docs/navigation-install.md

@@ -0,0 +1,144 @@
+# Pinned navigation installation
+
+Release issue [#5](https://github.com/openAMRobot/openamrobot-release/issues/5)
+is validated against the release-owned [installation manifest](../navigation-install-manifest.json),
+not a moving interfaces branch. The selected source commit is
+`fa7c438e33bd807c174fa0747119d7d627faa3bf`; `openamr_nav_msgs` package version
+is **0.0.0** and `NavigationStatus.CONTRACT_VERSION` is **1**. These identifiers
+are distinct. This is a source-install candidate, not a published binary package.
+
+## Reproduce the release gate
+
+Install Python 3.11+ and Docker with its Linux engine running. The host needs
+no ROS installation or developer workspace. From this release repository:
+
+```sh
+python3 scripts/validate_navigation_install.py --manifest navigation-install-manifest.json --evidence evidence/navigation-install
+```
+
+On Windows use `python` if that is the installed command. Choose a **new**
+evidence directory for every attempt; the runner refuses to overwrite one.
+The target is Ubuntu 24.04 / ROS 2 Jazzy / linux amd64, with the base image
+pinned by digest in the manifest. It matches the shared CI image base in
+[the CI Dockerfile](https://github.com/openAMRobot/.github/blob/a1f619307557ad3a0680065127df7e027d47dd83/containers/ci/Dockerfile).
+Two independent producer/consumer pairs run:
+
+1. The producer checks out the exact commit, verifies the package version,
+   resolves dependencies, builds an ordinary install (no symlink install),
+   and creates a source ZIP and installed-package tarball.
+2. A fresh consumer container receives the install tarball and test fixtures
+   only. The producer source/build tree is absent. Before installing the
+   artifact, CMake configuration must fail because `openamr_nav_msgs` is missing.
+3. After extracting the artifact, only ROS Jazzy and the navigation install
+   are sourced. The package prefix must be `/opt/nav-install/openamr_nav_msgs`.
+   All 11 generated messages are located, imported, and serialized/deserialized
+   with native Python type support; the contract constant must equal `1`.
+4. The minimal C++ consumer builds against the installed CMake exports and
+   headers, links native type support, and runs serialization round trips for
+   navigation, docking, and parking messages, including aggregate fields.
+5. The two runs must agree on generated header/IDL hashes, expanded definitions,
+   and resolved producer and consumer dependency inventories.
+
+The runner snapshots its scripts before starting. No developer overlay,
+host ROS paths, user Python packages, or source checkout is mounted into the
+consumer. Generated file reproducibility is checked; byte-identical binaries
+and a frozen apt/rosdep dependency snapshot are not claimed. Resolved package
+versions are recorded because apt and rosdep indexes remain live.
+
+## Consume the validated install
+
+The validation tarball is a test artifact for the recorded Linux/Jazzy environment.
+It is not an apt package or a published product release. In a matching environment
+with the dependencies recorded in `consumer/dependencies.txt` installed:
+
+```sh
+tar -C /opt -xzf navigation-install.tar.gz
+source /opt/ros/jazzy/setup.bash
+source /opt/nav-install/local_setup.bash
+ros2 pkg prefix openamr_nav_msgs
+ros2 interface show openamr_nav_msgs/msg/NavigationStatus
+mkdir -p consumer_ws/src
+cp -r scripts/nav-install/nav_consumer consumer_ws/src/
+cd consumer_ws
+colcon build --event-handlers console_direct+
+source install/local_setup.bash
+ros2 run nav_install_consumer smoke
+```
+
+Extracting into `/opt` may require administrative rights. Package dependencies
+and the exact setup/build commands are in `scripts/nav-install/consumer.sh`.
+The consumer fixture uses `find_package(openamr_nav_msgs 0.0.0 EXACT REQUIRED)`;
+its package manifest declares the dependency. Runtime contract version is
+checked separately. Owning-repository field semantics remain canonical in the
+[pinned navigation contract](https://github.com/openAMRobot/openamrobot-interfaces/blob/fa7c438e33bd807c174fa0747119d7d627faa3bf/ros2/openamr_nav_msgs/CONTRACT.md).
+
+## Release-manifest integration
+
+[navigation-install-test-config.json](../navigation-install-test-config.json) is a
+**navigation-only test fixture** with version `0.0.0-test`. It is not an rc.1
+configuration and contains no other product components. Product rc.1 pins,
+component scope and versioning belong to
+[PR #12](https://github.com/openAMRobot/openamrobot-release/pull/12).
+The historical `release-config.json` is unchanged.
+
+After the gate runs, use its exact validated archive with the fixture:
+
+```sh
+mkdir -p input
+cp evidence/navigation-install/first/producer/interfaces-source.zip input/openamrobot-interfaces-fa7c438e33bd807c174fa0747119d7d627faa3bf.zip
+python3 scripts/build_release.py --config navigation-install-test-config.json --input-dir input --output-dir dist --metadata-dir release-metadata
+```
+
+The fixture uses the manifest's `evidence_path`, which points to the canonical
+`evidence/navigation-install/result.json`. To consume an Actions run, download
+its `navigation-pinned-install-evidence` artifact into `evidence/navigation-install`.
+If a local run uses another output directory, update a local manifest copy's
+`evidence_path` and the local fixture's `install_manifest` together.
+The generated `NavigationInstallTest-v0.0.0-test-source.zip` is test output;
+legacy product metadata copied by the builder does not make it a product release.
+
+The builder rejects missing/failing evidence, mismatched manifest/evidence pins
+or versions, unvalidated archive bytes, or archive/package/contract mismatches.
+Generated `MANIFEST.json` carries the full source SHA, package version, contract
+version, evidence result/digest, workflow URL when hosted, and install-artifact
+digests. Do not overwrite or republish an existing release with this configuration.
+
+## Evidence and review
+
+See [the local evidence record](navigation-install-evidence.md). `commands.json`
+records the exact Docker arguments. `verification-source.json` records the verifier repository, commit, paths, file
+hashes and working-tree state; retrieve the tools from `scripts/nav-install`
+at that commit rather than maintaining evidence copies. Each stage retains full command output,
+dependency versions and colcon logs; consumer logs include all message checks
+and the negative control. `checksums.sha256` covers the evidence files.
+Install tarballs, source ZIPs and detailed colcon logs remain in the local/Actions
+artifact; compact logs and results are retained in this repository.
+The [CI workflow](../.github/workflows/navigation-install.yml) uploads evidence
+even on failure. A skipped job or partial artifact is not a pass. Local evidence
+does not constitute a hosted CI result. Reviewer acceptance and publication
+remain separate from a successful source install.
+
+## Troubleshooting
+
+- Docker engine pipe missing or engine HTTP 500: start Docker Desktop's Linux
+  engine and check `docker info`. No checks ran if the engine was unavailable.
+- Image, apt, Git or rosdep failure: retain the failed log and repair access to
+  the dependency source; do not skip dependency installation.
+- Missing package: source Jazzy, then the intended install's `local_setup.bash`;
+  verify the package prefix. Do not source a developer workspace to make it pass.
+- Python/type-support failure: check the recorded Jazzy system Python and ROS
+  runtime dependencies. Do not copy generated files from a source workspace.
+- CMake/version mismatch: verify the manifest SHA, package `0.0.0`, and contract
+  `1`. A package version does not replace the contract-version check.
+- Reproducibility mismatch: compare both dependency inventories and generated
+  hashes. Record a failure and rerun only after addressing the cause.
+- Build-release pin rejection: use the source ZIP emitted by the validated run;
+  redownloading or modifying a ZIP can change its digest despite the same commit.
+
+## Provenance
+
+Prepared with OpenAI Codex assistance at the release owner's request. The
+consumer and generated-message check reuse the earlier local interfaces install
+validation work; the producer/consumer separation, release builder integration,
+workflow, and documentation were prepared for issue #5. No external source code
+was copied. Repository code/documentation licensing applies.