79 lines
2.5 KiB
Markdown
79 lines
2.5 KiB
Markdown
|
# 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](core/widget-envelope-v1.md) | 1.0 | Active |
|
||
|
|
| Append-Only Events | [core/append-only-events-v1.md](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](functional/interaction-reporting-v1.md) | 1.0 | Active |
|
||
|
|
| Module Maturity Labels | [functional/module-maturity-labels.md](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](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
|
||
|
|
|
||
|
|
1. Create the file in the appropriate layer directory
|
||
|
|
2. Follow the header format: name, version, date, status, layer
|
||
|
|
3. Document: interface, invariants, compatibility rules, validation rules,
|
||
|
|
failure mode
|
||
|
|
4. Add an entry to this README table
|
||
|
|
5. Reference it in `ARCHITECTURE-LAYERS.md`
|