Package dev.dokimos.server.service

Class ComparisonSupport

java.lang.Object

dev.dokimos.server.service.ComparisonSupport

@Component
public class ComparisonSupport
extends Object

Shared entity-to-core conversion and run-comparison invocation for the regression gate and the per-case diff view. Both surfaces show the same comparison, so they must agree on how items are converted, how the pairing strategy is decided, and how the core RunComparison engine is configured. This component owns that single comparison path so the two services cannot drift.

Pairing strategy: items are paired by dataset item id only when both runs share a dataset version AND every loaded item on both sides carries a non-null dataset item id. A dataset-linked run can still hold unlinked items (stored against a stale dataset id), whose null id would collapse to a colliding positional fallback key inside the engine, mis-pairing items or throwing a duplicate-key error. When any item is unlinked, pairing falls back to positional.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	ComparisonSupport.ComparisonOutcome	Result of comparing two runs: the engine output, the pairing strategy, and the runs' loaded item entities so callers (the diff view) can derive per-case input text without re-querying.

Constructor Summary

Constructors

Constructor	Description
ComparisonSupport(ItemResultRepository itemResultRepository)

Method Summary

Modifier and Type	Method	Description
boolean	allItemsLinked(RunResult run)	True when every item in the run carries a non-null dataset item id.
ComparisonSupport.ComparisonOutcome	compare(ExperimentRun baseline, ExperimentRun candidate)	Compares a baseline run against a candidate run with the core engine, deciding the pairing strategy from the runs' dataset versions and item links.
UUID	datasetVersionId(ExperimentRun run)	The dataset version id of a run, or null for ad-hoc runs.
ExperimentRun	getRunInExperiment(UUID runId, Experiment experiment, String label, ExperimentRunRepository runRepository)	Loads a run by id and asserts it belongs to the given experiment.
boolean	isDatasetItemKey(String key)	True when a comparison key is a dataset item id rather than a positional fallback.
void	requireTerminal(ExperimentRun run, String label)	A run can be gated, diffed, or used as a baseline only once it has reached a terminal status.
RunResult	toRunResult(ExperimentRun run)	Converts a server run plus its item and eval results into a single core RunResult at run index 0.
RunResult	toRunResult(List<ItemResult> items)	Converts already-loaded item entities into a core RunResult at run index 0, preserving their order so positional pairing keys line up with the source list.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ComparisonSupport

public ComparisonSupport(ItemResultRepository itemResultRepository)

Method Details

compare

public ComparisonSupport.ComparisonOutcome compare(ExperimentRun baseline,
 ExperimentRun candidate)

Compares a baseline run against a candidate run with the core engine, deciding the pairing strategy from the runs' dataset versions and item links. Each run's items are loaded once and returned on the outcome so callers can reuse them.

Parameters:

baseline - the baseline run

candidate - the candidate run

Returns:

the comparison result, pairing strategy, and loaded items

toRunResult

public RunResult toRunResult(ExperimentRun run)

Converts a server run plus its item and eval results into a single core RunResult at run index 0. Items are loaded with a fetch-join to avoid an N+1 over the lazy eval collection, ordered by createdAt for a stable positional pairing fallback.

Parameters:

run - the run to convert

Returns:

the core run result

toRunResult

public RunResult toRunResult(List<ItemResult> items)

Converts already-loaded item entities into a core RunResult at run index 0, preserving their order so positional pairing keys line up with the source list.

Parameters:

items - the run's items, with evals loaded

Returns:

the core run result

allItemsLinked

public boolean allItemsLinked(RunResult run)

True when every item in the run carries a non-null dataset item id.

Parameters:

run - the run to inspect

Returns:

whether all items are dataset-linked

isDatasetItemKey

public boolean isDatasetItemKey(String key)

True when a comparison key is a dataset item id rather than a positional fallback. Positional keys are emitted by the engine as item-<index>; anything else is a dataset item id.

Parameters:

key - the comparison key

Returns:

whether the key is a dataset item id

requireTerminal

public void requireTerminal(ExperimentRun run,
 String label)

A run can be gated, diffed, or used as a baseline only once it has reached a terminal status.

Parameters:

run - the run to check

label - a human-readable label for the run, used in the error message

Throws:

IllegalStateException - if the run is not in a terminal SUCCESS/FAILED status

getRunInExperiment

public ExperimentRun getRunInExperiment(UUID runId,
 Experiment experiment,
 String label,
 ExperimentRunRepository runRepository)

Loads a run by id and asserts it belongs to the given experiment.

Parameters:

runId - the run id

experiment - the experiment the run must belong to

label - a human-readable label for the run, used in error messages

runRepository - the run repository

Returns:

the loaded run

Throws:

IllegalArgumentException - if the run does not exist or belongs to another experiment

datasetVersionId

public UUID datasetVersionId(ExperimentRun run)

The dataset version id of a run, or null for ad-hoc runs.

Parameters:

run - the run

Returns:

the dataset version id, or null