What the Orchestrator Does
The Causal-HTG module sits between the Heterogeneous Graph Transformer (HGT) and the ArcaQ causal governance pipeline. It listens to platform events, retrains HGT priors when the knowledge graph changes, triggers causal discovery when data is sufficient, and routes every candidate through a transparent promotion funnel.
Event Listeners
React to KG triple changes, ontology updates, data sufficiency, and SME decisions via Redis pub/sub.
arcaq.events.{tenant}.{type}Auto-HGT Triggers
Debounce graph changes and schedule HGT retraining. Generate scored link-prediction candidates.
hgt.model.retrainedAuto-Causal Triggers
Run PC/GES/FCI discovery when datasets cross sample thresholds, seeding from high-confidence HGT candidates.
causal.discovery.completedP1 / P2 / P3 Promotion Funnel
Candidates are tiered by confidence and review state. Only P2 and P1 enter the causal quarantine or production signal path; P3 remains in the detection backlog.
Backlog
- HGT score < 0.70
- Causal confidence < 0.60
- Visible in dashboard, not routed
Quarantine / Review Queue
- HGT score ≥ 0.70
- Causal confidence ≥ 0.60
- SME assigned, SLA countdown starts
Production Graph
- SME approved + SHACL valid
- HGT consensus ≥ 0.85
- Promoted to certified named graph
Causal Quarantine & SME Routing
Discovered causal edges enter the existing arcaq-causal quarantine
workflow. The orchestrator adds SLA breach detection, auto-rejection of overdue
items, and domain-aware SME assignment using the ArcaQ SME Management API.
Domain Detection
Map edge concepts to expertise domains using ontology labels and keyword heuristics.
Workload-Aware Routing
Select the best available SME by primary expertise, seniority, quality score, and active review load.
SLA Governance
72-hour review window. Auto-reject or escalate on breach. Notifications via the ArcaQ event bus.
Certified Causal Querying Shipped
The querying layer over certified causal knowledge is live. Multi-hop RDF traversal answers why and what-if questions exclusively over the certified named graph — quarantined or invalidated knowledge is never traversed. SHACL validation is fail-closed: an edge that fails certification cannot enter the production graph, and counterfactual confidence drops to zero when no explicit downstream effect is found — the system says "I don't know" instead of guessing.
Why & What-If Queries
Certified multi-hop RDF traversal traces cause chains forward and backward — explain a decision, or simulate a change across the graph.
causal.why / causal.what_ifFail-Closed SHACL Certification
Every candidate edge passes SHACL validation before certification. Failures quarantine the edge — they never reach the production graph.
shacl.validate → certifyProvenance & Invalidation
Quarantine persists workflow state, discovery time and provenance. Overturned challenge targets are invalidated with prov:wasInvalidatedBy — auditable end to end.
prov:wasInvalidatedByPlanned API Endpoints
Read-only status, tier dashboards, event replay, and admin triggers. Normal flow remains event-driven.
GET /api/v1/causal-htg/statusOrchestrator health and last processed event.GET /api/v1/causal-htg/tiers/{tenant_id}P1/P2/P3 counts and top candidates.GET /api/v1/causal-htg/events/{tenant_id}Recent processed events with idempotent replay.POST /api/v1/causal-htg/trigger/hgtAdmin: force HGT retrain for tenant.POST /api/v1/causal-htg/trigger/causalAdmin: force causal discovery for tenant.POST /api/v1/causal-htg/quarantine/promoteAdmin: batch SHACL promotion of approved edges.Integration Points
arcaq-gnn
HGT model training and link-prediction scoring via direct import or future HTTP service.
arcaq-causal
Discovery engine, quarantine workflow, SHACL validation, and named graph lifecycle.
arcaq-api
SME management, notification service, and proxy to causal review endpoints.