inter-hub/specs/InteractionHubFrameworkSpecification_v0.2.md

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.