Skip to main content

INTEGRATIONS

Documentation Map​

INTEGRATIONS

Internal Helpifyr Integrations​

jhf-shuttle-core​

  • Direction: bidirectional logical integration
  • Type: repository-intake
  • Surface: n8n_expert/, python -m n8n_expert, fabric-manifest.json
  • Auth: none
  • Stability: stable
  • Versioning: follows pyproject.toml, fabric-manifest.json, and documented contract/version files
  • Owner: jhf-shuttle repository, bundled jhf-shuttle Core-Subkomponente

Implemented:

  • jhf-shuttle bundles the reusable core package and exposes it through repo-owned CLI, API, and artifact paths.

Planned:

  • no separate first-class Fabric identity for the bundled core

External Integrations​

n8n-rest-api​

  • Direction: outgoing
  • Type: provider-contract
  • Surface: GET /api/v1/health, GET /api/v1/status, workflow and upgrade paths backed by live n8n calls
  • Auth: n8n API key
  • Stability: stable
  • Versioning: governed by upstream n8n version behavior plus local upgrade/version docs
  • Owner: upstream n8n runtime as provider, jhf-shuttle as consumer

Implemented:

  • live workflow, credential, execution, and health operations

upstream-release-sources​

  • Direction: outgoing read-only
  • Type: provider-contract
  • Surface: upstream release HTTP/tag fetches consumed by catalog and upgrade scripts
  • Auth: none for public sources
  • Stability: stable
  • Versioning: additive over upstream release metadata and local release-matrix rules
  • Owner: upstream release providers, jhf-shuttle as consumer

Implemented:

  • version-gap, release-matrix, and upgrade-intelligence inputs

optional-mission-control-api​

  • Direction: incoming
  • Type: execution-contract
  • Surface: /api/v1/health, /api/v1/status, /api/v1/openapi.json, selected read-only workflow/upgrade/catalog paths
  • Auth: optional bearer token via jhf_shuttle_API_TOKEN
  • Stability: partial
  • Versioning: additive over docs/MISSION_CONTROL_VERSIONING.md and openapi.json
  • Owner: jhf-shuttle

Implemented:

  • read-first status, health, workflow, catalog, upstream, and upgrade surfaces

Planned:

  • no new endpoint is required for the current Fabric baseline

jhf-dobby-optional-a2a-learning-input​

  • Direction: incoming read-only
  • Type: evidence-contract
  • Surface: GET /api/v1/evidence/a2a-handoffs/latest
  • Auth: optional bearer token via jhf_shuttle_API_TOKEN
  • Stability: experimental
  • Versioning: canonical contract jhf-shuttle.a2a-handoff-evidence.v1 with contract_version=1.0.0
  • Owner: jhf-shuttle publishes evidence read-only, jhf-dobby consumes optionally

Implemented:

  • canonical read-only a2a/handoff evidence payload with tenancy, correlation, and lineage fields
  • Dobby can consume this surface as optional learning input without gaining any write/control path
  • explicit degraded semantics when evidence is absent or unreadable (status=degraded + degraded_reason)
  • contract details: docs/A2A_HANDOFF_EVIDENCE_CONTRACT.md

Not allowed:

  • treating absence of Shuttle evidence as hard failure for Dobby runtime
  • using this integration as mutation/control surface for Shuttle state

jhf-spool-paddle-webhook-handoff​

  • Direction: outgoing operator-verify + cross-repo handoff
  • Type: webhook-contract
  • Surface: Spool Paddle ingress path /v1/webhooks/paddle
  • Auth: provider-side Paddle signature (owned by jhf-spool + Paddle tenant admin)
  • Stability: external-blocked (provider and billing-owner owned rollout)
  • Versioning: endpoint/path is owned by jhf-spool; jhf-shuttle only consumes read-only evidence
  • Owner: jhf-spool runtime for endpoint behavior, jhf-shuttle for handoff/verification evidence

Implemented from jhf-shuttle side:

  • operator verify commands and evidence capture for live webhook path reachability
  • explicit separation between:
    • path reachability/redirect behavior (Shuttle/operator-owned evidence)
    • provider credential and signing-secret correctness (external owner responsibility)
  • documented retry/error expectation for shuttle-owned upstream senders:
    • 2xx: accepted, no retry
    • 307/308: treat as endpoint canonicalization signal, switch sender to canonical HTTPS endpoint (do not keep looping on non-canonical HTTP URL)
    • 429/5xx or network timeout: bounded exponential retry with jitter
    • 4xx (except 429): treat as terminal contract/config error and escalate

External dependency (not owned by jhf-shuttle):

  • Paddle tenant-side live webhook registration + signing-secret rotation policy
  • billing product-owner confirmation of live price-map and settlement policy

repo-version-sources​

  • Direction: outgoing read-only
  • Type: repo-read
  • Surface: pyproject.toml, fabric-manifest.json, CHANGELOG.md
  • Auth: repository read access
  • Stability: stable
  • Versioning: these files are the documented version source; no dedicated runtime /version surface exists
  • Owner: jhf-shuttle

Implemented:

  • version can be resolved from existing repository artifacts

Event Contracts​

operator-event-log​

  • Direction: bidirectional logical integration
  • Type: execution-contract
  • Surface: logs/events.jsonl
  • Auth: filesystem access
  • Stability: stable
  • Versioning: additive file contract with repo-owned event schema expectations
  • Owner: jhf-shuttle

Implemented:

  • append-only persisted operator events

optional-event-webhook-sink​

  • Direction: outgoing
  • Type: webhook
  • Surface: jhf_shuttle_EVENT_WEBHOOK
  • Auth: target-specific webhook auth
  • Stability: partial
  • Versioning: best-effort event forwarding over current event payload shape
  • Owner: jhf-shuttle as sender, target system as receiver

Implemented:

  • optional best-effort event forwarding

Planned:

  • no Fabric-specific event subscription contract is implemented yet

mailbox-jetstream-delivery​

  • Direction: bidirectional logical integration
  • Type: message-bus
  • Surface: mailbox adapter /publish, /healthz, configured NATS/JetStream stream and subjects
  • Host-facing probe surface (implemented default): http://<host>:58805/healthz via MAILBOX_ADAPTER_HEALTH_HOST_PORT
  • Shuttle-owned OpenClaw evidence-forwarding surface: docs/OPENCLAW_HIGH_SEVERITY_EVIDENCE_FORWARDING_CONTRACT.md
  • Shuttle-owned host probe/publish path for optional OpenClaw evidence relay: http://<host>:58815/healthz and POST http://<host>:58815/publish
  • OpenClaw-plus canonical endpoint contract: OPENCLAW_PLUS_SHUTTLE_URL=http://<internal-runtime-redacted>:58805/healthz
  • Auth: optional publish token plus environment-specific NATS auth
  • Stability: partial
  • Versioning: product-local callback and delivery contract; no Fabric version contract
  • Owner: jhf-shuttle operator runtime

Implemented:

  • durable publish, session-serialized delivery, callback/result paths
  • stable owner contract for optional jhf-openclaw-env high-severity evidence forwarding on the Shuttle stack

Planned:

  • deeper semantics alignment only; no new orchestration model

MCP Integration​

mcp-status​

  • Direction: incoming
  • Type: mcp
  • Surface: no standalone MCP endpoint in this repository
  • Auth: n/a
  • Stability: planned
  • Versioning: n/a
  • Owner: n/a

Implemented:

  • none

Planned:

  • if Fabric ever consumes MCP-shaped metadata here, it must be layered on existing repo contracts rather than a new runtime invented for this repository

Planned Connections​

Future jhf-fabric connection​

jhf-fabric-read-contract​

  • Direction: outgoing read-only
  • Type: compatibility-shim
  • Surface: fabric-manifest.json, docs/FABRIC_TOOL_PROFILE.md, /api/v1/status, docs/CAPABILITIES.md
  • Auth: repository read access plus optional API bearer token
  • Stability: planned
  • Versioning: additive over current manifest and documented contract/version files
  • Owner: jhf-shuttle as producer, jhf-fabric as reader

Implemented:

  • Fabric can already read manifest, docs, and selected read-first API surfaces.
  • Live deployment contract route is provided by jhf-fabric API deployment contracts; exact path and unauthenticated response code are deployment-owned and must be verified in the target runtime.
  • jhf-fabric-platform-n8n (:35678) is a separate runtime and is not the deployment-endpoint-contract API surface.

Planned:

  • registration/discovery, topology hints, and policy hints remain documentation-only gaps

jhf-fabric-combination-profiles​

  • Direction: outgoing read-only
  • Type: compatibility-shim
  • Surface: /api/v1/combinations/profiles (Fabric-owned runtime surface)
  • Auth: Fabric deployment specific (this repository does not define auth semantics for that route)
  • Stability: stable (Fabric-owned truth contract)
  • Versioning: follows Fabric combination profile contract family and downstream read compatibility
  • Owner: JaddaHelpifyr/helpifyr-fabric as truth owner, jhf-shuttle as read-only consumer

Implemented:

  • jhf-shuttle consumes Fabric combination truth read-only and does not define local bundle/detection truth.
  • Supported profile keys for Shuttle preparation:
    • fabric-warp-shuttle
    • fabric-shuttle-bobbin
    • fabric-warp-shuttle-bobbin
    • shuttle-standalone-openclaw
  • Mismatch/stale posture must remain explicit when Fabric readback is unavailable or conflicting.

Not allowed:

  • deriving active bundle truth from local dashboard, workflow, or runtime heuristics
  • opening a second local truth family for bundle or detection semantics

jhf-fabric-contract-governance​

  • Direction: outgoing read-only
  • Type: compatibility-shim
  • Surface:
    • GET /api/v1/contracts/jarvis
    • GET /api/v1/contracts/jarvis/readiness
    • GET /api/v1/contracts/registry
    • GET /api/v1/contracts/families
    • GET /api/v1/contracts/schemas
    • GET /api/v1/contracts/matrix
  • Auth: Fabric deployment specific (this repository does not define auth semantics for these routes)
  • Stability: stable (Fabric-owned truth contract)
  • Versioning: accepted versions are read from Fabric matrix and mirrored as explicit consumer declaration in fabric-manifest.json
  • Owner: JaddaHelpifyr/helpifyr-fabric as truth owner, jhf-shuttle as read-only consumer

Implemented:

  • declared Fabric contract families and accepted versions in fabric-manifest.json:
    • helpifyr-schema-governance-docs-standard -> 1.0.0
    • helpifyr-schema-governance-wiki-governance -> 1.0.0
    • helpifyr-schema-governance-asyncapi-catalog -> 1.0.0
    • helpifyr-schema-governance-event-catalog -> 1.0.0
    • helpifyr-schema-governance-admission-governance -> 1.0.0
    • helpifyr-identity-surface-access-projection -> 1.0.0
    • helpifyr-identity-surface-admission-truth -> 1.0.0
    • helpifyr-identity-surface-lifecycle-truth -> 1.0.0
    • trace-envelope.v1 -> 1.0.0
    • step-envelope.v1 -> 1.0.0
    • guardrail-decision.v1 -> 1.0.0
    • skill-lifecycle.v1 -> 1.0.0
    • a2a-handoff.v1 -> 1.0.0
    • helpifyr-schema-governance-jarvis-adoption-status -> 1.0.0
  • local shadow-truth guardrails:
    • no local schema family definitions for these Fabric-owned families
    • no local accepted-version override
    • no local JARVIS lifecycle/closure shadow truth
    • readiness evidence must read back from the six canonical JARVIS/Fabric surfaces
  • verify/readiness path:
    • scripts/run_fabric_contract_governance_checks.py

Not allowed:

  • defining local canonical versions for these families independent from Fabric matrix truth
  • treating repo-local docs or local lifecycle notes as replacement for Fabric JARVIS/readiness truth

jhf-fabric-n8n-projection-admission-consumer​

  • Direction: outgoing read-only + bounded local execution
  • Type: compatibility-shim
  • Surface:
    • GET /api/v1/contracts/admission-governance
    • GET /api/v1/contracts/matrix
    • local artifact contracts/n8n_projection_contract.v1.json
  • Auth: Fabric deployment specific (this repository does not define auth semantics for these routes)
  • Stability: pilot
  • Versioning: local projection contract key jhf-shuttle.n8n-projection.v1 and Fabric admission-governance family compatibility
  • Owner: JaddaHelpifyr/helpifyr-fabric for decision truth, jhf-shuttle for bounded executor behavior

Implemented:

  • explicit consumer/executor boundary for projection execution
  • explicit projection operations, revocation handling, and orphan handling
  • local execution rejects any operation that is not explicitly allowed by Fabric decision payload

Not allowed:

  • local semantic reinterpretation of allow/deny/revoke/orphan decisions
  • local override or escalation of Fabric-declared operation allow-list

jhf-fabric-n8n-application-verdict-consumer​

  • Direction: outgoing read-only + bounded local execution
  • Type: compatibility-shim
  • Surface:
    • GET /api/v1/contracts/admission-governance
    • GET /api/v1/contracts/matrix
    • local artifact contracts/n8n_application_contract.v1.json
  • Auth: Fabric deployment specific (this repository does not define auth semantics for these routes)
  • Stability: pilot
  • Versioning: local application contract key jhf-shuttle.n8n-application.v1 and Fabric admission-governance family compatibility
  • Owner: JaddaHelpifyr/helpifyr-fabric for verdict truth, jhf-shuttle for bounded disable/delete/revoke execution

Implemented:

  • explicit disable/delete/revoke application contract for the n8n lane
  • explicit residual permissions diagnosis + surfacing in local evaluation output
  • executor blocks any operation not explicitly allowed by Fabric verdict payload

Not allowed:

  • local verdict override or semantic reinterpretation
  • local suppression of residual permission findings

Read-First Boundary​

  • Fabric may read manifest, docs, selected read-only API paths, and repo/file artifacts.
  • Current verify path is read-first only.
  • No write-back, workflow mutation, mailbox publish, or policy-file mutation is implemented for Fabric.

Not Allowed​

  • treating bundled jhf-shuttle as a second equal Fabric registration from this repository
  • inferring a dedicated /readyz, /version, /metrics, or topology endpoint that the repository does not actually expose
  • using Fabric as a control plane for workflow mutation, mailbox publish, or policy-file writes

Standalone Versus Integrated Contract View​

Contract AreaStandalone (implemented)Integrated (implemented)Integrated (planned)
execution ownershiptool-local CLI/API/compose pathsread-first metadata/status consumption onlyFabric registration/discovery contract
secret and credential sourceoperator env/env-file (N8N_API_KEY, optional API token, optional publish token); canonical source path for self-stack is contract-bound in contracts/n8n_api_key_source_contract.v1.jsonno Fabric secret injection path implementedexplicit shared credential handoff contract; consumer materialization in jhf-openclaw-env/jhf-deployment must follow source contract (refs: jhf-openclaw-env#174, jhf-deployment#249)
shared servicesoptional local NATS/mailbox pathnone attached through Fabric contracts yetbounded shared-service attachment once HF-047/050 contracts stabilize
shared Postgresnot used as shared Fabric servicenoneoptional metadata-only path if approved
migrate standalone to integratedmanual/operator-controlledno automatic adoption runtimeadopt-first protocol alignment when contract is finalized

Verification Surface Contract​

Current bounded verify surfaces used across both modes:

  • scripts/run_mission_control_checks.py
  • scripts/run_upgrade_freshness_checks.py
  • scripts/run_release_matrix_checks.py
  • scripts/run_final_release_hardening.py

No synthetic runtime endpoints are added only for contract compliance.

AGPLv3. Learn more at helpifyr.com.