inter-hub/ARCHITECTURE-LAYERS.md

ARCHITECTURE-LAYERS.md

Framework: GAAF-2026 v1.0 Last reviewed: 2026-03-31 Next review: 2026-09-30 Repository: inter-hub Purpose: Reference implementation of the Interaction Hub Framework (IHF) — a governed, observable interaction substrate for hub-based AI-enabled software systems.

---

Layer Map

Core — High rigidity, frozen after v1

Domain-agnostic primitives and invariants. The substrate that all functional modules depend on.

Entities: Hub, Widget, WidgetVersion, InteractionEvent, Annotation, AnnotationThread

Traceability chain: Widget → InteractionEvent / Annotation → RequirementCandidate → Requirement → DecisionRecord → ImplementationChangeReference → DeploymentRecord → OutcomeSignal

Contracts:

• widget-envelope-v1 — widget DOM protocol, required data-* attributes
• append-only-events-v1 — immutability invariant on interaction_events and outcome_signals

Key invariants:

• interaction_events and outcome_signals are append-only (DB-trigger enforced)
• Widget identity (UUID) is stable across implementation changes
• Actor attribution is explicit on all interaction and decision artifacts

Functional — Medium rigidity, evolvable

Value-realisation modules. Each module has a declared maturity. See docs/functional-modules.md for the full maturity register.

Modules:

• RequirementCandidate lifecycle (triage, reviewer assignment) — Stable
• DecisionRecord + governance ledger — Stable
• Requirements (promoted from candidates) — Stable
• DeploymentRecord + OutcomeSignal — Stable
• AgentProposal + AgentReviewRecord + ConfidenceAnnotation — Beta
• AgentRegistration + ModelRoutingPolicy — Beta
• AgentDelegation + CollectiveProposal + CollectiveProposalContribution — Experimental
• AiGovernancePolicy + AgentPerformanceRecord — Beta
• Cross-framework adapter contracts (EnvelopeEmissionContract, InteractionReportingContract, WidgetAdapterSpec) — Stable
• FrictionScore + BottleneckRecord — Beta
• HubHealthSnapshot — Beta
• CrossHubPropagation — Experimental
• WidgetOwnership — Stable
• HubRoutingRule — Stable
• FederatedPolicyOverlay — Beta
• StewardshipRole — Stable
• ArchiveRecord + lineage inspector — Beta
• Type registries (WidgetTypeRegistry, EventTypeRegistry, AnnotationCategoryRegistry, PolicyScopeRegistry) — Beta
• HubCapabilityManifest — Beta

Contract: interaction-reporting-v1

Customization — Low rigidity, hub-specific adaptation

Hub-specific routing behaviour, policy configuration, and pattern adoption. The manifest amendment workflow introduced in Phase 10 constitutes the formal per-hub configuration contract: adopting a pattern or cloning a governance template that introduces new types requires an explicit HubCapabilityManifest draft amendment, reviewed and activated by the hub operator.

Entities: HubRoutingRule, FederatedPolicyOverlay, PatternAdoption, GovernanceTemplateClone

Mechanism: Pattern adoption → manifest amendment draft → hub operator activates → types registered in framework-wide registry. No type is in use before it appears in an active manifest.

Configuration — Very low rigidity, declarative state

User-controlled settings validated against known schemas.

Fields: hubs.hub_kind, hubs.domain, hubs.api_key, widgets.policy_scope (validated against policy_scope_registry)

Env vars: IHP_SESSION_SECRET, DATABASE_URL, IHP_BASEURL, IHP_ANTHROPIC_API_KEY

Note: Runtime-validated configuration schemas per hub are planned. Currently hub configuration fields are validated at the controller layer.

Extensions — Cross-cutting, externally supplied

Domain hub vocabulary registration. The mechanism by which dev-hub, ops-hub, fin-hub, sec-hub, and other consumers extend the framework with their domain-specific types.

Entities: HubCapabilityManifest, WidgetTypeRegistry, EventTypeRegistry, AnnotationCategoryRegistry, PolicyScopeRegistry, ApiConsumer, ApiKey, WebhookSubscription, WebhookDelivery, ApiRequestLog, WidgetPattern, WidgetPatternVersion, PatternAdoption, GovernanceTemplate, GovernanceTemplateClone

Contract: hub-capability-manifest-v1

Phase 9 adds the external API surface to the Extensions layer: ApiConsumer (with optional HubCapabilityManifest FK), ApiKey (Bearer + OAuth tokens), WebhookSubscription (framework lifecycle events), WebhookDelivery (append-only delivery log), ApiRequestLog (usage tracking). ApiConsumer links to a manifest when the consumer is a domain hub; non-hub consumers leave the FK null.

Phase 10 adds the marketplace layer: WidgetPattern (reusable widget definitions, widget_type FK to widget_type_registry), WidgetPatternVersion (explicit version history), PatternAdoption (hub adoption records with pin/follow-latest), GovernanceTemplate (reusable governance templates with category JSONB validated at controller), GovernanceTemplateClone (adoption records for governance templates).

Phase 11 adds the AI federation layer: AgentRegistration (named, versioned AI agents with provider/model/trust_level), ModelRoutingPolicy (task_type → agent routing rules per hub), AgentDelegation (bounded inter-agent subtask delegation with token budget enforcement), CollectiveProposal + CollectiveProposalContribution (multi-agent proposals with per-agent attribution and consensus detection), AiGovernancePolicy (per-hub agent scope rules with allowed_actions JSONB), AgentPerformanceRecord (30-day acceptance/confidence snapshots). Integration via scripts/llm_bridge.py subprocess bridge to llm-connect Python library.

---

Dependency Rule

Core ← Functional ← Customization ← Configuration
Extensions plug into Core or Functional only via manifests and type registries.

Domain hubs (consumers) depend on Core and Functional.
They extend via Extensions (manifest registration).
They configure via Configuration (hub_kind, policy_scope, api_key).

Upward dependencies (Functional → Core) are permitted. Downward dependencies (Core → Functional) are forbidden.

---

GAAF-2026 Scorecard

Last updated: 2026-04-01 (post IHUB-WP-0012 — Phase 11 Advanced AI Federation)

Layer	Score (0–5)	Weight	Weighted	Notes
Core	3.8	30%	1.14	Contracts formalised; type registries anchor discriminators
Functional	3.6	20%	0.72	Multi-agent federation formalises AI collaboration; bridge + routing operational
Customization	3.2	15%	0.48	Manifest amendment workflow is formal per-hub config contract with migration
Configuration	3.2	10%	0.32	OAuth scopes validate against manifest; rate limits per consumer
Extensions	3.9	10%	0.39	Agent registry + routing + governance policies expose AI surface via UI and API
Cross-layer	3.7	15%	0.56	Fitness functions in CI; contracts documented; layer map current
Total			3.61	Strong — Phase 11 exit criteria met

Interpretation: 3.61 = Strong (≥3.5). Phase 11 exit target achieved.

Functional layer improvement (3.4 → 3.6): AgentRegistration + ModelRoutingPolicy + AgentDelegation + CollectiveProposal + AiGovernancePolicy formalise multi-agent federation as first-class governed artifacts. Agent invocations are now routed through the registry, policy-checked, and attributed with token counts.

Extensions layer improvement (3.8 → 3.9): Agent Registry UI + API surface; collective proposals expose multi-agent output with per-contributor attribution. AiGovernancePolicy makes AI scope constraints explicit and operator-configurable.

Previous scorecard (Phase 10): 3.56 (Strong)

Next review date: 2026-09-30

---

Architectural Fitness Functions

Implemented in Test/Architecture/LayerBoundarySpec.hs. Run as part of the standard test command.

Test	What it checks	On failure
Test 1 — Core immutability	Schema contains all 4 append-only triggers	Hard failure
Test 2 — Contract artifacts	/contracts/ key files exist	Hard failure
Test 3 — Registry non-empty	All 4 type registries have ≥1 active entry	Hard failure
Test 4 — No bare TEXT discriminators	New columns after GAAF marker use registry refs	Hard failure
Test 5 — Domain hub manifest	Domain hubs have active manifests	Warning only

---

GAAF Architectural Laws (Applied to inter-hub)

1. Type discriminator columns (widget_type, event_type, category, policy_scope) must reference a registry or carry a CHECK constraint. No new bare TEXT type discriminators after IHUB-WP-0009.

2. Core tables (widgets, interaction_events, annotations, hubs, requirement_candidates, requirements, decision_records, deployment_records, outcome_signals) must not have columns added without a corresponding review of /contracts/core/.

3. Append-only invariant on interaction_events and outcome_signals is permanent. No migration may remove or bypass the enforcement triggers.

4. Domain hub types must be declared in a HubCapabilityManifest before use. Unmanifested hub-owned types are flagged by fitness function Test 5.

5. Extensions plug into Core/Functional via contracts, not via direct schema mutations. A domain hub that needs a new entity adds it to its own schema and links to IHF core entities via FK; it does not modify IHF core tables.

---

Decisions Log

Date	Decision	Rationale
2026-03-31	Adopted GAAF-2026 as architectural compliance framework	Post-Phase 8 review identified gaps in extension layer, type safety, and contract formalisation
2026-03-31	Type registries over CHECK constraints	Registries enable Phase 10 marketplace discovery; CHECK constraints are inflexible for domain extension
2026-03-31	HubCapabilityManifest in inter-hub (not hub-core)	hub-core not yet implemented; manifest provides DB-side registration contract immediately
2026-03-31	hub_kind 'framework' has unique index constraint	Prevents accidental creation of a second framework hub row
2026-04-01	No HubRegistry table — registry is a view over existing tables	HubCapabilityManifest + HubHealthSnapshot + Hub already contain all needed data; a separate table would duplicate state
2026-04-01	widget_patterns.widget_type is a true FK to widget_type_registry	GAAF rule: no bare TEXT type discriminators; FK ensures patterns only reference registered types
2026-04-01	governance_templates.categories validated at controller (JSONB array FK)	SQL cannot express array FK; controller validates each element against annotation_category_registry at write time
2026-04-01	Manifest amendment gate on pattern adoption and template cloning	Adopting a cross-type-boundary artifact must go through the manifest activation flow to maintain GAAF compliance
2026-04-01	llm-connect via subprocess bridge (not direct Haskell FFI)	llm-connect is Python-only; subprocess bridge is the correct integration seam — avoids GHC/CPython FFI complexity
2026-04-01	trust_level/status/consensus_status as TEXT with CHECK constraints	GAAF rule: no bare TEXT discriminators; finite closed-set values suit CHECK over registry for these internal ADTs
2026-04-01	AiGovernancePolicy default = permit (no policy = allow propose)	Conservative default avoids silently blocking existing workflows after Phase 11 migration; operators add restrictions explicitly
2026-04-01	agent_proposals ALTER TABLE (not new table) for agent_registration_id	agent_proposals is a Core-adjacent table; extending it is cheaper and more traceable than a parallel Phase 11 table