InteractionHubFramework *Inter* # Interaction Hub Framework (IHF) *Formal Specification with Phased Implementation Plan* **Version:** 0.2 **Status:** Draft Extension Specification **Supersedes:** `InteractionHubFrameworkSpecification_v0.1.md` **Purpose:** Extend the IHF beyond Phase 8 into external platform maturity — public API surface, consumer SDKs, hub marketplace, and advanced AI federation. --- ## 1. Definition The **Interaction Hub Framework (IHF)** is a platform framework for building **commentable, observable, governable, and evolvable user interaction systems**. It provides a stable core for: * addressing UI elements as governed platform assets * capturing user feedback and interaction signals in context * transforming observed friction and intent into structured requirements * connecting requirements to decisions, implementations, deployments, and outcomes * supporting multiple evolving UI technologies without losing semantic continuity * federating governance across hub boundaries in multi-team AI factory deployments The IHF is intended to serve as the **interaction substrate** of a hub-based AI factory, especially in environments where product development, operations, governance, finance, security, and AI-assisted workflows interact continuously. --- ## 2. Design Intent The framework is designed to support the following long-term properties: **Stable semantic core** UI technologies may change, but interaction semantics, traceability, and governance remain stable. **Antifragility** The system should improve through systematically captured friction, confusion, unmet expectations, and emergent user needs. **Observability by design** Interaction, feedback, and governance events are first-class operational signals. **Governance by design** Requirements, decisions, policy concerns, and implementation consequences remain linked and auditable. **Agent compatibility** AI agents should be able to inspect, interpret, propose, implement, review, and monitor changes within explicit boundaries. **Framework independence at the edge** Any UI technology that can emit the widget envelope is a first-class participant. The IHF does not mandate a particular frontend stack. **Platform composability** The IHF should be consumable by external systems, third-party tooling, and downstream hubs via stable, versioned contracts. Internal governance state must not be a closed silo. --- ## 3. Scope ### In Scope * Widget identity, lifecycle governance, and semantic addressability * Interaction event capture and contextual enrichment * Annotation and structured comment threads * Requirements distillation from raw feedback clusters * Governance ledger: decision records linked to requirements and implementations * Outcome observation and pre/post change comparison * AI-assisted distillation, bounded, attributable, reviewer-controlled * Cross-framework UI adapter protocol * Operational observability: friction scoring, bottleneck detection, health snapshots * Federated governance: ownership delegation, requirement routing, policy overlays, stewardship, archival * External API surface for third-party and inter-system consumption * Consumer SDKs for common platform integrations * Hub registry and marketplace for reusable widget and governance patterns * Advanced AI federation for multi-model, multi-agent governance workflows ### Out of Scope * A complete universal frontend framework or design system * Pixel-level visual design or CSS conventions * Full product management methodology * Replacement for DevOps observability tooling * Unrestricted autonomous AI decision-making on requirements * Mandatory single UI technology for all hub surfaces * General-purpose data warehouse or business intelligence platform --- ## 4. Core Concepts *(Unchanged from v0.1 §4 — see `InteractionHubFrameworkSpecification_v0.1.md`)* --- ## 5. Phased Implementation Plan The v0.1 specification defined Phases 0–8. Phases 0–7 are complete as reference implementation. Phase 8 (Federated Hub Maturity) is in progress. This v0.2 specification extends the plan with Phases 9–12. ### Phase 0 — Concept Foundation *(complete)* ### Phase 1 — Minimal Interaction Core *(complete)* ### Phase 2 — Structured Feedback and Triage *(complete)* ### Phase 3 — Governance and Decision Linkage *(complete)* ### Phase 4 — Outcome Observation and Antifragility Loop *(complete)* ### Phase 5 — Agent-Assisted Distillation and Suggestion *(complete)* ### Phase 6 — Cross-Framework UI Adaptation Layer *(complete)* ### Phase 7 — Advanced Observability and Operational Integration *(complete)* ### Phase 8 — Federated Hub Maturity *(in progress)* --- ## Phase 9 — External API Surface and Consumer SDKs ### Goal Make the IHF consumable by systems outside the reference IHP implementation. Phase 8 established federated governance within a single deployment. Phase 9 exposes that governance state as a stable, versioned, authenticated REST API and ships consumer SDKs that make integration a day's work rather than a project. ### GAAF Foundation Prerequisite > **IHUB-WP-0009 (GAAF Compliance Foundation) must be complete before Phase 9 > begins.** Phase 9 generates an OpenAPI 3.1 specification that documents all IHF API fields. Three of those fields — `widget_type`, `event_type`, and `category` — are type discriminators. If they are documented as arbitrary `string` values, the API contract is immediately incorrect: consumers will invent values that diverge from the IHF vocabulary, breaking cross-hub aggregation and federation. IHUB-WP-0009 establishes the four type registries that enumerate these fields. Phase 9 must read from those registries to generate correct `enum` arrays in the OpenAPI spec. Building Phase 9 first and retrofitting enums later is a breaking API change. **Specific GAAF dependencies for Phase 9 implementation:** 1. **Type registry enumerations in OpenAPI** — The spec generator must query `widget_type_registry`, `event_type_registry`, and `annotation_category_registry` to produce `enum` arrays for the corresponding fields. The generated spec must NOT document these as unconstrained `string`. 2. **ApiConsumer linked to HubCapabilityManifest** — A `domain` hub authenticating as an API consumer is identified by its active `HubCapabilityManifest`. The `ApiConsumer` record should carry a `hub_capability_manifest_id` FK (nullable — non-hub consumers such as third-party tools authenticate without a manifest). When a manifested consumer submits an event, the `event_type` is validated against both the global `event_type_registry` and the manifest's `declared_event_types`. 3. **OAuth scope alignment with registered vocabulary** — OAuth scopes should include hub-specific scope claims (`hub:{slug}:write`) that the token exchange validates against the hub's active manifest. A consumer without a manifest can only write framework-level event types; hub-owned types require the corresponding hub scope. 4. **Contract file reference** — The OpenAPI spec must reference `/contracts/functional/interaction-reporting-v1.md` as its human-readable companion. The generated spec is derived data; the contract file is authoritative intent. ### Scope * Versioned REST API (`/api/v2/`) for all core IHF artifact types * OpenAPI 3.1 specification generated from the live schema, with type registry enumerations for all type discriminator fields * Authentication: OAuth 2.0 client credentials flow (superseding per-hub Bearer tokens) * API key management UI for external consumers; domain hub consumers linked to their active HubCapabilityManifest * Consumer SDKs: TypeScript/Node, Python (type-safe enums generated from type registries) * Webhook delivery for interaction events, candidate creation, and decision records * API usage dashboard: request counts, error rates, consumer identity * Rate limiting and quota management per consumer ### Functional Capabilities * External systems can read widget registry, interaction events, annotations, requirement candidates, decisions, deployments, and outcome signals * External systems can submit interaction events and annotations via the API * Domain hub consumers submitting hub-owned event types require a matching active HubCapabilityManifest * Downstream hubs can subscribe to governance events via webhooks * SDK consumers get type-safe access to IHF contracts without reading the spec; SDK enum types are generated from the live type registries * API consumers are tracked, quotaed, and auditable ### Exit Criteria * All core IHF artifact types are readable via `/api/v2/` * Interaction events and annotations are writable via `/api/v2/` * OpenAPI spec is generated and accurate; `widget_type`, `event_type`, and `category` fields carry `enum` arrays derived from the type registries * TypeScript SDK and Python SDK published (as static files or packages); both export typed enums for widget types and event types * Webhook delivery confirmed for at least two event types * API usage dashboard renders correctly * OAuth token flow works end-to-end * Submission of an unregistered `event_type` returns HTTP 422 with a registry-referenced error message ### Data Artifacts Introduced `ApiConsumer`, `ApiKey`, `WebhookSubscription`, `WebhookDelivery` Schema additions: `api_consumers.hub_capability_manifest_id` (FK, nullable) --- ## Phase 10 — Hub Registry and Widget Marketplace ### Goal Enable reuse of proven widget patterns, governance templates, and hub configurations across deployments. Phase 9 made the IHF externally consumable. Phase 10 makes it composable: hubs and widgets can be discovered, rated, adopted, and evolved as shared platform assets. ### GAAF Foundation Integration > **Phase 10's Hub Registry IS the `HubCapabilityManifest` table, extended with > a public-facing discovery UI.** It is not a separate data store. IHUB-WP-0009 > must be complete before Phase 10 begins. The Hub Registry in Phase 10 is the public-facing projection of the capability manifests introduced in IHUB-WP-0009. Every registered hub already has an active `HubCapabilityManifest` that declares its widget types, event types, annotation categories, and policy vocabulary. Phase 10 adds the browsability, pattern publishing, and adoption mechanics on top of that existing foundation. **Specific GAAF integration points for Phase 10 implementation:** 1. **Hub Registry = active HubCapabilityManifest + HubHealthSnapshot** — The hub registry view is a join of `hub_capability_manifests` (status=active), `hub_health_snapshots` (latest), and `hubs`. No new hub registry table is required. The data already exists; Phase 10 adds the discovery UI. 2. **Widget patterns reference registered types** — A `WidgetPattern` record must declare a `widget_type` that exists in `widget_type_registry`. When publishing a pattern, if the `widget_type` is owned by another hub, the pattern is cross-hub and requires that hub's acknowledgement (or uses a framework-level type). This prevents patterns from encoding unregistered vocabulary. 3. **Pattern adoption triggers manifest update** — When a hub adopts a `WidgetPattern`, if the pattern's `widget_type` is not in the adopting hub's `declared_widget_types`, the adopting hub's manifest is updated to include it (in draft amendment mode). The hub operator must re-activate the amended manifest. This ensures the adopting hub's type vocabulary stays coherent with its actual widget usage. 4. **Governance templates reference registered categories** — A `GovernanceTemplate` for requirement categories must reference entries in `annotation_category_registry`. Template cloning adds any new categories to the cloning hub's manifest (draft amendment). 5. **Hub registry GAAF compliance score** — The hub registry should display each hub's GAAF compliance indicator: whether it has an active manifest, how many registered types it owns, and whether the architecture fitness functions report any violations. This makes GAAF compliance visible as a platform-level metric. ### Scope * Hub registry: a catalog of registered hubs built on `HubCapabilityManifest` + `HubHealthSnapshot`, with public metadata, declared vocabulary, and health summaries * Widget pattern library: reusable widget definitions tied to registered types from `widget_type_registry` * Governance template library: requirement distillation and decision templates, tied to registered annotation categories * Widget ratings and adoption tracking: which widgets are in use where, with aggregated friction scores across deployments * Pattern versioning: widget patterns have explicit versions; hubs can pin or follow-latest * Pattern adoption with manifest amendment workflow: adoption updates the adopting hub's capability manifest when new types are introduced * Marketplace dashboard: browse, search, and adopt patterns ### Functional Capabilities * Hub operators can publish a widget pattern to the shared library; pattern widget type must be in `widget_type_registry` * Hub operators can adopt a published pattern into their hub; adoption triggers a manifest amendment if new types are introduced * Governance templates (requirement categories, decision checklists) can be cloned across hubs; cloning amends the cloning hub's manifest for new categories * Widget adoption across hubs is tracked for aggregate friction and outcome analysis * Pattern authors receive friction and outcome feedback from all adopter hubs (opt-in anonymised) * Hub registry shows each hub's active capability manifest summary and GAAF compliance status ### Exit Criteria * Hub registry renders all registered hubs with their active capability manifest declared vocabulary and current health score * Widget pattern library lists published patterns with version history; each pattern's widget type is linked to its registry entry * A pattern can be published from one hub and adopted into another; adoption triggers a manifest amendment draft when new types are introduced * Adoption tracking shows which hubs use which patterns * Governance template cloning works end-to-end; new categories appear in the adopting hub's manifest amendment * Marketplace dashboard renders search and browse * Hub registry GAAF compliance indicator renders correctly for all hubs ### Data Artifacts Introduced `WidgetPattern`, `WidgetPatternVersion`, `PatternAdoption`, `GovernanceTemplate`, `GovernanceTemplateClone` Note: No `HubRegistry` table — the hub registry is a view over existing `hub_capability_manifests`, `hub_health_snapshots`, and `hubs` tables. --- ## Phase 11 — Advanced AI Federation ### Goal Move AI assistance from single-model, single-agent operation to a federated, multi-model, multi-agent architecture. Phase 5 introduced bounded AI support for distillation and suggestion. Phase 11 introduces agent specialisation, model routing, inter-agent delegation, and collective AI governance — while keeping humans firmly in control of final decisions. ### Scope * Agent registry: named, versioned AI agents with declared capabilities and trust levels * Model routing: select model per task type based on cost, capability, and policy * Inter-agent delegation: an agent can spawn or invoke a specialist sub-agent with a bounded scope * Agent collaboration records: when multiple agents contribute to a single proposal, all contributions are attributed * Collective proposal review: proposals that require multi-agent consensus before human review * AI governance policies: per-hub rules controlling which agents may operate, on which artifact types, with what authority * Agent performance tracking: acceptance rate, revision rate, confidence calibration over time ### Functional Capabilities * Hub operators can register and configure specialised agents (triage agent, synthesis agent, policy agent, implementation agent) * Agent tasks are routed to the lowest-cost model that meets capability and policy requirements * A delegating agent can hand off a subtask with a capped token budget and scoped context * All inter-agent delegations are recorded and auditable * Humans can inspect the full provenance of any AI output: which agents contributed, which models were used, in what order * AI governance policies can restrict specific agents to read-only or advisory-only roles per hub ### Exit Criteria * Agent registry lists all registered agents with capability and trust metadata * Model routing selects the correct model for at least three task types * Inter-agent delegation creates an auditable delegation record * Collective proposals show all contributing agents * AI governance policy blocks an out-of-scope agent action * Agent performance dashboard renders acceptance and calibration metrics ### Data Artifacts Introduced `AgentRegistration`, `ModelRoutingPolicy`, `AgentDelegation`, `CollectiveProposal`, `AiGovernancePolicy`, `AgentPerformanceRecord` --- ## Phase 12 — Platform Memory and Continuous Learning ### Goal Close the longest feedback loop in the IHF: from deployed outcome signals and accumulated governance history back to improved distillation, better routing, and sharper AI proposals. Phase 12 makes the IHF a learning platform, not merely a record-keeping one. ### Scope * Long-term outcome correlation: connect deployment outcomes to the original requirement and annotation signals that drove them, across quarters * Pattern performance memory: track which widget patterns, governance templates, and routing rules have historically produced good outcomes * Adaptive friction thresholds: friction score weights and bottleneck thresholds adjust based on observed hub-specific outcome data * Institutional knowledge capture: significant decisions, their context, and their outcomes are distilled into a queryable knowledge base * Retroactive lineage enrichment: as new outcomes arrive, earlier records in the traceability chain are enriched with outcome metadata * Learning dashboard: shows what the platform has learned — best-performing patterns, most-predictive signals, longest-value decisions ### Functional Capabilities * The platform can answer "which types of annotation predicted a negative outcome in this hub?" * Widget patterns are ranked by historical outcome quality, not just adoption * Friction thresholds for a hub can be calibrated from its own outcome history * Governance decisions are enriched with outcome summaries when signals arrive * A knowledge base of significant decisions is queryable by agents and operators * The learning dashboard shows platform-level insights with evidence links ### Exit Criteria * Long-term outcome correlation produces at least one actionable hub-specific insight from test data * Pattern performance ranking changes after seeding outcome data * Adaptive thresholds update friction scores after calibration run * Institutional knowledge base is queryable and returns relevant decisions * Retroactive lineage enrichment updates at least one decision record with outcome metadata * Learning dashboard renders all panels with correct evidence links ### Data Artifacts Introduced `OutcomeCorrelation`, `PatternPerformanceRecord`, `AdaptiveThresholdConfig`, `InstitutionalKnowledgeEntry`, `LearningInsight` --- ## 6. Revised Phased Summary | Phase | Title | Status | |-------|-------|--------| | 0 | Concept Foundation | complete | | 1 | Minimal Interaction Core | complete | | 2 | Structured Feedback and Triage | complete | | 3 | Governance and Decision Linkage | complete | | 4 | Outcome Observation and Antifragility | complete | | 5 | Agent-Assisted Distillation | complete | | 6 | Cross-Framework UI Adaptation | complete | | 7 | Advanced Observability | complete | | 8 | Federated Hub Maturity | in progress | | 9 | External API Surface and Consumer SDKs | planned | | 10 | Hub Registry and Widget Marketplace | planned | | 11 | Advanced AI Federation | planned | | 12 | Platform Memory and Continuous Learning | planned | --- ## 7. Dependency Graph (Phases 9–12) ``` Phase 8 (Federated) ──→ IHUB-WP-0009 (GAAF Foundation) ──→ Phase 9 (External API) │ │ │ type registries, manifests, ▼ │ contracts, fitness fns Phase 10 (Marketplace) │ │ └──────────────────────────────────────┤ │ Phase 7 (Observability) ──→ Phase 11 (AI Federation) ←───────────────┘ Phase 5 (Agent Assist) ──┘ │ ▼ Phase 12 (Platform Memory) ▲ Phase 4 (Outcomes) ───────────┘ ``` - **IHUB-WP-0009 (GAAF Compliance Foundation) is a prerequisite for Phase 9 and Phase 10.** It establishes the type registries, HubCapabilityManifest, `/contracts/` directory, and architectural fitness functions that both phases depend on. Phase 9 cannot generate a correct OpenAPI specification without the type registries. Phase 10 cannot build its Hub Registry without the manifest schema. - Phase 9 requires Phase 8 (stable federated schema, OAuth replaces per-hub Bearer tokens) and IHUB-WP-0009 (type registry enumerations, manifest-linked API consumers) - Phase 10 requires Phase 9 (marketplace API is built on v2 API surface) and IHUB-WP-0009 (Hub Registry = HubCapabilityManifest + discovery UI; widget patterns reference type registry entries) - Phase 11 requires Phase 5 (agent model) and Phase 7 (observability signals needed for model routing and performance tracking) - Phase 12 requires Phase 4 (outcome signals), Phase 7 (friction/health history), and Phase 11 (agent performance as a learning input) --- ## 8. Risks and Failure Modes (v0.2 additions) ### 8.1 API Surface Becoming a Governance Bypass Risk: external consumers write interaction events or annotations without honouring the IHF envelope contract, polluting the governance record. Mitigation: the `/api/v2/` write endpoints validate against the active `InteractionReportingContract` and `EnvelopeEmissionContract`. Writes that fail validation return 422 with contract-referenced errors. ### 8.2 Marketplace Pattern Divergence Risk: adopted widget patterns diverge from their source over time, breaking the aggregate friction and outcome correlation. Mitigation: `PatternAdoption` records the version pinned at adoption time. Pattern authors can issue new versions; adopters choose whether to migrate. Aggregate metrics are version-scoped. ### 8.3 AI Federation Complexity Outpacing Auditability Risk: multi-agent delegation chains become too deep to audit meaningfully. Mitigation: `AgentDelegation` has a max depth field enforced at creation time (default: 2). Chains deeper than the hub's `AiGovernancePolicy.max_depth` are rejected with an audit record of the refusal. ### 8.4 Learning Feedback Loops Reinforcing Bias Risk: outcome correlation training on biased historical data produces systematically wrong friction weight adjustments. Mitigation: `AdaptiveThresholdConfig` records the data window and sample size used for each calibration. Calibrations below a minimum sample threshold are flagged as `low_confidence` and do not apply automatically. ### 8.5 Knowledge Base Becoming Stale Risk: `InstitutionalKnowledgeEntry` records reflect decisions that were later superseded, misleading agents and operators. Mitigation: entries link to their source `DecisionRecord`. When a decision is superseded (a new decision is linked to the same requirement), the knowledge entry is flagged `superseded` and a new entry is created for the successor. --- ## 9. Success Criteria (v0.2 additions) The Interaction Hub Framework at v0.2 maturity is successful when: * external systems can read and write IHF state via stable, versioned contracts * widget and governance patterns are reusable without copy-paste * multiple AI agents collaborate on proposals without reducing accountability * the platform visibly learns from its own outcome history * hub leaders can make evidence-based decisions about pattern adoption and agent configuration without reading source code * the IHF can be deployed across an organisation with clear ownership, policies, and audit trails at every layer --- ## 10. Short Strategic Summary The Interaction Hub Framework v0.2 extends the governed interaction substrate into a **composable, federated, learning platform**. Where v0.1 asked: *can we make interaction observable and governance auditable?* v0.2 asks: *can the platform teach itself, share what it knows, and remain accountable while doing so?* The answer depends on making every new capability — API surface, marketplace patterns, AI federation, outcome correlation — subject to the same contract discipline and human oversight that governs the core. That continuity of principle is what makes the framework trustworthy at scale.