Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

57.1 KB
Raw Blame
import { beforeEach, describe, expect, it, vi } from "vitest";
import type {
  TopicAssignment,
  TopicEmbeddingConfig,
  TopicExecution,
  TopicFacetVersion,
  TopicFacetRef,
  TopicRun,
  TopicProcessBatchState,
  TopicSummary,
  TopicTimeRange,
} from "@langfuse/shared/topics";
import {
  TOPICS_TRANSCRIPT_VERSION,
  getTopicClusteringSummaries,
  type TopicEmbeddingBatch,
  type TopicEmbeddingRef,
} from "@langfuse/shared/topics/server";
import { assembleTranscript } from "@langfuse/shared/src/server";
import {
  topicExecutionInputSchema,
  topicSourceKey,
} from "@langfuse/shared/topics";
import {
  TopicsProviderUnavailable,
  topicProviderError,
} from "./provider-error";

const state = vi.hoisted(() => ({
  batches: new Map<string, TopicProcessBatchState>(),
  executions: new Map<string, TopicExecution>(),
  summaries: new Map<string, TopicSummary>(),
  staged: new Map<
    string,
    { summary: TopicSummary; embeddingConfig: TopicEmbeddingConfig }
  >(),
  embeddingBatches: new Map<string, TopicEmbeddingBatch>(),
  completedBatches: new Set<string>(),
  deferEmbeddings: false,
  runs: new Map<string, TopicRun>(),
  assignments: new Map<string, TopicAssignment>(),
  facets: new Map<string, TopicFacetVersion>(),
  visible: true,
  resultReads: vi.fn(),
  assignmentWrites: vi.fn(),
  saveBatch: vi.fn(),
  saveExecution: vi.fn(),
  loadTranscript: vi.fn(),
  summarize: vi.fn(),
  summaryRequests: vi.fn(),
  embed: vi.fn(),
  name: vi.fn(),
  sampleNaming: false,
  numeric: vi.fn(),
}));
vi.mock("@langfuse/shared/src/server", async (importOriginal) => {
  const { assembleTranscript, isInternalEvalEnvironment } =
    await importOriginal<typeof import("@langfuse/shared/src/server")>();
  return {
    ...(await importOriginal<typeof import("@langfuse/shared/src/server")>()),
    assembleTranscript,
    isInternalEvalEnvironment,
    recordIncrement: vi.fn(),
    recordDistribution: vi.fn(),
  };
});
const facet: TopicFacetVersion = {
  projectId: "project",
  facetId: "facet",
  version: 1,
  prompt: "Describe the interaction intent.",
  createdAt: "2026-01-01T00:00:00.000Z",
};

vi.mock("@langfuse/shared/topics/server", async (importOriginal) => {
  const { TOPICS_TRANSCRIPT_VERSION, TOPIC_EMBEDDING_EXPIRED_ERROR } =
    await importOriginal<typeof import("@langfuse/shared/topics/server")>();
  return {
    getTopicTextResponseMetadata: () => undefined,
    isTopicsEnabled: () => true,
    getTopicsModels: async () => {
      const slot = (name: string, model: string) => ({
        slot: name,
        provider: "openai",
        adapter: "openai",
        model,
        connection: { secretKey: "encrypted" },
      });
      return {
        projectId: "project",
        enabled: true,
        summary: slot("summary", "gpt-4.1-nano"),
        embedding: {
          ...slot("embedding", "eu.cohere.embed-v4:0"),
          dimensions: 256,
        },
        clustering: slot("clustering", "gpt-5.6-terra"),
      };
    },
    TOPICS_TRANSCRIPT_VERSION,
    TOPIC_EMBEDDING_EXPIRED_ERROR,
    stageTopicSummary: async (
      scope: { projectId: string; executionId: string },
      summary: TopicSummary,
      embeddingConfig: TopicEmbeddingConfig,
    ) => {
      const key = `${scope.executionId}/${topicSourceKey(summary)}`;
      const accepted = state.staged.get(key);
      if (accepted) return accepted.summary;
      state.staged.set(key, structuredClone({ summary, embeddingConfig }));
      return summary;
    },
    readStagedTopicSummaries: async (
      projectId: string,
      executionId: string,
      facetId: string,
      facetVersion: number,
      traceIds: string[],
    ) =>
      [...state.staged.entries()]
        .filter(([key]) => key.startsWith(`${executionId}/`))
        .map(([, row]) => row.summary)
        .filter(
          (row) =>
            row.projectId === projectId &&
            row.facetId === facetId &&
            row.facetVersion === facetVersion &&
            row.traceId !== null &&
            traceIds.includes(row.traceId),
        ),
    readStagedTopicSummary: async (
      scope: { projectId: string; executionId: string },
      ref: TopicEmbeddingRef,
    ) =>
      state.staged.get(
        `${scope.executionId}/${topicSourceKey({ ...scope, ...ref, sessionId: null })}`,
      ) ?? null,
    updateStagedTopicSummary: async (
      scope: { projectId: string; executionId: string },
      ref: TopicEmbeddingRef,
      summary: TopicSummary,
    ) => {
      const key = `${scope.executionId}/${topicSourceKey({ ...scope, ...ref, sessionId: null })}`;
      const row = state.staged.get(key);
      if (!row) return null;
      if (row.summary.state !== "summarized") return row.summary;
      state.staged.set(key, { ...row, summary });
      return summary;
    },
    deleteStagedTopicSummary: async (
      scope: { projectId: string; executionId: string },
      ref: TopicEmbeddingRef,
    ) => {
      state.staged.delete(
        `${scope.executionId}/${topicSourceKey({ ...scope, ...ref, sessionId: null })}`,
      );
    },
    enqueueTopicEmbeddingBatch: async (batch: TopicEmbeddingBatch) => {
      const key = `${batch.projectId}/${batch.executionId}/${batch.batchId}`;
      if (state.completedBatches.has(key)) return "complete";
      state.embeddingBatches.set(key, batch);
      if (state.deferEmbeddings) return "pending";
      await processTopicEmbeddingBatch(batch);
      state.completedBatches.add(key);
      return "complete";
    },
    loadTopicTranscript: state.loadTranscript,
    readTopicExecutionSummary: async (_project: string, id: string) => {
      const execution = state.executions.get(id);
      if (!execution) return null;
      const { traceErrors: _errors, ...result } = execution;
      const input = { ...result.input };
      if (input.operation === "process")
        Reflect.deleteProperty(input, "traceIds");
      return structuredClone({
        ...result,
        input,
      });
    },
    writeTopicExecution: async (execution: TopicExecution) => {
      await state.saveExecution(execution);
      state.executions.set(execution.id, structuredClone(execution));
    },
    getTopicFacetVersion: async (
      _project: string,
      facetId: string,
      version: number,
    ) => state.facets.get(`${facetId}/${version}`) ?? null,
    listTopicFacets: async () =>
      [...state.facets.values()].map((version) => ({
        id: version.facetId,
        projectId: version.projectId,
        name: version.facetId,
        description: "",
        isBuiltIn: false,
        versions: [version],
      })),
    listTopicSummaries: async (
      projectId: string,
      filter: {
        traceIds: string[];
        facetId: string;
        facetVersion: number;
      },
      timeRange: TopicTimeRange,
    ) => {
      state.resultReads("historical");
      return [...state.summaries.values()].filter(
        (row) =>
          row.projectId === projectId &&
          row.facetId === filter.facetId &&
          row.facetVersion === filter.facetVersion &&
          row.traceId !== null &&
          filter.traceIds.includes(row.traceId) &&
          inTimeRange(row, timeRange),
      );
    },
    writeTopicSummaries: async (rows: TopicSummary[]) =>
      rows.forEach((row) => {
        const key = topicSourceKey(row);
        if ((state.summaries.get(key)?.processedAt ?? "") <= row.processedAt)
          state.summaries.set(key, row);
      }),
    createTopicRun: async (
      input: Pick<
        TopicRun,
        "projectId" | "facetId" | "facetVersion" | "config"
      >,
    ) => pendingRun({ ...input, id: `generated-run-${state.runs.size}` }),
    getPublishedTopicRun: async (_project: string, facetId: string) =>
      [...state.runs.values()]
        .filter((run) => run.status === "completed" && run.facetId === facetId)
        .sort(
          (a, b) =>
            a.facetVersion - b.facetVersion ||
            a.createdAt.localeCompare(b.createdAt),
        )
        .at(-1) ?? null,
    getTopicClusteringSummaries: vi.fn(
      async (
        projectId: string,
        facetId: string,
        facetVersion: number,
        embeddingConfig: TopicEmbeddingConfig,
        timeRange: TopicTimeRange,
      ) =>
        [...state.summaries.values()]
          .filter(
            (row) =>
              row.projectId === projectId &&
              row.facetId === facetId &&
              row.facetVersion === facetVersion &&
              row.traceId !== null &&
              row.state === "complete" &&
              row.embeddingModel === embeddingConfig.embeddingModel &&
              row.embedding.length === embeddingConfig.embeddingDimensions &&
              inTimeRange(row, timeRange),
          )
          .sort((a, b) =>
            a.traceId < b.traceId ? -1 : a.traceId > b.traceId ? 1 : 0,
          ),
    ),
    getTopicRun: async (_project: string, id: string) =>
      state.runs.get(id) ?? null,
    readTopicRunTraceIds: async (
      projectId: string,
      facet: TopicFacetRef,
      runId: string,
      timeRange: TopicTimeRange,
    ) =>
      [...state.assignments.values()]
        .filter(
          (row) =>
            row.projectId === projectId &&
            row.facetId === facet.facetId &&
            row.facetVersion === facet.version &&
            row.runId === runId &&
            row.origin === "initial" &&
            row.traceId !== null &&
            inTimeRange(row, timeRange),
        )
        .map((row) => row.traceId),
    readTopicMapAssignments: async (
      projectId: string,
      facet: TopicFacetRef,
      runId: string,
      timeRange: TopicTimeRange,
    ) =>
      [...state.assignments.values()].filter(
        (row) =>
          row.projectId === projectId &&
          row.facetId === facet.facetId &&
          row.facetVersion === facet.version &&
          row.runId === runId &&
          row.origin === "initial" &&
          inTimeRange(row, timeRange),
      ),
    saveTopicRun: async (run: TopicRun) => {
      state.runs.set(run.id, structuredClone(run));
      return structuredClone(run);
    },
    writeTopicAssignments: async (rows: TopicAssignment[]) => {
      await state.assignmentWrites(rows);
      rows.forEach((row) =>
        state.assignments.set(
          JSON.stringify([topicSourceKey(row), row.runId, row.origin]),
          row,
        ),
      );
    },
    readTopicAssignments: async (
      projectId: string,
      facet: TopicFacetRef,
      sources: Pick<TopicSummary, "traceId" | "sessionId">[],
      runId: string,
      timeRange: TopicTimeRange,
    ) => {
      state.resultReads("assignments");
      if (!state.visible) return [];
      return [...state.assignments.values()].filter(
        (row) =>
          row.projectId === projectId &&
          row.facetId === facet.facetId &&
          row.facetVersion === facet.version &&
          row.runId === runId &&
          sources.some((source) => source.traceId === row.traceId) &&
          inTimeRange(row, timeRange),
      );
    },
  };
});
vi.mock("./models", () => ({
  TopicInputTooLarge: class extends Error {},
  // One request per trace; `state.summarize` answers each facet, and one failure fails the request.
  summarizeTopicTraceFacets: async (
    _models: unknown,
    facets: { key: string; facet: TopicFacetVersion }[],
    text: string,
  ) => {
    state.summaryRequests(facets.length);
    const output: Record<string, unknown> = {};
    let usage = {};
    for (const { key, facet } of facets) {
      const result = await state.summarize(facet, text);
      output[key] = { notes: "", ...result.output };
      usage = { ...result, ...usage };
    }
    return { ...usage, output };
  },
  // `state.embed` sees each summary; one failure fails the whole batched call.
  embedTopicSummaries: async (
    _model: unknown,
    summaries: string[],
    dimensions: number,
  ) => {
    const results = [];
    for (const summary of summaries)
      results.push(await state.embed(summary, dimensions));
    return { ...results[0], embeddings: results.map((r) => r.embedding) };
  },
  prepareTopicNamingGroup: async (group: {
    members: { summary: string }[];
    contrasts: { id: string; summary: string }[];
  }) => {
    const members = state.sampleNaming
      ? group.members
          .toReversed()
          .filter((_, index) => index === 2 || index === 4)
      : group.members;
    return {
      // Citation IDs are opaque to the caller; packing can skip candidates.
      members: members.map((source, index) => ({
        id: state.sampleNaming ? `selected-${index}` : `m${index + 1}`,
        summary: source.summary,
        source,
      })),
      totalMemberCount: group.members.length,
      sampled: state.sampleNaming,
    };
  },
  nameTopicGroup: (_models: unknown, ...args: unknown[]) => state.name(...args),
}));
vi.mock("./numeric", async (importOriginal) => ({
  ...(await importOriginal<typeof import("./numeric")>()),
  runTopicClustering: (...args: unknown[]) => state.numeric(...args),
}));

import { processTopicsExecution as processTopicsExecutionAttempt } from "./processTopicsExecution";
import { processTopicEmbeddingBatch } from "./processTopicEmbeddingBatch";

function inTimeRange(
  row: Pick<TopicSummary, "unitStartTime">,
  timeRange: TopicTimeRange,
) {
  const timestamp = new Date(row.unitStartTime);
  return timestamp >= timeRange.from && timestamp < timeRange.to;
}

function traceInput(traceId: string, input: string | null = traceId) {
  return {
    unitStartTime: "2026-01-01T00:00:00.000Z",
    environment: "production",
    traceName: "Customer support",
    sessionId: "session",
    transcript: assembleTranscript([
      {
        id: `${traceId}-generation`,
        traceId,
        parentObservationId: null,
        type: "GENERATION",
        name: "chat",
        startTime: new Date("2026-01-01T00:00:00.000Z"),
        endTime: new Date("2026-01-01T00:00:01.000Z"),
        nestingLevel: 0,
        input,
        output: null,
        metadata: {},
      },
    ]),
  };
}

async function processTopicsExecution(
  scope: Parameters<typeof processTopicsExecutionAttempt>[0],
) {
  const selected = state.executions.get(scope.executionId)!;
  const traceIds =
    selected.input.operation === "process"
      ? selected.input.traceIds
      : undefined;
  return processTopicsExecutionAttempt({
    ...scope,
    traceIds,
    batchId: "batch-0",
    batchState: state.batches.get(scope.executionId),
    saveBatchState: async (value) => {
      await state.saveBatch(value);
      state.batches.set(scope.executionId, structuredClone(value));
      state.executions.set(scope.executionId, structuredClone(value.execution));
    },
  });
}

function pendingRun(
  input: Pick<
    TopicRun,
    "id" | "projectId" | "facetId" | "facetVersion" | "config"
  >,
): TopicRun {
  const run: TopicRun = {
    ...input,
    status: "pending",
    startedAt: null,
    createdAt: new Date().toISOString(),
    finishedAt: null,
    error: null,
    topics: [],
  };
  state.runs.set(run.id, structuredClone(run));
  return run;
}

function execution<T extends "process" | "update" = "process">(
  id: string,
  count: number,
  operation: T = "process" as T,
  facets = [facet],
  embeddingDimensions = 256,
): TopicExecution & {
  input: Extract<TopicExecution["input"], { operation: T }>;
} {
  facets.forEach((selected) =>
    state.facets.set(`${selected.facetId}/${selected.version}`, selected),
  );
  const input = topicExecutionInputSchema.parse({
    projectId: "project",
    requestId: id,
    operation,
    facets: facets.map(({ facetId, version }) => ({ facetId, version })),
    embeddingConfig: {
      embeddingModel: "eu.cohere.embed-v4:0",
      embeddingDimensions,
    },
    ...(operation === "process"
      ? {
          traceIds: Array.from({ length: count }, (_, i) => `trace${i}`),
          processingConfig: { summaryModel: "gpt-4.1-nano" },
        }
      : {
          timeRange: {
            from: new Date("2026-01-01T00:00:00.000Z"),
            to: new Date("2026-01-08T00:00:00.000Z"),
          },
        }),
  });
  return {
    id,
    projectId: "project",
    input,
    status: "queued",
    phase: "queued",
    createdAt: "2026-01-01T00:00:00.000Z",
    updatedAt: "2026-01-01T00:00:00.000Z",
    facets: facets.map((selected) => ({
      facetId: selected.facetId,
      facetVersion: selected.version,
      outcome: "pending",
      runId:
        operation === "process"
          ? ([...state.runs.values()]
              .filter(
                (run) =>
                  run.status === "completed" &&
                  run.facetId === selected.facetId &&
                  run.facetVersion === selected.version &&
                  run.config.dimensions === embeddingDimensions,
              )
              .at(-1)?.id ?? null)
          : pendingRun({
              id: `run-${id}-${selected.facetId}-${selected.version}`,
              projectId: "project",
              facetId: selected.facetId,
              facetVersion: selected.version,
              config: {},
            }).id,
      error: null,
      counts: {
        requested: count,
        complete: 0,
        nonApplicable: 0,
        insufficientInput: 0,
        failed: 0,
        assigned: 0,
        outlier: 0,
      },
    })),
    traceErrors: [],
    error: null,
  } as TopicExecution & {
    input: Extract<TopicExecution["input"], { operation: T }>;
  };
}

async function processSelection(
  id: string,
  count: number,
  traceIds?: string[],
  reuseExistingSummaries = false,
) {
  const pending = execution(id, count);
  pending.input.reuseExistingSummaries = reuseExistingSummaries;
  if (traceIds) pending.input.traceIds = traceIds;
  state.executions.set(id, pending);
  return processTopicsExecution({ projectId: "project", executionId: id });
}

async function updateSelection(id: string) {
  state.executions.set(id, execution(id, 0, "update"));
  await processTopicsExecution({ projectId: "project", executionId: id });
}

beforeEach(() => {
  vi.resetAllMocks();
  state.batches.clear();
  state.executions.clear();
  state.summaries.clear();
  state.staged.clear();
  state.embeddingBatches.clear();
  state.completedBatches.clear();
  state.deferEmbeddings = false;
  state.runs.clear();
  state.assignments.clear();
  state.facets.clear();
  state.visible = true;
  state.sampleNaming = false;
  state.loadTranscript.mockImplementation(async ({ traceId }) =>
    traceInput(traceId),
  );
  state.summarize.mockImplementation(async (_facet, text: string) => {
    // The projected transcript the trace-batch path sends.
    const transcript = JSON.parse(text);
    const input = transcript.threads[0].currentTurn[0].parts.find(
      (part: { type: string }) => part.type === "text",
    );
    return {
      output: {
        status: "applicable",
        summary: input!.text,
      },
      providedUsageDetails: { summary_input: 1 },
      usageDetails: { summary_input: 1 },
      providedCostDetails: {},
      costDetails: {},
    };
  });
  state.embed.mockImplementation(
    async (summary: string, dimensions: number) => {
      const i = Number(summary.replace("trace", ""));
      const embedding = Array.from({ length: dimensions }, () => 0);
      if (i === 101) embedding[2] = 1;
      else {
        embedding[i < 50 || i === 100 ? 0 : 1] = 1;
        embedding[3] = Math.sin(i) * 0.03;
      }
      return {
        embedding,
        providedUsageDetails: { embedding_input: 1 },
        usageDetails: { embedding_input: 1 },
        providedCostDetails: {},
        costDetails: {},
      };
    },
  );
  state.numeric.mockImplementation(async (vectors: number[][]) => ({
    status: "complete",
    labels: vectors.map((vector) =>
      vector[0] > 0.5 ? 0 : vector[1] > 0.5 ? 1 : -1,
    ),
    coordinates: vectors.map((vector) => vector.slice(0, 2)),
  }));
  state.name.mockImplementation(
    async (group: { members: { id: string; summary: string }[] }) => ({
      output: {
        name: `Topic ${group.members[0].summary}`,
        description: "Observed member interactions.",
        evidenceSummaryIds: [group.members[0].id],
      },
    }),
  );
});

describe("Topics execution", () => {
  it.each([false, true])(
    "rejects internal traces supplied by ID (cached: %s)",
    async (cached) => {
      const blocked = execution("blocked", 1);
      if (cached) {
        await processSelection("source", 1);
        const summary = [...state.summaries.values()][0];
        state.staged.set(`blocked/${topicSourceKey(summary)}`, {
          summary: { ...summary, environment: "langfuse-topics" },
          embeddingConfig: blocked.input.embeddingConfig,
        });
        state.summaries.clear();
        state.summarize.mockClear();
        state.embed.mockClear();
      } else {
        state.loadTranscript.mockResolvedValue({
          ...traceInput("trace0"),
          environment: "langfuse-topics",
        });
      }
      state.executions.set("blocked", blocked);
      await processTopicsExecution({
        projectId: "project",
        executionId: "blocked",
      });
      expect(state.summarize).not.toHaveBeenCalled();
      expect(state.embed).not.toHaveBeenCalled();
      expect(state.summaries.size).toBe(0);
      expect(state.executions.get("blocked")?.facets[0].counts.failed).toBe(1);
    },
  );

  it.each([false, true])(
    "resumes mixed internal staged summaries without repeating paid work (embedded: %s)",
    async (embedded) => {
      state.deferEmbeddings = true;
      await processSelection("resumed", 2);
      const saved = state.batches.get("resumed")!;
      expect(saved.summarized).toBe(true);
      const staged = [...state.staged.values()];
      staged[0].summary.environment = "langfuse-topics";
      if (embedded) {
        for (const row of staged) {
          row.summary.state = "complete";
          row.summary.embedding = Array(256).fill(0.25);
        }
        saved.assignedAt = "2026-01-01T00:01:00.000Z";
      }
      state.deferEmbeddings = false;
      state.summarize.mockClear();
      state.embed.mockClear();

      for (let attempt = 0; attempt < 2; attempt++) {
        await processTopicsExecution({
          projectId: "project",
          executionId: "resumed",
        });
        expect(state.executions.get("resumed")).toMatchObject({
          status: "completed_with_errors",
          error: null,
          facets: [{ counts: { complete: 1, failed: 1 } }],
          traceErrors: [
            {
              traceId: staged[0].summary.traceId,
              error: "Topics does not process internal Langfuse traces.",
            },
          ],
        });
        expect(state.batches.get("resumed")?.summaries).toEqual([
          expect.objectContaining({ traceId: staged[1].summary.traceId }),
        ]);
        expect(state.staged.size).toBe(0);
      }
      expect(state.summarize).not.toHaveBeenCalled();
      expect(state.embed).toHaveBeenCalledTimes(embedded ? 0 : 1);
      if (!embedded)
        expect([...state.summaries.values()]).toMatchObject([
          { traceId: staged[1].summary.traceId, state: "complete" },
        ]);
    },
  );

  it("records null transcripts as insufficient input without inference", async () => {
    state.loadTranscript.mockResolvedValueOnce(traceInput("trace0", null));
    await processSelection("empty-transcript", 1);
    expect(state.executions.get("empty-transcript")).toMatchObject({
      status: "completed",
      facets: [{ counts: { insufficientInput: 1, failed: 0 } }],
    });
    expect([...state.summaries.values()]).toMatchObject([
      { state: "insufficient_input", summary: "", embedding: [] },
    ]);
    expect(state.summarize).not.toHaveBeenCalled();
    expect(state.embed).not.toHaveBeenCalled();
  });

  it("processes fresh summaries without a topic map or implicit historical reuse", async () => {
    await processSelection("first", 10);
    expect(state.executions.get("first")?.status).toBe("completed");
    expect(state.executions.get("first")?.facets[0].outcome).toBe(
      "awaiting_topics",
    );
    expect(state.summaries.size).toBe(10);
    expect(state.assignments.size).toBe(0);
    expect([...state.summaries.values()][0]).toMatchObject({
      traceId: "trace0",
      sessionId: "session",
      environment: "production",
      traceName: "Customer support",
      unitStartTime: "2026-01-01T00:00:00.000Z",
      triggerType: "manual",
    });
    expect(state.numeric).not.toHaveBeenCalled();
    expect(state.saveExecution).not.toHaveBeenCalled();
    await processSelection("second", 10);
    expect(state.executions.get("second")?.status).toBe("completed");
    expect(state.summaries.size).toBe(10);
    await processTopicsExecution({
      projectId: "project",
      executionId: "first",
    });
    expect(state.summarize).toHaveBeenCalledTimes(20);
    expect(state.resultReads).not.toHaveBeenCalled();
  });

  it.each([
    { facetId: "issues", version: 1 },
    { facetId: "facet", version: 2 },
  ])(
    "resumes only unfinished facet $facetId version $version after completed payloads expire",
    async (reference) => {
      const issues = { ...facet, ...reference };
      state.executions.set(
        "source",
        execution("source", 100, "process", [facet, issues]),
      );
      await processTopicsExecution({
        projectId: "project",
        executionId: "source",
      });
      expect(state.loadTranscript).toHaveBeenCalledTimes(100);
      expect(state.summarize).toHaveBeenCalledTimes(200);
      // Like trace-batch, both facets of a trace share one summary request.
      expect(state.summaryRequests).toHaveBeenCalledTimes(100);
      expect(state.summaries.size).toBe(200);
      state.executions.set(
        "maps",
        execution("maps", 0, "update", [facet, issues]),
      );
      await processTopicsExecution({
        projectId: "project",
        executionId: "maps",
      });
      state.summarize.mockClear();
      state.embed.mockClear();
      state.resultReads.mockReset().mockImplementation(() => {
        throw new Error("Unexpected ClickHouse result read");
      });
      state.assignments.clear();
      state.executions.set(
        "partial-assignment",
        execution("partial-assignment", 1, "process", [facet, issues]),
      );
      state.assignmentWrites
        .mockReset()
        .mockResolvedValueOnce(undefined)
        .mockRejectedValueOnce(new Error("Insert failed"));
      await processTopicsExecution({
        projectId: "project",
        executionId: "partial-assignment",
      });
      expect(
        state.executions
          .get("partial-assignment")
          ?.facets.map((f) => f.outcome),
      ).toEqual(["assigned", "failed"]);
      expect(state.executions.get("partial-assignment")?.status).toBe(
        "completed_with_errors",
      );
      expect(state.staged.size).toBe(2);
      const failedWrite = structuredClone(
        state.assignmentWrites.mock.calls[1][0],
      );
      for (const [id, row] of state.staged) {
        if (
          row.summary.facetId === facet.facetId &&
          row.summary.facetVersion === facet.version
        )
          state.staged.delete(id);
      }
      state.embeddingBatches.clear();
      state.completedBatches.clear();
      await processTopicsExecution({
        projectId: "project",
        executionId: "partial-assignment",
      });
      expect(state.executions.get("partial-assignment")?.status).toBe(
        "completed",
      );
      expect(state.assignments.size).toBe(2);
      expect(state.assignmentWrites.mock.calls[2][0]).toEqual(failedWrite);
      expect(state.staged.size).toBe(0);
      expect(state.summarize).toHaveBeenCalledTimes(2);
      expect(state.embed).toHaveBeenCalledTimes(2);
      expect(state.resultReads).not.toHaveBeenCalled();
    },
  );

  it("retains Redis payloads until the terminal batch receipt is saved", async () => {
    state.saveBatch
      .mockImplementationOnce(async () => {})
      .mockImplementation(async (batch: TopicProcessBatchState) => {
        if (batch.execution.status === "completed")
          throw new Error("Redis receipt unavailable");
      });
    await processSelection("receipt", 1);
    expect(state.executions.get("receipt")?.status).toBe("failed");
    expect(state.staged.size).toBe(1);
    state.staged.clear();
    state.embeddingBatches.clear();
    state.completedBatches.clear();
    state.saveBatch.mockReset();
    await processTopicsExecution({
      projectId: "project",
      executionId: "receipt",
    });
    expect(state.executions.get("receipt")?.status).toBe("completed");
    expect(state.staged.size).toBe(0);
    expect(state.summarize).toHaveBeenCalledOnce();
    expect(state.embed).toHaveBeenCalledOnce();
  });

  it.each([false, true])(
    "does not regenerate expired payloads (embedding persisted: %s)",
    async (persisted) => {
      state.deferEmbeddings = true;
      await processSelection("expired", 1);
      if (persisted) {
        for (const [key, batch] of state.embeddingBatches) {
          await processTopicEmbeddingBatch(batch);
          state.completedBatches.add(key);
        }
      }
      expect(state.summaries.size).toBe(persisted ? 1 : 0);
      state.staged.clear();
      state.deferEmbeddings = false;
      await processTopicsExecution({
        projectId: "project",
        executionId: "expired",
      });
      expect(state.executions.get("expired")).toMatchObject({
        status: "failed",
        error: expect.stringContaining("expired"),
      });
      expect(state.resultReads).not.toHaveBeenCalled();
      expect(state.summarize).toHaveBeenCalledOnce();
    },
  );

  it.each([
    { version: TOPICS_TRANSCRIPT_VERSION, calls: 1, usageDetails: {} },
    {
      version: "older-transcript",
      calls: 2,
      usageDetails: { summary_input: 1, embedding_input: 1, total: 2 },
    },
  ])(
    "reuses only compatible historical summaries ($version)",
    async ({ version, calls, usageDetails }) => {
      await processSelection("first", 1);
      expect([...state.summaries.values()]).toMatchObject([
        { metadata: { executionId: "first" } },
      ]);
      for (const summary of state.summaries.values())
        summary.transcriptVersion = version;
      state.loadTranscript.mockImplementation(async ({ traceId }) => ({
        ...traceInput(traceId),
        environment: "staging",
        traceName: "Updated support",
      }));
      await processSelection("second", 1, undefined, true);
      expect(state.summarize).toHaveBeenCalledTimes(calls);
      expect(state.embed).toHaveBeenCalledTimes(calls);
      expect([...state.summaries.values()]).toMatchObject([
        {
          environment: "staging",
          traceName: "Updated support",
          transcriptVersion: TOPICS_TRANSCRIPT_VERSION,
          metadata: { executionId: "second" },
        },
      ]);
      expect([...state.summaries.values()][0].usageDetails).toEqual(
        usageDetails,
      );
    },
  );

  it("rejects frozen legacy summary models before reusing or relabeling results", async () => {
    await processSelection("source", 1);
    const summary = [...state.summaries.values()][0];
    summary.summaryModel = "legacy-summary-model";
    const original = structuredClone(summary);
    const legacy = execution("legacy", 1);
    legacy.input.reuseExistingSummaries = true;
    Object.assign(legacy.input.processingConfig, {
      summaryModel: "legacy-summary-model",
    });
    state.executions.set(legacy.id, legacy);
    vi.clearAllMocks();

    await processTopicsExecution({
      projectId: "project",
      executionId: legacy.id,
    });

    expect(state.executions.get(legacy.id)).toMatchObject({
      status: "failed",
      error: expect.stringContaining("start a new Topics execution"),
    });
    expect([...state.summaries.values()]).toEqual([original]);
    expect(state.resultReads).not.toHaveBeenCalled();
    expect(state.loadTranscript).not.toHaveBeenCalled();
    expect(state.summarize).not.toHaveBeenCalled();
    expect(state.embed).not.toHaveBeenCalled();
    expect(state.name).not.toHaveBeenCalled();
  });

  it("resumes accepted summaries after a provider interruption without regenerating paid work", async () => {
    const original = state.summarize.getMockImplementation()!;
    state.summarize
      .mockImplementationOnce(original)
      .mockRejectedValueOnce(
        topicProviderError(
          { statusCode: 503 },
          { slot: "summary", provider: "openai", model: "gpt-4.1-nano" },
        ),
      );
    await processSelection("partial", 3);
    // Traces run concurrently, so the third finishes while the second fails.
    expect(state.batches.get("partial")?.summaries).toHaveLength(2);
    expect(state.executions.get("partial")?.status).toBe("failed");
    const accepted = [...state.staged.values()][0].summary;
    accepted.transcriptVersion = "older-transcript";
    state.loadTranscript.mockClear();
    await processTopicsExecution({
      projectId: "project",
      executionId: "partial",
    });
    expect(state.executions.get("partial")?.status).toBe("completed");
    expect(state.summarize).toHaveBeenCalledTimes(4);
    expect(state.summaries.size).toBe(3);
    expect(state.loadTranscript).not.toHaveBeenCalledWith({
      projectId: "project",
      traceId: accepted.traceId,
    });
    expect(
      state.summaries.get(topicSourceKey(accepted))?.transcriptVersion,
    ).toBe("older-transcript");
  });

  it("resumes pending embeddings with the pinned map and no source or result reads", async () => {
    await processSelection("source", 100);
    await updateSelection("first-map");
    const first = [...state.runs.values()].at(-1)!;
    state.deferEmbeddings = true;
    await processSelection("incoming", 1, ["trace100"]);
    expect(state.batches.get("incoming")?.summarized).toBe(true);
    expect(state.executions.get("incoming")?.phase).toBe("embedding");
    await updateSelection("second-map");
    for (const [key, batch] of state.embeddingBatches) {
      if (!state.completedBatches.has(key))
        await processTopicEmbeddingBatch(batch);
      state.completedBatches.add(key);
    }
    state.loadTranscript.mockRejectedValue(
      new Error("Source trace unavailable"),
    );
    state.resultReads.mockClear();
    state.deferEmbeddings = false;
    await processTopicsExecution({
      projectId: "project",
      executionId: "incoming",
    });
    expect(state.executions.get("incoming")?.status).toBe("completed");
    expect(state.summarize).toHaveBeenCalledTimes(101);
    expect(state.resultReads).not.toHaveBeenCalled();
    expect(
      [...state.assignments.values()].find(
        (row) => row.traceId === "trace100" && row.origin === "online",
      )?.runId,
    ).toBe(first.id);
  });

  it("reuses summary inference when embedding dimensions change", async () => {
    await processSelection("source", 4);
    const reprocess = execution("dimensions", 4, "process", [facet], 512);
    reprocess.input.reuseExistingSummaries = true;
    state.executions.set("dimensions", reprocess);
    await processTopicsExecution({
      projectId: "project",
      executionId: "dimensions",
    });
    expect(state.summarize).toHaveBeenCalledTimes(4);
    expect(state.embed).toHaveBeenCalledTimes(8);
    expect(
      [...state.summaries.values()].filter(
        (row) => row.embedding.length === 512,
      ),
    ).toHaveLength(4);
  });

  it("does not reuse summaries of the capped legacy transcript", async () => {
    await processSelection("legacy", 1);
    for (const [key, row] of state.summaries)
      state.summaries.set(key, { ...row, transcriptId: "poc" });
    state.summarize.mockClear();
    await processSelection("current", 1, undefined, true);
    expect(state.summarize).toHaveBeenCalledOnce();
  });

  it("regenerates a stored summary when late observations move the source start", async () => {
    await processSelection("source", 1);
    state.loadTranscript.mockResolvedValue({
      ...traceInput("trace0"),
      unitStartTime: "2025-12-31T23:59:00.000Z",
    });

    await processSelection("earlier-start", 1, undefined, true);

    expect(state.summarize).toHaveBeenCalledTimes(2);
    expect([...state.summaries.values()]).toMatchObject([
      { unitStartTime: "2025-12-31T23:59:00.000Z" },
    ]);
  });

  it("records source failures while processing the remaining traces", async () => {
    state.loadTranscript.mockRejectedValueOnce(
      new Error("Source trace unavailable"),
    );
    await processSelection("source-failure", 3);
    expect(state.executions.get("source-failure")?.status).toBe(
      "completed_with_errors",
    );
    expect(
      state.executions.get("source-failure")?.facets[0].counts,
    ).toMatchObject({ complete: 2, failed: 1 });
    expect(state.summarize).toHaveBeenCalledTimes(2);
  });

  it("fails the pending discovery run when loading its cohort fails, preserving the published map", async () => {
    await processSelection("source", 100);
    await updateSelection("published");
    const published = [...state.runs.values()].at(-1)!;
    state.numeric.mockClear();
    state.name.mockClear();
    vi.mocked(getTopicClusteringSummaries).mockRejectedValueOnce(
      new Error("Clustering cohort exceeds capacity"),
    );

    await updateSelection("capacity-failure");

    const failed = state.executions.get("capacity-failure")!;
    expect(failed.status).toBe("completed_with_errors");
    expect(failed.facets[0].outcome).toBe("failed");
    expect(state.runs.get(failed.facets[0].runId!)).toMatchObject({
      status: "failed",
      error: "Clustering cohort exceeds capacity",
      finishedAt: expect.any(String),
    });
    expect(state.runs.get(published.id)).toEqual(published);
    expect(state.numeric).not.toHaveBeenCalled();
    expect(state.name).not.toHaveBeenCalled();
  });

  it.each(["invalid_output", "content_filter"] as const)(
    "fails only the trace whose model output is %s",
    async (reason) => {
      state.summarize.mockRejectedValueOnce(
        new TopicsProviderUnavailable("No object generated.", reason),
      );
      await processSelection("invalid-output", 3);
      expect(state.executions.get("invalid-output")?.status).toBe(
        "completed_with_errors",
      );
      expect(
        state.executions.get("invalid-output")?.facets[0].counts,
      ).toMatchObject({ complete: 2, failed: 1 });
    },
  );

  it("publishes filtered naming groups and later retries their labels without changing membership", async () => {
    const facets = [facet, { ...facet, facetId: "sibling" }];
    state.executions.set("source", execution("source", 100, "process", facets));
    await processTopicsExecution({
      projectId: "project",
      executionId: "source",
    });
    state.name.mockRejectedValueOnce(
      new TopicsProviderUnavailable(
        "The model filtered this response.",
        "content_filter",
      ),
    );
    state.executions.set(
      "filtered",
      execution("filtered", 0, "update", facets),
    );

    await processTopicsExecution({
      projectId: "project",
      executionId: "filtered",
    });

    const completed = state.executions.get("filtered")!;
    expect(completed).toMatchObject({
      status: "completed_with_errors",
      facets: [
        {
          outcome: "published",
          error: expect.any(String),
          counts: { assigned: 100, outlier: 0, failed: 0 },
        },
        {
          outcome: "published",
          error: null,
          counts: { assigned: 100, outlier: 0, failed: 0 },
        },
      ],
    });
    expect(state.name).toHaveBeenCalledTimes(4);
    const published = state.runs.get(completed.facets[0].runId!)!;
    expect(published.status).toBe("completed");
    expect(published.topics).toHaveLength(2);
    const placeholder = published.topics.find(
      (topic) => topic.metadata.namingFailure === "content_filter",
    )!;
    const named = published.topics.find((topic) => topic !== placeholder)!;
    expect(placeholder).toMatchObject({
      name: expect.any(String),
      description: expect.stringMatching(/filter/i),
    });
    expect(placeholder.name).not.toBe(named.name);
    // Definition readback must match after metadata passes through JSON storage.
    expect(JSON.parse(JSON.stringify(placeholder))).toStrictEqual(placeholder);
    const assignments = [...state.assignments.values()].filter(
      (row) => row.runId === published.id,
    );
    expect(assignments).toHaveLength(100);
    for (const topic of published.topics)
      expect(
        assignments.filter((row) => row.topicId === topic.topicId),
      ).toHaveLength(50);

    state.name.mockClear();
    await updateSelection("retry-label");

    expect(state.name).toHaveBeenCalledOnce();
    const retried = [...state.runs.values()].at(-1)!;
    expect(state.executions.get("retry-label")?.status).toBe("completed");
    expect(retried.topics).toContainEqual(named);
    const relabeled = retried.topics.find(
      (topic) => topic.topicId === placeholder.topicId,
    )!;
    expect(relabeled.metadata.namingFailure).toBeUndefined();
    expect(relabeled.topicVersionId).not.toBe(placeholder.topicVersionId);
    expect(relabeled.centroid).toEqual(placeholder.centroid);
    expect(relabeled.radius).toBe(placeholder.radius);
    const membership = (runId: string) =>
      [...state.assignments.values()]
        .filter((row) => row.runId === runId)
        .map(({ traceId, topicId }) => ({ traceId, topicId }));
    expect(membership(retried.id)).toEqual(membership(published.id));
  });

  it.each(["summary call", "reuse lookup"])(
    "keeps a reused facet when its sibling's %s fails",
    async (failing) => {
      await processSelection("source", 1);
      const sibling = { ...facet, facetId: "sibling" };
      const reprocess = execution("siblings", 1, "process", [facet, sibling]);
      reprocess.input.reuseExistingSummaries = true;
      state.executions.set("siblings", reprocess);
      if (failing === "summary call")
        state.summarize.mockRejectedValueOnce(
          new Error("The transcript is above this run's input limit."),
        );
      else {
        let lookups = 0;
        // The first lookup reuses `facet`; the sibling's lookup fails.
        state.resultReads.mockImplementation((kind: string) => {
          if (kind === "historical" && ++lookups === 2)
            throw new Error("ClickHouse is unavailable.");
        });
      }
      await processTopicsExecution({
        projectId: "project",
        executionId: "siblings",
      });
      expect(state.executions.get("siblings")?.facets).toMatchObject([
        { facetId: "facet", counts: { complete: 1, failed: 0 } },
        { facetId: "sibling", counts: { failed: 1 } },
      ]);
    },
  );

  it("restarts a failed update with fresh membership and naming while preserving the published map", async () => {
    await processSelection("source", 100);
    await updateSelection("published");
    const published = [...state.runs.values()].at(-1)!;
    for (const summary of state.summaries.values())
      summary.embedding[3] += 0.001;
    const naming = state.name.getMockImplementation()!;
    state.name
      .mockImplementationOnce(naming)
      .mockRejectedValueOnce(
        new TopicsProviderUnavailable("Naming unavailable", "invalid_output"),
      );
    await updateSelection("retry");
    const failed = [...state.runs.values()].at(-1)!;
    expect(failed.status).toBe("failed");
    expect(state.runs.get(published.id)?.status).toBe("completed");
    await processSelection("additional", 1, ["trace100"]);
    await processTopicsExecution({
      projectId: "project",
      executionId: "retry",
    });
    const retried = [...state.runs.values()].at(-1)!;
    expect(retried.id).not.toBe(failed.id);
    expect(retried.status).toBe("completed");
    expect(
      [...state.assignments.values()].filter(
        (row) => row.runId === retried.id && row.origin === "initial",
      ),
    ).toHaveLength(101);
    expect(state.numeric).toHaveBeenCalledTimes(3);
    expect(state.name).toHaveBeenCalledTimes(6);
  });

  it("keeps discovery and retry membership inside the frozen source-time window", async () => {
    await processSelection("source", 100);
    const summaries = [...state.summaries.values()];
    summaries[0].unitStartTime = "2025-12-31T23:59:59.999Z";
    summaries[1].unitStartTime = "2026-01-08T00:00:00.000Z";
    const pending = execution("bounded", 0, "update");
    pending.input.minimumTraceCount = 3;
    state.executions.set(pending.id, pending);
    state.assignmentWrites.mockRejectedValueOnce(new Error("Insert failed"));

    await processTopicsExecution({
      projectId: "project",
      executionId: pending.id,
    });
    expect(state.runs.get(pending.facets[0].runId!)?.status).toBe("failed");
    await processTopicsExecution({
      projectId: "project",
      executionId: pending.id,
    });

    const published = [...state.runs.values()].at(-1)!;
    expect(published).toMatchObject({
      status: "completed",
      config: {
        timeRange: {
          from: "2026-01-01T00:00:00.000Z",
          to: "2026-01-08T00:00:00.000Z",
        },
      },
    });
    const assigned = [...state.assignments.values()].filter(
      (row) => row.runId === published.id,
    );
    expect(assigned).toHaveLength(98);
    expect(assigned.some((row) => row.traceId === summaries[0].traceId)).toBe(
      false,
    );
    expect(assigned.some((row) => row.traceId === summaries[1].traceId)).toBe(
      false,
    );
  });

  it.each([false, true])(
    "recovers completed maps after a lost acknowledgement (all outliers: %s)",
    async (outliers) => {
      await processSelection("source", 100);
      state.loadTranscript.mockRejectedValue(
        new Error("Source trace unavailable"),
      );
      if (outliers)
        state.numeric.mockImplementation(async (vectors: number[][]) => ({
          status: "no_topics",
          labels: vectors.map(() => -1),
          coordinates: vectors.map(() => [0, 0]),
        }));
      state.saveExecution.mockImplementation(
        async (execution: TopicExecution) => {
          if (execution.facets[0].outcome !== "pending")
            throw new Error("Progress acknowledgement lost");
        },
      );
      await expect(updateSelection("published")).rejects.toThrow(
        "Progress acknowledgement lost",
      );
      const interrupted = state.executions.get("published")!.facets[0];
      expect(interrupted.outcome).toBe("pending");
      expect(state.runs.get(interrupted.runId!)?.status).toBe("completed");
      expect(state.summarize).toHaveBeenCalledTimes(100);
      expect(state.embed).toHaveBeenCalledTimes(100);
      expect(state.assignments.size).toBe(100);
      expect([...state.assignments.values()][0].coordinates).toHaveLength(2);
      state.saveExecution.mockReset();
      state.loadTranscript.mockImplementation(async ({ traceId }) => ({
        ...traceInput(traceId),
        environment: "staging",
        traceName: "New support requests",
      }));
      await processSelection("online", 2, ["trace100", "trace101"]);
      expect(state.executions.get("online")?.facets[0]).toMatchObject({
        outcome: "assigned",
        counts: { assigned: outliers ? 0 : 1, outlier: outliers ? 2 : 1 },
      });
      for (const assignment of state.assignments.values()) {
        const summary = state.summaries.get(topicSourceKey(assignment))!;
        expect(assignment).toMatchObject({
          environment: summary.environment,
          traceName: summary.traceName,
        });
      }
      await processTopicsExecution({
        projectId: "project",
        executionId: "published",
      });
      expect(state.executions.get("published")?.facets[0]).toMatchObject({
        outcome: outliers ? "no_topics" : "published",
        counts: {
          requested: 100,
          complete: 100,
          assigned: outliers ? 0 : 100,
          outlier: outliers ? 100 : 0,
        },
      });
      expect(state.numeric).toHaveBeenCalledOnce();
      expect(state.name).toHaveBeenCalledTimes(outliers ? 0 : 2);
      expect(state.runs.size).toBe(1);
    },
  );

  it("does not fit or name when persisting the attempt fails", async () => {
    await processSelection("source", 100);
    state.saveExecution.mockImplementation(
      async (execution: TopicExecution) => {
        if (execution.phase === "clustering")
          throw new Error("Progress unavailable");
      },
    );
    await updateSelection("unregistered");
    expect(state.executions.get("unregistered")?.facets[0]).toMatchObject({
      outcome: "failed",
      error: "Progress unavailable",
    });
    expect([...state.runs.values()][0].status).toBe("pending");
    expect(state.numeric).not.toHaveBeenCalled();
    expect(state.name).not.toHaveBeenCalled();
  });

  it("maps sampled naming citations back to their scoped source references", async () => {
    state.sampleNaming = true;
    await processSelection("source", 100);
    await updateSelection("named");
    const topics = [...state.runs.values()].at(-1)!.topics;
    expect(topics).toHaveLength(2);
    for (const [index, [group]] of state.name.mock.calls.entries()) {
      const source = [...state.summaries.values()].find(
        (summary) => summary.summary === group.members[0].summary,
      )!;
      expect(topics[index].metadata).toMatchObject({
        effectiveMemberCount: 50,
        selectedMemberCount: 2,
        namingSampled: true,
      });
      expect(topics[index].representativeSummaries).toEqual([
        {
          facetId: source.facetId,
          facetVersion: source.facetVersion,
          traceId: source.traceId,
          sessionId: null,
        },
      ]);
    }
  });

  it.each([0, 3])(
    "recovers a skipped cohort of %s after a lost progress acknowledgement",
    async (count) => {
      if (count) await processSelection("source", count);
      state.saveExecution.mockImplementation(
        async (execution: TopicExecution) => {
          if (execution.facets[0].outcome !== "pending")
            throw new Error("Progress acknowledgement lost");
        },
      );
      await expect(updateSelection("skipped")).rejects.toThrow(
        "Progress acknowledgement lost",
      );
      const interrupted = state.executions.get("skipped")!;
      expect(interrupted.facets[0].runId).toBeTruthy();
      expect(state.runs.get(interrupted.facets[0].runId!)?.status).toBe(
        "skipped",
      );
      state.saveExecution.mockReset();
      await processTopicsExecution({
        projectId: "project",
        executionId: "skipped",
      });
      expect(state.executions.get("skipped")?.facets[0]).toMatchObject({
        outcome: count ? "insufficient_data" : "no_applicable_summaries",
        counts: { requested: count },
      });
      expect(state.numeric).not.toHaveBeenCalled();
      expect(state.runs.size).toBe(1);
    },
  );

  it("reuses stored definitions despite roundoff as membership grows and updates retry", async () => {
    await processSelection("source", 100);
    for (const summary of state.summaries.values()) summary.embedding[3] = 0;
    await updateSelection("first");
    for (const topic of [...state.runs.values()].at(-1)!.topics) {
      topic.centroid[0] += Number.EPSILON;
      topic.radius += Number.EPSILON;
    }
    const first = structuredClone([...state.runs.values()].at(-1)!);
    await processSelection("additional", 1, ["trace100"]);
    for (const summary of state.summaries.values()) summary.embedding[3] = 0;
    state.assignmentWrites.mockRejectedValueOnce(
      new Error("Temporary failure"),
    );
    await updateSelection("second");
    expect([...state.runs.values()].at(-1)?.status).toBe("failed");
    await processTopicsExecution({
      projectId: "project",
      executionId: "second",
    });
    const second = [...state.runs.values()].at(-1)!;
    expect(second.status).toBe("completed");
    expect(second.topics).toEqual(first.topics);
    expect(
      second.topics.every((topic) => topic.createdByRunId === first.id),
    ).toBe(true);
    expect(state.name).toHaveBeenCalledTimes(2);
    expect(
      [...state.assignments.values()].find(
        (row) => row.runId === second.id && row.traceId === "trace100",
      )?.topicVersionId,
    ).toBe(
      first.topics.find((topic) => topic.centroid[0] > 0.5)?.topicVersionId,
    );
    expect(state.runs.get(first.id)).toEqual(first);
  });

  it("retains only populations served by stored geometry when near-tied definitions are reused", async () => {
    await processSelection("source", 100);
    for (const summary of state.summaries.values()) {
      const second = summary.embedding[1] > 0.5;
      summary.embedding.fill(0);
      summary.embedding[0] = 1;
      summary.embedding[1] = second ? 3e-8 : 0;
    }
    state.numeric.mockImplementation(async (vectors: number[][]) => ({
      status: "complete",
      labels: vectors.map((vector) => (vector[1] ? 1 : 0)),
      coordinates: vectors.map((vector) => vector.slice(0, 2)),
    }));
    await updateSelection("first");
    const first = [...state.runs.values()].at(-1)!;
    expect(first.topics).toHaveLength(2);
    first.topics.find((topic) => topic.centroid[1] === 0)!.centroid[0] -=
      4 * Number.EPSILON;
    const retained = first.topics.find((topic) => topic.centroid[1] > 0)!;
    await updateSelection("second");
    const second = [...state.runs.values()].at(-1)!;
    expect(second.topics).toEqual([retained]);
    expect(state.name).toHaveBeenCalledTimes(2);
    const assignments = [...state.assignments.values()].filter(
      (row) => row.runId === second.id,
    );
    expect(assignments).toHaveLength(100);
    expect(
      assignments.every(
        (row) => row.topicVersionId === retained.topicVersionId,
      ),
    ).toBe(true);
  });

  it.each(["centroid", "radius"] as const)(
    "creates a new version with the same stable identity when its %s changes",
    async (changed) => {
      await processSelection("source", 100);
      const members = [...state.summaries.values()].filter(
        (summary) => Number(summary.traceId?.replace("trace", "")) < 50,
      );
      members.forEach((summary, index) => {
        summary.embedding[3] = index % 2 ? 0.03 : -0.03;
      });
      await updateSelection("first");
      const first = structuredClone([...state.runs.values()].at(-1)!);
      members.forEach((summary, index) => {
        if (changed === "radius")
          summary.embedding[3] = index % 2 ? 0.04 : -0.04;
        else summary.embedding[3] += 0.001;
      });
      await updateSelection("second");
      const second = [...state.runs.values()].at(-1)!;
      const old = first.topics.find((topic) => topic.centroid[0] > 0.5)!;
      const updated = second.topics.find(
        (topic) => topic.topicId === old.topicId,
      )!;
      expect(updated.topicVersionId).not.toBe(old.topicVersionId);
      expect(updated.createdByRunId).toBe(second.id);
      expect(updated[changed]).not.toEqual(old[changed]);
      if (changed === "radius") expect(updated.centroid).toEqual(old.centroid);
      expect(second.topics.find((topic) => topic.centroid[1] > 0.5)).toEqual(
        first.topics.find((topic) => topic.centroid[1] > 0.5),
      );
      expect(state.name).toHaveBeenCalledTimes(3);
      expect(state.runs.get(first.id)).toEqual(first);
    },
  );

  it.each(["renamed", "repeated", "failed"] as const)(
    "publishes a changed definition whose name repeats a reused topic (retry %s)",
    async (retry) => {
      const persists = retry !== "renamed";
      await processSelection("source", 100);
      await updateSelection("first");
      const first = [...state.runs.values()].at(-1)!;
      const unchanged = first.topics.find((topic) => topic.centroid[1] > 0.5)!;
      for (const summary of state.summaries.values()) {
        if (summary.embedding[0] > 0.5) summary.embedding[3] += 0.001;
      }
      const colliding = {
        output: {
          name: unchanged.name,
          description: "A colliding name.",
          evidenceSummaryIds: ["m1"],
        },
      };
      state.name.mockResolvedValueOnce(colliding);
      if (retry === "repeated") state.name.mockResolvedValueOnce(colliding);
      if (retry === "failed")
        state.name.mockRejectedValueOnce(new Error("Naming unavailable"));
      const calls = state.name.mock.calls.length;
      await updateSelection("second");
      const [, conflictCall] = state.name.mock.calls.slice(calls);
      expect(conflictCall[2]).toMatchObject({
        name: unchanged.name,
        description: unchanged.description,
      });
      const second = [...state.runs.values()].at(-1)!;
      expect(second.status).toBe("completed");
      expect(
        second.topics.filter((topic) => topic.name === unchanged.name),
      ).toHaveLength(persists ? 2 : 1);
    },
  );

  it("bounds assignment writes and retries publication when a batch is not visible", async () => {
    await processSelection("source", 1);
    const template = [...state.summaries.values()][0];
    for (let index = 1; index < 2001; index++) {
      const summary = { ...template, traceId: `trace${index}` };
      state.summaries.set(topicSourceKey(summary), summary);
    }
    state.numeric.mockImplementation(async (vectors: number[][]) => ({
      status: "no_topics",
      labels: vectors.map(() => -1),
      coordinates: vectors.map(() => [0, 0]),
    }));
    state.assignmentWrites.mockImplementation(async () => {
      // A late visibility failure must prevent publication of the whole map.
      if (state.assignmentWrites.mock.calls.length === 3) state.visible = false;
    });
    await updateSelection("batched");
    expect(
      state.assignmentWrites.mock.calls.map(([rows]) => rows.length),
    ).toEqual([1000, 1000, 1]);
    expect([...state.runs.values()].at(-1)?.status).toBe("failed");
    expect(state.executions.get("batched")?.facets[0].error).toContain(
      "not fully visible",
    );
    state.visible = true;
    await processTopicsExecution({
      projectId: "project",
      executionId: "batched",
    });
    expect([...state.runs.values()].at(-1)?.status).toBe("completed");
    expect(state.numeric).toHaveBeenCalledTimes(2);
  });
});