diff --git a/specs/InteractionHubFrameworkSpecification_v0.2.md b/specs/InteractionHubFrameworkSpecification_v0.2.md new file mode 100644 index 0000000..63314d8 --- /dev/null +++ b/specs/InteractionHubFrameworkSpecification_v0.2.md @@ -0,0 +1,437 @@ +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. + +### Scope + +* Versioned REST API (`/api/v2/`) for all core IHF artifact types +* OpenAPI 3.1 specification generated from the live schema +* Authentication: OAuth 2.0 client credentials flow (superseding per-hub Bearer tokens) +* API key management UI for external consumers +* Consumer SDKs: TypeScript/Node, Python +* 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 +* Downstream hubs can subscribe to governance events via webhooks +* SDK consumers get type-safe access to IHF contracts without reading the spec +* 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 +* TypeScript SDK and Python SDK published (as static files or packages) +* Webhook delivery confirmed for at least two event types +* API usage dashboard renders correctly +* OAuth token flow works end-to-end + +### Data Artifacts Introduced + +`ApiConsumer`, `ApiKey`, `WebhookSubscription`, `WebhookDelivery` + +--- + +## 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. + +### Scope + +* Hub registry: a catalog of registered hubs with public metadata, capability + declarations, and health summaries +* Widget pattern library: reusable widget definitions that can be instantiated + into any hub +* Governance template library: requirement distillation and decision templates + that can be cloned across hubs +* 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 +* Marketplace dashboard: browse, search, and adopt patterns + +### Functional Capabilities + +* Hub operators can publish a widget pattern to the shared library +* Hub operators can adopt a published pattern into their hub +* Governance templates (requirement categories, decision checklists) can be + cloned across hubs +* 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) + +### Exit Criteria + +* Hub registry renders all registered hubs with capability metadata +* Widget pattern library lists published patterns with version history +* A pattern can be published from one hub and adopted into another +* Adoption tracking shows which hubs use which patterns +* Governance template cloning works end-to-end +* Marketplace dashboard renders search and browse + +### Data Artifacts Introduced + +`WidgetPattern`, `WidgetPatternVersion`, `PatternAdoption`, `GovernanceTemplate`, +`GovernanceTemplateClone` + +--- + +## 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) ──→ Phase 9 (External API) + │ + ▼ + Phase 10 (Marketplace) + │ +Phase 7 (Observability) ──→ Phase 11 (AI Federation) +Phase 5 (Agent Assist) ──┘ │ + ▼ + Phase 12 (Platform Memory) + ▲ +Phase 4 (Outcomes) ───────────┘ +``` + +- Phase 9 requires Phase 8 (stable federated schema, OAuth replaces per-hub + Bearer tokens) +- Phase 10 requires Phase 9 (marketplace API is built on v2 API surface) +- 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.