rag-v2

import type { RagCandidate, RagEvidenceBlock, RagRerankStrategy } from "./contracts";
import {
  assessCoreCorrectiveNeed,
  buildCoreCorrectiveQueryPlan,
} from "./corrective";
import type {
  RagAnswerEnvelopeOutput,
  RagDiagnostics,
  RagExecutionRoute,
  RagOrchestratorOutput,
  RagOutputForMode,
} from "./outputContracts";
import { RagQueryRewrite, type RagFileRef } from "./policyContracts";
import type {
  RagGroundingMode,
  RagOutputMode,
  RagRequestOptions,
  RagRequestedRoute,
  RagRetrievalOptions,
} from "./requestOptions";
import {
  buildRagEvidenceBlocks,
  dedupeRagCandidates,
  fuseRagCandidates,
  rerankRagCandidates,
} from "./retrievalPipeline";
import {
  hierarchicalRetrieveFromDocuments,
  lexicalRetrieveFromDocuments,
} from "./localRetrieval";
import { generateCoreQueryRewrites } from "./rewrite";
import {
  buildCoreAmbiguousGateMessage,
  buildCoreLikelyUnanswerableGateMessage,
  runCoreAnswerabilityGate,
} from "./gating";
import {
  buildCoreGroundingInstruction,
  sanitizeCoreEvidenceBlocks,
} from "./safety";
import { analyzeLargeCorpus } from "./largeCorpus";
import type {
  RagLoadedCorpus,
  RagOrchestrator,
  RagOrchestratorRequest,
  RagOrchestratorRuntime,
  RagPolicyDecision,
} from "./runtimeContracts";

const DEFAULT_MAX_EVIDENCE_BLOCKS = 5;
const DEFAULT_MAX_CANDIDATES = 8;
const DEFAULT_MULTI_QUERY_COUNT = 3;
const DEFAULT_DEDUPE_THRESHOLD = 0.85;
const DEFAULT_FULL_CONTEXT_TOKEN_LIMIT = 4000;
const DEFAULT_CORRECTIVE_MAX_ATTEMPTS = 1;
const DEFAULT_CORRECTIVE_MIN_SCORE = 0.35;
const DEFAULT_CORRECTIVE_MIN_ASPECT_COVERAGE = 0.5;

export const orchestrateRagRequest: RagOrchestrator["run"] = async (
  request,
  runtime
) => {
  const options = normalizeRequestOptions(request.options, request.outputMode, request.requestedRoute);
  const corpus = await loadCorpus(request, runtime);
  const diagnostics: RagDiagnostics = {
    route: "retrieval",
    notes: [...(corpus.analysis?.notes ?? [])],
    degraded: !runtime.semanticRetriever,
    runtimeCapabilities: collectRuntimeCapabilities(runtime),
  };
  const unsupportedClaimWarnings: Array<string> = [];

  const policyDecision = await evaluatePolicy(request.query, corpus, options, runtime);
  diagnostics.notes?.push(...(policyDecision.notes ?? []));
  unsupportedClaimWarnings.push(...(policyDecision.unsupportedClaimWarnings ?? []));

  if (policyDecision.route === "no-retrieval") {
    diagnostics.route = "no-retrieval";
    return shapeNoRetrievalOutput(request.query, corpus, options, diagnostics, unsupportedClaimWarnings);
  }

  const route = await determineRoute(request.query, corpus, options, runtime, policyDecision.route);
  diagnostics.route = route;

  if (route === "full-context") {
    const fullContextOutput = await shapeFullContextOutput(
      request.query,
      corpus,
      options,
      diagnostics,
      unsupportedClaimWarnings,
      runtime
    );
    return castOutput(fullContextOutput, request.outputMode);
  }

  if (route === "sample" || route === "global-summary") {
    const largeCorpusOutput = await shapeLargeCorpusSummaryOutput(
      request.query,
      corpus,
      route,
      options,
      diagnostics,
      unsupportedClaimWarnings,
      runtime
    );
    return castOutput(largeCorpusOutput, request.outputMode);
  }

  const retrievalResult = await runRetrievalFlow(request.query, corpus, options, runtime, route, diagnostics);
  unsupportedClaimWarnings.push(...retrievalResult.unsupportedClaimWarnings);

  const output = await shapeOutput(
    request.query,
    corpus,
    retrievalResult.candidates,
    retrievalResult.evidence,
    retrievalResult.route,
    options,
    diagnostics,
    unsupportedClaimWarnings,
    runtime
  );

  return castOutput(output, request.outputMode);
};

export const defaultRagOrchestrator: RagOrchestrator = {
  run: orchestrateRagRequest,
};

async function loadCorpus(
  request: RagOrchestratorRequest,
  runtime: RagOrchestratorRuntime
): Promise<RagLoadedCorpus> {
  const input = {
    documents: request.documents,
    paths: request.paths,
    chunks: request.chunks,
  };

  const baseCorpus = runtime.documentParser
    ? await runtime.documentParser.parse(input)
    : await runtime.loader.load(input);

  const analysis = await analyzeLargeCorpus(request.paths, request.query, baseCorpus, runtime.browser);
  if (!analysis) {
    return baseCorpus;
  }

  return {
    ...baseCorpus,
    analysis,
  };
}

async function evaluatePolicy(
  query: string,
  corpus: RagLoadedCorpus,
  options: RagRequestOptions,
  runtime: RagOrchestratorRuntime
): Promise<RagPolicyDecision> {
  if (runtime.policyEngine) {
    return runtime.policyEngine.evaluate({ query, corpus, options });
  }

  if (!options.policy?.answerabilityGateEnabled) {
    return { allowed: true };
  }

  const gateResult = runCoreAnswerabilityGate(
    query,
    corpus.documents.map((document) => ({ id: document.id, name: document.name } satisfies RagFileRef)),
    options.policy.answerabilityGateThreshold ?? 0.7
  );

  if (gateResult.decision === "no-retrieval-needed") {
    return {
      allowed: true,
      route: "no-retrieval",
      notes: gateResult.reasons,
    };
  }

  if (gateResult.decision === "ambiguous") {
    return {
      allowed: true,
      route: "no-retrieval",
      notes: gateResult.reasons,
      unsupportedClaimWarnings: [
        buildCoreAmbiguousGateMessage(
          query,
          corpus.documents.map((document) => ({ id: document.id, name: document.name })),
          options.policy.ambiguousQueryBehavior === "proceed"
            ? "attempt-best-effort"
            : "ask-clarification"
        ),
      ],
    };
  }

  if (gateResult.decision === "likely-unanswerable") {
    return {
      allowed: true,
      route: "no-retrieval",
      notes: gateResult.reasons,
      unsupportedClaimWarnings: [buildCoreLikelyUnanswerableGateMessage(query)],
    };
  }

  return {
    allowed: true,
    notes: gateResult.reasons,
  };
}

async function determineRoute(
  query: string,
  corpus: RagLoadedCorpus,
  options: RagRequestOptions,
  runtime: RagOrchestratorRuntime,
  policyRoute?: RagExecutionRoute
): Promise<RagExecutionRoute> {
  if (policyRoute) {
    return policyRoute;
  }

  const requestedRoute = options.routing?.requestedRoute;
  if (requestedRoute && requestedRoute !== "auto") {
    return normalizeRequestedRoute(requestedRoute);
  }

  if (corpus.candidates && corpus.candidates.length > 0) {
    return "prechunked-retrieval";
  }

  if (corpus.analysis?.recommendedRoute) {
    if (
      corpus.analysis.recommendedRoute === "hierarchical-retrieval" &&
      options.routing?.correctiveEnabled
    ) {
      return "corrective";
    }
    return corpus.analysis.recommendedRoute;
  }

  if (runtime.contextSizer) {
    const sizing = await runtime.contextSizer.measure({ query, corpus, options });
    if (sizing.recommendedRoute) {
      return sizing.recommendedRoute;
    }
    if (sizing.fullContextViable) {
      return "full-context";
    }
  }

  const estimatedTokens = corpus.estimatedTokens ?? 0;
  const fullContextLimit = options.routing?.fullContextTokenLimit ?? DEFAULT_FULL_CONTEXT_TOKEN_LIMIT;
  if (estimatedTokens > 0 && estimatedTokens <= fullContextLimit) {
    return "full-context";
  }

  if (options.routing?.correctiveEnabled) {
    return "corrective";
  }

  return "retrieval";
}

async function shapeFullContextOutput(
  query: string,
  corpus: RagLoadedCorpus,
  options: RagRequestOptions,
  diagnostics: RagDiagnostics,
  unsupportedClaimWarnings: Array<string>,
  runtime: RagOrchestratorRuntime
): Promise<RagOrchestratorOutput> {
  const preparedPrompt = buildFullContextPrompt(query, corpus, options.policy?.groundingMode ?? "warn-on-weak-evidence");

  if (options.outputMode === "prepared-prompt") {
    return {
      mode: "prepared-prompt",
      route: "full-context",
      preparedPrompt,
      evidence: [],
      diagnostics,
      unsupportedClaimWarnings,
    };
  }

  if (options.outputMode === "search-results") {
    return {
      mode: "search-results",
      route: "full-context",
      candidates: [],
      evidence: [],
      diagnostics,
      unsupportedClaimWarnings,
    };
  }

  const composed = await runtime.answerComposer.answer({
    query,
    corpus,
    evidence: [],
    route: "full-context",
    groundingMode: options.policy?.groundingMode,
    options,
  });

  return {
    mode: "answer-envelope",
    route: "full-context",
    answer: composed.answer,
    preparedPrompt,
    evidence: [],
    diagnostics,
    unsupportedClaimWarnings: mergeWarnings(unsupportedClaimWarnings, composed.unsupportedClaimWarnings),
    confidence: composed.confidence,
    groundingMode: options.policy?.groundingMode,
  };
}

async function shapeLargeCorpusSummaryOutput(
  query: string,
  corpus: RagLoadedCorpus,
  route: "sample" | "global-summary",
  options: RagRequestOptions,
  diagnostics: RagDiagnostics,
  unsupportedClaimWarnings: Array<string>,
  _runtime: RagOrchestratorRuntime
): Promise<RagOrchestratorOutput> {
  const summaryDocuments = corpus.analysis?.summaryDocuments ?? [];
  const summaryCorpus: RagLoadedCorpus = {
    ...corpus,
    documents: summaryDocuments,
    estimatedTokens: summaryDocuments.reduce(
      (sum, document) => sum + Math.ceil(document.content.length / 4),
      0
    ),
  };
  const preparedPrompt = buildFullContextPrompt(
    query,
    summaryCorpus,
    options.policy?.groundingMode ?? "warn-on-weak-evidence"
  );

  if (options.outputMode === "prepared-prompt") {
    return {
      mode: "prepared-prompt",
      route,
      preparedPrompt,
      evidence: [],
      diagnostics,
      unsupportedClaimWarnings,
    };
  }

  if (options.outputMode === "search-results") {
    return {
      mode: "search-results",
      route,
      candidates: [],
      evidence: [],
      diagnostics,
      unsupportedClaimWarnings,
    };
  }

  const answer = [
    `Large-corpus ${route} mode selected for: ${query}`,
    corpus.analysis?.notes.join(" ") ?? "",
    ...summaryDocuments.slice(0, 3).map((document) => `${document.name}: ${document.content}`),
  ]
    .filter(Boolean)
    .join(" ");

  return {
    mode: "answer-envelope",
    route,
    answer,
    preparedPrompt,
    evidence: [],
    diagnostics,
    unsupportedClaimWarnings,
    confidence: summaryDocuments.length > 0 ? 0.55 : 0.2,
    groundingMode: options.policy?.groundingMode,
  };
}

async function runRetrievalFlow(
  query: string,
  corpus: RagLoadedCorpus,
  options: RagRequestOptions,
  runtime: RagOrchestratorRuntime,
  initialRoute: RagExecutionRoute,
  diagnostics: RagDiagnostics
): Promise<{
  route: RagExecutionRoute;
  candidates: Array<RagCandidate>;
  evidence: Array<RagEvidenceBlock>;
  unsupportedClaimWarnings: Array<string>;
}> {
  const retrievalOptions = options.retrieval ?? {};
  const rewrites = buildRewrites(query, retrievalOptions);
  diagnostics.retrievalQueries = rewrites.map((rewrite) => rewrite.text);

  let activeRoute = initialRoute;
  let activeRewrites = rewrites;
  let attempt = 0;
  let finalCandidates: Array<RagCandidate> = [];
  let warnings: Array<string> = [];
  const maxAttempts = options.routing?.correctiveMaxAttempts ?? DEFAULT_CORRECTIVE_MAX_ATTEMPTS;

  while (attempt <= maxAttempts) {
    const candidates = await retrieveCandidates(
      query,
      corpus,
      activeRewrites,
      options,
      runtime,
      activeRoute
    );
    const filtered = candidates.filter(
      (candidate) => candidate.score >= (retrievalOptions.minScore ?? 0)
    );
    finalCandidates = await finalizeCandidates(
      query,
      filtered,
      options,
      runtime,
      diagnostics
    );

    const shouldAssessRetry =
      activeRoute === "corrective" ||
      activeRoute === "hierarchical-retrieval" ||
      (activeRoute === "retrieval" && Boolean(corpus.analysis?.hierarchicalIndex));

    if (!shouldAssessRetry) {
      break;
    }

    const assessment = assessCoreCorrectiveNeed(query, finalCandidates, {
      minAverageScore:
        activeRoute === "hierarchical-retrieval"
          ? DEFAULT_CORRECTIVE_MIN_SCORE + 0.05
          : DEFAULT_CORRECTIVE_MIN_SCORE,
      minAspectCoverage: DEFAULT_CORRECTIVE_MIN_ASPECT_COVERAGE,
      minEntryCount: Math.min(
        2,
        retrievalOptions.maxEvidenceBlocks ?? DEFAULT_MAX_EVIDENCE_BLOCKS
      ),
    });
    diagnostics.notes?.push(
      `Corrective assessment attempt ${attempt + 1} on ${activeRoute}: retry=${assessment.shouldRetry}, coverage=${assessment.matchedAspectCount}/${assessment.totalAspectCount}, avgScore=${assessment.averageScore.toFixed(2)}.`
    );

    if (!assessment.shouldRetry || attempt >= maxAttempts) {
      break;
    }

    activeRewrites = buildCoreCorrectiveQueryPlan(
      query,
      Math.max(retrievalOptions.multiQueryCount ?? DEFAULT_MULTI_QUERY_COUNT, 4)
    ).rewrites;
    warnings = mergeWarnings(warnings, assessment.reasons);

    if (activeRoute === "retrieval" && corpus.analysis?.hierarchicalIndex) {
      diagnostics.notes?.push(
        "Weak retrieval evidence triggered a hierarchical corrective retry."
      );
      activeRoute = "hierarchical-retrieval";
    } else if (activeRoute === "hierarchical-retrieval") {
      diagnostics.notes?.push(
        "Weak hierarchical evidence triggered a corrective retry with expanded rewrites."
      );
    } else {
      diagnostics.notes?.push(
        "Weak evidence triggered a corrective retry with expanded rewrites."
      );
      activeRoute = "corrective";
    }

    attempt += 1;
  }

  const evidence = await emitEvidence(finalCandidates, options, runtime);

  return {
    route: activeRoute,
    candidates: finalCandidates,
    evidence,
    unsupportedClaimWarnings: warnings,
  };
}

async function finalizeCandidates(
  query: string,
  candidates: Array<RagCandidate>,
  options: RagRequestOptions,
  runtime: RagOrchestratorRuntime,
  diagnostics: RagDiagnostics
): Promise<Array<RagCandidate>> {
  const rerankEnabled = options.rerank?.enabled ?? true;
  const rerankStrategy = options.rerank?.strategy ?? "heuristic-v1";
  const rerankTopK =
    options.rerank?.topK ??
    options.retrieval?.maxEvidenceBlocks ??
    DEFAULT_MAX_EVIDENCE_BLOCKS;

  let rerankedCandidates = candidates;

  if (rerankEnabled) {
    const heuristic = rerankRagCandidates(query, candidates, {
      topK: rerankTopK,
      strategy: rerankStrategy,
    }).map((ranked) => ({
      ...ranked.candidate,
      score: ranked.rerankScore,
    }));

    rerankedCandidates = heuristic.length > 0 ? heuristic : candidates;
    diagnostics.notes?.push(`Rerank enabled using strategy ${rerankStrategy}.`);

    if (runtime.llmReranker && rerankStrategy === "heuristic-then-llm") {
      if (runtime.rerankModelResolver) {
        const resolution = await runtime.rerankModelResolver.resolve({ options });
        diagnostics.notes?.push(
          `Resolved rerank model: ${resolution.modelId ?? "active chat model"} (${resolution.source}).`
        );
      }
      const llmRerankResult = await runtime.llmReranker.rerank({
        query,
        candidates: rerankedCandidates,
        options,
      });
      rerankedCandidates = llmRerankResult.candidates;
      diagnostics.notes?.push(...(llmRerankResult.notes ?? []));
    }
  } else {
    diagnostics.notes?.push("Rerank disabled; preserving retrieval order before dedupe.");
  }

  return dedupeRagCandidates(
    rerankedCandidates,
    options.retrieval?.dedupeSimilarityThreshold ?? DEFAULT_DEDUPE_THRESHOLD,
    options.retrieval?.maxEvidenceBlocks ?? DEFAULT_MAX_EVIDENCE_BLOCKS
  );
}

async function retrieveCandidates(
  query: string,
  corpus: RagLoadedCorpus,
  rewrites: Array<RagQueryRewrite>,
  options: RagRequestOptions,
  runtime: RagOrchestratorRuntime,
  route?: RagExecutionRoute
): Promise<Array<RagCandidate>> {
  if (corpus.candidates && corpus.candidates.length > 0) {
    return corpus.candidates.slice(0, options.retrieval?.maxEvidenceBlocks ?? DEFAULT_MAX_EVIDENCE_BLOCKS);
  }

  if (route === "hierarchical-retrieval") {
    const maxCandidates = options.retrieval?.maxCandidates ?? DEFAULT_MAX_CANDIDATES;
    if (rewrites.length <= 1) {
      return hierarchicalRetrieveFromDocuments(
        query,
        corpus.documents,
        maxCandidates,
        {
          maxParentDocuments: Math.max(2, Math.min(4, options.retrieval?.maxEvidenceBlocks ?? DEFAULT_MAX_EVIDENCE_BLOCKS)),
          maxChildChunksPerDocument: Math.max(3, options.retrieval?.maxEvidenceBlocks ?? DEFAULT_MAX_EVIDENCE_BLOCKS),
          hierarchicalIndex: corpus.analysis?.hierarchicalIndex,
        }
      );
    }

    const retrievalRuns = rewrites.map((rewrite) =>
      hierarchicalRetrieveFromDocuments(rewrite.text, corpus.documents, maxCandidates, {
        maxParentDocuments: Math.max(2, Math.min(4, options.retrieval?.maxEvidenceBlocks ?? DEFAULT_MAX_EVIDENCE_BLOCKS)),
        maxChildChunksPerDocument: Math.max(3, options.retrieval?.maxEvidenceBlocks ?? DEFAULT_MAX_EVIDENCE_BLOCKS),
        hierarchicalIndex: corpus.analysis?.hierarchicalIndex,
      })
    );

    return fuseRagCandidates(
      retrievalRuns,
      options.retrieval?.fusionMethod ?? "reciprocal-rank-fusion",
      maxCandidates
    );
  }

  if (runtime.semanticRetriever) {
    return runtime.semanticRetriever.search({
      query,
      rewrites,
      corpus,
      options,
      retrieval: options.retrieval,
    });
  }

  if (rewrites.length <= 1) {
    return runtime.retriever.search({
      query,
      corpus,
      options: options.retrieval,
    });
  }

  const retrievalRuns = await Promise.all(
    rewrites.map((rewrite) =>
      runtime.retriever.search({
        query: rewrite.text,
        corpus,
        options: options.retrieval,
      })
    )
  );

  return fuseRagCandidates(
    retrievalRuns,
    options.retrieval?.fusionMethod ?? "reciprocal-rank-fusion",
    options.retrieval?.maxCandidates ?? DEFAULT_MAX_CANDIDATES
  );
}

async function emitEvidence(
  candidates: Array<RagCandidate>,
  options: RagRequestOptions,
  runtime: RagOrchestratorRuntime
): Promise<Array<RagEvidenceBlock>> {
  const emitted = runtime.citationEmitter
    ? await runtime.citationEmitter.emit({ candidates, options })
    : buildRagEvidenceBlocks(candidates);

  return sanitizeCoreEvidenceBlocks(emitted, {
    sanitizeRetrievedText: options.safety?.sanitizeRetrievedText ?? false,
    stripInstructionalSpans: options.safety?.stripInstructionalSpans ?? false,
  });
}

async function shapeOutput(
  query: string,
  corpus: RagLoadedCorpus,
  candidates: Array<RagCandidate>,
  evidence: Array<RagEvidenceBlock>,
  route: RagExecutionRoute,
  options: RagRequestOptions,
  diagnostics: RagDiagnostics,
  unsupportedClaimWarnings: Array<string>,
  runtime: RagOrchestratorRuntime
): Promise<RagOrchestratorOutput> {
  const preparedPrompt = buildPreparedPrompt(query, route, evidence, options.policy?.groundingMode ?? "warn-on-weak-evidence");

  if (options.outputMode === "prepared-prompt") {
    return {
      mode: "prepared-prompt",
      route,
      preparedPrompt,
      evidence,
      diagnostics,
      unsupportedClaimWarnings,
    };
  }

  if (options.outputMode === "search-results") {
    return {
      mode: "search-results",
      route,
      candidates,
      evidence,
      diagnostics,
      unsupportedClaimWarnings,
    };
  }

  const composed = await runtime.answerComposer.answer({
    query,
    corpus,
    evidence,
    route,
    groundingMode: options.policy?.groundingMode,
    options,
  });

  return {
    mode: "answer-envelope",
    route,
    answer: composed.answer,
    preparedPrompt,
    evidence,
    diagnostics,
    unsupportedClaimWarnings: mergeWarnings(unsupportedClaimWarnings, composed.unsupportedClaimWarnings),
    confidence: composed.confidence,
    groundingMode: options.policy?.groundingMode,
  } satisfies RagAnswerEnvelopeOutput;
}

function buildRewrites(query: string, retrievalOptions: RagRetrievalOptions): Array<RagQueryRewrite> {
  if (!retrievalOptions.multiQueryEnabled) {
    return [{ label: "original", text: query }];
  }

  return generateCoreQueryRewrites(
    query,
    retrievalOptions.multiQueryCount ?? DEFAULT_MULTI_QUERY_COUNT
  );
}

function buildPreparedPrompt(
  query: string,
  route: RagExecutionRoute,
  evidence: Array<RagEvidenceBlock>,
  groundingMode: RagGroundingMode
) {
  const groundingInstruction = buildCoreGroundingInstruction(groundingMode);
  if (evidence.length === 0) {
    return [
      groundingInstruction,
      `Route: ${route}`,
      `User Query:\n${query}`,
      "No evidence was retrieved.",
    ].join("\n\n");
  }

  return [
    groundingInstruction,
    `Route: ${route}`,
    `User Query:\n${query}`,
    "Grounded Evidence:",
    evidence
      .map(
        (block) =>
          `${block.label} (file: ${block.fileName}, score: ${block.score.toFixed(3)}):\n${block.content}`
      )
      .join("\n\n"),
  ].join("\n\n");
}

function buildFullContextPrompt(
  query: string,
  corpus: RagLoadedCorpus,
  groundingMode: RagGroundingMode
) {
  return [
    buildCoreGroundingInstruction(groundingMode),
    `User Query:\n${query}`,
    "Attached Document Context:",
    corpus.documents
      .map((document) => `# ${document.name}\n${document.content}`)
      .join("\n\n"),
  ].join("\n\n");
}

function shapeNoRetrievalOutput(
  query: string,
  corpus: RagLoadedCorpus,
  options: RagRequestOptions,
  diagnostics: RagDiagnostics,
  unsupportedClaimWarnings: Array<string>
): RagOrchestratorOutput {
  const preparedPrompt = buildFullContextPrompt(
    query,
    corpus,
    options.policy?.groundingMode ?? "warn-on-weak-evidence"
  );

  if (options.outputMode === "prepared-prompt") {
    return {
      mode: "prepared-prompt",
      route: "no-retrieval",
      preparedPrompt,
      evidence: [],
      diagnostics,
      unsupportedClaimWarnings,
    };
  }

  if (options.outputMode === "search-results") {
    return {
      mode: "search-results",
      route: "no-retrieval",
      candidates: [],
      evidence: [],
      diagnostics,
      unsupportedClaimWarnings,
    };
  }

  return {
    mode: "answer-envelope",
    route: "no-retrieval",
    preparedPrompt,
    evidence: [],
    diagnostics,
    unsupportedClaimWarnings,
  };
}

function normalizeRequestOptions(
  options: RagRequestOptions | undefined,
  outputMode: RagOutputMode,
  requestedRoute?: RagRequestedRoute
): RagRequestOptions {
  return {
    policy: {
      groundingMode: options?.policy?.groundingMode ?? "warn-on-weak-evidence",
      answerabilityGateEnabled: options?.policy?.answerabilityGateEnabled ?? false,
      answerabilityGateThreshold: options?.policy?.answerabilityGateThreshold ?? 0.7,
      ambiguousQueryBehavior: options?.policy?.ambiguousQueryBehavior ?? "ask-for-clarification",
    },
    routing: {
      requestedRoute: options?.routing?.requestedRoute ?? requestedRoute ?? "auto",
      fullContextTokenLimit: options?.routing?.fullContextTokenLimit ?? DEFAULT_FULL_CONTEXT_TOKEN_LIMIT,
      activeModelContextTokens: options?.routing?.activeModelContextTokens,
      correctiveEnabled: options?.routing?.correctiveEnabled ?? requestedRoute === "corrective",
      correctiveMaxAttempts: options?.routing?.correctiveMaxAttempts ?? DEFAULT_CORRECTIVE_MAX_ATTEMPTS,
    },
    retrieval: {
      multiQueryEnabled: options?.retrieval?.multiQueryEnabled ?? false,
      multiQueryCount: options?.retrieval?.multiQueryCount ?? DEFAULT_MULTI_QUERY_COUNT,
      fusionMethod: options?.retrieval?.fusionMethod ?? "reciprocal-rank-fusion",
      hybridEnabled: options?.retrieval?.hybridEnabled ?? false,
      maxCandidates: options?.retrieval?.maxCandidates ?? DEFAULT_MAX_CANDIDATES,
      maxEvidenceBlocks: options?.retrieval?.maxEvidenceBlocks ?? DEFAULT_MAX_EVIDENCE_BLOCKS,
      minScore: options?.retrieval?.minScore ?? 0,
      dedupeSimilarityThreshold: options?.retrieval?.dedupeSimilarityThreshold ?? DEFAULT_DEDUPE_THRESHOLD,
    },
    rerank: {
      enabled: options?.rerank?.enabled ?? true,
      strategy: (options?.rerank?.strategy ?? "heuristic-v1") as RagRerankStrategy,
      topK: options?.rerank?.topK ?? options?.retrieval?.maxEvidenceBlocks ?? DEFAULT_MAX_EVIDENCE_BLOCKS,
    },
    safety: {
      sanitizeRetrievedText: options?.safety?.sanitizeRetrievedText ?? false,
      stripInstructionalSpans: options?.safety?.stripInstructionalSpans ?? false,
      requireEvidence: options?.safety?.requireEvidence ?? false,
    },
    outputMode,
  };
}

function normalizeRequestedRoute(route: RagRequestedRoute): RagExecutionRoute {
  if (route === "auto") {
    return "retrieval";
  }
  return route;
}

function collectRuntimeCapabilities(runtime: RagOrchestratorRuntime) {
  const capabilities = ["loader", "retriever", "answerComposer", "inspector"];
  if (runtime.documentParser) {
    capabilities.push("documentParser");
  }
  if (runtime.embeddingModelResolver) {
    capabilities.push("embeddingModelResolver");
  }
  if (runtime.rerankModelResolver) {
    capabilities.push("rerankModelResolver");
  }
  if (runtime.semanticRetriever) {
    capabilities.push("semanticRetriever");
  }
  if (runtime.llmReranker) {
    capabilities.push("llmReranker");
  }
  if (runtime.contextSizer) {
    capabilities.push("contextSizer");
  }
  if (runtime.citationEmitter) {
    capabilities.push("citationEmitter");
  }
  if (runtime.policyEngine) {
    capabilities.push("policyEngine");
  }
  return capabilities;
}

function mergeWarnings(
  left: Array<string>,
  right: Array<string> | undefined
): Array<string> {
  return [...new Set([...left, ...(right ?? [])])];
}

function castOutput<TMode extends RagOutputMode>(
  output: RagOrchestratorOutput,
  _mode: TMode
): RagOutputForMode<TMode> {
  return output as RagOutputForMode<TMode>;
}