create-safest-tools 0.6.0 → 0.7.0

package/template/src/integration-verification.ts

@@ -0,0 +1,249 @@
+import { canonicalJson } from "./audit";
+import { ApiError, json, methodNotAllowed, readJsonObject } from "./report-http";
+import type { OperatorSession } from "./report-types";
+import { parsePlaybook, type PlaybookGuide } from "../shared/playbooks";
+import type { IntegrationVerification, IntegrationVerificationList, VerificationChoice, VerificationStage } from "../shared/integration-progress";
+
+type Row = Record<string, string | number | null>;
+interface Selection { integrationId: string; formVersionId: string; queueId: string; decisionCode: string }
+interface CheckRow {
+  id: string; integration_id: string; form_version_id: string; queue_id: string; workflow_version_id: string; pin_id: string;
+  decision_code: string; configuration_digest: string; configuration_json: string; report_id: string | null;
+  workflow_run_id: string | null; started_at: string; invalidated_at: string | null;
+}
+interface Snapshot {
+  selection: Selection; guide: PlaybookGuide; integrationName: string; formName: string; queueName: string; playbookName: string;
+  workflowVersionId: string; pinId: string; routingId: string; queueVersionId: string; policyVersionId: string;
+  records: Row[][]; runtime: Record<string, string | boolean>;
+}
+const denied = () => new ApiError(403, "integration_verification_denied", "Verifying a customer connection requires integration, playbook and full case/evidence access.");
+function assertAccess(session: OperatorSession, queueId?: string) {
+  const p = session.permissions;
+  if (!p.manageComponents || !p.manageIntegrations || !p.manageWorkflows || !p.readReports || !p.readEvidence || session.fieldScope != null) throw denied();
+  if (queueId && session.queueScope != null && !session.queueScope.includes(queueId)) throw new ApiError(404, "verification_not_found", "This verification is not available in your queues.");
+}
+async function hash(value: unknown) {
+  const bytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonicalJson(value)));
+  return [...new Uint8Array(bytes)].map(byte => byte.toString(16).padStart(2, "0")).join("");
+}
+function localSandbox(env: Env) { return env.AI_LOCAL_FIXTURE_ENABLED === "true"; }
+function selection(row: CheckRow): Selection { return { integrationId: row.integration_id, formVersionId: row.form_version_id, queueId: row.queue_id, decisionCode: row.decision_code }; }
+
+export async function loadVerificationChoices(env: Env, session: OperatorSession): Promise<VerificationChoice> {
+  assertAccess(session);
+  const [integrations, forms, pins] = await env.DB.batch<Row>([
+    env.DB.prepare("SELECT id, name, form_version_id AS formVersionId FROM application_integrations WHERE installation_id='default' AND enabled=1 ORDER BY name, id"),
+    env.DB.prepare("SELECT id,title AS name FROM report_form_versions WHERE installation_id='default' AND published_at IS NOT NULL AND retired_at IS NULL ORDER BY title,version DESC"),
+    env.DB.prepare(`SELECT q.id AS queueId,q.name AS queueName,d.name,v.id AS workflowVersionId,v.graph_json
+      FROM queue_workflow_pins p JOIN queue_definitions q ON q.id=p.queue_id JOIN workflow_versions v ON v.id=p.workflow_version_id JOIN workflow_definitions d ON d.id=v.workflow_id
+      WHERE p.mode='primary' AND p.deactivated_at IS NULL AND q.enabled=1 AND q.status='active' AND v.retired_at IS NULL
+      AND v.authority_mode IN ('assist','bounded_auto') AND json_type(v.graph_json,'$.playbook')='object'
+      AND (?1=1 OR q.id IN (SELECT value FROM json_each(?2))) ORDER BY q.name,p.activated_at DESC`).bind(session.queueScope == null ? 1 : 0, canonicalJson(session.queueScope ?? [])),
+  ]);
+  return {
+    integrations: integrations.results.map(r => ({ id: String(r.id), name: String(r.name), formVersionId: r.formVersionId == null ? null : String(r.formVersionId) })),
+    forms: forms.results.map(r => ({ id: String(r.id), name: String(r.name) })),
+    playbooks: pins.results.flatMap(r => { try { const guide = parsePlaybook(JSON.parse(String(r.graph_json)).playbook); return [{ queueId: String(r.queueId), queueName: String(r.queueName), name: String(r.name), workflowVersionId: String(r.workflowVersionId), decisionCodes: guide.outcomes.decision_codes }]; } catch { return []; } }),
+  };
+}
+
+/** Secret-free snapshot of the selected path. Reads share one D1 transaction. */
+async function snapshot(env: Env, choice: Selection): Promise<Snapshot> {
+  const pin = await env.DB.prepare(`SELECT p.id AS pinId,p.workflow_version_id AS workflowVersionId,q.active_version_id AS queueVersionId,q.name AS queueName,d.name AS playbookName,v.graph_json
+    FROM queue_workflow_pins p JOIN queue_definitions q ON q.id=p.queue_id JOIN workflow_versions v ON v.id=p.workflow_version_id JOIN workflow_definitions d ON d.id=v.workflow_id
+    WHERE p.queue_id=?1 AND p.mode='primary' AND p.deactivated_at IS NULL AND q.enabled=1 AND q.status='active'
+      AND v.retired_at IS NULL AND v.authority_mode IN ('assist','bounded_auto') AND json_type(v.graph_json,'$.playbook')='object'
+    ORDER BY p.activated_at DESC,p.id DESC LIMIT 1`).bind(choice.queueId).first<Row>();
+  if (!pin) throw new ApiError(409, "verification_configuration_unavailable", "Activate a primary playbook for this queue before starting verification.");
+  const guide = parsePlaybook(JSON.parse(String(pin.graph_json)).playbook);
+  if (!guide.outcomes.decision_codes.includes(choice.decisionCode)) throw new ApiError(400, "verification_decision_invalid", "Choose an outcome supported by this playbook.");
+  const dependencyComponents = await env.DB.prepare(`SELECT dependency_version_id AS id FROM workflow_dependencies WHERE workflow_version_id=?1 AND dependency_type='component'
+    UNION SELECT json_extract(value,'$.component_version_id') AS id FROM json_each((SELECT rules_json FROM routing_rule_versions WHERE installation_id='default' AND published_at IS NOT NULL ORDER BY version DESC LIMIT 1),'$.intake_enrichments')`).bind(String(pin.workflowVersionId)).all<{id:string}>();
+  const componentIds = canonicalJson([...new Set([...guide.evidence.map(item => item.component_version_id), ...guide.outcomes.actions.map(item => item.component_version_id), ...dependencyComponents.results.map(item=>item.id)])].filter(Boolean).sort());
+  const connectionIds = `SELECT connection_version_id FROM component_versions WHERE id IN (SELECT value FROM json_each(?1)) UNION SELECT dependency_version_id FROM workflow_dependencies WHERE workflow_version_id=?2 AND dependency_type='connection'`;
+  const query = (sql: string, ...values: (string | number | null)[]) => values.length ? env.DB.prepare(sql).bind(...values) : env.DB.prepare(sql);
+  const results = await env.DB.batch<Row>([
+    query("SELECT * FROM application_integrations WHERE id=?1 AND installation_id='default' AND enabled=1", choice.integrationId),
+    query("SELECT * FROM report_form_versions WHERE id=?1 AND published_at IS NOT NULL AND retired_at IS NULL", choice.formVersionId),
+    query("SELECT * FROM queue_definitions WHERE id=?1", choice.queueId),
+    query("SELECT * FROM queue_versions WHERE id=?1", String(pin.queueVersionId)),
+    query("SELECT * FROM queue_workflow_pins WHERE queue_id=?1 AND mode='primary' AND deactivated_at IS NULL ORDER BY id", choice.queueId),
+    query("SELECT * FROM workflow_versions WHERE id=?1", String(pin.workflowVersionId)),
+    query("SELECT * FROM routing_rule_versions WHERE installation_id='default' AND published_at IS NOT NULL ORDER BY version DESC LIMIT 1"),
+    query("SELECT * FROM installations WHERE id='default'"),
+    query("SELECT * FROM policy_versions WHERE id=?1", guide.policy_version_id),
+    query("SELECT * FROM component_versions WHERE id IN (SELECT value FROM json_each(?1)) ORDER BY id", componentIds),
+    query("SELECT d.* FROM component_definitions d WHERE d.id IN (SELECT definition_id FROM component_versions WHERE id IN (SELECT value FROM json_each(?1))) ORDER BY d.id", componentIds),
+    query(`SELECT * FROM connection_versions WHERE id IN (${connectionIds}) ORDER BY id`, componentIds, String(pin.workflowVersionId)),
+    query(`SELECT * FROM connection_definitions WHERE id IN (SELECT connection_id FROM connection_versions WHERE id IN (${connectionIds})) ORDER BY id`, componentIds, String(pin.workflowVersionId)),
+    query(`SELECT id,connection_version_id,strategy,secret_reference,granted_scopes_json,status,created_at,updated_at FROM connection_credentials WHERE connection_version_id IN (${connectionIds}) ORDER BY id`, componentIds, String(pin.workflowVersionId)),
+    query("SELECT * FROM message_template_versions WHERE id IN (SELECT value FROM json_each(?1)) ORDER BY id", canonicalJson(guide.outcomes.notices.map(item => item.template_version_id))),
+    query("SELECT * FROM workflow_dependencies WHERE workflow_version_id=?1 ORDER BY dependency_type,dependency_key", String(pin.workflowVersionId)),
+    query("SELECT id,key_id,status,valid_from,expires_at,created_at,revoked_at FROM integration_api_keys WHERE integration_id=?1 ORDER BY id", choice.integrationId),
+    query("SELECT * FROM routing_agent_versions WHERE installation_id='default' AND published_at IS NOT NULL ORDER BY version DESC LIMIT 1"),
+    query("SELECT * FROM agent_versions WHERE id=?1", guide.investigation.enabled ? guide.investigation.agent_version_id : ""),
+    query("SELECT * FROM model_alias_versions WHERE id IN (SELECT model_alias_version_id FROM agent_versions WHERE id=?1)", guide.investigation.enabled ? guide.investigation.agent_version_id : ""),
+  ]);
+  const records = results.map(result => result.results);
+  const integration = records[0]?.[0], form = records[1]?.[0], routing = records[6]?.[0];
+  if (!integration || !form || !routing || (integration.form_version_id && integration.form_version_id !== choice.formVersionId)
+    || records[4]?.length !== 1 || records[4][0]?.id !== pin.pinId || records[2]?.[0]?.active_version_id !== pin.queueVersionId) {
+    throw new ApiError(409, "verification_configuration_unavailable", "The reporting form or active playbook changed. Refresh the setup and choose the current configuration.");
+  }
+  const secretNames = new Set(["CONTEXT_SIGNING_SECRET", "INTEGRATION_API_KEYS_JSON", "NOTIFICATION_WEBHOOK_SECRET", "CREDENTIAL_ENCRYPTION_KEY", "RATE_LIMIT_PEPPER", "TURNSTILE_SECRET_KEY", "AI_LOCAL_FIXTURE_JSON"]);
+  for (const row of [...(records[11] ?? []), ...(records[13] ?? [])]) if (row.secret_reference) secretNames.add(String(row.secret_reference));
+  const runtime: Record<string, string | boolean> = {
+    publicUrl: env.PUBLIC_BASE_URL ?? "", publicIntegrationId: env.PUBLIC_INTEGRATION_ID ?? "", turnstileSiteKey: env.TURNSTILE_SITE_KEY ?? "", contextTtl: env.CONTEXT_TOKEN_TTL_SECONDS ?? "", allowedOrigins: env.ALLOWED_ORIGINS ?? "", notificationUrl: env.NOTIFICATION_WEBHOOK_URL ?? "",
+    emailFrom: env.REPORTER_EMAIL_FROM ?? "", emailAvailable: Boolean(env.REPORTER_EMAIL), localSandbox: localSandbox(env),
+  };
+  for (const name of [...secretNames].sort()) { const value: unknown = Reflect.get(env, name); runtime[`credential:${name}`] = await hash(typeof value === "string" ? value : null); }
+  return { selection: choice, guide, integrationName: String(integration.name), formName: String(form.title), queueName: String(pin.queueName), playbookName: String(pin.playbookName), workflowVersionId: String(pin.workflowVersionId), pinId: String(pin.pinId), routingId: String(routing.id), queueVersionId: String(pin.queueVersionId), policyVersionId: guide.policy_version_id, records, runtime };
+}
+
+async function current(env: Env, row: CheckRow): Promise<boolean> {
+  if (row.invalidated_at) return false;
+  try { if (await hash(await snapshot(env, selection(row))) === row.configuration_digest) return true; }
+  catch (error) { if (!(error instanceof ApiError) || ![400,409].includes(error.status)) throw error; }
+  await env.DB.prepare("UPDATE integration_verifications SET invalidated_at=COALESCE(invalidated_at,?2) WHERE id=?1").bind(row.id,new Date().toISOString()).run();
+  return false;
+}
+
+export async function startIntegrationVerification(env: Env, session: OperatorSession, choice: Selection): Promise<IntegrationVerification> {
+  assertAccess(session, choice.queueId);
+  const config = await snapshot(env, choice), id = crypto.randomUUID(), startedAt = new Date().toISOString();
+  await env.DB.prepare(`INSERT INTO integration_verifications (id,installation_id,integration_id,form_version_id,queue_id,workflow_version_id,pin_id,decision_code,configuration_digest,configuration_json,started_by,started_at)
+    VALUES (?1,'default',?2,?3,?4,?5,?6,?7,?8,?9,?10,?11)`).bind(id,choice.integrationId,choice.formVersionId,choice.queueId,config.workflowVersionId,config.pinId,choice.decisionCode,await hash(config),canonicalJson(config),session.actor.id,startedAt).run();
+  return loadIntegrationVerification(env,session,id);
+}
+
+async function checkRow(env: Env, session: OperatorSession, id: string) {
+  assertAccess(session);
+  const row = await env.DB.prepare("SELECT * FROM integration_verifications WHERE id=?1").bind(id).first<CheckRow>();
+  if (!row) throw new ApiError(404,"verification_not_found","This verification could not be found.");
+  assertAccess(session,row.queue_id); return row;
+}
+const candidateSql = `SELECT r.id,r.public_reference AS reference,r.received_at AS receivedAt,wr.id AS runId
+  FROM reports r JOIN workflow_runs wr ON wr.report_id=r.id
+  WHERE r.integration_id=?1 AND r.form_version_id=?2 AND r.queue_id=?3 AND r.received_at>?4
+    AND r.routing_rule_version_id=?5 AND r.queue_version_id=?6 AND r.policy_version_id=?7
+    AND r.source IN ('server_api','signed_widget','public_page') AND r.routing_status='complete'
+    AND wr.run_kind='primary' AND wr.authority_mode IN ('assist','bounded_auto') AND wr.workflow_version_id=?8 AND wr.pin_id=?9
+    AND wr.created_at>=r.received_at AND wr.state NOT IN ('superseded','terminated')
+    AND NOT EXISTS (SELECT 1 FROM integration_verifications other WHERE other.report_id=r.id AND other.id!=?10)`;
+function candidateQuery(env: Env, row: CheckRow, config: Snapshot, reportId?: string) {
+  const sql = `${candidateSql}${reportId ? " AND r.id=?11" : ""} ORDER BY r.received_at DESC,r.id,wr.created_at DESC LIMIT 20`;
+  const values = [row.integration_id,row.form_version_id,row.queue_id,row.started_at,config.routingId,config.queueVersionId,config.policyVersionId,row.workflow_version_id,row.pin_id,row.id];
+  return env.DB.prepare(sql).bind(...(reportId ? [...values,reportId] : values));
+}
+
+export async function bindIntegrationVerification(env: Env, session: OperatorSession, id: string, reportId: string): Promise<IntegrationVerification> {
+  const row = await checkRow(env,session,id);
+  if (row.report_id) {
+    if (row.report_id === reportId) return loadIntegrationVerification(env,session,id);
+    throw new ApiError(409,"verification_case_already_linked","This check already follows another case. Start a new check to use a different case.");
+  }
+  if (!await current(env,row)) throw new ApiError(409,"verification_configuration_changed","Configuration changed. Start a new check before submitting a fresh report.");
+  const config = JSON.parse(row.configuration_json) as Snapshot;
+  const candidate = await candidateQuery(env,row,config,reportId).first<{ id: string; runId: string }>();
+  if (!candidate) throw new ApiError(409,"verification_case_mismatch","Choose a fresh report from this integration and form after it reaches the selected queue and playbook.");
+  try {
+    // Eligibility and compare-and-set run in the same SQL statement. A second browser cannot replace the linked case.
+    const eligibility = candidateSql.replace(/\?(\d+)/gu, (_, position: string) => `?${Number(position) + 4}`);
+    const result = await env.DB.prepare(`UPDATE integration_verifications SET report_id=?2,workflow_run_id=?3,linked_at=?4
+      WHERE id=?1 AND report_id IS NULL AND invalidated_at IS NULL AND EXISTS (
+        SELECT 1 FROM (${eligibility}) eligible WHERE eligible.id=?2 AND eligible.runId=?3
+      )`).bind(row.id,reportId,candidate.runId,new Date().toISOString(),row.integration_id,row.form_version_id,row.queue_id,row.started_at,config.routingId,config.queueVersionId,config.policyVersionId,row.workflow_version_id,row.pin_id,row.id).run();
+    if (!result.meta.changes) throw new ApiError(409,"verification_case_already_linked","Another change was saved first. Refresh this check.");
+  } catch (error) { if (error instanceof ApiError) throw error; if (error instanceof Error && error.message.includes("UNIQUE constraint")) throw new ApiError(409,"verification_case_already_linked","Another check already follows this case. Submit a fresh report."); throw error; }
+  return loadIntegrationVerification(env,session,id);
+}
+
+function stage(key: VerificationStage["key"], title: string, state: VerificationStage["state"], detail: string): VerificationStage { return { key,title,state,detail }; }
+async function evidenceStages(env: Env, row: CheckRow, config: Snapshot): Promise<{ report: IntegrationVerification["report"]; stages: VerificationStage[] }> {
+  const [reportResult, runResult, decisionsResult, findingsResult, actionsResult, noticesResult] = await env.DB.batch<Row>([
+    env.DB.prepare("SELECT id,public_reference AS reference,state,queue_id,form_version_id,routing_rule_version_id,policy_version_id,queue_version_id,integration_id FROM reports WHERE id=?1").bind(row.report_id),
+    env.DB.prepare("SELECT id,state,report_id,run_kind,authority_mode,pin_id,workflow_version_id FROM workflow_runs WHERE id=?1").bind(row.workflow_run_id),
+    env.DB.prepare("SELECT id,decision_code,idempotency_key FROM decisions WHERE report_id=?1 ORDER BY created_at DESC,rowid DESC LIMIT 1").bind(row.report_id),
+    env.DB.prepare(`SELECT f.component_version_id,s.node_id,f.status,f.expires_at,f.superseded_at,
+      EXISTS (SELECT 1 FROM component_runs cr WHERE cr.finding_id=f.id AND cr.report_id=f.report_id AND cr.workflow_run_id=f.run_id
+        AND cr.step_run_id=f.step_run_id AND cr.component_version_id=f.component_version_id AND cr.state='succeeded' AND cr.cache_hit=0 AND cr.attempt_count>0
+        AND (NOT EXISTS (SELECT 1 FROM component_versions cv WHERE cv.id=f.component_version_id AND cv.connection_version_id IS NOT NULL)
+          OR EXISTS (SELECT 1 FROM connection_attempts ca JOIN component_versions cv ON cv.id=f.component_version_id WHERE ca.component_run_id=cr.id AND ca.connection_version_id=cv.connection_version_id AND ca.operation_id=cr.operation_id AND ca.response_class='success' AND ca.response_digest IS NOT NULL))) AS fresh_read
+      FROM findings f JOIN workflow_step_runs s ON s.id=f.step_run_id AND s.run_id=f.run_id
+      WHERE f.report_id=?1 AND f.run_id=?2 ORDER BY f.created_at DESC,f.id`).bind(row.report_id,row.workflow_run_id),
+    env.DB.prepare(`SELECT p.id,p.state,p.action_code,p.component_version_id,p.confirmed_at,p.last_receipt_json,p.operation_id,p.payload_digest,p.decision_id,
+      EXISTS (SELECT 1 FROM connection_attempts a JOIN component_versions cv ON cv.id=p.component_version_id WHERE a.action_proposal_id=p.id AND a.operation_id=p.operation_id AND a.connection_version_id=cv.connection_version_id AND a.response_class='success' AND a.response_digest IS NOT NULL) AS customer_attempt
+      FROM action_proposals p WHERE p.report_id=?1 AND p.run_id=?2 ORDER BY p.created_at DESC,p.id`).bind(row.report_id,row.workflow_run_id),
+    env.DB.prepare(`SELECT m.audience,m.template_version_id,m.delivery_state,m.audience_checked_at,n.decision_id,
+      CASE WHEN n.delivery_state='delivered' AND c.report_id=m.report_id AND c.audience=m.audience AND participant.report_id=m.report_id AND participant.audience=m.audience
+        AND participant.contact_mode!='none' AND participant.reference_redacted_at IS NULL AND (
+          EXISTS (SELECT 1 FROM email_deliveries e WHERE e.message_id=m.id AND e.audience=m.audience AND e.state='delivered' AND e.delivered_at IS NOT NULL AND e.attempt_count>0)
+          OR EXISTS (SELECT 1 FROM notification_outbox o JOIN notification_attempts a ON a.notification_id=o.id
+            WHERE o.notice_id=n.id AND o.status='delivered' AND o.payload_redacted_at IS NULL AND a.response_status BETWEEN 200 AND 299
+            AND json_extract(o.payload_json,'$.audience')=m.audience
+            AND json_extract(o.payload_json,'$.recipient_reference')=participant.reference)
+        ) THEN 1 ELSE 0 END AS confirmed
+      FROM case_messages m JOIN notices n ON n.message_id=m.id AND n.report_id=m.report_id AND n.audience=m.audience AND n.template_version_id=m.template_version_id
+      JOIN conversations c ON c.id=m.conversation_id JOIN report_participants participant ON participant.id=c.participant_id
+      WHERE m.report_id=?1 AND m.workflow_run_id=?2 AND m.direction='outbound' AND m.redacted_at IS NULL AND n.redacted_at IS NULL
+      ORDER BY m.created_at DESC,m.id`).bind(row.report_id,row.workflow_run_id),
+  ]);
+  const report = reportResult.results[0], run = runResult.results[0], decision = decisionsResult.results[0];
+  const identityMatches = report && run && report.integration_id===row.integration_id && report.form_version_id===row.form_version_id && report.queue_id===row.queue_id
+    && report.routing_rule_version_id===config.routingId && report.queue_version_id===config.queueVersionId && report.policy_version_id===config.policyVersionId
+    && run.report_id===row.report_id && run.run_kind==='primary' && ['assist','bounded_auto'].includes(String(run.authority_mode)) && run.pin_id===row.pin_id && run.workflow_version_id===row.workflow_version_id;
+  const stages: VerificationStage[] = [stage("intake","Receive the fresh report",identityMatches?"complete":"blocked",identityMatches?"This case came through the selected integration, form, routing and active playbook.":"The linked case no longer matches the selected route and playbook. Start a fresh check.")];
+  const required = config.guide.evidence.filter(item => item.required), now = new Date().toISOString();
+  const missing = required.filter(item => !findingsResult.results.some(f => f.component_version_id===item.component_version_id && f.node_id===`evidence-${item.id}` && f.status==='available' && !f.superseded_at && (!f.expires_at || String(f.expires_at)>now) && f.fresh_read===1));
+  const failedEvidence = missing.some(item => findingsResult.results.some(f => f.component_version_id===item.component_version_id && f.node_id===`evidence-${item.id}` && ['unavailable','invalid','stale'].includes(String(f.status))));
+  stages.push(stage("context","Retrieve required customer evidence",!required.length?"not_required":!missing.length?"complete":failedEvidence?"blocked":"waiting",!required.length?"This path has no required evidence capabilities.":missing.length?`Still need a fresh successful customer read: ${missing.map(item => item.label).join(", ")}. Cached evidence does not verify the connection.`:"Every required capability returned fresh evidence for this case."));
+  const expectedActions = config.guide.outcomes.actions.filter(item => item.decision_code===row.decision_code);
+  const actionComplete = (a: Row) => { try { const receipt = JSON.parse(String(a.last_receipt_json)); return a.state==='applied' && a.customer_attempt===1 && a.confirmed_at && receipt.status==='applied' && receipt.action_id===a.id && receipt.operation_id===a.operation_id && receipt.payload_digest===a.payload_digest && a.decision_id===decision?.id; } catch { return false; } };
+  const missingActions = expectedActions.filter(item => !actionsResult.results.some(a => a.action_code===item.action_code && a.component_version_id===item.component_version_id && actionComplete(a)));
+  const failedActions = actionsResult.results.some(a => ['failed','rejected','cancelled','compensation_required','compensated'].includes(String(a.state)));
+  stages.push(stage("action","Confirm the customer change",!expectedActions.length?"not_required":!missingActions.length?"complete":failedActions?"blocked":"waiting",!expectedActions.length?"No customer action is configured for this outcome. Other action paths need their own check.":missingActions.length?`Awaiting an applied receipt for ${missingActions.map(item => item.action_code.replaceAll('_',' ')).join(', ')}. Approval or acceptance alone is insufficient.`:"The customer application confirmed each approved change for this decision."));
+  const expectedNotices = config.guide.outcomes.notices;
+  const missingNotices = expectedNotices.filter(item => !noticesResult.results.some(n => n.audience===item.audience && n.template_version_id===item.template_version_id && n.decision_id===decision?.id && n.delivery_state==='delivered' && n.audience_checked_at && n.confirmed===1));
+  const failedNotices = noticesResult.results.some(n => ['failed','suppressed'].includes(String(n.delivery_state)));
+  stages.push(stage("notice","Deliver the outcome to participants",!expectedNotices.length?"not_required":!missingNotices.length?"complete":failedNotices?"blocked":"waiting",!expectedNotices.length?"This path has no configured participant outcome notices.":missingNotices.length?`Awaiting confirmed delivery to ${missingNotices.map(item => item.audience==='reporter'?'the reporter':'the affected person').join(' and ')}. Open the case Outcome section to recover the participant delivery.`:"The configured outcome reached the delivery provider for each correct case participant. This does not establish that they read it."));
+  const terminal = identityMatches && run.state==='succeeded' && ['resolved_by_human','resolved_by_ai','closed'].includes(String(report.state))
+    && decision?.decision_code===row.decision_code && String(decision.idempotency_key).startsWith(`workflow-decision:${row.workflow_run_id}:`)
+    && !actionsResult.results.some(a => !actionComplete(a)) && !noticesResult.results.some(n => n.delivery_state!=='delivered');
+  const failed = !identityMatches || ['failed','terminated','repair_required','superseded'].includes(String(run?.state)) || (decision && decision.decision_code!==row.decision_code);
+  stages.push(stage("playbook","Finish this outcome path",terminal?"complete":failed?"blocked":"waiting",terminal?"This primary playbook finished with the selected decision and no unconfirmed actions or messages.":failed?"The case needs attention or followed a different outcome. Open it to review the reason; use a new check for a different scenario.":"Continue the case through review, confirmed customer actions and outcome delivery."));
+  return { report: report?{id:String(report.id),reference:String(report.reference)}:null, stages };
+}
+
+export async function loadIntegrationVerification(env: Env, session: OperatorSession, id: string): Promise<IntegrationVerification> {
+  const row = await checkRow(env,session,id), config = JSON.parse(row.configuration_json) as Snapshot;
+  const currentBefore = await current(env,row);
+  const evidence = row.report_id ? await evidenceStages(env,row,config) : { report:null, stages:[stage("intake","Submit a fresh test report","waiting","Use a safe test account and target in your customer product, then refresh this check and select that report. A check follows normal review, action and notification behavior.")] };
+  const candidates = !row.report_id && currentBefore ? (await candidateQuery(env,row,config).all<{id:string;reference:string;receivedAt:string}>()).results : [];
+  // Recheck after saved evidence reads. Verification is derived on each response, never a durable success flag.
+  const stillCurrent = currentBefore && await current(env,row);
+  const state: IntegrationVerification["state"] = !stillCurrent ? "stale" : !row.report_id ? "awaiting_case" : evidence.stages.some(s=>s.state==='blocked') ? "blocked" : evidence.stages.every(s=>['complete','not_required'].includes(s.state)) ? "verified" : "in_progress";
+  return { id:row.id,startedAt:row.started_at,integrationName:config.integrationName,formName:config.formName,queueName:config.queueName,playbookName:config.playbookName,decisionCode:row.decision_code,state,report:evidence.report,candidates:candidates.map(({id,reference,receivedAt})=>({id,reference,receivedAt})),stages:evidence.stages,localSandbox:localSandbox(env)||config.runtime.localSandbox===true };
+}
+
+export async function listIntegrationVerifications(env: Env, session: OperatorSession): Promise<IntegrationVerificationList> {
+  assertAccess(session);
+  const [choices, rows] = await Promise.all([
+    loadVerificationChoices(env,session),
+    env.DB.prepare(`SELECT id FROM integration_verifications WHERE (?1=1 OR queue_id IN (SELECT value FROM json_each(?2))) ORDER BY started_at DESC,id DESC LIMIT 5`).bind(session.queueScope==null?1:0,canonicalJson(session.queueScope??[])).all<{id:string}>(),
+  ]);
+  const runs = await Promise.all(rows.results.map(row=>loadIntegrationVerification(env,session,row.id)));
+  return { choices,runs };
+}
+
+/** Caller must use requireOperator for authentication and existing CSRF enforcement. */
+export async function handleIntegrationVerification(request: Request, env: Env, session: OperatorSession): Promise<Response> {
+  const match = /^\/v1\/admin\/integration-verifications(?:\/([^/]+)(?:\/(bind))?)?$/u.exec(new URL(request.url).pathname);
+  if (!match) throw new ApiError(404,"not_found","This route does not exist.");
+  assertAccess(session);
+  if (request.method==='GET' && !match[2]) return json(match[1]?await loadIntegrationVerification(env,session,match[1]):await listIntegrationVerifications(env,session));
+  if (request.method!=='POST' || (match[1] && !match[2])) return methodNotAllowed(match[1]&&match[2]?['POST']:['GET',...(!match[1]?['POST']:[])]);
+  const body = await readJsonObject(request,4096);
+  const text = (key:string) => { const value = body[key]; if(typeof value!=='string' || !value.trim() || value.length>160) throw new ApiError(400,"verification_input_invalid",`Choose a valid ${key.replaceAll('_',' ')}.`); return value.trim(); };
+  if(match[1]) return json(await bindIntegrationVerification(env,session,match[1],text('report_id')));
+  return json(await startIntegrationVerification(env,session,{integrationId:text('integration_id'),formVersionId:text('form_version_id'),queueId:text('queue_id'),decisionCode:text('decision_code')}),{status:201});
+}

package/template/src/investigation-evidence.ts

@@ -0,0 +1,95 @@
+import { canonicalJson } from "./audit";
+import { loadAgent } from "./agent-executor";
+import { ComponentExecutionError, loadWorkflowExecutionContext, executeAssistantReadOnlyComponent } from "./component-executor";
+import { parseWorkflowGraph } from "./workflow-platform-validation";
+import { evaluateInputMapping, validateJsonSchemaValue } from "./workflow-expressions";
+import { sha256 } from "./report-crypto";
+import type { JsonObject, WorkflowNodeV1 } from "./workflow-platform-types";
+
+export interface InvestigationRequest { runId: string; node: WorkflowNodeV1; branchKey: string; stepRunId: string }
+export interface InvestigationSource { id: string; digest: string; label: string; expiresAt: string | null }
+export type InvestigationConfig = Awaited<ReturnType<typeof loadInvestigation>>;
+export function investigationError(code: string): never { throw new ComponentExecutionError(code, false); }
+export const investigationTools = ["read_report_context", "read_findings", "check_evidence", "finish_investigation"];
+
+export async function loadInvestigation(env: Env, request: InvestigationRequest) {
+  const row = await env.DB.prepare(`SELECT r.state, v.graph_json AS graphJson FROM workflow_runs r JOIN workflow_versions v ON v.id=r.workflow_version_id WHERE r.id=?1`).bind(request.runId).first<{state:string;graphJson:string}>();
+  if (!row || ["succeeded","failed","terminated","superseded"].includes(row.state)) investigationError("investigation_run_unavailable");
+  const graph = parseWorkflowGraph(JSON.parse(row.graphJson));
+  const node = graph.nodes.find(candidate => candidate.id === request.node.id);
+  if (!node || node.kind !== "ai_proposal" || node.config.investigator !== true || canonicalJson(node) !== canonicalJson(request.node)
+    || request.stepRunId !== `${request.runId}:${node.id}:${request.branchKey || "main"}:1`) investigationError("investigation_scope_denied");
+  const agent = await loadAgent(env.DB, String(node.config.agent_version_id));
+  // Provider configuration is authoritative. A missing adapter must never become a fallback to another provider.
+  if (agent.provider !== "workers_ai" || !agent.model.startsWith("@cf/")) investigationError("investigation_model_adapter_unavailable");
+  const runtime = await loadWorkflowExecutionContext(env, request.runId, request.branchKey);
+  if (runtime.row.authorityMode === "off") investigationError("investigation_authority_disabled");
+  const input = evaluateInputMapping(node.inputMapping, runtime.context);
+  // Findings are fetched through a scoped tool, preserving their source identities and freshness.
+  if (validateJsonSchemaValue(input, JSON.parse(agent.inputSchemaJson)).length) investigationError("agent_input_schema_invalid");
+  delete input.findings;
+  const inputJson = canonicalJson(input);
+  if (new TextEncoder().encode(inputJson).byteLength > 65536) investigationError("investigation_context_too_large");
+  const policyVersionId=graph.playbook?.policy_version_id;
+  const policy=policyVersionId?await env.DB.prepare(`SELECT id,title AS name,rules_json AS rulesJson FROM policy_versions WHERE id=?1 AND published_at IS NOT NULL`).bind(policyVersionId).first<{id:string;name:string;rulesJson:string}>():null;
+  if(policyVersionId && !policy) investigationError("investigation_policy_unavailable");
+  const manifest: string[] = JSON.parse(agent.toolManifestJson);
+  const allowedTools = investigationTools.filter(tool => tool === "finish_investigation" || manifest.includes(tool));
+  return { agent, runtime:{...runtime,context:{}}, input, inputJson, inputDigest: `sha256:${await sha256(inputJson)}`, allowedTools,
+    maxSteps: Math.max(1, Math.min(20, Number(node.config.max_steps) || 8, agent.maximumTurns)),
+    policy:policy?{id:policy.id,name:policy.name,rules:JSON.parse(policy.rulesJson),customer_guidance:graph.playbook?.policy_text??""}:null,
+    policyCode:graph.playbook?.policy_code??null,
+    instructions: graph.playbook?.investigation.instructions ?? "",
+    decisionCodes: graph.playbook?.outcomes.decision_codes ?? [],
+    capabilities: graph.playbook?.evidence ?? [],
+  };
+}
+
+export async function assertInvestigationActive(env: Env, request: InvestigationRequest) {
+  const row = await env.DB.prepare(`SELECT state FROM workflow_runs WHERE id=?1`).bind(request.runId).first<{state:string}>();
+  if (!row || ["succeeded","failed","terminated","superseded"].includes(row.state)) investigationError("investigation_run_unavailable");
+}
+
+export async function readInvestigationFinding(env: Env, config: InvestigationConfig, id?: string) {
+  const base = `FROM findings WHERE report_id=?1 AND (run_id=?2 OR run_id IS NULL) AND status='available' AND (expires_at IS NULL OR expires_at>?3)`;
+  const params = [config.runtime.row.reportId,config.runtime.row.runId,new Date().toISOString()];
+  if (!id) {
+    const rows = await env.DB.prepare(`SELECT id, finding_type AS type, summary, created_at AS createdAt, expires_at AS expiresAt ${base} ORDER BY created_at DESC,id LIMIT 100`).bind(...params).all();
+    return { sources: rows.results, instruction: "Read a source by its id before citing it. Summaries alone are not reviewed evidence." };
+  }
+  const row = await env.DB.prepare(`SELECT id, finding_type AS type, data_json AS dataJson, provenance_json AS provenanceJson, uncertainty_json AS uncertaintyJson, output_digest AS digest, expires_at AS expiresAt ${base} AND id=?4`).bind(...params,id).first<{id:string;type:string;dataJson:string;provenanceJson:string;uncertaintyJson:string;digest:string;expiresAt:string|null}>();
+  if (!row) investigationError("investigation_source_unavailable");
+  if (new TextEncoder().encode(row.dataJson).byteLength > 32768) investigationError("investigation_source_too_large");
+  return { source: { id:row.id,digest:`sha256:${await sha256(row.dataJson)}`,label:row.type,expiresAt:row.expiresAt } as InvestigationSource,
+    data:JSON.parse(row.dataJson), provenance:JSON.parse(row.provenanceJson), uncertainty:JSON.parse(row.uncertaintyJson) };
+}
+
+export async function checkInvestigationEvidence(env: Env, request: InvestigationRequest, config: InvestigationConfig, capabilityId: string) {
+  const capability = config.capabilities.find(candidate => candidate.id === capabilityId);
+  if (!capability) investigationError("investigation_capability_denied");
+  const runtime = await loadWorkflowExecutionContext(env,request.runId,request.branchKey);
+  // The customer-approved mapping owns the target and input. The model chooses only a declared capability.
+  return executeAssistantReadOnlyComponent(env,{ reportId:config.runtime.row.reportId,componentVersionId:capability.component_version_id,
+    componentInput:evaluateInputMapping(capability.input_mapping,runtime.context),operationId:`${request.stepRunId}:evidence:${capability.id}`,
+    actorId:request.stepRunId,source:"investigator" });
+}
+
+export async function validateInvestigationProposal(env: Env, config: InvestigationConfig, sources: InvestigationSource[], proposal: JsonObject) {
+  if (validateJsonSchemaValue(proposal,JSON.parse(config.agent.outputSchemaJson)).length) investigationError("agent_output_schema_invalid");
+  if (!["ready_for_review","needs_information"].includes(String(proposal.result_code)) || typeof proposal.summary !== "string" || !proposal.summary.trim()
+    || !Array.isArray(proposal.citations) || !Array.isArray(proposal.missing_information) || !Array.isArray(proposal.uncertainty)
+    || [...proposal.citations,...proposal.missing_information,...proposal.uncertainty].some(value => typeof value !== "string")) investigationError("investigation_proposal_invalid");
+  if (proposal.result_code === "ready_for_review" && (!proposal.citations.length || proposal.missing_information.length)) investigationError("investigation_evidence_incomplete");
+  if (proposal.decision_code && config.decisionCodes.length && !config.decisionCodes.includes(String(proposal.decision_code))) investigationError("investigation_outcome_denied");
+  if (proposal.policy_code && config.policyCode && proposal.policy_code!==config.policyCode) investigationError("investigation_policy_denied");
+  if (proposal.action || proposal.message || proposal.automation_eligible === true) investigationError("investigation_effect_denied");
+  for (const id of proposal.citations) {
+    const source = sources.find(candidate => candidate.id === id);
+    if (!source) investigationError("investigation_citation_not_read");
+    if (source.id === `case:${config.runtime.row.reportId}:intake`) continue;
+    const current = await readInvestigationFinding(env,config,source.id);
+    if (!("source" in current) || current.source?.digest !== source.digest) investigationError("investigation_source_changed");
+  }
+  if (new TextEncoder().encode(canonicalJson(proposal)).byteLength > 32768) investigationError("agent_output_too_large");
+  return proposal;
+}

package/template/src/investigator-fixture.ts

@@ -0,0 +1,30 @@
+import type { LanguageModelV4, LanguageModelV4StreamPart } from "@ai-sdk/provider";
+
+/** Explicit local-only orchestration fixture. It makes no inference-quality claim or provider call. */
+export function investigatorFixture(env: Pick<Env,"AI_LOCAL_FIXTURE_ENABLED"|"AI_LOCAL_FIXTURE_JSON"|"PUBLIC_BASE_URL">): LanguageModelV4 | null {
+  if (env.AI_LOCAL_FIXTURE_ENABLED!=="true") return null;
+  let origin: URL;
+  try { origin=new URL(env.PUBLIC_BASE_URL); } catch { throw new Error("investigation_fixture_origin_invalid"); }
+  if (!["localhost","127.0.0.1"].includes(origin.hostname)) throw new Error("investigation_fixture_prohibited");
+  const fixture=JSON.parse(env.AI_LOCAL_FIXTURE_JSON) as {investigator_steps?:{tool:string;input:unknown;delay_ms?:number;error?:boolean}[]};
+  if (!Array.isArray(fixture.investigator_steps) || !fixture.investigator_steps.length || fixture.investigator_steps.length>20) throw new Error("investigation_fixture_missing");
+  return {
+    specificationVersion:"v4",provider:"safest_local_fixture",modelId:"scripted-investigator",supportedUrls:{},
+    async doGenerate(){throw new Error("investigation_fixture_stream_required");},
+    async doStream(options) {
+      const index=options.prompt.reduce((count,message)=>count+(Array.isArray(message.content)?message.content.filter(part=>part.type==="tool-call").length:0),0);
+      const entry=fixture.investigator_steps![Math.min(index,fixture.investigator_steps!.length-1)]!;
+      if(entry.error) throw new Error("investigation_fixture_provider_error");
+      if(entry.delay_ms) await new Promise(resolve=>setTimeout(resolve,Math.min(5000,Math.max(0,entry.delay_ms!))));
+      const sourceIds=options.prompt.flatMap(message=>Array.isArray(message.content)?message.content.flatMap(part=>{
+        if(part.type!=="tool-result" || part.output.type!=="json")return [];
+        const output=part.output.value as {source?:{id?:unknown}};
+        return typeof output?.source?.id==="string"?[output.source.id]:[];
+      }):[]);
+      const input=JSON.parse(JSON.stringify(entry.input).replaceAll('"__LAST_READ_SOURCE__"',JSON.stringify(sourceIds.at(-1)??"missing-fixture-source")));
+      const call={type:"tool-call" as const,toolCallId:`fixture-${index}`,toolName:entry.tool,input:JSON.stringify(input)};
+      const parts:LanguageModelV4StreamPart[]=[{type:"stream-start",warnings:[]},call,{type:"finish",finishReason:{unified:"tool-calls",raw:"tool_calls"},usage:{inputTokens:{total:120,noCache:120,cacheRead:0,cacheWrite:0},outputTokens:{total:40,text:40,reasoning:0}}}];
+      return {stream:new ReadableStream<LanguageModelV4StreamPart>({start(controller){for(const part of parts)controller.enqueue(part);controller.close();}})};
+    },
+  };
+}

package/template/src/notice-delivery.ts

@@ -0,0 +1,19 @@
+import { reconcileAppealCompletion } from "./appeal-continuity";
+
+/** The receipt in D1 is authoritative. Events only shorten the next durable check. */
+export async function signalNoticeDelivery(env: Env, messageId: string, attemptKey: string): Promise<void> {
+  const message = await env.DB.prepare(`SELECT workflow_run_id AS runId, report_id AS reportId, delivery_state AS state FROM case_messages WHERE id = ?1`)
+    .bind(messageId).first<{ runId: string | null; reportId: string; state: string }>();
+  if (message?.state === "delivered") await reconcileAppealCompletion(env.DB,message.reportId);
+  if (!message?.runId) return;
+  try {
+    const { sendWorkflowEvent } = await import("./workflow-runs");
+    await sendWorkflowEvent(env, message.runId, {
+      eventType: `notice.${messageId}.updated`, eventKey: `${messageId}:${attemptKey}:${message.state}`,
+      sourceType: "system", sourceId: "notice-delivery", payload: { message_id: messageId },
+    });
+  } catch {
+    // The workflow also checks its receipt on a bounded timeout.
+    console.warn("Notice delivery recorded; workflow wake-up awaits reconciliation", { messageId });
+  }
+}

package/template/src/notice-recovery.ts

@@ -0,0 +1,81 @@
+import { canonicalJson } from "./audit";
+import { assertOperatorReportAccess } from "./report-auth";
+import { reporterEmailConfigured, selectParticipantDelivery } from "./report-email";
+import { ApiError } from "./report-http";
+import { sha256 } from "./report-crypto";
+import type { DeliveryJob, OperatorSession } from "./report-types";
+
+export async function retryParticipantNotice(env: Env, reportId: string, noticeId: string, expectedUpdatedAt: string, session: OperatorSession, key: string) {
+  if (!session.permissions.messageReporters) throw new ApiError(403, "notice_retry_denied", "Your role cannot retry participant notices.");
+  await assertOperatorReportAccess(env.DB, session, reportId);
+  const replay = await env.DB.prepare(`SELECT action, actor_id AS actorId, target_id AS targetId FROM configuration_mutations WHERE idempotency_key = ?1`)
+    .bind(key).first<{ action: string; actorId: string; targetId: string }>();
+  if (replay) {
+    if (replay.action !== "notice.retry" || replay.actorId !== session.actor.id || replay.targetId !== `${reportId}:${noticeId}`) throw new ApiError(409, "idempotency_key_reused", "This retry key belongs to another request.");
+    return { noticeId, idempotentReplay: true };
+  }
+  const notice = await env.DB.prepare(`SELECT n.id, n.message_id AS messageId, n.audience, n.rendered_body AS body,
+    n.delivery_state AS state, n.updated_at AS updatedAt, n.redacted_at AS redactedAt, m.redacted_at AS messageRedactedAt,
+    r.installation_id AS installationId, r.public_reference AS reference,
+    p.reference AS participantReference, p.contact_mode AS contactMode, p.contact_ciphertext AS contactCiphertext
+    FROM notices n JOIN reports r ON r.id = n.report_id JOIN case_messages m ON m.id = n.message_id
+    LEFT JOIN report_participants p ON p.report_id = n.report_id AND p.audience = n.audience
+    WHERE n.id = ?1 AND n.report_id = ?2`)
+    .bind(noticeId, reportId).first<{ id: string; messageId: string; audience: "reporter" | "affected_user"; body: string; state: string; updatedAt: string; redactedAt: string | null; messageRedactedAt: string | null; installationId: string; reference: string; participantReference: string | null; contactMode: string | null; contactCiphertext: string | null }>();
+  if (!notice) throw new ApiError(404, "notice_not_found", "This participant notice is unavailable.");
+  if (!["failed", "suppressed"].includes(notice.state) || notice.updatedAt !== expectedUpdatedAt || notice.redactedAt || notice.messageRedactedAt) throw new ApiError(409, "notice_changed", "The notice changed or cannot be retried. Refresh its delivery status.");
+  const [email, notification] = await Promise.all([
+    env.DB.prepare(`SELECT id FROM email_deliveries WHERE message_id = ?1 LIMIT 1`).bind(notice.messageId).first<{ id: string }>(),
+    env.DB.prepare(`SELECT id FROM notification_outbox WHERE notice_id = ?1 LIMIT 1`).bind(noticeId).first<{ id: string }>(),
+  ]);
+  const delivery = !email && !notification ? await selectParticipantDelivery({
+    reportId, audience: notice.audience, contactMode: notice.contactMode ?? "", contactCiphertext: notice.contactCiphertext,
+    reference: notice.participantReference, emailEnabled: reporterEmailConfigured(env),
+    notificationEnabled: Boolean(env.NOTIFICATION_WEBHOOK_URL?.trim() && env.NOTIFICATION_WEBHOOK_SECRET?.trim()),
+    contactEncryptionKey: env.CREDENTIAL_ENCRYPTION_KEY, recipientHashPepper: env.RATE_LIMIT_PEPPER,
+  }) : null;
+  if (!email && !notification && !delivery?.channel) throw new ApiError(409, "notice_channel_unavailable", "Connect a participant notification channel and provide contact permission before retrying this notice.");
+  const timestamp = new Date().toISOString();
+  const response = { noticeId, idempotentReplay: false };
+  const guard = `EXISTS (SELECT 1 FROM configuration_mutations WHERE idempotency_key = ?1 AND action = 'notice.retry')`;
+  const statements = [
+    env.DB.prepare(`UPDATE notices SET delivery_state = 'queued', updated_at = ?3 WHERE id = ?1 AND report_id = ?2
+      AND updated_at = ?4 AND delivery_state IN ('failed','suppressed') AND redacted_at IS NULL
+      AND EXISTS (SELECT 1 FROM case_messages WHERE id = notices.message_id AND redacted_at IS NULL)
+      AND (?5 = 1 OR EXISTS (SELECT 1 FROM reports WHERE id = notices.report_id AND queue_id IN (SELECT value FROM json_each(?6))))
+      AND NOT EXISTS (SELECT 1 FROM notification_outbox WHERE notice_id = ?1 AND (status IN ('pending','delivering','delivered') OR terminal = 0))
+      AND NOT EXISTS (SELECT 1 FROM email_deliveries WHERE message_id = notices.message_id AND (state IN ('pending','sending','delivered') OR (state = 'failed' AND next_attempt_at IS NOT NULL)))`)
+      .bind(noticeId, reportId, timestamp, expectedUpdatedAt, session.queueScope === null || session.queueScope === undefined ? 1 : 0, canonicalJson(session.queueScope ?? [])),
+    env.DB.prepare(`INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at)
+      SELECT ?1, 'notice.retry', ?2, ?3, ?4, ?5 WHERE changes() = 1`)
+      .bind(key, session.actor.id, `${reportId}:${noticeId}`, canonicalJson(response), timestamp),
+    env.DB.prepare(`UPDATE case_messages SET delivery_state = 'queued' WHERE id = ?2 AND ${guard}`).bind(key, notice.messageId),
+  ];
+  let job: DeliveryJob;
+  if (email) {
+    statements.push(env.DB.prepare(`UPDATE email_deliveries SET state = 'pending', attempt_limit = attempt_count + 8, next_attempt_at = ?3, last_error_code = NULL, updated_at = ?3 WHERE id = ?2 AND ${guard}`).bind(key, email.id, timestamp));
+    job = { version: 1, type: "deliver_email", jobId: `email:${email.id}`, outboxId: email.id };
+  } else if (notification) {
+    statements.push(env.DB.prepare(`UPDATE notification_outbox SET status = 'pending', terminal = 0, attempt_limit = attempt_count + 8, next_attempt_at = ?3, lease_expires_at = NULL, last_error_code = NULL, updated_at = ?3 WHERE id = ?2 AND ${guard}`).bind(key, notification.id, timestamp));
+    job = { version: 1, type: "deliver_notification", jobId: `notification:${notification.id}`, outboxId: notification.id };
+  } else if (delivery?.channel === "email") {
+    const id = crypto.randomUUID();
+    statements.push(env.DB.prepare(`INSERT INTO email_deliveries (id, installation_id, message_id, audience, recipient_hash, provider, state, next_attempt_at, created_at, updated_at)
+      SELECT ?2, ?3, ?4, ?5, ?6, 'cloudflare_email_service', 'pending', ?7, ?7, ?7 WHERE ${guard}`)
+      .bind(key, id, notice.installationId, notice.messageId, notice.audience, delivery.recipientHash!, timestamp));
+    job = { version: 1, type: "deliver_email", jobId: `email:${id}`, outboxId: id };
+  } else {
+    const id = crypto.randomUUID();
+    statements.push(env.DB.prepare(`INSERT INTO notification_outbox (id, notice_id, idempotency_key, channel, payload_json, status, next_attempt_at, created_at, updated_at)
+      SELECT ?2, ?3, ?4, 'customer_webhook', ?5, 'pending', ?6, ?6, ?6 WHERE ${guard}`)
+      .bind(key, id, noticeId, `notice:${noticeId}`, canonicalJson({version: 1, event: "report.message.available", notification_id: id, report_reference: notice.reference, audience: notice.audience, ...(notice.participantReference ? {recipient_reference: notice.participantReference} : {}), recipient_contact_fingerprint: notice.contactCiphertext ? await sha256(notice.contactCiphertext) : null, message: notice.body}), timestamp));
+    job = { version: 1, type: "deliver_notification", jobId: `notification:${id}`, outboxId: id };
+  }
+  statements.push(env.DB.prepare(`INSERT INTO audit_events (id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at)
+    SELECT ?2, ?3, 'notice.retry_requested', ?4, ?5, 'notice', ?6, ?7, ?8 WHERE ${guard}`)
+    .bind(key, crypto.randomUUID(), `notice-retry:${key}`, session.actor.type, session.actor.id, noticeId, canonicalJson({reportId, audience: notice.audience, messageId: notice.messageId, originalBodyPreserved: true}), timestamp));
+  const written = await env.DB.batch(statements);
+  if (written[0]?.meta.changes !== 1) throw new ApiError(409, "notice_changed", "The notice changed while retrying. Refresh its delivery status.");
+  await env.DELIVERY_JOBS.send(job, {contentType: "json"}).catch(() => {});
+  return response;
+}

package/template/src/operator-scope.ts

@@ -0,0 +1,31 @@
+import { ApiError } from "./report-http";
+import type { OperatorSession } from "./report-types";
+
+export function assertOperatorQueueAccess(session: OperatorSession, queueId: string | null): void {
+  if (session.queueScope === null || session.queueScope === undefined) return;
+  if (!queueId || !session.queueScope.includes(queueId)) throw new ApiError(403, "operator_queue_scope_denied", "Your role is not authorized for this queue.");
+}
+
+export async function assertOperatorReportAccess(
+  db: D1Database,
+  session: OperatorSession,
+  reportId: string,
+): Promise<void> {
+  if (session.queueScope === null || session.queueScope === undefined) return;
+  const report = await db.prepare(`SELECT queue_id AS queueId FROM reports WHERE id = ?1 LIMIT 1`)
+    .bind(reportId).first<{ queueId: string | null }>();
+  if (!report) throw new ApiError(404, "report_not_found", "The report does not exist.");
+  assertOperatorQueueAccess(session, report.queueId);
+}
+
+export async function assertOperatorWorkflowRunAccess(
+  db: D1Database,
+  session: OperatorSession,
+  runId: string,
+): Promise<void> {
+  if (session.queueScope === null || session.queueScope === undefined) return;
+  const run = await db.prepare(`SELECT queue_id AS queueId FROM workflow_runs WHERE id = ?1 LIMIT 1`)
+    .bind(runId).first<{ queueId: string | null }>();
+  if (!run) throw new ApiError(404, "workflow_run_not_found", "The workflow run does not exist.");
+  assertOperatorQueueAccess(session, run.queueId);
+}