OSS Inventory and Version Truth

Documentation Map

• Overview

• Quick Start

• Installation

• Configuration

• Operations

• Troubleshooting

• Release Notes

• Compatibility

• Architecture

• API Reference

• Security

• Integrations

• Capabilities

• Data Model

• Roadmap

• OSS Inventory

• Channel: stable

• Source repo: JaddaHelpifyr/jhf-loom

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 key	Truth surface	Pinning mode
runtime.postgres	.env.example, compose.yml	exact_tag
runtime.activemq	.env.example, compose.yml	exact_tag
runtime.transform	.env.example, compose.yml	exact_tag
runtime.search	.env.example, compose.yml	exact_tag
runtime.repository	.env.example, compose.yml	exact_tag
runtime.share	.env.example, compose.yml	exact_tag
ci.action_checkout	.gitea/workflows/ci.yml	exact_commit_sha
ci.action_setup_python	.gitea/workflows/ci.yml	exact_commit_sha
ci.python_toolchain	.gitea/workflows/ci.yml	minor_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

Related Issues

• JaddaHelpifyr/jhf-loom#94

License: AGPLv3.

Helpifyr: https://helpifyr.com