create-safest-tools 0.2.0

package/template/console/operations/store.ts

@@ -0,0 +1,32 @@
+import { isOperationsWorkspaceSnapshot, operationsEvents } from "./events";
+import type { OperationsWorkspaceSnapshot } from "./types";
+
+const subscribers = new Set<() => void>();
+
+let snapshot: OperationsWorkspaceSnapshot = {
+  loading: true,
+  refreshing: false,
+  error: "",
+  canRead: false,
+  canOperate: false,
+  operations: null,
+  incidents: [],
+  filters: { state: "", severity: "" },
+  detail: { incidentId: null, loading: false, error: "", pendingAction: null, record: null },
+};
+
+window.addEventListener(operationsEvents.state, (event) => {
+  if (!(event instanceof CustomEvent) || !isOperationsWorkspaceSnapshot(event.detail)) return;
+  snapshot = event.detail;
+  for (const subscriber of subscribers) subscriber();
+});
+
+export function getOperationsWorkspaceSnapshot(): OperationsWorkspaceSnapshot { return snapshot; }
+export function setOperationsWorkspaceSnapshot(next: OperationsWorkspaceSnapshot | ((current: OperationsWorkspaceSnapshot) => OperationsWorkspaceSnapshot)): void {
+  snapshot = typeof next === "function" ? next(snapshot) : next;
+  for (const subscriber of subscribers) subscriber();
+}
+export function subscribeToOperationsWorkspace(callback: () => void): () => void {
+  subscribers.add(callback);
+  return () => subscribers.delete(callback);
+}

package/template/console/operations/types.ts

@@ -0,0 +1,107 @@
+export type OperationsPendingAction = "acknowledge" | "retry" | "resolve" | null;
+export type OperationsIncidentStateFilter = "" | "open" | "acknowledged" | "mitigated" | "resolved";
+export type OperationsIncidentSeverityFilter = "" | "info" | "low" | "medium" | "high" | "critical";
+
+export interface OperationsSnapshotCounts {
+  generatedAt: string;
+  routing: { failed: number; deadLetter: number };
+  actions: { retrying: number; terminalFailed: number };
+  notifications: { retrying: number; terminalFailed: number };
+  emails: { retrying: number; terminalFailed: number };
+  incidents: { open: number; acknowledged: number; highPriority: number };
+  deadLetters: OperationsDeadLetter[];
+  deliveryFailures: OperationsDeliveryFailure[];
+}
+
+export interface OperationsDeadLetter {
+  id: string;
+  jobType: string;
+  jobId?: string | null;
+  state: string;
+  errorCode?: string | null;
+  occurrenceCount: number;
+  lastSeenAt: string;
+}
+
+export interface OperationsDeliveryFailure {
+  id: string;
+  deliveryType: string;
+  reportReference: string;
+  status: string;
+  attemptCount: number;
+  errorCode?: string | null;
+  updatedAt: string;
+}
+
+export interface OperationsIncidentSummary {
+  id: string;
+  incidentKey: string;
+  severity: string;
+  category: string;
+  state: string;
+  title: string;
+  summary: string;
+  entityType?: string | null;
+  entityId?: string | null;
+  occurrenceCount: number;
+  firstSeenAt: string;
+  lastSeenAt: string;
+  acknowledgedBy?: string | null;
+  acknowledgedAt?: string | null;
+  resolvedBy?: string | null;
+  resolvedAt?: string | null;
+  resolutionSummary?: string | null;
+  metadata?: unknown;
+}
+
+export interface OperationsIncidentRecord {
+  incident: OperationsIncidentSummary;
+  deadLetters: Array<{
+    id: string;
+    jobType: string;
+    jobId?: string | null;
+    state: string;
+    errorCode?: string | null;
+    occurrenceCount: number;
+    lastSeenAt: string;
+  }>;
+  repairs: Array<{
+    id: string;
+    actionType: string;
+    entityType: string;
+    entityId: string;
+    state: string;
+    plannedBy?: string | null;
+    plannedAt: string;
+    appliedAt?: string | null;
+    errorCode?: string | null;
+  }>;
+}
+
+export interface OperationsFilters {
+  state: OperationsIncidentStateFilter;
+  severity: OperationsIncidentSeverityFilter;
+}
+
+export interface OperationsWorkspaceSnapshot {
+  loading: boolean;
+  refreshing: boolean;
+  error: string;
+  canRead: boolean;
+  canOperate: boolean;
+  operations: OperationsSnapshotCounts | null;
+  incidents: OperationsIncidentSummary[];
+  filters: OperationsFilters;
+  detail: {
+    incidentId: string | null;
+    loading: boolean;
+    error: string;
+    pendingAction: OperationsPendingAction;
+    record: OperationsIncidentRecord | null;
+  };
+}
+
+export interface OperationsResolutionInput {
+  resolutionCode: string;
+  summary: string;
+}

package/template/console/people/PeopleWorkspace.tsx

@@ -0,0 +1,81 @@
+import { useEffect, useState, useSyncExternalStore, type FormEvent } from "react";
+import { AnalystIdentity } from "../components/AnalystIdentity";
+import { PageHeader } from "../components/PageHeader";
+import { errorMessage, postJson, requestJson } from "../lib/http";
+import { relativeTime } from "../lib/format";
+import { getShellSnapshot, subscribeToShell } from "../shell/store";
+import type { InvitationResponse, PasswordResetResponse, PeopleResponse, WorkspaceInvitation, WorkspacePerson } from "./types";
+
+const roleNames: Record<string, string> = { reviewer: "Analyst", appeal_reviewer: "Appeal analyst", administrator: "Administrator", owner: "Infrastructure owner", auditor: "Auditor" };
+const roleName = (role: string): string => roleNames[role] ?? role.replaceAll("_", " ");
+
+async function copy(value: string): Promise<void> {
+  await navigator.clipboard.writeText(value);
+}
+
+export function PeopleWorkspace() {
+  const shell = useSyncExternalStore(subscribeToShell, getShellSnapshot, getShellSnapshot);
+  const [people, setPeople] = useState<WorkspacePerson[]>([]);
+  const [invitations, setInvitations] = useState<WorkspaceInvitation[]>([]);
+  const [email, setEmail] = useState("");
+  const [role, setRole] = useState("reviewer");
+  const [loading, setLoading] = useState(true);
+  const [pending, setPending] = useState("");
+  const [error, setError] = useState("");
+  const [inviteUrl, setInviteUrl] = useState("");
+  const [resetMessage, setResetMessage] = useState("");
+  const canManage = shell.session?.permissions.managePeople === true;
+  const isOwner = shell.session?.roles.includes("owner") === true;
+
+  const load = async (): Promise<void> => {
+    if (!canManage) { setPeople([]); setInvitations([]); setLoading(false); return; }
+    setError("");
+    try {
+      const result = await requestJson<PeopleResponse>("/v1/admin/people");
+      setPeople(Array.isArray(result.users) ? result.users : []);
+      setInvitations(Array.isArray(result.invitations) ? result.invitations : []);
+    } catch (cause) { setError(errorMessage(cause, "People could not be loaded.")); }
+    finally { setLoading(false); }
+  };
+
+  useEffect(() => { setLoading(true); setInviteUrl(""); setResetMessage(""); void load(); }, [shell.session?.actor.id, canManage]);
+
+  const invite = async (event: FormEvent<HTMLFormElement>): Promise<void> => {
+    event.preventDefault(); setPending("invite"); setError(""); setInviteUrl("");
+    try {
+      const result = await postJson<InvitationResponse>("/v1/admin/people", { email, role });
+      setInviteUrl(result.invitation.inviteUrl); setEmail(""); await load();
+    } catch (cause) { setError(errorMessage(cause, "The invitation could not be created.")); }
+    finally { setPending(""); }
+  };
+  const revoke = async (invitationId: string): Promise<void> => {
+    setPending(`revoke:${invitationId}`); setError("");
+    try { await requestJson(`/v1/admin/people/invitations/${encodeURIComponent(invitationId)}`, { method: "DELETE" }); await load(); }
+    catch (cause) { setError(errorMessage(cause, "The invitation could not be revoked.")); }
+    finally { setPending(""); }
+  };
+  const reset = async (personId: string): Promise<void> => {
+    setPending(`reset:${personId}`); setError(""); setResetMessage("");
+    try {
+      const result = await postJson<PasswordResetResponse>(`/v1/admin/people/${encodeURIComponent(personId)}/password-reset`, {});
+      setResetMessage(`Password reset instructions were sent to ${result.password_reset.email}.`);
+    }
+    catch (cause) { setError(errorMessage(cause, "The password reset email could not be sent.")); }
+    finally { setPending(""); }
+  };
+
+  return (
+    <div className="page-stack" data-react-slice="people-workspace">
+      <PageHeader titleId="people-title" title="People and roles" description="Invite teammates and manage workspace access.">
+        <div className="surface-buttons"><button className="secondary" type="button" disabled={loading} onClick={() => { setLoading(true); void load(); }}>Refresh</button></div>
+      </PageHeader>
+      <section className="surface people-surface" aria-labelledby="people-title">
+        <form className="invite-form" onSubmit={invite}><label>Email<input type="email" autoComplete="off" required value={email} onChange={(event) => setEmail(event.currentTarget.value)} /></label><label>Role<select value={role} onChange={(event) => setRole(event.currentTarget.value)}><option value="reviewer">Analyst</option><option value="appeal_reviewer">Appeal analyst</option><option value="auditor">Auditor</option>{isOwner ? <option value="administrator">Administrator</option> : null}</select></label><button className="primary" type="submit" disabled={pending === "invite"}>{pending === "invite" ? "Sending…" : "Send invitation"}</button></form>
+        {inviteUrl ? <div className="invite-result"><div><strong>Invitation sent</strong><small>The email contains this single-use link. You can also share it securely; it expires in seven days.</small></div><input value={inviteUrl} readOnly aria-label="Invitation link" /><button className="secondary" type="button" onClick={() => void copy(inviteUrl)}>Copy link</button></div> : null}
+        {resetMessage ? <p className="form-message" role="status">{resetMessage}</p> : null}
+        <div className="people-columns"><section><h2>Team</h2><div className="people-list" aria-busy={loading}>{loading ? <div className="skeleton-block" /> : people.length ? people.map((person) => { const privileged = person.roles.some((item) => item === "owner" || item === "administrator"); const canReset = isOwner || !privileged; return <article key={person.id}><AnalystIdentity analyst={{ displayName: person.displayName, avatarUrl: person.avatarUrl ?? null, avatarColor: "#315d4d" }} detail={person.email} /><span className="people-role">{person.roles.map(roleName).join(", ")}</span><small>{person.lastLoginAt ? `Last active ${relativeTime(person.lastLoginAt)}` : "Not signed in yet"}</small>{canReset ? <button className="secondary compact-button" type="button" disabled={pending === `reset:${person.id}`} onClick={() => void reset(person.id)}>{pending === `reset:${person.id}` ? "Sending…" : "Send password reset"}</button> : null}</article>; }) : <p className="people-empty">No team members found.</p>}</div></section><section><h2>Invitations</h2><div className="people-list">{invitations.length ? invitations.map((invitation) => <article key={invitation.id}><div><strong>{invitation.email}</strong><small>{roleName(invitation.role)} · {invitation.status}</small></div>{invitation.status === "pending" ? <button className="secondary compact-button" type="button" disabled={pending === `revoke:${invitation.id}`} onClick={() => void revoke(invitation.id)}>{pending === `revoke:${invitation.id}` ? "Revoking…" : "Revoke"}</button> : null}</article>) : <p className="people-empty">No pending invitations.</p>}</div></section></div>
+        <p className="error surface-error" role="alert">{error}</p>
+      </section>
+    </div>
+  );
+}

package/template/console/people/types.ts

@@ -0,0 +1,25 @@
+export interface WorkspacePerson {
+  id: string;
+  displayName: string;
+  email: string;
+  avatarUrl?: string | null;
+  roles: string[];
+  lastLoginAt?: string | null;
+}
+
+export interface WorkspaceInvitation {
+  id: string;
+  email: string;
+  role: string;
+  status: string;
+}
+
+export interface PeopleResponse {
+  users: WorkspacePerson[];
+  invitations: WorkspaceInvitation[];
+}
+
+export interface InvitationResponse { invitation: { inviteUrl: string } }
+export interface PasswordResetResponse {
+  password_reset: { delivery: "email"; email: string };
+}

package/template/console/profile/ProfileWorkspace.tsx

@@ -0,0 +1,136 @@
+import { useEffect, useState, useSyncExternalStore, type ChangeEvent, type FormEvent } from "react";
+import { AnalystAvatar } from "../components/AnalystIdentity";
+import { PageHeader } from "../components/PageHeader";
+import { errorMessage, putBinary, requestJson } from "../lib/http";
+import { getShellSnapshot, subscribeToShell } from "../shell/store";
+import type { ConsoleSession } from "../shell/types";
+import { dispatchProfileUpdated } from "./events";
+import type { ProfileResponse } from "./types";
+
+const maximumPictureBytes = 2 * 1024 * 1024;
+const acceptedPictureTypes = new Set(["image/jpeg", "image/png", "image/webp"]);
+const roleNames: Record<string, string> = { reviewer: "Analyst", appeal_reviewer: "Appeal analyst", administrator: "Administrator", owner: "Infrastructure owner", auditor: "Auditor" };
+const roleName = (role: string): string => roleNames[role] ?? role.replaceAll("_", " ");
+
+function accountSession(session: ConsoleSession | null): ConsoleSession | null {
+  return session?.actor.type === "operator_user" ? session : null;
+}
+
+export function ProfileWorkspace() {
+  const shell = useSyncExternalStore(subscribeToShell, getShellSnapshot, getShellSnapshot);
+  const profile = accountSession(shell.session);
+  const [displayName, setDisplayName] = useState("");
+  const [pending, setPending] = useState<"save" | "upload" | "remove" | "">("");
+  const [message, setMessage] = useState("");
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    setDisplayName(profile?.displayName ?? "");
+  }, [profile?.actor.id, profile?.displayName]);
+
+  useEffect(() => {
+    setMessage("");
+    setError("");
+  }, [profile?.actor.id]);
+
+  useEffect(() => {
+    const receiveAccountResult = (event: Event): void => {
+      if (!(event instanceof CustomEvent) || typeof event.detail?.profileMessage !== "string") return;
+      setMessage("");
+      setError(event.detail.profileMessage);
+    };
+    window.addEventListener("safest:auth:authenticated", receiveAccountResult);
+    return () => window.removeEventListener("safest:auth:authenticated", receiveAccountResult);
+  }, []);
+
+  const begin = (action: "save" | "upload" | "remove"): void => {
+    setPending(action);
+    setMessage("");
+    setError("");
+  };
+
+  const finish = (result: ProfileResponse, successMessage: string): void => {
+    dispatchProfileUpdated(result.profile);
+    setMessage(successMessage);
+  };
+
+  const save = async (event: FormEvent<HTMLFormElement>): Promise<void> => {
+    event.preventDefault();
+    if (!profile) return;
+    begin("save");
+    try {
+      const result = await requestJson<ProfileResponse>("/v1/account/profile", {
+        method: "PATCH",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ display_name: displayName }),
+      });
+      finish(result, "Profile saved.");
+    } catch (cause) {
+      setError(errorMessage(cause, "The profile could not be saved."));
+    } finally {
+      setPending("");
+    }
+  };
+
+  const upload = async (event: ChangeEvent<HTMLInputElement>): Promise<void> => {
+    const file = event.currentTarget.files?.[0];
+    event.currentTarget.value = "";
+    if (!file || !profile) return;
+    setMessage("");
+    setError("");
+    if (file.size > maximumPictureBytes) {
+      setError("Profile pictures must be 2 MB or smaller.");
+      return;
+    }
+    if (!acceptedPictureTypes.has(file.type)) {
+      setError("Use a JPEG, PNG, or WebP profile picture.");
+      return;
+    }
+    begin("upload");
+    try {
+      const result = await putBinary<ProfileResponse>("/v1/account/profile-picture", file, file.type);
+      finish(result, "Profile picture updated.");
+    } catch (cause) {
+      setError(errorMessage(cause, "The profile picture could not be uploaded."));
+    } finally {
+      setPending("");
+    }
+  };
+
+  const remove = async (): Promise<void> => {
+    if (!profile) return;
+    begin("remove");
+    try {
+      const result = await requestJson<ProfileResponse>("/v1/account/profile-picture", { method: "DELETE" });
+      finish(result, "Profile picture removed.");
+    } catch (cause) {
+      setError(errorMessage(cause, "The profile picture could not be removed."));
+    } finally {
+      setPending("");
+    }
+  };
+
+  return (
+    <div className="page-stack" data-react-slice="profile-workspace">
+      <PageHeader titleId="profile-title" title="My profile" description="Update how you appear in reviews and audit history." />
+      <section className="surface profile-surface" aria-labelledby="profile-title">
+        {profile ? <div className="profile-layout">
+          <div className="profile-photo-card">
+            <div className="profile-avatar-preview" aria-label="Current profile picture"><AnalystAvatar size="large" analyst={{ displayName: profile.displayName, avatarUrl: profile.avatarUrl ?? null, avatarColor: profile.profile?.avatarColor }} /></div>
+            <label className={`secondary upload-button${pending ? " disabled" : ""}`} aria-disabled={Boolean(pending)}>{pending === "upload" ? "Uploading…" : "Choose picture"}<input type="file" accept="image/jpeg,image/png,image/webp" disabled={Boolean(pending)} onChange={(event) => void upload(event)} /></label>
+            {profile.avatarUrl ? <button className="text-button" type="button" disabled={Boolean(pending)} onClick={() => void remove()}>{pending === "remove" ? "Removing…" : "Remove picture"}</button> : null}
+            <small>JPEG, PNG, or WebP. Maximum 2 MB.</small>
+          </div>
+          <form className="profile-form" onSubmit={save}>
+            <label>Full name<input autoComplete="name" maxLength={100} required value={displayName} onChange={(event) => setDisplayName(event.currentTarget.value)} /></label>
+            <label>Work email<input type="email" readOnly value={profile.email ?? ""} /></label>
+            <label>Workspace role<input readOnly value={profile.roles.map(roleName).join(", ")} /></label>
+            <button className="primary" type="submit" disabled={Boolean(pending) || displayName.trim() === profile.displayName}>{pending === "save" ? "Saving…" : "Save profile"}</button>
+          </form>
+        </div> : <div className="empty-product"><h2>Profile unavailable</h2><p>Sign in with a workspace account to manage a personal profile.</p></div>}
+        <p className="form-message" role="status">{message}</p>
+        <p className="error surface-error" role="alert">{error}</p>
+      </section>
+    </div>
+  );
+}

package/template/console/profile/events.ts

@@ -0,0 +1,9 @@
+import type { ConsoleSession } from "../shell/types";
+
+export const profileEvents = {
+  updated: "safest:profile:updated",
+} as const;
+
+export function dispatchProfileUpdated(profile: ConsoleSession): void {
+  window.dispatchEvent(new CustomEvent(profileEvents.updated, { detail: { profile } }));
+}

package/template/console/profile/types.ts

@@ -0,0 +1,6 @@
+import type { ConsoleSession } from "../shell/types";
+
+export interface ProfileResponse {
+  schema_version: "1";
+  profile: ConsoleSession;
+}

package/template/console/quality/QualityWorkspace.tsx

@@ -0,0 +1,87 @@
+import { useEffect, useRef, useState, useSyncExternalStore, type FormEvent, type ReactNode } from "react";
+import { readable, relativeTime } from "../lib/format";
+import { PageHeader } from "../components/PageHeader";
+import { dispatchClaimQualitySample, dispatchCloseQualitySample, dispatchOpenQualitySample, dispatchQualityRefresh, dispatchQualityReview } from "./events";
+import { getQualityWorkspaceSnapshot, subscribeToQualityWorkspace } from "./store";
+import type { QualityIssueCode, QualitySampleSummary } from "./types";
+
+function QualityRow({ sample }: { sample: QualitySampleSummary }) {
+  const status = sample.state === "complete" ? sample.agrees ? "agreed" : "disagreed" : sample.state;
+  return <article><div><strong>{sample.reportReference}</strong><small>{readable(sample.sampleReason)} · {readable(sample.aiOutcome || sample.aiRunStatus)} · {relativeTime(sample.selectedAt)}</small></div><span className={`badge${sample.agrees === false ? " urgent" : ""}`}>{readable(status)}</span><button className="secondary" type="button" onClick={() => dispatchOpenQualitySample(sample.id)}>{sample.state === "complete" ? "Inspect" : "Review"}</button></article>;
+}
+
+function Fact({ label, children }: { label: string; children: ReactNode }) {
+  return <><dt>{label}</dt><dd>{children || "—"}</dd></>;
+}
+
+export function QualityWorkspace() {
+  const snapshot = useSyncExternalStore(subscribeToQualityWorkspace, getQualityWorkspaceSnapshot, getQualityWorkspaceSnapshot);
+  const pending = snapshot.samples.filter((sample) => sample.state !== "complete").length;
+  return (
+    <div className="page-stack" data-react-slice="quality-workspace">
+      <PageHeader titleId="quality-title" title="AI quality" description="Compare sampled AI results with human review.">
+        <div className="surface-buttons"><button className="secondary" type="button" disabled={snapshot.refreshing || !snapshot.canRead} onClick={dispatchQualityRefresh}>{snapshot.refreshing ? "Refreshing…" : "Refresh"}</button></div>
+      </PageHeader>
+      <section className="surface quality-surface" aria-labelledby="quality-title">
+        <div className="quality-summary"><p>People review random autonomous decisions and shadow comparisons. A disagreement reopens the report and can pause the queue.</p><strong>{snapshot.loading ? "— pending" : `${pending} pending`}</strong></div>
+        <div className="quality-list" aria-busy={snapshot.loading || snapshot.refreshing}>{snapshot.loading ? <div className="skeleton-block" role="status" aria-label="Loading AI quality samples" /> : snapshot.samples.length ? snapshot.samples.map((sample) => <QualityRow sample={sample} key={sample.id} />) : <div className="empty compact"><h3>No quality reviews yet</h3><p>Reviews appear after AI decisions or shadow comparisons.</p></div>}</div>
+        <p className="error surface-error" role="alert">{snapshot.error}</p>
+      </section>
+    </div>
+  );
+}
+
+export function QualityDialog() {
+  const snapshot = useSyncExternalStore(subscribeToQualityWorkspace, getQualityWorkspaceSnapshot, getQualityWorkspaceSnapshot);
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const record = snapshot.detail.record;
+  const sample = record?.sample;
+  const report = record?.report;
+  const [agrees, setAgrees] = useState(true);
+  const [issueCode, setIssueCode] = useState<QualityIssueCode>("");
+  const [correctedOutcomeCode, setCorrectedOutcomeCode] = useState("");
+  const [correctedPolicyCode, setCorrectedPolicyCode] = useState("");
+  const [notes, setNotes] = useState("");
+  const complete = sample?.state === "complete";
+  const activeClaim = Boolean(sample?.claimedBy && sample.claimExpiresAt && Date.parse(sample.claimExpiresAt) > Date.parse(snapshot.generatedAt));
+  const mine = Boolean(activeClaim && sample?.claimedBy === snapshot.actorId);
+  const disabled = Boolean(complete || !mine || snapshot.detail.pendingAction === "review");
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (snapshot.detail.sampleId && !dialog.open) dialog.showModal();
+    if (!snapshot.detail.sampleId && dialog.open) dialog.close();
+  }, [snapshot.detail.sampleId]);
+  useEffect(() => {
+    setAgrees(sample?.agrees ?? true);
+    setIssueCode((sample?.issueCodes?.[0] as QualityIssueCode | undefined) ?? "");
+    setCorrectedOutcomeCode(sample?.correctedOutcomeCode ?? "");
+    setCorrectedPolicyCode(sample?.correctedPolicyCode ?? "");
+    setNotes(sample?.qualityNotes ?? "");
+  }, [snapshot.detail.sampleId, complete]);
+
+  const submit = (event: FormEvent<HTMLFormElement>): void => {
+    event.preventDefault();
+    dispatchQualityReview({ agrees, issueCode: agrees ? "" : issueCode, correctedOutcomeCode, correctedPolicyCode, notes });
+  };
+  const reportDetails = report?.answers.find((answer) => answer.fieldKey === "details")?.value;
+  const humanDecision = report?.decisions.find((decision) => decision.makerType === "human");
+  const claimMessage = complete
+    ? `Reviewed by ${sample?.qualityReviewerId || "a human reviewer"}: ${sample?.agrees ? "agreed" : "disagreed"}.`
+    : mine && sample?.claimExpiresAt
+      ? `Claimed by you until ${new Date(sample.claimExpiresAt).toLocaleTimeString()}.`
+      : activeClaim && sample?.claimExpiresAt
+        ? `Claimed by another reviewer until ${new Date(sample.claimExpiresAt).toLocaleTimeString()}.`
+        : "Claim this sample before recording a review.";
+
+  return (
+    <dialog ref={dialogRef} className="detail-dialog quality-dialog" aria-labelledby="quality-reference" onCancel={(event) => { event.preventDefault(); dispatchCloseQualitySample(); }} data-react-slice="quality-dialog">
+      <div className="detail-head"><div><h2 id="quality-reference">{sample?.reportReference || "AI sample"}</h2><p>{sample ? `${readable(sample.sampleReason)} · ${readable(sample.state)}` : snapshot.detail.loading ? "Loading sample…" : "AI quality review"}</p></div><button className="icon-button" type="button" aria-label="Close quality sample" onClick={dispatchCloseQualitySample}>×</button></div>
+      <div className="quality-detail-content">
+        {snapshot.detail.loading && !record ? <div className="skeleton-block" role="status" aria-label="Loading AI quality sample" /> : record && sample && report ? <><div className="detail-grid"><section><h3>Case and comparison</h3><dl><Fact label="Allegation">{readable(report.reasonCode)}</Fact><Fact label="Target">{readable(report.targetType)} · {report.targetReference}</Fact><Fact label="Report details">{typeof reportDetails === "string" ? reportDetails : "—"}</Fact><Fact label="AI outcome">{readable(sample.aiOutcome || "No outcome")} · {sample.aiPolicyCode || "no policy"}</Fact><Fact label="Human outcome">{humanDecision ? `${readable(humanDecision.decisionCode)} · ${humanDecision.policyCode || "no policy"}` : "Not recorded"}</Fact></dl></section><section><h3>AI provenance</h3><dl><Fact label="Configuration">{sample.configVersionId}</Fact><Fact label="Model">{sample.model}</Fact><Fact label="Prompt">{sample.promptVersion}</Fact><Fact label="Policy version">{sample.policyVersionId}</Fact><Fact label="Template">{sample.messageTemplateId || "None"}</Fact><Fact label="Evidence">{sample.aiEvidenceReferences?.join(", ") || "None"}</Fact></dl></section></div><section><h3>Validated AI output</h3><pre>{JSON.stringify(sample.rawOutput, null, 2)}</pre></section><div className="claim-bar"><p>{claimMessage}</p>{!complete && !activeClaim && snapshot.canDecide ? <button className="primary" type="button" disabled={snapshot.detail.pendingAction === "claim"} onClick={dispatchClaimQualitySample}>{snapshot.detail.pendingAction === "claim" ? "Claiming…" : "Claim sample"}</button> : null}</div><form className="quality-review-form" onSubmit={submit}><h3>Record comparison</h3><label>Assessment<select value={agrees ? "true" : "false"} disabled={disabled} onChange={(event) => { const next = event.currentTarget.value === "true"; setAgrees(next); if (next) setIssueCode(""); }}><option value="true">AI result agrees with human review</option><option value="false">AI result disagrees</option></select></label><label>Issue when disagreeing<select value={issueCode} required={!agrees} disabled={disabled || agrees} onChange={(event) => setIssueCode(event.currentTarget.value as QualityIssueCode)}><option value="">Select an issue</option><option value="incorrect_outcome">Incorrect outcome</option><option value="incorrect_policy_code">Incorrect policy code</option><option value="unsupported_evidence">Unsupported evidence</option><option value="unsafe_or_inaccurate_message">Unsafe or inaccurate message</option><option value="should_have_escalated">Should have escalated</option><option value="other">Other</option></select></label><label>Corrected outcome <small>Optional structured comparison.</small><input maxLength={100} value={correctedOutcomeCode} disabled={disabled} onChange={(event) => setCorrectedOutcomeCode(event.currentTarget.value)} /></label><label>Corrected policy code <small>Optional structured comparison.</small><input maxLength={100} value={correctedPolicyCode} disabled={disabled} onChange={(event) => setCorrectedPolicyCode(event.currentTarget.value)} /></label><label className="quality-notes">Review notes<textarea maxLength={4000} minLength={agrees ? undefined : 10} required={!agrees} value={notes} disabled={disabled} onChange={(event) => setNotes(event.currentTarget.value)} /></label><button className="primary" type="submit" disabled={disabled}>{snapshot.detail.pendingAction === "review" ? "Completing…" : "Complete quality review"}</button></form></> : null}
+        <p className="error" role="alert">{snapshot.detail.error}</p>
+      </div>
+    </dialog>
+  );
+}

package/template/console/quality/controller.ts

@@ -0,0 +1,154 @@
+import { errorMessage, mutationHeaders, requestJson } from "../lib/http";
+import { dispatchReportRefresh } from "../reports/events";
+import { getShellSnapshot, subscribeToShell } from "../shell/store";
+import { qualityEvents } from "./events";
+import { getQualityWorkspaceSnapshot, setQualityWorkspaceSnapshot } from "./store";
+import type { QualityDetailRecord, QualityReviewInput, QualitySampleSummary, QualityWorkspaceSnapshot } from "./types";
+
+interface QualityListResponse { samples: QualitySampleSummary[] }
+
+const initialSnapshot = (): QualityWorkspaceSnapshot => ({
+  loading: true,
+  refreshing: false,
+  error: "",
+  actorId: "",
+  generatedAt: new Date().toISOString(),
+  canRead: false,
+  canDecide: false,
+  samples: [],
+  detail: { sampleId: null, loading: false, error: "", pendingAction: null, record: null },
+});
+
+let actorId = "";
+let requestVersion = 0;
+let started = false;
+
+function permissions(snapshot: QualityWorkspaceSnapshot): QualityWorkspaceSnapshot {
+  const session = getShellSnapshot().session;
+  return {
+    ...snapshot,
+    actorId: session?.actor.id || "",
+    canRead: session?.permissions.readReports === true,
+    canDecide: session?.permissions.decideReports === true,
+    generatedAt: new Date().toISOString(),
+  };
+}
+
+async function loadSamples(): Promise<void> {
+  const session = getShellSnapshot().session;
+  if (!session?.permissions.readReports) {
+    setQualityWorkspaceSnapshot(permissions({ ...initialSnapshot(), loading: false }));
+    return;
+  }
+  const current = getQualityWorkspaceSnapshot();
+  setQualityWorkspaceSnapshot(permissions({ ...current, error: "", refreshing: !current.loading }));
+  try {
+    const result = await requestJson<QualityListResponse>("/v1/admin/ai/quality-samples?limit=50");
+    setQualityWorkspaceSnapshot((snapshot) => permissions({ ...snapshot, samples: result.samples || [] }));
+  } catch (cause) {
+    setQualityWorkspaceSnapshot((snapshot) => ({ ...snapshot, error: errorMessage(cause, "AI quality samples could not be loaded.") }));
+  } finally {
+    setQualityWorkspaceSnapshot((snapshot) => permissions({ ...snapshot, loading: false, refreshing: false }));
+  }
+}
+
+async function openSample(sampleId: string): Promise<void> {
+  const version = ++requestVersion;
+  setQualityWorkspaceSnapshot((snapshot) => permissions({
+    ...snapshot,
+    detail: {
+      ...snapshot.detail,
+      sampleId,
+      loading: true,
+      error: "",
+      record: snapshot.detail.record?.sample.id === sampleId ? snapshot.detail.record : null,
+    },
+  }));
+  try {
+    const record = await requestJson<QualityDetailRecord>(`/v1/admin/ai/quality-samples/${encodeURIComponent(sampleId)}`);
+    if (version !== requestVersion || getQualityWorkspaceSnapshot().detail.sampleId !== sampleId) return;
+    setQualityWorkspaceSnapshot((snapshot) => permissions({ ...snapshot, detail: { ...snapshot.detail, record } }));
+  } catch (cause) {
+    if (version !== requestVersion || getQualityWorkspaceSnapshot().detail.sampleId !== sampleId) return;
+    setQualityWorkspaceSnapshot((snapshot) => ({ ...snapshot, detail: { ...snapshot.detail, error: errorMessage(cause, "The AI quality sample could not be opened.") } }));
+  } finally {
+    if (version === requestVersion && getQualityWorkspaceSnapshot().detail.sampleId === sampleId) {
+      setQualityWorkspaceSnapshot((snapshot) => permissions({ ...snapshot, detail: { ...snapshot.detail, loading: false } }));
+    }
+  }
+}
+
+function closeSample(): void {
+  requestVersion += 1;
+  setQualityWorkspaceSnapshot((snapshot) => permissions({ ...snapshot, detail: { sampleId: null, loading: false, error: "", pendingAction: null, record: null } }));
+}
+
+async function claimSample(): Promise<void> {
+  const snapshot = getQualityWorkspaceSnapshot();
+  const sample = snapshot.detail.record?.sample;
+  if (!sample || !snapshot.canDecide || snapshot.detail.pendingAction) return;
+  setQualityWorkspaceSnapshot({ ...snapshot, detail: { ...snapshot.detail, error: "", pendingAction: "claim" } });
+  try {
+    await requestJson(`/v1/admin/ai/quality-samples/${encodeURIComponent(sample.id)}/claim`, { method: "POST" });
+    await openSample(sample.id);
+  } catch (cause) {
+    setQualityWorkspaceSnapshot((current) => ({ ...current, detail: { ...current.detail, error: errorMessage(cause, "The AI quality sample could not be claimed.") } }));
+  } finally {
+    setQualityWorkspaceSnapshot((current) => permissions({ ...current, detail: { ...current.detail, pendingAction: null } }));
+  }
+}
+
+async function recordReview(input: QualityReviewInput): Promise<void> {
+  const snapshot = getQualityWorkspaceSnapshot();
+  const sample = snapshot.detail.record?.sample;
+  const mine = Boolean(sample?.claimedBy === snapshot.actorId && sample.claimExpiresAt && Date.parse(sample.claimExpiresAt) > Date.now());
+  if (!sample || !snapshot.canDecide || snapshot.detail.pendingAction || !mine || sample.state === "complete") return;
+  setQualityWorkspaceSnapshot({ ...snapshot, detail: { ...snapshot.detail, error: "", pendingAction: "review" } });
+  try {
+    await requestJson(`/v1/admin/ai/quality-samples/${encodeURIComponent(sample.id)}/review`, {
+      method: "POST",
+      headers: mutationHeaders(),
+      body: JSON.stringify({
+        agrees: input.agrees,
+        issue_codes: input.agrees || !input.issueCode ? [] : [input.issueCode],
+        corrected_outcome_code: input.correctedOutcomeCode || null,
+        corrected_policy_code: input.correctedPolicyCode || null,
+        notes: input.notes,
+      }),
+    });
+    closeSample();
+    await loadSamples();
+    dispatchReportRefresh();
+  } catch (cause) {
+    setQualityWorkspaceSnapshot((current) => ({ ...current, detail: { ...current.detail, error: errorMessage(cause, "The AI quality review could not be recorded.") } }));
+  } finally {
+    setQualityWorkspaceSnapshot((current) => permissions({ ...current, detail: { ...current.detail, pendingAction: null } }));
+  }
+}
+
+export function startQualityController(): void {
+  if (started) return;
+  started = true;
+  subscribeToShell(() => {
+    const session = getShellSnapshot().session;
+    const nextActorId = session?.actor.id || "";
+    if (nextActorId === actorId) {
+      setQualityWorkspaceSnapshot((snapshot) => permissions(snapshot));
+      return;
+    }
+    actorId = nextActorId;
+    requestVersion += 1;
+    setQualityWorkspaceSnapshot(initialSnapshot());
+    if (session) void loadSamples();
+  });
+  window.addEventListener(qualityEvents.refresh, () => { void loadSamples(); });
+  window.addEventListener(qualityEvents.open, (event) => {
+    if (event instanceof CustomEvent && typeof event.detail?.sampleId === "string") void openSample(event.detail.sampleId);
+  });
+  window.addEventListener(qualityEvents.close, closeSample);
+  window.addEventListener(qualityEvents.claim, () => { void claimSample(); });
+  window.addEventListener(qualityEvents.review, (event) => {
+    if (!(event instanceof CustomEvent) || typeof event.detail?.agrees !== "boolean" || typeof event.detail?.issueCode !== "string" || typeof event.detail?.notes !== "string") return;
+    void recordReview(event.detail as QualityReviewInput);
+  });
+}