Bernd Worsch
3cac021213
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>
IHF Contract Catalog
Framework: GAAF-2026 Last reviewed: 2026-03-31 Repository: inter-hub
This directory contains the versioned, machine-readable contracts for each GAAF-2026 layer. Contract files are the authoritative declaration of interface, invariants, compatibility rules, and validation requirements for every public surface in the framework.
The canonical implementation of each contract is the PostgreSQL schema and Haskell controllers. These files are the discoverable declaration — the human and agent-readable companion that makes intent explicit without requiring the source code to be read.
Core Contracts
| Contract | File | Version | Status |
|---|---|---|---|
| Widget Envelope | core/widget-envelope-v1.md | 1.0 | Active |
| Append-Only Events | core/append-only-events-v1.md | 1.0 | Active |
Core contracts are immutable after activation. New requirements produce a new version (v1.1, v2.0); the old version remains readable for audit.
Functional Contracts
| Contract | File | Version | Status |
|---|---|---|---|
| Interaction Reporting API | functional/interaction-reporting-v1.md | 1.0 | Active |
| Module Maturity Labels | functional/module-maturity-labels.md | 1.0 | Active |
Functional contracts are evolvable with minor-version notice. Breaking changes require a major version bump and a deprecation window.
Extensions Contracts
| Contract | File | Version | Status |
|---|---|---|---|
| Hub Capability Manifest | extensions/hub-capability-manifest-v1.md | 1.0 | Active |
Extensions contracts govern how domain hubs register their vocabulary and capabilities with the framework.
Contract Lifecycle
Draft → Active → Superseded
↓
(never deleted — old versions remain for audit)
A contract becomes Active when:
- Its corresponding schema and code are deployed
- It is referenced in
ARCHITECTURE-LAYERS.md
A contract is Superseded when a new version replaces it. The old file
remains with a superseded_by note at the top.
Adding a New Contract
- Create the file in the appropriate layer directory
- Follow the header format: name, version, date, status, layer
- Document: interface, invariants, compatibility rules, validation rules, failure mode
- Add an entry to this README table
- Reference it in
ARCHITECTURE-LAYERS.md