create-safest-tools 0.2.0

package/template/src/report-queues.ts

@@ -0,0 +1,478 @@
+import { canonicalJson } from "./audit";
+import { ApiError } from "./report-http";
+import type { OperatorSession } from "./report-types";
+import type { QueueCreateInput, QueuePolicyInput, QueueStatus, QueueUpdateInput } from "./report-queue-validation";
+
+interface QueueRow {
+  id: string;
+  key: string;
+  name: string;
+  description: string;
+  purpose: "reports" | "appeals" | "quality" | "operations";
+  status: QueueStatus;
+  position: number;
+  activeVersionId: string | null;
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+  versionId: string | null;
+  version: number | null;
+  managementMode: QueuePolicyInput["managementMode"] | null;
+  rolloutMode: QueuePolicyInput["rolloutMode"] | null;
+  priority: number | null;
+  responseSlaMinutes: number | null;
+  resolutionSlaMinutes: number | null;
+  claimTtlMinutes: number | null;
+  fallbackQueueId: string | null;
+  reviewerInstructions: string | null;
+  aiInstructions: string | null;
+  aiBoundsJson: string | null;
+  versionCreatedBy: string | null;
+  versionCreatedAt: string | null;
+  publishedAt: string | null;
+  openReportCount: number;
+  totalReportCount: number;
+}
+
+interface VersionRow {
+  id: string;
+  queueId: string;
+  version: number;
+  managementMode: QueuePolicyInput["managementMode"];
+  rolloutMode: QueuePolicyInput["rolloutMode"];
+  priority: number;
+  responseSlaMinutes: number | null;
+  resolutionSlaMinutes: number | null;
+  claimTtlMinutes: number;
+  fallbackQueueId: string | null;
+  reviewerInstructions: string;
+  aiInstructions: string | null;
+  aiBoundsJson: string;
+  createdBy: string;
+  createdAt: string;
+  publishedAt: string | null;
+}
+
+interface MutationRow {
+  action: string;
+  actor_id: string;
+  response_json: string;
+}
+
+const closedStates = new Set(["resolved_by_human", "resolved_by_ai", "closed"]);
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function jsonValue<T>(value: string | null, fallback: T): T {
+  if (!value) return fallback;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+function publicRollout(value: QueuePolicyInput["rolloutMode"] | null): "off" | "shadow" | "assist" | "autonomous" | null {
+  return value === "autonomous_low_priority" ? "autonomous" : value;
+}
+
+function policyFromRow(row: VersionRow | QueueRow): Record<string, unknown> | null {
+  const id = "versionId" in row ? row.versionId : row.id;
+  if (!id || row.version === null || row.managementMode === null || row.rolloutMode === null) return null;
+  return {
+    id,
+    version: row.version,
+    managementMode: row.managementMode,
+    rolloutMode: publicRollout(row.rolloutMode),
+    priority: row.priority,
+    responseSlaMinutes: row.responseSlaMinutes,
+    resolutionSlaMinutes: row.resolutionSlaMinutes,
+    claimTtlMinutes: row.claimTtlMinutes,
+    fallbackQueueId: row.fallbackQueueId,
+    reviewerInstructions: row.reviewerInstructions,
+    aiInstructions: row.aiInstructions,
+    aiBounds: jsonValue(row.aiBoundsJson, {}),
+    createdBy: "versionCreatedBy" in row ? row.versionCreatedBy : row.createdBy,
+    createdAt: "versionCreatedAt" in row ? row.versionCreatedAt : row.createdAt,
+    publishedAt: row.publishedAt,
+  };
+}
+
+function queueFromRow(row: QueueRow): Record<string, unknown> {
+  return {
+    id: row.id,
+    key: row.key,
+    name: row.name,
+    description: row.description,
+    purpose: row.purpose,
+    status: row.status,
+    position: row.position,
+    createdBy: row.createdBy,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+    activePolicy: policyFromRow(row),
+    counts: { openReports: row.openReportCount, totalReports: row.totalReportCount },
+  };
+}
+
+async function mutationReplay(
+  db: D1Database,
+  idempotencyKey: string,
+  action: string,
+  actorId: string,
+): Promise<Record<string, unknown> | null> {
+  const row = await db.prepare(`
+    SELECT action, actor_id, response_json FROM configuration_mutations WHERE idempotency_key = ?1 LIMIT 1
+  `).bind(idempotencyKey).first<MutationRow>();
+  if (!row) return null;
+  if (row.action !== action || row.actor_id !== actorId) {
+    throw new ApiError(409, "idempotency_key_reused", "This Idempotency-Key was already used for another configuration mutation.");
+  }
+  return jsonValue<Record<string, unknown>>(row.response_json, {});
+}
+
+async function requireHumanFallback(db: D1Database, policy: QueuePolicyInput, queueId?: string): Promise<void> {
+  if (policy.managementMode === "human" || policy.rolloutMode === "off") return;
+  if (!policy.fallbackQueueId) {
+    throw new ApiError(400, "human_fallback_required", "An enabled AI-managed queue requires an active human-managed fallback queue.");
+  }
+  if (policy.fallbackQueueId === queueId) {
+    throw new ApiError(400, "invalid_fallback_queue", "A queue cannot use itself as its human fallback.");
+  }
+  const fallback = await db.prepare(`
+    SELECT q.id
+    FROM queue_definitions q
+    JOIN queue_versions v ON v.id = q.active_version_id
+    WHERE q.id = ?1 AND q.purpose = 'reports' AND q.status = 'active' AND v.management_mode = 'human'
+    LIMIT 1
+  `).bind(policy.fallbackQueueId).first<{ id: string }>();
+  if (!fallback) throw new ApiError(400, "invalid_fallback_queue", "The fallback must be an active human-managed report queue.");
+}
+
+async function requireAiPolicyResources(db: D1Database, policy: QueuePolicyInput): Promise<void> {
+  if (policy.managementMode === "human" || policy.rolloutMode === "off") return;
+  const adjudicationPolicy = await db.prepare(`
+    SELECT id FROM policy_versions WHERE id = ?1 AND published_at IS NOT NULL LIMIT 1
+  `).bind(policy.aiBounds.policyVersionId).first<{ id: string }>();
+  if (!adjudicationPolicy) {
+    throw new ApiError(400, "ai_policy_not_published", "The queue's adjudication policy version is not published.");
+  }
+  for (const templateId of policy.aiBounds.allowedTemplateIds) {
+    const template = await db.prepare(`
+      SELECT id FROM message_template_versions
+      WHERE id = ?1 AND audience = 'reporter' AND automation_allowed = 1 AND published_at IS NOT NULL
+      LIMIT 1
+    `).bind(templateId).first<{ id: string }>();
+    if (!template) throw new ApiError(400, "ai_template_not_approved", `Template ${templateId} is not approved for automated reporter messaging.`);
+  }
+}
+
+async function requireAutonomousReleaseGate(db: D1Database, queueId: string, policy: QueuePolicyInput): Promise<void> {
+  if (policy.rolloutMode !== "autonomous_low_priority") return;
+  const shadow = await db.prepare(`
+    SELECT COUNT(*) AS total,
+      SUM(CASE WHEN ar.status IN ('failed', 'invalid') THEN 1 ELSE 0 END) AS failures
+    FROM ai_runs ar JOIN ai_queue_config_versions c ON c.id = ar.config_version_id
+    WHERE c.queue_id = ?1 AND c.mode = 'shadow' AND c.model = ?2 AND c.policy_version_id = ?3
+  `).bind(queueId, policy.aiBounds.model, policy.aiBounds.policyVersionId)
+    .first<{ total: number; failures: number | null }>();
+  const total = Number(shadow?.total ?? 0);
+  const failureRate = total ? Number(shadow?.failures ?? 0) / total : 1;
+  if (total < policy.aiBounds.minimumShadowRuns || failureRate > policy.aiBounds.maximumFailureRate) {
+    throw new ApiError(409, "ai_shadow_gate_not_met", "Autonomous rollout has not met this queue policy's shadow volume and failure-rate gate.", {
+      observed_runs: total,
+      required_runs: policy.aiBounds.minimumShadowRuns,
+      observed_failure_rate: failureRate,
+      maximum_failure_rate: policy.aiBounds.maximumFailureRate,
+    });
+  }
+  const quality = await db.prepare(`
+    SELECT COUNT(*) AS total, SUM(CASE WHEN qr.agrees = 0 THEN 1 ELSE 0 END) AS disagreements
+    FROM quality_reviews qr JOIN ai_quality_samples qs ON qs.id = qr.sample_id
+    JOIN ai_runs ar ON ar.id = qs.ai_run_id
+    JOIN ai_queue_config_versions c ON c.id = ar.config_version_id
+    WHERE c.queue_id = ?1 AND c.model = ?2 AND c.policy_version_id = ?3
+  `).bind(queueId, policy.aiBounds.model, policy.aiBounds.policyVersionId)
+    .first<{ total: number; disagreements: number | null }>();
+  const reviewed = Number(quality?.total ?? 0);
+  const disagreementRate = reviewed ? Number(quality?.disagreements ?? 0) / reviewed : 0;
+  if (reviewed < policy.aiBounds.minimumQualityReviews || disagreementRate > policy.aiBounds.maximumDisagreementRate) {
+    throw new ApiError(409, "ai_quality_gate_not_met", "Autonomous rollout has not met this queue policy's human quality-review gate.", {
+      observed_reviews: reviewed,
+      required_reviews: policy.aiBounds.minimumQualityReviews,
+      observed_disagreement_rate: disagreementRate,
+      maximum_disagreement_rate: policy.aiBounds.maximumDisagreementRate,
+    });
+  }
+}
+
+function auditEvent(
+  db: D1Database,
+  input: { key: string; action: string; actorType: OperatorSession["actor"]["type"]; actorId: string; targetId: 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, ?4, ?5, 'queue', ?6, ?7, ?8)
+  `).bind(crypto.randomUUID(), input.key, input.action, input.actorType, input.actorId, input.targetId, canonicalJson(input.details), input.createdAt);
+}
+
+function versionInsert(db: D1Database, queueId: string, versionId: string, version: number, policy: QueuePolicyInput, actorId: string, createdAt: string): D1PreparedStatement {
+  return db.prepare(`
+    INSERT INTO queue_versions (
+      id, queue_id, version, mode, priority, response_sla_minutes, resolution_sla_minutes,
+      claim_ttl_minutes, fallback_queue_id, configuration_json, published_at, created_by, created_at,
+      management_mode, reviewer_instructions, ai_instructions, ai_bounds_json
+    ) VALUES (
+      ?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?11,
+      ?13, ?14, ?15, ?16
+    )
+  `).bind(
+    versionId, queueId, version, policy.rolloutMode, policy.priority, policy.responseSlaMinutes,
+    policy.resolutionSlaMinutes, policy.claimTtlMinutes, policy.fallbackQueueId,
+    canonicalJson({ schemaVersion: 2 }), createdAt, actorId, policy.managementMode,
+    policy.reviewerInstructions, policy.aiInstructions, canonicalJson(policy.aiBounds),
+  );
+}
+
+function aiRuntimeInsert(
+  db: D1Database,
+  queueId: string,
+  queueVersionId: string,
+  policy: QueuePolicyInput,
+  actorId: string,
+  createdAt: string,
+): D1PreparedStatement | null {
+  if (policy.managementMode === "human" || policy.rolloutMode === "off" || !policy.fallbackQueueId) return null;
+  return db.prepare(`
+    INSERT INTO ai_queue_config_versions (
+      id, queue_id, queue_version_id, version, mode, enabled, provider, model,
+      input_cost_microusd_per_million, output_cost_microusd_per_million,
+      prompt_version, policy_version_id, eligible_form_versions_json, eligible_sources_json,
+      eligible_reason_codes_json, eligible_target_types_json, allowed_fields_json, allowed_outcomes_json,
+      allowed_action_codes_json, allowed_template_ids_json, confidence_threshold, max_follow_up_turns,
+      max_wait_hours, daily_report_budget, daily_cost_budget_microusd, quality_sample_rate,
+      minimum_shadow_runs, minimum_quality_reviews, maximum_failure_rate, maximum_disagreement_rate,
+      fallback_queue_id, pause_state, published_at, created_by, created_at, idempotency_key
+    ) VALUES (
+      ?1, ?2, ?3, (SELECT COALESCE(MAX(version), 0) + 1 FROM ai_queue_config_versions WHERE queue_id = ?2),
+      ?4, 1, 'workers_ai', ?5, ?6, ?7, ?8, ?9, '["general-v1"]',
+      '["signed_widget","public_page","server_api"]', '["harassment","spam","other"]',
+      '["message","profile","listing","account","file","transaction","service"]',
+      ?10, ?11, '[]', ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19, ?20, ?21, ?22,
+      ?23, 'ready', ?24, ?25, ?24, ?26
+    )
+  `).bind(
+    `${queueVersionId}-ai-runtime`, queueId, queueVersionId, policy.rolloutMode,
+    policy.aiBounds.model, policy.aiBounds.inputCostMicrousdPerMillion,
+    policy.aiBounds.outputCostMicrousdPerMillion, `queue-policy-${queueVersionId}`,
+    policy.aiBounds.policyVersionId, canonicalJson(policy.aiBounds.allowedFields),
+    canonicalJson(policy.aiBounds.allowedOutcomes), canonicalJson(policy.aiBounds.allowedTemplateIds),
+    policy.aiBounds.confidenceThreshold, policy.aiBounds.maxFollowUpTurns, policy.aiBounds.maxWaitHours,
+    policy.aiBounds.dailyReportBudget, policy.aiBounds.dailyCostBudgetMicrousd,
+    policy.aiBounds.qualitySampleRate, policy.aiBounds.minimumShadowRuns,
+    policy.aiBounds.minimumQualityReviews, policy.aiBounds.maximumFailureRate,
+    policy.aiBounds.maximumDisagreementRate, policy.fallbackQueueId, createdAt, actorId,
+    `queue-policy-runtime:${queueVersionId}`,
+  );
+}
+
+export async function listQueues(db: D1Database, includeArchived = false): Promise<Record<string, unknown>[]> {
+  const result = await db.prepare(`
+    SELECT q.id, q.queue_key AS key, q.name, q.description, q.purpose, q.status, q.position,
+      q.active_version_id AS activeVersionId, q.created_by AS createdBy, q.created_at AS createdAt,
+      q.updated_at AS updatedAt, v.id AS versionId, v.version, v.management_mode AS managementMode,
+      v.mode AS rolloutMode, v.priority, v.response_sla_minutes AS responseSlaMinutes,
+      v.resolution_sla_minutes AS resolutionSlaMinutes, v.claim_ttl_minutes AS claimTtlMinutes,
+      v.fallback_queue_id AS fallbackQueueId,
+      v.reviewer_instructions AS reviewerInstructions, v.ai_instructions AS aiInstructions,
+      v.ai_bounds_json AS aiBoundsJson,
+      v.created_by AS versionCreatedBy, v.created_at AS versionCreatedAt, v.published_at AS publishedAt,
+      SUM(CASE WHEN r.id IS NOT NULL AND r.state NOT IN ('resolved_by_human', 'resolved_by_ai', 'closed') THEN 1 ELSE 0 END) AS openReportCount,
+      COUNT(r.id) AS totalReportCount
+    FROM queue_definitions q
+    LEFT JOIN queue_versions v ON v.id = q.active_version_id
+    LEFT JOIN reports r ON r.queue_id = q.id
+    WHERE q.purpose = 'reports' AND (?1 = 1 OR q.status != 'archived')
+    GROUP BY q.id
+    ORDER BY q.position, q.name, q.id
+  `).bind(includeArchived ? 1 : 0).all<QueueRow>();
+  return result.results.map(queueFromRow);
+}
+
+async function queueRow(db: D1Database, queueId: string): Promise<QueueRow | null> {
+  return db.prepare(`
+    SELECT q.id, q.queue_key AS key, q.name, q.description, q.purpose, q.status, q.position,
+      q.active_version_id AS activeVersionId, q.created_by AS createdBy, q.created_at AS createdAt,
+      q.updated_at AS updatedAt, v.id AS versionId, v.version, v.management_mode AS managementMode,
+      v.mode AS rolloutMode, v.priority, v.response_sla_minutes AS responseSlaMinutes,
+      v.resolution_sla_minutes AS resolutionSlaMinutes, v.claim_ttl_minutes AS claimTtlMinutes,
+      v.fallback_queue_id AS fallbackQueueId,
+      v.reviewer_instructions AS reviewerInstructions, v.ai_instructions AS aiInstructions,
+      v.ai_bounds_json AS aiBoundsJson,
+      v.created_by AS versionCreatedBy, v.created_at AS versionCreatedAt, v.published_at AS publishedAt,
+      SUM(CASE WHEN r.id IS NOT NULL AND r.state NOT IN ('resolved_by_human', 'resolved_by_ai', 'closed') THEN 1 ELSE 0 END) AS openReportCount,
+      COUNT(r.id) AS totalReportCount
+    FROM queue_definitions q
+    LEFT JOIN queue_versions v ON v.id = q.active_version_id
+    LEFT JOIN reports r ON r.queue_id = q.id
+    WHERE q.id = ?1 AND q.purpose = 'reports'
+    GROUP BY q.id
+    LIMIT 1
+  `).bind(queueId).first<QueueRow>();
+}
+
+export async function loadQueue(db: D1Database, queueId: string): Promise<Record<string, unknown> | null> {
+  const queue = await queueRow(db, queueId);
+  if (!queue) return null;
+  const versions = await db.prepare(`
+    SELECT id, queue_id AS queueId, version, management_mode AS managementMode, mode AS rolloutMode,
+      priority, response_sla_minutes AS responseSlaMinutes, resolution_sla_minutes AS resolutionSlaMinutes,
+      claim_ttl_minutes AS claimTtlMinutes, fallback_queue_id AS fallbackQueueId,
+      reviewer_instructions AS reviewerInstructions, ai_instructions AS aiInstructions,
+      ai_bounds_json AS aiBoundsJson, created_by AS createdBy, created_at AS createdAt, published_at AS publishedAt
+    FROM queue_versions WHERE queue_id = ?1 ORDER BY version DESC, id DESC
+  `).bind(queueId).all<VersionRow>();
+  return { ...queueFromRow(queue), versions: versions.results.map(policyFromRow) };
+}
+
+export async function createQueue(
+  db: D1Database,
+  input: QueueCreateInput,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<Record<string, unknown>> {
+  const replay = await mutationReplay(db, idempotencyKey, "queue.create", session.actor.id);
+  if (replay) return { ...replay, idempotentReplay: true };
+  await requireHumanFallback(db, input.policy);
+  await requireAiPolicyResources(db, input.policy);
+  const conflict = await db.prepare(`SELECT id FROM queue_definitions WHERE installation_id = 'default' AND queue_key = ?1 LIMIT 1`)
+    .bind(input.key).first<{ id: string }>();
+  if (conflict) throw new ApiError(409, "queue_key_exists", "A queue with this key already exists.");
+  const queueId = crypto.randomUUID();
+  const versionId = crypto.randomUUID();
+  const createdAt = now();
+  const response = { queueId, policyVersionId: versionId, version: 1 };
+  const runtime = aiRuntimeInsert(db, queueId, versionId, input.policy, session.actor.id, createdAt);
+  await db.batch([
+    db.prepare(`
+      INSERT INTO queue_definitions (
+        id, installation_id, queue_key, name, queue_kind, enabled, created_at, updated_at,
+        description, purpose, status, position, active_version_id, created_by
+      ) VALUES (?1, 'default', ?2, ?3, ?4, 1, ?5, ?5, ?6, 'reports', 'active', ?7, ?8, ?9)
+    `).bind(
+      queueId, input.key, input.name, input.policy.managementMode === "ai" ? "ai" : "human",
+      createdAt, input.description, input.position, versionId, session.actor.id,
+    ),
+    versionInsert(db, queueId, versionId, 1, input.policy, session.actor.id, createdAt),
+    db.prepare(`
+      INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at)
+      VALUES (?1, 'queue.create', ?2, ?3, ?4, ?5)
+    `).bind(idempotencyKey, session.actor.id, queueId, canonicalJson(response), createdAt),
+    auditEvent(db, {
+      key: `queue-create:${idempotencyKey}`, action: "queue.created", actorType: session.actor.type, actorId: session.actor.id,
+      targetId: queueId, details: { key: input.key, policyVersionId: versionId, managementMode: input.policy.managementMode }, createdAt,
+    }),
+    ...(runtime ? [runtime] : []),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function publishQueuePolicy(
+  db: D1Database,
+  queueId: string,
+  policy: QueuePolicyInput,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<Record<string, unknown>> {
+  const replay = await mutationReplay(db, idempotencyKey, "queue.policy.publish", session.actor.id);
+  if (replay) return { ...replay, idempotentReplay: true };
+  const queue = await queueRow(db, queueId);
+  if (!queue) throw new ApiError(404, "queue_not_found", "The queue does not exist.");
+  if (queue.status === "archived") throw new ApiError(409, "queue_archived", "Archived queues cannot receive new policy versions.");
+  await requireHumanFallback(db, policy, queueId);
+  await requireAiPolicyResources(db, policy);
+  await requireAutonomousReleaseGate(db, queueId, policy);
+  const latest = await db.prepare(`SELECT COALESCE(MAX(version), 0) AS version FROM queue_versions WHERE queue_id = ?1`)
+    .bind(queueId).first<{ version: number }>();
+  const version = Number(latest?.version ?? 0) + 1;
+  const versionId = crypto.randomUUID();
+  const createdAt = now();
+  const response = { queueId, policyVersionId: versionId, version };
+  const runtime = aiRuntimeInsert(db, queueId, versionId, policy, session.actor.id, createdAt);
+  await db.batch([
+    versionInsert(db, queueId, versionId, version, policy, session.actor.id, createdAt),
+    db.prepare(`
+      UPDATE queue_definitions
+      SET active_version_id = ?2, queue_kind = ?3, updated_at = ?4
+      WHERE id = ?1
+    `).bind(queueId, versionId, policy.managementMode === "ai" ? "ai" : "human", createdAt),
+    db.prepare(`
+      INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at)
+      VALUES (?1, 'queue.policy.publish', ?2, ?3, ?4, ?5)
+    `).bind(idempotencyKey, session.actor.id, queueId, canonicalJson(response), createdAt),
+    auditEvent(db, {
+      key: `queue-policy:${idempotencyKey}`, action: "queue.policy_published", actorType: session.actor.type, actorId: session.actor.id,
+      targetId: queueId, details: { policyVersionId: versionId, version, managementMode: policy.managementMode, rolloutMode: publicRollout(policy.rolloutMode) }, createdAt,
+    }),
+    ...(runtime ? [runtime] : []),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+export async function updateQueue(
+  db: D1Database,
+  queueId: string,
+  input: QueueUpdateInput,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<Record<string, unknown>> {
+  const replay = await mutationReplay(db, idempotencyKey, "queue.update", session.actor.id);
+  if (replay) return { ...replay, idempotentReplay: true };
+  const queue = await queueRow(db, queueId);
+  if (!queue) throw new ApiError(404, "queue_not_found", "The queue does not exist.");
+  if (input.status === "archived" && queue.openReportCount > 0) {
+    throw new ApiError(409, "queue_has_open_reports", "Move or resolve all open reports before archiving this queue.");
+  }
+  if (input.status && input.status !== "active") {
+    const fallbackUse = await db.prepare(`
+      SELECT q.id FROM queue_definitions q JOIN queue_versions qv ON qv.id = q.active_version_id
+      WHERE q.status = 'active' AND qv.management_mode IN ('ai', 'hybrid')
+        AND qv.mode != 'off' AND qv.fallback_queue_id = ?1 LIMIT 1
+    `).bind(queueId).first<{ id: string }>();
+    if (fallbackUse) {
+      throw new ApiError(409, "queue_is_active_fallback", "This queue is the required human fallback for an active AI or hybrid queue.");
+    }
+  }
+  const createdAt = now();
+  const next = {
+    name: input.name ?? queue.name,
+    description: input.description ?? queue.description,
+    position: input.position ?? queue.position,
+    status: input.status ?? queue.status,
+  };
+  const response = { queueId, status: next.status };
+  await db.batch([
+    db.prepare(`
+      UPDATE queue_definitions
+      SET name = ?2, description = ?3, position = ?4, status = ?5,
+          enabled = CASE WHEN ?5 = 'active' THEN 1 ELSE 0 END, updated_at = ?6
+      WHERE id = ?1
+    `).bind(queueId, next.name, next.description, next.position, next.status, createdAt),
+    db.prepare(`
+      INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at)
+      VALUES (?1, 'queue.update', ?2, ?3, ?4, ?5)
+    `).bind(idempotencyKey, session.actor.id, queueId, canonicalJson(response), createdAt),
+    auditEvent(db, {
+      key: `queue-update:${idempotencyKey}`, action: "queue.updated", actorType: session.actor.type, actorId: session.actor.id,
+      targetId: queueId, details: next, createdAt,
+    }),
+  ]);
+  return { ...response, idempotentReplay: false };
+}
+
+export function isClosedReportState(state: string): boolean {
+  return closedStates.has(state);
+}