Skip to main content

OSS Inventory, Version Truth, and Upgrade Readiness

Documentation Map​

OSS Inventory, Version Truth, and Upgrade Readiness

This document defines the repo-local consumer contract for OSS inventory and version truth in jhf-warp.

Upstream Canonical Truth​

Source Of Truth: JaddaHelpifyr/helpifyr-fabric.

Warp consumes these Fabric-owned OSS upgrade and module-identity contracts:

  • 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

Warp does not own central platform upgrade truth and must not create a parallel interpretation.

Canonical Machine-Readable Sources​

  • maintenance/oss-inventory.json
  • maintenance/oss-version-truth.json
  • maintenance/oss-upgrade-policy.json

These files are repo-owned consumer truth for:

  • relevant OSS components used by runtime, CI, and packaging paths
  • component pinning posture (tag-pinned, major-track, external-floating-classified)
  • external owner classification where this repo does not own the upstream release train
  • upgrade readiness blockers that are outside this repository
  • explicit owner-side upgrade posture in maintenance/oss-upgrade-policy.json -> upgrade_families

Verification Path​

Run:

python scripts/verify_oss_inventory.py
python scripts/verify_fabric_oss_upgrade_consumer.py

The verifier fails closed when:

  • an observed OSS surface is missing from inventory truth
  • observed refs drift from inventory truth
  • a repo-owned container ref is floating (latest or untagged)
  • pyproject dependency truth drifts from maintenance/oss-version-truth.json
  • required external blocker references drift from maintenance/oss-upgrade-policy.json
  • required Fabric upstream contract/doc/surface references drift from maintenance/oss-upgrade-policy.json -> fabric_consumer_contract
  • any component-specific owner upgrade fields are missing or stale:
    • current_version
    • target_version (or explicit target posture)
    • allowed_version_range
    • pinning_posture
    • compatibility_window_ref
    • preflight_assertion_refs
    • postdeploy_assertion_refs
    • rollback_contract_ref
    • evidence_contract_ref

Policy Summary​

  • Repo-owned container/runtime tooling refs must be explicit and non-floating.
  • Runner labels may stay *-latest only when explicitly classified as external owner scope.
  • Python dependencies must remain bounded by explicit version ranges.
  • External cross-repo upgrade blockers are tracked in machine-readable policy truth and must not be hidden by local workarounds.
  • Fabric projection readback surfaces for consumer gating are:
    • GET /api/v1/platform/version-truth
    • GET /api/v1/platform/projection-catalog
    • GET /api/v1/updates/compatibility-matrix
  • Missing or stale Fabric truth is fail-closed for consumer upgrade readiness.
  • Missing owner-side upgrade/evidence/rollback truth is fail-closed for this repo.

Compatibility Note​

docs/OSS_VERSION_GOVERNANCE.md remains as a compatibility alias and points to this canonical document.

License​

AGPLv3. See ../LICENSE (LICENSE).

Learn more at helpifyr.com.