Skip to main content

OSS Inventory

Documentation Map​

OSS Inventory

This document defines the repo-owned OSS inventory/version readiness surface for jhf-shuttle#141.

Canonical Files​

  • inventory: maintenance/oss-inventory.json
  • version truth: maintenance/oss-version-truth.json
  • upgrade policy: maintenance/oss-upgrade-policy.json
  • owner upgrade truth: maintenance/oss-upgrade-owner-truth.v1.json
  • Fabric consumer binding: maintenance/fabric_oss_upgrade_consumer_binding.v1.json
  • verifier: scripts/verify_oss_inventory_version_truth.py
  • binding verifier: scripts/verify_fabric_oss_upgrade_consumer_binding.py

Fabric Canonical Upstream Truth (Read-Only)​

  • contracts/platform/platform_version_truth.json
  • contracts/platform/platform_projection_catalog.json
  • contracts/platform/platform_oss_upgrade_governance_v1.json
  • contracts/platform/platform_oss_upgrade_compatibility_matrix_v1.json
  • contracts/platform/platform_oss_upgrade_evidence_contract_v1.json
  • contracts/platform/helpifyr_stack_module_identity_v1.json
  • contracts/platform/stack_tool_oss_inventory_directory.json
  • docs/contracts/HELPIFYR_PLATFORM_OSS_UPGRADE_GOVERNANCE.md
  • docs/contracts/HELPIFYR_STACK_MODULE_IDENTITY.md
  • docs/contracts/HELPIFYR_STACK_TOOL_OSS_INVENTORY_DIRECTORY.md

Shuttle consumes these as Fabric-owned truth via read-only snapshots under:

  • contracts/fabric_upstream/platform/
  • docs/fabric_upstream/contracts/

Scope​

  • inventory all upgrade-relevant OSS/runtime/CI components for this repository
  • keep repo-owned components pinned (pinned_exact), except for the single explicit Gitea CI runner label alias workflow.runner.gitea_ci = ubuntu-latest
  • classify floating external surfaces explicitly as external_owner + blocked_external
  • require the repo OCI root Docker base to stay digest-pinned so shared-runner builds do not drift across Debian base refreshes
  • reject latest and unclassified floating drift for repo-owned components; ubuntu-latest is allowed only for workflow.runner.gitea_ci and must remain machine-declared as the dedicated runner-alias exception
  • fail closed when Fabric consumer snapshots are missing, stale, or hash-mismatched
  • fail closed when owner upgrade truth misses required upgrade/evidence/rollback fields

Owner Upgrade Fields (Machine-Readable)​

Each relevant OSS family in maintenance/oss-upgrade-owner-truth.v1.json carries:

  • current_version
  • target_version (or explicit owner-controlled posture)
  • allowed_version_range
  • pinning_posture
  • compatibility_window_ref
  • preflight_assertion_refs
  • postdeploy_assertion_refs
  • rollback_contract_ref
  • evidence_contract_ref

Verify Path​

Local:

python scripts/verify_oss_inventory_version_truth.py
python scripts/verify_fabric_oss_upgrade_consumer_binding.py
python -m pytest -q tests/test_verify_oss_inventory_version_truth.py
python -m pytest -q tests/test_verify_fabric_oss_upgrade_consumer_binding.py

CI:

  • .gitea/workflows/ci.yml runs python scripts/verify_oss_inventory_version_truth.py
  • a non-zero verifier exit fails the lane (fail-closed)

Optional live (runtime-relevant slices only):

ssh <internal-runtime-redacted><internal-runtime-redacted> "docker ps --format '{{.Names}}\t{{.Status}}' | grep -E '^jhf-shuttle-'"

External Owner Dependencies​

  • JaddaHelpifyr/helpifyr-fabric#289
  • JaddaHelpifyr/jhf-openclaw-env#209
  • JaddaHelpifyr/jhf-deployment#270

These dependencies are referenced in inventory/policy for surfaces where this repo is not the final upgrade owner.

AGPLv3. Learn more at helpifyr.com.