Skip to main content

OSS Inventory Version Truth

Documentation Map​

OSS Inventory Version Truth

Purpose​

This page is the canonical Bobbin-owned contract for OSS inventory truth, version pinning posture, and upgrade-readiness verification.

It does not replace runtime-owner truth in other repositories. It defines what jhf-bobbin itself owns and how it proves consistency in CI and repo-local verification.

Source of Truth Artifacts​

  • configs/oss-inventory.json (configs/oss-inventory.json)
  • configs/installer.env.example (configs/installer.env.example)
  • scripts/install_jhf_memory.sh (scripts/install_jhf_memory.sh)
  • fabric-manifest.json (fabric-manifest.json) (runtime.runtimeVersionTruth)
  • contracts/oss/oss_inventory_v1.json (contracts/oss/oss_inventory_v1.json)
  • contracts/oss/oss_version_truth_v1.json (contracts/oss/oss_version_truth_v1.json)
  • contracts/oss/oss_upgrade_governance_v1.json (contracts/oss/oss_upgrade_governance_v1.json)
  • contracts/oss/oss_upgrade_evidence_contract_v1.json (contracts/oss/oss_upgrade_evidence_contract_v1.json)

Fabric OSS Upgrade Consumer Contract (Read-Only)​

Bobbin consumes Fabric-owned OSS update/upgrade truth as a consumer and does not redefine platform ownership locally. Canonical upstream owner repo: JaddaHelpifyr/helpifyr-fabric.

Canonical upstream contract references:

  • 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

Repo-local consumer readback surfaces:

  • GET /api/v1/platform/version-truth
  • GET /api/v1/platform/projection-catalog
  • GET /api/v1/updates/compatibility-matrix
  • GET /api/v1/platform/tool-oss-inventory-directory

This lane is explicitly fail-closed for missing, stale, unreadable, or contradicting Fabric truth. Bobbin must not pass this lane by rebuilding local shadow truth.

Canonical Runtime Family Truth​

  • LocalAI: localai:v4.1.0
  • Mem0 plugin fork: openclaw-mem0 ref 3330dd4fae526c8eab0c197d5fc681cacf8e5430
  • Qdrant: Qdrant v1.17.1
  • @qdrant/js-client-rest: 1.15.1

All runtime pins above are enforced as contract truth, not best-effort hints.

Classification Model​

Components in configs/oss-inventory.json must be classified as exactly one of:

  • pinned: repo-owned exact pin or immutable reference
  • external_classified: not pinned in Bobbin, but explicitly owned elsewhere

No unclassified dependency is accepted for this contract surface.

Verify Route (Versioned And Testable)​

Repo-local contract verification​

python3 scripts/check_runtime_version_truth.py
python3 scripts/check_oss_inventory_contract.py
python3 scripts/check_fabric_oss_upgrade_consumer_contract.py
python3 scripts/check_bobbin_oss_upgrade_owner_contract.py

Full repo contract lane​

python3 -m unittest -q tests/test_contracts.py
bash scripts/fabric-selfcheck.sh

Optional live consumer verification​

python3 scripts/check_fabric_oss_upgrade_consumer_contract.py --check-live --fabric-base-url http://<internal-runtime-redacted>:28080

CI route​

The default .gitea workflow executes both:

  • python scripts/check_runtime_version_truth.py
  • python scripts/check_oss_inventory_contract.py

This ensures version truth and inventory truth fail closed on drift before merge.

Fail-Closed Behavior​

A red verify result means at least one of these drift classes exists:

  • manifest and OSS inventory mismatch
  • installer defaults and OSS inventory mismatch
  • install script defaults and OSS inventory mismatch
  • pinned dependency downgraded to floating behavior
  • required docs/version references missing from compatibility/profile docs

In that state, Bobbin must not claim upgrade-readiness as green.

Ownership Boundary​

Bobbin owns the inventory and consistency checks for its runtime family contract. It does not own external runtime projection logic or deployment materialization in other repos.

AGPLv3. See ../LICENSE (LICENSE).

Learn more at helpifyr.com.