feat(WP-0009): IHF GAAF Compliance Foundation — type registries, extension manifests, architectural contracts

Implements IHUB-WP-0009: closes four GAAF-2026 gaps before domain hub work begins. - TypeRegistry helper + controllers/views (hub_kind, hub_capability_manifest) - HubCapabilityManifest entity with validation and registry linkage - ARCHITECTURE-LAYERS.md + CI-enforced boundary contracts - Alembic migration 1743724800, fitness tests (Test/Architecture/) - GAAF spec, Operational Architecture spec, domain hub extension guide - Updates to CLAUDE.md, SCOPE.md, Schema.sql, Routes, FrontController, Types state_hub_sync: pending (tunnel was STALE at completion time; run fix-consistency) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-31 21:17:39 +00:00
parent 1a7732d7da
commit b5d73aa18b
47 changed files with 4855 additions and 104 deletions
--- a/specs/InteractionHubFrameworkSpecification_v0.2.md
+++ b/specs/InteractionHubFrameworkSpecification_v0.2.md
@@ -121,13 +121,59 @@ 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
+* 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
-* Consumer SDKs: TypeScript/Node, Python
+* 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
@@ -137,24 +183,33 @@ ships consumer SDKs that make integration a day's work rather than a project.
 * 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 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
-* TypeScript SDK and Python SDK published (as static files or packages)
+* 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
@@ -166,45 +221,105 @@ 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 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
+* 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
-* Hub operators can adopt a published pattern into their hub
+* 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
+  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 capability metadata
-* Widget pattern library lists published patterns with version history
-* A pattern can be published from one hub and adopted into another
+* 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
+* 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
@@ -339,12 +454,14 @@ merely a record-keeping one.
 ## 7. Dependency Graph (Phases 9–12)

 ```
-Phase 8 (Federated) ──→ Phase 9 (External API)
-                              │
-                              ▼
-                        Phase 10 (Marketplace)
-                              │
-Phase 7 (Observability) ──→ Phase 11 (AI Federation)
+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)
@@ -352,9 +469,18 @@ Phase 5 (Agent Assist)  ──┘       │
 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)
- Phase 10 requires Phase 9 (marketplace API is built on v2 API surface)
+  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