create-safest-tools 0.6.0 → 0.7.0

package/template/src/index.ts

@@ -1,4 +1,16 @@
+import { changeReportOwner, eligibleReportOwners } from "./report-ownership";
+import { retryParticipantNotice } from "./notice-recovery";
+import { confirmAppealCorrection, reconcileAppealCompletion } from "./appeal-continuity";
+import { createAppealCorrection, loadAppealCorrections, reassignAppealCorrection, retryAppealCorrection } from "./appeal-corrections";
+import { loadIntegrationProgress } from "./integration-progress";
+import { handleIntegrationVerification } from "./integration-verification";
+import { handleParticipantRequest } from "./participant-routes";
+import { handleCustomerParticipantAccess } from "./participant-customer-access";
+import { issueParticipantAccessLink, pruneParticipantAccess } from "./participant-access";
+import { acknowledgeCaseEscalation, getCaseEscalationPolicies, listCaseEscalations, reconcileCaseEscalations, saveCaseEscalationPolicy } from "./case-escalations";
+export { CaseInvestigator } from "./case-investigator";
 import { canonicalJson } from "./audit";
+import { loadPlaybookResources } from "./playbook-resources";
 import { reporterEmailConfigured } from "./report-email";
 import { decodeApiCursor, encodeApiCursor } from "./api-cursor";
 import {
@@ -177,6 +189,7 @@ import {
   loadAppealDetail,
   loadReportDetail,
   recordHumanDecision,
+  recordParticipantAppeal,
   releaseAppealClaim,
   releaseReportClaim,
 } from "./report-workflow";
@@ -254,6 +267,7 @@ import {
   deleteWorkflowFixture,
   diffWorkflowVersion,
   listWorkflowFixtures,
+  listWorkflowTestRuns,
   listWorkflowDefinitions,
   loadWorkflowTestRun,
   loadWorkflowVersion,
@@ -308,6 +322,7 @@ import {
   verifyFeature,
 } from "./installation-admin";
 import { loadWorkspaceBrand } from "./workspace-branding";
+import { databaseSchemaReady } from "./database-readiness";
 import {
   createExport,
   createSavedView,
@@ -337,8 +352,6 @@ const reportStates = new Set<ReportState>([
   "received", "human_review", "ai_review", "awaiting_reporter", "resolved_by_human",
   "resolved_by_ai", "human_review_requested", "appealed", "closed",
 ]);
-const EXPECTED_DATABASE_MIGRATIONS = 41;
-
 function integer(value: string | undefined, fallback: number, minimum: number, maximum: number): number {
   const parsed = Number.parseInt(value ?? "", 10);
   return Number.isFinite(parsed) ? Math.max(minimum, Math.min(maximum, parsed)) : fallback;
@@ -368,6 +381,22 @@ function receiptJson(receipt: Awaited<ReturnType<typeof createReport>>["receipt"
   };
 }
 
+async function receiptWithParticipantAccess(env: Env, result: Awaited<ReturnType<typeof createReport>>): Promise<Record<string, unknown>> {
+  const receipt = receiptJson(result.receipt);
+  // An idempotency key alone is not participant authentication. Only the
+  // request that created this report may receive a new private access link.
+  if (!result.created) return receipt;
+  try {
+    return { ...receipt, participant_url: await issueParticipantAccessLink(env, {
+      reportId: result.receipt.reportId, audience: "reporter", deliveryKey: `intake:${result.receipt.reportId}`,
+    }) };
+  } catch {
+    // The report has already committed. A failed access-link dependency must
+    // not imply that the submission failed or encourage another new report.
+    return { ...receipt, participant_access: "unavailable", participant_access_message: "Your report was received. Use the private link in your case email, or contact the service with your reference if you cannot receive updates." };
+  }
+}
+
 function queueRoutingJob(env: Env, ctx: ExecutionContext, jobId: string, reportId: string): void {
   const job: ReportJob = { version: 1, jobId, type: "route_report", reportId };
   ctx.waitUntil((async () => {
@@ -615,7 +644,7 @@ async function handleWidgetReport(request: Request, env: Env, ctx: ExecutionCont
   if (result.route) queueRoutingJob(env, ctx, result.jobId, result.receipt.reportId);
   queueDeliveryJobs(env, ctx, result.deliveryJobs);
   if (result.created) publishWorkspaceEvent(env, ctx, { type: "reports_changed", reportId: result.receipt.reportId });
-  return json(receiptJson(result.receipt), { status: result.created ? 201 : 200 });
+  return json(await receiptWithParticipantAccess(env, result), { status: result.created ? 201 : 200, headers: { "cache-control": "no-store", "referrer-policy": "no-referrer" } });
 }
 
 async function handleAnonymousWidgetReport(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
@@ -652,7 +681,7 @@ async function handleAnonymousWidgetReport(request: Request, env: Env, ctx: Exec
   if (result.route) queueRoutingJob(env, ctx, result.jobId, result.receipt.reportId);
   queueDeliveryJobs(env, ctx, result.deliveryJobs);
   if (result.created) publishWorkspaceEvent(env, ctx, { type: "reports_changed", reportId: result.receipt.reportId });
-  return json(receiptJson(result.receipt), { status: result.created ? 201 : 200 });
+  return json(await receiptWithParticipantAccess(env, result), { status: result.created ? 201 : 200, headers: { "cache-control": "no-store", "referrer-policy": "no-referrer" } });
 }
 
 async function handleServerReport(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
@@ -674,7 +703,7 @@ async function handleServerReport(request: Request, env: Env, ctx: ExecutionCont
   if (result.route) queueRoutingJob(env, ctx, result.jobId, result.receipt.reportId);
   queueDeliveryJobs(env, ctx, result.deliveryJobs);
   if (result.created) publishWorkspaceEvent(env, ctx, { type: "reports_changed", reportId: result.receipt.reportId });
-  return json(receiptJson(result.receipt), { status: result.created ? 201 : 200 });
+  return json(await receiptWithParticipantAccess(env, result), { status: result.created ? 201 : 200, headers: { "cache-control": "no-store", "referrer-policy": "no-referrer" } });
 }
 
 async function handlePublicConfig(request: Request, env: Env): Promise<Response> {
@@ -703,6 +732,7 @@ async function handlePublicConfig(request: Request, env: Env): Promise<Response>
   return json({
     schema_version: "1",
     turnstile_site_key: config.siteKey,
+    reporter_notifications_available: reporterEmailConfigured(env),
     form: {
       id: form.id,
       title: form.title,
@@ -748,7 +778,7 @@ async function handlePublicReport(request: Request, env: Env, ctx: ExecutionCont
   if (result.route) queueRoutingJob(env, ctx, result.jobId, result.receipt.reportId);
   queueDeliveryJobs(env, ctx, result.deliveryJobs);
   if (result.created) publishWorkspaceEvent(env, ctx, { type: "reports_changed", reportId: result.receipt.reportId });
-  return json(receiptJson(result.receipt), { status: result.created ? 201 : 200 });
+  return json(await receiptWithParticipantAccess(env, result), { status: result.created ? 201 : 200, headers: { "cache-control": "no-store", "referrer-policy": "no-referrer" } });
 }
 
 async function handleAdminSession(request: Request, env: Env): Promise<Response> {
@@ -869,7 +899,7 @@ async function handleOperatorPasswordResetRequest(request: Request, env: Env, ct
   });
   if (!better.ok) {
     console.warn("Password reset request was not accepted by Better Auth", better.status);
-    better.body?.cancel();
+    await better.body?.cancel().catch(() => undefined);
   }
   return json({
     schema_version: "1",
@@ -955,7 +985,7 @@ async function handleOwnerSetupAccept(request: Request, env: Env, ctx: Execution
     rememberMe: false,
   });
   if (!signUp.ok) return normalizedBetterAuthError(signUp, "The owner account could not be created.");
-  signUp.body?.cancel();
+  await signUp.body?.cancel().catch(() => undefined);
   await env.DB.prepare(`UPDATE auth_user SET emailVerified = 1, updatedAt = ?2 WHERE email = ?1 COLLATE NOCASE`)
     .bind(setup.email, new Date().toISOString()).run();
   const signIn = await callBetterAuth(request, env, ctx, "/sign-in/email", {
@@ -970,7 +1000,7 @@ async function handleOwnerSetupAccept(request: Request, env: Env, ctx: Execution
     name: displayName || setup.email.split("@", 1)[0],
   }, null, setup.id);
   if (!owner?.roles.includes("owner")) {
-    signIn.body?.cancel();
+    await signIn.body?.cancel().catch(() => undefined);
     throw new ApiError(409, "owner_setup_already_used", "This owner setup link has already been used or is no longer valid.");
   }
   return clearOwnerSetupCookie(normalizedBetterAuthSuccess(signIn, {
@@ -1089,7 +1119,8 @@ async function handleAdminPresence(request: Request, env: Env): Promise<Response
   }
   if (request.method === "POST") {
     const heartbeat = parsePresenceHeartbeat(await readJsonObject(request, 4 * 1024));
-    const result = await touchAnalystSession(env.DB, {
+    const db = env.DB.withSession("first-primary");
+    const result = await touchAnalystSession(db, {
       ...heartbeat,
       actorId: session.actor.id,
       allowedQueueIds: session.queueScope ?? null,
@@ -1099,7 +1130,7 @@ async function handleAdminPresence(request: Request, env: Env): Promise<Response
       schema_version: "1",
       profile,
       claim_renewed: result.claimRenewed,
-      analysts: await listAnalystPresence(env.DB, 45, session.queueScope ?? null),
+      analysts: await listAnalystPresence(db, 45, session.queueScope ?? null),
     });
   }
   return methodNotAllowed(["GET", "POST"]);
@@ -1636,6 +1667,10 @@ async function handleAdminWorkflow(
     }
     return methodNotAllowed(["GET", "POST"]);
   }
+  if (action === "test-runs" && request.method === "GET") {
+    await requireOperator(request, env, "manageWorkflows");
+    return json({ schema_version: "1", test_runs: await listWorkflowTestRuns(env.DB, workflowId) });
+  }
   if (action === "test" || action === "test-runs") {
     if (request.method !== "POST") return methodNotAllowed(["POST"]);
     const session = await requireOperator(request, env, "manageWorkflows");
@@ -1693,7 +1728,9 @@ async function handleAdminWorkflowFixture(
   };
   const name = body.name ?? current.name;
   if (typeof name !== "string") throw new ApiError(400, "workflow_fixture_invalid", "name must be a string.");
+  if (!Number.isInteger(body.expected_revision) || Number(body.expected_revision) < 1) throw new ApiError(400, "workflow_fixture_revision_required", "expected_revision must be the saved example revision.");
   const result = await updateWorkflowFixture(env.DB, workflowId, fixtureId, {
+    expectedRevision: Number(body.expected_revision),
     name,
     input: objectField(body.input ?? current.input, "input"),
     componentResults: objectField(body.component_results ?? current.componentResults, "component_results"),
@@ -1761,8 +1798,11 @@ async function handleAdminQueueWorkflowPin(request: Request, env: Env, queueId:
     if (body.rollback_of_pin_id !== undefined && typeof body.rollback_of_pin_id !== "string") {
       throw new ApiError(400, "workflow_pin_invalid", "rollback_of_pin_id must be a string when supplied.");
     }
+    if (body.expected_pin_id !== undefined && body.expected_pin_id !== null && typeof body.expected_pin_id !== "string") throw new ApiError(400, "workflow_pin_invalid", "expected_pin_id must be a string or null.");
+    assertOperatorQueueAccess(session, queueId);
     const result = await pinQueueWorkflow(env.DB, queueId, {
       workflowVersionId: body.workflow_version_id.trim(),
+      ...(body.expected_pin_id !== undefined ? { expectedPinId: body.expected_pin_id as string | null } : {}),
       mode: body.mode,
       ...(typeof body.rollback_of_pin_id === "string" ? { rollbackOfPinId: body.rollback_of_pin_id } : {}),
     }, session, mutationKey(request));
@@ -1819,6 +1859,7 @@ async function handleAdminWorkflowRuns(request: Request, env: Env): Promise<Resp
     schema_version: "1",
     runs: await listWorkflowRuns(env.DB, {
       ...(state ? { state } : {}),
+      workflowId: url.searchParams.get("workflow_id")?.trim() || undefined,
       allowedQueueIds: session.queueScope ?? null,
       limit: integer(url.searchParams.get("limit") ?? undefined, 50, 1, 100),
     }),
@@ -1989,9 +2030,9 @@ async function handleAdminAiRun(request: Request, env: Env, runId: string): Prom
 
 async function handleAdminAiUsage(request: Request, env: Env): Promise<Response> {
   if (request.method !== "GET") return methodNotAllowed(["GET"]);
-  await requireOperator(request, env, "readAi");
+  const session = await requireOperator(request, env, "readAi");
   const days = integer(new URL(request.url).searchParams.get("days") ?? undefined, 30, 1, 366);
-  return json({ schema_version: "1", usage: await loadAiUsage(env.DB, days) });
+  return json({ schema_version: "1", usage: await loadAiUsage(env.DB, days, session.queueScope ?? null) });
 }
 
 async function handleAdminBudgets(request: Request, env: Env): Promise<Response> {
@@ -2226,15 +2267,21 @@ async function handleAdminHumanTasks(request: Request, env: Env): Promise<Respon
   const queueId = url.searchParams.get("queue_id")?.trim() || undefined;
   if (queueId && queueId.length > 100) throw new ApiError(400, "human_task_queue_invalid", "queue_id is invalid.");
   if (queueId) assertOperatorQueueAccess(session, queueId);
+  const reportId = url.searchParams.get("report_id")?.trim() || undefined;
+  if (reportId) {
+    if (reportId.length > 100) throw new ApiError(400, "human_task_report_invalid", "report_id is invalid.");
+    await assertOperatorReportAccess(env.DB, session, reportId);
+  }
   return json({
     schema_version: "1",
-    tasks: await listHumanTasks(env.DB, {
+    tasks: projectOperatorFields(session, "task", await listHumanTasks(env.DB, {
       ...(state ? { state } : {}),
+      ...(reportId ? { reportId } : {}),
       ...(queueId ? { queueId } : {}),
       ...(url.searchParams.get("mine") === "true" ? { operatorId: session.actor.id } : {}),
       allowedQueueIds: session.queueScope ?? null,
       limit: integer(url.searchParams.get("limit") ?? undefined, 50, 1, 100),
-    }),
+    })),
   });
 }
 
@@ -2439,6 +2486,7 @@ async function handleAdminActionProposal(
     if (request.method !== "GET") return methodNotAllowed(["GET"]);
     const session = await requireOperator(request, env, "readReports");
     await assertOperatorReportAccess(env.DB, session, reference.reportId);
+    if (!session.permissions.readSensitiveEvidence && !session.permissions.approveActions) throw new ApiError(403, "action_details_restricted", "Your role can read action progress but cannot inspect protected customer action data.");
     const detail = await loadActionProposalDetail(env.DB, proposalId);
     return json({ schema_version: "1", ...detail });
   }
@@ -2603,6 +2651,8 @@ async function handleAdminAiQualitySample(
   const report = await loadReportDetail(env.DB, String(sample.reportId), {
     contactEncryptionKey: env.CREDENTIAL_ENCRYPTION_KEY,
     includeReporterEmail: session.permissions.messageReporters,
+    includeCustomerContext: session.permissions.readSensitiveEvidence,
+    allowedQueueIds: session.queueScope ?? null,
   });
   if (!report) throw new ApiError(404, "report_not_found", "The sampled report does not exist.");
   return json({ schema_version: "1", sample: projectOperatorFields(session, "quality_sample", sample), report: projectOperatorFields(session, "report", report) });
@@ -2645,24 +2695,23 @@ async function handleAdminAiQualityReview(
 
 async function handleAdminAnalytics(request: Request, env: Env): Promise<Response> {
   if (request.method !== "GET") return methodNotAllowed(["GET"]);
-  await requireOperator(request, env, "readAnalytics");
+  const session = await requireOperator(request, env, "readAnalytics");
   const days = integer(new URL(request.url).searchParams.get("days") ?? undefined, 30, 1, 366);
-  await refreshDailyAggregatesIfStale(env.DB);
-  return json({ schema_version: "1", analytics: await loadAnalytics(env.DB, days) });
+  return json({ schema_version: "1", analytics: await loadAnalytics(env.DB, days, session.queueScope ?? null) });
 }
 
 async function handleAdminAnalyticsAi(request: Request, env: Env): Promise<Response> {
   if (request.method !== "GET") return methodNotAllowed(["GET"]);
-  await requireOperator(request, env, "readAi");
+  const session = await requireOperator(request, env, "readAi");
   const days = integer(new URL(request.url).searchParams.get("days") ?? undefined, 30, 1, 366);
-  return json({ schema_version: "1", analytics: await loadAiUsage(env.DB, days) });
+  return json({ schema_version: "1", analytics: await loadAiUsage(env.DB, days, session.queueScope ?? null) });
 }
 
 async function handleAdminAnalyticsWorkflows(request: Request, env: Env): Promise<Response> {
   if (request.method !== "GET") return methodNotAllowed(["GET"]);
-  await requireOperator(request, env, "readAnalytics");
+  const session = await requireOperator(request, env, "readAnalytics");
   const days = integer(new URL(request.url).searchParams.get("days") ?? undefined, 30, 1, 366);
-  return json({ schema_version: "1", analytics: await loadWorkflowAnalytics(env.DB, days) });
+  return json({ schema_version: "1", analytics: await loadWorkflowAnalytics(env.DB, days, session.queueScope ?? null) });
 }
 
 async function handleAdminSearch(request: Request, env: Env): Promise<Response> {
@@ -2854,6 +2903,8 @@ async function handleAdminReportDetail(request: Request, env: Env, reportId: str
   const report = await loadReportDetail(env.DB, reportId, {
     contactEncryptionKey: env.CREDENTIAL_ENCRYPTION_KEY,
     includeReporterEmail: session.permissions.messageReporters,
+    includeCustomerContext: session.permissions.readSensitiveEvidence,
+    allowedQueueIds: session.queueScope ?? null,
   });
   if (!report) throw new ApiError(404, "report_not_found", "The report does not exist.");
   return json({ schema_version: "1", report: projectOperatorFields(session, "report", report) });
@@ -3094,8 +3145,20 @@ async function handleAdminDecision(request: Request, env: Env, decisionId: strin
 }
 
 async function handleAdminAppeals(request: Request, env: Env): Promise<Response> {
-  if (request.method !== "GET") return methodNotAllowed(["GET"]);
+  if (!["GET", "POST"].includes(request.method)) return methodNotAllowed(["GET", "POST"]);
   const session = await requireOperator(request, env, "reviewAppeals");
+  if (request.method === "POST") {
+    const input = await readJsonObject(request, 16 * 1024);
+    const reference = typeof input.report_reference === "string" ? input.report_reference.trim() : "";
+    const reason = typeof input.reason === "string" ? input.reason.trim() : "";
+    const key = request.headers.get("idempotency-key")?.trim() || "";
+    if (!reference || reference.length > 100 || reason.length < 3 || reason.length > 8000 || !["reporter", "affected_user"].includes(String(input.audience)) || key.length < 8 || key.length > 200) throw new ApiError(400, "appeal_input_invalid", "Enter a report reference, participant, reason (3–8000 characters), and idempotency key.");
+    const report = await env.DB.prepare(`SELECT id FROM reports WHERE public_reference = ?1 LIMIT 1`).bind(reference).first<{ id: string }>();
+    if (!report) throw new ApiError(404, "report_not_found", "No report matches this reference.");
+    await assertOperatorReportAccess(env.DB, session, report.id);
+    const result = await recordParticipantAppeal(env.DB, report.id, session, { audience: input.audience as "reporter" | "affected_user", reason, idempotencyKey: key });
+    return json({ schema_version: "1", appeal_id: result.appealId, idempotent_replay: result.idempotentReplay }, { status: result.idempotentReplay ? 200 : 201 });
+  }
   const limit = integer(new URL(request.url).searchParams.get("limit") ?? undefined, 50, 1, 100);
   return json({ schema_version: "1", appeals: await listAppeals(env.DB, limit, session.queueScope ?? null) });
 }
@@ -3171,24 +3234,26 @@ async function handleReady(request: Request, env: Env): Promise<Response> {
   await requireAnyOperator(request, env);
   try {
     const [migrations, features] = await Promise.all([
-      env.DB.prepare(`SELECT COUNT(*) AS count FROM d1_migrations`).first<{ count: number }>(),
+      env.DB.prepare(`SELECT name FROM d1_migrations ORDER BY id`).all<{ name: string }>(),
       env.DB.prepare(`SELECT feature_key AS featureKey, state FROM installation_features WHERE installation_id = 'default'`).all<{ featureKey: string; state: string }>(),
       env.PROFILE_MEDIA.list({ limit: 1 }),
       env.WORKFLOW_ARTIFACTS.list({ limit: 1 }),
       env.EVIDENCE_OBJECTS.list({ limit: 1 }),
       env.EXPORTS.list({ limit: 1 }),
     ]);
-    const migrationCount = Number(migrations?.count ?? 0);
+    const migrationNames = migrations.results.map(({ name }) => name);
+    const migrationCount = migrationNames.length;
     const featureStates = new Map(features.results.map((feature) => [feature.featureKey, feature.state]));
     const requiredFeatures = ["database", "workflow_runtime", "workers_ai", "object_storage", "queues"];
     const unavailable = requiredFeatures.filter((feature) => featureStates.get(feature) !== "ready");
     const bindingsReady = Boolean(env.WORKFLOWS && env.LOADER && env.CONTROL_JOBS && env.REPORT_JOBS && env.DELIVERY_JOBS && env.AI);
-    const ready = migrationCount >= EXPECTED_DATABASE_MIGRATIONS && unavailable.length === 0 && bindingsReady;
+    const schemaReady = databaseSchemaReady(migrationNames);
+    const ready = schemaReady && unavailable.length === 0 && bindingsReady;
     return json({
       status: ready ? "ready" : "not_ready",
       service: "safest-resolve-reports",
       schema_migrations: migrationCount,
-      checks: { database: true, private_object_storage: true, runtime_bindings: bindingsReady, unavailable_features: unavailable },
+      checks: { database: schemaReady, private_object_storage: true, runtime_bindings: bindingsReady, unavailable_features: unavailable },
     }, { status: ready ? 200 : 503 });
   } catch {
     return json({ status: "not_ready", service: "safest-resolve-reports", checks: { dependency_probe: false } }, { status: 503 });
@@ -3498,7 +3563,10 @@ async function handleAdminIntegration(
 }
 
 async function route(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+  if (new URL(request.url).pathname === "/v1/participant-access") return handleCustomerParticipantAccess(request, env);
   const url = new URL(request.url);
+  const participantResponse = await handleParticipantRequest(request, env, reportId => publishWorkspaceEvent(env, ctx, { type: "reports_changed", reportId }));
+  if (participantResponse) return participantResponse;
   if (url.pathname === "/api/auth" || url.pathname.startsWith("/api/auth/")) {
     return handleBetterAuthRequest(request, env, ctx);
   }
@@ -3532,6 +3600,43 @@ async function route(request: Request, env: Env, ctx: ExecutionContext): Promise
   if (url.pathname === "/v1/admin/installation") return handleAdminInstallation(request, env);
   if (url.pathname === "/v1/admin/brand") return handleAdminBrand(request, env);
   if (url.pathname === "/v1/admin/reporting-channels") return handleAdminReportingChannels(request, env);
+  if (url.pathname === "/v1/admin/integration-progress") {
+    if(request.method!=="GET")return methodNotAllowed(["GET"]);
+    const session=await requireOperator(request,env,"manageComponents");
+    return json(await loadIntegrationProgress(env,session));
+  }
+  if (/^\/v1\/admin\/integration-verifications(?:\/[^/]+(?:\/bind)?)?$/u.test(url.pathname)) {
+    const session = await requireOperator(request, env, "manageIntegrations");
+    return handleIntegrationVerification(request, env, session);
+  }
+  if (url.pathname === "/v1/admin/case-escalations" || /^\/v1\/admin\/case-escalations\/[^/]+\/acknowledge$/u.test(url.pathname)) {
+    const acknowledgedId = /^\/v1\/admin\/case-escalations\/([^/]+)\/acknowledge$/u.exec(url.pathname)?.[1];
+    if (request.method !== (acknowledgedId ? "POST" : "GET")) return methodNotAllowed([acknowledgedId ? "POST" : "GET"]);
+    const identity = await requireAnyOperator(request, env);
+    const session = await requireOperator(request, env, identity.permissions.readReports ? "readReports" : "readOperations");
+    if (!acknowledgedId) return json(await listCaseEscalations(env.DB, session, url.searchParams.get("cursor") || ""));
+    const body = await readJsonObject(request, 4096);
+    if (typeof body.revision !== "number" || !Number.isSafeInteger(body.revision) || body.revision < 1) throw new ApiError(400, "escalation_revision_required", "Refresh the recovery item before acknowledging it.");
+    await acknowledgeCaseEscalation(env.DB, session, acknowledgedId, body.revision);
+    return json({ acknowledged: true });
+  }
+  if (url.pathname === "/v1/admin/case-escalation-policies") {
+    if (!["GET", "PUT"].includes(request.method)) return methodNotAllowed(["GET", "PUT"]);
+    const session = await requireOperator(request, env, "manageConfiguration");
+    if (request.method === "GET") return json(await getCaseEscalationPolicies(env.DB, session));
+    const body = await readJsonObject(request, 8192);
+    if (![body.queueId, body.primaryOperatorId, body.backupOperatorId].every(value => value === null || (typeof value === "string" && value.length > 0 && value.length <= 100))
+      || typeof body.acknowledgementMinutes !== "number" || typeof body.followUpMinutes !== "number" || typeof body.revision !== "number") {
+      throw new ApiError(400, "escalation_policy_invalid", "Choose recovery contacts and response deadlines.");
+    }
+    await saveCaseEscalationPolicy(env.DB, session, {
+      queueId: typeof body.queueId === "string" ? body.queueId : null,
+      primaryOperatorId: typeof body.primaryOperatorId === "string" ? body.primaryOperatorId : null,
+      backupOperatorId: typeof body.backupOperatorId === "string" ? body.backupOperatorId : null,
+      acknowledgementMinutes: body.acknowledgementMinutes, followUpMinutes: body.followUpMinutes, revision: body.revision,
+    });
+    return json({ saved: true });
+  }
   if (url.pathname === "/v1/admin/setup") return handleAdminSetup(request, env);
   if (url.pathname === "/v1/admin/integrations") return handleAdminIntegrations(request, env);
   if (url.pathname === "/v1/admin/people") return handleAdminPeople(request, env);
@@ -3541,6 +3646,11 @@ async function route(request: Request, env: Env, ctx: ExecutionContext): Promise
   if (url.pathname === "/v1/admin/reports") return handleAdminReports(request, env);
   if (url.pathname === "/v1/admin/queues") return handleAdminQueues(request, env);
   if (url.pathname === "/v1/admin/workflows") return handleAdminWorkflows(request, env);
+  if (url.pathname === "/v1/admin/playbook-resources") {
+    if (request.method !== "GET") return methodNotAllowed(["GET"]);
+    await requireOperator(request, env, "manageWorkflows");
+    return json({ schema_version: "1", ...await loadPlaybookResources(env.DB) });
+  }
   if (url.pathname === "/v1/admin/workflow-runs") return handleAdminWorkflowRuns(request, env);
   if (url.pathname === "/v1/admin/prompts") return handleAdminPrompts(request, env);
   if (url.pathname === "/v1/admin/model-aliases") return handleAdminModelAliases(request, env);
@@ -3797,9 +3907,27 @@ async function route(request: Request, env: Env, ctx: ExecutionContext): Promise
     decodeURIComponent(reportEnrichmentRoute[1] ?? ""),
     decodeURIComponent(reportEnrichmentRoute[2] ?? ""),
   );
-  const reportRoute = /^\/v1\/admin\/reports\/([^/]+)(?:\/(claim|messages|decisions|workflow-runs|reassign|timeline|findings|actions|close|reopen))?$/u.exec(url.pathname);
+  const noticeRetryRoute = /^\/v1\/admin\/reports\/([^/]+)\/notices\/([^/]+)\/retry$/u.exec(url.pathname);
+  if (noticeRetryRoute) {
+    if (request.method !== "POST") return methodNotAllowed(["POST"]);
+    const session = await requireOperator(request, env, "messageReporters");
+    const body = await readJsonObject(request, 4096);
+    if (typeof body.expected_updated_at !== "string") throw new ApiError(400, "notice_revision_required", "Refresh the notice before retrying.");
+    return json(await retryParticipantNotice(env, decodeURIComponent(noticeRetryRoute[1]!), decodeURIComponent(noticeRetryRoute[2]!), body.expected_updated_at, session, mutationKey(request)));
+  }
+  const reportRoute = /^\/v1\/admin\/reports\/([^/]+)(?:\/(ownership|claim|messages|decisions|workflow-runs|reassign|timeline|findings|actions|close|reopen))?$/u.exec(url.pathname);
   if (reportRoute) {
     const reportId = decodeURIComponent(reportRoute[1] ?? "");
+    if (reportRoute[2] === "ownership") {
+      const session = await requireOperator(request, env, "reassignReports");
+      await assertOperatorReportAccess(env.DB, session, reportId);
+      if (request.method === "GET") return json({ reviewers: await eligibleReportOwners(env.DB, reportId) });
+      if (request.method !== "PATCH") return methodNotAllowed(["GET", "PATCH"]);
+      const body = await readJsonObject(request, 24 * 1024);
+      await changeReportOwner(env.DB, reportId, session, { reviewerId: body.reviewer_id as string | null, version: body.version as number, note: body.note as string });
+      publishWorkspaceEvent(env, ctx, { type: "claim_changed", reportId });
+      return new Response(null, { status: 204 });
+    }
     if (reportRoute[2] === "claim") return handleAdminReportClaim(request, env, ctx, reportId);
     if (reportRoute[2] === "messages") return handleAdminReportMessage(request, env, ctx, reportId);
     if (reportRoute[2] === "decisions") return handleAdminReportDecision(request, env, ctx, reportId);
@@ -3813,6 +3941,38 @@ async function route(request: Request, env: Env, ctx: ExecutionContext): Promise
     }
     return handleAdminReportDetail(request, env, reportId);
   }
+  const appealCorrectionsRoute = /^\/v1\/admin\/appeals\/([^/]+)\/corrections(?:\/([^/]+)\/(verify|retry|assignment))?$/u.exec(url.pathname);
+  if (appealCorrectionsRoute) {
+    const appealId = decodeURIComponent(appealCorrectionsRoute[1]!);
+    const correctionId = appealCorrectionsRoute[2] ? decodeURIComponent(appealCorrectionsRoute[2]) : undefined;
+    const action = appealCorrectionsRoute[3];
+    if (!action && request.method === "GET") {
+      const session = await requireOperator(request, env, "reviewAppeals");
+      return json(await loadAppealCorrections(env.DB, appealId, session));
+    }
+    if (request.method !== "POST") return methodNotAllowed(action ? ["POST"] : ["GET", "POST"]);
+    const session = await requireOperator(request, env, action === "verify" ? "reviewAppeals" : "decideAppeals");
+    let result;
+    if (action === "retry") result = await retryAppealCorrection(env, appealId, correctionId!, session, mutationKey(request));
+    else {
+      const input = await readJsonObject(request, 24 * 1024);
+      if (action === "verify") {
+        if (typeof input.reference !== "string" || typeof input.note !== "string") throw new ApiError(400, "correction_evidence_required", "Record the customer reference and verification notes.");
+        result = await confirmAppealCorrection(env.DB, appealId, session, {correctionId, reference: input.reference.trim(), note: input.note.trim(), idempotencyKey: mutationKey(request)});
+      } else if (action === "assignment") result = await reassignAppealCorrection(env, appealId, correctionId!, session, input, mutationKey(request));
+      else result = await createAppealCorrection(env, appealId, session, input, mutationKey(request));
+    }
+    publishWorkspaceEvent(env, ctx, {type: "reports_changed"});
+    return json(result);
+  }
+  const appealCorrectionRoute = /^\/v1\/admin\/appeals\/([^/]+)\/correction$/u.exec(url.pathname);
+  if (appealCorrectionRoute) {
+    if (request.method !== "POST") return methodNotAllowed(["POST"]);
+    const session = await requireOperator(request,env,"reviewAppeals");
+    const input = await readJsonObject(request, 8 * 1024);
+    if (typeof input.reference !== "string" || typeof input.note !== "string") throw new ApiError(400,"correction_evidence_required","Record the customer reference and verification notes.");
+    return json(await confirmAppealCorrection(env.DB,decodeURIComponent(appealCorrectionRoute[1]!),session,{reference:input.reference.trim(),note:input.note.trim(),idempotencyKey:mutationKey(request)}));
+  }
   const appealClaimRoute = /^\/v1\/admin\/appeals\/([^/]+)\/claim$/u.exec(url.pathname);
   if (appealClaimRoute) return handleAdminAppealClaim(request, env, decodeURIComponent(appealClaimRoute[1] ?? ""));
   const appealDecisionRoute = /^\/v1\/admin\/appeals\/([^/]+)\/decision$/u.exec(url.pathname);
@@ -3999,6 +4159,7 @@ async function reconcileRouting(env: Env): Promise<ReconciliationResult> {
 }
 
 async function reconcileDeliveries(env: Env): Promise<ReconciliationResult> {
+  await reconcileAppealCompletion(env.DB);
   const [jobs, actionJobs] = await Promise.all([
     pendingDeliveryJobs(env.DB, 50),
     pendingActionProposalJobs(env.DB, 50),
@@ -4161,9 +4322,10 @@ export default {
   async scheduled(_controller: ScheduledController, env: Env, ctx: ExecutionContext): Promise<void> {
     ctx.waitUntil((async () => {
       await Promise.all([
-        runRecordedReconciliation(env, "all", "system:maintenance"), escalateExpiredAiWaits(env.DB),
+        runRecordedReconciliation(env, "all", "system:maintenance"), escalateExpiredAiWaits(env.DB), reconcileCaseEscalations(env.DB),
         maintainIntakeProtection(env.DB),
         pruneReportContexts(env.DB),
+        pruneParticipantAccess(env.DB),
         compareCompletedShadowRuns(env.DB),
         expireExports(env),
         pruneConnectionOAuthStates(env.DB),

package/template/src/installation-admin.ts

@@ -1,3 +1,4 @@
+import { version as applicationVersion } from "../package.json";
 import { canonicalJson } from "./audit";
 import { sha256 } from "./report-crypto";
 import { ApiError } from "./report-http";
@@ -293,7 +294,7 @@ export async function verifyFeature(env: Env, feature: string, actorId: string):
 export async function metaVersion(db: D1Database): Promise<Record<string, unknown>> {
   const migration = await db.prepare(`SELECT name FROM d1_migrations ORDER BY id DESC LIMIT 1`).first<{ name: string }>().catch(() => null);
   return {
-    application: "0.1.0",
+    application: applicationVersion,
     apiSchema: "1",
     databaseMigration: migration?.name ?? "unknown",
     workflowCompiler: WORKFLOW_COMPILER_VERSION,

package/template/src/integration-progress.ts

@@ -0,0 +1,45 @@
+import { canonicalJson } from "./audit";
+import { ApiError } from "./report-http";
+import { reporterEmailConfigured } from "./report-email";
+import type { OperatorSession } from "./report-types";
+
+import type { IntegrationEvidence, IntegrationProgress } from "../shared/integration-progress";
+
+export async function loadIntegrationProgress(env: Env, session: OperatorSession): Promise<IntegrationProgress> {
+  if (!session.permissions.manageComponents) throw new ApiError(403,"integration_progress_denied","Your role cannot inspect customer capability setup.");
+  const unrestricted=session.queueScope==null?1:0,queues=canonicalJson(session.queueScope??[]);
+  const canReadCases=session.permissions.readReports && session.fieldScope==null;
+  const scope="(?1 = 1 OR r.queue_id IN (SELECT value FROM json_each(?2)))";
+  const evidence=async(from:string,where:string,at:string):Promise<IntegrationEvidence|null>=>canReadCases
+    ? env.DB.prepare(`SELECT r.id AS reportId, r.public_reference AS reference, ${at} AS observedAt ${from} WHERE ${where} AND ${scope} ORDER BY ${at} DESC, r.id DESC LIMIT 1`).bind(unrestricted,queues).first<IntegrationEvidence>()
+    : null;
+  const [routes,tools,pins,intake,context,action,notice,playbook]=await Promise.all([
+    session.permissions.manageIntegrations?env.DB.prepare(`SELECT
+      (SELECT COUNT(*) FROM application_integrations WHERE enabled = 1) +
+      (SELECT COUNT(*) FROM report_form_versions f JOIN installations i ON i.id=f.installation_id
+        WHERE i.anonymous_reporting_enabled = 1 AND f.published_at IS NOT NULL AND f.retired_at IS NULL
+          AND f.id IN (SELECT value FROM json_each(i.settings_json,'$.public_form_version_ids'))) AS count`).first<{count:number}>():null,
+    env.DB.prepare(`SELECT SUM(CASE WHEN d.effect_class='read_only' THEN 1 ELSE 0 END) AS reads,
+      SUM(CASE WHEN d.effect_class='side_effecting' THEN 1 ELSE 0 END) AS actions
+      FROM component_definitions d JOIN component_versions v ON v.id=d.active_version_id
+      WHERE d.owner_kind='customer' AND d.status='active' AND v.retired_at IS NULL`).first<{reads:number|null;actions:number|null}>(),
+    session.permissions.manageWorkflows?env.DB.prepare(`SELECT COUNT(*) AS count FROM queue_workflow_pins p JOIN workflow_versions v ON v.id=p.workflow_version_id
+      JOIN queue_definitions q ON q.id=p.queue_id WHERE p.deactivated_at IS NULL AND p.mode='primary' AND q.enabled=1 AND q.status='active'
+        AND json_type(v.graph_json,'$.playbook')='object' AND (?1=1 OR p.queue_id IN (SELECT value FROM json_each(?2)))`).bind(unrestricted,queues).first<{count:number}>():null,
+    evidence("FROM reports r","r.source IN ('server_api','signed_widget','public_page')","r.received_at"),
+    session.permissions.readEvidence?evidence(`FROM findings f JOIN reports r ON r.id=f.report_id JOIN component_versions cv ON cv.id=f.component_version_id
+      JOIN component_definitions cd ON cd.id=cv.definition_id JOIN workflow_runs wr ON wr.id=f.run_id`,
+      "cd.owner_kind='customer' AND cd.effect_class='read_only' AND f.status='available' AND f.superseded_at IS NULL AND (f.expires_at IS NULL OR f.expires_at>strftime('%Y-%m-%dT%H:%M:%fZ','now')) AND wr.run_kind='primary' AND wr.authority_mode!='shadow'","f.created_at"):null,
+    evidence("FROM action_proposals p JOIN reports r ON r.id=p.report_id","p.state='applied' AND p.confirmed_at IS NOT NULL","p.confirmed_at"),
+    evidence("FROM notices n JOIN reports r ON r.id=n.report_id","n.delivery_state='delivered' AND n.redacted_at IS NULL","n.updated_at"),
+    evidence("FROM workflow_runs wr JOIN workflow_versions v ON v.id=wr.workflow_version_id JOIN reports r ON r.id=wr.report_id",
+      `wr.state='succeeded' AND wr.run_kind='primary' AND wr.authority_mode!='shadow' AND json_type(v.graph_json,'$.playbook')='object'
+        AND CAST(replace(v.compiler_version,'safest-workflow-compiler-v','') AS INTEGER)>=5 AND r.state IN ('resolved_by_human','resolved_by_ai','closed')
+        AND EXISTS (SELECT 1 FROM decisions WHERE report_id=r.id)
+        AND NOT EXISTS (SELECT 1 FROM action_proposals WHERE run_id=wr.id AND state!='applied')
+        AND NOT EXISTS (SELECT 1 FROM case_messages WHERE workflow_run_id=wr.id AND direction='outbound' AND delivery_state!='delivered')`,"wr.updated_at"),
+  ]);
+  let localSandbox=false;try{localSandbox=env.AI_LOCAL_FIXTURE_ENABLED==="true"&&["localhost","127.0.0.1"].includes(new URL(env.PUBLIC_BASE_URL).hostname);}catch{}
+  return {localSandbox,canReadCases,configuration:{reportingRoutes:routes?.count??null,customerReads:tools?.reads??0,customerActions:tools?.actions??0,activePlaybooks:pins?.count??null,
+    noticeChannel:session.permissions.manageIntegrations||session.permissions.manageInstallation?Boolean(reporterEmailConfigured(env)||(env.NOTIFICATION_WEBHOOK_URL?.trim()&&env.NOTIFICATION_WEBHOOK_SECRET?.trim())):null},evidence:{intake,context,action,notice,playbook}};
+}