create-safest-tools 0.6.0 → 0.7.0

package/template/src/report-workflow.ts

@@ -1,10 +1,13 @@
+import { changeReportOwner } from "./report-ownership";
+export { decideAppeal } from "./appeal-decisions";
 import { AUDIT_GENESIS_HASH, canonicalJson, hashAuditEntry } from "./audit";
 import { decryptReportContact } from "./report-crypto";
 import { selectParticipantDelivery, type ParticipantDelivery } from "./report-email";
 import { ApiError } from "./report-http";
 import { analystAvatarColor } from "./report-presence";
+import { assertOperatorReportAccess } from "./operator-scope";
 import type { DeliveryJob, OperatorSession, ParticipantAudience, ReportState } from "./report-types";
-import type { AppealDecisionInput, DecisionInput, ReviewerMessageInput } from "./report-workflow-validation";
+import type { DecisionInput, ReviewerMessageInput } from "./report-workflow-validation";
 
 interface WorkflowReportRow {
   id: string;
@@ -86,11 +89,33 @@ async function requireActiveClaim(db: D1Database, reportId: string, reviewerId:
     LIMIT 1
   `).bind(reportId).first<ClaimRow>();
   if (!claim || claim.reviewer_id !== reviewerId || claim.expires_at <= at) {
-    throw new ApiError(409, "active_claim_required", "Claim this report before changing it.");
+    throw new ApiError(409, "active_claim_required", "Start or resume review to edit this case. Your private draft is unchanged.");
   }
   return claim;
 }
 
+async function commitReviewerMutation(db: D1Database, report: WorkflowReportRow, claim: ClaimRow, session: OperatorSession, statements: D1PreparedStatement[], decision = false): Promise<void> {
+  const id = crypto.randomUUID();
+  try {
+    await db.batch([
+      db.prepare(`INSERT INTO report_edit_guards (id,authorized)
+        SELECT ?1,EXISTS (SELECT 1 FROM reports r JOIN review_claims c ON c.report_id = r.id
+          WHERE r.id = ?2 AND r.state = ?3 AND r.policy_version_id IS ?4 AND r.queue_version_id IS ?5
+            AND c.reviewer_id = ?6 AND c.version = ?7 AND c.expires_at > strftime('%Y-%m-%dT%H:%M:%fZ','now')
+            AND (?8 = 1 OR r.queue_id IN (SELECT value FROM json_each(?9)))
+            AND (?10 = 0 OR NOT EXISTS (SELECT 1 FROM workflow_runs wr JOIN workflow_versions wv ON wv.id = wr.workflow_version_id
+              WHERE wr.report_id = r.id AND wr.run_kind = 'primary' AND json_type(wv.graph_json,'$.playbook') = 'object'
+                AND wr.state NOT IN ('succeeded','failed','terminated','superseded'))))`)
+        .bind(id,report.id,report.state,report.policy_version_id,report.queue_version_id,session.actor.id,claim.version,session.queueScope == null ? 1 : 0,canonicalJson(session.queueScope ?? []),decision ? 1 : 0),
+      ...statements,
+      db.prepare("DELETE FROM report_edit_guards WHERE id = ?1").bind(id),
+    ]);
+  } catch (error) {
+    if (String(error).includes("active_report_edit_access")) throw new ApiError(409,"active_claim_required","Case ownership, editing access or the review requirements changed before saving. Refresh the case and resume review. Your private draft is unchanged.");
+    throw error;
+  }
+}
+
 export async function claimReport(
   db: D1Database,
   reportId: string,
@@ -104,37 +129,26 @@ export async function claimReport(
   }
   const claimedAt = now();
   const expiresAt = addMinutes(claimedAt, Math.max(1, Math.min(1_440, claimTtlMinutes)));
-  await db.prepare(`
-    INSERT INTO review_claims (report_id, reviewer_id, claimed_at, expires_at, version)
-    VALUES (?1, ?2, ?3, ?4, 1)
-    ON CONFLICT(report_id) DO UPDATE SET
-      reviewer_id = excluded.reviewer_id,
-      claimed_at = excluded.claimed_at,
-      expires_at = excluded.expires_at,
-      version = review_claims.version + 1
-    WHERE review_claims.expires_at <= ?3 OR review_claims.reviewer_id = ?2
-  `).bind(reportId, session.actor.id, claimedAt, expiresAt).run();
-  const claim = await db.prepare(`
-    SELECT report_id, reviewer_id, claimed_at, expires_at, version
-    FROM review_claims WHERE report_id = ?1 LIMIT 1
-  `).bind(reportId).first<ClaimRow>();
-  if (!claim || claim.reviewer_id !== session.actor.id) {
-    throw new ApiError(409, "report_already_claimed", "Another reviewer currently holds this report.", {
-      expires_at: claim?.expires_at,
-    });
-  }
-  await db.batch([
-    auditEvent(db, {
-      idempotencyKey: `claim:${reportId}:${claim.version}`,
-      action: "report.claimed",
-      actorType: session.actor.type,
-      actorId: session.actor.id,
-      targetType: "report",
-      targetId: reportId,
-      details: { expiresAt: claim.expires_at, version: claim.version },
-      createdAt: claimedAt,
-    }),
+  const written = await db.batch([
+    db.prepare(`
+      INSERT INTO review_claims (report_id, reviewer_id, claimed_at, expires_at, version)
+      SELECT r.id, ?2, ?3, ?4, COALESCE((SELECT MAX(CAST(json_extract(details_json, '$.version') AS INTEGER))
+        FROM audit_events WHERE target_type = 'report' AND target_id = ?1), 0) + 1
+      FROM reports r WHERE r.id = ?1 AND r.state IN ('human_review','awaiting_reporter','human_review_requested')
+        AND (?5 = 1 OR r.queue_id IN (SELECT value FROM json_each(?6)))
+      ON CONFLICT(report_id) DO UPDATE SET claimed_at = excluded.claimed_at,
+        expires_at = excluded.expires_at, version = review_claims.version + 1
+      WHERE review_claims.reviewer_id = ?2
+    `).bind(reportId, session.actor.id, claimedAt, expiresAt, session.queueScope == null ? 1 : 0, canonicalJson(session.queueScope ?? [])),
+    db.prepare(`INSERT INTO audit_events (id,idempotency_key,action,actor_type,actor_id,target_type,target_id,details_json,created_at)
+      SELECT ?1,?1,'report.claimed',?2,?3,'report',?4,json_object('expiresAt',expires_at,'version',version),?5
+      FROM review_claims WHERE report_id = ?4 AND changes() = 1`)
+      .bind(crypto.randomUUID(),session.actor.type,session.actor.id,reportId,claimedAt),
   ]);
+  const claim = await db.prepare(`SELECT report_id,reviewer_id,claimed_at,expires_at,version FROM review_claims WHERE report_id = ?1`).bind(reportId).first<ClaimRow>();
+  if (written[0]?.meta.changes !== 1 || !claim || claim.reviewer_id !== session.actor.id) {
+    throw new ApiError(409, "report_already_claimed", "This case is assigned to another reviewer or is no longer ready for review. Refresh to see its current owner.");
+  }
   return { reviewerId: claim.reviewer_id, claimedAt: claim.claimed_at, expiresAt: claim.expires_at, version: claim.version };
 }
 
@@ -143,28 +157,16 @@ export async function releaseReportClaim(db: D1Database, reportId: string, sessi
     .bind(reportId).first<{ reviewer_id: string; version: number }>();
   if (!claim) return;
   if (claim.reviewer_id !== session.actor.id && !session.permissions.manageConfiguration) {
-    throw new ApiError(409, "claim_owned_by_another_reviewer", "Only the current reviewer or an administrator can release this claim.");
+    throw new ApiError(409, "claim_owned_by_another_reviewer", "Only the case owner or an administrator can return this case.");
   }
-  const createdAt = now();
-  await db.batch([
-    db.prepare(`DELETE FROM review_claims WHERE report_id = ?1`).bind(reportId),
-    auditEvent(db, {
-      idempotencyKey: `claim-release:${reportId}:${claim.version}`,
-      action: "report.claim_released",
-      actorType: session.actor.type,
-      actorId: session.actor.id,
-      targetType: "report",
-      targetId: reportId,
-      details: { priorReviewerId: claim.reviewer_id, version: claim.version },
-      createdAt,
-    }),
-  ]);
+  // Keep the legacy endpoint compatible while using the same atomic handoff.
+  await changeReportOwner(db,reportId,session,{ reviewerId:null,version:claim.version,note:"Returned to the queue." });
 }
 
 export async function loadReportDetail(
   db: D1Database,
   reportId: string,
-  options: { contactEncryptionKey?: string; includeReporterEmail?: boolean } = {},
+  options: { contactEncryptionKey?: string; includeReporterEmail?: boolean; includeCustomerContext?: boolean; allowedQueueIds?: string[] | null } = {},
 ): Promise<Record<string, unknown> | null> {
   const report = await db.prepare(`
     SELECT r.id, r.public_reference AS reference, r.source, r.state, r.priority, r.reason_code AS reasonCode,
@@ -176,10 +178,13 @@ export async function loadReportDetail(
            policy.rules_json AS policyRulesJson, r.queue_version_id AS queuePolicyVersionId,
            qv.management_mode AS queueManagementMode, qv.reviewer_instructions AS reviewerInstructions,
            t.target_type AS targetType, t.target_reference AS targetReference,
-           t.owner_reference AS ownerReference, t.customer_url AS customerUrl,
+           t.owner_reference AS ownerReference, t.customer_url AS customerUrl, t.signed_facts_json AS customerFactsJson,
            p.reference AS reporterReference, p.contact_mode AS reporterContactMode,
            p.contact_ciphertext AS reporterContactCiphertext,
-           p.reference_redacted_at AS reporterReferenceRedactedAt
+           p.reference_redacted_at AS reporterReferenceRedactedAt,
+           EXISTS (SELECT 1 FROM workflow_runs wr JOIN workflow_versions wv ON wv.id = wr.workflow_version_id
+             WHERE wr.report_id = r.id AND wr.run_kind = 'primary' AND json_type(wv.graph_json, '$.playbook') = 'object'
+               AND wr.state NOT IN ('succeeded','failed','terminated','superseded')) AS playbookManaged
     FROM reports r
     JOIN report_targets t ON t.report_id = r.id
     JOIN report_participants p ON p.report_id = r.id AND p.audience = 'reporter'
@@ -190,7 +195,7 @@ export async function loadReportDetail(
     LIMIT 1
   `).bind(reportId).first<Record<string, unknown>>();
   if (!report) return null;
-  const [answers, evidence, messages, decisions, actions, notices, aiRuns, history, claim, findings] = await Promise.all([
+  const [answers, evidence, messages, decisions, actions, notices, aiRuns, history, claim, findings, related, appeals, handoffs] = await Promise.all([
     db.prepare(`SELECT field_key AS fieldKey, value_json AS valueJson FROM report_answers WHERE report_id = ?1 ORDER BY field_key`).bind(reportId).all<Record<string, unknown>>(),
     db.prepare(`SELECT id, evidence_kind AS kind, reference, availability, created_at AS createdAt FROM evidence_references WHERE report_id = ?1 ORDER BY created_at, id`).bind(reportId).all<Record<string, unknown>>(),
     db.prepare(`SELECT id, audience, direction, sender_type AS senderType, sender_id AS senderId, body, automated, delivery_state AS deliveryState, created_at AS createdAt FROM case_messages WHERE report_id = ?1 ORDER BY created_at, id LIMIT 500`).bind(reportId).all<Record<string, unknown>>(),
@@ -201,8 +206,15 @@ export async function loadReportDetail(
       FROM decision_action_outbox WHERE report_id = ?1 ORDER BY created_at DESC, id DESC
     `).bind(reportId).all<Record<string, unknown>>(),
     db.prepare(`
-      SELECT id, decision_id AS decisionId, audience, delivery_state AS deliveryState, updated_at AS updatedAt
-      FROM notices WHERE report_id = ?1 ORDER BY created_at DESC, id DESC
+      SELECT n.id, n.message_id AS messageId, n.decision_id AS decisionId, n.audience, n.delivery_state AS deliveryState, n.updated_at AS updatedAt,
+        CASE WHEN n.idempotency_key LIKE 'appeal-decision:%' THEN 'appeal' ELSE 'case' END AS purpose,
+        CASE WHEN EXISTS (SELECT 1 FROM email_deliveries e WHERE e.message_id = n.message_id) THEN 'email'
+          WHEN EXISTS (SELECT 1 FROM notification_outbox o WHERE o.notice_id = n.id) THEN 'customer_webhook' ELSE NULL END AS channel,
+        COALESCE((SELECT SUM(attempt_count) FROM email_deliveries e WHERE e.message_id = n.message_id), 0)
+          + COALESCE((SELECT SUM(attempt_count) FROM notification_outbox o WHERE o.notice_id = n.id), 0) AS attemptCount,
+        COALESCE((SELECT last_error_code FROM email_deliveries e WHERE e.message_id = n.message_id ORDER BY e.updated_at DESC LIMIT 1),
+          (SELECT last_error_code FROM notification_outbox o WHERE o.notice_id = n.id ORDER BY o.updated_at DESC LIMIT 1)) AS errorCode
+      FROM notices n WHERE n.report_id = ?1 ORDER BY n.created_at DESC, n.id DESC
     `).bind(reportId).all<Record<string, unknown>>(),
     db.prepare(`
       SELECT ar.id, ar.status, ar.mode, ar.model, ar.prompt_version AS promptVersion,
@@ -222,9 +234,9 @@ export async function loadReportDetail(
              p.avatar_color AS analystAvatarColor
       FROM review_claims c
       LEFT JOIN analyst_profiles p ON p.actor_id = c.reviewer_id
-      WHERE c.report_id = ?1 AND c.expires_at > ?2
+      WHERE c.report_id = ?1
       LIMIT 1
-    `).bind(reportId, now()).first<Record<string, unknown>>(),
+    `).bind(reportId).first<Record<string, unknown>>(),
     db.prepare(`
       SELECT f.id, f.run_id AS runId, f.step_run_id AS stepRunId,
         f.component_version_id AS componentVersionId, f.ai_run_id AS aiRunId,
@@ -241,6 +253,22 @@ export async function loadReportDetail(
       WHERE f.report_id = ?1 ORDER BY f.created_at DESC, f.id DESC
       LIMIT 500
     `).bind(reportId).all<Record<string, unknown>>(),
+    db.prepare(`SELECT r.id, r.public_reference AS reference, r.state, r.reason_code AS reasonCode, r.submitted_at AS submittedAt, q.name AS queueName
+      FROM duplicate_group_members source JOIN duplicate_group_members member ON member.group_id = source.group_id
+      JOIN reports origin ON origin.id = source.report_id JOIN reports r ON r.id = member.report_id
+      LEFT JOIN queue_definitions q ON q.id = r.queue_id
+      WHERE source.report_id = ?1 AND source.removed_at IS NULL AND member.removed_at IS NULL AND r.id != ?1
+        AND (?2 = 1 OR (r.queue_id IN (SELECT value FROM json_each(?3)) AND origin.queue_id IN (SELECT value FROM json_each(?3))))
+      ORDER BY r.submitted_at, r.id LIMIT 50`)
+      .bind(reportId,options.allowedQueueIds===null?1:0,canonicalJson(options.allowedQueueIds??[])).all<Record<string,unknown>>(),
+    db.prepare(`SELECT a.id, a.appellant_audience AS audience, a.state, a.submitted_at AS submittedAt, ad.completion_state AS completionState,
+      ad.correction_required AS correctionRequired, ad.correction_confirmed_at AS correctionConfirmedAt,
+      n.delivery_state AS noticeState FROM appeals a LEFT JOIN appeal_decisions ad ON ad.appeal_id = a.id
+      LEFT JOIN notices n ON n.idempotency_key = 'appeal-decision:' || ad.id || ':notice' WHERE a.report_id = ?1 ORDER BY a.submitted_at, a.id`)
+      .bind(reportId).all<Record<string,unknown>>(),
+    db.prepare(`SELECT h.id,h.from_reviewer_id AS fromReviewerId,h.to_reviewer_id AS toReviewerId,h.note,h.created_at AS createdAt,
+      COALESCE(p.display_name,h.actor_id) AS authorName FROM report_handoffs h LEFT JOIN analyst_profiles p ON p.actor_id = h.actor_id
+      WHERE h.report_id = ?1 ORDER BY h.created_at DESC,h.id DESC LIMIT 100`).bind(reportId).all<Record<string,unknown>>(),
   ]);
   const formFieldsValue = parsedJson(report.formFieldsJson, []);
   const formFields = Array.isArray(formFieldsValue)
@@ -298,6 +326,11 @@ export async function loadReportDetail(
   }
   return {
     ...report,
+    relatedReports: related.results,
+    appeals: appeals.results,
+    playbookManaged: report.playbookManaged === 1,
+    customerFacts: options.includeCustomerContext ? parsedJson(report.customerFactsJson, {}) : undefined,
+    customerFactsJson: undefined,
     reporterEmail,
     reporterContactStatus,
     reporterContactCiphertext: undefined,
@@ -315,7 +348,7 @@ export async function loadReportDetail(
     messages: messages.results.map((row) => ({ ...row, automated: row.automated === 1 })),
     decisions: decisions.results.map((row) => ({
       ...row,
-      evidenceReferences: JSON.parse(String(row.evidenceReferencesJson)),
+      evidenceReferences: parsedJson(row.evidenceReferencesJson, []),
       evidenceReferencesJson: undefined,
     })),
     actions: actions.results.map((row) => ({ ...row, terminal: row.terminal === 1 })),
@@ -323,7 +356,7 @@ export async function loadReportDetail(
     aiRuns: aiRuns.results.map((row) => ({
       ...row,
       uncertain: row.uncertain === 1,
-      validationErrors: row.validationErrorsJson ? JSON.parse(String(row.validationErrorsJson)) : [],
+      validationErrors: parsedJson(row.validationErrorsJson, []),
       validationErrorsJson: undefined,
     })),
     history: history.results,
@@ -337,7 +370,12 @@ export async function loadReportDetail(
       provenanceJson: undefined,
       uncertaintyJson: undefined,
     })),
-    claim: claim ? {
+    claim: claim && String(claim.expiresAt) > now() ? {
+      reviewerId: claim.reviewerId, claimedAt: claim.claimedAt, expiresAt: claim.expiresAt, version: claim.version,
+      analyst: { displayName: claim.analystDisplayName ?? claim.reviewerId, avatarUrl: claim.analystAvatarUrl ?? null, avatarColor: claim.analystAvatarColor ?? analystAvatarColor(String(claim.reviewerId)) },
+    } : null,
+    handoffs: handoffs.results,
+    assignment: claim ? {
       reviewerId: claim.reviewerId,
       claimedAt: claim.claimedAt,
       expiresAt: claim.expiresAt,
@@ -390,7 +428,7 @@ export async function addReviewerMessage(
   `).bind(reportId, input.idempotencyKey).first<{ id: string; deliveryState: string; deliveryChannel: ParticipantDelivery["channel"] }>();
   if (existing) return { messageId: existing.id, jobs: [], deliveryState: existing.deliveryState, deliveryChannel: existing.deliveryChannel, idempotentReplay: true };
   const createdAt = now();
-  await requireActiveClaim(db, reportId, session.actor.id, createdAt);
+  const claim = await requireActiveClaim(db, reportId, session.actor.id, createdAt);
   const report = await workflowReport(db, reportId);
   if (!report) throw new ApiError(404, "report_not_found", "The report does not exist.");
   if (["closed", "resolved_by_human", "resolved_by_ai", "appealed"].includes(report.state)) {
@@ -461,7 +499,7 @@ export async function addReviewerMessage(
       message: input.body,
     }), createdAt));
   }
-  await db.batch(statements);
+  await commitReviewerMutation(db, report, claim, session, statements);
   return { messageId, jobs, deliveryState: delivery.state, deliveryChannel: delivery.channel, idempotentReplay: false };
 }
 
@@ -482,8 +520,13 @@ export async function recordHumanDecision(
     SELECT id FROM decisions WHERE report_id = ?1 AND idempotency_key = ?2 LIMIT 1
   `).bind(reportId, input.idempotencyKey).first<{ id: string }>();
   if (existing) return { decisionId: existing.id, jobs: [], idempotentReplay: true };
+  if (await db.prepare(`SELECT 1 FROM workflow_runs wr JOIN workflow_versions wv ON wv.id = wr.workflow_version_id
+    WHERE wr.report_id = ?1 AND wr.run_kind = 'primary' AND json_type(wv.graph_json, '$.playbook') = 'object'
+      AND wr.state NOT IN ('succeeded','failed','terminated','superseded') LIMIT 1`).bind(reportId).first()) {
+    throw new ApiError(409, "playbook_review_required", "This case is following a published playbook. Complete its current review task to continue the case.");
+  }
   const createdAt = now();
-  await requireActiveClaim(db, reportId, session.actor.id, createdAt);
+  const claim = await requireActiveClaim(db, reportId, session.actor.id, createdAt);
   const report = await workflowReport(db, reportId);
   if (!report) throw new ApiError(404, "report_not_found", "The report does not exist.");
   if (!["human_review", "awaiting_reporter", "human_review_requested"].includes(report.state)) {
@@ -669,11 +712,57 @@ export async function recordHumanDecision(
     jobs.push({ version: 1, jobId: `action:${actionId}`, type: "deliver_action", outboxId: actionId });
   }
 
-  await db.batch(statements);
+  await commitReviewerMutation(db, report, claim, session, statements, true);
   return { decisionId, jobs, idempotentReplay: false };
 }
 
 
+export async function recordParticipantAppeal(
+  db: D1Database, reportId: string, session: OperatorSession,
+  input: { audience: ParticipantAudience; reason: string; idempotencyKey: string },
+): Promise<{ appealId: string; idempotentReplay: boolean }> {
+  if (!session.permissions.reviewAppeals) throw new ApiError(403,"appeal_record_denied","Your role cannot record appeals.");
+  await assertOperatorReportAccess(db,session,reportId);
+  const existing = await db.prepare(`SELECT a.id, a.reason, a.appellant_audience AS audience, e.actor_id AS actorId FROM appeals a
+    LEFT JOIN audit_events e ON e.idempotency_key = 'appeal-recorded:' || a.id WHERE a.report_id = ?1 AND a.idempotency_key = ?2 LIMIT 1`)
+    .bind(reportId, input.idempotencyKey).first<{ id: string; reason: string; audience: string; actorId: string | null }>();
+  if (existing) {
+    if (existing.reason !== input.reason || existing.audience !== input.audience || existing.actorId !== session.actor.id) throw new ApiError(409,"idempotency_key_reused","This appeal request key belongs to another participant, reason or operator.");
+    return { appealId: existing.id, idempotentReplay: true };
+  }
+  const report = await db.prepare(`SELECT state FROM reports WHERE id = ?1 LIMIT 1`).bind(reportId).first<{ state: string }>();
+  if (!report || !["resolved_by_human", "resolved_by_ai", "appealed", "closed"].includes(report.state)) throw new ApiError(409, "appeal_requires_decision", "Only a resolved report can receive an appeal.");
+  const decision = await db.prepare(`SELECT id FROM decisions WHERE report_id = ?1 ORDER BY created_at DESC, id DESC LIMIT 1`).bind(reportId).first<{ id: string }>();
+  if (!decision) throw new ApiError(409, "appeal_requires_decision", "The report has no decision to appeal.");
+  const participant = await db.prepare(`SELECT id FROM report_participants WHERE report_id = ?1 AND audience = ?2 AND reference_redacted_at IS NULL LIMIT 1`).bind(reportId, input.audience).first();
+  if (!participant) throw new ApiError(400, "appeal_participant_missing", "This report has no participant with the selected audience.");
+  const queue = await db.prepare(`SELECT id FROM queue_definitions WHERE queue_kind = 'appeal' AND enabled = 1 AND status = 'active' ORDER BY position, id LIMIT 1`).first<{ id: string }>();
+  if (!queue) throw new ApiError(409, "appeal_queue_unavailable", "Enable an appeal queue before recording an appeal.");
+  const appealId = crypto.randomUUID();
+  const createdAt = now();
+  await db.batch([
+    db.prepare(`INSERT OR IGNORE INTO appeals (id, report_id, decision_id, appellant_audience, reason, state, queue_id, submitted_at, idempotency_key)
+      SELECT ?1, ?2, ?3, ?4, ?5, 'submitted', ?6, ?7, ?8 FROM reports r WHERE r.id = ?2 AND r.state = ?9
+        AND (?10 = 1 OR r.queue_id IN (SELECT value FROM json_each(?11)))
+        AND EXISTS (SELECT 1 FROM report_participants WHERE report_id = ?2 AND audience = ?4 AND reference_redacted_at IS NULL)
+        AND EXISTS (SELECT 1 FROM decisions WHERE id = ?3 AND sensitive_redacted_at IS NULL)
+        AND ?3 = (SELECT id FROM decisions WHERE report_id = ?2 ORDER BY created_at DESC, id DESC LIMIT 1)
+        AND EXISTS (SELECT 1 FROM queue_definitions WHERE id = ?6 AND queue_kind = 'appeal' AND enabled = 1 AND status = 'active')`)
+      .bind(appealId, reportId, decision.id, input.audience, input.reason, queue.id, createdAt, input.idempotencyKey, report.state,session.queueScope==null?1:0,canonicalJson(session.queueScope??[])),
+    db.prepare(`UPDATE reports SET state = 'appealed', updated_at = ?2 WHERE id = ?1 AND EXISTS (SELECT 1 FROM appeals WHERE id = ?3)`).bind(reportId, createdAt, appealId),
+    db.prepare(`INSERT INTO report_state_history (id, report_id, from_state, to_state, reason_code, actor_type, actor_id, created_at) SELECT ?1, ?2, ?3, 'appealed', 'participant_appeal_recorded', ?4, ?5, ?6 WHERE EXISTS (SELECT 1 FROM appeals WHERE id = ?7)`)
+      .bind(crypto.randomUUID(), reportId, report.state, session.actor.type, session.actor.id, createdAt, appealId),
+    db.prepare(`INSERT INTO audit_events (id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at) SELECT ?1, ?2, 'appeal.recorded', ?3, ?4, 'appeal', ?5, ?6, ?7 WHERE EXISTS (SELECT 1 FROM appeals WHERE id = ?5)`)
+      .bind(crypto.randomUUID(), `appeal-recorded:${appealId}`, session.actor.type, session.actor.id, appealId, canonicalJson({ reportId, decisionId: decision.id, audience: input.audience }), createdAt),
+  ]);
+  const saved = await db.prepare(`SELECT a.id, a.idempotency_key AS idempotencyKey, a.reason, e.actor_id AS actorId FROM appeals a
+    LEFT JOIN audit_events e ON e.idempotency_key = 'appeal-recorded:' || a.id WHERE a.decision_id = ?1 AND a.appellant_audience = ?2 LIMIT 1`)
+    .bind(decision.id, input.audience).first<{ id: string; idempotencyKey: string; reason: string; actorId: string | null }>();
+  if (!saved || saved.idempotencyKey !== input.idempotencyKey) throw new ApiError(409, "appeal_already_recorded", "An appeal for this participant and decision already exists.");
+  if (saved.reason !== input.reason || saved.actorId !== session.actor.id) throw new ApiError(409,"idempotency_key_reused","This appeal request key belongs to another operator or reason.");
+  return { appealId: saved.id, idempotentReplay: saved.id !== appealId };
+}
+
 export async function listAppeals(db: D1Database, limit: number, allowedQueueIds?: string[] | null): Promise<Array<Record<string, unknown>>> {
   const result = await db.prepare(`
     SELECT a.id, a.report_id AS reportId, r.public_reference AS reportReference,
@@ -711,9 +800,14 @@ export async function loadAppealDetail(db: D1Database, appealId: string): Promis
   `).bind(appealId, now()).first<Record<string, unknown>>();
   if (!appeal) return null;
   const decisions = await db.prepare(`
-    SELECT id, outcome, rationale, reviewer_id AS reviewerId,
-      corrective_action_id AS correctiveActionId, created_at AS createdAt
-    FROM appeal_decisions WHERE appeal_id = ?1 ORDER BY created_at, id
+    SELECT ad.id, ad.outcome, ad.rationale, ad.reviewer_id AS reviewerId,
+      ad.corrective_action_id AS correctiveActionId, ad.created_at AS createdAt,
+      ad.completion_state AS completionState, ad.correction_required AS correctionRequired,
+      ad.correction_reference AS correctionReference, ad.correction_note AS correctionNote,
+      ad.correction_confirmed_by AS correctionConfirmedBy, ad.correction_confirmed_at AS correctionConfirmedAt,
+      n.delivery_state AS noticeState
+    FROM appeal_decisions ad LEFT JOIN notices n ON n.idempotency_key = 'appeal-decision:' || ad.id || ':notice'
+    WHERE ad.appeal_id = ?1 ORDER BY ad.created_at, ad.id
   `).bind(appealId).all<Record<string, unknown>>();
   return { ...appeal, decisions: decisions.results };
 }
@@ -723,6 +817,10 @@ export async function releaseAppealClaim(
   appealId: string,
   session: OperatorSession,
 ): Promise<void> {
+  if (!session.permissions.reviewAppeals) throw new ApiError(403,"appeal_claim_denied","Your role cannot review appeals.");
+  const appeal = await db.prepare(`SELECT report_id AS reportId FROM appeals WHERE id = ?1`).bind(appealId).first<{reportId:string}>();
+  if (!appeal) throw new ApiError(404,"appeal_not_found","The appeal does not exist.");
+  await assertOperatorReportAccess(db,session,appeal.reportId);
   const claim = await db.prepare(`SELECT reviewer_id AS reviewerId, version FROM appeal_claims WHERE appeal_id = ?1 LIMIT 1`)
     .bind(appealId).first<{ reviewerId: string; version: number }>();
   if (!claim) return;
@@ -730,20 +828,16 @@ export async function releaseAppealClaim(
     throw new ApiError(409, "appeal_claim_owned_by_another_reviewer", "Only the current reviewer or an assignment manager can release this claim.");
   }
   const createdAt = now();
-  await db.batch([
-    db.prepare(`DELETE FROM appeal_claims WHERE appeal_id = ?1`).bind(appealId),
-    db.prepare(`UPDATE appeals SET state = 'submitted' WHERE id = ?1 AND state = 'human_review'`).bind(appealId),
-    auditEvent(db, {
-      idempotencyKey: `appeal-claim-release:${appealId}:${claim.version}`,
-      action: "appeal.claim_released",
-      actorType: session.actor.type,
-      actorId: session.actor.id,
-      targetType: "appeal",
-      targetId: appealId,
-      details: { priorReviewerId: claim.reviewerId, version: claim.version },
-      createdAt,
-    }),
+  const result = await db.batch([
+    db.prepare(`DELETE FROM appeal_claims WHERE appeal_id = ?1 AND version = ?2 AND reviewer_id = ?3
+      AND EXISTS (SELECT 1 FROM appeals a JOIN reports r ON r.id = a.report_id WHERE a.id = ?1 AND a.state = 'human_review'
+        AND (?4 = 1 OR r.queue_id IN (SELECT value FROM json_each(?5))))`).bind(appealId,claim.version,claim.reviewerId,session.queueScope==null?1:0,canonicalJson(session.queueScope??[])),
+    db.prepare(`UPDATE appeals SET state = 'submitted' WHERE id = ?1 AND state = 'human_review' AND changes() = 1`).bind(appealId),
+    db.prepare(`INSERT INTO audit_events(id,idempotency_key,action,actor_type,actor_id,target_type,target_id,details_json,created_at)
+      SELECT ?1,?2,'appeal.claim_released',?3,?4,'appeal',?5,?6,?7 WHERE changes() = 1`)
+      .bind(crypto.randomUUID(),`appeal-claim-release:${appealId}:${claim.version}`,session.actor.type,session.actor.id,appealId,canonicalJson({priorReviewerId:claim.reviewerId,version:claim.version}),createdAt),
   ]);
+  if (result[0]?.meta.changes !== 1) throw new ApiError(409,"appeal_claim_changed","The appeal claim changed. Refresh before releasing it.");
 }
 
 export async function claimAppeal(
@@ -752,200 +846,40 @@ export async function claimAppeal(
   session: OperatorSession,
   claimTtlMinutes: number,
 ): Promise<{ reviewerId: string; claimedAt: string; expiresAt: string; version: number }> {
+  if (!session.permissions.reviewAppeals) throw new ApiError(403,"appeal_claim_denied","Your role cannot review appeals.");
   const appeal = await db.prepare(`
-    SELECT a.id, a.state, d.maker_type, d.maker_id
+    SELECT a.id, a.report_id, a.state, d.maker_type, d.maker_id
     FROM appeals a JOIN decisions d ON d.id = a.decision_id
     WHERE a.id = ?1 LIMIT 1
-  `).bind(appealId).first<{ id: string; state: string; maker_type: string; maker_id: string }>();
+  `).bind(appealId).first<{ id: string; report_id: string; state: string; maker_type: string; maker_id: string }>();
   if (!appeal) throw new ApiError(404, "appeal_not_found", "The appeal does not exist.");
+  await assertOperatorReportAccess(db,session,appeal.report_id);
   if (!["submitted", "human_review"].includes(appeal.state)) throw new ApiError(409, "appeal_not_claimable", "The appeal is not awaiting human review.");
   if (appeal.maker_type === "human" && appeal.maker_id === session.actor.id) {
     throw new ApiError(409, "independent_appeal_reviewer_required", "The original decision maker cannot claim this appeal.");
   }
   const claimedAt = now();
   const expiresAt = addMinutes(claimedAt, Math.max(1, Math.min(1_440, claimTtlMinutes)));
-  await db.batch([
+  const written = await db.batch([
     db.prepare(`
       INSERT INTO appeal_claims (appeal_id, reviewer_id, claimed_at, expires_at, version)
-      VALUES (?1, ?2, ?3, ?4, 1)
+      SELECT ?1, ?2, ?3, ?4, 1 FROM appeals a JOIN decisions d ON d.id = a.decision_id JOIN reports r ON r.id = a.report_id
+      WHERE a.id = ?1 AND a.state IN ('submitted','human_review') AND a.reason_redacted_at IS NULL AND r.state = 'appealed'
+        AND d.maker_id != ?2 AND (?5 = 1 OR r.queue_id IN (SELECT value FROM json_each(?6)))
       ON CONFLICT(appeal_id) DO UPDATE SET reviewer_id = excluded.reviewer_id,
         claimed_at = excluded.claimed_at, expires_at = excluded.expires_at,
         version = appeal_claims.version + 1
       WHERE appeal_claims.expires_at <= ?3 OR appeal_claims.reviewer_id = ?2
-    `).bind(appealId, session.actor.id, claimedAt, expiresAt),
-    db.prepare(`UPDATE appeals SET state = 'human_review' WHERE id = ?1 AND state = 'submitted'`).bind(appealId),
+    `).bind(appealId, session.actor.id, claimedAt, expiresAt,session.queueScope==null?1:0,canonicalJson(session.queueScope??[])),
+    db.prepare(`UPDATE appeals SET state = 'human_review' WHERE id = ?1 AND state = 'submitted' AND changes() = 1`).bind(appealId),
   ]);
+  if (written[0]?.meta.changes !== 1) throw new ApiError(409,"appeal_claim_changed","The appeal or claim changed. Refresh before claiming it.");
   const claim = await db.prepare(`SELECT reviewer_id, claimed_at, expires_at, version FROM appeal_claims WHERE appeal_id = ?1 LIMIT 1`)
     .bind(appealId).first<{ reviewer_id: string; claimed_at: string; expires_at: string; version: number }>();
   if (!claim || claim.reviewer_id !== session.actor.id) throw new ApiError(409, "appeal_already_claimed", "Another appeal reviewer currently holds this appeal.");
   return { reviewerId: claim.reviewer_id, claimedAt: claim.claimed_at, expiresAt: claim.expires_at, version: claim.version };
 }
 
-export async function decideAppeal(
-  db: D1Database,
-  appealId: string,
-  session: OperatorSession,
-  input: AppealDecisionInput,
-  options: DecisionOptions,
-): Promise<{ appealDecisionId: string; jobs: DeliveryJob[]; idempotentReplay: boolean }> {
-  const existing = await db.prepare(`
-    SELECT id FROM appeal_decisions WHERE appeal_id = ?1 AND idempotency_key = ?2 LIMIT 1
-  `).bind(appealId, input.idempotencyKey).first<{ id: string }>();
-  if (existing) return { appealDecisionId: existing.id, jobs: [], idempotentReplay: true };
-  const createdAt = now();
-  const appeal = await db.prepare(`
-    SELECT a.id, a.report_id, a.decision_id, a.appellant_audience, a.state, a.submitted_at,
-           d.maker_id AS original_maker_id, r.public_reference, r.state AS report_state,
-           r.policy_version_id, t.target_reference,
-           p.reference AS participant_reference
-    FROM appeals a
-    JOIN decisions d ON d.id = a.decision_id
-    JOIN reports r ON r.id = a.report_id
-    JOIN report_targets t ON t.report_id = r.id
-    JOIN report_participants p ON p.report_id = r.id AND p.audience = a.appellant_audience
-    WHERE a.id = ?1
-    LIMIT 1
-  `).bind(appealId).first<{
-    id: string;
-    report_id: string;
-    decision_id: string;
-    appellant_audience: ParticipantAudience;
-    state: string;
-    submitted_at: string;
-    original_maker_id: string;
-    public_reference: string;
-    report_state: ReportState;
-    policy_version_id: string | null;
-    target_reference: string;
-    participant_reference: string | null;
-  }>();
-  if (!appeal) throw new ApiError(404, "appeal_not_found", "The appeal does not exist.");
-  if (appeal.state !== "human_review") throw new ApiError(409, "appeal_not_decidable", "The appeal is not awaiting a human decision.");
-  if (appeal.original_maker_id === session.actor.id) {
-    throw new ApiError(409, "independent_appeal_reviewer_required", "The original decision maker cannot decide this appeal.");
-  }
-  const claim = await db.prepare(`SELECT reviewer_id, expires_at FROM appeal_claims WHERE appeal_id = ?1 LIMIT 1`)
-    .bind(appealId).first<{ reviewer_id: string; expires_at: string }>();
-  if (!claim || claim.reviewer_id !== session.actor.id || claim.expires_at <= createdAt) {
-    throw new ApiError(409, "active_appeal_claim_required", "Claim this appeal before deciding it.");
-  }
-  if (input.correctiveActionCode && (!options.actionEnabled || !options.allowedActionCodes.has(input.correctiveActionCode))) {
-    throw new ApiError(400, "action_not_allowed", "The corrective application action is not allowlisted for this deployment.");
-  }
-  const appealDecisionId = crypto.randomUUID();
-  const messageId = crypto.randomUUID();
-  const noticeId = crypto.randomUUID();
-  const notificationId = crypto.randomUUID();
-  const actionId = input.correctiveActionCode ? crypto.randomUUID() : null;
-  const templateId = appeal.appellant_audience === "affected_user" ? "appeal-outcome-v1" : "reporter-outcome-v1";
-  const jobs: DeliveryJob[] = [];
-  const statements: D1PreparedStatement[] = [
-    db.prepare(`
-      INSERT INTO appeal_decisions (
-        id, appeal_id, outcome, rationale, reviewer_id, corrective_action_id, created_at, idempotency_key
-      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)
-    `).bind(appealDecisionId, appealId, input.outcome, input.rationale, session.actor.id, actionId, createdAt, input.idempotencyKey),
-    db.prepare(`UPDATE appeals SET state = ?2, resolved_at = ?3 WHERE id = ?1`).bind(appealId, input.outcome, createdAt),
-    db.prepare(`UPDATE reports SET state = 'closed', queue_id = NULL, updated_at = ?2 WHERE id = ?1`)
-      .bind(appeal.report_id, createdAt),
-    db.prepare(`
-      INSERT INTO report_state_history (id, report_id, from_state, to_state, reason_code, actor_type, actor_id, created_at)
-      VALUES (?1, ?2, ?3, 'closed', ?4, ?5, ?6, ?7)
-    `).bind(crypto.randomUUID(), appeal.report_id, appeal.report_state, `appeal_${input.outcome}`, session.actor.type, session.actor.id, createdAt),
-    db.prepare(`
-      INSERT INTO case_messages (
-        id, report_id, audience, direction, sender_type, sender_id, body, template_version_id,
-        automated, delivery_state, created_at, idempotency_key
-      ) VALUES (?1, ?2, ?3, 'outbound', 'human', ?4, ?5, ?6, 0, ?7, ?8, ?9)
-    `).bind(
-      messageId, appeal.report_id, appeal.appellant_audience, session.actor.id, input.participantNotice,
-      templateId, options.notificationEnabled ? "queued" : "suppressed", createdAt,
-      `appeal-decision:${appealDecisionId}:message`,
-    ),
-    db.prepare(`
-      INSERT INTO notices (
-        id, report_id, decision_id, audience, template_version_id, rendered_body,
-        delivery_state, created_at, updated_at, idempotency_key, message_id
-      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?8, ?9, ?10)
-    `).bind(
-      noticeId, appeal.report_id, appeal.decision_id, appeal.appellant_audience, templateId,
-      input.participantNotice, options.notificationEnabled ? "queued" : "suppressed", createdAt,
-      `appeal-decision:${appealDecisionId}:notice`, messageId,
-    ),
-    db.prepare(`DELETE FROM appeal_claims WHERE appeal_id = ?1`).bind(appealId),
-    auditEvent(db, {
-      idempotencyKey: `appeal-decision:${appealId}:${input.idempotencyKey}`,
-      action: "appeal.human_decision_recorded",
-      actorType: session.actor.type,
-      actorId: session.actor.id,
-      targetType: "appeal_decision",
-      targetId: appealDecisionId,
-      details: {
-        appealId,
-        reportId: appeal.report_id,
-        outcome: input.outcome,
-        correctiveActionCode: input.correctiveActionCode ?? null,
-      },
-      createdAt,
-    }),
-  ];
-  if (input.outcome === "reversed") {
-    statements.push(db.prepare(`
-      INSERT INTO ai_usage_daily (usage_date, config_version_id, appeal_reversals, updated_at)
-      SELECT substr(?2, 1, 10), ar.config_version_id, 1, ?2
-      FROM decisions d JOIN ai_runs ar ON ar.id = d.ai_run_id
-      WHERE d.id = ?1
-      ON CONFLICT(usage_date, config_version_id) DO UPDATE SET
-        appeal_reversals = appeal_reversals + 1, updated_at = excluded.updated_at
-    `).bind(appeal.decision_id, createdAt));
-  }
-  if (options.notificationEnabled) {
-    statements.push(db.prepare(`
-      INSERT INTO notification_outbox (
-        id, notice_id, idempotency_key, channel, payload_json, status, next_attempt_at, created_at, updated_at
-      ) VALUES (?1, ?2, ?3, 'customer_webhook', ?4, 'pending', ?5, ?5, ?5)
-    `).bind(notificationId, noticeId, `notice:${noticeId}`, canonicalJson({
-      version: 1,
-      event: "appeal.outcome.available",
-      notification_id: notificationId,
-      report_reference: appeal.public_reference,
-      ...(appeal.participant_reference ? { recipient_reference: appeal.participant_reference } : {}),
-      audience: appeal.appellant_audience,
-      message: input.participantNotice,
-    }), createdAt));
-    jobs.push({ version: 1, jobId: `notification:${notificationId}`, type: "deliver_notification", outboxId: notificationId });
-  }
-  if (input.correctiveActionCode && actionId) {
-    statements.push(db.prepare(`
-      INSERT INTO decision_action_outbox (
-        id, report_id, decision_id, idempotency_key, action_code, target_reference,
-        payload_json, status, next_attempt_at, created_at, updated_at
-      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, 'pending', ?8, ?8, ?8)
-    `).bind(
-      actionId, appeal.report_id, appeal.decision_id,
-      `appeal-action:${appealDecisionId}:${input.correctiveActionCode}`,
-      input.correctiveActionCode, appeal.target_reference,
-      canonicalJson({
-        version: 1,
-        action_id: actionId,
-        idempotency_key: `appeal-action:${appealDecisionId}:${input.correctiveActionCode}`,
-        report_id: appeal.report_id,
-        report_reference: appeal.public_reference,
-        original_decision_id: appeal.decision_id,
-        appeal_id: appealId,
-        appeal_decision_id: appealDecisionId,
-        action_code: input.correctiveActionCode,
-        target_reference: appeal.target_reference,
-        policy_version_id: appeal.policy_version_id,
-      }),
-      createdAt,
-    ));
-    jobs.push({ version: 1, jobId: `action:${actionId}`, type: "deliver_action", outboxId: actionId });
-  }
-  await db.batch(statements);
-  return { appealDecisionId, jobs, idempotentReplay: false };
-}
-
 export async function chainPendingAuditEvents(db: D1Database, limit = 50): Promise<void> {
   const pending = await db.prepare(`
     SELECT id, action, actor_type, actor_id, target_type, target_id, details_json, created_at