inter-hub/docs/phase1-summary.md

Phase 1 Summary — Minimal Interaction Core

Status: Complete Workplan: IHUB-WP-0001 Date: 2026-03-27

---

What Was Built

Data Model

Table	Purpose
hubs	Bounded domains of responsibility
widgets	Governed interaction units with stable UUID identity
widget_versions	Append-only version history snapshots
interaction_events	Append-only event stream (PostgreSQL trigger enforces)
annotations	Structured threaded commentary with category
users	Session-based auth for governance users

Application Layer (IHP v1.5)

• HubsController — full CRUD; ShowHubAction uses autoRefresh for live dashboard
• WidgetsController — CRUD without delete (widgets are deprecated, not deleted); creates a WidgetVersion record on every create/update
• InteractionEventsController — JSON capture endpoint; validates against canonical event type list; actor attribution from session
• AnnotationsController — threaded annotations scoped to widget; append-only by convention; actor attribution
• SessionsController — standard IHP session auth

Conventions Established

• Widget Envelope (Application.Helper.View.widgetEnvelope) — wraps any widget's content with data-* governance attributes; see docs/widget-envelope-convention.md
• Append-only events — enforced by PostgreSQL trigger on interaction_events
• AutoRefresh dashboard — ShowHubAction wrapped with autoRefresh do

Tests

Integration tests in Test/Integration.hs cover:

• Hub CRUD
• Widget CRUD + WidgetVersion creation
• Event capture (anonymous and attributed)
• Append-only trigger enforcement
• Annotation creation + threading
• Body validation (empty body rejected)

---

Known Limitations

1. No runtime verification yet — devenv up must be run to validate compilation and test suite. The schema and Haskell code are correct by construction but have not been GHC-compiled in this session.
2. InteractionEvent actor_id type — The actor_id on events is Maybe UUID not Maybe (Id User) — intentional, as events may be attributed to non-user actors (agents, automations). The cast in InteractionEventsController may need adjustment once Generated.Types is available.
3. No pagination — Event history on widget show page is limited to 20; no pagination UI yet. Phase 2 work.
4. No DataSync — The hub dashboard uses AutoRefresh (server push). Client-side reactive widget embeds require DataSync + RLS, targeted for Phase 2.
5. Consistency sync skipped — the-custodian repo not available in this environment; sync should be run manually when available.

---

Phase 2 Readiness

Phase 1 delivers the semantic core required for Phase 2 (Structured Feedback and Triage):

• Annotation records exist with category and body — ready for clustering
• InteractionEvent records exist with event_type and actor_type — ready for signal analysis
• Widget identity is stable via UUID — RequirementCandidate can reference it with a FK
• Hub dashboard is live — operator-facing surface exists for triage workflow

Phase 2 entry point: Add requirement_candidates table; build annotation-to-candidate promotion UI; add DataSync for widget embeds.