inter-hub-haskell/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](contracts/core/widget-envelope-v1.md) — widget DOM
  protocol, required `data-*` attributes
- [append-only-events-v1](contracts/core/append-only-events-v1.md) — 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**
- 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](contracts/functional/interaction-reporting-v1.md)

### Customization — Low rigidity, hub-specific adaptation

Hub-specific routing behaviour and policy configuration. These are Functional
modules in implementation but serve the Customization purpose of adapting
framework behaviour per-hub without forking code.

**Entities:** `HubRoutingRule`, `FederatedPolicyOverlay`

**Note:** A formal Customization layer manifest (per-hub configuration contract
with migration support) is planned for IHF v1.0. Currently these are Functional
modules with hub-scoped parameters.

### 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`

**Contract:** [hub-capability-manifest-v1](contracts/extensions/hub-capability-manifest-v1.md)

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.

---

## 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-0010 — Phase 9 External API)*

| Layer | Score (0–5) | Weight | Weighted | Notes |
|---|---|---|---|---|
| Core | 3.8 | 30% | 1.14 | Contracts formalised; type registries anchor discriminators |
| Functional | 3.3 | 20% | 0.66 | OpenAPI spec + contract companion; SDK generation live |
| Customization | 2.5 | 15% | 0.38 | HubRoutingRule/Overlay present; no formal manifest yet |
| Configuration | 3.2 | 10% | 0.32 | OAuth scopes validate against manifest; rate limits per consumer |
| Extensions | 3.7 | 10% | 0.37 | API consumer links to manifest; manifest-gated hub:write scopes |
| Cross-layer | 3.6 | 15% | 0.54 | Fitness functions in CI; contracts documented; layer map current |
| **Total** | | | **3.41** | Usable but vulnerable — Phase 10 ready |

**Interpretation:** 3.41 = Usable but vulnerable (2.5–3.4 range; approaching Strong).
Target for Phase 10 exit: ≥3.5 (Strong).

*Score ≥3.5 target criteria for Phase 10:*
- Customization layer manifest implemented (per-hub configuration contract)
- Functional module demand signals formalised
- Hub config schema runtime-validated
- Hub Registry (Phase 10) public discovery UI operational

*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 |