Skip to main content

OSS Inventory and Version Truth

Documentation Map​

OSS Inventory and Version Truth

Tool / Contract Summary​

jhf-loom publishes one repo-owned OSS inventory, one version truth document, and one upgrade policy for upgrade-relevant runtime and CI dependencies.

Machine-readable sources:

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

Fabric contract alignment sources:

  • 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

Repo validators:

python scripts/validate_oss_inventory_truth.py
python maintenance/pull_stack_oss_inventory.py --output test-results/stack-oss-inventory.workspace.json

Optional live host verification:

python scripts/validate_oss_inventory_truth.py --host <internal-runtime-redacted>
python maintenance/pull_stack_oss_inventory.py --host <internal-runtime-redacted> --output test-results/stack-oss-inventory.workspace.json

Business Value​

Upgrade readiness must not rely on scattered compose tags, drifting CI action refs, or undocumented host assumptions. This repo now publishes one explicit inventory and one explicit pinning policy so upgrade consumers can distinguish between repo-owned exact pins, explicit toolchain channels, and external blockers.

Current Verified State​

The current repo-owned OSS scope covers:

  • runtime images: PostgreSQL, ActiveMQ, Transform, Search, Repository, Share
  • CI actions: actions/checkout, actions/setup-python
  • CI toolchain channel: Python 3.12

Pinning posture:

  • runtime images: exact_tag
  • CI actions: exact_commit_sha
  • CI Python toolchain: minor_channel

External readiness blockers stay explicit in maintenance/oss-upgrade-policy.json (maintenance/oss-upgrade-policy.json) and are not worked around in this repo.

Upgrade Plan Fields (Fail-Closed)​

Every repo-owned OSS component policy entry must declare all of these fields:

  • current_version
  • target_version
  • allowed_version_range
  • pinning_posture
  • compatibility_window_ref
  • preflight_assertion_refs
  • postdeploy_assertion_refs
  • rollback_contract_ref
  • evidence_contract_ref

Missing any of these fields is a hard validation error (fail closed).

Available now​

Component keyTruth surfacePinning mode
runtime.postgres.env.example, compose.ymlexact_tag
runtime.activemq.env.example, compose.ymlexact_tag
runtime.transform.env.example, compose.ymlexact_tag
runtime.search.env.example, compose.ymlexact_tag
runtime.repository.env.example, compose.ymlexact_tag
runtime.share.env.example, compose.ymlexact_tag
ci.action_checkout.gitea/workflows/ci.ymlexact_commit_sha
ci.action_setup_python.gitea/workflows/ci.ymlexact_commit_sha
ci.python_toolchain.gitea/workflows/ci.ymlminor_channel

Planned / Not in current scope​

  • stack-wide cross-repo upgrade wave orchestration remains external
  • owner-side adapter/document/runtime upgrade decisions in other repos remain blocked until their issues are resolved
  • no host-side workaround or shadow truth is introduced here

Public Surfaces​

  • maintenance/oss-inventory.json (maintenance/oss-inventory.json)
  • maintenance/oss-version-truth.json (maintenance/oss-version-truth.json)
  • maintenance/oss-upgrade-policy.json (maintenance/oss-upgrade-policy.json)
  • maintenance/pull_stack_oss_inventory.py (maintenance/pull_stack_oss_inventory.py)
  • scripts/validate_oss_inventory_truth.py (scripts/validate_oss_inventory_truth.py)

Compatibility Window​

jhf-loom treats runtime images as exact-tag surfaces and CI actions as exact-commit surfaces. Python 3.12 is intentionally a channel pin, not a patch pin, and widening it to a major-only or latest style ref is not allowed.

Lifecycle Status​

  • status: active
  • current issue:
    • inventory tracking lane: JaddaHelpifyr/jhf-loom#94
    • contract adoption lane: JaddaHelpifyr/jhf-loom#102
  • blocked externally by:
    • JaddaHelpifyr/helpifyr-fabric#289
    • JaddaHelpifyr/jhf-openclaw-env#209
    • JaddaHelpifyr/jhf-deployment#270
    • JaddaHelpifyr/jhf-spindle#208
    • JaddaHelpifyr/jhf-heddle#117
    • JaddaHelpifyr/jhf-warp#257
    • JaddaHelpifyr/jhf-keystore#82
    • JaddaHelpifyr/jhf-shuttle#138
    • JaddaHelpifyr/jhf-reed#13

Readiness / Drift / Monitoring​

The validator turns red when:

  • a declared OSS component is missing from the inventory, version truth, or policy
  • a runtime image uses latest, no tag, or a mismatched tag
  • a CI action uses a tag ref instead of the declared commit SHA
  • the CI Python channel drifts from the declared 3.12 track
  • live runtime containers on <internal-runtime-redacted> do not match repo-owned image truth

Deployment / Verify​

Repo:

python scripts/validate_oss_inventory_truth.py
python maintenance/pull_stack_oss_inventory.py --output test-results/stack-oss-inventory.workspace.json
python -m unittest discover -s tests -p "test_*.py"

Live:

python scripts/validate_oss_inventory_truth.py --host <internal-runtime-redacted>
python maintenance/pull_stack_oss_inventory.py --host <internal-runtime-redacted> --output test-results/stack-oss-inventory.workspace.json

Rollback Posture​

Rollback contract posture is repo-owned and machine-readable via:

  • maintenance/oss-upgrade-policy.json#/policies/<component>/upgrade_plan/rollback_contract_ref
  • maintenance/oss-version-truth.json#/components/<component>/rollback_contract_ref

No OSS upgrade path is treated as complete when rollback references are missing.

Known Limits​

  • this repo validates Loom-owned runtime and CI truth only
  • external blocked-by repos remain explicit and are not normalized locally
  • no raw secrets or passwords are emitted; only component keys, refs, and version presence are validated
  • JaddaHelpifyr/jhf-loom#94

License: AGPLv3.

Helpifyr: https://helpifyr.com