[OPIK-7352] [BE] validate config-entity referenced ids on ingest

thiagohora · claude · thiagohora · commit 5f9f035eb5cd · 2026-07-21T16:29:00.000+02:00
Extends referenced-id validation to config-entity references (verify-then-
enforce: confirmed zero non-UUIDv7 ids across prod projects, datasets,
dataset_versions, prompts, prompt_versions, alerts, dashboards, webhooks,
automation_rules, and guardrails, so enforcement rejects no existing data).

Adds null-safe validateIdNotInFutureIfPresent(Async) helpers and validates:
projectId across span/trace update + batch-update, feedback scores (single
+ batch), guardrails, assertion results, annotation queues, experiments,
optimizations, alerts, automation-rule evaluators, prompts + prompt
versions, dashboards, and thread open/close; feedback/guardrail
sourceQueueId; guardrail secondaryId; experiment optimizationId +
datasetVersionId; dataset-item datasetId + copy-from ids. Upgrades the
guardrail/assertion referenced entityId from version-only to the shared
not-in-future policy.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/apps/opik-backend/src/main/java/com/comet/opik/domain/AlertService.java b/apps/opik-backend/src/main/java/com/comet/opik/domain/AlertService.java
@@ -555,6 +555,7 @@ private Alert prepareAlert(Alert alert, String userName, String workspaceId) {
 
         UUID id = alert.id() == null ? idGenerator.generateId() : alert.id();
         IdGenerator.validateVersion(id, "Alert");
+        idGenerator.validateIdNotInFutureIfPresent(alert.projectId(), "project");
 
         UUID webhookId = alert.webhook().id() == null ? idGenerator.generateId() : alert.webhook().id();
         IdGenerator.validateVersion(webhookId, "Webhook");
diff --git a/apps/opik-backend/src/main/java/com/comet/opik/domain/AnnotationQueueService.java b/apps/opik-backend/src/main/java/com/comet/opik/domain/AnnotationQueueService.java
@@ -261,6 +261,7 @@ private Mono<AnnotationQueue.AnnotationQueuePage> enhancePageWithProjectNames(
     private AnnotationQueue prepareAnnotationQueue(AnnotationQueue annotationQueue) {
         UUID id = annotationQueue.id() == null ? idGenerator.generateId() : annotationQueue.id();
         IdGenerator.validateVersion(id, "AnnotationQueue");
+        idGenerator.validateIdNotInFutureIfPresent(annotationQueue.projectId(), "project");
 
         log.debug("Preparing annotation queue with id '{}', name '{}', project '{}'",
                 id, annotationQueue.name(), annotationQueue.projectId());
diff --git a/apps/opik-backend/src/main/java/com/comet/opik/domain/AssertionResultService.java b/apps/opik-backend/src/main/java/com/comet/opik/domain/AssertionResultService.java
@@ -43,6 +43,7 @@ class AssertionResultServiceImpl implements AssertionResultService {
     private final @NonNull AssertionResultDAO assertionResultDAO;
     private final @NonNull ProjectService projectService;
     private final @NonNull EventBus eventBus;
+    private final @NonNull IdGenerator idGenerator;
 
     @Override
     public Mono<Long> insertBatch(@NonNull EntityType entityType,
@@ -63,7 +64,10 @@ public Mono<Void> saveBatch(@NonNull EntityType entityType,
         }
 
         // Validate up front so a bad id fails fast and independently of project-name normalisation.
-        assertionResults.forEach(item -> IdGenerator.validateVersion(item.entityId(), entityType.getType()));
+        assertionResults.forEach(item -> {
+            idGenerator.validateIdNotInFuture(item.entityId(), entityType.getType());
+            idGenerator.validateIdNotInFutureIfPresent(item.projectId(), "project");
+        });
 
         return Mono.deferContextual(ctx -> {
             String workspaceId = ctx.get(RequestContext.WORKSPACE_ID);
diff --git a/apps/opik-backend/src/main/java/com/comet/opik/domain/DashboardService.java b/apps/opik-backend/src/main/java/com/comet/opik/domain/DashboardService.java
@@ -83,6 +83,7 @@ public Dashboard create(@NonNull Dashboard dashboard, @NonNull DashboardScope sc
         // Generate ID if not provided
         var dashboardId = dashboard.id() != null ? dashboard.id() : idGenerator.generateId();
         IdGenerator.validateVersion(dashboardId, "dashboard");
+        idGenerator.validateIdNotInFutureIfPresent(dashboard.projectId(), "project");
 
         final UUID resolvedProjectId;
         if (StringUtils.isNotBlank(dashboard.projectName()) && dashboard.projectId() == null) {
diff --git a/apps/opik-backend/src/main/java/com/comet/opik/domain/DatasetItemService.java b/apps/opik-backend/src/main/java/com/comet/opik/domain/DatasetItemService.java
@@ -1572,6 +1572,10 @@ private List<DatasetItem> prepareAddedItems(DatasetItemChanges changes, UUID dat
     @WithSpan
     public Mono<DatasetVersion> save(@NonNull DatasetItemBatch batch) {
 
+        idGenerator.validateIdNotInFutureIfPresent(batch.datasetId(), "dataset");
+        idGenerator.validateIdNotInFutureIfPresent(batch.copyFromDatasetId(), "dataset");
+        idGenerator.validateIdNotInFutureIfPresent(batch.copyFromVersionId(), "dataset version");
+
         if (!featureFlags.isDatasetVersioningEnabled()) {
             // Legacy: save to legacy table
             log.info("Saving items to legacy table for dataset '{}'", batch.datasetId());
diff --git a/apps/opik-backend/src/main/java/com/comet/opik/domain/ExperimentService.java b/apps/opik-backend/src/main/java/com/comet/opik/domain/ExperimentService.java
@@ -495,6 +495,9 @@ private Set<UUID> getPromptVersionIds(Experiment experiment) {
     public Mono<UUID> create(@NonNull Experiment experiment) {
         var id = experiment.id() == null ? idGenerator.generateId() : experiment.id();
         IdGenerator.validateVersion(id, "Experiment");
+        idGenerator.validateIdNotInFutureIfPresent(experiment.projectId(), "project");
+        idGenerator.validateIdNotInFutureIfPresent(experiment.optimizationId(), "optimization");
+        idGenerator.validateIdNotInFutureIfPresent(experiment.datasetVersionId(), "dataset version");
         var name = StringUtils.getIfBlank(experiment.name(), nameGenerator::generateName);
         return resolveProjectId(experiment)
                 .flatMap(resolvedExperiment -> datasetService
diff --git a/apps/opik-backend/src/main/java/com/comet/opik/domain/FeedbackScoreService.java b/apps/opik-backend/src/main/java/com/comet/opik/domain/FeedbackScoreService.java
@@ -102,6 +102,7 @@ public Mono<Void> scoreTrace(@NonNull UUID traceId, @NonNull FeedbackScore score
             String userName = ctx.get(RequestContext.USER_NAME);
 
             idGenerator.validateIdNotInFuture(traceId, EntityType.TRACE.getType());
+            idGenerator.validateIdNotInFutureIfPresent(score.sourceQueueId(), "annotation queue");
             return traceDAO.getProjectIdFromTrace(traceId)
                     .switchIfEmpty(Mono.error(failWithNotFound("Trace", traceId)))
                     .flatMap(projectId -> getAuthor()
@@ -121,6 +122,7 @@ public Mono<Void> scoreSpan(@NonNull UUID spanId, @NonNull FeedbackScore score)
             String userName = ctx.get(RequestContext.USER_NAME);
 
             idGenerator.validateIdNotInFuture(spanId, EntityType.SPAN.getType());
+            idGenerator.validateIdNotInFutureIfPresent(score.sourceQueueId(), "annotation queue");
             return spanDAO.getProjectIdFromSpan(spanId)
                     .switchIfEmpty(Mono.error(failWithNotFound("Span", spanId)))
                     .flatMap(projectId -> getAuthor()
@@ -177,6 +179,8 @@ private Mono<Void> processScoreBatch(EntityType entityType, List<FeedbackScoreBa
                 .stream()
                 .map(score -> {
                     idGenerator.validateIdNotInFuture(score.id(), entityType.getType()); // validate span/trace id
+                    idGenerator.validateIdNotInFutureIfPresent(score.projectId(), "project");
+                    idGenerator.validateIdNotInFutureIfPresent(score.sourceQueueId(), "annotation queue");
 
                     return score.toBuilder()
                             .projectName(WorkspaceUtils.getProjectName(score.projectName()))
diff --git a/apps/opik-backend/src/main/java/com/comet/opik/domain/GuardrailsService.java b/apps/opik-backend/src/main/java/com/comet/opik/domain/GuardrailsService.java
@@ -51,7 +51,9 @@ public Mono<Void> addTraceGuardrails(List<Guardrail> guardrails) {
                 .stream()
                 .map(guardrail -> {
                     UUID id = idGenerator.generateId();
-                    IdGenerator.validateVersion(guardrail.entityId(), entityType.getType()); // validate trace id
+                    idGenerator.validateIdNotInFuture(guardrail.entityId(), entityType.getType());
+                    idGenerator.validateIdNotInFuture(guardrail.secondaryId(), "guardrail secondary");
+                    idGenerator.validateIdNotInFutureIfPresent(guardrail.projectId(), "project");
 
                     return guardrail.toBuilder()
                             .id(id)
diff --git a/apps/opik-backend/src/main/java/com/comet/opik/domain/IdGenerator.java b/apps/opik-backend/src/main/java/com/comet/opik/domain/IdGenerator.java
@@ -48,6 +48,20 @@ public interface IdGenerator {
 
     Mono<UUID> validateIdNotInFutureAsync(UUID id, String resource);
 
+    /**
+     * Null-safe variant of {@link #validateIdNotInFuture} for optional referenced ids (e.g. an optional
+     * {@code projectId} that may be resolved by name instead). No-op when {@code id} is null.
+     */
+    default void validateIdNotInFutureIfPresent(UUID id, String resource) {
+        if (id != null) {
+            validateIdNotInFuture(id, resource);
+        }
+    }
+
+    default Mono<UUID> validateIdNotInFutureIfPresentAsync(UUID id, String resource) {
+        return id == null ? Mono.empty() : validateIdNotInFutureAsync(id, resource);
+    }
+
     static Mono<UUID> validateVersionAsync(@NonNull UUID id, String resource) {
         return Mono.fromCallable(() -> {
             validateVersion(id, resource);
diff --git a/apps/opik-backend/src/main/java/com/comet/opik/domain/OptimizationService.java b/apps/opik-backend/src/main/java/com/comet/opik/domain/OptimizationService.java
@@ -176,6 +176,7 @@ private OptimizationSearchCriteria resolveDatasetNameFilter(
     public Mono<UUID> upsert(@NonNull Optimization optimization) {
         UUID id = optimization.id() == null ? idGenerator.generateId() : optimization.id();
         IdGenerator.validateVersion(id, "Optimization");
+        idGenerator.validateIdNotInFutureIfPresent(optimization.projectId(), "project");
 
         // Detect if this is a Studio optimization (has studioConfig in the request)
         boolean isStudioOptimization = optimization.studioConfig() != null;
diff --git a/apps/opik-backend/src/main/java/com/comet/opik/domain/PromptService.java b/apps/opik-backend/src/main/java/com/comet/opik/domain/PromptService.java
@@ -214,6 +214,7 @@ private PromptVersion createPromptVersionFromPromptRequest(Prompt createdPrompt,
     private Prompt savePrompt(String workspaceId, Prompt prompt) {
 
         IdGenerator.validateVersion(prompt.id(), "prompt");
+        idGenerator.validateIdNotInFutureIfPresent(prompt.projectId(), "project");
 
         transactionTemplate.inTransaction(WRITE, handle -> {
             PromptDAO promptDAO = handle.attach(PromptDAO.class);
@@ -332,6 +333,7 @@ public PromptVersion createPromptVersion(@NonNull CreatePromptVersion createProm
                 : createPromptVersion.version().commit();
 
         IdGenerator.validateVersion(id, "prompt version");
+        idGenerator.validateIdNotInFutureIfPresent(createPromptVersion.projectId(), "project");
 
         TemplateStructure templateStructure = createPromptVersion.templateStructure();
 
diff --git a/apps/opik-backend/src/main/java/com/comet/opik/domain/SpanService.java b/apps/opik-backend/src/main/java/com/comet/opik/domain/SpanService.java
@@ -162,9 +162,7 @@ public Mono<UUID> create(@NonNull Span span) {
         return idGenerator
                 .validateIdAsync(id, SPAN_KEY)
                 .then(idGenerator.validateIdNotInFutureAsync(span.traceId(), SPAN_TRACE_KEY))
-                .then(span.parentSpanId() == null
-                        ? Mono.<UUID>empty()
-                        : idGenerator.validateIdNotInFutureAsync(span.parentSpanId(), SPAN_PARENT_KEY))
+                .then(idGenerator.validateIdNotInFutureIfPresentAsync(span.parentSpanId(), SPAN_PARENT_KEY))
                 .then(projectService.getOrCreate(projectName))
                 .flatMap(project -> lockService.executeWithLock(
                         new LockService.Lock(id, SPAN_KEY),
@@ -228,9 +226,8 @@ public Mono<Void> update(@NonNull UUID id, @NonNull SpanUpdate spanUpdate) {
             return idGenerator
                     .validateIdNotInFutureAsync(id, SPAN_KEY)
                     .then(idGenerator.validateIdNotInFutureAsync(spanUpdate.traceId(), SPAN_TRACE_KEY))
-                    .then(spanUpdate.parentSpanId() == null
-                            ? Mono.<UUID>empty()
-                            : idGenerator.validateIdNotInFutureAsync(spanUpdate.parentSpanId(), SPAN_PARENT_KEY))
+                    .then(idGenerator.validateIdNotInFutureIfPresentAsync(spanUpdate.parentSpanId(), SPAN_PARENT_KEY))
+                    .then(idGenerator.validateIdNotInFutureIfPresentAsync(spanUpdate.projectId(), "project"))
                     .then(Mono.defer(() -> getProjectById(spanUpdate)
                             .switchIfEmpty(Mono.defer(() -> projectService.getOrCreate(projectName)))
                             .subscribeOn(Schedulers.boundedElastic()))
@@ -258,10 +255,9 @@ public Mono<Void> batchUpdate(@NonNull SpanBatchUpdate batchUpdate) {
             String userName = ctx.get(RequestContext.USER_NAME);
 
             return idGenerator.validateIdNotInFutureAsync(batchUpdate.update().traceId(), SPAN_TRACE_KEY)
-                    .then(batchUpdate.update().parentSpanId() == null
-                            ? Mono.<UUID>empty()
-                            : idGenerator.validateIdNotInFutureAsync(batchUpdate.update().parentSpanId(),
-                                    SPAN_PARENT_KEY))
+                    .then(idGenerator.validateIdNotInFutureIfPresentAsync(batchUpdate.update().parentSpanId(),
+                            SPAN_PARENT_KEY))
+                    .then(idGenerator.validateIdNotInFutureIfPresentAsync(batchUpdate.update().projectId(), "project"))
                     .then(spanDAO.bulkUpdate(batchUpdate.ids(), batchUpdate.update(), mergeTags))
                     .onErrorResume(TagOperations::mapTagLimitError)
                     .doOnSuccess(__ -> {
@@ -476,9 +472,7 @@ private List<Span> bindSpanToProjectAndId(List<Span> spans, List<Project> projec
                     UUID id = span.id() == null ? idGenerator.generateId() : span.id();
                     idGenerator.validateId(id, SPAN_KEY);
                     idGenerator.validateIdNotInFuture(span.traceId(), SPAN_TRACE_KEY);
-                    if (span.parentSpanId() != null) {
-                        idGenerator.validateIdNotInFuture(span.parentSpanId(), SPAN_PARENT_KEY);
-                    }
+                    idGenerator.validateIdNotInFutureIfPresent(span.parentSpanId(), SPAN_PARENT_KEY);
 
                     return span.toBuilder().id(id).projectId(project.id()).build();
                 })
diff --git a/apps/opik-backend/src/main/java/com/comet/opik/domain/TraceService.java b/apps/opik-backend/src/main/java/com/comet/opik/domain/TraceService.java
@@ -323,6 +323,7 @@ public Mono<Void> update(@NonNull TraceUpdate traceUpdate, @NonNull UUID id) {
 
         return Mono.deferContextual(ctx -> idGenerator
                 .validateIdNotInFutureAsync(id, TRACE_KEY)
+                .then(idGenerator.validateIdNotInFutureIfPresentAsync(traceUpdate.projectId(), "project"))
                 .then(getProjectById(traceUpdate)
                         .switchIfEmpty(Mono.defer(() -> projectService.getOrCreate(projectName)))
                         .subscribeOn(Schedulers.boundedElastic())
@@ -358,7 +359,8 @@ public Mono<Void> batchUpdate(@NonNull TraceBatchUpdate batchUpdate) {
             String workspaceId = ctx.get(RequestContext.WORKSPACE_ID);
             String userName = ctx.get(RequestContext.USER_NAME);
             String workspaceName = ctx.getOrDefault(RequestContext.WORKSPACE_NAME, "");
-            return dao.getProjectIdsByTraceIds(new ArrayList<>(batchUpdate.ids()))
+            return idGenerator.validateIdNotInFutureIfPresentAsync(batchUpdate.update().projectId(), "project")
+                    .then(dao.getProjectIdsByTraceIds(new ArrayList<>(batchUpdate.ids())))
                     .flatMap(traceToProjectMap -> {
                         var projectIds = Set.copyOf(traceToProjectMap.values());
                         return dao.bulkUpdate(batchUpdate.ids(), batchUpdate.update(), mergeTags)
diff --git a/apps/opik-backend/src/main/java/com/comet/opik/domain/evaluators/AutomationRuleEvaluatorService.java b/apps/opik-backend/src/main/java/com/comet/opik/domain/evaluators/AutomationRuleEvaluatorService.java
@@ -117,6 +117,7 @@ public <E, F extends Filter, T extends AutomationRuleEvaluator<E, F>> T save(@No
 
         UUID id = idGenerator.generateId();
         IdGenerator.validateVersion(id, "AutomationRuleEvaluator");
+        projectIds.forEach(projectId -> idGenerator.validateIdNotInFutureIfPresent(projectId, "project"));
 
         // Dual-field sync: First projectId becomes the legacy project_id field
         UUID primaryProjectId = projectIds.isEmpty() ? null : projectIds.iterator().next();
@@ -227,6 +228,8 @@ public <E, F extends Filter, T extends AutomationRuleEvaluator<E, F>> T save(@No
     public void update(@NonNull UUID id, @NonNull Set<UUID> projectIds, @NonNull String workspaceId,
             @NonNull String userName, @NonNull AutomationRuleEvaluatorUpdate<?, ?> evaluatorUpdate) {
 
+        projectIds.forEach(projectId -> idGenerator.validateIdNotInFutureIfPresent(projectId, "project"));
+
         log.debug("Updating AutomationRuleEvaluator with id '{}' in projectIds '{}' and workspaceId '{}'", id,
                 projectIds,
                 workspaceId);
diff --git a/apps/opik-backend/src/main/java/com/comet/opik/domain/threads/TraceThreadService.java b/apps/opik-backend/src/main/java/com/comet/opik/domain/threads/TraceThreadService.java
@@ -10,6 +10,7 @@
 import com.comet.opik.api.events.ProjectWithPendingClosureTraceThreads;
 import com.comet.opik.api.events.TraceThreadsCreated;
 import com.comet.opik.api.resources.v1.events.TraceThreadBufferConfig;
+import com.comet.opik.domain.IdGenerator;
 import com.comet.opik.domain.ProjectService;
 import com.comet.opik.domain.TagOperations;
 import com.comet.opik.domain.TraceService;
@@ -86,6 +87,7 @@ class TraceThreadServiceImpl implements TraceThreadService {
 
     private static final Duration LOCK_DURATION = Duration.ofSeconds(5);
 
+    private final @NonNull IdGenerator idGenerator;
     private final @NonNull TraceThreadDAO traceThreadDAO;
     private final @NonNull TraceThreadIdService traceThreadIdService;
     private final @NonNull TraceService traceService;
@@ -398,6 +400,7 @@ public Mono<Boolean> addToPendingQueue(@NonNull UUID projectId) {
 
     @Override
     public Mono<Void> openThread(UUID projectId, String projectName, @NonNull String threadId) {
+        idGenerator.validateIdNotInFutureIfPresent(projectId, "project");
         return projectService.resolveProjectIdAndVerifyVisibility(projectId, projectName)
                 .flatMap(verifiedProjectId -> getOrCreateThreadId(verifiedProjectId, threadId)
                         .then(Mono.defer(() -> lockService.executeWithLockCustomExpire(
@@ -411,6 +414,7 @@ public Mono<Void> openThread(UUID projectId, String projectName, @NonNull String
 
     @Override
     public Mono<Void> closeThreads(UUID projectId, String projectName, @NonNull Set<String> threadIds) {
+        idGenerator.validateIdNotInFutureIfPresent(projectId, "project");
         if (CollectionUtils.isEmpty(threadIds)) {
             return Mono.empty();
         }
