generated from coulomb/repo-seed
Bernd Worsch
3cac021213
Some checks failed
Test / test (push) Has been cancelled
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>
199 lines
8.4 KiB
Markdown
199 lines
8.4 KiB
Markdown
# ARCHITECTURE-LAYERS.md
|
||
|
||
**Framework:** GAAF-2026 v1.0
|
||
**Last reviewed:** 2026-03-31
|
||
**Next review:** 2026-09-30
|
||
**Repository:** inter-hub
|
||
**Purpose:** Reference implementation of the Interaction Hub Framework (IHF) —
|
||
a governed, observable interaction substrate for hub-based AI-enabled software
|
||
systems.
|
||
|
||
---
|
||
|
||
## Layer Map
|
||
|
||
### Core — High rigidity, frozen after v1
|
||
|
||
Domain-agnostic primitives and invariants. The substrate that all functional
|
||
modules depend on.
|
||
|
||
**Entities:** `Hub`, `Widget`, `WidgetVersion`, `InteractionEvent`, `Annotation`,
|
||
`AnnotationThread`
|
||
|
||
**Traceability chain:** `Widget → InteractionEvent / Annotation →
|
||
RequirementCandidate → Requirement → DecisionRecord → ImplementationChangeReference
|
||
→ DeploymentRecord → OutcomeSignal`
|
||
|
||
**Contracts:**
|
||
- [widget-envelope-v1](contracts/core/widget-envelope-v1.md) — widget DOM
|
||
protocol, required `data-*` attributes
|
||
- [append-only-events-v1](contracts/core/append-only-events-v1.md) — immutability
|
||
invariant on `interaction_events` and `outcome_signals`
|
||
|
||
**Key invariants:**
|
||
- `interaction_events` and `outcome_signals` are append-only (DB-trigger enforced)
|
||
- Widget identity (UUID) is stable across implementation changes
|
||
- Actor attribution is explicit on all interaction and decision artifacts
|
||
|
||
### Functional — Medium rigidity, evolvable
|
||
|
||
Value-realisation modules. Each module has a declared maturity. See
|
||
`docs/functional-modules.md` for the full maturity register.
|
||
|
||
**Modules:**
|
||
- RequirementCandidate lifecycle (triage, reviewer assignment) — **Stable**
|
||
- DecisionRecord + governance ledger — **Stable**
|
||
- Requirements (promoted from candidates) — **Stable**
|
||
- DeploymentRecord + OutcomeSignal — **Stable**
|
||
- AgentProposal + AgentReviewRecord + ConfidenceAnnotation — **Beta**
|
||
- Cross-framework adapter contracts (EnvelopeEmissionContract,
|
||
InteractionReportingContract, WidgetAdapterSpec) — **Stable**
|
||
- FrictionScore + BottleneckRecord — **Beta**
|
||
- HubHealthSnapshot — **Beta**
|
||
- CrossHubPropagation — **Experimental**
|
||
- WidgetOwnership — **Stable**
|
||
- HubRoutingRule — **Stable**
|
||
- FederatedPolicyOverlay — **Beta**
|
||
- StewardshipRole — **Stable**
|
||
- ArchiveRecord + lineage inspector — **Beta**
|
||
- Type registries (WidgetTypeRegistry, EventTypeRegistry,
|
||
AnnotationCategoryRegistry, PolicyScopeRegistry) — **Beta**
|
||
- HubCapabilityManifest — **Beta**
|
||
|
||
**Contract:** [interaction-reporting-v1](contracts/functional/interaction-reporting-v1.md)
|
||
|
||
### Customization — Low rigidity, hub-specific adaptation
|
||
|
||
Hub-specific routing behaviour and policy configuration. These are Functional
|
||
modules in implementation but serve the Customization purpose of adapting
|
||
framework behaviour per-hub without forking code.
|
||
|
||
**Entities:** `HubRoutingRule`, `FederatedPolicyOverlay`
|
||
|
||
**Note:** A formal Customization layer manifest (per-hub configuration contract
|
||
with migration support) is planned for IHF v1.0. Currently these are Functional
|
||
modules with hub-scoped parameters.
|
||
|
||
### Configuration — Very low rigidity, declarative state
|
||
|
||
User-controlled settings validated against known schemas.
|
||
|
||
**Fields:** `hubs.hub_kind`, `hubs.domain`, `hubs.api_key`,
|
||
`widgets.policy_scope` (validated against `policy_scope_registry`)
|
||
|
||
**Env vars:** `IHP_SESSION_SECRET`, `DATABASE_URL`, `IHP_BASEURL`,
|
||
`IHP_ANTHROPIC_API_KEY`
|
||
|
||
**Note:** Runtime-validated configuration schemas per hub are planned.
|
||
Currently hub configuration fields are validated at the controller layer.
|
||
|
||
### Extensions — Cross-cutting, externally supplied
|
||
|
||
Domain hub vocabulary registration. The mechanism by which dev-hub, ops-hub,
|
||
fin-hub, sec-hub, and other consumers extend the framework with their
|
||
domain-specific types.
|
||
|
||
**Entities:** `HubCapabilityManifest`, `WidgetTypeRegistry`, `EventTypeRegistry`,
|
||
`AnnotationCategoryRegistry`, `PolicyScopeRegistry`,
|
||
`ApiConsumer`, `ApiKey`, `WebhookSubscription`, `WebhookDelivery`, `ApiRequestLog`
|
||
|
||
**Contract:** [hub-capability-manifest-v1](contracts/extensions/hub-capability-manifest-v1.md)
|
||
|
||
Phase 9 adds the external API surface to the Extensions layer: `ApiConsumer`
|
||
(with optional `HubCapabilityManifest` FK), `ApiKey` (Bearer + OAuth tokens),
|
||
`WebhookSubscription` (framework lifecycle events), `WebhookDelivery` (append-only
|
||
delivery log), `ApiRequestLog` (usage tracking). `ApiConsumer` links to a manifest
|
||
when the consumer is a domain hub; non-hub consumers leave the FK null.
|
||
|
||
---
|
||
|
||
## Dependency Rule
|
||
|
||
```
|
||
Core ← Functional ← Customization ← Configuration
|
||
Extensions plug into Core or Functional only via manifests and type registries.
|
||
|
||
Domain hubs (consumers) depend on Core and Functional.
|
||
They extend via Extensions (manifest registration).
|
||
They configure via Configuration (hub_kind, policy_scope, api_key).
|
||
```
|
||
|
||
Upward dependencies (Functional → Core) are permitted.
|
||
Downward dependencies (Core → Functional) are **forbidden**.
|
||
|
||
---
|
||
|
||
## GAAF-2026 Scorecard
|
||
|
||
*Last updated: 2026-04-01 (post IHUB-WP-0010 — Phase 9 External API)*
|
||
|
||
| Layer | Score (0–5) | Weight | Weighted | Notes |
|
||
|---|---|---|---|---|
|
||
| Core | 3.8 | 30% | 1.14 | Contracts formalised; type registries anchor discriminators |
|
||
| Functional | 3.3 | 20% | 0.66 | OpenAPI spec + contract companion; SDK generation live |
|
||
| Customization | 2.5 | 15% | 0.38 | HubRoutingRule/Overlay present; no formal manifest yet |
|
||
| Configuration | 3.2 | 10% | 0.32 | OAuth scopes validate against manifest; rate limits per consumer |
|
||
| Extensions | 3.7 | 10% | 0.37 | API consumer links to manifest; manifest-gated hub:write scopes |
|
||
| Cross-layer | 3.6 | 15% | 0.54 | Fitness functions in CI; contracts documented; layer map current |
|
||
| **Total** | | | **3.41** | Usable but vulnerable — Phase 10 ready |
|
||
|
||
**Interpretation:** 3.41 = Usable but vulnerable (2.5–3.4 range; approaching Strong).
|
||
Target for Phase 10 exit: ≥3.5 (Strong).
|
||
|
||
*Score ≥3.5 target criteria for Phase 10:*
|
||
- Customization layer manifest implemented (per-hub configuration contract)
|
||
- Functional module demand signals formalised
|
||
- Hub config schema runtime-validated
|
||
- Hub Registry (Phase 10) public discovery UI operational
|
||
|
||
*Next review date: 2026-09-30*
|
||
|
||
---
|
||
|
||
## Architectural Fitness Functions
|
||
|
||
Implemented in `Test/Architecture/LayerBoundarySpec.hs`.
|
||
Run as part of the standard `test` command.
|
||
|
||
| Test | What it checks | On failure |
|
||
|---|---|---|
|
||
| Test 1 — Core immutability | Schema contains all 4 append-only triggers | Hard failure |
|
||
| Test 2 — Contract artifacts | `/contracts/` key files exist | Hard failure |
|
||
| Test 3 — Registry non-empty | All 4 type registries have ≥1 active entry | Hard failure |
|
||
| Test 4 — No bare TEXT discriminators | New columns after GAAF marker use registry refs | Hard failure |
|
||
| Test 5 — Domain hub manifest | Domain hubs have active manifests | Warning only |
|
||
|
||
---
|
||
|
||
## GAAF Architectural Laws (Applied to inter-hub)
|
||
|
||
1. **Type discriminator columns** (`widget_type`, `event_type`, `category`,
|
||
`policy_scope`) must reference a registry or carry a CHECK constraint.
|
||
No new bare TEXT type discriminators after IHUB-WP-0009.
|
||
|
||
2. **Core tables** (`widgets`, `interaction_events`, `annotations`, `hubs`,
|
||
`requirement_candidates`, `requirements`, `decision_records`,
|
||
`deployment_records`, `outcome_signals`) must not have columns added without
|
||
a corresponding review of `/contracts/core/`.
|
||
|
||
3. **Append-only invariant** on `interaction_events` and `outcome_signals` is
|
||
permanent. No migration may remove or bypass the enforcement triggers.
|
||
|
||
4. **Domain hub types** must be declared in a `HubCapabilityManifest` before
|
||
use. Unmanifested hub-owned types are flagged by fitness function Test 5.
|
||
|
||
5. **Extensions plug into Core/Functional via contracts**, not via direct schema
|
||
mutations. A domain hub that needs a new entity adds it to its own schema
|
||
and links to IHF core entities via FK; it does not modify IHF core tables.
|
||
|
||
---
|
||
|
||
## Decisions Log
|
||
|
||
| Date | Decision | Rationale |
|
||
|---|---|---|
|
||
| 2026-03-31 | Adopted GAAF-2026 as architectural compliance framework | Post-Phase 8 review identified gaps in extension layer, type safety, and contract formalisation |
|
||
| 2026-03-31 | Type registries over CHECK constraints | Registries enable Phase 10 marketplace discovery; CHECK constraints are inflexible for domain extension |
|
||
| 2026-03-31 | HubCapabilityManifest in inter-hub (not hub-core) | hub-core not yet implemented; manifest provides DB-side registration contract immediately |
|
||
| 2026-03-31 | hub_kind 'framework' has unique index constraint | Prevents accidental creation of a second framework hub row |
|