import { createChartArtifact } from "./chart.js";
import { readMetric } from "./data.js";
import { searchLearn } from "./learn.js";
import {
  metricByName,
  metricCategories,
  metricVariants,
  searchMetrics,
} from "./metrics/index.js";
import { ASK_STAGE_PROMPTS } from "./prompts.js";
import { AskRefs } from "./refs.js";
import { renderData, renderEvidence } from "./render.js";
import {
  clarifyTool,
  navigateTool,
  resolveTool,
  rewriteTool,
  searchTool,
} from "./schemas.js";
import { normalize } from "./text.js";

const MAX_OPTIONS = 12;
const MAX_CATEGORIES = 24;

/** @typedef {import("../storage.js").ChartArtifact} ChartArtifact */

/**
 * @typedef {Object} MetricOption
 * @property {string} ref
 * @property {string} label
 * @property {any} metric
 */

/** @param {unknown} value @param {string} name */
function requiredString(value, name) {
  if (typeof value !== "string" || !value.trim()) throw new Error(`${name} is required`);
  return value.trim();
}

/** @param {unknown} value @param {string} name */
function requiredStrings(value, name) {
  if (
    !Array.isArray(value) ||
    !value.length ||
    value.some((item) => typeof item !== "string" || !item.trim())
  ) throw new Error(`${name} are required`);
  return [...new Set(value.map((item) => item.trim()))];
}

/** @param {unknown} value */
function uniqueRefs(value) {
  if (!Array.isArray(value) || !value.length || value.some((ref) => typeof ref !== "string")) {
    throw new Error("One or more returned references are required");
  }
  return [...new Set(value)];
}

/** @param {string} value */
function label(value) {
  return value.replaceAll("_", " ");
}

/** @param {string} value */
function isExplicitComparison(value) {
  return /\b(?:vs\.?|versus|compare|compared|comparison)\b/i.test(value);
}

/** @param {string} value */
function referencesPrevious(value) {
  return /\b(?:it|its|that|this|they|their|them|those|these|same)\b/i.test(value);
}

/** @param {string} request */
function isDirectValueFollowup(request) {
  const text = normalize(request);
  const hasPoint = /\b(?:current|currently|latest|now|today)\b/.test(text) ||
    /\bblock\s+\d{4,}\b/.test(text) ||
    /\b\d{4}-\d{2}-\d{2}\b/.test(text);
  const needsInterpretation = /^(?:how|why)\b/.test(text) ||
    /\b(?:available|availability|chart|cohorts?|code|explain|formula|graph|history|plot|source|trend|variants?)\b/.test(text);
  return referencesPrevious(text) && hasPoint && !needsInterpretation;
}

/** @param {string} request @param {string} proposed */
function evidenceFocus(request, proposed) {
  if (/\b(?:cohorts?|variants?|availability|available)\b/i.test(request)) return "variants";
  if (/\b(?:source|code|implemented?|implementation|calculated?|calculation|formula)\b/i.test(request)) {
    return "implementation";
  }
  return proposed;
}

/** @param {string} request */
function isDirectDefinition(request) {
  const text = normalize(request);
  const asks = /\b(?:define|explain|meaning)\b/.test(text) ||
    /^(?:what is|what are)\b/.test(text);
  const needsRouting = /\b(?:available|availability|chart|cohorts?|code|current|file|graph|history|latest|now|path|plot|source|today|trend|variants?)\b/.test(text) ||
    /\bblock\s+\d+\b/.test(text) ||
    /\b\d{4}-\d{2}-\d{2}\b/.test(text);
  return asks && !needsRouting;
}

/** @param {string} request */
function directReadAction(request) {
  const block = request.match(/\bblock\s+(\d{4,})\b/i)?.[1];
  const dates = [...request.matchAll(/\b\d{4}-\d{2}-\d{2}\b/g)].map(([date]) => date);
  if (block) return { mode: "at", index: "height", at: block };
  if (dates.length === 1) return { mode: "at", index: "day1", at: dates[0] };
  if (dates.length > 1 || /\b(?:ago|before|after|between|from|last|previous|since|yesterday)\b/i.test(request)) {
    return undefined;
  }
  return { mode: "latest" };
}

/** @param {string[]} queries */
function completeComparisonQueries(queries) {
  if (queries.length < 3) return queries;

  const shared = queries.at(-1) ?? "";
  const qualifiers = queries.slice(0, -1);
  if (!qualifiers.every((query) => normalize(query).split(" ").length === 1)) return queries;

  return qualifiers.map((qualifier) => `${qualifier} ${shared}`);
}

/** @param {any[]} history */
function latestChart(history) {
  for (const message of [...history].reverse()) {
    const chart = message.artifacts?.findLast?.(
      (/** @type {any} */ artifact) => artifact.type === "chart",
    );
    if (chart) return chart;
  }
  return undefined;
}

/** @param {any[]} items */
function uniqueMetricOptions(items) {
  return [...new Map(items.map((/** @type {any} */ item) => [item.ref, item])).values()];
}

/** @param {any[][]} groups */
function mergeMetricGroups(groups) {
  const output = [];
  const positions = new Map();
  const ranks = Math.max(...groups.map((group) => group.length), 0);

  for (let rank = 0; rank < ranks && output.length < MAX_OPTIONS; rank += 1) {
    for (const group of groups) {
      const metric = group[rank];
      if (!metric) continue;

      const position = positions.get(metric.path);
      if (position !== undefined) {
        const current = output[position];
        const exact = normalize(metric.name) === normalize(metric.matchedQuery ?? "");
        const currentExact = normalize(current.name) === normalize(current.matchedQuery ?? "");
        if (exact && !currentExact) output[position] = metric;
        continue;
      }
      positions.set(metric.path, output.length);
      output.push(metric);
      if (output.length === MAX_OPTIONS) break;
    }
  }
  return output;
}

/** @param {any[]} items */
function balancedOptions(items) {
  const order = ["fact", "guide", "metric", "source"];
  const groups = order
    .map((kind) => items
      .filter((item) => item.kind === kind)
      .sort((left, right) => right.score - left.score))
    .filter((group) => group.length);
  const output = [];

  for (let rank = 0; output.length < MAX_OPTIONS; rank += 1) {
    let added = false;
    for (const group of groups) {
      const item = group[rank];
      if (!item) continue;
      const { score, ...option } = item;
      output.push(option);
      added = true;
      if (output.length === MAX_OPTIONS) break;
    }
    if (!added) break;
  }
  return output;
}

export class AskToolSession {
  /** @param {import("./source/index.js").AskSource} source */
  constructor(source) {
    this.source = source;
  }

  source;
  refs = new AskRefs();
  request = "";
  /** @type {string[]} */
  previousTopics = [];
  query = "";
  /** @type {string[]} */
  queries = [];
  outcome = "";
  focus = "definition";
  stage = "search";
  directMatch = false;
  rewritten = false;
  rewriteChanged = false;
  comparison = false;
  /** @type {string[]} */
  categoryPaths = [];
  /** @type {any} */
  observation;
  /** @type {any[]} */
  options = [];
  /** @type {MetricOption[]} */
  metricOptions = [];
  /** @type {any} */
  formula;
  sourceSearched = false;
  /** @type {ChartArtifact | undefined} */
  activeChart;

  /** @param {string} request @param {any[]} history */
  begin(request, history) {
    this.refs = new AskRefs();
    this.request = request.trim();
    this.query = "";
    this.queries = [];
    this.outcome = "";
    this.focus = "definition";
    this.stage = "search";
    this.directMatch = false;
    this.rewritten = false;
    this.rewriteChanged = false;
    this.comparison = false;
    this.categoryPaths = [];
    this.observation = undefined;
    this.options = [];
    this.metricOptions = [];
    this.formula = undefined;
    this.sourceSearched = false;
    this.activeChart ??= latestChart(history);
  }

  /** @param {(status: string) => void} onStatus */
  async tryDirect(onStatus) {
    if (this.previousTopics.length === 1 && isDirectValueFollowup(this.request)) {
      const action = directReadAction(this.request);
      if (action) {
        const topic = this.previousTopics[0];
        const metrics = (await searchMetrics(
          [topic],
          3,
          [],
          () => onStatus("Indexing metrics…"),
        )).filter((metric) => normalize(metric.name) === normalize(topic));

        if (metrics.length === 1) {
          onStatus("Reading data…");
          const result = await readMetric(metrics[0], action);
          this.previousTopics = [label(metrics[0].name)];
          return { output: renderData([result]), artifacts: [] };
        }
      }
    }

    if (!isDirectDefinition(this.request)) return undefined;

    const [metric] = await searchMetrics(
      [this.request],
      1,
      [],
      () => onStatus("Indexing metrics…"),
    );
    if (!metric) return undefined;

    onStatus("Searching source…");
    const formula = await this.source.explain(
      `${this.request}\n${metric.name}`,
      ({ loaded, total }) => onStatus(`Indexing source · ${loaded} / ${total}`),
    );
    if (!formula || normalize(formula.fact.metric) !== normalize(metric.name)) return undefined;

    this.previousTopics = [label(formula.fact.metric)];
    return { output: formula.answer, artifacts: [] };
  }

  async tool() {
    if (this.stage === "search") {
      const categories = await metricCategories();
      return searchTool(
        Boolean(this.activeChart),
        this.previousTopics.length > 0,
        categories,
      );
    }
    if (this.stage === "rewrite") return rewriteTool(this.queries);
    if (this.stage === "navigate") return navigateTool(this.options);
    if (this.stage === "resolve") {
      const maxItems = this.formula
        ? 1
        : this.outcome === "explain_from_verified_facts"
          ? Math.min(this.queries.length, 3)
          : this.comparison
            ? this.outcome === "read_requested_value" ? 3 : 6
            : 1;
      const options = this.outcome === "explain_from_verified_facts"
        ? this.options
        : this.metricOptions;
      return resolveTool(options, this.outcome, Math.max(1, maxItems));
    }
    return clarifyTool();
  }

  instruction() {
    if (this.stage === "search") {
      const previous = this.previousTopics.length
        ? `\nPrevious verified topic${this.previousTopics.length === 1 ? "" : "s"}: ${this.previousTopics.join(", ")}. Reuse only when the newest request depends on it.`
        : "";
      const chart = this.activeChart
        ? `\nActive chart: ${this.activeChart.chart.title}; series: ${this.activeChart.chart.series.map((item) => item.label).join(", ")}.`
        : "";
      return `${ASK_STAGE_PROMPTS.search}${previous}${chart}`;
    }
    if (this.stage === "navigate") return ASK_STAGE_PROMPTS.navigate;
    if (this.stage === "rewrite") return ASK_STAGE_PROMPTS.rewrite;
    if (this.stage === "resolve") {
      if (this.outcome === "explain_from_verified_facts") {
        return this.directMatch
          ? `${ASK_STAGE_PROMPTS.explain}\nA trusted direct match exists. Use only recommendedRefs.`
          : ASK_STAGE_PROMPTS.explain;
      }
      if (this.outcome === "read_requested_value") return ASK_STAGE_PROMPTS.read;
      return this.outcome === "edit_existing_chart"
        ? ASK_STAGE_PROMPTS.editChart
        : ASK_STAGE_PROMPTS.chart;
    }
    return ASK_STAGE_PROMPTS.clarify;
  }

  /** @param {(status: string) => void} onStatus */
  async search(onStatus) {
    const [globalMetrics, rawMetrics, scopedMetrics, guideGroups] = await Promise.all([
      searchMetrics(
        this.queries,
        MAX_OPTIONS,
        [],
        () => onStatus("Indexing metrics…"),
      ),
      searchMetrics(
        [this.request],
        MAX_OPTIONS,
        [],
        () => onStatus("Indexing metrics…"),
      ),
      searchMetrics(
        this.queries,
        MAX_OPTIONS,
        this.categoryPaths,
        () => onStatus("Indexing metrics…"),
      ),
      Promise.all(this.queries.map((query) => searchLearn(query, MAX_OPTIONS))),
    ]);
    const foundMetrics = mergeMetricGroups([globalMetrics, rawMetrics, scopedMetrics]);
    const metrics = [...foundMetrics];
    const metricNames = new Set(metrics.map((metric) => metric.name));
    const guides = [...new Map(
      guideGroups.flat().map((/** @type {any} */ guide) => [guide.breadcrumbs.join("/"), guide]),
    ).values()].filter((/** @type {any} */ guide) =>
      this.outcome === "explain_from_verified_facts" ||
      guide.series.some((/** @type {any} */ series) => metricNames.has(series.name))
    );
    /** @type {any[]} */
    let sources = [];

    if (
      this.outcome === "explain_from_verified_facts" &&
      this.focus !== "variants" &&
      !this.sourceSearched
    ) {
      this.sourceSearched = true;
      onStatus("Searching source…");
      const originalMetric = foundMetrics.find((metric) =>
        normalize(metric.matchedQuery ?? "") === normalize(this.request)
      );
      this.formula = await this.source.explain(
        [this.request, originalMetric?.name, ...this.queries].filter(Boolean).join("\n"),
        ({ loaded, total }) => onStatus(`Indexing source · ${loaded} / ${total}`),
      );
      if (!this.formula) {
        sources = (await this.source.search(
          this.queries.join(" "),
          undefined,
          ({ loaded, total }) => onStatus(`Indexing source · ${loaded} / ${total}`),
        )).matches;
      } else {
        const formulaMetric = await metricByName(this.formula.fact.metric);
        if (formulaMetric && !metrics.some((metric) => metric.path === formulaMetric.path)) {
          metrics.unshift({
            ...formulaMetric,
            matchedQuery: label(this.formula.fact.metric),
            score: 2_000,
          });
        }
      }
    }

    /** @type {any[]} */
    const ranked = [];
    for (const metric of metrics) {
      const ref = this.refs.issue("metric", metric, metric.path);
      ranked.push({
        ref,
        kind: "metric",
        label: label(metric.name),
        detail: metric.path,
        matchedQuery: metric.matchedQuery,
        score: metric.score,
      });
    }
    for (const guide of guides) {
      const key = guide.breadcrumbs.join("/");
      const ref = this.refs.issue("guide", guide, key);
      ranked.push({
        ref,
        kind: "guide",
        label: guide.title,
        detail: guide.description,
        score: guide.score,
      });
    }
    for (const source of sources) {
      const ref = this.refs.issue("source", source, `${source.path}:${source.startLine}`);
      ranked.push({
        ref,
        kind: "source",
        label: `${source.path}:${source.startLine}`,
        detail: source.content,
        score: source.score,
      });
    }
    if (this.formula && !metrics.length) {
      const ref = this.refs.issue("fact", this.formula, this.formula.fact.metric);
      ranked.push({
        ref,
        kind: "fact",
        label: label(this.formula.fact.metric),
        detail: this.formula.answer,
        score: 1_000,
      });
    }

    this.options = balancedOptions(ranked);
    if (!this.options.length) {
      this.stage = "clarify";
      this.observation = { noMatch: true };
      return;
    }

    const normalizedQueries = this.queries.map(normalize);
    const exactCandidates = this.options.filter((option) =>
      option.kind === "metric" &&
      normalize(option.label) === normalize(option.matchedQuery ?? "")
    );
    const exact = exactCandidates.filter((option) => {
      const optionLabel = normalize(option.label);
      return !exactCandidates.some((candidate) => {
        const candidateLabel = normalize(candidate.label);
        return candidateLabel !== optionLabel && candidateLabel.includes(optionLabel);
      });
    });
    const exactByQuery = normalizedQueries.map((query) =>
      exact.filter((option) => normalize(option.matchedQuery ?? "") === query)
    );
    this.directMatch = exactByQuery.every((matches) => matches.length === 1);
    const directOptions = exactByQuery.flat();
    const trusted = this.directMatch ||
      this.comparison && metrics.length > 0 ||
      this.rewritten && this.rewriteChanged && metrics.length > 0 ||
      Boolean(this.formula) ||
      sources.length > 0 ||
      this.outcome !== "explain_from_verified_facts" && guides.length > 0;
    if (!trusted && !this.categoryPaths.length) {
      if (!this.rewritten) {
        this.stage = "rewrite";
        this.observation = { unmatchedQueries: this.queries };
        return;
      }
      this.options = (await metricCategories()).slice(0, MAX_CATEGORIES).map((category) => ({
        ref: this.refs.issue("category", category, category.path),
        kind: "category",
        label: category.label,
        detail: `${category.count} series; ${category.examples.join(", ")}`,
      }));
      this.stage = "navigate";
      this.observation = { options: this.options };
      return;
    }

    if (
      this.directMatch &&
      this.outcome === "explain_from_verified_facts" &&
      this.focus === "variants"
    ) {
      onStatus("Inspecting results…");
      return this.inspect(directOptions.map(({ ref }) => ref));
    }
    if (this.directMatch && this.outcome === "read_requested_value") {
      const action = directReadAction(this.request);
      if (action) {
        const refs = directOptions.map(({ ref }) => ref);
        this.rememberMetrics(refs);
        onStatus("Reading data…");
        return this.read({ refs, ...action });
      }
    }
    if (this.directMatch && this.outcome === "build_requested_chart") {
      const refs = directOptions.map(({ ref }) => ref);
      this.rememberMetrics(refs);
      onStatus("Building chart…");
      return this.buildChart({ refs });
    }

    this.stage = "resolve";
    const formulaOption = this.formula
      ? this.options.find((option) =>
        option.kind === "metric" &&
        normalize(option.label) === normalize(this.formula.fact.metric)
      )
      : undefined;
    if (this.outcome === "explain_from_verified_facts") {
      if (formulaOption) return this.inspect([formulaOption.ref]);

      this.observation = {
        recommendedRefs: (directOptions.length ? directOptions : this.options)
          .slice(0, 3)
          .map(({ ref }) => ref),
        options: this.options,
      };
      return;
    }

    await this.prepareMetricOptions();
  }

  /** @param {string[]} queries @param {(status: string) => void} onStatus */
  async rewrite(queries, onStatus) {
    this.rewriteChanged = queries.length !== this.queries.length ||
      queries.some((query, index) => normalize(query) !== normalize(this.queries[index] ?? ""));
    this.queries = queries;
    this.query = queries.join(" / ");
    this.rewritten = true;
    return await this.search(onStatus) ?? { done: false };
  }

  /** @param {string[]} selected @param {(status: string) => void} onStatus */
  async navigate(selected, onStatus) {
    const categories = selected.map((ref) => this.refs.get(ref, "category"));
    this.categoryPaths = categories.map((category) => category.path);
    const prefix = categories.map((category) => category.label).join(" ");
    this.queries = this.queries.map((query) => `${prefix} ${query}`);
    this.query = this.queries.join(" / ");
    return await this.search(onStatus) ?? { done: false };
  }

  async prepareMetricOptions() {
    /** @type {MetricOption[]} */
    const metrics = [];

    for (const option of this.options) {
      const kind = this.refs.kind(option.ref);
      if (kind === "metric") {
        const metric = this.refs.get(option.ref, "metric");
        metrics.push({ ref: option.ref, label: metric.label ?? label(metric.name), metric });
      } else if (kind === "guide") {
        const guide = this.refs.get(option.ref, "guide");
        for (const series of guide.series) {
          const metric = await metricByName(series.name);
          if (!metric) continue;
          const value = { ...metric, label: series.label };
          const ref = this.refs.issue("metric", value, metric.path);
          metrics.push({ ref, label: series.label, metric: value });
        }
      }
    }

    this.metricOptions = uniqueMetricOptions(metrics).slice(0, MAX_OPTIONS);
    if (!this.metricOptions.length) {
      this.stage = "clarify";
      this.observation = { noMetric: true };
      return;
    }
    this.observation = {
      verifiedMetrics: this.metricOptions.map(({ ref, label: metricLabel, metric }) => ({
        ref,
        label: metricLabel,
        path: metric.path,
        unit: metric.suggestedUnit,
      })),
    };
  }

  /** @param {string[]} selected */
  async inspect(selected) {
    const evidence = {
      facts: /** @type {string[]} */ ([]),
      sources: /** @type {string[]} */ ([]),
      excerpts: /** @type {any[]} */ ([]),
    };
    /** @type {string[]} */
    const topics = [];

    for (const ref of selected) {
      const kind = this.refs.kind(ref);
      if (kind === "fact") {
        const fact = this.refs.get(ref, "fact");
        topics.push(label(fact.fact.metric));
        evidence.facts.push(fact.answer);
        evidence.sources.push(`${fact.fact.path}:${fact.fact.line}`);
      } else if (kind === "source") {
        const match = this.refs.get(ref, "source");
        const excerpt = await this.source.read(match.path, match.startLine, match.endLine);
        evidence.excerpts.push(excerpt);
        evidence.sources.push(`${excerpt.path}:${excerpt.startLine}-${excerpt.endLine}`);
      } else if (kind === "guide") {
        const guide = this.refs.get(ref, "guide");
        if (guide.description) evidence.facts.push(guide.description);
        topics.push(...guide.series.map((/** @type {any} */ series) => label(series.name)));
      } else if (kind === "metric") {
        const metric = this.refs.get(ref, "metric");
        topics.push(label(metric.name));
        const variants = this.focus === "variants"
          ? await metricVariants(metric, this.query)
          : undefined;
        if (variants) {
          const groups = variants.groups
            .map((group) => `${group.family}: ${group.examples.join(", ")}`)
            .join("; ");
          evidence.facts.push(
            `${label(metric.name)} has ${variants.totalSeries} available series. Cohorts: ${groups}.`,
          );
        }
      }
    }

    if (this.formula && selected.some((ref) => this.refs.kind(ref) === "metric")) {
      evidence.facts.unshift(this.formula.answer);
      evidence.sources.push(`${this.formula.fact.path}:${this.formula.fact.line}`);
    }

    this.previousTopics = [...new Set(topics.length ? topics : this.queries)].slice(0, 4);
    return { done: true, output: renderEvidence(evidence) };
  }

  /** @param {Record<string, unknown>} action */
  async read(action) {
    const selected = uniqueRefs(action.refs);
    const block = this.request.match(/\b(?:block\s*)?(\d{4,})\b/i)?.[1];
    const date = this.request.match(/\b\d{4}-\d{2}-\d{2}\b/)?.[0];
    const request = action.mode === "at" && action.at === undefined
      ? { ...action, at: block ?? date }
      : action;
    const results = await Promise.all(
      selected.map((ref) => readMetric(this.refs.get(ref, "metric"), request)),
    );
    return { done: true, output: renderData(results) };
  }

  /** @param {Record<string, unknown>} action */
  buildChart(action) {
    const selected = uniqueRefs(action.refs);
    const chosen = selected.map((ref) => this.refs.get(ref, "metric"));
    const existingChart = this.outcome === "edit_existing_chart"
      ? this.activeChart
      : undefined;
    const operation = typeof action.operation === "string" ? action.operation : "add";
    const added = chosen.map((/** @type {any} */ metric) => ({
      path: metric.path,
      label: metric.label ?? label(metric.name),
    }));
    const prior = existingChart?.chart.series ?? [];
    const paths = new Set(added.map(({ path }) => path));
    const series = !existingChart || operation === "replace"
      ? added
      : operation === "remove"
        ? prior.filter((item) => !paths.has(item.path))
        : [...prior, ...added.filter((item) => !prior.some((old) => old.path === item.path))];
    if (!series.length) throw new Error("A chart needs at least one series");

    const inferredUnit = chosen.map((metric) => metric.suggestedUnit).find(Boolean);
    const artifact = createChartArtifact({
      title: typeof action.title === "string" && action.title.trim()
        ? action.title.trim()
        : existingChart
          ? existingChart.chart.title
          : chosen.map((metric) => metric.label ?? label(metric.name)).join(" and "),
      unit: existingChart ? existingChart.chart.unit : inferredUnit,
      series,
    });
    this.activeChart = artifact;
    return {
      done: true,
      output: `${existingChart ? "Updated" : "Built"} **${artifact.chart.title}** with ${artifact.chart.series.map((item) => item.label).join(", ")}.`,
      artifacts: [artifact],
    };
  }

  /**
   * @param {Record<string, unknown>} action
   * @param {(status: string) => void} onStatus
   */
  async execute(action, onStatus) {
    const name = requiredString(action.action, "action");
    if (this.stage === "search") {
      if (name !== "search") throw new Error("The AI chose an invalid search action");
      const context = requiredString(action.context, "context");
      const proposed = requiredStrings(action.queries, "queries");
      const cardinality = requiredString(action.cardinality, "cardinality");
      const families = requiredStrings(action.families, "families")
        .filter((family) => family !== "auto");
      const dependent = this.previousTopics.length > 0 && referencesPrevious(this.request);
      const effectiveContext = dependent
        ? isExplicitComparison(this.request) ? "extend_previous" : "reuse_previous"
        : context;
      if (effectiveContext !== "new_topic" && !this.previousTopics.length) {
        throw new Error("There is no previous verified topic to reuse");
      }
      const routedQueries = effectiveContext === "reuse_previous"
        ? [...this.previousTopics]
        : effectiveContext === "extend_previous"
          ? [...new Set([...this.previousTopics, ...proposed])]
          : proposed;
      this.outcome = requiredString(action.outcome, "outcome");
      this.focus = evidenceFocus(this.request, requiredString(action.focus, "focus"));
      this.comparison = cardinality === "multiple" || isExplicitComparison(this.request);
      this.queries = this.comparison
        ? completeComparisonQueries(routedQueries)
        : routedQueries.slice(0, 1);
      this.categoryPaths = this.comparison || dependent ? [] : families;
      this.query = this.queries.join(" / ");
      return await this.search(onStatus) ?? { done: false };
    }
    if (this.stage === "resolve" && this.outcome === "explain_from_verified_facts") {
      if (name !== "answer") throw new Error("The AI chose an invalid evidence action");
      onStatus("Inspecting results…");
      return this.inspect(uniqueRefs(action.refs));
    }
    if (this.stage === "navigate") {
      if (name !== "navigate") throw new Error("The AI chose an invalid navigation action");
      onStatus("Narrowing search…");
      return this.navigate(uniqueRefs(action.refs), onStatus);
    }
    if (this.stage === "rewrite") {
      if (name !== "rewrite") throw new Error("The AI chose an invalid rewrite action");
      onStatus("Refining search…");
      return this.rewrite(requiredStrings(action.queries, "queries"), onStatus);
    }
    if (this.stage === "resolve" && this.outcome === "read_requested_value") {
      if (name !== "read_data") throw new Error("The AI chose an invalid data action");
      this.rememberMetrics(uniqueRefs(action.refs));
      onStatus("Reading data…");
      return this.read(action);
    }
    if (this.stage === "resolve") {
      if (name !== "build_chart" && name !== "edit_chart") {
        throw new Error("The AI chose an invalid chart action");
      }
      this.rememberMetrics(uniqueRefs(action.refs));
      onStatus("Building chart…");
      return this.buildChart(action);
    }
    if (name !== "clarify") throw new Error("The AI chose an invalid clarification action");
    return { done: true, output: requiredString(action.text, "text") };
  }

  /** @param {string[]} refs */
  rememberMetrics(refs) {
    this.previousTopics = refs
      .map((ref) => label(this.refs.get(ref, "metric").name))
      .filter((topic, index, topics) => topics.indexOf(topic) === index)
      .slice(0, 4);
  }
}