Skip to main content

OSS Inventory and Version Truth

Documentation Map​

OSS Inventory and Version Truth

Tool / Contract Summary​

jhf-beam publishes repo-owned OSS inventory and version-truth lanes for stack-wide upgrade readiness and owner routing. The normal path consumes the Fabric-owned OSS upgrade truth family read-only:

  • GET /api/v1/platform/version-truth
  • GET /api/v1/platform/projection-catalog
  • GET /api/v1/platform/tool-oss-inventory-directory

The canonical upstream contract sources remain in helpifyr-fabric:

  • 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

Machine-readable sources:

  • maintenance/stack-oss-scan-scope.json (maintenance/stack-oss-scan-scope.json)
  • monitoring/sources/stack-oss-catalog.json (monitoring/sources/stack-oss-catalog.json)
  • maintenance/oss-inventory-scope.json (maintenance/oss-inventory-scope.json)
  • maintenance/fabric-oss-upgrade-consumption.json (maintenance/fabric-oss-upgrade-consumption.json)

Execution and verification surfaces:

  • maintenance/pull_stack_oss_inventory.py (maintenance/pull_stack_oss_inventory.py)
  • maintenance/verify-fabric-oss-upgrade-consumption.py (maintenance/verify-fabric-oss-upgrade-consumption.py)
  • maintenance/verify-fabric-tool-oss-directory-status.py (maintenance/verify-fabric-tool-oss-directory-status.py)
  • maintenance/generate_stack_upgrade_plan.py (maintenance/generate_stack_upgrade_plan.py)
  • maintenance/verify-stack-oss-inventory.py (maintenance/verify-stack-oss-inventory.py)
  • scripts/testing/run_beam_stack_oss_inventory_wave.sh (scripts/testing/run_beam_stack_oss_inventory_wave.sh)

Business Value​

Upgrade readiness must not depend on scattered version snippets. Beam keeps one explicit OSS inventory lane, one explicit version/readback lane, and explicit owner routing for drift and blockers. Fabric directory summary status and blocked-tool count are fail-closed inputs in the wave path. Fabric version truth, projection catalog, governance, compatibility, evidence, and module identity stay upstream-owned and Beam must not reconstruct them from prose, latest tags, or host memory.

Current Verified State​

  • stack-wide OSS inventory and upgrade planning are implemented and validated through repo verifiers
  • Beam is explicitly classified as a Fabric read-only-upgrade-consumer through maintenance/fabric-oss-upgrade-consumption.json (maintenance/fabric-oss-upgrade-consumption.json)
  • Fabric directory fields summary_status and blocked_tool_count are included in inventory evidence and validated fail-closed
  • Fabric version-truth, projection-catalog, governance, compatibility, evidence, and module-identity surfaces are verified as one coherent upstream family
  • owner-routing stays explicit and does not create local shadow truth in Beam
  • AGENTS guidance for Gitea API token runtime usage is documented in: AGENTS.md (AGENTS.md) (C:/CodexTest/.env as GITEA_TOKEN, no token value in repo artifacts)

Verify Path​

Repo:

python maintenance/verify-fabric-oss-upgrade-consumption.py --fabric-root ../helpifyr-fabric
python maintenance/verify-stack-oss-inventory.py
python maintenance/verify-maintenance-contracts.py
bash scripts/testing/run_beam_stack_oss_inventory_wave.sh

Optional live host readback:

curl `api/v`1/platform/version-truth
curl `api/v`1/platform/projection-catalog
curl `api/v`1/platform/tool-oss-inventory-directory
python maintenance/pull_stack_oss_inventory.py --host <internal-runtime-redacted> --output test-results/stack-oss-inventory.live.json
python maintenance/verify-fabric-tool-oss-directory-status.py --inventory test-results/stack-oss-inventory.live.json

Planned / Not in current scope​

  • no local workaround for external owner repo drift
  • no shadow-truth fallback for Fabric version truth, projection catalog, governance, compatibility, evidence, module identity, or directory in normal mode
  • no local latest-based upgrade acceptance
  • no token materialization in docs, issues, logs, or evidence
  • no replacement of owner repo version truth with Beam-authored shadow data
  • JaddaHelpifyr/jhf-beam#154
  • JaddaHelpifyr/jhf-beam#172

License​

AGPLv3. See ../LICENSE (LICENSE).

Learn more at helpifyr.com.