+
+
← Home
+
Platform Capabilities
+
IHF v0.2 — GAAF 3.68 Strong — 12 phases complete
+
+
+ {-- Phase map --}
+
+ 12-Phase Capability Map
+
+ {phaseRow "1" "Core Domain Model" "Hubs, Widgets, WidgetVersions, InteractionEvents (append-only), Annotations, ViewContexts, CapabilityReferences. Widget envelope helper injects stable widget-id attributes."}
+ {phaseRow "2" "Requirement Candidates" "Triage lifecycle, duplicate detection, policy sensitivity routing, reviewer assignment, promotion to Requirement."}
+ {phaseRow "3" "Decision Records" "Requirement → DecisionRecord chain with policy references, implementation change references, and governance status."}
+ {phaseRow "4" "Deployment & Outcomes" "DeploymentRecord, OutcomeSignal (append-only), ChangeEvaluation. Outcome feedback closes the loop to DecisionRecords."}
+ {phaseRow "5" "Agent-Assisted Distillation" "AI agents (Anthropic API) draft Requirements from widget clusters, route via configurable model selection. AgentProposals with confidence annotations."}
+ {phaseRow "6" "Cross-Framework UI Adaptation" "EnvelopeEmissionContracts, InteractionReportingContracts, WidgetAdapterSpecs. Adapts widgets across framework boundaries."}
+ {phaseRow "7" "Advanced Observability" "FrictionScores, BottleneckRecords, HubHealthSnapshots, CrossHubPropagation detection. Heatmaps and operational review board."}
+ {phaseRow "8" "Federated Hub Maturity" "WidgetOwnerships, HubRoutingRules, FederatedPolicyOverlays, StewardshipRoles, ArchiveRecords with LineageInspector."}
+ {phaseRow "9" "External API Surface" "REST v1 + v2, JWT auth, OpenAPI 3.1, TypeScript + Python SDKs, WebhookSubscriptions, per-consumer ApiKeys, ApiDashboard."}
+ {phaseRow "10" "Hub Registry & Widget Marketplace" "WidgetPatterns with versioned adoption, GovernanceTemplates, HubRegistry, Marketplace dashboard. Phase 10 API v2 endpoints."}
+ {phaseRow "11" "Advanced AI Federation" "AgentRegistrations, ModelRoutingPolicies, AgentDelegations (tree), CollectiveProposals, AiGovernancePolicies, AgentPerformanceRecords."}
+ {phaseRow "12" "Platform Memory & Continuous Learning" "OutcomeCorrelations, PatternPerformanceRecords, AdaptiveThresholdConfigs, InstitutionalKnowledgeBase (GIN FTS), LearningInsights, retroactive lineage enrichment."}
+
+
+
+ {-- GAAF scorecard --}
+
+ GAAF-2026 Scorecard
+
+ {scoreCard "Core Architecture" "3.9" "Append-only invariants, type registry, FK discipline"}
+ {scoreCard "Functional Completeness" "3.8" "All 12 phases implemented with full controller+view coverage"}
+ {scoreCard "Observability" "3.5" "Friction heatmaps, health snapshots, lineage inspector"}
+ {scoreCard "Overall" "3.68" "Strong — GAAF 2026 threshold for production readiness"}
+
+
+
+ {-- API surface --}
+
+ API Surface
+
+
+
+
+ | Version |
+ Endpoints |
+ Auth |
+
+
+
+
+ | v1 |
+ POST /api/v1/interaction-events |
+ None (legacy write path) |
+
+
+ | v2 |
+ Widgets, Events, Annotations, Candidates, Decisions, Deployments, Signals, Registries, Patterns, Learning |
+ JWT Bearer |
+
+
+ | v2 spec |
+ GET /api/v2/openapi.json · /api/v2/openapi.yaml · /api/v2/docs |
+ None (public) |
+
+
+
+
+
+
+ {-- Learning loop --}
+
+ The Learning Loop
+
+ Phase 12 closes the full learning loop. The system continuously improves routing
+ and triage thresholds based on observed outcomes:
+
+
+ Widget → Annotation → RequirementCandidate → Requirement
+ → DecisionRecord → DeploymentRecord → OutcomeSignal
+ → OutcomeCorrelation / PatternPerformanceRecord
+ → InstitutionalKnowledgeEntry → AdaptiveThresholdConfig
+ → improved routing + triage (loop closed)
+
+
+
+ {-- Type registry --}
+
+ Type Registry System
+
+ GAAF Rule 1: all type discriminator columns reference a registry table.
+ New hub-owned types must be registered before use (GAAF Rule 2).
+
+
+
widget_type_registry — hub-owned widget types
+
event_type_registry — interaction event types
+
annotation_category_registry — annotation categories
+
policy_scope_registry — policy sensitivity scopes
+
+
+
+
+
+ |]
+ where
+ phaseRow num title_ desc = [hsx|
+
+
+
← Home
+
Domain Hub Extension Guide
+
+ How to build and register a domain hub extension: HubCapabilityManifest,
+ type registry entries, hub-owned widget types, and hub-scoped controllers.
+
+
+
+ {-- Overview --}
+
+ Overview
+
+ inter-hub provides the governance substrate. Domain hubs (dev-hub, ops-hub, fin-hub, sec-hub)
+ extend it by registering their own capability manifests and type discriminators.
+ This keeps core tables stable while allowing domain-specific specialisation.
+
+
+ GAAF Rule 2: New hub-owned types must be declared in the hub's
+ HubCapabilityManifest before use.
+ Register via the Extensions admin UI before creating any hub-owned widget types.
+
+
+
+ {-- Step 1: Create a Hub --}
+
+ {stepBadge "1"} Create a Hub
+
+ Navigate to Management UI → Hubs
+ and create a new hub. Each hub has a slug
+ that will prefix its owned types (e.g. dev.code-review).
+
+
+
+ {-- Step 2: Register a HubCapabilityManifest --}
+
+ {stepBadge "2"} Register a HubCapabilityManifest
+
+ A HubCapabilityManifest is the DB-side contract for a domain hub.
+ Go to Extensions
+ and create a manifest for your hub. Set status to active.
+
+
+ The manifest includes: hubId, manifestVersion,
+ capabilitySchema (JSON), and an optional apiEndpointBase.
+ It is the anchor point for per-consumer API keys in Phase 9.
+
+
+
+ {-- Step 3: Register type discriminators --}
+
+ {stepBadge "3"} Register Type Discriminators
+
+ Before creating widgets of a new type, register the type in the appropriate registry.
+ Go to Registries:
+
+
+ - Widget Type Registry — new widget types your hub will own
+ - Event Type Registry — custom interaction event types
+ - Annotation Category Registry — custom annotation categories
+ - Policy Scope Registry — custom policy sensitivity scopes
+
+
+ Set owner_hub_id to your hub. Once registered, your hub-scoped code
+ can create widgets of that type and the type will appear in the marketplace.
+
+
+
+ {-- Step 4: Create widgets --}
+
+ {stepBadge "4"} Create Widgets
+
+ With the type registered, create widgets via the
+ Widgets page
+ or the API:
+
+
+ POST /api/v2/widgets
+ {"{"} "name": "PR Review Widget",
+ "widgetType": "dev.code-review",
+ "hubId": "...",
+ "viewContext": "pull-request-sidebar" {"}"}
+
+
+
+ {-- Step 5: Publish a widget pattern --}
+
+ {stepBadge "5"} Publish a Widget Pattern (optional)
+
+ If your widget design is reusable, publish it to the
+ Widget Marketplace.
+ Other hubs can adopt it and pin to specific versions. Patterns support
+ semantic versioning and adoption tracking.
+
+
+
+ {-- Step 6: AI agent integration --}
+
+ {stepBadge "6"} Connect an AI Agent (Phase 11)
+
+ Register an AgentRegistration
+ for your hub, then create a
+ ModelRoutingPolicy
+ to route task types to specific models or agents.
+ Agents can draft Requirements, propose governance decisions, and participate in
+ CollectiveProposals.
+
+
+
+ {-- GAAF rules reminder --}
+
+ GAAF Architecture Rules (Summary)
+
+ {ruleBox "1" "Type discriminator columns must reference a registry table or carry a CHECK constraint. No bare TEXT for new type discriminators."}
+ {ruleBox "2" "New hub-owned types must be declared in the hub's HubCapabilityManifest before use."}
+ {ruleBox "3" "Core tables (widgets, interaction_events, annotations, hubs) must not have new columns without updating /contracts/core/."}
+ {ruleBox "4" "Append-only invariant on interaction_events and outcome_signals is permanent. Never bypass those triggers."}
+
+
+
+
+
+ |]
+ where
+ stepBadge n = [hsx|
+
+
+ {-- Hero --}
+
+
inter-hub
+
+ Reference implementation of the Interaction Hub Framework (IHF)
+
+
+ A governed, observable interaction substrate for hub-based AI-enabled software
+ systems. Every UI element is a governed artifact with a full traceability chain
+ from rendered widget to observed outcome.
+
+
+
+
+ {-- Traceability chain --}
+
+
Full Traceability Chain
+
+
+ {chainLink "Widget" "indigo"}
+ {arrow}
+ {chainLink "InteractionEvent" "blue"}
+ {chainLink "Annotation" "blue"}
+ {arrow}
+ {chainLink "RequirementCandidate" "violet"}
+ {arrow}
+ {chainLink "Requirement" "purple"}
+ {arrow}
+ {chainLink "DecisionRecord" "fuchsia"}
+ {arrow}
+ {chainLink "DeploymentRecord" "rose"}
+ {arrow}
+ {chainLink "OutcomeSignal" "orange"}
+ {arrow}
+ {chainLink "Learning" "emerald"}
+
+
+ Append-only event log · PostgreSQL-enforced invariants · Full lineage inspector
+
+
+
+
+ {-- Key capabilities grid --}
+
+
Key Capabilities
+
+ {capCard "Governed Widgets"
+ "Every UI element carries a stable widget-id, version history, and owner hub. Type discriminators reference a registry — no bare TEXT."
+ "indigo"}
+ {capCard "AI Agent Federation"
+ "Multi-agent routing, delegation trees, collective proposals, model selection policies, and AI governance overlays. Phase 11 complete."
+ "violet"}
+ {capCard "Continuous Learning"
+ "Outcome correlation engine, pattern performance ranking, adaptive friction thresholds, and institutional knowledge base with full-text search. Phase 12 complete."
+ "emerald"}
+ {capCard "External API Surface"
+ "REST API v2 with JWT auth, OpenAPI 3.1 spec, TypeScript + Python SDKs, webhook subscriptions, and per-consumer API keys."
+ "blue"}
+ {capCard "Hub Federation"
+ "Cross-hub propagation detection, routing rules, stewardship roles, federated policy overlays, and GAAF compliance governance."
+ "orange"}
+ {capCard "Widget Marketplace"
+ "Published widget patterns with versioned adoption, governance template library, and hub registry for domain extension discovery."
+ "rose"}
+
+
+
+ {-- Status bar --}
+
+
+
+
12 / 12
+
IHF Phases Complete
+
+
+
3.68
+
GAAF Score (Strong)
+
+
+
+
IHF v0.2
+
Specification
+
+
+
+
+ {-- Nav to docs --}
+
+
+ |]
+ where
+ chainLink label color = [hsx|
+
+
+
← Home
+
Developer Tutorial
+
How IHF works from a developer perspective — widget lifecycle, governance flow, outcome loop.
+
+
+ {-- Step 1: Hubs and Widgets --}
+
+ {stepBadge "1"} Hubs and Widgets
+
+ A Hub is a bounded domain of responsibility (e.g. Dev Hub, Ops Hub, Fin Hub).
+ Hubs own Widgets — the smallest semantically governable interaction unit.
+ Each widget has a widget_id (stable UUID),
+ a widget_type (from the registry),
+ and a version history.
+
+
+
-- Every rendered widget wraps its HSX in widgetEnvelope
+ widgetEnvelope widgetId viewContext [hsx|...|]
+
+
+ The envelope injects data-widget-id and data-view-context attributes,
+ enabling client-side event capture without coupling to implementation.
+
+
+
+ {-- Step 2: Interaction Events --}
+
+ {stepBadge "2"} Interaction Events
+
+ When a user or agent interacts with a widget, an InteractionEvent is recorded —
+ clicked, viewed, submitted, dismissed, etc. Events are append-only:
+ a PostgreSQL trigger prevents UPDATE and DELETE on the interaction_events table.
+
+
+ POST /api/v1/interaction-events
+ POST /api/v2/interaction-events
+
+
+ Events flow into Annotations (human/agent commentary with category)
+ and eventually surface as RequirementCandidates.
+
+
+
+ {-- Step 3: Governance flow --}
+
+ {stepBadge "3"} Governance Flow
+
+ RequirementCandidates go through a triage lifecycle: open → triaged → reviewed → promoted or dismissed.
+ Phase 5 agents can draft Requirements from widget clusters using the Anthropic API.
+ Promoted candidates become Requirements, which are linked to DecisionRecords.
+
+
+ {flowBox "RequirementCandidate" "open · triaged · reviewed"}
+ {arrow_}
+ {flowBox "Requirement" "linked to Decision"}
+ {arrow_}
+ {flowBox "DecisionRecord" "policy refs · impl refs"}
+
+
+
+ {-- Step 4: Deployment and outcomes --}
+
+ {stepBadge "4"} Deployment and Outcomes
+
+ A DecisionRecord links to a DeploymentRecord. After deployment,
+ OutcomeSignals are recorded (also append-only) and evaluated via
+ ChangeEvaluations. Outcome feedback flows back to the DecisionRecord,
+ closing the governance loop.
+
+
+
+ {-- Step 5: Learning --}
+
+ {stepBadge "5"} Continuous Learning (Phase 12)
+
+ Phase 12 layers a learning engine on top of the governance loop:
+
+
+ - OutcomeCorrelations — compute correlation scores between widget patterns and outcomes
+ - PatternPerformanceRecords — rank widget patterns by observed outcome quality
+ - AdaptiveThresholdConfigs — auto-calibrate friction and triage thresholds per hub
+ - InstitutionalKnowledgeBase — GIN full-text search over all governance decisions
+ - LearningInsights — actionable recommendations surfaced in the Learning Dashboard
+
+
+
+ {-- Step 6: Hub federation --}
+
+ {stepBadge "6"} Hub Federation
+
+ Multiple hubs interact via routing rules, stewardship roles, and federated policy overlays.
+ Cross-hub propagation patterns are detected automatically. The GAAF compliance layer
+ enforces type registry discipline and contract stability across hub boundaries.
+
+
+
+
+
+ |]
+ where
+ stepBadge n = [hsx|
+