Files

Test / test (push) Has been cancelled

Details

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

3.0 KiB

Raw Blame History

Interaction Reporting API Contract

Name: interaction-reporting Version: 1.0 Date: 2026-03-31 Status: Active Layer: Functional Maturity: Stable

Purpose

Defines the REST API surface for external systems (non-IHP adapters, domain hubs, third-party tools) to submit interaction events and annotations to the IHF without coupling to the IHP server-side implementation.

Canonical Source of Truth

The authoritative runtime contract is the active row in the interaction_reporting_contracts table. This file is the discoverable human-readable declaration. In case of conflict, the database row governs.

Endpoint

POST /api/v1/interaction-events

Authentication: Authorization: Bearer <hub-api-key>

The hub-api-key must match the api_key column of a registered hub.

Required Request Fields

Field	Type	Description
`widget_id`	UUID	The governed widget's stable ID
`event_type`	TEXT	Must exist in `event_type_registry` with `status = 'active'`
`occurred_at`	ISO 8601 timestamp	When the event occurred on the client

Optional Request Fields

Field	Type	Description
`actor_id`	UUID	The acting user's ID
`actor_type`	TEXT	`user`, `agent`, `automation`, `external_adapter`
`view_context_ref`	TEXT	View path where event occurred
`metadata`	JSON object	Arbitrary additional context

Response — Success (201 Created)

{
  "id": "<uuid>",
  "widget_id": "<uuid>",
  "event_type": "clicked",
  "occurred_at": "2026-03-31T12:00:00Z"
}

Response — Validation Error (422 Unprocessable Entity)

{
  "error": "event_type 'pipeline_started' not registered",
  "help": "Register this event type via the Type Registry admin UI or hub capability manifest before submitting."
}

Response — Auth Error (401 Unauthorized)

{
  "error": "Authorization: Bearer <hub-api-key> required"
}

Accepted Event Types

Accepted event types are all entries in event_type_registry with status = 'active'. The framework-level seed vocabulary:

viewed, focused, clicked, submitted, abandoned, retried, failed, commented, flagged_confusing, flagged_helpful, blocked_by_policy, escalated, accepted_recommendation, rejected_recommendation

Domain hubs may register additional event types via HubCapabilityManifest.

Versioning Policy

v1.0: current version. Stable.
Adding new optional request fields: minor version (v1.1), no breaking change.
Changing required fields, response shape, or auth scheme: major version (v2.0).
Phase 9 will introduce /api/v2/ with OAuth 2.0 replacing per-hub Bearer tokens. v1.0 will remain supported during the migration window.

Implementation Reference

Controller: Web/Controller/ApiInteractionEvents.hs
Route: Web/Routes.hs (CanRoute ApiInteractionEventsController)
DB record: interaction_reporting_contracts (contract_version = '1.0')

3.0 KiB Raw Blame History