create-safest-tools 0.2.0

package/template/src/report-ai-quality.ts

@@ -0,0 +1,390 @@
+import { canonicalJson } from "./audit";
+import { ApiError } from "./report-http";
+import type { OperatorSession } from "./report-types";
+
+const issueCodes = new Set([
+  "incorrect_outcome",
+  "incorrect_policy_code",
+  "unsupported_evidence",
+  "unsafe_or_inaccurate_message",
+  "should_have_escalated",
+  "other",
+]);
+
+interface QualityReviewInput {
+  agrees: boolean;
+  issueCodes: string[];
+  correctedOutcomeCode: string | null;
+  correctedPolicyCode: string | null;
+  notes: string;
+  idempotencyKey: string;
+}
+
+interface PauseConfig {
+  id: string;
+  mode: string;
+  enabled: number;
+  pause_state: string;
+  minimum_shadow_runs: number;
+  minimum_quality_reviews: number;
+  maximum_failure_rate: number;
+  maximum_disagreement_rate: number;
+}
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function addMinutes(timestamp: string, minutes: number): string {
+  return new Date(Date.parse(timestamp) + minutes * 60_000).toISOString();
+}
+
+function jsonValue(value: string | null): unknown {
+  if (!value) return null;
+  try { return JSON.parse(value); } catch { return null; }
+}
+
+function auditEvent(
+  db: D1Database,
+  input: { key: string; action: string; actorType: string; actorId: string; targetType: 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, ?6, ?7, ?8, ?9)
+  `).bind(
+    crypto.randomUUID(), input.key, input.action, input.actorType, input.actorId,
+    input.targetType, input.targetId, canonicalJson(input.details), input.createdAt,
+  );
+}
+
+function boundedOptional(value: unknown, name: string): string | null {
+  if (value === null || value === undefined || value === "") return null;
+  if (typeof value !== "string" || value.trim().length > 100) {
+    throw new ApiError(400, "invalid_quality_review", `${name} must contain at most 100 characters.`);
+  }
+  return value.trim() || null;
+}
+
+export function parseQualityReview(value: unknown, idempotencyKeyValue: string | null): QualityReviewInput {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ApiError(400, "invalid_quality_review", "The quality review must be an object.");
+  const input = value as Record<string, unknown>;
+  if (Object.keys(input).some((key) => !["agrees", "issue_codes", "corrected_outcome_code", "corrected_policy_code", "notes"].includes(key))) {
+    throw new ApiError(400, "invalid_quality_review", "The quality review contains unsupported fields.");
+  }
+  const idempotencyKey = idempotencyKeyValue?.trim() ?? "";
+  if (idempotencyKey.length < 8 || idempotencyKey.length > 200) {
+    throw new ApiError(400, "idempotency_key_required", "A stable Idempotency-Key header containing 8 to 200 characters is required.");
+  }
+  if (typeof input.agrees !== "boolean") throw new ApiError(400, "invalid_quality_review", "agrees must be a boolean.");
+  if (!Array.isArray(input.issue_codes) || input.issue_codes.length > 10
+    || input.issue_codes.some((code) => typeof code !== "string" || !issueCodes.has(code))) {
+    throw new ApiError(400, "invalid_quality_review", "issue_codes contains an unsupported value.");
+  }
+  const selectedIssueCodes = [...new Set(input.issue_codes as string[])];
+  const notes = typeof input.notes === "string" ? input.notes.trim() : "";
+  if (notes.length > 4_000 || (!input.agrees && notes.length < 10)) {
+    throw new ApiError(400, "invalid_quality_review", "Disagreements require notes containing 10 to 4,000 characters.");
+  }
+  if (input.agrees && selectedIssueCodes.length) throw new ApiError(400, "invalid_quality_review", "An agreeing review cannot include issue codes.");
+  if (!input.agrees && !selectedIssueCodes.length) throw new ApiError(400, "invalid_quality_review", "A disagreeing review requires at least one issue code.");
+  return {
+    agrees: input.agrees,
+    issueCodes: selectedIssueCodes,
+    correctedOutcomeCode: boundedOptional(input.corrected_outcome_code, "corrected_outcome_code"),
+    correctedPolicyCode: boundedOptional(input.corrected_policy_code, "corrected_policy_code"),
+    notes,
+    idempotencyKey,
+  };
+}
+
+export async function listAiQualitySamples(
+  db: D1Database,
+  state: "pending" | "claimed" | "complete" | null,
+  limit: number,
+  allowedQueueIds?: string[] | null,
+): Promise<Array<Record<string, unknown>>> {
+  const result = await db.prepare(`
+    SELECT qs.id, qs.report_id AS reportId, r.public_reference AS reportReference,
+      r.reason_code AS allegation, r.state AS reportState, t.target_type AS targetType,
+      qs.sample_reason AS sampleReason, qs.state, qs.selected_at AS selectedAt,
+      qs.claimed_by AS claimedBy, qs.claim_expires_at AS claimExpiresAt,
+      ar.id AS aiRunId, ar.config_version_id AS configVersionId, ar.mode, ar.status AS aiRunStatus, ar.model,
+      ar.prompt_version AS promptVersion, ar.policy_version_id AS policyVersionId,
+      ai.outcome AS aiOutcome, ai.policy_code AS aiPolicyCode, ai.confidence,
+      d.decision_code AS latestDecisionOutcome, d.maker_type AS latestDecisionMaker,
+      qr.agrees, qr.created_at AS reviewedAt
+    FROM ai_quality_samples qs
+    JOIN reports r ON r.id = qs.report_id
+    JOIN report_targets t ON t.report_id = r.id
+    JOIN ai_runs ar ON ar.id = qs.ai_run_id
+    LEFT JOIN ai_results ai ON ai.ai_run_id = ar.id
+    LEFT JOIN decisions d ON d.id = (
+      SELECT id FROM decisions WHERE report_id = r.id ORDER BY created_at DESC, id DESC LIMIT 1
+    )
+    LEFT JOIN quality_reviews qr ON qr.sample_id = qs.id
+    WHERE (?1 IS NULL OR qs.state = ?1)
+      AND (?3 = 1 OR r.queue_id IN (SELECT value FROM json_each(?4)))
+    ORDER BY CASE qs.state WHEN 'pending' THEN 0 WHEN 'claimed' THEN 1 ELSE 2 END,
+      qs.selected_at, qs.id LIMIT ?2
+  `).bind(
+    state,
+    Math.max(1, Math.min(100, limit)),
+    allowedQueueIds === null || allowedQueueIds === undefined ? 1 : 0,
+    canonicalJson(allowedQueueIds ?? []),
+  ).all<Record<string, unknown>>();
+  return result.results.map((row) => ({ ...row, agrees: row.agrees === null ? null : row.agrees === 1 }));
+}
+
+export async function loadAiQualitySample(db: D1Database, sampleId: string): Promise<Record<string, unknown> | null> {
+  const row = await db.prepare(`
+    SELECT qs.id, qs.report_id AS reportId, r.public_reference AS reportReference,
+      r.reason_code AS allegation, r.state AS reportState, t.target_type AS targetType,
+      qs.sample_reason AS sampleReason, qs.state, qs.selected_at AS selectedAt,
+      qs.claimed_by AS claimedBy, qs.claimed_at AS claimedAt, qs.claim_expires_at AS claimExpiresAt,
+      ar.id AS aiRunId, ar.config_version_id AS configVersionId, ar.mode, ar.provider, ar.model,
+      ar.prompt_version AS promptVersion, ar.policy_version_id AS policyVersionId,
+      ar.status AS aiRunStatus, ar.input_references_json AS inputReferencesJson,
+      ar.output_json AS rawOutputJson, ar.started_at AS aiStartedAt, ar.finished_at AS aiFinishedAt,
+      ai.outcome AS aiOutcome, ai.policy_code AS aiPolicyCode,
+      ai.evidence_references_json AS aiEvidenceReferencesJson, ai.summary AS aiSummary,
+      ai.confidence, ai.uncertain, ai.message_template_id AS messageTemplateId,
+      ai.message_variables_json AS messageVariablesJson, ai.action_code AS actionCode,
+      ai.escalation_code AS escalationCode, ai.validation_state AS validationState,
+      ai.validation_errors_json AS validationErrorsJson,
+      qr.id AS qualityReviewId, qr.reviewer_id AS qualityReviewerId, qr.agrees,
+      qr.issue_codes_json AS issueCodesJson, qr.corrected_outcome_code AS correctedOutcomeCode,
+      qr.corrected_policy_code AS correctedPolicyCode, qr.notes AS qualityNotes,
+      qr.created_at AS reviewedAt
+    FROM ai_quality_samples qs
+    JOIN reports r ON r.id = qs.report_id
+    JOIN report_targets t ON t.report_id = r.id
+    JOIN ai_runs ar ON ar.id = qs.ai_run_id
+    LEFT JOIN ai_results ai ON ai.ai_run_id = ar.id
+    LEFT JOIN quality_reviews qr ON qr.sample_id = qs.id
+    WHERE qs.id = ?1 LIMIT 1
+  `).bind(sampleId).first<Record<string, unknown>>();
+  if (!row) return null;
+  const tools = await db.prepare(`
+    SELECT id, tool_name AS toolName, input_references_json AS inputReferencesJson,
+      status, error_code AS errorCode, created_at AS createdAt
+    FROM ai_tool_calls WHERE ai_run_id = ?1 ORDER BY created_at, id
+  `).bind(row.aiRunId).all<Record<string, unknown>>();
+  return {
+    ...row,
+    uncertain: row.uncertain === 1,
+    agrees: row.agrees === null ? null : row.agrees === 1,
+    inputReferences: jsonValue(String(row.inputReferencesJson ?? "")),
+    rawOutput: jsonValue(row.rawOutputJson === null ? null : String(row.rawOutputJson)),
+    aiEvidenceReferences: jsonValue(row.aiEvidenceReferencesJson === null ? null : String(row.aiEvidenceReferencesJson)),
+    messageVariables: jsonValue(row.messageVariablesJson === null ? null : String(row.messageVariablesJson)),
+    validationErrors: jsonValue(row.validationErrorsJson === null ? null : String(row.validationErrorsJson)),
+    issueCodes: jsonValue(row.issueCodesJson === null ? null : String(row.issueCodesJson)),
+    toolCalls: tools.results.map((tool) => ({
+      ...tool,
+      inputReferences: jsonValue(String(tool.inputReferencesJson ?? "")),
+      inputReferencesJson: undefined,
+    })),
+    inputReferencesJson: undefined,
+    rawOutputJson: undefined,
+    aiEvidenceReferencesJson: undefined,
+    messageVariablesJson: undefined,
+    validationErrorsJson: undefined,
+    issueCodesJson: undefined,
+  };
+}
+
+export async function claimAiQualitySample(
+  db: D1Database,
+  sampleId: string,
+  session: OperatorSession,
+  ttlMinutes: number,
+): Promise<Record<string, unknown>> {
+  const claimedAt = now();
+  const expiresAt = addMinutes(claimedAt, Math.max(1, Math.min(1_440, ttlMinutes)));
+  const sample = await db.prepare(`SELECT state, claimed_by, claim_expires_at FROM ai_quality_samples WHERE id = ?1 LIMIT 1`)
+    .bind(sampleId).first<{ state: string; claimed_by: string | null; claim_expires_at: string | null }>();
+  if (!sample) throw new ApiError(404, "quality_sample_not_found", "The quality sample does not exist.");
+  if (sample.state === "complete") throw new ApiError(409, "quality_sample_complete", "This quality sample is already complete.");
+  if (sample.state === "claimed" && sample.claimed_by !== session.actor.id && (sample.claim_expires_at ?? "") > claimedAt) {
+    throw new ApiError(409, "quality_sample_claimed", "Another reviewer currently holds this quality sample.");
+  }
+  const result = await db.prepare(`
+    UPDATE ai_quality_samples SET state = 'claimed', claimed_by = ?2, claimed_at = ?3, claim_expires_at = ?4
+    WHERE id = ?1 AND state != 'complete'
+      AND (state = 'pending' OR claimed_by = ?2 OR claim_expires_at IS NULL OR claim_expires_at <= ?3)
+  `).bind(sampleId, session.actor.id, claimedAt, expiresAt).run();
+  if ((result.meta.changes ?? 0) < 1) throw new ApiError(409, "quality_sample_claimed", "Another reviewer currently holds this quality sample.");
+  await db.batch([auditEvent(db, {
+    key: `quality-claim:${sampleId}:${session.actor.id}:${claimedAt}`,
+    action: "ai.quality_sample_claimed",
+    actorType: session.actor.type,
+    actorId: session.actor.id,
+    targetType: "ai_quality_sample",
+    targetId: sampleId,
+    details: { expiresAt },
+    createdAt: claimedAt,
+  })]);
+  return { reviewerId: session.actor.id, claimedAt, expiresAt };
+}
+
+async function pauseConfiguration(
+  db: D1Database,
+  config: PauseConfig,
+  reason: "quality_threshold_exceeded" | "failure_threshold_exceeded",
+  observed: Record<string, unknown>,
+): Promise<boolean> {
+  if (config.mode !== "autonomous_low_priority" || config.enabled !== 1 || config.pause_state !== "ready") return false;
+  const pausedAt = now();
+  const result = await db.prepare(`
+    UPDATE ai_queue_config_versions SET pause_state = 'quality_paused', pause_reason = ?2, paused_at = ?3
+    WHERE id = ?1 AND pause_state = 'ready' AND enabled = 1 AND mode = 'autonomous_low_priority'
+  `).bind(config.id, reason, pausedAt).run();
+  if ((result.meta.changes ?? 0) < 1) return false;
+  await db.batch([auditEvent(db, {
+    key: `ai-auto-pause:${config.id}:${reason}`,
+    action: "ai.queue_automatically_paused",
+    actorType: "system",
+    actorId: "ai-quality-controller-v1",
+    targetType: "ai_queue_configuration",
+    targetId: config.id,
+    details: { reason, ...observed },
+    createdAt: pausedAt,
+  })]);
+  return true;
+}
+
+export async function evaluateAiFailurePause(db: D1Database, configId: string): Promise<boolean> {
+  const config = await db.prepare(`SELECT * FROM ai_queue_config_versions WHERE id = ?1 LIMIT 1`)
+    .bind(configId).first<PauseConfig>();
+  if (!config) return false;
+  const stats = await db.prepare(`
+    SELECT COUNT(*) AS total, SUM(CASE WHEN status IN ('failed', 'invalid') THEN 1 ELSE 0 END) AS failures
+    FROM ai_runs WHERE config_version_id = ?1
+  `).bind(configId).first<{ total: number; failures: number | null }>();
+  const total = stats?.total ?? 0;
+  const failures = stats?.failures ?? 0;
+  const failureRate = total ? failures / total : 0;
+  if (total < config.minimum_shadow_runs || failureRate <= config.maximum_failure_rate) return false;
+  return pauseConfiguration(db, config, "failure_threshold_exceeded", {
+    observedRuns: total,
+    observedFailures: failures,
+    observedFailureRate: failureRate,
+    configuredMaximumFailureRate: config.maximum_failure_rate,
+  });
+}
+
+export async function evaluateAiQualityPause(db: D1Database, configId: string): Promise<boolean> {
+  const config = await db.prepare(`SELECT * FROM ai_queue_config_versions WHERE id = ?1 LIMIT 1`)
+    .bind(configId).first<PauseConfig>();
+  if (!config) return false;
+  const stats = 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
+    WHERE ar.config_version_id = ?1
+  `).bind(configId).first<{ total: number; disagreements: number | null }>();
+  const total = stats?.total ?? 0;
+  const disagreements = stats?.disagreements ?? 0;
+  const disagreementRate = total ? disagreements / total : 0;
+  if (total < config.minimum_quality_reviews || disagreementRate <= config.maximum_disagreement_rate) return false;
+  return pauseConfiguration(db, config, "quality_threshold_exceeded", {
+    observedReviews: total,
+    observedDisagreements: disagreements,
+    observedDisagreementRate: disagreementRate,
+    configuredMaximumDisagreementRate: config.maximum_disagreement_rate,
+  });
+}
+
+export async function recordAiQualityReview(
+  db: D1Database,
+  sampleId: string,
+  session: OperatorSession,
+  input: QualityReviewInput,
+): Promise<{ reviewId: string; idempotentReplay: boolean; queuePaused: boolean; reportReopened: boolean }> {
+  const existing = await db.prepare(`SELECT id FROM quality_reviews WHERE idempotency_key = ?1 LIMIT 1`)
+    .bind(input.idempotencyKey).first<{ id: string }>();
+  if (existing) return { reviewId: existing.id, idempotentReplay: true, queuePaused: false, reportReopened: false };
+  const reviewedAt = now();
+  const sample = await db.prepare(`
+    SELECT qs.state, qs.claimed_by, qs.claim_expires_at, qs.report_id, ar.config_version_id,
+      r.state AS report_state
+    FROM ai_quality_samples qs JOIN ai_runs ar ON ar.id = qs.ai_run_id
+    JOIN reports r ON r.id = qs.report_id WHERE qs.id = ?1 LIMIT 1
+  `).bind(sampleId).first<{
+    state: string; claimed_by: string | null; claim_expires_at: string | null;
+    report_id: string; config_version_id: string; report_state: string;
+  }>();
+  if (!sample) throw new ApiError(404, "quality_sample_not_found", "The quality sample does not exist.");
+  if (sample.state === "complete") throw new ApiError(409, "quality_sample_complete", "This quality sample is already complete.");
+  if (sample.state !== "claimed" || sample.claimed_by !== session.actor.id || (sample.claim_expires_at ?? "") <= reviewedAt) {
+    throw new ApiError(409, "active_quality_claim_required", "Claim this quality sample before recording a review.");
+  }
+  const reviewId = crypto.randomUUID();
+  const reopen = !input.agrees && sample.report_state === "resolved_by_ai";
+  const fallback = reopen
+    ? await db.prepare(`
+        SELECT q.id, q.active_version_id
+        FROM ai_queue_config_versions c
+        JOIN queue_definitions q ON q.id = c.fallback_queue_id
+        JOIN queue_versions qv ON qv.id = q.active_version_id
+        WHERE c.id = ?1 AND q.status = 'active' AND qv.management_mode = 'human'
+        LIMIT 1
+      `).bind(sample.config_version_id).first<{ id: string; active_version_id: string }>()
+      ?? await db.prepare(`
+        SELECT q.id, q.active_version_id
+        FROM queue_definitions q JOIN queue_versions qv ON qv.id = q.active_version_id
+        WHERE q.purpose = 'reports' AND q.status = 'active' AND qv.management_mode = 'human'
+        ORDER BY q.position, q.id LIMIT 1
+      `).first<{ id: string; active_version_id: string }>()
+    : null;
+  const statements: D1PreparedStatement[] = [
+    db.prepare(`
+      INSERT INTO quality_reviews (
+        id, sample_id, reviewer_id, agrees, notes, created_at, issue_codes_json,
+        corrected_outcome_code, corrected_policy_code, idempotency_key
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)
+    `).bind(
+      reviewId, sampleId, session.actor.id, input.agrees ? 1 : 0, input.notes, reviewedAt,
+      canonicalJson(input.issueCodes), input.correctedOutcomeCode, input.correctedPolicyCode, input.idempotencyKey,
+    ),
+    db.prepare(`UPDATE ai_quality_samples SET state = 'complete', claim_expires_at = NULL WHERE id = ?1`).bind(sampleId),
+    auditEvent(db, {
+      key: `quality-review:${input.idempotencyKey}`,
+      action: "ai.quality_review_recorded",
+      actorType: session.actor.type,
+      actorId: session.actor.id,
+      targetType: "ai_quality_sample",
+      targetId: sampleId,
+      details: { agrees: input.agrees, issueCodes: input.issueCodes, reportReopened: reopen },
+      createdAt: reviewedAt,
+    }),
+  ];
+  if (reopen) {
+    statements.push(
+      db.prepare(`
+        UPDATE reports SET state = 'human_review_requested', queue_id = ?2, queue_version_id = ?3,
+          priority = MAX(priority, 70), resolved_at = NULL, updated_at = ?4
+        WHERE id = ?1 AND state = 'resolved_by_ai'
+      `).bind(sample.report_id, fallback?.id ?? null, fallback?.active_version_id ?? null, reviewedAt),
+      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, 'resolved_by_ai', 'human_review_requested', 'ai_quality_disagreement', ?3, ?4, ?5)
+      `).bind(crypto.randomUUID(), sample.report_id, session.actor.type, session.actor.id, reviewedAt),
+      auditEvent(db, {
+        key: `quality-reopen:${sampleId}`,
+        action: "ai.quality_disagreement_reopened_report",
+        actorType: session.actor.type,
+        actorId: session.actor.id,
+        targetType: "report",
+        targetId: sample.report_id,
+        details: { sampleId, issueCodes: input.issueCodes, fallbackQueueId: fallback?.id ?? null },
+        createdAt: reviewedAt,
+      }),
+    );
+  }
+  await db.batch(statements);
+  const queuePaused = await evaluateAiQualityPause(db, sample.config_version_id);
+  return { reviewId, idempotentReplay: false, queuePaused, reportReopened: reopen };
+}

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

@@ -0,0 +1,80 @@
+export type AiMode = "off" | "shadow" | "assist" | "autonomous_low_priority";
+
+export interface ValidatedAiResult {
+  outcome: string;
+  policyCode: string | null;
+  evidenceReferences: string[];
+  summary: string;
+  confidence: number | null;
+  uncertain: boolean;
+  message: { templateId: string; variables: Record<string, string> } | null;
+  actionCode: string | null;
+  escalationCode: string | null;
+}
+
+function optionalString(value: unknown, maximum: number): string | null | undefined {
+  if (value === null || value === undefined) return null;
+  if (typeof value !== "string" || !value.trim() || value.trim().length > maximum) return undefined;
+  return value.trim();
+}
+
+export function validateAiResult(
+  value: unknown,
+  bounds: { allowedOutcomes: Set<string>; allowedPolicyCodes: Set<string>; allowedEvidenceReferences: Set<string>; allowedTemplateIds: Set<string>; allowedActionCodes: Set<string>; confidenceThreshold: number },
+): { result: ValidatedAiResult | null; errors: string[] } {
+  const errors: string[] = [];
+  if (!value || typeof value !== "object" || Array.isArray(value)) return { result: null, errors: ["output_not_object"] };
+  const input = value as Record<string, unknown>;
+  const allowedKeys = new Set(["outcome", "policy_code", "evidence_references", "summary", "confidence", "uncertain", "message", "action", "escalation"]);
+  if (Object.keys(input).some((key) => !allowedKeys.has(key))) errors.push("unknown_output_field");
+  const outcome = optionalString(input.outcome, 100);
+  if (!outcome || !bounds.allowedOutcomes.has(outcome)) errors.push("outcome_not_allowed");
+  const policyCode = optionalString(input.policy_code, 100);
+  if (outcome !== "escalate_to_human" && (!policyCode || !bounds.allowedPolicyCodes.has(policyCode))) errors.push("policy_code_not_allowed");
+  const summary = optionalString(input.summary, 500);
+  if (!summary) errors.push("summary_invalid");
+  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.uncertain !== "boolean") errors.push("uncertainty_invalid");
+  const uncertain = input.uncertain === true || confidence === null || confidence < bounds.confidenceThreshold;
+  const evidenceReferences = Array.isArray(input.evidence_references)
+    ? input.evidence_references.filter((entry): entry is string => typeof entry === "string" && entry.length <= 2_048)
+    : [];
+  if (!Array.isArray(input.evidence_references) || evidenceReferences.length !== input.evidence_references.length
+    || evidenceReferences.some((reference) => !bounds.allowedEvidenceReferences.has(reference))) errors.push("evidence_reference_not_supplied");
+
+  let message: ValidatedAiResult["message"] = null;
+  if (input.message !== null && input.message !== undefined) {
+    if (!input.message || typeof input.message !== "object" || Array.isArray(input.message)) errors.push("message_invalid");
+    else {
+      const messageInput = input.message as Record<string, unknown>;
+      const templateId = optionalString(messageInput.template_id, 100);
+      const variablesInput = messageInput.variables;
+      const variables: Record<string, string> = {};
+      if (!templateId || !bounds.allowedTemplateIds.has(templateId)) errors.push("message_template_not_allowed");
+      if (!variablesInput || typeof variablesInput !== "object" || Array.isArray(variablesInput)) errors.push("message_variables_invalid");
+      else for (const [key, child] of Object.entries(variablesInput)) {
+        if (!/^[a-z][a-z0-9_]{0,49}$/u.test(key) || typeof child !== "string" || child.trim().length < 1 || child.trim().length > 160) {
+          errors.push("message_variables_invalid");
+          break;
+        }
+        variables[key] = child.trim();
+      }
+      if (templateId && bounds.allowedTemplateIds.has(templateId)) message = { templateId, variables };
+    }
+  }
+  if (outcome === "insufficient_information" && !message) errors.push("follow_up_message_required");
+  const actionCode = input.action === null || input.action === undefined ? null : optionalString(input.action, 100);
+  if (actionCode === undefined || actionCode && !bounds.allowedActionCodes.has(actionCode)) errors.push("action_not_allowed");
+  const escalationCode = input.escalation === null || input.escalation === undefined ? null : optionalString(input.escalation, 100);
+  if (escalationCode === undefined) errors.push("escalation_invalid");
+  if (errors.length || !outcome || !summary) return { result: null, errors: [...new Set(errors)] };
+  return {
+    result: {
+      outcome, policyCode: policyCode ?? null, evidenceReferences, summary, confidence, uncertain,
+      message, actionCode: actionCode ?? null, escalationCode: escalationCode ?? null,
+    },
+    errors: [],
+  };
+}