create-safest-tools 0.2.0

package/template/src/report-ai.ts

@@ -0,0 +1,857 @@
+import { canonicalJson } from "./audit";
+import { evaluateAiFailurePause } from "./report-ai-quality";
+import type { AiJob, DeliveryJob, ReportState } from "./report-types";
+import type { AiMode, ValidatedAiResult } from "./report-ai-validation";
+import { validateAiResult } from "./report-ai-validation";
+
+const AI_MAX_ATTEMPTS = 3;
+const AI_RETRY_DELAYS = [30, 120, 600] as const;
+const AI_TIMEOUT_MS = 15_000;
+const AI_OUTPUT_LIMIT = 16 * 1024;
+
+export interface AiBinding {
+  run(model: string, input: Record<string, unknown>): Promise<unknown>;
+}
+
+interface AiConfigRow {
+  id: string;
+  queue_id: string;
+  queue_version_id: string | null;
+  version: number;
+  mode: AiMode;
+  enabled: number;
+  provider: "workers_ai";
+  model: string;
+  input_cost_microusd_per_million: number;
+  output_cost_microusd_per_million: number;
+  prompt_version: string;
+  policy_version_id: string;
+  eligible_form_versions_json: string;
+  eligible_sources_json: string;
+  eligible_reason_codes_json: string;
+  eligible_target_types_json: string;
+  allowed_fields_json: string;
+  allowed_outcomes_json: string;
+  allowed_action_codes_json: string;
+  allowed_template_ids_json: string;
+  confidence_threshold: number;
+  max_follow_up_turns: number;
+  max_wait_hours: number;
+  daily_report_budget: number;
+  daily_cost_budget_microusd: number;
+  quality_sample_rate: number;
+  minimum_shadow_runs: number;
+  minimum_quality_reviews: number;
+  maximum_failure_rate: number;
+  maximum_disagreement_rate: number;
+  fallback_queue_id: string;
+  pause_state: "ready" | "paused" | "budget_exhausted" | "quality_paused";
+  pause_reason: string | null;
+  paused_at: string | null;
+  published_at: string | null;
+  retired_at: string | null;
+  created_at: string;
+}
+
+interface AiContextRow extends AiConfigRow {
+  job_id: string;
+  job_state: "pending" | "enqueued" | "processing" | "complete" | "failed" | "dead_letter";
+  attempt_count: number;
+  report_id: string;
+  public_reference: string;
+  source: string;
+  report_state: ReportState;
+  reason_code: string;
+  form_version_id: string;
+  target_type: string;
+  target_reference: string;
+  signed_facts_json: string;
+  reporter_reference: string | null;
+  queue_ai_instructions: string | null;
+}
+
+interface UsageRow {
+  reports_started: number;
+  estimated_cost_microusd: number;
+}
+
+export class RetryableAiError extends Error {
+  constructor(readonly delaySeconds: number) {
+    super("AI processing failed temporarily and was scheduled for retry.");
+    this.name = "RetryableAiError";
+  }
+}
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function plusSeconds(timestamp: string, seconds: number): string {
+  return new Date(Date.parse(timestamp) + seconds * 1_000).toISOString();
+}
+
+function jsonArray(value: string): string[] {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed.filter((entry): entry is string => typeof entry === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+function jsonObject(value: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : {};
+  } catch {
+    return {};
+  }
+}
+
+function auditEvent(
+  db: D1Database,
+  input: { key: string; action: string; targetType: string; targetId: string; actorId: string; details: unknown; createdAt: 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', ?4, ?5, ?6, ?7, ?8)
+  `).bind(
+    crypto.randomUUID(), input.key, input.action, input.actorId, input.targetType, input.targetId,
+    canonicalJson(input.details), input.createdAt,
+  );
+}
+
+export async function activeAiConfiguration(db: D1Database, queueId: string, queueVersionId?: string): Promise<AiConfigRow | null> {
+  return db.prepare(`
+    SELECT * FROM ai_queue_config_versions
+    WHERE queue_id = ?1 AND (?2 IS NULL OR queue_version_id = ?2)
+      AND published_at IS NOT NULL AND retired_at IS NULL
+    ORDER BY version DESC LIMIT 1
+  `).bind(queueId, queueVersionId ?? null).first<AiConfigRow>();
+}
+
+export async function aiConfigurationForRouting(
+  db: D1Database,
+  queueId: string,
+  queueVersionId: string,
+): Promise<{ id: string; queueId: string; mode: AiMode; fallbackQueueId: string } | null> {
+  const row = await activeAiConfiguration(db, queueId, queueVersionId);
+  if (!row || row.enabled !== 1 || row.mode === "off" || row.pause_state !== "ready") return null;
+  return { id: row.id, queueId: row.queue_id, mode: row.mode, fallbackQueueId: row.fallback_queue_id };
+}
+
+const protectedContent = /\b(child|minor|underage|csam|sextortion|suicid(?:e|al)|self[- ]?harm|kill|murder|bomb|terror(?:ism|ist)|court order|law enforcement|police|imminent danger|credible threat|nude|intimate image)\b/iu;
+const humanRequest = /\b(human|person|reviewer|manual review|real person)\b/iu;
+
+export function requiresHumanFromContent(input: { details: string; messages: string[] }): string | null {
+  if (protectedContent.test(input.details)) return "protected_content_detected";
+  if (input.messages.some((message) => humanRequest.test(message))) return "reporter_requested_human";
+  return null;
+}
+
+function aiResponseSchema(allowedOutcomes: string[], policyCodes: string[], evidenceReferences: string[], templateIds: string[]) {
+  return {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      outcome: { type: "string", enum: allowedOutcomes },
+      policy_code: { anyOf: [{ type: "string", enum: policyCodes }, { type: "null" }] },
+      evidence_references: { type: "array", maxItems: 20, items: { type: "string", enum: evidenceReferences.length ? evidenceReferences : ["none"] } },
+      summary: { type: "string", maxLength: 500 },
+      confidence: { type: "number", minimum: 0, maximum: 1 },
+      uncertain: { type: "boolean" },
+      message: {
+        anyOf: [
+          { type: "null" },
+          {
+            type: "object", additionalProperties: false,
+            properties: {
+              template_id: { type: "string", enum: templateIds },
+              variables: { type: "object", additionalProperties: { type: "string", maxLength: 160 } },
+            },
+            required: ["template_id", "variables"],
+          },
+        ],
+      },
+      action: { type: "null" },
+      escalation: { anyOf: [{ type: "string", maxLength: 100 }, { type: "null" }] },
+    },
+    required: ["outcome", "policy_code", "evidence_references", "summary", "confidence", "uncertain", "message", "action", "escalation"],
+  };
+}
+
+function unwrapAiResponse(value: unknown): { output: unknown; inputUnits: number | null; outputUnits: number | null } {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("ai_response_invalid");
+  const response = value as Record<string, unknown>;
+  const usage = response.usage && typeof response.usage === "object" && !Array.isArray(response.usage)
+    ? response.usage as Record<string, unknown> : {};
+  let output = response.response;
+  if (output === undefined && Array.isArray(response.choices)) {
+    const choice = response.choices[0] as Record<string, unknown> | undefined;
+    const message = choice?.message && typeof choice.message === "object" ? choice.message as Record<string, unknown> : null;
+    output = message?.content;
+  }
+  if (typeof output === "string") output = JSON.parse(output);
+  const encoded = canonicalJson(output);
+  if (new TextEncoder().encode(encoded).byteLength > AI_OUTPUT_LIMIT) throw new Error("ai_output_too_large");
+  const unit = (candidate: unknown): number | null => typeof candidate === "number" && Number.isInteger(candidate) && candidate >= 0 ? candidate : null;
+  return {
+    output,
+    inputUnits: unit(usage.prompt_tokens ?? usage.input_tokens ?? usage.input_units),
+    outputUnits: unit(usage.completion_tokens ?? usage.output_tokens ?? usage.output_units),
+  };
+}
+
+function costMicrousd(config: AiConfigRow, inputUnits: number | null, outputUnits: number | null): number {
+  return Math.max(0, Math.round(
+    (inputUnits ?? 0) * config.input_cost_microusd_per_million / 1_000_000
+      + (outputUnits ?? 0) * config.output_cost_microusd_per_million / 1_000_000,
+  ));
+}
+
+function retryDelay(attempt: number): number {
+  return AI_RETRY_DELAYS[Math.min(AI_RETRY_DELAYS.length - 1, Math.max(0, attempt - 1))] ?? 600;
+}
+
+function randomSample(rate: number): boolean {
+  if (rate <= 0) return false;
+  if (rate >= 1) return true;
+  const values = new Uint32Array(1);
+  crypto.getRandomValues(values);
+  return (values[0] ?? 0) / 0x1_0000_0000 < rate;
+}
+
+async function aiContext(db: D1Database, jobId: string): Promise<AiContextRow | null> {
+  return db.prepare(`
+    SELECT j.id AS job_id, j.state AS job_state, j.attempt_count, r.id AS report_id,
+      r.public_reference, r.source, r.state AS report_state, r.reason_code, r.form_version_id,
+      t.target_type, t.target_reference, t.signed_facts_json,
+      p.reference AS reporter_reference, qv.ai_instructions AS queue_ai_instructions, c.*
+    FROM background_jobs j
+    JOIN reports r ON r.id = j.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 = 'reporter'
+    JOIN ai_queue_config_versions c ON c.id = j.ai_config_version_id
+    LEFT JOIN queue_versions qv ON qv.id = c.queue_version_id
+    WHERE j.id = ?1 AND j.job_type = 'resume_ai'
+    LIMIT 1
+  `).bind(jobId).first<AiContextRow>();
+}
+
+async function routeToHuman(db: D1Database, context: AiContextRow, reason: string, jobState: "complete" | "dead_letter" = "complete"): Promise<void> {
+  const createdAt = now();
+  const expectedHumanMode = reason === "ai_shadow_complete" || reason === "ai_assist_complete";
+  const transitionsToHuman = context.report_state === "ai_review";
+  await db.batch([
+    ...(transitionsToHuman ? [
+      db.prepare(`
+        UPDATE reports SET state = 'human_review', queue_id = ?2,
+          queue_version_id = (SELECT active_version_id FROM queue_definitions WHERE id = ?2),
+          priority = MAX(priority, 60), updated_at = ?3
+        WHERE id = ?1 AND state = 'ai_review'
+      `).bind(context.report_id, context.fallback_queue_id, createdAt),
+      db.prepare(`
+        INSERT 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, 'ai_review', 'human_review', ?4, 'system', 'bounded-ai-v2', ?5)
+      `).bind(crypto.randomUUID(), context.report_id, context.job_id, reason, createdAt),
+    ] : []),
+    db.prepare(`UPDATE background_jobs SET state = ?2, last_error_code = ?3, updated_at = ?4 WHERE id = ?1`)
+      .bind(context.job_id, jobState, reason.slice(0, 100), createdAt),
+    ...(!expectedHumanMode && transitionsToHuman ? [usageStatement(db, context.id, { escalated: 1 }, createdAt)] : []),
+    auditEvent(db, {
+      key: `ai-fallback:${context.job_id}:${reason}`,
+      action: "ai.report_escalated",
+      actorId: "bounded-ai-v2",
+      targetType: "report",
+      targetId: context.report_id,
+      details: { aiConfigVersionId: context.id, queueVersionId: context.queue_version_id, reason, fallbackQueueId: context.fallback_queue_id, reportAlreadyHuman: !transitionsToHuman },
+      createdAt,
+    }),
+  ]);
+}
+
+function usageStatement(
+  db: D1Database,
+  configId: string,
+  fields: {
+    started?: number; resolved?: number; escalated?: number; failures?: number; cost?: number;
+    eligible?: number; waiting?: number; humanRequests?: number; appeals?: number; reversals?: number;
+    invalidOutputs?: number; providerErrors?: number; timeouts?: number;
+  },
+  at: string,
+): D1PreparedStatement {
+  return db.prepare(`
+    INSERT INTO ai_usage_daily (
+      usage_date, config_version_id, reports_started, reports_resolved, reports_escalated,
+      failures, estimated_cost_microusd, updated_at, eligible_reports, waiting_for_reporter,
+      human_review_requests, appeals_filed, appeal_reversals, invalid_outputs, provider_errors, timeouts
+    ) VALUES (substr(?1, 1, 10), ?2, ?3, ?4, ?5, ?6, ?7, ?1, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15)
+    ON CONFLICT(usage_date, config_version_id) DO UPDATE SET
+      reports_started = reports_started + excluded.reports_started,
+      reports_resolved = reports_resolved + excluded.reports_resolved,
+      reports_escalated = reports_escalated + excluded.reports_escalated,
+      failures = failures + excluded.failures,
+      estimated_cost_microusd = estimated_cost_microusd + excluded.estimated_cost_microusd,
+      eligible_reports = eligible_reports + excluded.eligible_reports,
+      waiting_for_reporter = waiting_for_reporter + excluded.waiting_for_reporter,
+      human_review_requests = human_review_requests + excluded.human_review_requests,
+      appeals_filed = appeals_filed + excluded.appeals_filed,
+      appeal_reversals = appeal_reversals + excluded.appeal_reversals,
+      invalid_outputs = invalid_outputs + excluded.invalid_outputs,
+      provider_errors = provider_errors + excluded.provider_errors,
+      timeouts = timeouts + excluded.timeouts,
+      updated_at = excluded.updated_at
+  `).bind(
+    at, configId, fields.started ?? 0, fields.resolved ?? 0, fields.escalated ?? 0,
+    fields.failures ?? 0, fields.cost ?? 0, fields.eligible ?? 0, fields.waiting ?? 0,
+    fields.humanRequests ?? 0, fields.appeals ?? 0, fields.reversals ?? 0,
+    fields.invalidOutputs ?? 0, fields.providerErrors ?? 0, fields.timeouts ?? 0,
+  );
+}
+
+async function renderTemplate(db: D1Database, templateId: string, variables: Record<string, string>): Promise<string> {
+  const template = await db.prepare(`
+    SELECT body_template, variables_schema_json FROM message_template_versions
+    WHERE id = ?1 AND automation_allowed = 1 AND audience = 'reporter' AND published_at IS NOT NULL LIMIT 1
+  `).bind(templateId).first<{ body_template: string; variables_schema_json: string }>();
+  if (!template) throw new Error("ai_template_unavailable");
+  const schema = jsonObject(template.variables_schema_json);
+  if (Object.keys(variables).some((key) => !(key in schema)) || Object.keys(schema).some((key) => !(key in variables))) {
+    throw new Error("ai_template_variables_invalid");
+  }
+  let body = template.body_template;
+  for (const [key, value] of Object.entries(variables)) {
+    const rule = schema[key] as Record<string, unknown>;
+    const minimum = typeof rule?.minLength === "number" ? rule.minLength : 1;
+    const maximum = typeof rule?.maxLength === "number" ? rule.maxLength : 160;
+    if (value.length < minimum || value.length > maximum) throw new Error("ai_template_variables_invalid");
+    body = body.replaceAll(`{{${key}}}`, value);
+  }
+  if (/\{\{[^}]+\}\}/u.test(body) || body.length > 1_000) throw new Error("ai_template_render_invalid");
+  return body;
+}
+
+async function saveAiResult(
+  db: D1Database,
+  context: AiContextRow,
+  runId: string,
+  result: ValidatedAiResult | null,
+  errors: string[],
+  output: unknown,
+  status: "succeeded" | "invalid" | "escalated",
+  units: { input: number | null; output: number | null; cost: number },
+): Promise<void> {
+  const finishedAt = now();
+  await db.batch([
+    db.prepare(`
+      UPDATE ai_runs SET status = ?2, output_json = ?3, error_code = ?4, finished_at = ?5,
+        input_units = ?6, output_units = ?7, estimated_cost_microusd = ?8 WHERE id = ?1
+    `).bind(runId, status, canonicalJson(output), errors[0] ?? null, finishedAt, units.input, units.output, units.cost),
+    db.prepare(`
+      INSERT OR REPLACE INTO ai_results (
+        id, ai_run_id, outcome, policy_code, evidence_references_json, summary, confidence, uncertain,
+        message_template_id, message_variables_json, action_code, escalation_code,
+        validation_state, validation_errors_json, created_at
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15)
+    `).bind(
+      crypto.randomUUID(), runId, result?.outcome ?? "invalid", result?.policyCode ?? null,
+      canonicalJson(result?.evidenceReferences ?? []), result?.summary ?? "Invalid structured output",
+      result?.confidence ?? null, result?.uncertain ? 1 : 0, result?.message?.templateId ?? null,
+      result?.message ? canonicalJson(result.message.variables) : null, result?.actionCode ?? null,
+      result?.escalationCode ?? null, errors.length ? "invalid" : "valid", canonicalJson(errors), finishedAt,
+    ),
+    usageStatement(db, context.id, { cost: units.cost }, finishedAt),
+  ]);
+}
+
+async function terminalAiFailure(db: D1Database, context: AiContextRow, runId: string, errorCode: string): Promise<void> {
+  const finishedAt = now();
+  const fingerprint = `ai-runtime:${context.job_id}`;
+  await db.batch([
+    db.prepare(`UPDATE ai_runs SET status = 'failed', error_code = ?2, finished_at = ?3 WHERE id = ?1`).bind(runId, errorCode, finishedAt),
+    db.prepare(`
+      UPDATE reports SET state = 'human_review', queue_id = ?2,
+        queue_version_id = (SELECT active_version_id FROM queue_definitions WHERE id = ?2), priority = MAX(priority, 60),
+        routing_error_code = ?3, updated_at = ?4 WHERE id = ?1 AND state = 'ai_review'
+    `).bind(context.report_id, context.fallback_queue_id, errorCode, finishedAt),
+    db.prepare(`UPDATE background_jobs SET state = 'dead_letter', last_error_code = ?2, updated_at = ?3 WHERE id = ?1`)
+      .bind(context.job_id, errorCode, finishedAt),
+    db.prepare(`
+      INSERT INTO dead_letter_items (
+        id, fingerprint, source_queue, source_message_id, job_type, job_id, report_id,
+        state, error_code, details_json, first_seen_at, last_seen_at
+      ) VALUES (?1, ?2, 'ai-runtime', ?3, 'process_ai_report', ?3, ?4, 'open', ?5, ?6, ?7, ?7)
+      ON CONFLICT(fingerprint) DO UPDATE SET occurrence_count = occurrence_count + 1,
+        state = 'open', error_code = excluded.error_code, details_json = excluded.details_json,
+        last_seen_at = excluded.last_seen_at, resolved_at = NULL
+    `).bind(
+      crypto.randomUUID(), fingerprint, context.job_id, context.report_id, errorCode,
+      canonicalJson({ version: 1, configVersionId: context.id, fallbackQueueId: context.fallback_queue_id }), finishedAt,
+    ),
+    db.prepare(`
+      INSERT INTO report_state_history (id, report_id, background_job_id, from_state, to_state, reason_code, actor_type, actor_id, created_at)
+      SELECT ?1, ?2, ?3, 'ai_review', 'human_review', ?4, 'system', 'bounded-ai-v2', ?5
+      WHERE ?6 = 'ai_review'
+    `).bind(crypto.randomUUID(), context.report_id, context.job_id, errorCode, finishedAt, context.report_state),
+    usageStatement(db, context.id, {
+      failures: 1,
+      escalated: 1,
+      ...(errorCode === "ai_timeout" ? { timeouts: 1 } : { providerErrors: 1 }),
+    }, finishedAt),
+    auditEvent(db, {
+      key: `ai-terminal-failure:${context.job_id}`,
+      action: "ai.processing_failed_to_human",
+      actorId: "bounded-ai-v2",
+      targetType: "report",
+      targetId: context.report_id,
+      details: { aiConfigVersionId: context.id, errorCode, fallbackQueueId: context.fallback_queue_id },
+      createdAt: finishedAt,
+    }),
+  ]);
+  await evaluateAiFailurePause(db, context.id);
+}
+
+async function providerFailure(db: D1Database, context: AiContextRow, runId: string, errorCode: string): Promise<never | void> {
+  if (context.attempt_count >= AI_MAX_ATTEMPTS) return terminalAiFailure(db, context, runId, errorCode);
+  const failedAt = now();
+  const delay = retryDelay(context.attempt_count);
+  await db.batch([
+    db.prepare(`UPDATE ai_runs SET status = 'failed', error_code = ?2, finished_at = ?3 WHERE id = ?1`).bind(runId, errorCode, failedAt),
+    db.prepare(`
+      UPDATE background_jobs SET state = 'failed', available_at = ?2, last_error_code = ?3, updated_at = ?4
+      WHERE id = ?1
+    `).bind(context.job_id, plusSeconds(failedAt, delay), errorCode, failedAt),
+    usageStatement(db, context.id, {
+      failures: 1,
+      ...(errorCode === "ai_timeout" ? { timeouts: 1 } : { providerErrors: 1 }),
+    }, failedAt),
+  ]);
+  throw new RetryableAiError(delay);
+}
+
+export interface AiProcessOptions {
+  notificationEnabled: boolean;
+}
+
+export async function processAiJob(
+  db: D1Database,
+  ai: AiBinding | undefined,
+  job: AiJob,
+  options: AiProcessOptions,
+): Promise<DeliveryJob[]> {
+  const claimedAt = now();
+  const claim = await db.prepare(`
+    UPDATE background_jobs SET state = 'processing', attempt_count = attempt_count + 1, updated_at = ?2
+    WHERE id = ?1 AND job_type = 'resume_ai' AND available_at <= ?2
+      AND (state IN ('pending', 'enqueued', 'failed') OR (state = 'processing' AND updated_at <= ?3))
+  `).bind(job.jobId, claimedAt, plusSeconds(claimedAt, -60)).run();
+  if ((claim.meta.changes ?? 0) < 1) return [];
+  const context = await aiContext(db, job.jobId);
+  if (!context) throw new Error("AI job context does not exist.");
+  const expectedReportState = context.mode === "shadow" ? "human_review" : "ai_review";
+  if (context.report_state !== expectedReportState) {
+    await db.prepare(`UPDATE background_jobs SET state = 'complete', updated_at = ?2 WHERE id = ?1`).bind(job.jobId, claimedAt).run();
+    return [];
+  }
+  if (context.attempt_count === 1) await db.batch([usageStatement(db, context.id, { eligible: 1 }, claimedAt)]);
+  if (context.enabled !== 1 || context.mode === "off" || context.pause_state !== "ready" || !ai) {
+    await routeToHuman(db, context, !ai ? "ai_binding_unavailable" : "ai_configuration_not_active");
+    return [];
+  }
+  const usage = await db.prepare(`
+    SELECT reports_started, estimated_cost_microusd FROM ai_usage_daily
+    WHERE usage_date = substr(?1, 1, 10) AND config_version_id = ?2 LIMIT 1
+  `).bind(claimedAt, context.id).first<UsageRow>();
+  if ((usage?.reports_started ?? 0) >= context.daily_report_budget
+    || (usage?.estimated_cost_microusd ?? 0) >= context.daily_cost_budget_microusd) {
+    await db.batch([
+      db.prepare(`
+        UPDATE ai_queue_config_versions SET pause_state = 'budget_exhausted',
+          pause_reason = 'daily_budget_exhausted', paused_at = ?2 WHERE id = ?1
+      `).bind(context.id, claimedAt),
+      auditEvent(db, {
+        key: `ai-budget:${context.id}:${claimedAt.slice(0, 10)}`,
+        action: "ai.queue_budget_exhausted",
+        actorId: "bounded-ai-v1",
+        targetType: "ai_queue_configuration",
+        targetId: context.id,
+        details: { usageDate: claimedAt.slice(0, 10), fallbackQueueId: context.fallback_queue_id },
+        createdAt: claimedAt,
+      }),
+    ]);
+    await routeToHuman(db, context, "ai_budget_exhausted");
+    return [];
+  }
+
+  const answersResult = await db.prepare(`SELECT field_key, value_json FROM report_answers WHERE report_id = ?1 ORDER BY field_key`)
+    .bind(context.report_id).all<{ field_key: string; value_json: string }>();
+  const evidenceResult = await db.prepare(`SELECT reference FROM evidence_references WHERE report_id = ?1 ORDER BY created_at, id LIMIT 20`)
+    .bind(context.report_id).all<{ reference: string }>();
+  const messagesResult = await db.prepare(`
+    SELECT body FROM case_messages WHERE report_id = ?1 AND audience = 'reporter' AND direction = 'inbound'
+    ORDER BY created_at, id LIMIT 20
+  `).bind(context.report_id).all<{ body: string }>();
+  const findingsResult = await db.prepare(`
+    SELECT f.finding_type AS findingType, f.data_json AS dataJson
+    FROM findings f
+    WHERE f.report_id = ?1 AND f.status = 'available'
+      AND (f.expires_at IS NULL OR f.expires_at > ?2)
+      AND NOT EXISTS (
+        SELECT 1 FROM findings newer
+        WHERE newer.report_id = f.report_id AND newer.finding_type = f.finding_type
+          AND newer.status = 'available' AND (newer.expires_at IS NULL OR newer.expires_at > ?2)
+          AND (newer.created_at > f.created_at OR (newer.created_at = f.created_at AND newer.id > f.id))
+      )
+    ORDER BY f.finding_type, f.created_at DESC, f.id DESC
+  `).bind(context.report_id, claimedAt).all<{ findingType: string; dataJson: string }>();
+  const answers = Object.fromEntries(answersResult.results.map((row) => {
+    try { return [row.field_key, JSON.parse(row.value_json)]; } catch { return [row.field_key, null]; }
+  }));
+  const details = typeof answers.details === "string" ? answers.details : "";
+  const forcedHumanReason = requiresHumanFromContent({ details, messages: messagesResult.results.map((row) => row.body) });
+  if (forcedHumanReason) {
+    await routeToHuman(db, context, forcedHumanReason);
+    return [];
+  }
+  const trustedFacts = jsonObject(context.signed_facts_json);
+  if (["protected_category", "minor_involved", "high_impact", "identity_missing", "evidence_unavailable", "trusted_facts_conflict"]
+    .some((key) => trustedFacts[key] === true)) {
+    await routeToHuman(db, context, "protected_trusted_fact");
+    return [];
+  }
+  const policy = await db.prepare(`SELECT rules_json FROM policy_versions WHERE id = ?1 AND published_at IS NOT NULL LIMIT 1`)
+    .bind(context.policy_version_id).first<{ rules_json: string }>();
+  const policyRules = policy ? (() => { try { const value: unknown = JSON.parse(policy.rules_json); return Array.isArray(value) ? value : []; } catch { return []; } })() : [];
+  const policyCodes = policyRules.map((rule) => rule && typeof rule === "object" && !Array.isArray(rule) ? (rule as Record<string, unknown>).code : null)
+    .filter((code): code is string => typeof code === "string");
+  if (!policyCodes.length) {
+    await routeToHuman(db, context, "ai_policy_unavailable");
+    return [];
+  }
+  const allowedFields = new Set(jsonArray(context.allowed_fields_json));
+  const evidenceReferences = evidenceResult.results.map((row) => row.reference);
+  const enrichments = Object.fromEntries(findingsResult.results.map((row) => [row.findingType, jsonObject(row.dataJson)]));
+  const modelCase = {
+    allegation: context.reason_code,
+    ...(allowedFields.has("target.type") ? { target_type: context.target_type } : {}),
+    ...(allowedFields.has("answers.details") ? { details } : {}),
+    ...(allowedFields.has("evidence.references") ? { evidence_references: evidenceReferences } : {}),
+    ...(allowedFields.has("enrichments") ? { enrichments } : {}),
+  };
+  const inputReferences = {
+    fields: Object.keys(modelCase),
+    evidenceReferences: allowedFields.has("evidence.references") ? evidenceReferences : [],
+    messageCount: messagesResult.results.length,
+  };
+  const runId = crypto.randomUUID();
+  await db.batch([
+    db.prepare(`
+      INSERT INTO ai_runs (
+        id, report_id, background_job_id, config_version_id, mode, provider, model,
+        prompt_version, policy_version_id, status, input_references_json, started_at
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, 'running', ?10, ?11)
+      ON CONFLICT(background_job_id) DO UPDATE SET status = 'running', error_code = NULL,
+        output_json = NULL, started_at = excluded.started_at, finished_at = NULL
+    `).bind(
+      runId, context.report_id, context.job_id, context.id, context.mode, context.provider, context.model,
+      context.prompt_version, context.policy_version_id, canonicalJson(inputReferences), claimedAt,
+    ),
+    ...(context.attempt_count === 1 ? [usageStatement(db, context.id, { started: 1 }, claimedAt)] : []),
+  ]);
+  const storedRun = await db.prepare(`SELECT id FROM ai_runs WHERE background_job_id = ?1 LIMIT 1`)
+    .bind(context.job_id).first<{ id: string }>();
+  if (!storedRun) throw new Error("AI run was not created.");
+
+  const allowedOutcomes = jsonArray(context.allowed_outcomes_json);
+  const allowedTemplates = jsonArray(context.allowed_template_ids_json);
+  let providerResult: unknown;
+  try {
+    providerResult = await Promise.race([
+      ai.run(context.model, {
+        messages: [
+          {
+            role: "system",
+            content: `You are a bounded safety workflow. Use only the supplied case, enrichment data, and policy codes. Never infer hidden facts. Escalate if uncertain. Customer queue instructions: ${context.queue_ai_instructions ?? "Escalate to a human."} Return only the requested structured object. Configuration version: ${context.id}.`,
+          },
+          {
+            role: "user",
+            content: canonicalJson({ case: modelCase, policy_codes: policyCodes, allowed_outcomes: allowedOutcomes, approved_templates: allowedTemplates }),
+          },
+        ],
+        response_format: {
+          type: "json_schema",
+          json_schema: aiResponseSchema(allowedOutcomes, policyCodes, evidenceReferences, allowedTemplates),
+        },
+      }),
+      new Promise<never>((_, reject) => setTimeout(() => reject(new Error("ai_timeout")), AI_TIMEOUT_MS)),
+    ]);
+  } catch (error) {
+    const errorCode = error instanceof Error && error.message === "ai_timeout" ? "ai_timeout" : "ai_provider_error";
+    await providerFailure(db, context, storedRun.id, errorCode);
+    return [];
+  }
+  let unwrapped: ReturnType<typeof unwrapAiResponse>;
+  try {
+    unwrapped = unwrapAiResponse(providerResult);
+  } catch {
+    await providerFailure(db, context, storedRun.id, "ai_response_invalid");
+    return [];
+  }
+  const estimatedCost = costMicrousd(context, unwrapped.inputUnits, unwrapped.outputUnits);
+  const validation = validateAiResult(unwrapped.output, {
+    allowedOutcomes: new Set(allowedOutcomes),
+    allowedPolicyCodes: new Set(policyCodes),
+    allowedEvidenceReferences: new Set(evidenceReferences),
+    allowedTemplateIds: new Set(allowedTemplates),
+    allowedActionCodes: new Set(jsonArray(context.allowed_action_codes_json)),
+    confidenceThreshold: context.confidence_threshold,
+  });
+  if (!validation.result) {
+    await saveAiResult(db, context, storedRun.id, null, validation.errors, unwrapped.output, "invalid", {
+      input: unwrapped.inputUnits, output: unwrapped.outputUnits, cost: estimatedCost,
+    });
+    await db.batch([usageStatement(db, context.id, { failures: 1, invalidOutputs: 1 }, now())]);
+    await evaluateAiFailurePause(db, context.id);
+    await routeToHuman(db, context, "ai_output_invalid");
+    return [];
+  }
+  const result = validation.result;
+  if (context.mode === "shadow" || context.mode === "assist") {
+    await saveAiResult(db, context, storedRun.id, result, [], unwrapped.output, "succeeded", {
+      input: unwrapped.inputUnits, output: unwrapped.outputUnits, cost: estimatedCost,
+    });
+    if (context.mode === "shadow") {
+      await db.prepare(`
+        INSERT OR IGNORE INTO ai_quality_samples (id, ai_run_id, report_id, sample_reason, state, selected_at)
+        VALUES (?1, ?2, ?3, 'shadow_comparison', 'pending', ?4)
+      `).bind(crypto.randomUUID(), storedRun.id, context.report_id, now()).run();
+    }
+    await routeToHuman(db, context, context.mode === "shadow" ? "ai_shadow_complete" : "ai_assist_complete");
+    return [];
+  }
+  if (result.uncertain || result.outcome === "escalate_to_human" || result.actionCode) {
+    await saveAiResult(db, context, storedRun.id, result, [], unwrapped.output, "escalated", {
+      input: unwrapped.inputUnits, output: unwrapped.outputUnits, cost: estimatedCost,
+    });
+    await routeToHuman(db, context, result.actionCode ? "ai_action_requires_human" : result.escalationCode ?? "ai_uncertain");
+    return [];
+  }
+
+  const finishedAt = now();
+  const decisionId = crypto.randomUUID();
+  const messageId = crypto.randomUUID();
+  const noticeId = crypto.randomUUID();
+  const notificationId = crypto.randomUUID();
+  let templateId: string;
+  let variables: Record<string, string>;
+  let nextState: ReportState;
+  if (result.outcome === "insufficient_information") {
+    const followUps = await db.prepare(`
+      SELECT COUNT(*) AS count FROM case_messages
+      WHERE report_id = ?1 AND sender_type = 'ai' AND template_version_id = 'ai-more-context-v1'
+    `).bind(context.report_id).first<{ count: number }>();
+    if (Number(followUps?.count ?? 0) >= context.max_follow_up_turns) {
+      await saveAiResult(db, context, storedRun.id, result, [], unwrapped.output, "escalated", {
+        input: unwrapped.inputUnits, output: unwrapped.outputUnits, cost: estimatedCost,
+      });
+      await routeToHuman(db, context, "ai_follow_up_limit_reached");
+      return [];
+    }
+    if (!result.message || result.message.templateId !== "ai-more-context-v1") {
+      await saveAiResult(db, context, storedRun.id, result, ["follow_up_template_invalid"], unwrapped.output, "invalid", {
+        input: unwrapped.inputUnits, output: unwrapped.outputUnits, cost: estimatedCost,
+      });
+      await db.batch([usageStatement(db, context.id, { failures: 1, invalidOutputs: 1 }, now())]);
+      await evaluateAiFailurePause(db, context.id);
+      await routeToHuman(db, context, "ai_output_invalid");
+      return [];
+    }
+    templateId = result.message.templateId;
+    variables = result.message.variables;
+    nextState = "awaiting_reporter";
+  } else if (result.outcome === "no_violation_found") {
+    templateId = "ai-no-violation-v1";
+    variables = { policy_code: result.policyCode ?? "the selected policy" };
+    nextState = "resolved_by_ai";
+  } else if (result.outcome === "out_of_scope") {
+    templateId = "ai-out-of-scope-v1";
+    variables = { policy_code: result.policyCode ?? "the selected policy" };
+    nextState = "resolved_by_ai";
+  } else {
+    await saveAiResult(db, context, storedRun.id, result, ["autonomous_outcome_requires_human"], unwrapped.output, "invalid", {
+      input: unwrapped.inputUnits, output: unwrapped.outputUnits, cost: estimatedCost,
+    });
+    await db.batch([usageStatement(db, context.id, { failures: 1, invalidOutputs: 1 }, now())]);
+    await evaluateAiFailurePause(db, context.id);
+    await routeToHuman(db, context, "ai_output_invalid");
+    return [];
+  }
+  let renderedBody: string;
+  try {
+    renderedBody = await renderTemplate(db, templateId, variables);
+  } catch {
+    await saveAiResult(db, context, storedRun.id, result, ["template_render_failed"], unwrapped.output, "invalid", {
+      input: unwrapped.inputUnits, output: unwrapped.outputUnits, cost: estimatedCost,
+    });
+    await db.batch([usageStatement(db, context.id, { failures: 1, invalidOutputs: 1 }, now())]);
+    await evaluateAiFailurePause(db, context.id);
+    await routeToHuman(db, context, "ai_template_failed");
+    return [];
+  }
+  await saveAiResult(db, context, storedRun.id, result, [], unwrapped.output, "succeeded", {
+    input: unwrapped.inputUnits, output: unwrapped.outputUnits, cost: estimatedCost,
+  });
+  const statements: D1PreparedStatement[] = [
+    db.prepare(`
+      UPDATE reports SET state = ?2, queue_id = ?3, resolved_at = ?4, updated_at = ?5 WHERE id = ?1 AND state = 'ai_review'
+    `).bind(
+      context.report_id, nextState, nextState === "awaiting_reporter" ? context.queue_id : null,
+      nextState === "resolved_by_ai" ? finishedAt : null, finishedAt,
+    ),
+    db.prepare(`
+      INSERT 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, 'ai_review', ?4, ?5, 'ai', ?6, ?7)
+    `).bind(crypto.randomUUID(), context.report_id, context.job_id, nextState, `ai_${result.outcome}`, context.id, finishedAt),
+    db.prepare(`UPDATE background_jobs SET state = 'complete', last_error_code = NULL, updated_at = ?2 WHERE id = ?1`).bind(context.job_id, finishedAt),
+    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', 'ai', ?3, ?4, ?5, 1, ?6, ?7, ?8)
+    `).bind(
+      messageId, context.report_id, context.id, renderedBody, templateId,
+      options.notificationEnabled ? "queued" : "suppressed", finishedAt, `ai-message:${storedRun.id}`,
+    ),
+    usageStatement(db, context.id, nextState === "resolved_by_ai" ? { resolved: 1 } : { waiting: 1 }, finishedAt),
+    auditEvent(db, {
+      key: `ai-outcome:${storedRun.id}`,
+      action: nextState === "resolved_by_ai" ? "ai.report_resolved" : "ai.reporter_information_requested",
+      actorId: context.id,
+      targetType: "report",
+      targetId: context.report_id,
+      details: { aiRunId: storedRun.id, outcome: result.outcome, policyCode: result.policyCode, templateId },
+      createdAt: finishedAt,
+    }),
+  ];
+  if (nextState === "resolved_by_ai") {
+    statements.push(db.prepare(`
+      INSERT INTO decisions (
+        id, report_id, decision_code, policy_version_id, policy_code, rationale,
+        evidence_references_json, maker_type, maker_id, queue_version_id, ai_run_id,
+        proposed_action_code, created_at, idempotency_key
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, 'ai', ?8, ?9, ?10, NULL, ?11, ?12)
+    `).bind(
+      decisionId, context.report_id, result.outcome, context.policy_version_id, result.policyCode,
+      result.summary, canonicalJson(result.evidenceReferences), context.id, context.queue_version_id, storedRun.id,
+      finishedAt, `ai-decision:${storedRun.id}`,
+    ));
+    if (randomSample(context.quality_sample_rate)) {
+      statements.push(db.prepare(`
+        INSERT OR IGNORE INTO ai_quality_samples (id, ai_run_id, report_id, sample_reason, state, selected_at)
+        VALUES (?1, ?2, ?3, 'blind_random_sample', 'pending', ?4)
+      `).bind(crypto.randomUUID(), storedRun.id, context.report_id, finishedAt));
+    }
+  }
+  statements.push(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, 'reporter', ?4, ?5, ?6, ?7, ?7, ?8, ?9)
+  `).bind(
+    noticeId, context.report_id, nextState === "resolved_by_ai" ? decisionId : null, templateId, renderedBody,
+    options.notificationEnabled ? "queued" : "suppressed", finishedAt, `ai-notice:${storedRun.id}`, messageId,
+  ));
+  const jobs: DeliveryJob[] = [];
+  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: nextState === "resolved_by_ai" ? "report.outcome.available" : "report.message.available",
+      notification_id: notificationId,
+      report_reference: context.public_reference,
+      ...(context.reporter_reference ? { recipient_reference: context.reporter_reference } : {}),
+      audience: "reporter",
+      message: renderedBody,
+    }), finishedAt));
+    jobs.push({ version: 1, jobId: `notification:${notificationId}`, type: "deliver_notification", outboxId: notificationId });
+  }
+  await db.batch(statements);
+  return jobs;
+}
+
+export async function pendingAiJobs(db: D1Database, limit = 50): Promise<AiJob[]> {
+  const at = now();
+  const result = await db.prepare(`
+    SELECT id, report_id FROM background_jobs
+    WHERE job_type = 'resume_ai' AND available_at <= ?1
+      AND (state IN ('pending', 'failed') OR (state = 'processing' AND updated_at <= ?2))
+    ORDER BY available_at, id LIMIT ?3
+  `).bind(at, plusSeconds(at, -60), Math.max(1, Math.min(100, limit))).all<{ id: string; report_id: string }>();
+  return result.results.map((row) => ({ version: 1, jobId: row.id, type: "process_ai_report", reportId: row.report_id }));
+}
+
+export async function escalateExpiredAiWaits(db: D1Database, limit = 50): Promise<number> {
+  const expired = await db.prepare(`
+    SELECT r.id AS report_id, r.queue_id, r.queue_version_id, c.id AS config_id,
+      c.fallback_queue_id, fallback.active_version_id AS fallback_version_id
+    FROM reports r
+    JOIN ai_queue_config_versions c ON c.queue_version_id = r.queue_version_id
+    JOIN queue_definitions fallback ON fallback.id = c.fallback_queue_id
+    JOIN queue_versions fallback_version ON fallback_version.id = fallback.active_version_id
+    WHERE r.state = 'awaiting_reporter' AND c.enabled = 1 AND c.mode = 'autonomous_low_priority'
+      AND fallback.status = 'active' AND fallback_version.management_mode = 'human'
+      AND julianday(r.updated_at) + (c.max_wait_hours / 24.0) <= julianday(?1)
+    ORDER BY r.updated_at, r.id LIMIT ?2
+  `).bind(now(), Math.max(1, Math.min(100, limit))).all<{
+    report_id: string; queue_id: string; queue_version_id: string; config_id: string;
+    fallback_queue_id: string; fallback_version_id: string;
+  }>();
+  for (const report of expired.results) {
+    const createdAt = now();
+    await db.batch([
+      db.prepare(`
+        UPDATE reports SET state = 'human_review', queue_id = ?2, queue_version_id = ?3,
+          priority = MAX(priority, 65), updated_at = ?4
+        WHERE id = ?1 AND state = 'awaiting_reporter'
+      `).bind(report.report_id, report.fallback_queue_id, report.fallback_version_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, 'awaiting_reporter', 'human_review', 'ai_reporter_wait_expired',
+          'system', 'bounded-ai-v2', ?3)
+      `).bind(crypto.randomUUID(), report.report_id, createdAt),
+      usageStatement(db, report.config_id, { escalated: 1 }, createdAt),
+      auditEvent(db, {
+        key: `ai-wait-expired:${report.report_id}:${report.queue_version_id}`,
+        action: "ai.reporter_wait_expired_to_human",
+        actorId: "bounded-ai-v2",
+        targetType: "report",
+        targetId: report.report_id,
+        details: { queueId: report.queue_id, queueVersionId: report.queue_version_id, fallbackQueueId: report.fallback_queue_id },
+        createdAt,
+      }),
+    ]);
+  }
+  return expired.results.length;
+}
+
+export async function markAiJobUnexpectedFailure(db: D1Database, jobId: string): Promise<void> {
+  const failedAt = now();
+  await db.prepare(`
+    UPDATE background_jobs SET state = 'failed', available_at = ?2,
+      last_error_code = 'ai_internal_error', updated_at = ?2
+    WHERE id = ?1 AND state = 'processing'
+  `).bind(jobId, failedAt).run();
+}
+
+export async function markAiJobEnqueued(db: D1Database, jobId: string, success: boolean): Promise<void> {
+  const updatedAt = now();
+  await db.prepare(`
+    UPDATE background_jobs SET state = ?2, last_error_code = ?3, updated_at = ?4
+    WHERE id = ?1 AND state IN ('pending', 'failed')
+  `).bind(jobId, success ? "enqueued" : "failed", success ? null : "ai_queue_send_failed", updatedAt).run();
+}