Zum Hauptinhalt springen

OSS Inventory

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/integrated_system_inventory_crosswalk_v1.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

The companion integrated-system reference for management-facing and architecture-facing software lists lives in:

  • docs/contracts/HELPIFYR_INTEGRATED_SYSTEM_INVENTORY_CROSSWALK.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.

Integrated System Companion​

The narrow Fabric-owned platform inventory above is intentionally not the same thing as the broader integrated software landscape used across the Helpifyr stack.

Management-facing, partner-facing, and architecture-facing software lists must consume the complementary integrated-system crosswalk instead of widening the platform-family list above.

The current crosswalk explicitly covers the following integrated system groups:

  • enterprise and business systems: Alfresco Community Edition, ERPNext / Frappe, Zammad, Keycloak, Plane
  • workspace and collaboration systems: Nextcloud Hub, Collabora Online, Stalwart Mail Server
  • voice and telephony systems: Asterisk
  • shared platform services: shared n8n, shared NATS, shared PostgreSQL, Dapr Runtime, Wiki.js
  • observability and delivery surfaces: Grafana OSS, Prometheus, Gitea
  • supporting runtime dependencies: Elasticsearch, ActiveMQ

The canonical machine-readable source for those broader software lists is:

  • contracts/platform/integrated_system_inventory_crosswalk_v1.json

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. python scripts/verify_integrated_system_inventory_crosswalk.py --workspace-root C:/CodexTest --output contracts/platform/integrated_system_inventory_crosswalk_v1.json
  8. 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.
  • Management- and architecture-facing software lists must consume the integrated-system crosswalk instead of widening the narrow stack-tool directory beyond its contract.
  • 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​