create-safest-tools 0.2.0

package/template/src/report-repository.ts

@@ -0,0 +1,972 @@
+import { AUDIT_GENESIS_HASH, canonicalJson, hashAuditEntry } from "./audit";
+import { aiConfigurationForRouting } from "./report-ai";
+import { ApiError } from "./report-http";
+import { encryptReportContact, randomPublicReference, sha256 } from "./report-crypto";
+import { analystAvatarColor } from "./report-presence";
+import { activeRoutingAgent, executeRoutingAgent, type RoutingAiBinding } from "./report-router-agent";
+import { evaluateHardSafeguards, queueMatches, selectRoute, type QueueRoutingPolicy, type RoutingInput } from "./report-routing";
+import type { QueueManagementMode, QueueRolloutMode, RoutingCondition } from "./report-queue-validation";
+import type { AiJob, DeliveryJob, InboxReport, IntakeReceipt, ReportSubmission, ReportState } from "./report-types";
+import type { WorkflowDispatchJob } from "./report-types";
+import { preparePinnedWorkflowRunsForRouting } from "./workflow-runs";
+import { planIntakeProtection } from "./intake-abuse";
+import { validateAnswersAgainstFormFields } from "./report-form-validation";
+import type { JsonObject, JsonValue } from "./workflow-platform-types";
+
+export interface IntegrationRow {
+  id: string;
+  key_id: string;
+  allowed_origins_json: string;
+  enabled: number;
+  channel_mode: "contextual" | "anonymous";
+  form_version_id: string | null;
+  context_schema_json: string;
+}
+
+interface FormRow {
+  id: string;
+  target_types_json: string;
+  reasons_json: string;
+  fields_json: string;
+  consent_notice: string;
+}
+
+interface ExistingReportRow {
+  id: string;
+  public_reference: string;
+  state: ReportState;
+  received_at: string;
+}
+
+interface AuditTipRow {
+  sequence: number;
+  entry_hash: string;
+}
+
+interface InboxReportRow {
+  id: string;
+  reference: string;
+  state: ReportState;
+  priority: number;
+  reasonCode: string;
+  queueId: string | null;
+  targetType: string;
+  targetReference: string;
+  submittedAt: string;
+  receivedAt: string;
+  updatedAt: string;
+  dueAt: string | null;
+  claimReviewerId: string | null;
+  claimedAt: string | null;
+  claimExpiresAt: string | null;
+  analystDisplayName: string | null;
+  analystAvatarUrl: string | null;
+  analystAvatarColor: string | null;
+}
+
+interface RoutingJobRow {
+  id: string;
+  report_id: string;
+  state: "pending" | "enqueued" | "processing" | "complete" | "failed" | "dead_letter";
+  reason_code: string;
+  trusted_facts_json: string;
+  report_state: ReportState;
+  source: string;
+  form_version_id: string;
+  target_type: string;
+  target_reference: string;
+  owner_reference: string | null;
+  customer_url: string | null;
+  public_reference: string;
+  installation_id: string;
+}
+
+interface QueueRoutingRow {
+  queueId: string;
+  queueVersionId: string;
+  managementMode: QueueManagementMode;
+  rolloutMode: QueueRolloutMode;
+  priority: number;
+  responseSlaMinutes: number | null;
+  fallbackQueueId: string | null;
+  position: number;
+  aiBoundsJson: string;
+}
+
+interface PublishedRoutingRule {
+  id: string;
+  queueId: string;
+  priority: number;
+  routingCriteria: { match: "all" | "any"; conditions: RoutingCondition[] };
+}
+
+interface PublishedRoutingRuleSet {
+  id: string;
+  defaultQueueId: string;
+  safeguardQueueId: string;
+  intakeEnrichments: Array<{ componentVersionId: string; inputMapping: Record<string, JsonValue> }>;
+  rules: PublishedRoutingRule[];
+}
+
+export interface RoutingIntakeEnrichmentInput {
+  reportId: string;
+  componentVersionId: string;
+  inputMapping: Record<string, JsonValue>;
+  context: JsonObject;
+  operationId: string;
+}
+
+export type RoutingIntakeEnrichmentExecutor = (input: RoutingIntakeEnrichmentInput) => Promise<{
+  componentKey: string;
+  data: JsonObject;
+}>;
+
+function isoNow(): string {
+  return new Date().toISOString();
+}
+
+function addMinutes(timestamp: string, minutes: number): string {
+  return new Date(Date.parse(timestamp) + minutes * 60_000).toISOString();
+}
+
+function parseJsonArray(value: string): unknown[] {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+function d1Message(error: unknown): string {
+  return error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+}
+
+function isConstraintError(error: unknown): boolean {
+  const message = d1Message(error);
+  return message.includes("constraint") || message.includes("unique") || message.includes("foreign key");
+}
+
+function receipt(row: ExistingReportRow, idempotentReplay: boolean): IntakeReceipt {
+  return {
+    reportId: row.id,
+    reference: row.public_reference,
+    state: row.state,
+    receivedAt: row.received_at,
+    idempotentReplay,
+  };
+}
+
+export async function loadIntegration(db: D1Database, integrationId: string): Promise<IntegrationRow | null> {
+  return db.prepare(`
+    SELECT id, key_id, allowed_origins_json, enabled,
+      channel_mode, form_version_id, context_schema_json
+    FROM application_integrations
+    WHERE id = ?1
+    LIMIT 1
+  `).bind(integrationId).first<IntegrationRow>();
+}
+
+export function integrationAllowsOrigin(integration: IntegrationRow, origin: string): boolean {
+  return parseJsonArray(integration.allowed_origins_json).some((value) => value === origin);
+}
+
+export async function installationAllowsWidgetOrigin(db: D1Database, origin: string): Promise<boolean> {
+  const rows = await db.prepare(`SELECT allowed_origins_json AS originsJson FROM application_integrations WHERE installation_id = 'default' AND enabled = 1`)
+    .all<{ originsJson: string }>();
+  return rows.results.some((row) => parseJsonArray(row.originsJson).some((value) => value === origin));
+}
+
+async function loadExisting(db: D1Database, integrationId: string, idempotencyKey: string): Promise<ExistingReportRow | null> {
+  return db.prepare(`
+    SELECT id, public_reference, state, received_at
+    FROM reports
+    WHERE integration_id = ?1 AND idempotency_key = ?2
+    LIMIT 1
+  `).bind(integrationId, idempotencyKey).first<ExistingReportRow>();
+}
+
+export async function loadContextReportReplay(
+  db: D1Database,
+  integrationId: string,
+  contextJti: string,
+  idempotencyKey: string,
+): Promise<IntakeReceipt | null> {
+  const row = await db.prepare(`
+    SELECT r.id, r.public_reference, r.state, r.received_at
+    FROM context_token_uses u
+    JOIN reports r ON r.id = u.report_id
+    WHERE u.jti = ?1 AND u.integration_id = ?2
+      AND r.integration_id = ?2 AND r.idempotency_key = ?3
+    LIMIT 1
+  `).bind(contextJti, integrationId, idempotencyKey).first<ExistingReportRow>();
+  if (!row) return null;
+  return receipt(row, true);
+}
+
+async function loadForm(db: D1Database, formVersionId: string): Promise<FormRow | null> {
+  return db.prepare(`
+    SELECT id, target_types_json, reasons_json, fields_json, consent_notice
+    FROM report_form_versions
+    WHERE id = ?1 AND published_at IS NOT NULL AND retired_at IS NULL
+    LIMIT 1
+  `).bind(formVersionId).first<FormRow>();
+}
+
+function validateAgainstForm(submission: ReportSubmission, form: FormRow): void {
+  const targets = new Set(parseJsonArray(form.target_types_json).filter((value): value is string => typeof value === "string"));
+  if (!targets.has(submission.target.type)) {
+    throw new ApiError(400, "target_type_not_allowed", "The selected form does not accept this target type.", { field: "target.type" });
+  }
+  const reasons = new Set(parseJsonArray(form.reasons_json)
+    .map((value) => value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>).code : null)
+    .filter((value): value is string => typeof value === "string"));
+  if (!reasons.has(submission.reasonCode)) {
+    throw new ApiError(400, "reason_not_allowed", "The selected form does not accept this reason.", { field: "reason_code" });
+  }
+  if (submission.consentNotice !== form.consent_notice) {
+    throw new ApiError(409, "form_notice_changed", "The form notice changed. Reload the form before submitting.");
+  }
+  validateAnswersAgainstFormFields(submission.answers, parseJsonArray(form.fields_json));
+}
+
+async function auditTip(db: D1Database): Promise<AuditTipRow> {
+  return await db.prepare(`SELECT sequence, entry_hash FROM audit_entries ORDER BY sequence DESC LIMIT 1`).first<AuditTipRow>()
+    ?? { sequence: 0, entry_hash: AUDIT_GENESIS_HASH };
+}
+
+export interface CreateReportOptions {
+  contactEncryptionKey: string;
+  emailEnabled: boolean;
+  notificationEnabled: boolean;
+  abusePepper: string;
+  networkAddress?: string | null;
+  turnstileOutcome?: string | null;
+  surgeThresholdPerFiveMinutes: number;
+}
+
+export async function createReport(
+  db: D1Database,
+  submission: ReportSubmission,
+  options: CreateReportOptions,
+): Promise<{ receipt: IntakeReceipt; jobId: string; deliveryJobs: DeliveryJob[]; created: boolean; route: boolean }> {
+  if (submission.source === "public_page" && submission.reporter.email && !options.emailEnabled && !options.notificationEnabled) {
+    throw new ApiError(503, "reporter_notifications_unavailable", "Anonymous reporting is temporarily unavailable because its secure email notification channel is not configured.");
+  }
+  const integration = await loadIntegration(db, submission.integrationId);
+  if (!integration || integration.enabled !== 1) throw new ApiError(401, "integration_not_available", "The application integration is not enabled.");
+  const existing = await loadExisting(db, submission.integrationId, submission.idempotencyKey);
+  if (existing) {
+    return { receipt: receipt(existing, true), jobId: `route:${existing.id}`, deliveryJobs: [], created: false, route: false };
+  }
+  const form = await loadForm(db, submission.formVersionId);
+  if (!form) throw new ApiError(400, "form_not_available", "The selected report form is not available.");
+  validateAgainstForm(submission, form);
+
+  const intakePlan = await planIntakeProtection(db, submission, {
+    pepper: options.abusePepper,
+    networkAddress: options.networkAddress ?? null,
+    turnstileOutcome: options.turnstileOutcome ?? null,
+    surgeThresholdPerFiveMinutes: options.surgeThresholdPerFiveMinutes,
+  });
+
+  const reportId = crypto.randomUUID();
+  const publicReference = randomPublicReference();
+  const receivedAt = isoNow();
+  const jobId = `route:${reportId}`;
+  const reporterParticipantId = crypto.randomUUID();
+  const contactCiphertext = submission.reporter.email
+    ? await encryptReportContact(options.contactEncryptionKey, submission.reporter.email, reportId, "reporter")
+    : null;
+  const receiptMessageId = crypto.randomUUID();
+  const receiptNoticeId = crypto.randomUUID();
+  const receiptDeliveryId = crypto.randomUUID();
+  const receiptBody = `We received report ${publicReference}. The safety team will send updates through your configured notification channel.`;
+  const directEmail = Boolean(submission.reporter.email && options.emailEnabled);
+  const webhookNotification = Boolean(!directEmail && options.notificationEnabled
+    && (submission.reporter.email || submission.reporter.reference));
+  const deliveryJobs: DeliveryJob[] = directEmail
+    ? [{ version: 1, jobId: `email:${receiptDeliveryId}`, type: "deliver_email", outboxId: receiptDeliveryId }]
+    : webhookNotification
+      ? [{ version: 1, jobId: `notification:${receiptDeliveryId}`, type: "deliver_notification", outboxId: receiptDeliveryId }]
+      : [];
+  const receiptDeliveryState = deliveryJobs.length ? "queued" : "suppressed";
+  const detailsJson = canonicalJson({
+    source: submission.source,
+    formVersionId: submission.formVersionId,
+    reasonCode: submission.reasonCode,
+    targetType: submission.target.type,
+    evidenceMode: submission.evidence.mode,
+    intakeDecision: intakePlan.disposition,
+    duplicateGroupId: intakePlan.duplicateGroupId,
+  });
+  const auditAction = intakePlan.disposition === "quarantine"
+    ? "report.quarantined" : intakePlan.disposition === "group" ? "report.grouped" : "report.accepted";
+
+  for (let auditAttempt = 0; auditAttempt < 3; auditAttempt += 1) {
+    const tip = await auditTip(db);
+    const auditSequence = tip.sequence + 1;
+    const auditId = crypto.randomUUID();
+    const auditHash = await hashAuditEntry({
+      sequence: auditSequence,
+      action: auditAction,
+      actorType: "integration",
+      actorId: submission.integrationId,
+      targetType: "report",
+      targetId: reportId,
+      detailsJson,
+      previousHash: tip.entry_hash,
+      createdAt: receivedAt,
+    });
+
+    const statements: D1PreparedStatement[] = [
+      db.prepare(`
+        INSERT INTO duplicate_groups (
+          id, installation_id, fingerprint_version, fingerprint,
+          target_type, target_reference_hash, reason_family, state,
+          canonical_report_id, member_count, first_seen_at, last_seen_at,
+          created_at, updated_at
+        ) VALUES (?1, 'default', 'v1', ?2, ?3, ?4, ?5, 'active', NULL, 0, ?6, ?6, ?6, ?6)
+        ON CONFLICT(installation_id, fingerprint_version, fingerprint) DO UPDATE SET
+          last_seen_at = excluded.last_seen_at, updated_at = excluded.updated_at
+      `).bind(
+        intakePlan.duplicateGroupId, intakePlan.campaignFingerprint,
+        submission.target.type, intakePlan.targetKeyHash, submission.reasonCode, receivedAt,
+      ),
+      db.prepare(`
+        INSERT INTO reports (
+          id, public_reference, installation_id, integration_id, idempotency_key, source,
+          form_version_id, policy_version_id, state, priority, reason_code, locale,
+          consent_notice, consented_at, submitted_at, received_at, updated_at, routing_status,
+          duplicate_group_id, quarantine_reason_code
+        ) VALUES (?1, ?2, 'default', ?3, ?4, ?5, ?6, 'general-policy-v1', 'received', 50, ?7, ?8, ?9, ?10, ?11, ?12, ?12, ?13, ?14, ?15)
+      `).bind(
+        reportId, publicReference, submission.integrationId, submission.idempotencyKey, submission.source,
+        submission.formVersionId, submission.reasonCode, submission.locale, submission.consentNotice,
+        submission.consentedAt, submission.submittedAt, receivedAt,
+        intakePlan.route ? "pending" : "complete", intakePlan.duplicateGroupId,
+        intakePlan.disposition === "quarantine" ? intakePlan.reasonCodes[0] : null,
+      ),
+      db.prepare(`
+        INSERT INTO report_participants (id, report_id, audience, reference, contact_mode, contact_ciphertext, created_at)
+        VALUES (?1, ?2, 'reporter', ?3, ?4, ?5, ?6)
+      `).bind(reporterParticipantId, reportId, submission.reporter.reference ?? null, submission.reporter.contactMode, contactCiphertext, receivedAt),
+      db.prepare(`
+        INSERT INTO report_targets (
+          id, report_id, target_type, target_reference, owner_reference, customer_url,
+          signed_facts_json, routing_facts_json, created_at
+        ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)
+      `).bind(
+        crypto.randomUUID(), reportId, submission.target.type, submission.target.reference,
+        submission.target.ownerReference ?? null, submission.target.customerUrl ?? null,
+        canonicalJson(submission.trustedFacts), canonicalJson(submission.routingFacts), receivedAt,
+      ),
+      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, NULL, 'received', ?3, 'integration', ?4, ?5)
+      `).bind(
+        crypto.randomUUID(), reportId,
+        intakePlan.disposition === "quarantine" ? "intake_quarantined" : intakePlan.disposition === "group" ? "intake_grouped" : "durable_intake",
+        submission.integrationId, receivedAt,
+      ),
+      db.prepare(`
+        INSERT INTO background_jobs (
+          id, report_id, job_type, idempotency_key, state, payload_json, available_at, created_at, updated_at
+        ) VALUES (?1, ?2, 'route_report', ?1, ?3, ?4, ?5, ?5, ?5)
+      `).bind(
+        jobId, reportId, intakePlan.route ? "pending" : "complete",
+        canonicalJson({ reportId, intakeDecisionId: intakePlan.decisionId, disposition: intakePlan.disposition }), receivedAt,
+      ),
+      db.prepare(`
+        INSERT INTO intake_decisions (
+          id, installation_id, integration_id, report_id, request_id,
+          decision, reason_codes_json, source, network_key_hash,
+          contact_key_hash, target_key_hash, campaign_fingerprint,
+          turnstile_outcome, rate_summary_json, created_at
+        ) VALUES (?1, 'default', ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14)
+      `).bind(
+        intakePlan.decisionId, submission.integrationId, reportId, intakePlan.requestId,
+        intakePlan.disposition, canonicalJson(intakePlan.reasonCodes), submission.source,
+        intakePlan.networkKeyHash, intakePlan.contactKeyHash, intakePlan.targetKeyHash,
+        intakePlan.campaignFingerprint, options.turnstileOutcome ?? null,
+        canonicalJson(intakePlan.rateSummary), receivedAt,
+      ),
+      db.prepare(`UPDATE reports SET intake_decision_id = ?2 WHERE id = ?1`).bind(reportId, intakePlan.decisionId),
+      db.prepare(`
+        INSERT INTO duplicate_group_members (group_id, report_id, similarity_basis_json, added_at)
+        VALUES (?1, ?2, ?3, ?4)
+      `).bind(
+        intakePlan.duplicateGroupId, reportId,
+        canonicalJson({ fingerprint_version: "v1", exact_fingerprint: true, target_hash: intakePlan.targetKeyHash }), receivedAt,
+      ),
+      db.prepare(`
+        UPDATE duplicate_groups SET canonical_report_id = COALESCE(canonical_report_id, ?2),
+          member_count = (SELECT COUNT(*) FROM duplicate_group_members WHERE group_id = ?1 AND removed_at IS NULL),
+          last_seen_at = ?3, updated_at = ?3 WHERE id = ?1
+      `).bind(intakePlan.duplicateGroupId, reportId, receivedAt),
+      db.prepare(`
+        INSERT INTO audit_entries (
+          sequence, id, action, actor_type, actor_id, target_type, target_id, details_json,
+          previous_hash, entry_hash, created_at
+        ) VALUES (?1, ?2, ?3, 'integration', ?4, 'report', ?5, ?6, ?7, ?8, ?9)
+      `).bind(auditSequence, auditId, auditAction, submission.integrationId, reportId, detailsJson, tip.entry_hash, auditHash, receivedAt),
+      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, 'reporter', 'outbound', 'system', 'intake', ?3, 'report-received-v1', 1, ?4, ?5, ?6)
+      `).bind(receiptMessageId, reportId, receiptBody, receiptDeliveryState, receivedAt, `report-received:${reportId}`),
+      db.prepare(`
+        INSERT INTO notices (
+          id, report_id, audience, template_version_id, rendered_body, delivery_state,
+          created_at, updated_at, idempotency_key, message_id
+        ) VALUES (?1, ?2, 'reporter', 'report-received-v1', ?3, ?4, ?5, ?5, ?6, ?7)
+      `).bind(receiptNoticeId, reportId, receiptBody, receiptDeliveryState, receivedAt, `report-received:${reportId}`, receiptMessageId),
+    ];
+
+    if (directEmail && submission.reporter.email) {
+      statements.push(db.prepare(`
+        INSERT INTO email_deliveries (
+          id, installation_id, message_id, audience, recipient_hash,
+          provider, state, attempt_count, next_attempt_at, created_at, updated_at
+        ) VALUES (?1, 'default', ?2, 'reporter', ?3, 'cloudflare_email_service', 'pending', 0, ?4, ?4, ?4)
+      `).bind(
+        receiptDeliveryId, receiptMessageId,
+        `sha256:${await sha256(`email-recipient-v1:${options.abusePepper}:${submission.reporter.email}`)}`,
+        receivedAt,
+      ));
+    } else if (webhookNotification) {
+      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(receiptDeliveryId, receiptNoticeId, `notice:${receiptNoticeId}`, canonicalJson({
+        version: 1,
+        event: "report.received",
+        notification_id: receiptDeliveryId,
+        report_reference: publicReference,
+        ...(submission.reporter.reference ? { recipient_reference: submission.reporter.reference } : {}),
+        audience: "reporter",
+        message: receiptBody,
+      }), receivedAt));
+    }
+
+    if (intakePlan.activateSurge) {
+      statements.push(db.prepare(`
+        INSERT INTO abuse_surge_states (
+          installation_id, state, reason_codes_json, activated_at,
+          recover_after, revision, updated_by, updated_at
+        ) VALUES ('default', 'surge', '["public_intake_velocity"]', ?1, ?2, 1, 'system:intake-guard', ?1)
+        ON CONFLICT(installation_id) DO UPDATE SET state = 'surge',
+          reason_codes_json = excluded.reason_codes_json,
+          activated_at = COALESCE(abuse_surge_states.activated_at, excluded.activated_at),
+          recover_after = excluded.recover_after, revision = abuse_surge_states.revision + 1,
+          updated_by = excluded.updated_by, updated_at = excluded.updated_at
+      `).bind(receivedAt, addMinutes(receivedAt, 15)));
+    }
+
+    if (submission.contextJti) {
+      statements.push(db.prepare(`
+        INSERT INTO context_token_uses (jti, integration_id, report_id, used_at)
+        VALUES (?1, ?2, ?3, ?4)
+      `).bind(submission.contextJti, submission.integrationId, reportId, receivedAt));
+    }
+    if (submission.contextId) {
+      statements.push(db.prepare(`
+        UPDATE report_contexts SET used_at = ?2, report_id = ?3
+        WHERE id = ?1 AND integration_id = ?4 AND used_at IS NULL
+      `).bind(submission.contextId, receivedAt, reportId, submission.integrationId));
+    }
+    for (const [key, value] of Object.entries(submission.answers)) {
+      statements.push(db.prepare(`
+        INSERT INTO report_answers (report_id, field_key, value_json, created_at)
+        VALUES (?1, ?2, ?3, ?4)
+      `).bind(reportId, key, canonicalJson(value), receivedAt));
+    }
+    const evidenceReferences = new Set([submission.target.reference, ...submission.evidence.references]);
+    for (const reference of evidenceReferences) {
+      statements.push(db.prepare(`
+        INSERT INTO evidence_references (id, report_id, evidence_kind, reference, created_at)
+        VALUES (?1, ?2, ?3, ?4, ?5)
+      `).bind(
+        crypto.randomUUID(), reportId, submission.source === "public_page" ? "allegation" : "customer_reference",
+        reference, receivedAt,
+      ));
+    }
+
+    try {
+      await db.batch(statements);
+      const row: ExistingReportRow = { id: reportId, public_reference: publicReference, state: "received", received_at: receivedAt };
+      return { receipt: receipt(row, false), jobId, deliveryJobs, created: true, route: intakePlan.route };
+    } catch (error) {
+      if (!isConstraintError(error)) throw error;
+      const concurrent = await loadExisting(db, submission.integrationId, submission.idempotencyKey);
+      if (concurrent) {
+        return { receipt: receipt(concurrent, true), jobId: `route:${concurrent.id}`, deliveryJobs: [], created: false, route: false };
+      }
+      if (submission.contextJti) {
+        const used = await db.prepare(`SELECT report_id FROM context_token_uses WHERE jti = ?1 LIMIT 1`)
+          .bind(submission.contextJti).first<{ report_id: string }>();
+        if (used) throw new ApiError(409, "context_token_replayed", "This signed context token has already been used.");
+      }
+      if (auditAttempt === 2) throw new ApiError(503, "audit_contention", "The report could not be accepted yet. Retry with the same idempotency key.");
+    }
+  }
+  throw new ApiError(503, "intake_unavailable", "The report could not be accepted yet. Retry with the same idempotency key.");
+}
+
+export async function markJobEnqueued(db: D1Database, jobId: string): Promise<void> {
+  await db.prepare(`
+    UPDATE background_jobs SET state = 'enqueued', last_error_code = NULL, updated_at = ?2
+    WHERE id = ?1 AND state IN ('pending', 'failed')
+  `).bind(jobId, isoNow()).run();
+  await db.prepare(`
+    UPDATE reports SET routing_status = 'enqueued', routing_error_code = NULL, updated_at = ?2
+    WHERE id = (SELECT report_id FROM background_jobs WHERE id = ?1) AND routing_status IN ('pending', 'failed')
+  `).bind(jobId, isoNow()).run();
+}
+
+export async function markJobEnqueueFailed(db: D1Database, jobId: string, errorCode: string): Promise<void> {
+  const now = isoNow();
+  await db.batch([
+    db.prepare(`
+      UPDATE background_jobs
+      SET state = 'failed', attempt_count = attempt_count + 1, last_error_code = ?2, updated_at = ?3
+      WHERE id = ?1 AND state != 'complete'
+    `).bind(jobId, errorCode.slice(0, 100), now),
+    db.prepare(`
+      UPDATE reports
+      SET routing_status = 'failed', routing_attempts = routing_attempts + 1, routing_error_code = ?2, updated_at = ?3
+      WHERE id = (SELECT report_id FROM background_jobs WHERE id = ?1) AND routing_status != 'complete'
+    `).bind(jobId, errorCode.slice(0, 100), now),
+  ]);
+}
+
+export async function pendingRoutingJobs(db: D1Database, limit = 50): Promise<Array<{ id: string; reportId: string }>> {
+  const staleBefore = new Date(Date.now() - 5 * 60_000).toISOString();
+  const result = await db.prepare(`
+    SELECT id, report_id AS reportId
+    FROM background_jobs
+    WHERE job_type = 'route_report'
+      AND (state IN ('pending', 'failed') OR (state = 'processing' AND updated_at <= ?3))
+      AND available_at <= ?1
+    ORDER BY available_at ASC, id ASC
+    LIMIT ?2
+  `).bind(isoNow(), Math.max(1, Math.min(100, limit)), staleBefore).all<{ id: string; reportId: string }>();
+  return result.results;
+}
+
+function parsedRoutingPolicy(row: QueueRoutingRow): QueueRoutingPolicy | null {
+  try {
+    const aiBounds: unknown = JSON.parse(row.aiBoundsJson);
+    return {
+      queueId: row.queueId,
+      queueVersionId: row.queueVersionId,
+      managementMode: row.managementMode,
+      rolloutMode: row.rolloutMode,
+      priority: row.priority,
+      responseSlaMinutes: row.responseSlaMinutes,
+      fallbackQueueId: row.fallbackQueueId,
+      position: row.position,
+      routingCriteria: { match: "all", conditions: [] },
+      adjudicationPolicyVersionId: aiBounds && typeof aiBounds === "object" && !Array.isArray(aiBounds)
+        && typeof (aiBounds as Record<string, unknown>).policyVersionId === "string"
+        ? String((aiBounds as Record<string, unknown>).policyVersionId)
+        : "general-policy-v1",
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function activeQueueRoutingPolicies(db: D1Database): Promise<QueueRoutingPolicy[]> {
+  const rows = await db.prepare(`
+    SELECT q.id AS queueId, v.id AS queueVersionId, v.management_mode AS managementMode,
+      v.mode AS rolloutMode, v.priority, v.response_sla_minutes AS responseSlaMinutes,
+      v.fallback_queue_id AS fallbackQueueId, q.position, v.ai_bounds_json AS aiBoundsJson
+    FROM queue_definitions q JOIN queue_versions v ON v.id = q.active_version_id
+    WHERE q.purpose = 'reports' AND q.status = 'active'
+    ORDER BY q.position, q.id
+  `).all<QueueRoutingRow>();
+  return rows.results.map(parsedRoutingPolicy).filter((queue): queue is QueueRoutingPolicy => Boolean(queue));
+}
+
+async function activePublishedRoutingRules(db: D1Database): Promise<PublishedRoutingRuleSet> {
+  const row = await db.prepare(`
+    SELECT id, rules_json AS rulesJson FROM routing_rule_versions
+    WHERE installation_id = 'default' AND published_at IS NOT NULL
+    ORDER BY version DESC, id DESC LIMIT 1
+  `).first<{ id: string; rulesJson: string }>();
+  if (!row) throw new ApiError(503, "published_routing_rules_missing", "A published routing rule version is required before reports can be routed.");
+  try {
+    const content = JSON.parse(row.rulesJson) as Record<string, unknown>;
+    if (!content || typeof content !== "object" || Array.isArray(content)
+      || typeof content.default_queue_id !== "string" || typeof content.safeguard_queue_id !== "string"
+      || !Array.isArray(content.rules)) throw new Error("invalid");
+    const rules = content.rules.map((value): PublishedRoutingRule => {
+      if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid");
+      const rule = value as Record<string, unknown>;
+      if (typeof rule.id !== "string" || typeof rule.queue_id !== "string" || !Number.isInteger(rule.priority)
+        || (rule.match !== "all" && rule.match !== "any") || !Array.isArray(rule.conditions)) throw new Error("invalid");
+      return {
+        id: rule.id,
+        queueId: rule.queue_id,
+        priority: Number(rule.priority),
+        routingCriteria: { match: rule.match, conditions: rule.conditions as RoutingCondition[] },
+      };
+    }).sort((left, right) => right.priority - left.priority || left.id.localeCompare(right.id));
+    const intakeEnrichments: Array<{ componentVersionId: string; inputMapping: Record<string, JsonValue> }> = [];
+    if (Array.isArray(content.intake_enrichments)) {
+      for (const value of content.intake_enrichments) {
+        if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("invalid");
+        const entry = value as Record<string, unknown>;
+        if (typeof entry.component_version_id !== "string" || !entry.input_mapping || typeof entry.input_mapping !== "object" || Array.isArray(entry.input_mapping)) throw new Error("invalid");
+        intakeEnrichments.push({ componentVersionId: entry.component_version_id, inputMapping: entry.input_mapping as Record<string, JsonValue> });
+      }
+    }
+    if (intakeEnrichments.length > 5 || new Set(intakeEnrichments.map((entry) => entry.componentVersionId)).size !== intakeEnrichments.length) throw new Error("invalid");
+    return {
+      id: row.id,
+      defaultQueueId: content.default_queue_id,
+      safeguardQueueId: content.safeguard_queue_id,
+      intakeEnrichments,
+      rules,
+    };
+  } catch {
+    throw new ApiError(503, "published_routing_rules_invalid", "The published routing rule version cannot be evaluated safely.");
+  }
+}
+
+export async function processRoutingJob(
+  db: D1Database,
+  jobId: string,
+  ai?: RoutingAiBinding,
+  intakeExecutor?: RoutingIntakeEnrichmentExecutor,
+): Promise<Array<AiJob | WorkflowDispatchJob>> {
+  const job = await db.prepare(`
+    SELECT j.id, j.report_id, j.state, r.reason_code, r.source, r.form_version_id,
+           r.installation_id, r.public_reference,
+           t.target_type, t.target_reference, t.owner_reference, t.customer_url,
+           t.routing_facts_json AS trusted_facts_json, r.state AS report_state
+    FROM background_jobs j
+    JOIN reports r ON r.id = j.report_id
+    JOIN report_targets t ON t.report_id = r.id
+    WHERE j.id = ?1 AND j.job_type = 'route_report'
+    LIMIT 1
+  `).bind(jobId).first<RoutingJobRow>();
+  if (!job) throw new ApiError(404, "job_not_found", "The routing job does not exist.");
+  if (job.state === "complete") return [];
+  if (job.report_state !== "received") {
+    await db.prepare(`UPDATE background_jobs SET state = 'complete', updated_at = ?2 WHERE id = ?1`).bind(jobId, isoNow()).run();
+    return [];
+  }
+  const claimedAt = isoNow();
+  const staleBefore = new Date(Date.now() - 5 * 60_000).toISOString();
+  const claim = await db.prepare(`
+    UPDATE background_jobs SET state = 'processing', attempt_count = attempt_count + 1,
+      last_error_code = NULL, updated_at = ?2
+    WHERE id = ?1 AND job_type = 'route_report'
+      AND (state IN ('pending','enqueued','failed') OR (state = 'processing' AND updated_at <= ?3))
+  `).bind(jobId, claimedAt, staleBefore).run();
+  if ((claim.meta.changes ?? 0) !== 1) return [];
+  await db.prepare(`UPDATE reports SET routing_status = 'processing', routing_error_code = NULL, updated_at = ?2 WHERE id = ?1 AND state = 'received'`)
+    .bind(job.report_id, claimedAt).run();
+  let trustedFacts: Record<string, string | number | boolean | null> = {};
+  try {
+    const parsed: unknown = JSON.parse(job.trusted_facts_json);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) trustedFacts = parsed as typeof trustedFacts;
+  } catch {
+    trustedFacts = { trusted_facts_conflict: true };
+  }
+  const answersResult = await db.prepare(`SELECT field_key, value_json FROM report_answers WHERE report_id = ?1`)
+    .bind(job.report_id).all<{ field_key: string; value_json: string }>();
+  const answers: Record<string, unknown> = {};
+  for (const row of answersResult.results) {
+    try { answers[row.field_key] = JSON.parse(row.value_json) as unknown; } catch { answers[row.field_key] = null; }
+  }
+  const routingInput: RoutingInput = {
+    reasonCode: job.reason_code,
+    source: job.source,
+    targetType: job.target_type,
+    trustedFacts,
+    answers,
+    priority: 50,
+  };
+  const queues = await activeQueueRoutingPolicies(db);
+  const routingRules = await activePublishedRoutingRules(db);
+  const routingAgent = await activeRoutingAgent(db);
+  const defaultQueueId = routingRules.defaultQueueId;
+  const safeguardQueueId = routingRules.safeguardQueueId;
+  if (!defaultQueueId || !safeguardQueueId) {
+    throw new ApiError(503, "routing_human_fallback_missing", "Routing requires active default and safeguard human queues.");
+  }
+  const safeguard = evaluateHardSafeguards(routingInput);
+  const byQueueId = new Map(queues.map((queue) => [queue.queueId, queue]));
+  let matchedRules = routingRules.rules.filter((rule) => {
+    const queue = byQueueId.get(rule.queueId);
+    return queue ? queueMatches(routingInput, { ...queue, routingCriteria: rule.routingCriteria }, safeguard) : false;
+  });
+  let intakeEnrichmentFailures: string[] = [];
+  if (!safeguard.requiresHuman && matchedRules.length === 0 && routingRules.intakeEnrichments.length) {
+    if (intakeExecutor) {
+      const context = JSON.parse(canonicalJson({
+        report: {
+          id: job.report_id, public_reference: job.public_reference, reason_code: job.reason_code,
+          source: job.source, target_type: job.target_type, priority: 50,
+        },
+        target: {
+          type: job.target_type, reference: job.target_reference,
+          owner_reference: job.owner_reference, customer_url: job.customer_url,
+          signed_facts: trustedFacts,
+        },
+        answers,
+        trusted_facts: trustedFacts,
+      })) as JsonObject;
+      const settled = await Promise.allSettled(routingRules.intakeEnrichments.map((entry) => intakeExecutor({
+        reportId: job.report_id,
+        componentVersionId: entry.componentVersionId,
+        inputMapping: entry.inputMapping,
+        context,
+        operationId: `${jobId}:intake:${entry.componentVersionId}`,
+      })));
+      const enrichments: Record<string, unknown> = {};
+      settled.forEach((result, index) => {
+        const componentVersionId = routingRules.intakeEnrichments[index]!.componentVersionId;
+        if (result.status === "fulfilled") enrichments[result.value.componentKey] = result.value.data;
+        else intakeEnrichmentFailures.push(componentVersionId);
+      });
+      routingInput.enrichments = enrichments;
+      matchedRules = routingRules.rules.filter((rule) => {
+        const queue = byQueueId.get(rule.queueId);
+        return queue ? queueMatches(routingInput, { ...queue, routingCriteria: rule.routingCriteria }, safeguard) : false;
+      });
+    } else {
+      intakeEnrichmentFailures = routingRules.intakeEnrichments.map((entry) => entry.componentVersionId);
+    }
+  }
+  const deterministicQueueId = matchedRules[0]?.queueId ?? null;
+  const agentDecision = routingAgent && !safeguard.requiresHuman && !deterministicQueueId
+    ? await executeRoutingAgent(db, ai, routingAgent, job.report_id, jobId, routingInput, queues)
+    : { queueId: null, accepted: false };
+  let route = selectRoute(routingInput, queues, {
+    defaultQueueId,
+    safeguardQueueId,
+    deterministicQueueId,
+    agentQueueId: agentDecision.queueId,
+    agentAccepted: agentDecision.accepted,
+  });
+  if (!route) throw new ApiError(503, "routing_policy_unavailable", "No safe active queue policy can receive this report.");
+  let aiConfiguration = await aiConfigurationForRouting(db, route.queueId, route.queueVersionId);
+  if (route.state === "ai_review" && !aiConfiguration) {
+    const selectedQueue = queues.find((queue) => queue.queueId === route!.queueId);
+    const fallback = queues.find((queue) => queue.queueId === selectedQueue?.fallbackQueueId && queue.managementMode === "human")
+      ?? queues.find((queue) => queue.queueId === defaultQueueId && queue.managementMode === "human");
+    if (!fallback) throw new ApiError(503, "routing_ai_fallback_missing", "The selected AI queue has no available human fallback.");
+    route = {
+      queueId: fallback.queueId,
+      queueVersionId: fallback.queueVersionId,
+      state: "human_review",
+      priority: Math.max(60, fallback.priority),
+      reasonCode: "ai_runtime_unavailable_human_fallback",
+      responseSlaMinutes: fallback.responseSlaMinutes,
+      safeguardReasons: [],
+    };
+  }
+  const now = isoNow();
+  const aiJobId = aiConfiguration && (route.state === "ai_review" || aiConfiguration.mode === "shadow")
+    ? `ai:${job.report_id}:${aiConfiguration.id}`
+    : null;
+  const routedQueue = queues.find((queue) => queue.queueId === route.queueId);
+  const workflowRuns = await preparePinnedWorkflowRunsForRouting(db, {
+    reportId: job.report_id,
+    installationId: job.installation_id,
+    queueId: route.queueId,
+    queueVersionId: route.queueVersionId,
+    createdAt: now,
+  });
+  const statements = [
+    db.prepare(`
+      UPDATE reports
+      SET queue_id = ?2, queue_version_id = ?3, policy_version_id = ?4, state = ?5, priority = ?6, due_at = ?7,
+          routing_rule_version_id = ?8, routing_agent_version_id = ?9, routing_reason_json = ?10,
+          routing_status = 'complete', routing_error_code = NULL, updated_at = ?11
+      WHERE id = ?1 AND state = 'received'
+    `).bind(
+      job.report_id, route.queueId, route.queueVersionId, routedQueue?.adjudicationPolicyVersionId ?? "general-policy-v1", route.state, route.priority,
+      route.responseSlaMinutes === null ? null : addMinutes(now, route.responseSlaMinutes),
+      routingRules.id,
+      routingAgent?.id ?? null,
+      canonicalJson({ reasonCode: route.reasonCode, safeguards: route.safeguardReasons, matchedRuleIds: matchedRules.map((rule) => rule.id), intakeEnrichmentFailures, routingAgentAccepted: agentDecision.accepted }),
+      now,
+    ),
+    db.prepare(`
+      INSERT OR IGNORE INTO report_state_history (
+        id, report_id, background_job_id, from_state, to_state, reason_code, actor_type, actor_id, created_at
+      ) VALUES (?1, ?2, ?3, 'received', ?4, ?5, 'system', ?6, ?7)
+    `).bind(crypto.randomUUID(), job.report_id, jobId, route.state, route.reasonCode, routingAgent?.id ?? "queue-policy-router-v2", now),
+    db.prepare(`
+      INSERT OR IGNORE INTO report_queue_assignments (
+        id, report_id, queue_id, queue_version_id, routing_rule_version_id, routing_agent_version_id,
+        assignment_kind, reason_json, assigned_by_type, assigned_by_id, assigned_at
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'initial', ?7, 'system', ?8, ?9)
+    `).bind(
+      crypto.randomUUID(), job.report_id, route.queueId, route.queueVersionId,
+      routingRules.id, routingAgent?.id ?? null,
+      canonicalJson({ reasonCode: route.reasonCode, safeguards: route.safeguardReasons, matchedRuleIds: matchedRules.map((rule) => rule.id), intakeEnrichmentFailures, routingAgentAccepted: agentDecision.accepted }),
+      routingAgent?.id ?? routingRules.id, now,
+    ),
+    db.prepare(`
+      UPDATE background_jobs
+      SET state = 'complete', last_error_code = NULL, updated_at = ?2
+      WHERE id = ?1
+    `).bind(jobId, now),
+    ...workflowRuns.statements,
+  ];
+  if (aiJobId && aiConfiguration) {
+    statements.push(db.prepare(`
+      INSERT OR IGNORE INTO background_jobs (
+        id, report_id, job_type, idempotency_key, state, payload_json, available_at,
+        created_at, updated_at, ai_config_version_id
+      ) VALUES (?1, ?2, 'resume_ai', ?1, 'pending', ?3, ?4, ?4, ?4, ?5)
+    `).bind(
+      aiJobId, job.report_id,
+      canonicalJson({ version: 1, reportId: job.report_id, configVersionId: aiConfiguration.id }),
+      now, aiConfiguration.id,
+    ));
+  }
+  await db.batch(statements);
+  return [
+    ...workflowRuns.jobs,
+    ...(aiJobId
+      ? [{ version: 1, jobId: aiJobId, type: "process_ai_report", reportId: job.report_id } satisfies AiJob]
+      : []),
+  ];
+}
+
+export type InboxCursor = {
+  priority: number;
+  receivedAt: string;
+  id: string;
+};
+
+export async function listInboxReports(
+  db: D1Database,
+  options: {
+    queueId?: string;
+    allowedQueueIds?: string[] | null;
+    state?: ReportState;
+    cursor?: InboxCursor | null;
+    limit: number;
+  },
+): Promise<{ reports: InboxReport[]; nextPosition: InboxCursor | null }> {
+  const clauses = ["1 = 1"];
+  const bindings: unknown[] = [];
+  if (options.queueId) {
+    bindings.push(options.queueId);
+    clauses.push(`r.queue_id = ?${bindings.length}`);
+  }
+  if (options.allowedQueueIds !== undefined && options.allowedQueueIds !== null) {
+    if (!options.allowedQueueIds.length) return { reports: [], nextPosition: null };
+    const placeholders = options.allowedQueueIds.map((queueId) => {
+      bindings.push(queueId);
+      return `?${bindings.length}`;
+    });
+    clauses.push(`r.queue_id IN (${placeholders.join(",")})`);
+  }
+  if (options.state) {
+    bindings.push(options.state);
+    clauses.push(`r.state = ?${bindings.length}`);
+  }
+  if (options.cursor) {
+    bindings.push(options.cursor.priority);
+    const priorityBinding = bindings.length;
+    bindings.push(options.cursor.receivedAt);
+    const receivedAtBinding = bindings.length;
+    bindings.push(options.cursor.id);
+    const idBinding = bindings.length;
+    clauses.push(`(
+      r.priority < ?${priorityBinding}
+      OR (r.priority = ?${priorityBinding} AND r.received_at > ?${receivedAtBinding})
+      OR (r.priority = ?${priorityBinding} AND r.received_at = ?${receivedAtBinding} AND r.id > ?${idBinding})
+    )`);
+  }
+  bindings.push(isoNow());
+  const atBinding = bindings.length;
+  const limit = Math.max(1, Math.min(100, options.limit));
+  bindings.push(limit + 1);
+  const limitBinding = bindings.length;
+  const result = await db.prepare(`
+    SELECT r.id, r.public_reference AS reference, r.state, r.priority, r.reason_code AS reasonCode,
+           r.queue_id AS queueId, t.target_type AS targetType, t.target_reference AS targetReference,
+           r.submitted_at AS submittedAt, r.received_at AS receivedAt, r.updated_at AS updatedAt, r.due_at AS dueAt,
+           c.reviewer_id AS claimReviewerId, c.claimed_at AS claimedAt, c.expires_at AS claimExpiresAt,
+           p.display_name AS analystDisplayName, p.avatar_url AS analystAvatarUrl,
+           p.avatar_color AS analystAvatarColor
+    FROM reports r
+    JOIN report_targets t ON t.report_id = r.id
+    LEFT JOIN review_claims c ON c.report_id = r.id AND c.expires_at > ?${atBinding}
+    LEFT JOIN analyst_profiles p ON p.actor_id = c.reviewer_id
+    WHERE ${clauses.join(" AND ")}
+    ORDER BY r.priority DESC, r.received_at ASC, r.id ASC
+    LIMIT ?${limitBinding}
+  `).bind(...bindings).all<InboxReportRow>();
+  const reports = result.results.slice(0, limit).map((row): InboxReport => ({
+    id: row.id,
+    reference: row.reference,
+    state: row.state,
+    priority: row.priority,
+    reasonCode: row.reasonCode,
+    queueId: row.queueId,
+    targetType: row.targetType,
+    targetReference: row.targetReference,
+    submittedAt: row.submittedAt,
+    receivedAt: row.receivedAt,
+    updatedAt: row.updatedAt,
+    dueAt: row.dueAt,
+    claim: row.claimReviewerId && row.claimedAt && row.claimExpiresAt ? {
+      reviewerId: row.claimReviewerId,
+      claimedAt: row.claimedAt,
+      expiresAt: row.claimExpiresAt,
+      analyst: {
+        displayName: row.analystDisplayName ?? row.claimReviewerId,
+        avatarUrl: row.analystAvatarUrl,
+        avatarColor: row.analystAvatarColor ?? analystAvatarColor(row.claimReviewerId),
+      },
+    } : null,
+  }));
+  const last = reports.at(-1);
+  return {
+    reports,
+    nextPosition: result.results.length > limit && last
+      ? { priority: last.priority, receivedAt: last.receivedAt, id: last.id }
+      : null,
+  };
+}
+
+export async function publicForm(db: D1Database, formVersionId = "general-v1"): Promise<{
+  id: string;
+  title: string;
+  description: string;
+  targetTypes: unknown[];
+  reasons: unknown[];
+  fields: unknown[];
+  consentNotice: string;
+} | null> {
+  const row = await db.prepare(`
+    SELECT id, title, description, target_types_json, reasons_json, fields_json, consent_notice
+    FROM report_form_versions
+    WHERE id = ?1 AND published_at IS NOT NULL AND retired_at IS NULL
+    LIMIT 1
+  `).bind(formVersionId).first<FormRow & { title: string; description: string }>();
+  if (!row) return null;
+  return {
+    id: row.id,
+    title: row.title,
+    description: row.description,
+    targetTypes: parseJsonArray(row.target_types_json),
+    reasons: parseJsonArray(row.reasons_json),
+    fields: parseJsonArray(row.fields_json),
+    consentNotice: row.consent_notice,
+  };
+}