Package dev.dokimos.server.service

Class TraceEvalJobTransactions

java.lang.Object

dev.dokimos.server.service.TraceEvalJobTransactions

@Component
public class TraceEvalJobTransactions
extends Object

The transactional steps of the trace eval worker, each in its own committed transaction so the worker can make the LLM HTTP call between them without holding a database transaction open. Splitting these out of the worker also makes REQUIRES_NEW boundaries effective, since self-invocation would otherwise bypass the proxy. Mirrors JudgeJobTransactions.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	TraceEvalJobTransactions.ClaimedJob	A claimed job paired with the span text snapshots the worker scores after the transaction closes.

Constructor Summary

Constructors

Constructor	Description
TraceEvalJobTransactions(TraceEvalJobRepository jobRepository)

Method Summary

Modifier and Type	Method	Description
Optional<TraceEvalJobTransactions.ClaimedJob>	claimNextJob(int maxAttempts)	Claims the oldest pending job below the retry ceiling: locks its row, marks it CLAIMED, stamps the claim time, and increments the attempt count.
void	markSucceeded(UUID jobId, double score, boolean success, String reason)	Marks a job SUCCEEDED and records its score.
void	recordFailure(UUID jobId, String error, boolean retryable, int maxAttempts)	Records a failure.
int	recoverStaleClaims(Instant cutoff)	Returns jobs orphaned by a crashed worker (claimed before the cutoff and never finished) to PENDING so the next poll can reclaim them.

Methods inherited from class java.lang.Object

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

Constructor Details

TraceEvalJobTransactions

public TraceEvalJobTransactions(TraceEvalJobRepository jobRepository)

Method Details

recoverStaleClaims

@Transactional(propagation=REQUIRES_NEW)
public int recoverStaleClaims(Instant cutoff)

Returns jobs orphaned by a crashed worker (claimed before the cutoff and never finished) to PENDING so the next poll can reclaim them. The attempt count is left as-is, so the retry ceiling still bounds reclaims.

Parameters:

cutoff - jobs claimed before this instant are requeued

Returns:

the number of jobs requeued

claimNextJob

@Transactional(propagation=REQUIRES_NEW)
public Optional<TraceEvalJobTransactions.ClaimedJob> claimNextJob(int maxAttempts)

Claims the oldest pending job below the retry ceiling: locks its row, marks it CLAIMED, stamps the claim time, and increments the attempt count. Commits before returning so the lock is not held during the HTTP work that follows. The connection and span are initialized while the session is open since the worker reads them after the transaction closes.

Parameters:

maxAttempts - the retry ceiling

Returns:

a snapshot of the claimed job, or empty if none is available

markSucceeded

@Transactional(propagation=REQUIRES_NEW)
public void markSucceeded(UUID jobId,
 double score,
 boolean success,
 String reason)

Marks a job SUCCEEDED and records its score.

Parameters:

jobId - the job that finished scoring

score - the numeric score

success - the pass/fail decision

reason - the judge's reasoning

recordFailure

@Transactional(propagation=REQUIRES_NEW)
public void recordFailure(UUID jobId,
 String error,
 boolean retryable,
 int maxAttempts)

Records a failure. When the failure is retryable and the attempt ceiling has not been reached, the job is returned to PENDING for a later poll; otherwise it is marked FAILED.

Parameters:

jobId - the job that failed

error - the error message to record

retryable - whether the failure is worth retrying

maxAttempts - the retry ceiling