From 4bb05bd23152015beb6b2752fabc58f5da211e11 Mon Sep 17 00:00:00 2001 From: sergeyb Date: Tue, 2 Jun 2026 18:21:01 +0000 Subject: [PATCH] docs(storage): clarify BatchDependentStore invariant and Get semantics Document on the interface that every active Batch has a paired BatchDependent row (Create runs before BatchStore.Create), so Get only sees IDs from the active set and ErrNotFound is an invariant violation rather than an expected outcome. Also note that an empty Dependents list is the normal "no dependents" result. Co-Authored-By: Claude Opus 4.7 --- extension/storage/batch_dependent_store.go | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/extension/storage/batch_dependent_store.go b/extension/storage/batch_dependent_store.go index 0dc2d1ac..5fcdb235 100644 --- a/extension/storage/batch_dependent_store.go +++ b/extension/storage/batch_dependent_store.go @@ -23,13 +23,22 @@ import ( ) // BatchDependentStore is an interface that defines methods for managing batch dependent information in the database. +// +// A BatchDependent is a reverse index ("batches that depend on me") paired one-to-one with a Batch. +// The batch-creation flow always calls Create here before creating the Batch itself, so every active +// Batch is guaranteed to have a corresponding BatchDependent row. Lookups via Get are only performed +// for batch IDs returned from the active-batch set, meaning a missing row indicates data corruption or +// out-of-band manipulation rather than a normal "not found" outcome. ErrNotFound is therefore part of +// the contract for completeness but is not expected to be returned in steady-state operation. type BatchDependentStore interface { // Get retrieves the batch dependent by batch ID. - // Returns ErrNotFound if the batch dependent is not found. + // If the batch contains no dependents, the returned BatchDependent will have an empty Dependents list. + // Returns ErrNotFound if the batch itself is not found, which should never happen in steady-state system and + // therefore does not need a special handling. Get(ctx context.Context, batchID string) (entity.BatchDependent, error) // Create creates a new batch dependent. - // Returns ErrAlreadyExists if the entry already exists. + // Returns ErrAlreadyExists if the entry already exists for the given batch ID. Create(ctx context.Context, batchDependent entity.BatchDependent) error // UpdateDependents updates the dependents of a batch dependent and the version to newVersion