storage

type BatchDependentStore interface {
	// Get retrieves the batch dependent by batch ID.
	// 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 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
	// if the current persisted version matches oldVersion. If versions do not match, returns ErrVersionMismatch.
	// Version arithmetic is owned by the caller; the store performs a pure conditional write.
	UpdateDependents(ctx context.Context, batchID string, oldVersion, newVersion int32, dependents []string) error
}

type BatchStore interface {
	// Get retrieves a batch by ID. Returns ErrNotFound if the batch is not found.
	Get(ctx context.Context, id string) (entity.Batch, error)

	// Create creates a new batch. The batch must have a unique ID already assigned.
	// Returns ErrAlreadyExists if a batch with the same ID already exists.
	Create(ctx context.Context, batch entity.Batch) error

	// UpdateState updates the state of a batch to newState and the version to newVersion
	// if the current persisted version matches oldVersion. If versions do not match, returns ErrVersionMismatch.
	// Version arithmetic is owned by the caller; the store performs a pure conditional write.
	UpdateState(ctx context.Context, id string, oldVersion, newVersion int32, newState entity.BatchState) error

	// GetByQueueAndStates retrieves all batches that belong to the given queue and are in the given states.
	GetByQueueAndStates(ctx context.Context, queue string, states []entity.BatchState) ([]entity.Batch, error)
}

type BuildStore interface {
	// Get retrieves a build by ID. Returns ErrNotFound if the build is not found.
	Get(ctx context.Context, id string) (entity.Build, error)

	// Create creates a new build. The build must have a unique ID already assigned.
	// Returns ErrAlreadyExists if a build with the same ID already exists.
	Create(ctx context.Context, build entity.Build) error

	// UpdateStatus updates the status of a build.
	UpdateStatus(ctx context.Context, id string, newStatus entity.BuildStatus) error
}

type ChangeStore interface {
	// Create persists a single ChangeRecord (identity + Details) in one write. A
	// primary-key conflict on (Queue, URI, RequestID) is silently ignored, which makes
	// the call idempotent under queue redeliveries of the same request (first write
	// wins). Records belonging to different requests do not conflict on the PK —
	// cross-request overlap is detected by GetByURI, not by Create.
	Create(ctx context.Context, record entity.ChangeRecord) error

	// GetByURI returns every ChangeRecord for the given (queue, uri). Multiple
	// requests can have claimed the same URI over time, so the slice may have
	// any number of entries; an empty slice means no claim has ever been
	// recorded for this URI in this queue.
	//
	// The store does not filter by request_id or by the owning request's
	// state — callers that want to skip self filter by RequestID, and callers
	// that want only live owners consult RequestStore for liveness.
	GetByURI(ctx context.Context, queue string, uri string) ([]entity.ChangeRecord, error)
}

type RequestLogStore interface {
	// Insert appends a new request log record. Timestamps should be generated by the caller and not modified by the implementation.
	Insert(ctx context.Context, log entity.RequestLog) error

	// List retrieves all request log records for a given request ID, ordered by timestamp ascending.
	// Returns ErrNotFound if no records exist for the given request ID.
	List(ctx context.Context, requestID string) ([]entity.RequestLog, error)
}

type RequestQueueSummaryCursor struct {
	// ReceivedAtMs is the receipt timestamp of the last item from the previous page.
	ReceivedAtMs int64
	// RequestID is the request ID of the last item from the previous page.
	RequestID string
}

type RequestQueueSummaryQuery struct {
	// Queue is the exact queue partition to scan.
	Queue string
	// ReceivedAtOrAfterMs is the inclusive lower receipt-time bound.
	ReceivedAtOrAfterMs int64
	// ReceivedBeforeMs is the exclusive upper receipt-time bound.
	ReceivedBeforeMs int64
	// Cursor is an exclusive continuation boundary when HasCursor is true.
	Cursor RequestQueueSummaryCursor
	// HasCursor selects whether Cursor participates in the query.
	HasCursor bool
	// Limit is the maximum number of rows returned and must be positive.
	Limit int
}

type RequestQueueSummaryStore interface {
	// Create inserts summary and returns ErrAlreadyExists when its full primary key already exists.
	Create(ctx context.Context, summary entity.RequestQueueSummary) error

	// Get returns the row identified by its full primary key, or ErrNotFound when absent.
	Get(ctx context.Context, queue string, receivedAtMs int64, requestID string) (entity.RequestQueueSummary, error)

	// Update conditionally replaces mutable fields when the persisted projection version equals oldVersion.
	// The store writes newVersion exactly as supplied and returns ErrVersionMismatch when the guard does not match.
	Update(ctx context.Context, summary entity.RequestQueueSummary, oldVersion, newVersion int32) error

	// List returns at most query.Limit rows ordered by received_at_ms descending, then request_id descending.
	List(ctx context.Context, query RequestQueueSummaryQuery) ([]entity.RequestQueueSummary, error)
}

type RequestStore interface {
	// Get retrieves a land request by ID. Returns ErrNotFound if the request is not found.
	Get(ctx context.Context, id string) (entity.Request, error)

	// Create creates a new land request. The request must have a unique ID already assigned.
	// Returns ErrAlreadyExists if a request with the same ID already exists.
	Create(ctx context.Context, request entity.Request) error

	// UpdateState updates the state of a land request to newState and the version to newVersion
	// if the current persisted version matches oldVersion. If versions do not match, returns ErrVersionMismatch.
	// Version arithmetic is owned by the caller; the store performs a pure conditional write.
	UpdateState(ctx context.Context, id string, oldVersion, newVersion int32, newState entity.RequestState) error
}

type RequestSummaryStore interface {
	// Create inserts summary and returns ErrAlreadyExists when RequestID already exists.
	// The caller owns retry identity and decides whether an existing row is an identical retry or a conflict.
	Create(ctx context.Context, summary entity.RequestSummary) error

	// Get returns the summary for requestID, or ErrNotFound when absent.
	Get(ctx context.Context, requestID string) (entity.RequestSummary, error)

	// Update conditionally replaces the mutable status fields when the persisted projection version equals oldVersion.
	// The store writes newVersion exactly as supplied and returns ErrVersionMismatch when the guard does not match.
	Update(ctx context.Context, summary entity.RequestSummary, oldVersion, newVersion int32) error
}

type RequestURIStore interface {
	// Create inserts mapping and returns ErrAlreadyExists when its full primary key already exists.
	Create(ctx context.Context, mapping entity.RequestURI) error

	// ListByURI returns at most limit mappings ordered by received_at_ms descending, then request_id descending.
	ListByURI(ctx context.Context, changeURI string, limit int) ([]entity.RequestURI, error)
}

type Storage interface {
	// GetRequestStore returns the RequestStore instance.
	GetRequestStore() RequestStore

	// GetChangeStore returns the ChangeStore instance.
	GetChangeStore() ChangeStore

	// GetBatchStore returns the BatchStore instance.
	GetBatchStore() BatchStore

	// GetBatchDependentStore returns the BatchDependentStore instance.
	GetBatchDependentStore() BatchDependentStore

	// GetBuildStore returns the BuildStore instance.
	GetBuildStore() BuildStore

	// GetRequestLogStore returns the RequestLogStore instance.
	GetRequestLogStore() RequestLogStore

	// GetRequestSummaryStore returns the RequestSummaryStore instance.
	GetRequestSummaryStore() RequestSummaryStore

	// GetRequestQueueSummaryStore returns the RequestQueueSummaryStore instance.
	GetRequestQueueSummaryStore() RequestQueueSummaryStore

	// GetRequestURIStore returns the RequestURIStore instance.
	GetRequestURIStore() RequestURIStore

	// Close closes the storage and all underlying connections. Should only be called once at the end of the program.
	Close() error
}