Skip to main content

OSS Inventory Version Truth

Documentation Map​

OSS Inventory Version Truth

This page records the repo-owned OSS inventory, version truth, and upgrade readiness posture for jhf-heddle.

The canonical machine-readable sources are:

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

Purpose​

This slice exists so the repository can answer three questions without guessing:

  • which upgrade-relevant OSS components are actually repo-owned here
  • which refs are pinned versus only externally classified
  • how to detect drift between repo truth, CI truth, and bounded live runtime readback

Repo-Owned Inventory​

Repo-owned pinned components currently include:

  • Keycloak runtime image
  • Postgres runtime image
  • Python base images for Plane bridge, Loom bridge, agent-reconcile API, and agent-reconcile worker
  • Gitea CI action refs for checkout and setup-python
  • Gitea CI Python runtime patch version
  • Gitea CI PyYAML dependency pin

Repo-owned upgrade governance is additionally machine-readable and component-scoped via:

  • maintenance/oss-upgrade-governance.json

This governance artifact binds each component to explicit:

  • current_version
  • target_version (or explicit steady-state target posture)
  • allowed_version_range
  • pinning_posture
  • compatibility_window_ref
  • preflight_assertion_refs
  • postdeploy_assertion_refs
  • rollback_contract_ref
  • evidence_contract_ref

and links back to Fabric-owned upstream contracts as canonical cross-repo truth.

External classification remains explicit where this repo is not the owner:

  • ubuntu-latest runner label materialization belongs to JaddaHelpifyr/jhf-deployment#270
  • stackwide OSS/version governance alignment remains referenced via JaddaHelpifyr/helpifyr-fabric#289
  • host rollout/materialization alignment remains referenced via JaddaHelpifyr/jhf-openclaw-env#209

Pinning Rules​

  • no :latest for repo-owned runtime/base images
  • no unpinned repo-owned runtime images
  • no unpinned repo-owned base images
  • no major-only action refs in repo-owned workflow definitions
  • no floating repo-owned CI package pins
  • exact CI Python patch version required

Verify Path​

Repo-only:

python maintenance/verify-oss-version-truth.py
python -m unittest tests.test_verify_oss_version_truth

Repo + Fabric-contract-readability (fail-closed):

python maintenance/verify-oss-version-truth.py \
  --fabric-contract-root C:/CodexTest/helpifyr-fabric/contracts/platform \
  --fabric-docs-root C:/CodexTest/helpifyr-fabric/docs/contracts

Bounded live verify on the canonical host:

python maintenance/verify-oss-version-truth.py \
  --live-host <internal-runtime-redacted> \
  --ssh-user administrator

CI fail-closed check:

  • .gitea/workflows/ci.yml step: Validate OSS inventory and version truth

The live verifier checks:

  • running Keycloak and Postgres image IDs against pinned immutable refs
  • Python version and OS release readback from the repo-built bridge/API/worker containers
  • repo-owned workflow refs and package pins remain aligned with machine-readable truth
  • Fabric upstream contract/doc sources are readable and include a valid jhf-heddle stack-module identity row when --fabric-contract-root / --fabric-docs-root are provided

Scope Notes​

  • this contract does not invent stackwide version truth for Fabric, deployment, or host-runner surfaces
  • external ownership is referenced explicitly instead of mirrored locally
  • live verification is read-only and does not redeploy or mutate runtime

License: AGPLv3
Project: https://helpifyr.com