generated from coulomb/repo-seed
Bernd Worsch
b5d73aa18b
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>
189 lines
7.8 KiB
Markdown
189 lines
7.8 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`
|
||
|
||
**Contract:** [hub-capability-manifest-v1](contracts/extensions/hub-capability-manifest-v1.md)
|
||
|
||
---
|
||
|
||
## 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
|
||
|
||
*Initial assessment: 2026-03-31 (post IHUB-WP-0009)*
|
||
|
||
| Layer | Score (0–5) | Weight | Weighted | Notes |
|
||
|---|---|---|---|---|
|
||
| Core | 3.8 | 30% | 1.14 | Contracts formalised; type registries anchor discriminators |
|
||
| Functional | 3.2 | 20% | 0.64 | Maturity labels added; demand signals still informal |
|
||
| Customization | 2.5 | 15% | 0.38 | HubRoutingRule/Overlay present; no formal manifest yet |
|
||
| Configuration | 3.0 | 10% | 0.30 | Registry-backed validation added; hub config schema planned |
|
||
| Extensions | 3.5 | 10% | 0.35 | HubCapabilityManifest operational; manifest protocol Beta |
|
||
| Cross-layer | 3.5 | 15% | 0.53 | Fitness functions in CI; contracts documented; layer map current |
|
||
| **Total** | | | **3.34** | Usable but vulnerable — Phase 9 ready |
|
||
|
||
**Interpretation:** 3.34 = Usable but vulnerable (2.5–3.4). Phase 9 may begin.
|
||
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
|
||
|
||
---
|
||
|
||
## 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 |
|