Skip to main content

Helpifyr OSS Inventory Version Truth

Documentation Map​

Helpifyr OSS Inventory Version Truth

This document defines the repo-owned OSS inventory and version-truth verification posture for Fabric-owned platform OSS families.

The canonical machine-readable sources remain:

  • contracts/platform/helpifyr_stack_module_identity_v1.json
  • contracts/platform/platform_version_truth.json
  • contracts/platform/platform_projection_catalog.json
  • contracts/platform/stack_tool_oss_inventory_directory.json
  • contracts/platform/platform_oss_upgrade_adoption_roles_v1.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
  • GET /api/v1/platform/version-truth
  • GET /api/v1/platform/projection-catalog
  • GET /api/v1/platform/tool-oss-inventory-directory

The companion operator-facing reference for this verify path lives in:

  • docs/OSS_INVENTORY_VERSION_TRUTH.md

Scope​

This inventory and its upgrade companions are fail-closed for the following platform families:

  • grafana-oss
  • prometheus-oss
  • wikijs-oss
  • wikijs-proxy-nginx
  • dapr-runtime
  • shared-n8n
  • shared-nats
  • postgres-oss
  • otel-collector

Any missing family, version drift, :latest image tag, or doc/contract mismatch is a verification failure.

Verify Path (Fail-Closed)​

  1. python scripts/verify_platform_version_truth.py --check
  2. python scripts/verify_platform_oss_upgrade_contracts.py --check
  3. python scripts/verify_platform_oss_upgrade_adoption_contract.py --check
  4. python scripts/verify_stack_module_identity_contract.py --check
  5. python scripts/verify_oss_inventory_version_truth.py --check
  6. python scripts/verify_stack_tool_oss_inventory_directory.py --workspace-root C:/CodexTest --output contracts/platform/stack_tool_oss_inventory_directory.json
  7. bash scripts/testing/run_beam_stack_oss_inventory_wave.sh

If any check fails, the OSS inventory truth is considered not-ready and must not be treated as green.

Upgrade Readiness Rule​

  • Upgrade planning must consume Fabric-owned version truth directly.
  • Upgrade planning must also consume the explicit Fabric-owned target-version, compatibility, rollback, and evidence companions directly.
  • Upgrade planning must classify future modules through the Fabric-owned owner-versus-consumer adoption contract directly.
  • Upgrade planning must only consume tool-level directory entries for modules admitted by helpifyr_stack_module_identity_v1.json.
  • Downstream consumers must not infer OSS version truth from scattered compose files or stale docs.
  • Floating posture is only allowed where explicitly declared in platform_projection_catalog.json.

Admission Rule For New Tools​

Fabric admission is fail-closed for onboarding:

  • contracts/admission/admission_dry_run_input.schema.json
  • contracts/admission/future_tool_admission_governance.json
  • POST /api/v1/tools/admission/dry-run
  • GET /api/v1/contracts/admission-governance

Every new tool that wants to connect to Fabric must provide in docs_metadata:

  • oss_inventory_doc_path = docs/OSS_INVENTORY.md
  • oss_inventory_verify_entrypoint = python scripts/verify_oss_inventory_version_truth.py --check

Missing or mismatched values block admission.

Evidence​

Post verification evidence should be attached to:

  • JaddaHelpifyr/helpifyr-fabric#295

License​