feat(T02-T11): IHF Phase 1 schema, controllers, views, and helpers

- Schema: hubs, widgets, widget_versions, interaction_events (append-only trigger), annotations, users — single migration file - Web layer: Types, Routes, FrontController with auth + AutoRefresh layout - Controllers: Hubs (CRUD), Widgets (CRUD + versioning), InteractionEvents (JSON capture, canonical event_type validation), Annotations (threaded, append-only) - Sessions controller for IHP auth - Views: Hubs (index/show/new/edit), Widgets (index/show/new/edit), Annotations (index/new), Sessions (login) - widgetEnvelope helper with full data-* governance attributes - Integration tests: Hub CRUD, Widget versioning, event capture, append-only guard, annotation threading, validation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-27 01:42:43 +00:00
parent ff11913d5c
commit c560e541c7
26 changed files with 1591 additions and 12 deletions
--- a/Application/Helper/View.hs
+++ b/Application/Helper/View.hs
@@ -1,5 +1,44 @@
 module Application.Helper.View where

 import IHP.ViewPrelude
+import Generated.Types
+import Web.Types

-- Here you can add functions which are available in all your views
+-- | Widget Envelope — wraps any widget's rendered content with IHF governance metadata.
+--
+-- Every interactive element that is part of the governed widget registry should
+-- be wrapped with this helper. It injects the stable data-* attributes that the
+-- client-side event capture script reads to identify the widget without coupling
+-- to implementation details.
+--
+-- Usage:
+--
+-- @
+-- widgetEnvelope widget [hsx|
+--     <button>Click me</button>
+-- |]
+-- @
+--
+-- See docs/widget-envelope-convention.md for the full convention.
+widgetEnvelope :: Widget -> Html -> Html
+widgetEnvelope widget inner = [hsx|
+    <div
+        class="ihf-widget"
+        data-widget-id={tshow widget.id}
+        data-widget-type={widget.widgetType}
+        data-hub-id={tshow widget.hubId}
+        data-capability-ref={fromMaybe "" widget.capabilityRef}
+        data-view-context={fromMaybe "" widget.viewContext}
+        data-policy-scope={widget.policyScope}
+        data-widget-version={tshow widget.version}
+    >
+        {inner}
+        <div class="ihf-widget-controls mt-2">
+            <a href={WidgetAnnotationsAction { widgetId = widget.id }}
+               class="ihf-annotate-btn text-xs text-gray-400 hover:text-indigo-600 border border-gray-200
+                      rounded px-2 py-0.5 hover:border-indigo-300">
+                Annotate
+            </a>
+        </div>
+    </div>
+|]
--- a/Application/Migration/1743034800-ihf-phase1-initial-schema.sql
+++ b/Application/Migration/1743034800-ihf-phase1-initial-schema.sql
@@ -0,0 +1,92 @@
+-- IHF Phase 1 Initial Schema Migration
+-- Creates: users, hubs, widgets, widget_versions, interaction_events, annotations
+
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+
+CREATE TABLE users (
+    id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+    email TEXT NOT NULL UNIQUE,
+    password_hash TEXT NOT NULL,
+    name TEXT NOT NULL,
+    locked_at TIMESTAMP WITH TIME ZONE DEFAULT NULL,
+    failed_login_attempts INT NOT NULL DEFAULT 0,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
+);
+
+CREATE TABLE hubs (
+    id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+    slug TEXT NOT NULL UNIQUE,
+    name TEXT NOT NULL,
+    domain TEXT NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
+);
+
+CREATE TABLE widgets (
+    id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+    hub_id UUID NOT NULL REFERENCES hubs(id) ON DELETE RESTRICT,
+    name TEXT NOT NULL,
+    widget_type TEXT NOT NULL,
+    capability_ref TEXT,
+    view_context TEXT,
+    policy_scope TEXT NOT NULL DEFAULT 'internal',
+    status TEXT NOT NULL DEFAULT 'active',
+    version INT NOT NULL DEFAULT 1,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
+);
+
+CREATE TABLE widget_versions (
+    id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+    widget_id UUID NOT NULL REFERENCES widgets(id) ON DELETE CASCADE,
+    version INT NOT NULL,
+    schema_snapshot JSONB NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL,
+    UNIQUE (widget_id, version)
+);
+
+CREATE TABLE interaction_events (
+    id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+    widget_id UUID NOT NULL REFERENCES widgets(id) ON DELETE CASCADE,
+    event_type TEXT NOT NULL,
+    actor_id UUID,
+    actor_type TEXT NOT NULL DEFAULT 'user',
+    view_context_ref TEXT,
+    metadata JSONB DEFAULT '{}' NOT NULL,
+    occurred_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
+);
+
+CREATE INDEX interaction_events_widget_id_idx ON interaction_events (widget_id);
+CREATE INDEX interaction_events_occurred_at_idx ON interaction_events (occurred_at DESC);
+
+CREATE OR REPLACE FUNCTION prevent_interaction_event_mutation()
+RETURNS TRIGGER AS $$
+BEGIN
+    RAISE EXCEPTION 'interaction_events is append-only: UPDATE and DELETE are not permitted';
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER interaction_events_no_update
+    BEFORE UPDATE ON interaction_events
+    FOR EACH ROW EXECUTE FUNCTION prevent_interaction_event_mutation();
+
+CREATE TRIGGER interaction_events_no_delete
+    BEFORE DELETE ON interaction_events
+    FOR EACH ROW EXECUTE FUNCTION prevent_interaction_event_mutation();
+
+CREATE TABLE annotations (
+    id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+    widget_id UUID NOT NULL REFERENCES widgets(id) ON DELETE CASCADE,
+    parent_id UUID REFERENCES annotations(id) ON DELETE CASCADE,
+    body TEXT NOT NULL,
+    category TEXT NOT NULL DEFAULT 'friction',
+    actor_id UUID,
+    actor_type TEXT NOT NULL DEFAULT 'user',
+    widget_state_ref TEXT,
+    retracted_at TIMESTAMP WITH TIME ZONE DEFAULT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
+);
+
+CREATE INDEX annotations_widget_id_idx ON annotations (widget_id);
+
+-- Dev seed: one hub for local development
+INSERT INTO hubs (slug, name, domain)
+VALUES ('dev', 'Dev Hub', 'development');
--- a/Application/Schema.sql
+++ b/Application/Schema.sql
@@ -1 +1,96 @@
-- Your database schema. Use the Schema Designer at http://localhost:8001/ to add some tables.
+-- IHF Phase 1 Schema
+-- Hub, Widget, WidgetVersion, InteractionEvent, Annotation
+-- See workplans/IHUB-WP-0001-ihf-phase1-minimal-interaction-core.md
+
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+
+-- Users (T10 — authentication)
+CREATE TABLE users (
+    id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+    email TEXT NOT NULL UNIQUE,
+    password_hash TEXT NOT NULL,
+    name TEXT NOT NULL,
+    locked_at TIMESTAMP WITH TIME ZONE DEFAULT NULL,
+    failed_login_attempts INT NOT NULL DEFAULT 0,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
+);
+
+-- Hubs — bounded domains of responsibility
+CREATE TABLE hubs (
+    id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+    slug TEXT NOT NULL UNIQUE,
+    name TEXT NOT NULL,
+    domain TEXT NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
+);
+
+-- Widgets — smallest semantically governable interaction units
+CREATE TABLE widgets (
+    id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+    hub_id UUID NOT NULL REFERENCES hubs(id) ON DELETE RESTRICT,
+    name TEXT NOT NULL,
+    widget_type TEXT NOT NULL,
+    capability_ref TEXT,
+    view_context TEXT,
+    policy_scope TEXT NOT NULL DEFAULT 'internal',
+    status TEXT NOT NULL DEFAULT 'active',
+    version INT NOT NULL DEFAULT 1,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
+);
+
+-- Widget version history
+CREATE TABLE widget_versions (
+    id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+    widget_id UUID NOT NULL REFERENCES widgets(id) ON DELETE CASCADE,
+    version INT NOT NULL,
+    schema_snapshot JSONB NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL,
+    UNIQUE (widget_id, version)
+);
+
+-- Interaction events — append-only capture
+CREATE TABLE interaction_events (
+    id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+    widget_id UUID NOT NULL REFERENCES widgets(id) ON DELETE CASCADE,
+    event_type TEXT NOT NULL,
+    actor_id UUID,
+    actor_type TEXT NOT NULL DEFAULT 'user',
+    view_context_ref TEXT,
+    metadata JSONB DEFAULT '{}' NOT NULL,
+    occurred_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
+);
+
+CREATE INDEX interaction_events_widget_id_idx ON interaction_events (widget_id);
+CREATE INDEX interaction_events_occurred_at_idx ON interaction_events (occurred_at DESC);
+
+-- Enforce append-only on interaction_events
+CREATE OR REPLACE FUNCTION prevent_interaction_event_mutation()
+RETURNS TRIGGER AS $$
+BEGIN
+    RAISE EXCEPTION 'interaction_events is append-only: UPDATE and DELETE are not permitted';
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER interaction_events_no_update
+    BEFORE UPDATE ON interaction_events
+    FOR EACH ROW EXECUTE FUNCTION prevent_interaction_event_mutation();
+
+CREATE TRIGGER interaction_events_no_delete
+    BEFORE DELETE ON interaction_events
+    FOR EACH ROW EXECUTE FUNCTION prevent_interaction_event_mutation();
+
+-- Annotations — structured commentary, also append-only by convention
+CREATE TABLE annotations (
+    id UUID DEFAULT uuid_generate_v4() PRIMARY KEY NOT NULL,
+    widget_id UUID NOT NULL REFERENCES widgets(id) ON DELETE CASCADE,
+    parent_id UUID REFERENCES annotations(id) ON DELETE CASCADE,
+    body TEXT NOT NULL,
+    category TEXT NOT NULL DEFAULT 'friction',
+    actor_id UUID,
+    actor_type TEXT NOT NULL DEFAULT 'user',
+    widget_state_ref TEXT,
+    retracted_at TIMESTAMP WITH TIME ZONE DEFAULT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT now() NOT NULL
+);
+
+CREATE INDEX annotations_widget_id_idx ON annotations (widget_id);