generated from coulomb/repo-seed
feat(WP-0009): IHF GAAF Compliance Foundation — type registries, extension manifests, architectural contracts
Some checks failed
Test / test (push) Has been cancelled
Some checks failed
Test / test (push) Has been cancelled
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>
This commit is contained in:
123
contracts/functional/interaction-reporting-v1.md
Normal file
123
contracts/functional/interaction-reporting-v1.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# 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)
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "<uuid>",
|
||||
"widget_id": "<uuid>",
|
||||
"event_type": "clicked",
|
||||
"occurred_at": "2026-03-31T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Response — Validation Error (422 Unprocessable Entity)
|
||||
|
||||
```json
|
||||
{
|
||||
"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)
|
||||
|
||||
```json
|
||||
{
|
||||
"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')
|
||||
84
contracts/functional/module-maturity-labels.md
Normal file
84
contracts/functional/module-maturity-labels.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# Module Maturity Labels
|
||||
|
||||
**Name:** module-maturity-labels
|
||||
**Version:** 1.0
|
||||
**Date:** 2026-03-31
|
||||
**Status:** Active
|
||||
**Layer:** Functional
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
Defines the four maturity states used to label IHF functional modules and
|
||||
contract tables. These labels communicate to domain hub developers which
|
||||
surfaces are safe to depend on long-term.
|
||||
|
||||
---
|
||||
|
||||
## Labels
|
||||
|
||||
### Stable
|
||||
|
||||
The public interface **will not change** within the current major version.
|
||||
|
||||
- Removing a field, renaming a table, or changing a column type is a **breaking
|
||||
change** and requires a major version bump (e.g. IHF v1.0 → v2.0).
|
||||
- Adding a nullable or defaulted column is **not** breaking and may occur
|
||||
without a version bump, but is documented in the changelog.
|
||||
- Suitable for all production use, including domain hub compilation dependencies.
|
||||
|
||||
### Beta
|
||||
|
||||
The interface is **finalised for typical use** but edge-case fields may change
|
||||
with a minor-version notice (e.g. IHF v0.2 → v0.3).
|
||||
|
||||
- Core workflow fields are stable; metadata, computed, or supplementary fields
|
||||
may be refined.
|
||||
- Suitable for production use with awareness: monitor the changelog before
|
||||
upgrading.
|
||||
- A Beta module will be promoted to Stable once it has been used in at least
|
||||
two deployed domain hubs without reported breaking-change issues.
|
||||
|
||||
### Experimental
|
||||
|
||||
The interface **may change without notice** between patch releases.
|
||||
|
||||
- Use only for internal prototyping, spike implementations, or with explicit
|
||||
opt-in acknowledgement.
|
||||
- Not suitable for domain hub production code.
|
||||
- A module remains Experimental until its design is confirmed by real usage.
|
||||
|
||||
### Deprecated
|
||||
|
||||
The module or field **will be removed** in the next major version.
|
||||
|
||||
- A replacement is documented in the contract or in the schema comment.
|
||||
- The deprecated item remains functional until the major version boundary.
|
||||
- Domain hubs must migrate before upgrading to the next major version.
|
||||
|
||||
---
|
||||
|
||||
## Where Labels Are Used
|
||||
|
||||
| Surface | How the label is expressed |
|
||||
|---|---|
|
||||
| Functional modules | `docs/functional-modules.md` maturity column |
|
||||
| `envelope_emission_contracts` table | `maturity` column (added in IHUB-WP-0009) |
|
||||
| `interaction_reporting_contracts` table | `maturity` column |
|
||||
| `widget_adapter_specs` table | `maturity` column |
|
||||
| Type registry entries | `status` column (`active` / `deprecated`) |
|
||||
| Contract files in `/contracts/` | `Maturity:` header field |
|
||||
|
||||
---
|
||||
|
||||
## Promotion Path
|
||||
|
||||
```
|
||||
Experimental → Beta → Stable
|
||||
↓
|
||||
Deprecated → (removed at next major version)
|
||||
```
|
||||
|
||||
Promotions are recorded in the module's entry in `docs/functional-modules.md`
|
||||
and the corresponding `maturity` column in the DB is updated.
|
||||
Reference in New Issue
Block a user