Skip to main content

Helpifyr OSS Inventory Version Truth Companion

Documentation Map​

Helpifyr OSS Inventory Version Truth Companion

This document complements the canonical Fabric-owned OSS inventory lane for platform and tool upgrade readiness.

The authoritative machine-readable truth remains:

  • contracts/platform/helpifyr_stack_module_identity_v1.json
  • contracts/platform/platform_version_truth.json
  • contracts/platform/platform_projection_catalog.json
  • contracts/platform/stack_tool_oss_inventory_directory.json
  • contracts/platform/platform_oss_upgrade_adoption_roles_v1.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
  • GET /api/v1/platform/version-truth
  • GET /api/v1/platform/projection-catalog
  • GET /api/v1/platform/tool-oss-inventory-directory

Purpose​

  • keep one explicit operator-facing reference for repo-owned OSS version truth
  • prevent consumers from inferring upgrade posture from scattered compose files, stale issue comments, or prose-only docs
  • anchor the fail-closed verify path used by Beam, admission checks, and cross-repo rollout planning

Canonical Verify Path​

  1. python scripts/verify_platform_version_truth.py --check
  2. python scripts/verify_platform_oss_upgrade_contracts.py --check
  3. python scripts/verify_platform_oss_upgrade_adoption_contract.py --check
  4. python scripts/verify_stack_module_identity_contract.py --check
  5. python scripts/verify_oss_inventory_version_truth.py --check
  6. python scripts/build_stack_tool_oss_inventory_directory.py --workspace-root C:/CodexTest --output contracts/platform/stack_tool_oss_inventory_directory.json
  7. python scripts/verify_stack_tool_oss_inventory_directory.py --workspace-root C:/CodexTest --output contracts/platform/stack_tool_oss_inventory_directory.json
  8. bash scripts/testing/run_beam_stack_oss_inventory_wave.sh

If any step fails, OSS inventory truth is not ready and must stay fail-closed.

Ownership and Readback​

  • Fabric owns the central version-truth and stack-directory publication.
  • Fabric owns the canonical owner-versus-consumer adoption contract for future OSS upgrade modules.
  • Fabric also owns the central upgrade-governance, compatibility, and evidence companions for platform OSS families.
  • Fabric owns the stack-module identity contract that decides which registry-listed tools are actually in scope for the stack directory.
  • Downstream repos own their local docs/OSS_INVENTORY.md plus machine-readable repo-local sources.
  • Consumers must treat summary_status = gaps-detected on GET /api/v1/platform/tool-oss-inventory-directory as blocking truth, not as a warning-only hint.
  • JaddaHelpifyr/helpifyr-fabric#295

License​