create-safest-tools 0.6.0 → 0.7.0

package/README.md

@@ -6,7 +6,7 @@ Safest Resolve accepts explicit reports from an embedded widget, a public page,
 
 ## Quick start
 
-You need Node.js 20.12+, a Cloudflare account with Workers, Dynamic Workflows, Worker Loaders, D1, R2, Queues, Durable Objects, and Workers AI available, plus an HTTPS hostname for the reports service.
+You need Node.js 22.13+, a Cloudflare account with Workers, Dynamic Workflows, Worker Loaders, D1, R2, Queues, Durable Objects, and Workers AI available, plus an HTTPS hostname for the reports service.
 
 ```bash
 npx create-safest-tools safest-resolve \
@@ -18,7 +18,7 @@ npx create-safest-tools safest-resolve \
   --email-from reports@example.com
 ```
 
-The `--email-from` address is a real, receivable mailbox used for receipts, follow-ups, outcomes, and replies from reporters or affected users. Use a short base address such as `reports@example.com` on a domain onboarded under Cloudflare Email Service → Email Sending, then enable Email Routing for that domain. Setup creates an exact Worker route for this address, enables plus-addressing for signed case replies, and does not enable catch-all mail. Account verification, invitations, and password recovery use a distinct `accounts@` address on the same domain by default; pass `--auth-email-from` to choose another address. Every customer-facing email automatically uses the organization name, logo, colors, type, and spacing saved under Configuration → Branding.
+The `--email-from` address is a real, receivable mailbox used for receipts, follow-ups, outcomes, and replies from reporters or affected users. Use a short base address such as `reports@example.com` on a domain onboarded under Cloudflare Email Service → Email Sending, then enable Email Routing for that domain. Setup creates an exact Worker route for this address, enables plus-addressing for signed case replies, and does not enable catch-all mail. Account verification, invitations, and password recovery use a distinct `accounts@` address on the same domain by default; pass `--auth-email-from` to choose another address. Every customer-facing email automatically uses the organization name, logo, colors, type, and spacing saved under Settings → Branding.
 
 The command creates a local project and prints a read-only infrastructure plan. It does not change Cloudflare unless `--deploy` is supplied or the generated project’s `npm run setup` command is run and explicitly confirmed.
 
@@ -46,7 +46,7 @@ npm run setup
 
 `setup:plan` lists exact resource names and the reporter email route, then exits without modifying Cloudflare. `setup` opens Wrangler's Cloudflare login when needed, lets you choose the owning account, and verifies Workers Paid from the account's Workers usage model. Standard accounts need no separate billing token; only legacy or ambiguous account models use the temporary Billing Read fallback. It then guides Google, GitHub, and Cloudflare OAuth configuration with exact callback URLs and masked secret input. Nothing is provisioned until the exact `DEPLOY <installation-id>` confirmation. After confirmation it verifies Email Routing, enables subaddressing, and deploys only the exact reporter-address route. If Cloudflare interrupts the deployment, run `npm run setup` again; it detects the unfinished installation, reuses the saved authentication choices and exact resources, suppresses expected already-exists errors, and continues through the owner-link step.
 
-A new installation applies one current D1 schema baseline. Later releases add only forward-compatible upgrade migrations.
+A new 0.6.1 installation applies one current D1 schema baseline. Later releases add only forward-compatible upgrade migrations. Because 0.6.1 replaces the earlier development migration chain with that baseline, the updater refuses to modify a deployed pre-0.6.1 project in place. Back up that deployment and create a separately named installation instead. Undeployed scaffolds may cross the boundary normally.
 
 After deployment, setup prints a 256-bit, single-use owner link that expires after 15 minutes. The raw token stays in the URL fragment, D1 stores only its digest, and the installer never writes it to disk. Open it to create the Safest owner account. If it expires, run `npm run owner:setup`. For later break-glass recovery, authenticate Wrangler and run `npm run owner:recover`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-safest-tools",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Create customer-owned abuse-reporting infrastructure on Cloudflare",
   "type": "module",
   "license": "Apache-2.0",
@@ -26,7 +26,7 @@
     "test": "node --test test/*.test.mjs"
   },
   "engines": {
-    "node": ">=20.12.0"
+    "node": ">=22.13.0"
   },
   "publishConfig": {
     "access": "public"

package/src/config.mjs

@@ -124,8 +124,8 @@ export function buildWranglerConfiguration(config) {
       class_name: "DynamicWorkflow",
       limits: { steps: 1000 },
     }],
-    durable_objects: { bindings: [{ name: "WORKSPACE_PRESENCE", class_name: "WorkspacePresence" }] },
-    exports: { WorkspacePresence: { type: "durable-object", storage: "sqlite" } },
+    durable_objects: { bindings: [{ name: "WORKSPACE_PRESENCE", class_name: "WorkspacePresence" }, { name: "CASE_INVESTIGATOR", class_name: "CaseInvestigator" }] },
+    exports: { WorkspacePresence: { type: "durable-object", storage: "sqlite" }, CaseInvestigator: { type: "durable-object", storage: "sqlite" } },
     d1_databases: [{ binding: "DB", database_name: config.resources.databaseName, migrations_dir: "migrations" }],
     queues: {
       producers: [

package/src/update.mjs

@@ -6,6 +6,7 @@ import { buildWranglerConfiguration } from "./config.mjs";
 
 const MANIFEST_PATH = ".safest-managed.json";
 const MANIFEST_SCHEMA_VERSION = 1;
+const FRESH_SCHEMA_BASELINE_VERSION = "0.6.1";
 const REBUILDABLE_PATHS = new Set(["public/console/auth-shell.js"]);
 const CUSTOMER_RUNTIME_VAR_KEYS = new Set([
   "ALLOWED_ACTION_CODES",
@@ -185,6 +186,15 @@ export async function planProjectUpdate({ directory, templateDirectory }) {
   if (compareVersions(targetVersion, manifest.installedVersion) < 0) {
     throw new Error(`refusing to downgrade Safest Resolve from ${manifest.installedVersion} to ${targetVersion}`);
   }
+  const deployed = (currentWrangler.d1_databases ?? []).some(({ database_id: id }) => typeof id === "string" && id.length > 0);
+  if (deployed
+    && compareVersions(manifest.installedVersion, FRESH_SCHEMA_BASELINE_VERSION) < 0
+    && compareVersions(targetVersion, FRESH_SCHEMA_BASELINE_VERSION) >= 0) {
+    throw new Error(
+      `Safest Resolve ${FRESH_SCHEMA_BASELINE_VERSION} starts a new fresh-install schema lineage. `
+      + `Back up this ${manifest.installedVersion} deployment, then create and verify a separately named installation instead of updating it in place.`,
+    );
+  }
 
   const added = [];
   const updated = [];
@@ -205,7 +215,6 @@ export async function planProjectUpdate({ directory, templateDirectory }) {
   if (!wranglerMatchesManifest(currentWrangler, manifest.wranglerHash)) conflicts.push("wrangler.jsonc");
 
   const desiredWrangler = mergeWranglerRuntimeState(buildWranglerConfiguration(reportsConfiguration), currentWrangler);
-  const deployed = (currentWrangler.d1_databases ?? []).some(({ database_id: id }) => typeof id === "string" && id.length > 0);
   const uniqueConflicts = [...new Set(conflicts)].sort();
   return {
     action: "update",

package/template/README.md

@@ -4,7 +4,7 @@ Safest Resolve handles abuse, safety, fraud, and policy reports in the Cloudflar
 
 The service does not proxy or inspect normal application traffic. The customer application remains responsible for the content references it provides and for carrying out any approved action.
 
-This project deploys one Worker, one D1 database, four private R2 buckets, a Dynamic Workflow, report and delivery Queues, an operations dead-letter Queue, a presence Durable Object, static assets, a Worker Loader, and a Workers AI binding. The Cloudflare account owner owns every secret, webhook, log, and retained row.
+This project deploys one Worker, one D1 database, four private R2 buckets, a Dynamic Workflow, report and delivery Queues, an operations dead-letter Queue, presence and case-investigator Durable Objects, static assets, a Worker Loader, and a Workers AI binding. The Cloudflare account owner owns every secret, webhook, log, and retained row.
 
 Before deployment:
 
@@ -14,7 +14,7 @@ Before deployment:
 4. Type the exact installation confirmation when setup requests it. After deployment, setup prints a 256-bit, single-use owner link that expires after 15 minutes and is never written to disk.
 5. Open the owner link, create the Safest owner account, then invite administrators and analysts from People. Nobody needs a Cloudflare account to sign in. Names and workspace roles are always displayed separately.
 
-Setup creates D1, four private R2 buckets, and three Queues, applies one current D1 schema baseline, and deploys the Worker with Dynamic Workflows. Later releases add only forward-compatible upgrade migrations. After owner setup, verify the `database`, `workflow_runtime`, `workers_ai`, `object_storage`, and `queues` setup features, then require an authenticated `GET /ready` response of 200. Public `GET /health` is liveness only. Better Auth owns password hashing, OAuth accounts, sessions, and one-time password-reset tokens in D1. Upgrades always back up D1 before migrations and deployment.
+Setup creates D1, four private R2 buckets, and three Queues, applies the current fresh-install D1 baseline, and deploys the Worker with Dynamic Workflows. Version 0.6.1 begins this schema lineage; the updater blocks deployed pre-0.6.1 projects from crossing it in place and directs operators to a verified backup plus separately named installation. Later releases add only forward-compatible migrations. After owner setup, verify the `database`, `workflow_runtime`, `workers_ai`, `object_storage`, and `queues` setup features, then require an authenticated `GET /ready` response of 200. Public `GET /health` is liveness only. Better Auth owns password hashing, OAuth accounts, sessions, and one-time password-reset tokens in D1. Upgrades always back up D1 before migrations and deployment.
 
 If the setup link expires, run `npm run owner:setup`. If the owner loses access later, authenticate Wrangler as the Cloudflare account owner and run `npm run owner:recover`; the resulting single-use link creates a 12-hour break-glass session and is recorded in the audit log.
 

package/template/console/README.md

@@ -6,10 +6,10 @@ The console uses React, TypeScript, and Vite. Each product area keeps its DOM, t
 
 - **Account access:** sign-in, infrastructure-owner bootstrap, password reset, invitation acceptance, and optional profile-picture upload.
 - **Workspace shell:** header, responsive navigation, current route, health, analyst identity, and permission-aware navigation.
-- **Command centre:** metrics, work that needs attention, queue pressure, recent workflow runs, and setup actions.
+- **Command centre:** an SLA-aware review queue, reviewer availability, queue health, operational health, and the next best action.
 - **Reports and appeals:** queue filters, presence, claims, participant messages, decisions, delivery history, workflow evidence, and separate appeal ownership.
 - **Queues and workflows:** queue policy publication, routing rollout, workflow drafts, graph editing, checks, fixture tests, publishing, and queue pins.
-- **Components and configuration:** component and connection records, outbound allowlists, intake forms, routing rules, decision policies, message templates, and the visual form builder.
+- **Tools, connections, and configuration:** reusable workflow capabilities, governed outbound routes, intake forms, routing rules, decision policies, message templates, and the visual form builder. Runtime APIs and database tables retain the stable `component` name for backward compatibility.
 - **Operations and quality:** AI samples, reviewer corrections, incidents, retries, dead-letter evidence, analytics, audit verification, and CSV export.
 - **People and settings:** invitations, password-reset emails, roles, personal profiles, deployment checks, branding, and reporting channels.
 - **Ask Safest:** scoped conversations, citations, read-only activity, and links back to reports.

package/template/console/analytics/AnalyticsWorkspace.tsx

@@ -1,15 +1,18 @@
 import { useSyncExternalStore } from "react";
 import { PageHeader } from "../components/PageHeader";
 import { readable } from "../lib/format";
+import { dispatchReportFilters } from "../reports/events";
+import { dispatchNavigation } from "../shell/events";
+import { getShellSnapshot, subscribeToShell } from "../shell/store";
 import { dispatchAnalyticsPeriod, dispatchAnalyticsRefresh, dispatchAuditVerification, dispatchReportExport } from "./events";
 import { getAnalyticsWorkspaceSnapshot, subscribeToAnalyticsWorkspace } from "./store";
 import type { AnalyticsSeriesRow } from "./types";
 
-function metricTotal(series: AnalyticsSeriesRow[], metricKey: string, dimensionKey: string): number {
-  return series.filter((row) => row.metricKey === metricKey && row.dimensionKey === dimensionKey)
-    .reduce((sum, row) => sum + Number(row.value || 0), 0);
+function totals(series: AnalyticsSeriesRow[], metric: string, dimension: string): Array<[string, number]> {
+  const values = new Map<string, number>();
+  for (const row of series) if (row.metricKey === metric && row.dimensionKey === dimension) values.set(row.dimensionValue, (values.get(row.dimensionValue) || 0) + Number(row.value || 0));
+  return [...values].sort((a,b) => b[1]-a[1]);
 }
-
 function readableDuration(seconds: number | null): string {
   if (seconds === null) return "—";
   if (seconds < 60) return `${seconds}s`;
@@ -17,39 +20,49 @@ function readableDuration(seconds: number | null): string {
   if (seconds < 86400) return `${Math.round(seconds / 3600)}h`;
   return `${Math.round(seconds / 86400)}d`;
 }
-
+function Breakdown({ rows, empty }: { rows: Array<[string, number]>; empty: string }) {
+  return <div className="analytics-list">{rows.length ? rows.map(([label,count]) => <div key={label}><span>{label}</span><strong>{count}</strong></div>) : <p>{empty}</p>}</div>;
+}
 export function AnalyticsWorkspace() {
   const snapshot = useSyncExternalStore(subscribeToAnalyticsWorkspace, getAnalyticsWorkspaceSnapshot, getAnalyticsWorkspaceSnapshot);
+  const shell = useSyncExternalStore(subscribeToShell, getShellSnapshot, getShellSnapshot);
   const analytics = snapshot.analytics;
-  const received = analytics ? metricTotal(analytics.series, "reports_received", "source") : 0;
-  const decisions = analytics ? metricTotal(analytics.series, "decisions", "maker_type") : 0;
-  const backlog = analytics?.backlog.reduce((sum, row) => sum + Number(row.count || 0), 0) ?? 0;
-  const reasons = new Map<string, number>();
-  for (const row of analytics?.series ?? []) {
-    if (row.metricKey === "reports_received" && row.dimensionKey === "reason") reasons.set(row.dimensionValue, (reasons.get(row.dimensionValue) ?? 0) + Number(row.value || 0));
-  }
-  const reasonRows = [...reasons.entries()].sort((left, right) => right[1] - left[1]);
-
-  return (
-    <div className="page-stack" data-react-slice="analytics-workspace">
-      <PageHeader titleId="analytics-title" title="Reports and outcomes" description="Review report volume, decisions, backlogs, and audit checks.">
-        <div className="surface-buttons">
-          {snapshot.canVerifyAudit ? <button className="secondary" type="button" disabled={snapshot.auditPending} onClick={dispatchAuditVerification}>{snapshot.auditPending ? "Verifying…" : "Verify audit"}</button> : null}
-          {snapshot.canExport ? <button className="secondary" type="button" disabled={snapshot.exportPending} onClick={dispatchReportExport}>{snapshot.exportPending ? "Exporting…" : "Export CSV"}</button> : null}
-          <button className="secondary" type="button" disabled={snapshot.refreshing || !snapshot.canRead} onClick={dispatchAnalyticsRefresh}>{snapshot.refreshing ? "Refreshing…" : "Refresh"}</button>
-        </div>
-      </PageHeader>
-      <section className="surface analytics-surface" aria-labelledby="analytics-title">
-        <div className="surface-head analytics-toolbar"><div><h2>Last {snapshot.days} days</h2><p>Counts describe reports and recorded decisions, not verified incidents.</p></div><label>Period<select value={snapshot.days} onChange={(event) => dispatchAnalyticsPeriod(Number(event.currentTarget.value))}><option value="7">7 days</option><option value="30">30 days</option><option value="90">90 days</option><option value="180">180 days</option><option value="365">365 days</option></select></label></div>
-        <div className="analytics-metrics" aria-busy={snapshot.loading || snapshot.refreshing}>
-          <article><span>Reports received</span><strong>{snapshot.loading ? "—" : received}</strong><small>Allegations, not confirmed incidents</small></article>
-          <article><span>Decisions recorded</span><strong>{snapshot.loading ? "—" : decisions}</strong><small>Human and bounded AI</small></article>
-          <article><span>Median resolution</span><strong>{snapshot.loading ? "—" : readableDuration(analytics?.resolutionSeconds.median ?? null)}</strong><small>{snapshot.loading ? "P95 —" : `P95 ${readableDuration(analytics?.resolutionSeconds.p95 ?? null)}`}</small></article>
-          <article><span>Open backlog</span><strong>{snapshot.loading ? "—" : backlog}</strong><small>Across visible operational states</small></article>
-        </div>
-        {snapshot.loading ? <div className="skeleton-block" role="status" aria-label="Loading reports and outcomes" /> : <div className="analytics-body"><div><h3>Reports by allegation</h3><div className="analytics-list">{reasonRows.length ? reasonRows.map(([reason, count]) => <div key={reason}><span>{readable(reason)}</span><strong>{count}</strong></div>) : <p>No report reasons were recorded in this period.</p>}</div></div><div><h3>Safeguards</h3><p className="audit-verification">{snapshot.auditVerification}</p><ul>{(analytics?.limitations ?? []).map((limitation) => <li key={limitation}>{limitation}</li>)}</ul></div></div>}
-        <p className="error surface-error" role="alert">{snapshot.error}</p>
-      </section>
-    </div>
-  );
+  const series = analytics?.series || [];
+  const received = totals(series, "reports_received", "source").reduce((sum,[,count]) => sum+count,0);
+  const makers = totals(series, "decisions", "maker_type");
+  const decisions = makers.reduce((sum,[,count]) => sum+count,0);
+  const backlog = analytics?.backlog.reduce((sum,row) => sum+Number(row.count || 0),0) ?? 0;
+  const coverage = analytics?.evidenceCoverage;
+  const number = (value: number | undefined) => snapshot.loading || !analytics ? "—" : value ?? 0;
+  return <div className="page-stack insights-workspace" data-react-slice="analytics-workspace">
+    <PageHeader titleId="analytics-title" title="Insights" description="See what needs attention, what was decided, and which outcomes were confirmed.">
+      <div className="surface-buttons">
+        {snapshot.canVerifyAudit ? <button className="secondary" type="button" disabled={snapshot.auditPending} onClick={dispatchAuditVerification}>{snapshot.auditPending ? "Verifying…" : "Verify audit"}</button> : null}
+        {snapshot.canExport ? <button className="secondary" type="button" disabled={snapshot.exportPending} onClick={dispatchReportExport}>{snapshot.exportPending ? "Exporting…" : "Export CSV"}</button> : null}
+        <button className="secondary" type="button" disabled={snapshot.refreshing || !snapshot.canRead} onClick={dispatchAnalyticsRefresh}>{snapshot.refreshing ? "Refreshing…" : "Refresh"}</button>
+      </div>
+    </PageHeader>
+    <section className="surface analytics-surface" aria-labelledby="analytics-title">
+      <div className="surface-head analytics-toolbar"><div><h2>Last {snapshot.days} days</h2><p>{analytics?.queueScope ? "Cases in your permitted queues." : "Cases across your workspace."} {analytics ? `Updated ${new Date(analytics.generatedAt).toLocaleTimeString()}.` : "Loading recorded outcomes."}</p></div><label>Period<select value={snapshot.days} onChange={event => dispatchAnalyticsPeriod(Number(event.currentTarget.value))}><option value="7">7 days</option><option value="30">30 days</option><option value="90">90 days</option><option value="180">180 days</option><option value="365">365 days</option></select></label></div>
+      <div className="analytics-metrics" aria-busy={snapshot.loading || snapshot.refreshing}>
+        <article><span>Cases received</span><strong>{number(received)}</strong><small>Recorded allegations</small></article>
+        <article><span>Decisions recorded</span><strong>{number(decisions)}</strong><small>{makers.length ? makers.map(([maker,count]) => `${count} ${readable(maker).toLowerCase()}`).join(" · ") : "No decisions in this period"}</small></article>
+        <article><span>Median resolution</span><strong>{snapshot.loading ? "—" : readableDuration(analytics?.resolutionSeconds.median ?? null)}</strong><small>{analytics?.resolutionSeconds.count ?? 0} resolved cases · P95 {readableDuration(analytics?.resolutionSeconds.p95 ?? null)}</small></article>
+        <article><span>Open backlog</span><strong>{number(backlog)}</strong><small>Current work, across all dates</small></article>
+      </div>
+      <p className="error surface-error" role="alert">{snapshot.error}</p>
+    </section>
+    {snapshot.loading ? <div className="skeleton-block" role="status" aria-label="Loading Insights" /> : analytics ? <>
+      <div className="insights-grid">
+        <section className="surface insights-panel"><h2>Evidence and uncertainty</h2><p>Of {coverage?.receivedCases ?? 0} cases received in this period.</p><Breakdown rows={[["With available retrieved evidence",coverage?.withRetrievedEvidence ?? 0],["With unavailable, invalid or expired findings",coverage?.withEvidenceGaps ?? 0],["With recorded uncertainty",coverage?.withRecordedUncertainty ?? 0]]} empty="No cases in this period." /><small>These groups can overlap. A stored finding is evidence to review, not proof of a violation.</small></section>
+        <section className="surface insights-panel"><h2>Decision outcomes</h2><p>Includes each recorded decision, including revised decisions.</p><Breakdown rows={totals(series,"decisions","outcome").map(([code,count]) => [readable(code),count])} empty="No decisions have been recorded in this period." /></section>
+        <section className="surface insights-panel"><h2>Customer actions</h2><p>Proposals and customer acknowledgements remain distinct.</p><Breakdown rows={(analytics?.actions || []).map(row => [`${row.pipeline === "playbook" ? "Playbook" : "Direct review"} · ${readable(row.state)}`,row.count])} empty="No customer actions were proposed in this period." />{shell.session?.permissions.readOperations ? <button type="button" className="text-button" onClick={() => dispatchNavigation("operations")}>Inspect delivery and recovery</button> : null}</section>
+        <section className="surface insights-panel"><h2>Participant notices</h2><p>Delivery is tracked separately for each audience.</p><Breakdown rows={(analytics?.notices || []).map(row => [`${row.audience === "affected_user" ? "Affected person" : "Reporter"} · ${row.state === "suppressed" ? "No delivery channel" : readable(row.state)}`,row.count])} empty="No participant notices were created in this period." /><small>Delivered means handed to the configured provider. Reading is not measured.</small></section>
+        <section className="surface insights-panel"><h2>Independent appeals</h2><p>Appeals filed in this period, by their current state.</p><Breakdown rows={(analytics?.appeals || []).map(row => [readable(row.state),row.count])} empty="No appeals were filed in this period." />{shell.session?.permissions.reviewAppeals ? <button type="button" className="text-button" onClick={() => dispatchNavigation("appeals")}>Open appeals</button> : null}</section>
+        <section className="surface insights-panel"><h2>Quality review coverage</h2><p>Completed reviews out of selected samples, by selection reason.</p><div className="analytics-list">{analytics?.audits?.length ? analytics.audits.map(row => <div key={row.reason}><span>{readable(row.reason)}</span><strong>{row.reviewed} / {row.selected}</strong></div>) : <p>No quality samples were selected in this period.</p>}</div><small>Sampling and appeal outcomes do not establish an overall accuracy score.</small>{shell.session?.permissions.reviewQuality ? <button type="button" className="text-button" onClick={() => dispatchNavigation("ai-quality")}>Review samples</button> : null}</section>
+      </div>
+      <section className="surface insights-panel"><h2>Work waiting now</h2><p>Open a queue to work on the cases behind these counts.</p><div className="insights-backlog">{analytics?.backlog.length ? analytics.backlog.map(row => <button className="secondary" type="button" key={`${row.queueId}:${row.state}`} onClick={() => { dispatchReportFilters({ search:"", queueId:row.queueId || "", priority:"", age:"", state:row.state, sort:"oldest", ownership:"" }); dispatchNavigation("reports"); }}><span>{row.queueName || "Unassigned"}<small>{readable(row.state)} · oldest {readableDuration(row.oldestAgeSeconds ?? null)}</small></span><strong>{row.count}</strong></button>) : <p>No open backlog in your queue scope.</p>}</div></section>
+      <section className="surface insights-panel"><h2>How to read these numbers</h2><Breakdown rows={totals(series,"reports_received","reason").map(([reason,count]) => [readable(reason),count])} empty="No allegations recorded in this period." /><p className="audit-verification">{snapshot.auditVerification}</p><ul>{(analytics?.limitations || []).map(limitation => <li key={limitation}>{limitation}</li>)}</ul></section>
+    </> : <section className="surface insights-panel"><h2>Insights are unavailable</h2><p>Use Refresh to try loading the recorded outcomes again.</p></section>}
+  </div>;
 }

package/template/console/analytics/controller.ts

@@ -31,7 +31,9 @@ const initialSnapshot = (): AnalyticsWorkspaceSnapshot => ({
 });
 
 let actorId = "";
+let accessKey = "";
 let started = false;
+let requestVersion = 0;
 
 function withPermissions(snapshot: AnalyticsWorkspaceSnapshot): AnalyticsWorkspaceSnapshot {
   const permissions = getShellSnapshot().session?.permissions;
@@ -44,10 +46,12 @@ function withPermissions(snapshot: AnalyticsWorkspaceSnapshot): AnalyticsWorkspa
 }
 
 function reset(): void {
+  requestVersion += 1;
   setAnalyticsWorkspaceSnapshot(initialSnapshot());
 }
 
 async function loadAnalytics(): Promise<void> {
+  const version = ++requestVersion;
   const session = getShellSnapshot().session;
   if (!session?.permissions.readAnalytics) {
     setAnalyticsWorkspaceSnapshot(withPermissions({ ...initialSnapshot(), loading: false }));
@@ -57,11 +61,13 @@ async function loadAnalytics(): Promise<void> {
   setAnalyticsWorkspaceSnapshot(withPermissions({ ...current, error: "", refreshing: !current.loading }));
   try {
     const result = await requestJson<AnalyticsResponse>(`/v1/admin/analytics?days=${current.days}`);
+    if (version !== requestVersion) return;
     setAnalyticsWorkspaceSnapshot((snapshot) => withPermissions({ ...snapshot, analytics: result.analytics }));
   } catch (cause) {
+    if (version !== requestVersion) return;
     setAnalyticsWorkspaceSnapshot((snapshot) => ({ ...snapshot, error: errorMessage(cause, "Analytics could not be loaded.") }));
   } finally {
-    setAnalyticsWorkspaceSnapshot((snapshot) => withPermissions({ ...snapshot, loading: false, refreshing: false }));
+    if (version === requestVersion) setAnalyticsWorkspaceSnapshot((snapshot) => withPermissions({ ...snapshot, loading: false, refreshing: false }));
   }
 }
 
@@ -112,11 +118,13 @@ export function startAnalyticsController(): void {
   subscribeToShell(() => {
     const session = getShellSnapshot().session;
     const nextActorId = session?.actor.id || "";
-    if (nextActorId === actorId) {
+    const nextAccessKey = JSON.stringify([nextActorId, session?.queueScope, session?.permissions.readAnalytics]);
+    if (nextActorId === actorId && nextAccessKey === accessKey) {
       setAnalyticsWorkspaceSnapshot((snapshot) => withPermissions(snapshot));
       return;
     }
     actorId = nextActorId;
+    accessKey = nextAccessKey;
     reset();
     if (session) void loadAnalytics();
   });

package/template/console/analytics/types.ts

@@ -8,6 +8,7 @@ export interface AnalyticsSeriesRow {
 
 export interface AnalyticsBacklogRow {
   queueId?: string | null;
+  queueName?: string | null;
   state: string;
   count: number;
   oldestAgeSeconds?: number | null;
@@ -20,6 +21,12 @@ export interface AnalyticsRecord {
   series: AnalyticsSeriesRow[];
   backlog: AnalyticsBacklogRow[];
   resolutionSeconds: { count: number; median: number | null; p90: number | null; p95: number | null };
+  queueScope?: string[] | null;
+  evidenceCoverage: { receivedCases: number; withRetrievedEvidence: number; withEvidenceGaps: number; withRecordedUncertainty: number };
+  actions: Array<{ pipeline: string; state: string; count: number }>;
+  notices: Array<{ audience: string; state: string; count: number }>;
+  appeals: Array<{ state: string; count: number }>;
+  audits: Array<{ reason: string; selected: number; reviewed: number }>;
   limitations: string[];
 }
 

package/template/console/appeals/AppealFollowup.tsx

@@ -0,0 +1,171 @@
+import { useEffect, useRef, useState, type FormEvent } from "react";
+import { dateTime, readable, safeCustomerUrl } from "../lib/format";
+import { ApiRequestError, errorMessage, mutationHeaders, requestJson } from "../lib/http";
+import { dispatchAppealRefresh } from "./events";
+import type { AppealRecord } from "./types";
+import { useAppealDraftGuard } from "./useAppealDraftGuard";
+import "./appeal-corrections.css";
+
+type Field = { type: string; title?: string; description?: string; enum?: Array<string | number>; minLength?: number; maxLength?: number; minimum?: number; maximum?: number };
+type Capability = { id: string; name: string; actionCode: string; inputSchema: { properties: Record<string, Field>; required?: string[] } };
+type Original = { sourceKey: string; operationId: string; actionCode: string; state: string; target: Record<string, unknown>; capabilityIds: string[] };
+type Correction = { id: string; sourceKey: string; mode: string; assignedOperatorName: string; assignedOperatorId: string; dueAt: string; instructions: string; verifiedAt: string | null; verifiedBy: string | null; evidenceReference: string | null; evidenceNote: string | null; state: string | null; acceptedAt: string | null; lastErrorCode: string | null; deliveryTerminal: number; operationId: string | null; actionCode: string | null };
+type Snapshot = { canApprove: boolean; originals: Original[]; capabilities: Capability[]; owners: Array<{ id: string; displayName: string }>; corrections: Correction[] };
+const localDeadline = () => { const date = new Date(Date.now() + 86400000); return new Date(date.getTime() - date.getTimezoneOffset() * 60000).toISOString().slice(0, 16); };
+const endpoint = (appealId: string) => `/v1/admin/appeals/${encodeURIComponent(appealId)}/corrections`;
+
+function customerItemUrl(value: unknown): URL | null {
+  if (typeof value !== "string") return null;
+  try {
+    const safeUrl = safeCustomerUrl(value);
+    if (!safeUrl) return null;
+    const url = new URL(safeUrl);
+    return !url.username && !url.password ? url : null;
+  } catch { return null; }
+}
+
+function customerFacts(value: unknown, path: string[] = [], depth = 0): Array<{ label: string; value: string }> {
+  if (value === null || value === undefined || depth > 4) return [];
+  if (typeof value === "object") {
+    return Object.entries(value).slice(0, 20).flatMap(([key, child]) => customerFacts(child, [...path, Array.isArray(value) ? `Item ${Number(key) + 1}` : readable(key)], depth + 1)).slice(0, 20);
+  }
+  if (!["string", "number", "boolean"].includes(typeof value)) return [];
+  return [{ label: path.join(" / "), value: typeof value === "boolean" ? value ? "Yes" : "No" : String(value) }];
+}
+
+function CorrectionTarget({ target }: { target: Original["target"] }) {
+  const itemUrl = customerItemUrl(target.customer_url);
+  const fields = [
+    { label: "Item type", value: typeof target.type === "string" ? readable(target.type) : "" },
+    { label: "Item reference", value: typeof target.reference === "string" ? target.reference : "" },
+    { label: "Owner reference", value: typeof target.owner_reference === "string" ? target.owner_reference : "" },
+  ].filter(field => field.value);
+  const facts = customerFacts(target.signed_facts);
+  return <div className="appeal-target-summary" role="group" aria-label="Original customer item">
+    <dl className="appeal-target-fields">{fields.map(field => <div key={field.label}><dt>{field.label}</dt><dd>{field.value}</dd></div>)}</dl>
+    {itemUrl && <p className="appeal-target-link"><a href={itemUrl.href} target="_blank" rel="noopener noreferrer" aria-label="Open customer item (opens in a new tab)">Open customer item</a><span>{itemUrl.host}</span></p>}
+    {facts.length > 0 && <details className="appeal-target-facts"><summary>Customer context</summary><dl className="appeal-target-fields">{facts.map((fact, index) => <div key={`${fact.label}:${index}`}><dt>{fact.label}</dt><dd>{fact.value}</dd></div>)}</dl></details>}
+  </div>;
+}
+
+function CorrectionPlan({ appealId, original, snapshot, actorId, refresh }: { appealId: string; original: Original; snapshot: Snapshot; actorId: string; refresh: () => void }) {
+  const capabilities = snapshot.capabilities.filter(item => original.capabilityIds.includes(item.id));
+  const [method, setMethod] = useState(capabilities[0]?.id ?? "manual");
+  const [owner, setOwner] = useState(snapshot.owners.some(person => person.id === actorId) ? actorId : "");
+  const [deadline, setDeadline] = useState(localDeadline);
+  const [instructions, setInstructions] = useState("");
+  const [payload, setPayload] = useState<Record<string, string | number | boolean>>({});
+  const [approved, setApproved] = useState(false);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState("");
+  const key = useRef(crypto.randomUUID());
+  const capability = capabilities.find(item => item.id === method);
+  useAppealDraftGuard(true, Boolean(instructions || Object.keys(payload).length), pending);
+  // React clears currentTarget after the handler. Capture primitive values before
+  // enqueueing a functional update, which may run after the event has returned.
+  const changePayload = (name: string, value: string, type: string) => {
+    const converted = type === "boolean" ? value === "true" : type === "string" ? value : Number(value);
+    setPayload(previous => {
+      const next = { ...previous };
+      if (value === "" && type !== "string") delete next[name];
+      else next[name] = converted;
+      return next;
+    });
+  };
+
+  const submit = async (event: FormEvent) => {
+    event.preventDefault(); if (pending) return; setPending(true); setError("");
+    try {
+      await requestJson(endpoint(appealId), { method: "POST", headers: { ...mutationHeaders(), "idempotency-key": key.current }, body: JSON.stringify({ source_key: original.sourceKey, mode: capability ? "automated" : "manual", component_version_id: capability?.id, payload: capability ? payload : undefined, assigned_operator_id: owner, due_at: new Date(deadline).toISOString(), instructions, approved }) });
+      setInstructions(""); setPayload({}); refresh();
+    } catch (cause) {
+      if (cause instanceof ApiRequestError && cause.status >= 400 && cause.status < 500) key.current = crypto.randomUUID();
+      setError(errorMessage(cause, "The correction could not be approved. Your entries are still here."));
+    } finally { setPending(false); }
+  };
+  return <form className="appeal-correction-form" onSubmit={event => void submit(event)}>
+    <label>How will this be corrected?<select value={method} disabled={pending} onChange={event => { setMethod(event.currentTarget.value); setPayload({}); setApproved(false); }}>
+      {capabilities.map(item => <option key={item.id} value={item.id}>{item.name}</option>)}<option value="manual">Arrange and verify a manual correction</option>
+    </select></label>
+    {!capabilities.length && <p>No compatible automated correction is configured for this action. Assign someone to complete it in the customer application.</p>}
+    {capability && <><p>The customer application will receive <strong>{readable(capability.actionCode)}</strong> for the original target shown above. The original operation is included automatically.</p>
+      {Object.entries(capability.inputSchema.properties).filter(([name]) => name !== "original_operation_id").map(([name, field]) => <label key={`${capability.id}:${name}`}>{field.title || readable(name)}
+        {field.type === "boolean" ? <select value={String(payload[name] ?? "")} required={capability.inputSchema.required?.includes(name)} disabled={pending} onChange={event => changePayload(name, event.currentTarget.value, "boolean")}><option value="">Choose…</option><option value="true">Yes</option><option value="false">No</option></select>
+          : field.enum ? <select value={String(payload[name] ?? "")} required={capability.inputSchema.required?.includes(name)} disabled={pending} onChange={event => changePayload(name, event.currentTarget.value, field.type)}><option value="">Choose…</option>{field.enum.map(value => <option key={value} value={value}>{readable(String(value))}</option>)}</select>
+            : <input type={field.type === "string" ? "text" : "number"} step={field.type === "integer" ? 1 : "any"} value={String(payload[name] ?? "")} required={capability.inputSchema.required?.includes(name)} minLength={field.minLength} maxLength={field.maxLength} min={field.minimum} max={field.maximum} disabled={pending} onChange={event => changePayload(name, event.currentTarget.value, field.type)} />}
+        {field.description && <small>{field.description}</small>}
+      </label>)}
+    </>}
+    <label>Responsible person<select value={owner} required disabled={pending} onChange={event => setOwner(event.currentTarget.value)}><option value="">Choose a person…</option>{snapshot.owners.map(person => <option key={person.id} value={person.id}>{person.displayName}</option>)}</select></label>
+    <label>Complete by<input type="datetime-local" required value={deadline} disabled={pending} onChange={event => setDeadline(event.currentTarget.value)} /></label>
+    <label>{capability ? "Why this correction is approved" : "What the responsible person needs to do"}<textarea minLength={3} maxLength={4000} required value={instructions} disabled={pending} onChange={event => setInstructions(event.currentTarget.value)} /></label>
+    <label className="appeal-correction-approval"><input type="checkbox" checked={approved} required disabled={pending} onChange={event => setApproved(event.currentTarget.checked)} /><span>I reviewed the original target and approve this specific {capability ? "customer change" : "manual correction assignment"}.</span></label>
+    <button className="primary" type="submit" disabled={pending || !approved}>{pending ? "Saving correction…" : capability ? "Approve and send correction" : "Assign manual correction"}</button>
+    {error && <p className="error" role="alert">{error}</p>}
+  </form>;
+}
+
+function CorrectionAssignment({ appealId, correction, owners, refresh }: { appealId: string; correction: Correction; owners: Snapshot["owners"]; refresh: () => void }) {
+  const [owner, setOwner] = useState(owners.some(person => person.id === correction.assignedOperatorId) ? correction.assignedOperatorId : "");
+  const [deadline, setDeadline] = useState(localDeadline); const [note, setNote] = useState(""); const [manual, setManual] = useState(false);
+  const [pending, setPending] = useState(false); const [error, setError] = useState(""); const key = useRef(crypto.randomUUID());
+  const submit = async (event: FormEvent) => {
+    event.preventDefault(); if (pending) return; setPending(true); setError("");
+    try { await requestJson(`${endpoint(appealId)}/${encodeURIComponent(correction.id)}/assignment`, {method: "POST", headers: {...mutationHeaders(), "idempotency-key": key.current}, body: JSON.stringify({assigned_operator_id: owner, due_at: new Date(deadline).toISOString(), note, manual_recovery: manual})}); setNote(""); refresh(); }
+    catch(cause) { if (cause instanceof ApiRequestError && cause.status >= 400 && cause.status < 500) key.current = crypto.randomUUID(); setError(errorMessage(cause, "The assignment could not be updated.")); }
+    finally { setPending(false); }
+  };
+  return <details><summary>Change responsibility or recovery plan</summary><form className="appeal-correction-form" onSubmit={event => void submit(event)}>
+    <label>New responsible person<select value={owner} required disabled={pending} onChange={event => setOwner(event.currentTarget.value)}><option value="">Choose a person…</option>{owners.map(person => <option key={person.id} value={person.id}>{person.displayName}</option>)}</select></label>
+    <label>New deadline<input type="datetime-local" required value={deadline} disabled={pending} onChange={event => setDeadline(event.currentTarget.value)} /></label>
+    <label>Handoff and next steps<textarea required minLength={3} maxLength={4000} value={note} disabled={pending} onChange={event => setNote(event.currentTarget.value)} /></label>
+    {correction.mode === "automated" && correction.state === "failed" && correction.deliveryTerminal === 1 && <label className="appeal-correction-approval"><input type="checkbox" checked={manual} disabled={pending} onChange={event => setManual(event.currentTarget.checked)} /><span>Assign manual recovery. The stopped automated attempt stays in the history; an independent reviewer must verify the actual customer correction.</span></label>}
+    <button type="submit" disabled={pending}>{pending ? "Saving assignment…" : "Save correction assignment"}</button>{error && <p className="error" role="alert">{error}</p>}
+  </form></details>;
+}
+
+function CorrectionProgress({ appealId, correction, canApprove, owners, refresh }: { appealId: string; correction: Correction; canApprove: boolean; owners: Snapshot["owners"]; refresh: () => void }) {
+  const [reference, setReference] = useState(""); const [note, setNote] = useState("");
+  const [pending, setPending] = useState(false); const [error, setError] = useState(""); const key = useRef(crypto.randomUUID());
+  useAppealDraftGuard(true, Boolean(reference || note), pending);
+  const mutate = async (kind: "verify" | "retry") => {
+    if (pending) return; setPending(true); setError("");
+    try { await requestJson(`${endpoint(appealId)}/${encodeURIComponent(correction.id)}/${kind}`, { method: "POST", headers: { ...mutationHeaders(), "idempotency-key": key.current }, body: JSON.stringify({ reference, note }) }); setReference(""); setNote(""); refresh(); }
+    catch (cause) { if (cause instanceof ApiRequestError && cause.status >= 400 && cause.status < 500) key.current = crypto.randomUUID(); setError(errorMessage(cause, "The correction could not be updated.")); }
+    finally { setPending(false); }
+  };
+  const status = correction.verifiedAt ? correction.mode === "automated" ? "Confirmed by customer application" : "Verified by independent reviewer" : correction.mode === "manual" ? "Manual correction outstanding" : correction.state === "failed" ? "Customer correction needs attention" : correction.acceptedAt ? "Accepted — awaiting customer confirmation" : "Awaiting customer completion";
+  return <div className="appeal-correction-progress"><p className="appeal-correction-action"><strong>Correction:</strong> {correction.mode === "manual" ? "Manual customer correction" : correction.actionCode ? readable(correction.actionCode) : "Approved customer change"}</p><h5>{status}</h5>
+    <p><strong>{correction.assignedOperatorName}</strong> is responsible · Due {dateTime(correction.dueAt)}</p><p>{correction.instructions}</p>
+    {correction.verifiedAt ? <><p>Verified {dateTime(correction.verifiedAt)}</p>{correction.mode === "manual" ? <><p>Human verification: {correction.evidenceNote}</p><p>Evidence reference: {correction.evidenceReference}</p></> : <p>The customer returned a matching applied receipt for this correction.</p>}</>
+      : correction.mode === "manual" ? canApprove ? <form className="appeal-correction-form" onSubmit={event => { event.preventDefault(); void mutate("verify"); }}><p>After the responsible person completes the work, independently check the customer application and record what proves the correction.</p><label>Customer evidence reference<input minLength={3} maxLength={500} required value={reference} disabled={pending} onChange={event => setReference(event.currentTarget.value)} /></label><label>How you verified the correction<textarea minLength={3} maxLength={4000} required value={note} disabled={pending} onChange={event => setNote(event.currentTarget.value)} /></label><button className="primary" type="submit" disabled={pending}>{pending ? "Saving verification…" : "Record verified correction"}</button></form> : <p>The independent appeal reviewer must verify the completed work.</p>
+        : <><p>The appeal remains open until the customer confirms this change and the participant notice is handed to its channel.</p>{correction.lastErrorCode && <p role="status">{readable(correction.lastErrorCode)}</p>}{canApprove && correction.state === "failed" && correction.deliveryTerminal === 1 && <button type="button" disabled={pending} onClick={() => void mutate("retry")}>{pending ? "Requesting retry…" : "Retry the same approved correction"}</button>}</>}
+    {correction.operationId && <details className="appeal-operation-details"><summary>{correction.mode === "manual" ? "Previous automated attempt" : "Correction operation reference"}</summary>{correction.mode === "manual" && correction.actionCode && <p>{readable(correction.actionCode)}</p>}<p className="appeal-operation-reference">{correction.operationId}</p></details>}
+    {!correction.verifiedAt && canApprove && <CorrectionAssignment appealId={appealId} correction={correction} owners={owners} refresh={refresh} />}
+    {error && <p className="error" role="alert">{error}</p>}
+  </div>;
+}
+
+export function AppealFollowup({ appeal, actorId }: { appeal: AppealRecord; actorId: string }) {
+  const [snapshot, setSnapshot] = useState<Snapshot | null>(null); const [error, setError] = useState(""); const [revision, setRevision] = useState(0);
+  const needsCorrection = appeal.decisions?.some(decision => decision.correctionRequired);
+  const refresh = () => { setRevision(value => value + 1); dispatchAppealRefresh(); };
+  useEffect(() => {
+    if (!needsCorrection) return;
+    let current = true;
+    requestJson<Snapshot>(endpoint(appeal.id)).then(result => { if (current) { setSnapshot(result); setError(""); } }).catch(cause => { if (current) setError(errorMessage(cause, "The correction status could not be loaded.")); });
+    return () => { current = false; };
+  }, [appeal.id, needsCorrection, appeal.decisions, revision]);
+  return <>{appeal.decisions?.map(decision => <section className="surface appeal-followup" key={decision.id} aria-label="Appeal verdict and follow-up">
+    <h3>{readable(decision.outcome)}</h3><p>{decision.rationale}</p>
+    <dl><dt>Participant notice</dt><dd>{decision.noticeState === "delivered" ? "Handed to channel" : decision.noticeState ? readable(decision.noticeState) : "No delivery record"}</dd><dt>Follow-up</dt><dd>{decision.completionState === "completed" ? "Complete" : decision.completionState === "legacy" ? "Historical verdict" : "Still outstanding"}</dd></dl>
+    {decision.correctionRequired ? <><h4>Correct the customer outcome</h4><p>The verdict preserves the original decision and action. Each original customer action needs its own confirmed correction.</p>
+      {!snapshot && !error && <p role="status">Loading customer actions…</p>}
+      {snapshot?.originals.map(original => { const correction = snapshot.corrections.find(item => item.sourceKey === original.sourceKey); return <section className="appeal-correction-card" key={original.sourceKey} aria-label={`Correction for ${readable(original.actionCode)}`}><h4>Original action: {readable(original.actionCode)}</h4><CorrectionTarget target={original.target} /><details className="appeal-operation-details"><summary>Original operation reference</summary><p className="appeal-operation-reference">{original.operationId}</p></details>
+        {correction ? <CorrectionProgress appealId={appeal.id} correction={correction} canApprove={snapshot.canApprove} owners={snapshot.owners} refresh={refresh} /> : snapshot.canApprove ? <CorrectionPlan appealId={appeal.id} original={original} snapshot={snapshot} actorId={actorId} refresh={refresh} /> : <p>The independent reviewer needs to approve a correction and assign a responsible person.</p>}
+      </section>; })}
+      {snapshot && !snapshot.originals.length && <p>No original customer action is available here. Open the original case to inspect historical follow-up before completing this appeal.</p>}
+    </> : null}
+    <p>Open the original case to inspect or retry the participant notice.</p>{error && <p className="error" role="alert">{error}</p>}
+  </section>)}</>;
+}