Skip to main content

Compatibility

This compatibility page is generated from canonical repo-owned source material in JaddaHelpifyr/jhf-beam.

Compatibility Sources​

  • docs/OSS_INVENTORY.md
  • docs/PUBLIC_SURFACES.md

Derived from OSS Inventory and Version Truth​

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. Schema version 2 makes every discovered component carry license, license_class, and license_evidence_url. The default is deliberately fail-closed: NOASSERTION with unknown_blocked until the responsible owner provides an SPDX identifier and component-specific legal evidence. Discovery must never infer a license from an image name, package name, or general documentation. 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)
  • schemas/stack-oss-inventory.schema.json (schemas/stack-oss-inventory.schema.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 active OpenClaw execution surfaces are OpenTofu-clean, but the stack OSS inventory still intentionally publishes the deployment-owned opentofu core tool and terratest family while jhf-deployment remains their owner of record
  • 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) (<local-env-redacted> 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
python -m pytest -q tests/test_stack_oss_inventory_license_metadata.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 premature removal of deployment-owned opentofu or terratest from the stack OSS inventory while jhf-deployment still publishes those families
  • 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
  • no legal approval inferred from inventory discovery; unknown_blocked stays blocked until an owner-reviewed catalog entry supplies a concrete SPDX value and evidence URL
  • JaddaHelpifyr/jhf-beam#154
  • JaddaHelpifyr/jhf-beam#172
  • JaddaHelpifyr/jhf-beam#617
  • JaddaHelpifyr/helpifyr-fabric#1541
  • JaddaHelpifyr/helpifyr-fabric#1543

License​

AGPLv3. See ../LICENSE (LICENSE).

Learn more at helpifyr.com.