feat(WP-0010): IHF Phase 9 — External API Surface and Consumer SDKs

Delivers the full Phase 9 external API layer:

- Versioned REST API (/api/v2/) with OpenAPI 3.1 spec; enum arrays for
  widget_type, event_type, annotation category drawn live from registry tables
- OAuth 2.0 client credentials flow (/api/v2/token); hub:*:write scopes
  gated on active HubCapabilityManifest FK
- API key management: SHA256-hashed tokens, key_prefix for display,
  one-time reveal on creation, revocation support
- TypeScript and Python consumer SDKs generated from registry tables
  (/api/v2/sdk/ihf-client.ts, /api/v2/sdk/ihf-client.py)
- Webhook delivery: HMAC-SHA256 signing, append-only webhook_deliveries,
  fire-and-forget dispatch via forkIO, 3-retry logic
- Admin API dashboard with 24h stats (request count, error rate, last seen)
- Rate limiting (per-minute) and daily quota enforcement via api_request_log
- Schema migration: api_consumers, api_keys, webhook_subscriptions (CHECK
  constraint on 6 framework lifecycle topics), webhook_deliveries
  (append-only trigger), api_request_log
- ARCHITECTURE-LAYERS.md scorecard: 3.34 → 3.41 (approaching Strong)
- contracts/functional/interaction-reporting-v1.md extended with Phase 9
  endpoint catalogue and 422 validation error format

GAAF: no bare TEXT discriminators; webhook event_type uses CHECK constraint
over 6 allowed framework lifecycle topic strings (not widget event types).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Web/Controller/Api/V2/Annotations.hs

@@ -0,0 +1,100 @@
+module Web.Controller.Api.V2.Annotations where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import Data.Aeson (object, (.=))
+import Web.Controller.Api.V2.Auth
+    ( requireApiConsumer, paginatedResponse, getPageParams
+    , respondWithStatus )
+import Application.Helper.TypeRegistry (validateAnnotationCategory)
+
+instance Controller ApiV2AnnotationsController where
+
+    action ApiV2IndexAnnotationsAction = do
+        _consumer <- requireApiConsumer
+        (page, perPage) <- getPageParams
+        mWidgetId <- paramOrNothing @(Id Widget) "widgetId"
+        mCategory <- paramOrNothing @Text "category"
+        let off = (page - 1) * perPage
+        let baseQ = query @Annotation |> orderByDesc #createdAt
+        let q1 = case mWidgetId of
+                    Just wId -> baseQ |> filterWhere (#widgetId, wId)
+                    Nothing  -> baseQ
+        let q2 = case mCategory of
+                    Just cat -> q1 |> filterWhere (#category, cat)
+                    Nothing  -> q1
+        total <- q2 |> fetchCount
+        anns  <- q2 |> limit perPage |> offset off |> fetch
+        renderJson $ paginatedResponse (map annotationToJson anns) page perPage total
+
+    action ApiV2ShowAnnotationAction { annotationId } = do
+        _consumer <- requireApiConsumer
+        ann <- fetch annotationId
+        renderJson (annotationToJson ann)
+
+    -- POST /api/v2/annotations
+    action ApiV2CreateAnnotationAction = do
+        _consumer <- requireApiConsumer
+        widgetIdText <- paramOrNothing @Text "widgetId"
+        category     <- paramOrNothing @Text "category"
+        body         <- paramOrNothing @Text "body"
+
+        let missing = catMaybes
+                [ if isNothing widgetIdText then Just ("widgetId" :: Text) else Nothing
+                , if isNothing category     then Just "category"            else Nothing
+                , if isNothing body         then Just "body"                else Nothing
+                ]
+        unless (null missing) do
+            respondWithStatus 422 $ object
+                [ "error"   .= ("Missing required fields" :: Text)
+                , "missing" .= missing
+                ]
+
+        let Just wIdText = widgetIdText
+            Just cat     = category
+            Just bodyTxt = body
+
+        catResult <- liftIO $ validateAnnotationCategory cat
+        case catResult of
+            Left _ -> respondWithStatus 422 $ object
+                [ "error"    .= ("Unregistered annotation category" :: Text)
+                , "code"     .= ("unregistered_category" :: Text)
+                , "value"    .= cat
+                , "registry" .= ("/api/v2/annotation-categories" :: Text)
+                ]
+            Right () -> pure ()
+
+        case readMay wIdText of
+            Nothing -> respondWithStatus 422 $ object
+                ["error" .= ("widgetId must be a valid UUID" :: Text)]
+            Just rawId -> do
+                let wId = Id rawId :: Id Widget
+                mWidget <- fetchOneOrNothing wId
+                case mWidget of
+                    Nothing -> respondWithStatus 422 $ object
+                        ["error" .= ("Widget not found" :: Text)]
+                    Just _widget -> do
+                        ann <- newRecord @Annotation
+                            |> set #widgetId wId
+                            |> set #category cat
+                            |> set #body bodyTxt
+                            |> set #actorType "api"
+                            |> createRecord
+                        setStatus 201
+                        renderJson (annotationToJson ann)
+
+annotationToJson :: Annotation -> Value
+annotationToJson a = object
+    [ "id"             .= a.id
+    , "widgetId"       .= a.widgetId
+    , "parentId"       .= a.parentId
+    , "body"           .= a.body
+    , "category"       .= a.category
+    , "severity"       .= a.severity
+    , "threadId"       .= a.threadId
+    , "actorId"        .= a.actorId
+    , "actorType"      .= a.actorType
+    , "createdAt"      .= a.createdAt
+    ]