create-safest-tools 0.2.0

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

@@ -0,0 +1,309 @@
+import { ApiError } from "./report-http";
+
+export type QueueManagementMode = "human" | "ai" | "hybrid";
+export type QueueRolloutMode = "off" | "shadow" | "assist" | "autonomous_low_priority";
+export type QueueStatus = "active" | "paused" | "archived";
+
+export interface RoutingCondition {
+  field: string;
+  operator: "eq" | "neq" | "in" | "not_in" | "exists" | "gt" | "gte" | "lt" | "lte" | "contains";
+  value?: string | number | boolean | null | Array<string | number | boolean>;
+}
+
+export interface QueuePolicyInput {
+  managementMode: QueueManagementMode;
+  rolloutMode: QueueRolloutMode;
+  priority: number;
+  responseSlaMinutes: number | null;
+  resolutionSlaMinutes: number | null;
+  claimTtlMinutes: number;
+  fallbackQueueId: string | null;
+  reviewerInstructions: string;
+  aiInstructions: string | null;
+  aiBounds: {
+    allowedOutcomes: string[];
+    confidenceThreshold: number;
+    maxFollowUpTurns: number;
+    autonomousActions: false;
+    model: string;
+    policyVersionId: string;
+    allowedFields: string[];
+    allowedTemplateIds: string[];
+    maxWaitHours: number;
+    dailyReportBudget: number;
+    dailyCostBudgetMicrousd: number;
+    inputCostMicrousdPerMillion: number;
+    outputCostMicrousdPerMillion: number;
+    qualitySampleRate: number;
+    minimumShadowRuns: number;
+    minimumQualityReviews: number;
+    maximumFailureRate: number;
+    maximumDisagreementRate: number;
+  };
+}
+
+export interface QueueCreateInput {
+  key: string;
+  name: string;
+  description: string;
+  position: number;
+  policy: QueuePolicyInput;
+}
+
+export interface QueueUpdateInput {
+  name?: string;
+  description?: string;
+  position?: number;
+  status?: QueueStatus;
+}
+
+const queueKeyPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const referencePattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/u;
+const criterionFieldPattern = /^(?:reason_code|source|target_type|priority|safeguard\.requires_human|trusted_fact\.[A-Za-z0-9_.:-]{1,160}|answer\.[A-Za-z0-9_.:-]{1,160}|enrichment\.[A-Za-z0-9_.:-]{1,160})$/u;
+const managementModes = new Set<QueueManagementMode>(["human", "ai", "hybrid"]);
+const rolloutModes = new Map<string, QueueRolloutMode>([
+  ["off", "off"], ["shadow", "shadow"], ["assist", "assist"],
+  ["autonomous", "autonomous_low_priority"], ["autonomous_low_priority", "autonomous_low_priority"],
+]);
+const queueStatuses = new Set<QueueStatus>(["active", "paused", "archived"]);
+const routingOperators = new Set<RoutingCondition["operator"]>(["eq", "neq", "in", "not_in", "exists", "gt", "gte", "lt", "lte", "contains"]);
+const aiFields = new Set(["target.type", "answers.details", "evidence.references", "enrichments"]);
+const aiOutcomes = new Set(["out_of_scope", "insufficient_information", "no_violation_found", "escalate_to_human"]);
+const aiTemplates = new Set(["ai-more-context-v1", "ai-no-violation-v1", "ai-out-of-scope-v1"]);
+
+function object(value: unknown, name: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ApiError(400, "invalid_queue_configuration", `${name} must be an object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function knownFields(value: Record<string, unknown>, allowed: readonly string[], name: string): void {
+  const unexpected = Object.keys(value).find((key) => !allowed.includes(key));
+  if (unexpected) throw new ApiError(400, "invalid_queue_configuration", `${name} contains unsupported field ${unexpected}.`);
+}
+
+function stringValue(value: unknown, name: string, minimum: number, maximum: number): string {
+  if (typeof value !== "string" || value.trim().length < minimum || value.trim().length > maximum) {
+    throw new ApiError(400, "invalid_queue_configuration", `${name} must contain ${minimum} to ${maximum} characters.`);
+  }
+  return value.trim();
+}
+
+function integer(value: unknown, name: string, minimum: number, maximum: number): number {
+  if (!Number.isInteger(value) || Number(value) < minimum || Number(value) > maximum) {
+    throw new ApiError(400, "invalid_queue_configuration", `${name} must be an integer from ${minimum} to ${maximum}.`);
+  }
+  return Number(value);
+}
+
+function numeric(value: unknown, name: string, minimum: number, maximum: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < minimum || value > maximum) {
+    throw new ApiError(400, "invalid_queue_configuration", `${name} must be a number from ${minimum} to ${maximum}.`);
+  }
+  return value;
+}
+
+function nullableInteger(value: unknown, name: string, minimum: number, maximum: number): number | null {
+  return value === null || value === undefined ? null : integer(value, name, minimum, maximum);
+}
+
+function identifier(value: unknown, name: string): string {
+  const parsed = stringValue(value, name, 1, 200);
+  if (!referencePattern.test(parsed)) throw new ApiError(400, "invalid_queue_configuration", `${name} is invalid.`);
+  return parsed;
+}
+
+function routingValue(value: unknown, name: string): RoutingCondition["value"] {
+  if (value === null || typeof value === "boolean") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.length <= 500) return value;
+  if (Array.isArray(value) && value.length > 0 && value.length <= 50) {
+    return value.map((item, index) => {
+      if (typeof item === "boolean") return item;
+      if (typeof item === "number" && Number.isFinite(item)) return item;
+      if (typeof item === "string" && item.length <= 500) return item;
+      throw new ApiError(400, "invalid_queue_configuration", `${name}[${index}] is invalid.`);
+    });
+  }
+  throw new ApiError(400, "invalid_queue_configuration", `${name} is invalid.`);
+}
+
+export function parseRoutingCriteria(value: unknown): { match: "all" | "any"; conditions: RoutingCondition[] } {
+  const input = object(value, "routing_criteria");
+  knownFields(input, ["match", "conditions"], "routing_criteria");
+  if (input.match !== "all" && input.match !== "any") {
+    throw new ApiError(400, "invalid_queue_configuration", "routing_criteria.match must be all or any.");
+  }
+  if (!Array.isArray(input.conditions) || input.conditions.length > 50) {
+    throw new ApiError(400, "invalid_queue_configuration", "routing_criteria.conditions must contain at most 50 conditions.");
+  }
+  const conditions = input.conditions.map((value, index): RoutingCondition => {
+    const condition = object(value, `routing_criteria.conditions[${index}]`);
+    knownFields(condition, ["field", "operator", "value"], `routing_criteria.conditions[${index}]`);
+    const field = stringValue(condition.field, `routing_criteria.conditions[${index}].field`, 1, 200);
+    if (!criterionFieldPattern.test(field)) {
+      throw new ApiError(400, "invalid_queue_configuration", `routing_criteria.conditions[${index}].field is not an allowed report, safeguard, or enrichment field.`);
+    }
+    if (typeof condition.operator !== "string" || !routingOperators.has(condition.operator as RoutingCondition["operator"])) {
+      throw new ApiError(400, "invalid_queue_configuration", `routing_criteria.conditions[${index}].operator is invalid.`);
+    }
+    const operator = condition.operator as RoutingCondition["operator"];
+    if (operator === "exists") {
+      if (condition.value !== undefined) throw new ApiError(400, "invalid_queue_configuration", `routing_criteria.conditions[${index}].value is not used with exists.`);
+      return { field, operator };
+    }
+    if (condition.value === undefined) throw new ApiError(400, "invalid_queue_configuration", `routing_criteria.conditions[${index}].value is required.`);
+    const parsedValue = routingValue(condition.value, `routing_criteria.conditions[${index}].value`);
+    if ((operator === "in" || operator === "not_in") && !Array.isArray(parsedValue)) {
+      throw new ApiError(400, "invalid_queue_configuration", `${operator} requires an array value.`);
+    }
+    return { field, operator, value: parsedValue };
+  });
+  return { match: input.match, conditions };
+}
+
+function stringList(value: unknown, name: string, maximum: number, allowed?: Set<string>): string[] {
+  if (!Array.isArray(value) || value.length > maximum) {
+    throw new ApiError(400, "invalid_queue_configuration", `${name} must contain at most ${maximum} identifiers.`);
+  }
+  const parsed = value.map((item, index) => identifier(item, `${name}[${index}]`));
+  if (new Set(parsed).size !== parsed.length) throw new ApiError(400, "invalid_queue_configuration", `${name} contains duplicates.`);
+  if (allowed && parsed.some((item) => !allowed.has(item))) {
+    throw new ApiError(400, "invalid_queue_configuration", `${name} contains an unsupported value.`);
+  }
+  return parsed;
+}
+
+function parseAiBounds(value: unknown): QueuePolicyInput["aiBounds"] {
+  const input = object(value ?? {}, "ai_bounds");
+  knownFields(input, [
+    "allowed_outcomes", "confidence_threshold", "max_follow_up_turns", "autonomous_actions",
+    "model", "policy_version_id", "allowed_fields", "allowed_template_ids", "max_wait_hours",
+    "daily_report_budget", "daily_cost_budget_microusd", "input_cost_microusd_per_million",
+    "output_cost_microusd_per_million", "quality_sample_rate", "minimum_shadow_runs",
+    "minimum_quality_reviews", "maximum_failure_rate", "maximum_disagreement_rate",
+  ], "ai_bounds");
+  if (input.autonomous_actions !== undefined && input.autonomous_actions !== false) {
+    throw new ApiError(400, "autonomous_actions_not_supported", "Autonomous customer application actions are disabled in the first release.");
+  }
+  const confidence = input.confidence_threshold ?? 0.85;
+  if (typeof confidence !== "number" || !Number.isFinite(confidence) || confidence < 0 || confidence > 1) {
+    throw new ApiError(400, "invalid_queue_configuration", "ai_bounds.confidence_threshold must be from 0 to 1.");
+  }
+  const model = stringValue(input.model ?? "@cf/meta/llama-3.1-8b-instruct-fast", "ai_bounds.model", 3, 200);
+  if (!model.startsWith("@cf/")) throw new ApiError(400, "invalid_queue_configuration", "ai_bounds.model must be a Workers AI @cf model.");
+  const allowedOutcomes = stringList(input.allowed_outcomes ?? [
+    "no_violation_found", "out_of_scope", "insufficient_information", "escalate_to_human",
+  ], "ai_bounds.allowed_outcomes", 50, aiOutcomes);
+  return {
+    allowedOutcomes,
+    confidenceThreshold: confidence,
+    maxFollowUpTurns: integer(input.max_follow_up_turns ?? 0, "ai_bounds.max_follow_up_turns", 0, 10),
+    autonomousActions: false,
+    model,
+    policyVersionId: identifier(input.policy_version_id ?? "general-policy-v1", "ai_bounds.policy_version_id"),
+    allowedFields: stringList(input.allowed_fields ?? ["target.type", "answers.details", "evidence.references", "enrichments"], "ai_bounds.allowed_fields", 20, aiFields),
+    allowedTemplateIds: stringList(input.allowed_template_ids ?? ["ai-more-context-v1", "ai-no-violation-v1", "ai-out-of-scope-v1"], "ai_bounds.allowed_template_ids", 20, aiTemplates),
+    maxWaitHours: integer(input.max_wait_hours ?? 168, "ai_bounds.max_wait_hours", 1, 720),
+    dailyReportBudget: integer(input.daily_report_budget ?? 100, "ai_bounds.daily_report_budget", 0, 1_000_000),
+    dailyCostBudgetMicrousd: integer(input.daily_cost_budget_microusd ?? 1_000_000, "ai_bounds.daily_cost_budget_microusd", 0, 1_000_000_000),
+    inputCostMicrousdPerMillion: integer(input.input_cost_microusd_per_million ?? 0, "ai_bounds.input_cost_microusd_per_million", 0, 1_000_000_000),
+    outputCostMicrousdPerMillion: integer(input.output_cost_microusd_per_million ?? 0, "ai_bounds.output_cost_microusd_per_million", 0, 1_000_000_000),
+    qualitySampleRate: numeric(input.quality_sample_rate ?? 0.1, "ai_bounds.quality_sample_rate", 0, 1),
+    minimumShadowRuns: integer(input.minimum_shadow_runs ?? 25, "ai_bounds.minimum_shadow_runs", 1, 100_000),
+    minimumQualityReviews: integer(input.minimum_quality_reviews ?? 10, "ai_bounds.minimum_quality_reviews", 0, 100_000),
+    maximumFailureRate: numeric(input.maximum_failure_rate ?? 0.1, "ai_bounds.maximum_failure_rate", 0, 1),
+    maximumDisagreementRate: numeric(input.maximum_disagreement_rate ?? 0.1, "ai_bounds.maximum_disagreement_rate", 0, 1),
+  };
+}
+
+export function parseQueuePolicy(value: unknown): QueuePolicyInput {
+  const input = object(value, "policy");
+  knownFields(input, [
+    "management_mode", "rollout_mode", "priority", "response_sla_minutes", "resolution_sla_minutes",
+    "claim_ttl_minutes", "fallback_queue_id", "reviewer_instructions", "ai_instructions", "ai_bounds",
+  ], "policy");
+  if (typeof input.management_mode !== "string" || !managementModes.has(input.management_mode as QueueManagementMode)) {
+    throw new ApiError(400, "invalid_queue_configuration", "policy.management_mode must be human, ai, or hybrid.");
+  }
+  const managementMode = input.management_mode as QueueManagementMode;
+  const rolloutMode = typeof input.rollout_mode === "string" ? rolloutModes.get(input.rollout_mode) : undefined;
+  if (!rolloutMode) throw new ApiError(400, "invalid_queue_configuration", "policy.rollout_mode is invalid.");
+  if (managementMode === "human" && rolloutMode !== "off") {
+    throw new ApiError(400, "invalid_queue_configuration", "Human-managed queues must use the off automation rollout.");
+  }
+  const aiInstructions = input.ai_instructions === null || input.ai_instructions === undefined
+    ? null
+    : stringValue(input.ai_instructions, "policy.ai_instructions", 10, 10_000);
+  if (managementMode !== "human" && !aiInstructions) {
+    throw new ApiError(400, "invalid_queue_configuration", "AI and hybrid queues require policy.ai_instructions.");
+  }
+  const aiBounds = parseAiBounds(input.ai_bounds);
+  if (managementMode !== "human" && rolloutMode !== "off") {
+    if (!aiBounds.allowedOutcomes.length || !aiBounds.dailyReportBudget || !aiBounds.dailyCostBudgetMicrousd) {
+      throw new ApiError(400, "invalid_queue_configuration", "Enabled AI and hybrid queues require allowed outcomes plus non-zero daily report and cost budgets.");
+    }
+    const requiredTemplates = new Map([
+      ["insufficient_information", "ai-more-context-v1"],
+      ["no_violation_found", "ai-no-violation-v1"],
+      ["out_of_scope", "ai-out-of-scope-v1"],
+    ]);
+    for (const outcome of aiBounds.allowedOutcomes) {
+      const template = requiredTemplates.get(outcome);
+      if (template && !aiBounds.allowedTemplateIds.includes(template)) {
+        throw new ApiError(400, "invalid_queue_configuration", `${outcome} requires approved template ${template}.`);
+      }
+    }
+  }
+  if (rolloutMode === "autonomous_low_priority") {
+    if (!aiBounds.inputCostMicrousdPerMillion && !aiBounds.outputCostMicrousdPerMillion) {
+      throw new ApiError(400, "invalid_queue_configuration", "Autonomous rollout requires configured model unit prices for cost enforcement.");
+    }
+    if (aiBounds.qualitySampleRate < 0.05) {
+      throw new ApiError(400, "invalid_queue_configuration", "Autonomous rollout requires at least a 5% human quality sample.");
+    }
+  }
+  return {
+    managementMode,
+    rolloutMode,
+    priority: integer(input.priority ?? 50, "policy.priority", 0, 100),
+    responseSlaMinutes: nullableInteger(input.response_sla_minutes, "policy.response_sla_minutes", 1, 525_600),
+    resolutionSlaMinutes: nullableInteger(input.resolution_sla_minutes, "policy.resolution_sla_minutes", 1, 525_600),
+    claimTtlMinutes: integer(input.claim_ttl_minutes ?? 15, "policy.claim_ttl_minutes", 1, 1_440),
+    fallbackQueueId: input.fallback_queue_id === null || input.fallback_queue_id === undefined
+      ? null : identifier(input.fallback_queue_id, "policy.fallback_queue_id"),
+    reviewerInstructions: stringValue(input.reviewer_instructions, "policy.reviewer_instructions", 10, 10_000),
+    aiInstructions,
+    aiBounds,
+  };
+}
+
+export function parseQueueCreate(value: Record<string, unknown>): QueueCreateInput {
+  knownFields(value, ["key", "name", "description", "position", "policy"], "queue");
+  const key = stringValue(value.key, "key", 2, 80);
+  if (!queueKeyPattern.test(key)) throw new ApiError(400, "invalid_queue_configuration", "key must be a lowercase kebab-case identifier.");
+  return {
+    key,
+    name: stringValue(value.name, "name", 2, 100),
+    description: value.description === undefined ? "" : stringValue(value.description, "description", 0, 1_000),
+    position: integer(value.position ?? 100, "position", 0, 10_000),
+    policy: parseQueuePolicy(value.policy),
+  };
+}
+
+export function parseQueueUpdate(value: Record<string, unknown>): QueueUpdateInput {
+  knownFields(value, ["name", "description", "position", "status"], "queue update");
+  if (!Object.keys(value).length) throw new ApiError(400, "invalid_queue_configuration", "The queue update is empty.");
+  const result: QueueUpdateInput = {};
+  if (value.name !== undefined) result.name = stringValue(value.name, "name", 2, 100);
+  if (value.description !== undefined) result.description = stringValue(value.description, "description", 0, 1_000);
+  if (value.position !== undefined) result.position = integer(value.position, "position", 0, 10_000);
+  if (value.status !== undefined) {
+    if (typeof value.status !== "string" || !queueStatuses.has(value.status as QueueStatus)) {
+      throw new ApiError(400, "invalid_queue_configuration", "status must be active, paused, or archived.");
+    }
+    result.status = value.status as QueueStatus;
+  }
+  return result;
+}