create-safest-tools 0.2.0

package/template/src/report-router-agent.ts

@@ -0,0 +1,328 @@
+import { canonicalJson } from "./audit";
+import { ApiError } from "./report-http";
+import type { QueueRoutingPolicy, RoutingInput } from "./report-routing";
+import type { OperatorSession } from "./report-types";
+import type { RoutingAgentConfigurationInput, RoutingAgentRollout } from "./report-router-validation";
+
+export interface RoutingAiBinding {
+  run(model: string, input: Record<string, unknown>): Promise<unknown>;
+}
+
+interface RoutingAgentRow {
+  id: string;
+  version: number;
+  enabled: number;
+  rollout_mode: RoutingAgentRollout;
+  provider: "workers_ai";
+  model: string;
+  instructions: string;
+  candidate_queue_ids_json: string;
+  safeguard_queue_id: string;
+  default_queue_id: string;
+  confidence_threshold: number;
+  allowed_fields_json: string;
+  published_at: string;
+  created_by: string;
+  created_at: string;
+}
+
+export interface ActiveRoutingAgent {
+  id: string;
+  version: number;
+  enabled: boolean;
+  rolloutMode: RoutingAgentRollout;
+  model: string;
+  instructions: string;
+  candidateQueueIds: string[];
+  safeguardQueueId: string;
+  defaultQueueId: string;
+  confidenceThreshold: number;
+  allowedFields: string[];
+  publishedAt: string;
+  createdBy: string;
+  createdAt: string;
+}
+
+const ROUTER_TIMEOUT_MS = 12_000;
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function stringArray(value: string): string[] {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed.filter((item): item is string => typeof item === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+function publicAgent(row: RoutingAgentRow): ActiveRoutingAgent {
+  return {
+    id: row.id,
+    version: row.version,
+    enabled: row.enabled === 1,
+    rolloutMode: row.rollout_mode,
+    model: row.model,
+    instructions: row.instructions,
+    candidateQueueIds: stringArray(row.candidate_queue_ids_json),
+    safeguardQueueId: row.safeguard_queue_id,
+    defaultQueueId: row.default_queue_id,
+    confidenceThreshold: row.confidence_threshold,
+    allowedFields: stringArray(row.allowed_fields_json),
+    publishedAt: row.published_at,
+    createdBy: row.created_by,
+    createdAt: row.created_at,
+  };
+}
+
+export async function activeRoutingAgent(db: D1Database): Promise<ActiveRoutingAgent | null> {
+  const row = await db.prepare(`
+    SELECT * FROM routing_agent_versions
+    WHERE installation_id = 'default' AND published_at IS NOT NULL
+    ORDER BY version DESC, id DESC LIMIT 1
+  `).first<RoutingAgentRow>();
+  return row ? publicAgent(row) : null;
+}
+
+export async function listRoutingAgents(db: D1Database): Promise<ActiveRoutingAgent[]> {
+  const rows = await db.prepare(`
+    SELECT * FROM routing_agent_versions
+    WHERE installation_id = 'default' AND published_at IS NOT NULL
+    ORDER BY version DESC, id DESC LIMIT 50
+  `).all<RoutingAgentRow>();
+  return rows.results.map(publicAgent);
+}
+
+async function validateQueueAssignments(db: D1Database, input: RoutingAgentConfigurationInput): Promise<void> {
+  const requiredHuman = await db.prepare(`
+    SELECT q.id
+    FROM queue_definitions q JOIN queue_versions v ON v.id = q.active_version_id
+    WHERE q.id IN (?1, ?2) AND q.purpose = 'reports' AND q.status = 'active' AND v.management_mode = 'human'
+  `).bind(input.safeguardQueueId, input.defaultQueueId).all<{ id: string }>();
+  const validHumans = new Set(requiredHuman.results.map((row) => row.id));
+  if (!validHumans.has(input.safeguardQueueId)) {
+    throw new ApiError(400, "invalid_safeguard_queue", "The safeguard queue must be an active human-managed report queue.");
+  }
+  if (!validHumans.has(input.defaultQueueId)) {
+    throw new ApiError(400, "invalid_default_queue", "The default queue must be an active human-managed report queue.");
+  }
+  if (!input.candidateQueueIds.length) return;
+  const placeholders = input.candidateQueueIds.map((_, index) => `?${index + 1}`).join(", ");
+  const candidates = await db.prepare(`
+    SELECT id FROM queue_definitions
+    WHERE id IN (${placeholders}) AND purpose = 'reports' AND status = 'active' AND active_version_id IS NOT NULL
+  `).bind(...input.candidateQueueIds).all<{ id: string }>();
+  const valid = new Set(candidates.results.map((row) => row.id));
+  if (input.candidateQueueIds.some((id) => !valid.has(id))) {
+    throw new ApiError(400, "invalid_candidate_queue", "Every routing-agent candidate must be an active report queue with a published policy.");
+  }
+}
+
+export async function publishRoutingAgent(
+  db: D1Database,
+  input: RoutingAgentConfigurationInput,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ id: string; version: number; idempotentReplay: boolean }> {
+  const replay = await db.prepare(`
+    SELECT target_id FROM configuration_mutations
+    WHERE idempotency_key = ?1 AND action = 'routing_agent.publish' AND actor_id = ?2 LIMIT 1
+  `).bind(idempotencyKey, session.actor.id).first<{ target_id: string }>();
+  if (replay) {
+    const existing = await db.prepare(`SELECT version FROM routing_agent_versions WHERE id = ?1 LIMIT 1`)
+      .bind(replay.target_id).first<{ version: number }>();
+    if (existing) return { id: replay.target_id, version: existing.version, idempotentReplay: true };
+  }
+  const reused = await db.prepare(`SELECT action, actor_id FROM configuration_mutations WHERE idempotency_key = ?1 LIMIT 1`)
+    .bind(idempotencyKey).first<{ action: string; actor_id: string }>();
+  if (reused) throw new ApiError(409, "idempotency_key_reused", "This Idempotency-Key was already used for another configuration mutation.");
+  await validateQueueAssignments(db, input);
+  const latest = await db.prepare(`SELECT COALESCE(MAX(version), 0) AS version FROM routing_agent_versions WHERE installation_id = 'default'`)
+    .first<{ version: number }>();
+  const version = Number(latest?.version ?? 0) + 1;
+  const id = crypto.randomUUID();
+  const createdAt = now();
+  const response = { id, version };
+  await db.batch([
+    db.prepare(`
+      INSERT INTO routing_agent_versions (
+        id, installation_id, version, enabled, rollout_mode, provider, model, instructions,
+        candidate_queue_ids_json, safeguard_queue_id, default_queue_id, confidence_threshold,
+        allowed_fields_json, published_at, created_by, created_at, idempotency_key
+      ) VALUES (?1, 'default', ?2, ?3, ?4, 'workers_ai', ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?12, ?14)
+    `).bind(
+      id, version, input.enabled ? 1 : 0, input.rolloutMode, input.model, input.instructions,
+      canonicalJson(input.candidateQueueIds), input.safeguardQueueId, input.defaultQueueId,
+      input.confidenceThreshold, canonicalJson(input.allowedFields), createdAt, session.actor.id, idempotencyKey,
+    ),
+    db.prepare(`
+      INSERT INTO configuration_mutations (idempotency_key, action, actor_id, target_id, response_json, created_at)
+      VALUES (?1, 'routing_agent.publish', ?2, ?3, ?4, ?5)
+    `).bind(idempotencyKey, session.actor.id, id, canonicalJson(response), createdAt),
+    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, 'routing_agent.published', ?3, ?4, 'routing_agent', ?5, ?6, ?7)
+    `).bind(
+      crypto.randomUUID(), `routing-agent:${idempotencyKey}`, session.actor.type, session.actor.id, id,
+      canonicalJson({ version, enabled: input.enabled, rolloutMode: input.rolloutMode, candidateQueueIds: input.candidateQueueIds }), createdAt,
+    ),
+  ]);
+  return { id, version, idempotentReplay: false };
+}
+
+function boundedReportInput(input: RoutingInput, allowedFields: Set<string>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  if (allowedFields.has("reason_code")) result.reason_code = input.reasonCode;
+  if (allowedFields.has("source")) result.source = input.source;
+  if (allowedFields.has("target_type")) result.target_type = input.targetType;
+  if (allowedFields.has("answers.details") && typeof input.answers.details === "string") {
+    result.details = input.answers.details.slice(0, 4_000);
+  }
+  if (allowedFields.has("trusted_facts")) result.trusted_facts = input.trustedFacts;
+  if (allowedFields.has("enrichments") && input.enrichments) {
+    const serialized = canonicalJson(input.enrichments);
+    result.enrichments = new TextEncoder().encode(serialized).byteLength <= 16_384
+      ? input.enrichments
+      : { available_keys: Object.keys(input.enrichments).slice(0, 50), omitted_for_size: true };
+  }
+  return result;
+}
+
+function unwrap(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  const response = value as Record<string, unknown>;
+  let output: unknown = response.response ?? response.result ?? value;
+  if (typeof output === "string") {
+    try { output = JSON.parse(output) as unknown; } catch { return output; }
+  }
+  return output;
+}
+
+export function validateRoutingAgentOutput(
+  value: unknown,
+  candidates: Set<string>,
+  threshold: number,
+): { queueId: string | null; confidence: number | null; needsHuman: boolean; rationale: string | null; errors: string[] } {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { queueId: null, confidence: null, needsHuman: true, rationale: null, errors: ["output_not_object"] };
+  }
+  const input = value as Record<string, unknown>;
+  const errors: string[] = [];
+  if (Object.keys(input).some((key) => !["queue_id", "confidence", "needs_human", "rationale"].includes(key))) errors.push("unknown_output_field");
+  const queueId = typeof input.queue_id === "string" && candidates.has(input.queue_id) ? input.queue_id : null;
+  if (!queueId) errors.push("queue_not_candidate");
+  const confidence = typeof input.confidence === "number" && Number.isFinite(input.confidence)
+    && input.confidence >= 0 && input.confidence <= 1 ? input.confidence : null;
+  if (confidence === null) errors.push("confidence_invalid");
+  if (typeof input.needs_human !== "boolean") errors.push("needs_human_invalid");
+  const rationale = typeof input.rationale === "string" && input.rationale.trim().length >= 3 && input.rationale.trim().length <= 500
+    ? input.rationale.trim() : null;
+  if (!rationale) errors.push("rationale_invalid");
+  const needsHuman = input.needs_human !== false || confidence === null || confidence < threshold;
+  return { queueId, confidence, needsHuman, rationale, errors };
+}
+
+async function recordRun(
+  db: D1Database,
+  input: {
+    runId: string;
+    reportId: string;
+    agentId: string;
+    jobId: string;
+    status: "succeeded" | "failed" | "rejected" | "shadowed";
+    candidates: string[];
+    queueId: string | null;
+    confidence: number | null;
+    needsHuman: boolean;
+    rationale: string | null;
+    errors: string[];
+    startedAt: string;
+  },
+): Promise<void> {
+  await db.prepare(`
+    INSERT INTO routing_agent_runs (
+      id, report_id, routing_agent_version_id, background_job_id, status,
+      candidate_queue_ids_json, selected_queue_id, confidence, needs_human, rationale,
+      validation_errors_json, started_at, finished_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13)
+  `).bind(
+    input.runId, input.reportId, input.agentId, input.jobId, input.status,
+    canonicalJson(input.candidates), input.queueId, input.confidence, input.needsHuman ? 1 : 0,
+    input.rationale, canonicalJson(input.errors), input.startedAt, now(),
+  ).run();
+}
+
+export async function executeRoutingAgent(
+  db: D1Database,
+  ai: RoutingAiBinding | undefined,
+  agent: ActiveRoutingAgent,
+  reportId: string,
+  jobId: string,
+  input: RoutingInput,
+  queues: QueueRoutingPolicy[],
+): Promise<{ queueId: string | null; accepted: boolean }> {
+  if (!agent.enabled || agent.rolloutMode === "off") return { queueId: null, accepted: false };
+  const activeIds = new Set(queues.map((queue) => queue.queueId));
+  const candidates = agent.candidateQueueIds.filter((id) => activeIds.has(id));
+  const runId = crypto.randomUUID();
+  const startedAt = now();
+  if (!ai || !candidates.length) {
+    await recordRun(db, {
+      runId, reportId, agentId: agent.id, jobId, status: "failed", candidates,
+      queueId: null, confidence: null, needsHuman: true, rationale: null,
+      errors: [ai ? "no_active_candidates" : "ai_binding_unavailable"], startedAt,
+    });
+    return { queueId: null, accepted: false };
+  }
+  const queueDescriptions = await db.prepare(`
+    SELECT q.id, q.name, q.description, v.reviewer_instructions AS reviewerInstructions
+    FROM queue_definitions q JOIN queue_versions v ON v.id = q.active_version_id
+    WHERE q.status = 'active' AND q.purpose = 'reports'
+  `).all<{ id: string; name: string; description: string; reviewerInstructions: string }>();
+  const choices = queueDescriptions.results.filter((queue) => candidates.includes(queue.id)).map((queue) => ({
+    id: queue.id, name: queue.name, description: queue.description, policy_summary: queue.reviewerInstructions.slice(0, 1_000),
+  }));
+  try {
+    const response = await Promise.race([
+      ai.run(agent.model, {
+        messages: [
+          { role: "system", content: `${agent.instructions}\nYou are a routing agent only. Do not decide the report or propose an application action.` },
+          { role: "user", content: canonicalJson({ report: boundedReportInput(input, new Set(agent.allowedFields)), candidate_queues: choices }) },
+        ],
+        response_format: {
+          type: "json_schema",
+          json_schema: {
+            type: "object", additionalProperties: false,
+            properties: {
+              queue_id: { type: "string", enum: candidates },
+              confidence: { type: "number", minimum: 0, maximum: 1 },
+              needs_human: { type: "boolean" },
+              rationale: { type: "string", minLength: 3, maxLength: 500 },
+            },
+            required: ["queue_id", "confidence", "needs_human", "rationale"],
+          },
+        },
+      }),
+      new Promise<never>((_, reject) => setTimeout(() => reject(new Error("routing_agent_timeout")), ROUTER_TIMEOUT_MS)),
+    ]);
+    const validated = validateRoutingAgentOutput(unwrap(response), new Set(candidates), agent.confidenceThreshold);
+    const accepted = agent.rolloutMode === "active" && !validated.needsHuman && validated.errors.length === 0;
+    await recordRun(db, {
+      runId, reportId, agentId: agent.id, jobId,
+      status: validated.errors.length ? "rejected" : agent.rolloutMode === "shadow" ? "shadowed" : "succeeded",
+      candidates, queueId: validated.queueId, confidence: validated.confidence, needsHuman: validated.needsHuman,
+      rationale: validated.rationale, errors: validated.errors, startedAt,
+    });
+    return { queueId: validated.queueId, accepted };
+  } catch (error) {
+    await recordRun(db, {
+      runId, reportId, agentId: agent.id, jobId, status: "failed", candidates,
+      queueId: null, confidence: null, needsHuman: true, rationale: null,
+      errors: [error instanceof Error && error.message === "routing_agent_timeout" ? "timeout" : "execution_failed"], startedAt,
+    });
+    return { queueId: null, accepted: false };
+  }
+}

package/template/src/report-router-validation.ts

@@ -0,0 +1,81 @@
+import { ApiError } from "./report-http";
+
+export type RoutingAgentRollout = "off" | "shadow" | "active";
+
+export interface RoutingAgentConfigurationInput {
+  enabled: boolean;
+  rolloutMode: RoutingAgentRollout;
+  model: string;
+  instructions: string;
+  candidateQueueIds: string[];
+  safeguardQueueId: string;
+  defaultQueueId: string;
+  confidenceThreshold: number;
+  allowedFields: Array<"reason_code" | "source" | "target_type" | "answers.details" | "trusted_facts" | "enrichments">;
+}
+
+const rollouts = new Set<RoutingAgentRollout>(["off", "shadow", "active"]);
+const fields = new Set<RoutingAgentConfigurationInput["allowedFields"][number]>([
+  "reason_code", "source", "target_type", "answers.details", "trusted_facts", "enrichments",
+]);
+const idPattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/u;
+
+function identifier(value: unknown, name: string): string {
+  if (typeof value !== "string" || !idPattern.test(value)) {
+    throw new ApiError(400, "invalid_routing_agent_configuration", `${name} is invalid.`);
+  }
+  return value;
+}
+
+function list<T extends string>(value: unknown, name: string, allowed?: Set<T>): T[] {
+  if (!Array.isArray(value) || value.length > 50) {
+    throw new ApiError(400, "invalid_routing_agent_configuration", `${name} must contain at most 50 values.`);
+  }
+  const result = value.map((item, index) => identifier(item, `${name}[${index}]`) as T);
+  if (new Set(result).size !== result.length) throw new ApiError(400, "invalid_routing_agent_configuration", `${name} contains duplicates.`);
+  if (allowed && result.some((item) => !allowed.has(item))) {
+    throw new ApiError(400, "invalid_routing_agent_configuration", `${name} contains an unsupported field.`);
+  }
+  return result;
+}
+
+export function parseRoutingAgentConfiguration(value: Record<string, unknown>): RoutingAgentConfigurationInput {
+  const allowed = new Set([
+    "enabled", "rollout_mode", "model", "instructions", "candidate_queue_ids",
+    "safeguard_queue_id", "default_queue_id", "confidence_threshold", "allowed_fields",
+  ]);
+  const unexpected = Object.keys(value).find((key) => !allowed.has(key));
+  if (unexpected) throw new ApiError(400, "invalid_routing_agent_configuration", `The routing agent contains unsupported field ${unexpected}.`);
+  if (typeof value.enabled !== "boolean") throw new ApiError(400, "invalid_routing_agent_configuration", "enabled must be a boolean.");
+  if (typeof value.rollout_mode !== "string" || !rollouts.has(value.rollout_mode as RoutingAgentRollout)) {
+    throw new ApiError(400, "invalid_routing_agent_configuration", "rollout_mode must be off, shadow, or active.");
+  }
+  const rolloutMode = value.rollout_mode as RoutingAgentRollout;
+  if (rolloutMode === "off" && value.enabled) throw new ApiError(400, "invalid_routing_agent_configuration", "An off routing agent cannot be enabled.");
+  if (rolloutMode !== "off" && !value.enabled) throw new ApiError(400, "invalid_routing_agent_configuration", "Shadow and active routing agents must be enabled.");
+  if (typeof value.model !== "string" || !value.model.startsWith("@cf/") || value.model.length > 200) {
+    throw new ApiError(400, "invalid_routing_agent_configuration", "model must be a Workers AI @cf model identifier.");
+  }
+  if (typeof value.instructions !== "string" || value.instructions.trim().length < 20 || value.instructions.trim().length > 10_000) {
+    throw new ApiError(400, "invalid_routing_agent_configuration", "instructions must contain 20 to 10000 characters.");
+  }
+  const candidateQueueIds = list<string>(value.candidate_queue_ids, "candidate_queue_ids");
+  if (rolloutMode !== "off" && candidateQueueIds.length < 1) {
+    throw new ApiError(400, "invalid_routing_agent_configuration", "An enabled routing agent requires at least one candidate queue.");
+  }
+  if (typeof value.confidence_threshold !== "number" || !Number.isFinite(value.confidence_threshold)
+    || value.confidence_threshold < 0 || value.confidence_threshold > 1) {
+    throw new ApiError(400, "invalid_routing_agent_configuration", "confidence_threshold must be from 0 to 1.");
+  }
+  return {
+    enabled: value.enabled,
+    rolloutMode,
+    model: value.model,
+    instructions: value.instructions.trim(),
+    candidateQueueIds,
+    safeguardQueueId: identifier(value.safeguard_queue_id, "safeguard_queue_id"),
+    defaultQueueId: identifier(value.default_queue_id, "default_queue_id"),
+    confidenceThreshold: value.confidence_threshold,
+    allowedFields: list(value.allowed_fields, "allowed_fields", fields),
+  };
+}

package/template/src/report-routing.ts

@@ -0,0 +1,178 @@
+import type { QueueManagementMode, QueueRolloutMode, RoutingCondition } from "./report-queue-validation";
+
+export interface RoutingInput {
+  reasonCode: string;
+  source: string;
+  targetType: string;
+  trustedFacts: Record<string, string | number | boolean | null>;
+  answers: Record<string, unknown>;
+  enrichments?: Record<string, unknown>;
+  priority?: number;
+}
+
+export interface QueueRoutingPolicy {
+  queueId: string;
+  queueVersionId: string;
+  managementMode: QueueManagementMode;
+  rolloutMode: QueueRolloutMode;
+  priority: number;
+  responseSlaMinutes: number | null;
+  fallbackQueueId: string | null;
+  position: number;
+  routingCriteria: { match: "all" | "any"; conditions: RoutingCondition[] };
+  adjudicationPolicyVersionId: string;
+}
+
+export interface RoutingResult {
+  queueId: string;
+  queueVersionId: string;
+  state: "human_review" | "ai_review";
+  priority: number;
+  reasonCode: string;
+  responseSlaMinutes: number | null;
+  safeguardReasons: string[];
+}
+
+const protectedReasons = new Set([
+  "child_safety", "credible_threat", "immediate_danger", "self_harm", "terrorism",
+  "violent_extremism", "non_consensual_intimate_imagery", "sextortion", "legal_notice",
+  "law_enforcement", "trusted_flagger", "threat",
+]);
+
+const protectedFacts = [
+  "protected_category", "minor_involved", "high_impact", "identity_missing",
+  "evidence_unavailable", "trusted_facts_conflict", "contested", "appeal",
+] as const;
+
+const protectedContent = /\b(?:underage|minor|child sexual|suicid(?:e|al)|self[- ]harm|kill (?:myself|them|him|her)|bomb threat|credible threat|sextortion|intimate image)\b/iu;
+const humanRequest = /\b(?:human review|real person|appeal|contest(?:ed|ing)? (?:this|the) decision)\b/iu;
+
+function answerText(answers: Record<string, unknown>): string {
+  return Object.values(answers).filter((value): value is string => typeof value === "string").join("\n").slice(0, 20_000);
+}
+
+export function evaluateHardSafeguards(input: RoutingInput): { requiresHuman: boolean; reasons: string[] } {
+  const reasons: string[] = [];
+  if (protectedReasons.has(input.reasonCode)) reasons.push("protected_reason_code");
+  for (const fact of protectedFacts) {
+    if (input.trustedFacts[fact] === true) reasons.push(`trusted_fact:${fact}`);
+  }
+  const content = answerText(input.answers);
+  if (protectedContent.test(content)) reasons.push("protected_content_detected");
+  if (humanRequest.test(content)) reasons.push("human_review_requested");
+  return { requiresHuman: reasons.length > 0, reasons };
+}
+
+function nestedValue(value: unknown, path: string[]): unknown {
+  let current = value;
+  for (const part of path) {
+    if (!current || typeof current !== "object" || Array.isArray(current)) return undefined;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+function routingValue(input: RoutingInput, safeguard: { requiresHuman: boolean }, field: string): unknown {
+  if (field === "reason_code") return input.reasonCode;
+  if (field === "source") return input.source;
+  if (field === "target_type") return input.targetType;
+  if (field === "priority") return input.priority ?? 50;
+  if (field === "safeguard.requires_human") return safeguard.requiresHuman;
+  if (field.startsWith("trusted_fact.")) return input.trustedFacts[field.slice("trusted_fact.".length)];
+  if (field.startsWith("answer.")) return input.answers[field.slice("answer.".length)];
+  if (field.startsWith("enrichment.")) {
+    return nestedValue(input.enrichments ?? {}, field.slice("enrichment.".length).split("."));
+  }
+  return undefined;
+}
+
+function equal(left: unknown, right: unknown): boolean {
+  return typeof left === typeof right && left === right;
+}
+
+export function matchesRoutingCondition(actual: unknown, condition: RoutingCondition): boolean {
+  if (condition.operator === "exists") return actual !== undefined && actual !== null;
+  if (actual === undefined || actual === null) return false;
+  const expected = condition.value;
+  if (condition.operator === "eq") return equal(actual, expected);
+  if (condition.operator === "neq") return !equal(actual, expected);
+  if (condition.operator === "in") return Array.isArray(expected) && expected.some((value) => equal(actual, value));
+  if (condition.operator === "not_in") return Array.isArray(expected) && !expected.some((value) => equal(actual, value));
+  if (condition.operator === "contains") {
+    if (typeof actual === "string" && typeof expected === "string") return actual.toLowerCase().includes(expected.toLowerCase());
+    return Array.isArray(actual) && actual.some((value) => equal(value, expected));
+  }
+  if ((typeof actual !== "number" && typeof actual !== "string")
+    || (typeof expected !== "number" && typeof expected !== "string")) return false;
+  if (condition.operator === "gt") return actual > expected;
+  if (condition.operator === "gte") return actual >= expected;
+  if (condition.operator === "lt") return actual < expected;
+  if (condition.operator === "lte") return actual <= expected;
+  return false;
+}
+
+export function queueMatches(
+  input: RoutingInput,
+  queue: QueueRoutingPolicy,
+  safeguard = evaluateHardSafeguards(input),
+): boolean {
+  const results = queue.routingCriteria.conditions.map((condition) => (
+    matchesRoutingCondition(routingValue(input, safeguard, condition.field), condition)
+  ));
+  return queue.routingCriteria.match === "all" ? results.every(Boolean) : results.length > 0 && results.some(Boolean);
+}
+
+export function routingCriteriaMatches(
+  input: RoutingInput,
+  criteria: { match: "all" | "any"; conditions: RoutingCondition[] },
+): boolean {
+  const safeguard = evaluateHardSafeguards(input);
+  const results = criteria.conditions.map((condition) => matchesRoutingCondition(routingValue(input, safeguard, condition.field), condition));
+  return criteria.match === "all" ? results.every(Boolean) : results.length > 0 && results.some(Boolean);
+}
+
+function routedState(queue: QueueRoutingPolicy): "human_review" | "ai_review" {
+  if (queue.managementMode === "human" || queue.rolloutMode === "off" || queue.rolloutMode === "shadow") return "human_review";
+  return "ai_review";
+}
+
+export function selectRoute(
+  input: RoutingInput,
+  queues: QueueRoutingPolicy[],
+  options: {
+    defaultQueueId: string;
+    safeguardQueueId: string;
+    deterministicQueueId?: string | null;
+    agentQueueId?: string | null;
+    agentAccepted?: boolean;
+  },
+): RoutingResult | null {
+  const safeguard = evaluateHardSafeguards(input);
+  const byId = new Map(queues.map((queue) => [queue.queueId, queue]));
+  let queue: QueueRoutingPolicy | undefined;
+  let reasonCode: string;
+  if (safeguard.requiresHuman) {
+    queue = byId.get(options.safeguardQueueId);
+    reasonCode = "hard_safeguard_human_route";
+  } else if (options.deterministicQueueId) {
+    queue = byId.get(options.deterministicQueueId);
+    reasonCode = "published_routing_rule_match";
+  } else if (options.agentAccepted && options.agentQueueId) {
+    queue = byId.get(options.agentQueueId);
+    reasonCode = "validated_routing_agent_selection";
+  } else {
+    queue = byId.get(options.defaultQueueId);
+    reasonCode = "default_queue_route";
+  }
+  if (!queue) return null;
+  if (safeguard.requiresHuman && queue.managementMode !== "human") return null;
+  return {
+    queueId: queue.queueId,
+    queueVersionId: queue.queueVersionId,
+    state: safeguard.requiresHuman ? "human_review" : routedState(queue),
+    priority: safeguard.requiresHuman ? Math.max(90, queue.priority) : queue.priority,
+    reasonCode,
+    responseSlaMinutes: queue.responseSlaMinutes,
+    safeguardReasons: safeguard.reasons,
+  };
+}