# 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.