create-safest-tools 0.6.1 → 0.7.0

package/template/src/report-delivery.ts

@@ -1,11 +1,13 @@
 import { canonicalJson } from "./audit";
 import type { DeliveryJob } from "./report-types";
-import { decryptReportContact } from "./report-crypto";
+import { decryptReportContact, sha256 } from "./report-crypto";
 import { BudgetControlError, reserveBudgets, settleBudgets } from "./budget-control";
 import { reporterEmailBinding, reporterEmailFrom, reporterEmailSubjectPrefix, reporterReplyAddress } from "./report-email";
 import { renderReporterEmail } from "./report-email-template";
-import { readBoundedBytes } from "./report-http";
+import { ApiError, readBoundedBytes } from "./report-http";
 import { loadWorkspaceBrand } from "./workspace-branding";
+import { signalNoticeDelivery } from "./notice-delivery";
+import { issueParticipantAccessLink, lookupParticipantAccessLink } from "./participant-access";
 
 const MAX_ATTEMPTS = 8;
 const RESPONSE_LIMIT = 16 * 1024;
@@ -29,6 +31,8 @@ interface NotificationOutboxRow {
   payload_json: string;
   status: string;
   attempt_count: number;
+  attempt_limit: number;
+  message_id: string | null;
   audience: "reporter" | "affected_user";
   recipient_reference: string | null;
   contact_ciphertext: string | null;
@@ -41,6 +45,9 @@ interface EmailDeliveryRow {
   audience: "reporter" | "affected_user";
   state: string;
   attemptCount: number;
+  attemptLimit: number;
+  claimedAt: string;
+  recipientHash: string;
   recipientReference: string | null;
   contactCiphertext: string | null;
   body: string;
@@ -58,7 +65,7 @@ export class RetryableDeliveryError extends Error {
 }
 
 export class DeliveryConfigurationError extends Error {
-  constructor(message: string) {
+  constructor(message: string, readonly code?: string) {
     super(message);
     this.name = "DeliveryConfigurationError";
   }
@@ -186,16 +193,16 @@ async function claimNotification(db: D1Database, id: string): Promise<Notificati
     UPDATE notification_outbox
     SET status = 'delivering', attempt_count = attempt_count + 1,
         lease_expires_at = ?2, updated_at = ?1
-    WHERE id = ?3 AND terminal = 0 AND attempt_count < ?4
+    WHERE id = ?3 AND terminal = 0 AND attempt_count < attempt_limit
       AND (
         status = 'pending'
         OR (status = 'failed' AND next_attempt_at <= ?1)
         OR (status = 'delivering' AND lease_expires_at <= ?1)
       )
-  `).bind(claimedAt, plusSeconds(claimedAt, 60), id, MAX_ATTEMPTS).run();
+  `).bind(claimedAt, plusSeconds(claimedAt, 60), id).run();
   if ((result.meta.changes ?? 0) < 1) return null;
   return db.prepare(`
-    SELECT o.id, n.report_id, o.notice_id, o.idempotency_key, o.payload_json, o.status, o.attempt_count,
+    SELECT o.id, n.report_id, o.notice_id, o.idempotency_key, o.payload_json, o.status, o.attempt_count, o.attempt_limit, n.message_id,
       n.audience, p.reference AS recipient_reference, p.contact_ciphertext
     FROM notification_outbox o JOIN notices n ON n.id = o.notice_id
     LEFT JOIN report_participants p ON p.report_id = n.report_id AND p.audience = n.audience
@@ -208,14 +215,14 @@ async function claimEmail(db: D1Database, id: string): Promise<EmailDeliveryRow
   const staleAt = plusSeconds(claimedAt, -60);
   const result = await db.prepare(`
     UPDATE email_deliveries SET state = 'sending', attempt_count = attempt_count + 1,
-      updated_at = ?2 WHERE id = ?1 AND attempt_count < ?3
+      updated_at = ?2 WHERE id = ?1 AND attempt_count < attempt_limit
       AND (state = 'pending' OR (state = 'failed' AND next_attempt_at <= ?2)
-        OR (state = 'sending' AND updated_at <= ?4))
-  `).bind(id, claimedAt, MAX_ATTEMPTS, staleAt).run();
+        OR (state = 'sending' AND updated_at <= ?3))
+  `).bind(id, claimedAt, staleAt).run();
   if ((result.meta.changes ?? 0) < 1) return null;
   return db.prepare(`
     SELECT e.id, m.report_id AS reportId, e.message_id AS messageId,
-      e.audience, e.state, e.attempt_count AS attemptCount,
+      e.audience, e.state, e.attempt_count AS attemptCount, e.attempt_limit AS attemptLimit, e.updated_at AS claimedAt, e.recipient_hash AS recipientHash,
       p.reference AS recipientReference, p.contact_ciphertext AS contactCiphertext,
       m.body, m.template_version_id AS templateVersionId, r.public_reference AS reportReference,
       r.installation_id AS installationId, r.queue_id AS queueId
@@ -230,14 +237,17 @@ async function claimEmail(db: D1Database, id: string): Promise<EmailDeliveryRow
 function deliveryAudit(
   db: D1Database,
   input: { key: string; action: string; targetType: string; targetId: string; reportId: string; details: unknown; createdAt: string },
+  receipt?: { table: "notification_attempts" | "email_delivery_attempts"; id: string },
 ): D1PreparedStatement {
   return db.prepare(`
     INSERT OR IGNORE INTO audit_events (
       id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at
-    ) VALUES (?1, ?2, ?3, 'system', 'delivery-worker', ?4, ?5, ?6, ?7)
+    ) SELECT ?1, ?2, ?3, 'system', 'delivery-worker', ?4, ?5, ?6, ?7
+      ${receipt ? `WHERE EXISTS (SELECT 1 FROM ${receipt.table} WHERE id = ?8)` : ""}
   `).bind(
     crypto.randomUUID(), input.key, input.action, input.targetType, input.targetId,
     canonicalJson({ reportId: input.reportId, ...input.details as Record<string, unknown> }), input.createdAt,
+    ...(receipt ? [receipt.id] : []),
   );
 }
 
@@ -331,14 +341,14 @@ async function processAction(db: D1Database, outboxId: string, env: Env): Promis
   if (!terminal) throw new RetryableDeliveryError(retryDelay);
 }
 
-async function updateNoticeDelivery(db: D1Database, noticeId: string, state: "delivered" | "failed", timestamp: string): Promise<void> {
-  await db.batch([
-    db.prepare(`UPDATE notices SET delivery_state = ?2, updated_at = ?3 WHERE id = ?1`).bind(noticeId, state, timestamp),
-    db.prepare(`
-      UPDATE case_messages SET delivery_state = ?2
-      WHERE id = (SELECT message_id FROM notices WHERE id = ?1)
-    `).bind(noticeId, state),
-  ]);
+function localNotificationTransport(env: Env): typeof fetch | undefined {
+  // Only the disposable loopback demo can use its local customer service binding.
+  if (env.AI_LOCAL_FIXTURE_ENABLED !== "true" || env.NOTIFICATION_WEBHOOK_URL !== "https://safest-notice-harness.invalid/api/safest/notices") return;
+  try {if (!["localhost", "127.0.0.1"].includes(new URL(env.PUBLIC_BASE_URL).hostname)) return;} catch {return;}
+  const candidate: unknown = Reflect.get(env, "NOTICE_CUSTOMER");
+  if (!candidate || typeof candidate !== "object" || !("fetch" in candidate) || typeof candidate.fetch !== "function") return;
+  const binding = candidate as Fetcher;
+  return (input, init) => binding.fetch(input, init);
 }
 
 async function processNotification(db: D1Database, outboxId: string, env: Env): Promise<void> {
@@ -355,13 +365,29 @@ async function processNotification(db: D1Database, outboxId: string, env: Env):
     } catch {
       payload = {};
     }
+    if ("recipient_contact_fingerprint" in payload) {
+      const fingerprint = row.contact_ciphertext ? await sha256(row.contact_ciphertext) : null;
+      if (payload.recipient_contact_fingerprint !== fingerprint || (payload.recipient_reference ?? null) !== row.recipient_reference) throw new DeliveryConfigurationError("The participant identity changed after this notice was prepared.", "notice_recipient_changed");
+      delete payload.recipient_contact_fingerprint;
+    }
     const recipientEmail = row.contact_ciphertext
       ? (await decryptReportContact(env.CREDENTIAL_ENCRYPTION_KEY, row.contact_ciphertext, row.report_id, row.audience)).trim().toLowerCase()
       : null;
+    const accessInput = {
+      reportId: row.report_id, audience: row.audience, deliveryKey: `notice:${row.id}`,
+      expectedIdentity: { reference: row.recipient_reference, contactCiphertext: row.contact_ciphertext },
+    };
+    // Keep webhook retries byte-equivalent even for a notice first sent by an
+    // older build without a participant link. Existing grants reproduce the
+    // original link; an upgrade must never add a new credential to an old retry.
+    const participantUrl = row.attempt_count === 1
+      ? await issueParticipantAccessLink(env, accessInput)
+      : await lookupParticipantAccessLink(env, accessInput);
     const deliveryPayload = canonicalJson({
       ...payload,
       ...(row.recipient_reference ? { recipient_reference: row.recipient_reference } : {}),
       ...(recipientEmail ? { recipient_email: recipientEmail } : {}),
+      ...(participantUrl ? { participant_url: participantUrl } : {}),
     });
     const response = await sendWebhook({
       url: env.NOTIFICATION_WEBHOOK_URL,
@@ -370,70 +396,81 @@ async function processNotification(db: D1Database, outboxId: string, env: Env):
       event: "participant.notification.requested",
       idempotencyKey: row.idempotency_key,
       payload: deliveryPayload,
-    });
+    }, localNotificationTransport(env));
     status = response.status;
   } catch (error) {
     errorCode = error instanceof DeliveryConfigurationError
-      ? "webhook_configuration_error"
+      ? error.code ?? "webhook_configuration_error"
+      : error instanceof ApiError && error.code === "participant_access_unavailable" ? "notice_recipient_changed"
       : error instanceof DOMException && error.name === "AbortError" ? "webhook_timeout" : "webhook_network_error";
   }
   const finishedAt = now();
   const attemptId = crypto.randomUUID();
-  if (status !== null && responseClass(status) === "success") {
-    await db.batch([
-      db.prepare(`
-        UPDATE notification_outbox SET status = 'delivered', terminal = 1,
-          lease_expires_at = NULL, last_error_code = NULL, updated_at = ?2 WHERE id = ?1
-      `).bind(row.id, finishedAt),
-      db.prepare(`
-        INSERT INTO notification_attempts (
-          id, notification_id, attempt_number, response_class, response_status, started_at, finished_at
-        ) VALUES (?1, ?2, ?3, 'delivered', ?4, ?5, ?6)
-      `).bind(attemptId, row.id, row.attempt_count, status, startedAt, finishedAt),
-      deliveryAudit(db, {
-        key: `notification-delivery:${row.id}:delivered`,
-        action: "notification.delivered",
-        targetType: "notification",
-        targetId: row.id,
-        reportId: row.report_id,
-        details: { responseStatus: status, attemptCount: row.attempt_count },
-        createdAt: finishedAt,
-      }),
-    ]);
-    await updateNoticeDelivery(db, row.notice_id, "delivered", finishedAt);
-    return;
-  }
-  if (status !== null) errorCode = `webhook_http_${status}`;
-  const temporary = errorCode !== "webhook_configuration_error"
+  const delivered = status !== null && responseClass(status) === "success";
+  if (status !== null && !delivered) errorCode = `webhook_http_${status}`;
+  const temporary = errorCode !== "webhook_configuration_error" && errorCode !== "notice_recipient_changed"
     && (status === null || responseClass(status) === "temporary_failure");
-  const terminal = !temporary || row.attempt_count >= MAX_ATTEMPTS;
+  const terminal = delivered || !temporary || row.attempt_count >= row.attempt_limit;
   const retryDelay = delay(row.attempt_count);
   const statements = [
-    db.prepare(`
-      UPDATE notification_outbox SET status = 'failed', terminal = ?2,
-        next_attempt_at = ?3, lease_expires_at = NULL, last_error_code = ?4, updated_at = ?5
-      WHERE id = ?1
-    `).bind(row.id, terminal ? 1 : 0, plusSeconds(finishedAt, retryDelay), errorCode, finishedAt),
-    db.prepare(`
-      INSERT INTO notification_attempts (
-        id, notification_id, attempt_number, response_class, response_status, error_code, started_at, finished_at
-      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)
-    `).bind(attemptId, row.id, row.attempt_count, terminal ? "permanent_failure" : "temporary_failure", status, errorCode, startedAt, finishedAt),
+    db.prepare(`UPDATE notification_outbox SET status = ?2, terminal = ?3,
+      next_attempt_at = ?4, lease_expires_at = NULL, last_error_code = ?5, updated_at = ?6
+      WHERE id = ?1 AND status = 'delivering' AND attempt_count = ?7 AND terminal = 0`)
+      .bind(row.id, delivered ? "delivered" : "failed", terminal ? 1 : 0, plusSeconds(finishedAt, retryDelay), delivered ? null : errorCode, finishedAt, row.attempt_count),
+    db.prepare(`INSERT INTO notification_attempts (id, notification_id, attempt_number, response_class, response_status, error_code, started_at, finished_at)
+      SELECT ?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8 WHERE changes() = 1`)
+      .bind(attemptId, row.id, row.attempt_count, delivered ? "delivered" : terminal ? "permanent_failure" : "temporary_failure", status, delivered ? null : errorCode, startedAt, finishedAt),
   ];
-  if (terminal) statements.push(deliveryAudit(db, {
-    key: `notification-delivery:${row.id}:failed`,
-    action: "notification.delivery_failed",
-    targetType: "notification",
-    targetId: row.id,
-    reportId: row.report_id,
-    details: { errorCode, responseStatus: status, attemptCount: row.attempt_count },
-    createdAt: finishedAt,
-  }));
-  await db.batch(statements);
-  if (terminal) await updateNoticeDelivery(db, row.notice_id, "failed", finishedAt);
+  if (terminal) statements.push(
+    db.prepare(`UPDATE notices SET delivery_state = ?2, updated_at = ?3 WHERE id = ?1
+      AND EXISTS (SELECT 1 FROM notification_attempts WHERE id = ?4)`)
+      .bind(row.notice_id, delivered ? "delivered" : "failed", finishedAt, attemptId),
+    db.prepare(`UPDATE case_messages SET delivery_state = ?2 WHERE id = (SELECT message_id FROM notices WHERE id = ?1)
+      AND EXISTS (SELECT 1 FROM notification_attempts WHERE id = ?3)`)
+      .bind(row.notice_id, delivered ? "delivered" : "failed", attemptId),
+    deliveryAudit(db, {
+      key: `notification-delivery:${row.id}:${row.attempt_count}:${delivered ? "delivered" : "failed"}`,
+      action: delivered ? "notification.delivered" : "notification.delivery_failed", targetType: "notification", targetId: row.id,
+      reportId: row.report_id, details: { responseStatus: status, attemptCount: row.attempt_count, errorCode: delivered ? null : errorCode }, createdAt: finishedAt,
+    }, {table: "notification_attempts", id: attemptId}),
+  );
+  const written = await db.batch(statements);
+  if (written[0]?.meta.changes !== 1) return;
+  if (terminal && row.message_id) await signalNoticeDelivery(env, row.message_id, `notification-${row.attempt_count}`);
   if (!terminal) throw new RetryableDeliveryError(retryDelay);
 }
 
+async function commitEmailResult(db: D1Database, env: Env, row: EmailDeliveryRow, input: {
+  state: "delivered" | "failed" | "suppressed"; terminal: boolean; nextAttemptAt: string | null;
+  errorCode: string | null; providerMessageId?: string | null;
+}): Promise<boolean> {
+  const timestamp = now(), attemptId = crypto.randomUUID();
+  const statements = [
+    db.prepare(`UPDATE email_deliveries SET state = ?2, provider_message_id = COALESCE(?3, provider_message_id),
+      last_error_code = ?4, next_attempt_at = ?5, delivered_at = CASE WHEN ?2 = 'delivered' THEN ?6 ELSE delivered_at END, updated_at = ?6
+      WHERE id = ?1 AND state = 'sending' AND attempt_count = ?7 AND updated_at = ?8`)
+      .bind(row.id, input.state, input.providerMessageId ?? null, input.errorCode, input.nextAttemptAt, timestamp, row.attemptCount, row.claimedAt),
+    db.prepare(`INSERT INTO email_delivery_attempts (id, delivery_id, attempt_number, result, provider_message_id, error_code, started_at, finished_at)
+      SELECT ?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8 WHERE changes() = 1`)
+      .bind(attemptId, row.id, row.attemptCount, input.state, input.providerMessageId ?? null, input.errorCode, row.claimedAt, timestamp),
+  ];
+  if (input.terminal) statements.push(
+    db.prepare(`UPDATE case_messages SET delivery_state = ?2 WHERE id = ?1 AND EXISTS (SELECT 1 FROM email_delivery_attempts WHERE id = ?3)`)
+      .bind(row.messageId, input.state, attemptId),
+    db.prepare(`UPDATE notices SET delivery_state = ?2, updated_at = ?3 WHERE message_id = ?1 AND EXISTS (SELECT 1 FROM email_delivery_attempts WHERE id = ?4)`)
+      .bind(row.messageId, input.state, timestamp, attemptId),
+    deliveryAudit(db, {
+      key: `email-delivery:${row.id}:${row.attemptCount}:${input.state}`, action: input.state === "delivered" ? "email.delivered" : "email.delivery_failed",
+      targetType: "email_delivery", targetId: row.id, reportId: row.reportId,
+      details: {provider: "cloudflare_email_service", attemptCount: row.attemptCount, errorCode: input.errorCode}, createdAt: timestamp,
+    }, {table: "email_delivery_attempts", id: attemptId}),
+  );
+  const written = await db.batch(statements);
+  if (written[0]?.meta.changes !== 1) return false;
+  if (input.terminal) await signalNoticeDelivery(env, row.messageId, `email-${row.attemptCount}`);
+  return true;
+}
+
 async function processEmail(db: D1Database, deliveryId: string, env: Env): Promise<void> {
   const row = await claimEmail(db, deliveryId);
   if (!row) return;
@@ -449,22 +486,16 @@ async function processEmail(db: D1Database, deliveryId: string, env: Env): Promi
     });
   } catch (error) {
     if (!(error instanceof BudgetControlError)) throw error;
-    const timestamp = now();
-    if (error.retryable) {
-      await db.prepare(`UPDATE email_deliveries SET state = 'failed', last_error_code = 'email_budget_deferred', next_attempt_at = ?2, updated_at = ?3 WHERE id = ?1`)
-        .bind(row.id, plusSeconds(timestamp, error.delaySeconds), timestamp).run();
-      throw new RetryableDeliveryError(error.delaySeconds);
-    }
-    await db.batch([
-      db.prepare(`UPDATE email_deliveries SET state = 'suppressed', last_error_code = 'email_budget_exhausted', next_attempt_at = NULL, updated_at = ?2 WHERE id = ?1`).bind(row.id, timestamp),
-      deliveryAudit(db, {
-        key: `email-delivery:${row.id}:budget-suppressed`, action: "email.budget_exhausted",
-        targetType: "email_delivery", targetId: row.id, reportId: row.reportId,
-        details: { fallback: "customer_webhook", fallbackReference: error.fallbackReference }, createdAt: timestamp,
-      }),
-    ]);
+    const terminal = !error.retryable || row.attemptCount >= row.attemptLimit;
+    const committed = await commitEmailResult(db, env, row, {
+      state: terminal ? "suppressed" : "failed", terminal,
+      errorCode: terminal ? "email_budget_exhausted" : "email_budget_deferred",
+      nextAttemptAt: terminal ? null : plusSeconds(now(), error.delaySeconds),
+    });
+    if (committed && !terminal) throw new RetryableDeliveryError(error.delaySeconds);
     return;
   }
+
   let providerMessageId: string | null = null;
   let providerAttempted = false;
   let errorCode: string | null = null;
@@ -476,6 +507,7 @@ async function processEmail(db: D1Database, deliveryId: string, env: Env): Promi
     if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/u.test(email) || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/u.test(from)) {
       throw new DeliveryConfigurationError("Email sender or recipient configuration is invalid.");
     }
+    if (row.recipientHash && row.recipientHash !== `sha256:${await sha256(`email-recipient-v1:${env.RATE_LIMIT_PEPPER}:${email}`)}`) throw new DeliveryConfigurationError("The participant address changed after this notice was prepared.", "notice_recipient_changed");
     const prefix = reporterEmailSubjectPrefix(env);
     const [brand, replyTo] = await Promise.all([
       loadWorkspaceBrand(db),
@@ -493,6 +525,10 @@ async function processEmail(db: D1Database, deliveryId: string, env: Env): Promi
     const rendered = renderReporterEmail({
       brand, body: row.body, reportReference: row.reportReference,
       templateVersionId: row.templateVersionId, subjectPrefix: prefix, audience: row.audience,
+      participantUrl: await issueParticipantAccessLink(env, {
+        reportId: row.reportId, audience: row.audience, deliveryKey: `email:${row.id}`,
+        expectedIdentity: { reference: row.recipientReference, contactCiphertext: row.contactCiphertext },
+      }),
     });
     providerAttempted = true;
     const result = await binding.send({
@@ -507,50 +543,21 @@ async function processEmail(db: D1Database, deliveryId: string, env: Env): Promi
     providerMessageId = typeof result.messageId === "string" ? result.messageId.slice(0, 300) : null;
   } catch (error) {
     errorCode = error instanceof DeliveryConfigurationError
-      ? "email_configuration_error"
+      ? error.code ?? "email_configuration_error"
+      : error instanceof ApiError && error.code === "participant_access_unavailable" ? "notice_recipient_changed"
       : typeof error === "object" && error !== null && "code" in error && typeof error.code === "string"
         ? `email_${error.code}`.slice(0, 100) : "email_provider_error";
   }
-  const finishedAt = now();
-  if (!errorCode) {
-    await settleBudgets(db, reservations, true);
-    await db.batch([
-      db.prepare(`UPDATE email_deliveries SET state = 'delivered', provider_message_id = ?2, last_error_code = NULL, next_attempt_at = NULL, delivered_at = ?3, updated_at = ?3 WHERE id = ?1`)
-        .bind(row.id, providerMessageId, finishedAt),
-      db.prepare(`UPDATE case_messages SET delivery_state = 'delivered' WHERE id = ?1`).bind(row.messageId),
-      db.prepare(`UPDATE notices SET delivery_state = 'delivered', updated_at = ?2 WHERE message_id = ?1`).bind(row.messageId, finishedAt),
-      deliveryAudit(db, {
-        key: `email-delivery:${row.id}:delivered`, action: "email.delivered",
-        targetType: "email_delivery", targetId: row.id, reportId: row.reportId,
-        details: { provider: "cloudflare_email_service", attemptCount: row.attemptCount }, createdAt: finishedAt,
-      }),
-    ]);
-    return;
-  }
-  const permanentConfigurationFailure = errorCode === "email_configuration_error"
-    || errorCode === "email_contact_decryption_failed"
-    || errorCode === "email_contact_encryption_unavailable";
-  const terminal = permanentConfigurationFailure || row.attemptCount >= MAX_ATTEMPTS;
   await settleBudgets(db, reservations, providerAttempted);
+  const configurationFailure = errorCode === "email_configuration_error" || errorCode === "notice_recipient_changed"
+    || errorCode === "email_contact_decryption_failed" || errorCode === "email_contact_encryption_unavailable";
+  const terminal = !errorCode || configurationFailure || row.attemptCount >= row.attemptLimit;
   const retryDelay = delay(row.attemptCount);
-  const nextAttemptAt = terminal ? null : plusSeconds(finishedAt, retryDelay);
-  const statements: D1PreparedStatement[] = [
-    db.prepare(`UPDATE email_deliveries SET state = 'failed', last_error_code = ?2, next_attempt_at = ?3, updated_at = ?4 WHERE id = ?1`)
-      .bind(row.id, errorCode, nextAttemptAt, finishedAt),
-  ];
-  if (terminal) {
-    statements.push(
-      db.prepare(`UPDATE case_messages SET delivery_state = 'failed' WHERE id = ?1 AND delivery_state != 'delivered'`).bind(row.messageId),
-      db.prepare(`UPDATE notices SET delivery_state = 'failed', updated_at = ?2 WHERE message_id = ?1 AND delivery_state != 'delivered'`).bind(row.messageId, finishedAt),
-      deliveryAudit(db, {
-        key: `email-delivery:${row.id}:failed`, action: "email.delivery_failed",
-        targetType: "email_delivery", targetId: row.id, reportId: row.reportId,
-        details: { errorCode, attemptCount: row.attemptCount }, createdAt: finishedAt,
-      }),
-    );
-  }
-  await db.batch(statements);
-  if (!terminal) throw new RetryableDeliveryError(retryDelay);
+  const committed = await commitEmailResult(db, env, row, {
+    state: errorCode ? "failed" : "delivered", terminal,
+    errorCode, providerMessageId, nextAttemptAt: terminal ? null : plusSeconds(now(), retryDelay),
+  });
+  if (committed && !terminal) throw new RetryableDeliveryError(retryDelay);
 }
 
 export async function processDeliveryJob(db: D1Database, job: DeliveryJob, env: Env): Promise<void> {
@@ -573,21 +580,21 @@ export async function pendingDeliveryJobs(db: D1Database, limit = 50): Promise<D
     `).bind(at, MAX_ATTEMPTS, boundedLimit).all<{ id: string }>(),
     db.prepare(`
       SELECT id FROM notification_outbox
-      WHERE terminal = 0 AND attempt_count < ?2 AND (
+      WHERE terminal = 0 AND attempt_count < attempt_limit AND (
         (status IN ('pending', 'failed') AND next_attempt_at <= ?1)
         OR (status = 'delivering' AND lease_expires_at <= ?1)
       )
-      ORDER BY next_attempt_at, id LIMIT ?3
-    `).bind(at, MAX_ATTEMPTS, boundedLimit).all<{ id: string }>(),
+      ORDER BY next_attempt_at, id LIMIT ?2
+    `).bind(at, boundedLimit).all<{ id: string }>(),
     db.prepare(`
       SELECT id FROM email_deliveries
-      WHERE attempt_count < ?2 AND (
+      WHERE attempt_count < attempt_limit AND (
         (state = 'pending' AND COALESCE(next_attempt_at, created_at) <= ?1)
         OR (state = 'failed' AND next_attempt_at IS NOT NULL AND next_attempt_at <= ?1)
-        OR (state = 'sending' AND updated_at <= ?3)
+        OR (state = 'sending' AND updated_at <= ?2)
       )
-      ORDER BY COALESCE(next_attempt_at, created_at), id LIMIT ?4
-    `).bind(at, MAX_ATTEMPTS, plusSeconds(at, -60), boundedLimit).all<{ id: string }>(),
+      ORDER BY COALESCE(next_attempt_at, created_at), id LIMIT ?3
+    `).bind(at, plusSeconds(at, -60), boundedLimit).all<{ id: string }>(),
   ]);
   return [
     ...actions.results.map((row): DeliveryJob => ({ version: 1, jobId: `action:${row.id}`, type: "deliver_action", outboxId: row.id })),

package/template/src/report-email-template.ts

@@ -153,6 +153,7 @@ export function renderReporterEmail(input: {
   templateVersionId: string | null;
   subjectPrefix: string;
   audience?: CaseEmailAudience;
+  participantUrl?: string;
 }): RenderedEmail {
   const emailKind = caseKind(input.templateVersionId);
   const audience = input.audience ?? "reporter";
@@ -196,7 +197,8 @@ export function renderReporterEmail(input: {
     category: copy.category,
     heading: copy.heading,
     intro: copy.intro,
-    contentHtml: `<div style="margin:24px 0 0;padding:20px;border-left:4px solid ${input.brand.accent_color};border-radius:${Math.min(input.brand.border_radius, 12)}px;background-color:${input.brand.background_color};color:${input.brand.text_color};font-size:16px;line-height:1.65">${messageHtml(input.body)}</div>`,
+    contentHtml: `<div style="margin:24px 0 0;padding:20px;border-left:4px solid ${input.brand.accent_color};border-radius:${Math.min(input.brand.border_radius, 12)}px;background-color:${input.brand.background_color};color:${input.brand.text_color};font-size:16px;line-height:1.65">${messageHtml(input.body)}</div>`
+      + (input.participantUrl ? `<p style="margin:24px 0"><a href="${escapeHtml(input.participantUrl)}" style="display:inline-block;padding:14px 20px;border-radius:8px;background:${actionColors(input.brand).background};color:${actionColors(input.brand).foreground};text-decoration:none;font-weight:700">Open your case</a></p><p style="font-size:14px;line-height:1.6">Read your conversation, add information or request an independent appeal. This private link is for you only; do not forward it. It opens once within 30 days. Request a fresh link from the case page if needed.</p>` : ""),
     details: [
       { label: "Report reference", value: input.reportReference },
       { label: "Status", value: copy.status },
@@ -206,7 +208,8 @@ export function renderReporterEmail(input: {
   return {
     subject: copy.subject,
     html,
-    text: `${copy.heading}\n\n${copy.intro}\n\n${input.body}\n\nReport reference: ${input.reportReference}\nStatus: ${copy.status}\n\n${replyCopy}\n\nFor privacy, this email includes only the information needed for this update.`,
+    text: `${copy.heading}\n\n${copy.intro}\n\n${input.body}\n\nReport reference: ${input.reportReference}\nStatus: ${copy.status}\n\n${replyCopy}\n\nFor privacy, this email includes only the information needed for this update.`
+      + (input.participantUrl ? `\n\nOpen your case: ${input.participantUrl}\nRead your conversation, add information or request an independent appeal. This private link is for you only; do not forward it. It opens once within 30 days. Request a fresh link from the case page if needed.` : ""),
   };
 }
 

package/template/src/report-governance.ts

@@ -100,57 +100,49 @@ function percentile(values: number[], ratio: number): number | null {
   return Math.round(values[index] ?? 0);
 }
 
-export async function loadAnalytics(db: D1Database, days = 30): Promise<Record<string, unknown>> {
+export async function loadAnalytics(db: D1Database, days = 30, queueScope: string[] | null = null): Promise<Record<string, unknown>> {
   const generatedAt = now();
   const boundedDays = Math.max(1, Math.min(366, days));
   const fromDate = subtractDays(generatedAt, boundedDays).slice(0, 10);
-  const [series, durations, backlog, aiUsage] = await Promise.all([
-    db.prepare(`
-      SELECT aggregate_date AS aggregateDate, metric_key AS metricKey, dimension_key AS dimensionKey,
-        dimension_value AS dimensionValue, value
-      FROM daily_aggregates WHERE aggregate_date >= ?1
-      ORDER BY aggregate_date, metric_key, dimension_key, dimension_value LIMIT 10000
-    `).bind(fromDate).all<Record<string, unknown>>(),
-    db.prepare(`
-      SELECT CAST((julianday(resolved_at) - julianday(received_at)) * 86400 AS INTEGER) AS seconds
-      FROM reports WHERE resolved_at IS NOT NULL AND received_at >= ?1
-      ORDER BY seconds LIMIT 10000
-    `).bind(`${fromDate}T00:00:00.000Z`).all<{ seconds: number }>(),
-    db.prepare(`
-      SELECT queue_id AS queueId, state, COUNT(*) AS count,
-        CAST(MAX((julianday(?1) - julianday(received_at)) * 86400) AS INTEGER) AS oldestAgeSeconds
-      FROM reports WHERE state IN ('received', 'human_review', 'ai_review', 'awaiting_reporter', 'human_review_requested', 'appealed')
-      GROUP BY queue_id, state ORDER BY queue_id, state
-    `).bind(generatedAt).all<Record<string, unknown>>(),
-    db.prepare(`
-      SELECT usage_date AS usageDate, SUM(reports_started) AS reportsStarted,
-        SUM(reports_resolved) AS reportsResolved, SUM(reports_escalated) AS reportsEscalated,
-        SUM(failures) AS failures, SUM(estimated_cost_microusd) AS estimatedCostMicrousd,
-        SUM(eligible_reports) AS eligibleReports, SUM(waiting_for_reporter) AS waitingForReporter,
-        SUM(human_review_requests) AS humanReviewRequests, SUM(appeals_filed) AS appealsFiled,
-        SUM(appeal_reversals) AS appealReversals, SUM(invalid_outputs) AS invalidOutputs,
-        SUM(provider_errors) AS providerErrors, SUM(timeouts) AS timeouts
-      FROM ai_usage_daily WHERE usage_date >= ?1 GROUP BY usage_date ORDER BY usage_date
-    `).bind(fromDate).all<Record<string, unknown>>(),
+  const from = `${fromDate}T00:00:00.000Z`;
+  const scope = queueScope === null ? null : JSON.stringify(queueScope);
+  const visible = `WITH visible_reports AS (SELECT * FROM reports WHERE (?2 IS NULL OR queue_id IN (SELECT value FROM json_each(?2))))`;
+  const query = (sql: string) => db.prepare(`${visible} ${sql}`).bind(from, scope);
+  const [series, durations, backlog, evidence, actions, notices, appeals, audits] = await Promise.all([
+    query(`SELECT substr(received_at,1,10) AS aggregateDate, 'reports_received' AS metricKey, 'source' AS dimensionKey, source AS dimensionValue, COUNT(*) AS value FROM visible_reports WHERE received_at >= ?1 GROUP BY aggregateDate, source
+      UNION ALL SELECT substr(received_at,1,10), 'reports_received', 'reason', reason_code, COUNT(*) FROM visible_reports WHERE received_at >= ?1 GROUP BY substr(received_at,1,10), reason_code
+      UNION ALL SELECT substr(d.created_at,1,10), 'decisions', 'maker_type', d.maker_type, COUNT(*) FROM decisions d JOIN visible_reports r ON r.id=d.report_id WHERE d.created_at >= ?1 GROUP BY substr(d.created_at,1,10), d.maker_type
+      UNION ALL SELECT substr(d.created_at,1,10), 'decisions', 'outcome', d.decision_code, COUNT(*) FROM decisions d JOIN visible_reports r ON r.id=d.report_id WHERE d.created_at >= ?1 GROUP BY substr(d.created_at,1,10), d.decision_code
+      ORDER BY 1,2,3,4 LIMIT 10000`).all<Record<string, unknown>>(),
+    query(`SELECT CAST((julianday(resolved_at)-julianday(received_at))*86400 AS INTEGER) AS seconds FROM visible_reports WHERE resolved_at IS NOT NULL AND received_at >= ?1 ORDER BY seconds LIMIT 10000`).all<{ seconds: number }>(),
+    // Backlog is current, irrespective of the selected reporting period.
+    db.prepare(`${visible} SELECT queue_id AS queueId, (SELECT name FROM queue_definitions WHERE id=queue_id) AS queueName, state, COUNT(*) AS count, CAST(MAX((julianday(?1)-julianday(received_at))*86400) AS INTEGER) AS oldestAgeSeconds
+      FROM visible_reports WHERE state IN ('received','human_review','ai_review','awaiting_reporter','human_review_requested','appealed') GROUP BY queue_id,state ORDER BY queue_id,state`).bind(generatedAt, scope).all<Record<string, unknown>>(),
+    query(`SELECT COUNT(*) AS receivedCases,
+      COALESCE(SUM(EXISTS(SELECT 1 FROM findings f WHERE f.report_id=r.id AND f.status='available' AND (f.expires_at IS NULL OR f.expires_at > ?3))),0) AS withRetrievedEvidence,
+      COALESCE(SUM(EXISTS(SELECT 1 FROM findings f WHERE f.report_id=r.id AND (f.status IN ('unavailable','invalid','stale') OR (f.status='available' AND f.expires_at <= ?3)))),0) AS withEvidenceGaps,
+      COALESCE(SUM(EXISTS(SELECT 1 FROM findings f WHERE f.report_id=r.id AND f.status='available' AND json_array_length(f.uncertainty_json)>0)),0) AS withRecordedUncertainty
+      FROM visible_reports r WHERE received_at >= ?1`).bind(from, scope, generatedAt).first<Record<string, number>>(),
+    query(`SELECT 'playbook' AS pipeline, CASE WHEN a.accepted_at IS NOT NULL AND a.delivery_terminal = 0 THEN 'awaiting_confirmation' ELSE a.state END AS state, COUNT(*) AS count FROM action_proposals a JOIN visible_reports r ON r.id=a.report_id WHERE a.created_at >= ?1 GROUP BY 2
+      UNION ALL SELECT 'legacy', a.status, COUNT(*) FROM decision_action_outbox a JOIN visible_reports r ON r.id=a.report_id WHERE a.created_at >= ?1 GROUP BY a.status`).all<Record<string, unknown>>(),
+    query(`SELECT n.audience, n.delivery_state AS state, COUNT(*) AS count FROM notices n JOIN visible_reports r ON r.id=n.report_id WHERE n.created_at >= ?1 GROUP BY n.audience,n.delivery_state`).all<Record<string, unknown>>(),
+    query(`SELECT a.state, COUNT(*) AS count FROM appeals a JOIN visible_reports r ON r.id=a.report_id WHERE a.submitted_at >= ?1 GROUP BY a.state`).all<Record<string, unknown>>(),
+    query(`SELECT s.sample_reason AS reason, COUNT(*) AS selected, SUM(EXISTS(SELECT 1 FROM quality_reviews q WHERE q.sample_id=s.id)) AS reviewed FROM ai_quality_samples s JOIN visible_reports r ON r.id=s.report_id WHERE s.selected_at >= ?1 GROUP BY s.sample_reason`).all<Record<string, unknown>>(),
   ]);
-  const seconds = durations.results.map((row) => row.seconds).filter((value) => Number.isFinite(value));
+  const seconds = durations.results.map(row => row.seconds).filter(value => Number.isFinite(value) && value >= 0);
   return {
-    generatedAt,
-    fromDate,
-    days: boundedDays,
-    series: series.results,
-    backlog: backlog.results,
-    resolutionSeconds: {
-      count: seconds.length,
-      median: percentile(seconds, 0.5),
-      p90: percentile(seconds, 0.9),
-      p95: percentile(seconds, 0.95),
-    },
-    aiUsage: aiUsage.results,
+    generatedAt, fromDate, days: boundedDays, queueScope,
+    series: series.results, backlog: backlog.results,
+    resolutionSeconds: { count: seconds.length, median: percentile(seconds,0.5), p90: percentile(seconds,0.9), p95: percentile(seconds,0.95) },
+    evidenceCoverage: evidence, actions: actions.results, notices: notices.results, appeals: appeals.results, audits: audits.results,
     limitations: [
-      "Counts describe reports and decisions, not verified real-world incidents.",
-      "No rate denominator is calculated unless the customer supplies one.",
+      "Counts describe recorded cases and decisions, not verified real-world incidents.",
+      "Evidence coverage counts stored, available findings; it does not establish that an allegation is true.",
+      "Delivered notices were handed to a delivery provider; recipient reading is not measured.",
+      "Appeal outcomes and quality samples describe reviewed work, not an overall accuracy score.",
+      ...(queueScope !== null ? ["Only cases in your current queue scope are included."] : []),
       ...(durations.results.length >= 10000 ? ["Resolution percentiles are bounded to the first 10,000 records in the selected period."] : []),
+      ...(series.results.length >= 10000 ? ["Daily breakdowns are limited to 10,000 rows; narrow the period for a complete breakdown."] : []),
     ],
   };
 }
@@ -179,6 +171,7 @@ async function anonymizeReport(
   ]);
   if (scope === "all_permitted_data") {
     await db.batch([
+      db.prepare(`UPDATE report_handoffs SET note = '[removed by retention]', redacted_at = COALESCE(redacted_at, ?2) WHERE report_id = ?1`).bind(reportId, at),
       db.prepare(`UPDATE case_messages SET body = '[removed by retention]', sender_id = 'redacted', redacted_at = COALESCE(redacted_at, ?2) WHERE report_id = ?1`).bind(reportId, at),
       db.prepare(`
         UPDATE report_targets SET target_reference = 'redacted:' || id, owner_reference = NULL,
@@ -189,7 +182,7 @@ async function anonymizeReport(
       db.prepare(`UPDATE decisions SET rationale = '[removed by retention]', evidence_references_json = '[]', sensitive_redacted_at = ?2 WHERE report_id = ?1 AND sensitive_redacted_at IS NULL`).bind(reportId, at),
       db.prepare(`UPDATE notices SET rendered_body = '[removed by retention]', redacted_at = ?2 WHERE report_id = ?1 AND redacted_at IS NULL`).bind(reportId, at),
       db.prepare(`
-        UPDATE appeal_decisions SET rationale = '[removed by retention]', rationale_redacted_at = ?2
+        UPDATE appeal_decisions SET rationale = '[removed by retention]', rationale_redacted_at = ?2, correction_reference = NULL, correction_note = NULL
         WHERE appeal_id IN (SELECT id FROM appeals WHERE report_id = ?1) AND rationale_redacted_at IS NULL
       `).bind(reportId, at),
       db.prepare(`
@@ -249,6 +242,10 @@ export async function runScheduledRetention(db: D1Database, messageRetentionDays
         SELECT 1 FROM legal_holds h WHERE h.report_id = notices.report_id AND h.state = 'active'
       )
     `).bind(messageCutoff, startedAt).run();
+    await db.prepare(`UPDATE report_handoffs SET note = '[removed by retention]', redacted_at = ?2
+      WHERE redacted_at IS NULL AND created_at < ?1 AND NOT EXISTS (
+        SELECT 1 FROM legal_holds h WHERE h.report_id = report_handoffs.report_id AND h.state = 'active'
+      )`).bind(messageCutoff, startedAt).run();
     const candidates = await db.prepare(`
       SELECT id FROM reports r
       WHERE r.updated_at < ?1 AND r.state IN ('resolved_by_human', 'resolved_by_ai', 'closed')