inter-hub-haskell/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.