stores

type APITokenStore interface {
	Create(ctx context.Context, token *models.APIToken) (*models.APIToken, *errors.ServiceError)
	GetByID(ctx context.Context, id string) (*models.APIToken, *errors.ServiceError)
	GetByTokenHash(ctx context.Context, hash string) (*models.APIToken, *errors.ServiceError)
	ListByUserID(ctx context.Context, userID string) ([]*models.APIToken, *errors.ServiceError)
	Revoke(ctx context.Context, id string) *errors.ServiceError
	UpdateLastUsed(ctx context.Context, id string) *errors.ServiceError
}

type AtomicExecutor interface {
	WithTransaction(ctx context.Context, fn func(ctx context.Context) *errors.ServiceError) *errors.ServiceError
}

type ClusterImageRegistryStore interface {
	GetByID(ctx context.Context, ID string) (*models.ClusterImageRegistry, *errors.ServiceError)
	GetForOrgAndCluster(ctx context.Context, orgID, clusterID string) (*models.ClusterImageRegistry, *errors.ServiceError)
	ListForOrg(ctx context.Context, orgID string) ([]*models.ClusterImageRegistry, *errors.ServiceError)
	ListByClusterID(ctx context.Context, orgID, clusterID string) ([]*models.ClusterImageRegistry, *errors.ServiceError)
	ListByClusterIDInternal(ctx context.Context, clusterID string) ([]*models.ClusterImageRegistry, *errors.ServiceError)
	Create(ctx context.Context, spec *models.ClusterImageRegistry) (*models.ClusterImageRegistry, *errors.ServiceError)
	CreateWithTx(ctx context.Context, spec *models.ClusterImageRegistry) (*models.ClusterImageRegistry, *errors.ServiceError)
	UpdateStatus(ctx context.Context, ID string, status *models.ClusterImageRegistryStatus) *errors.ServiceError
	Delete(ctx context.Context, ID string) *errors.ServiceError
	DeleteWithTx(ctx context.Context, ID string) *errors.ServiceError
	MarkDeletingWithTx(ctx context.Context, ID string) *errors.ServiceError
	MarkAllDeletingByClusterIDWithTx(ctx context.Context, clusterID string) *errors.ServiceError
	AtomicExecutor
}

type ClusterStore interface {
	Create(ctx context.Context, spec *models.Cluster) (*models.Cluster, *errors.ServiceError)
	CreateWithTx(ctx context.Context, spec *models.Cluster) (*models.Cluster, *errors.ServiceError)
	ListBYOCClustersForOrg(ctx context.Context, orgID string) ([]*models.Cluster, *errors.ServiceError)
	ListSharedComputeClusters(ctx context.Context) ([]*models.Cluster, *errors.ServiceError)
	ListSharedComputeClustersForOrg(ctx context.Context, orgID string) ([]*models.Cluster, *errors.ServiceError)
	Get(ctx context.Context, ID string) (*models.Cluster, *errors.ServiceError)
	PersistManagerState(ctx context.Context, ID string, running bool) *errors.ServiceError
	Delete(ctx context.Context, ID string) *errors.ServiceError
	DeleteWithTx(ctx context.Context, ID string) *errors.ServiceError
	MarkDeletingWithTx(ctx context.Context, ID string, at time.Time) *errors.ServiceError
	ListIDsForImageRegistryReconciliation(ctx context.Context) ([]string, *errors.ServiceError)
	GetByClusterUrl(ctx context.Context, clusterURL string) (*models.Cluster, *errors.ServiceError)
	FindAnyClusterIDBySharedCompute(ctx context.Context, sharedCompute bool) (string, *errors.ServiceError)
	UpdateSharedComputeCluster(ctx context.Context, cluster *models.Cluster) *errors.ServiceError
	UpdateClusterInfo(ctx context.Context, ID string, info *models.ClusterInfo) *errors.ServiceError
	ListAll(ctx context.Context) ([]*models.Cluster, *errors.ServiceError)
	AtomicExecutor
}

type Filter struct {
	Field string
	Value any
}

type GitInstallationStore interface {
	// Upsert creates or updates the installation keyed by
	// (git_integration_id, installation_id).
	Upsert(ctx context.Context, installation *models.GitInstallation) (*models.GitInstallation, *errors.ServiceError)
	ListByIntegrationID(ctx context.Context, integrationID string) ([]*models.GitInstallation, *errors.ServiceError)
	GetByIntegrationAndID(ctx context.Context, integrationID, id string) (*models.GitInstallation, *errors.ServiceError)
	GetByIntegrationAndAccount(ctx context.Context, integrationID, accountLogin string) (*models.GitInstallation, *errors.ServiceError)
	// GetByInstallationID looks up an installation by its GitHub-global
	// installation id (repository webhooks carry only this reference).
	GetByInstallationID(ctx context.Context, installationID int64) (*models.GitInstallation, *errors.ServiceError)
	DeleteByInstallationID(ctx context.Context, integrationID string, installationID int64) *errors.ServiceError
}

type GitIntegrationStore interface {
	Create(ctx context.Context, integration *models.GitIntegration) (*models.GitIntegration, *errors.ServiceError)
	GetByID(ctx context.Context, ID string) (*models.GitIntegration, *errors.ServiceError)
	// GetByOrgAndHost returns the git_credentials integration for the (org,
	// host) pair.
	GetByOrgAndHost(ctx context.Context, organisationID, host string) (*models.GitIntegration, *errors.ServiceError)
	// GetGitHubAppForOrg returns the org's github_app integration.
	GetGitHubAppForOrg(ctx context.Context, organisationID string) (*models.GitIntegration, *errors.ServiceError)
	ListByOrgID(ctx context.Context, organisationID string) ([]*models.GitIntegration, *errors.ServiceError)
	// ListGitHubApps returns every github_app integration across orgs (used
	// to match webhook deliveries by app ID).
	ListGitHubApps(ctx context.Context) ([]*models.GitIntegration, *errors.ServiceError)
	Update(ctx context.Context, integration *models.GitIntegration) (*models.GitIntegration, *errors.ServiceError)
	Delete(ctx context.Context, ID string) *errors.ServiceError
}

type ImageBuildStore interface {
	Create(ctx context.Context, resourceBuild *models.ImageBuild) (*models.ImageBuild, *errors.ServiceError)
	UpdateStatus(ctx context.Context, BuildID string, status *models.ImageBuildStatus) *errors.ServiceError
	GetByResourceID(ctx context.Context, resourceID string) ([]*models.ImageBuild, *errors.ServiceError)
	ListByStackID(ctx context.Context, stackID string) ([]*models.ImageBuild, *errors.ServiceError)
	GetByID(ctx context.Context, ID string) (*models.ImageBuild, *errors.ServiceError)
}

type ListParams struct {
	Filters  []Filter
	Page     int
	PageSize int
	OrderBy  string
}

type NamespacesStore interface {
	CreateWithTx(ctx context.Context, ns *models.Namespace) (*models.Namespace, *errors.ServiceError)
	Create(ctx context.Context, ns *models.Namespace) (*models.Namespace, *errors.ServiceError)
	Get(ctx context.Context, id string) (*models.Namespace, *errors.ServiceError)
	Delete(ctx context.Context, id string) *errors.ServiceError
	DeleteWithTx(ctx context.Context, id string) *errors.ServiceError
	Update(ctx context.Context, id string, ns *models.Namespace) (*models.Namespace, *errors.ServiceError)
	ListByOrganisation(ctx context.Context, organisationID string) ([]*models.Namespace, *errors.ServiceError)
	ListByStack(ctx context.Context, stackID string) ([]*models.Namespace, *errors.ServiceError)
}

type OAuthStateStore interface {
	Create(ctx context.Context, state *models.OAuthState) *errors.ServiceError
	Consume(ctx context.Context, state, provider string) (*models.OAuthState, *errors.ServiceError)
	DeleteExpired(ctx context.Context, maxAge time.Duration) error
}

type ObjectStoreStore interface {
	Create(ctx context.Context, objectStore *models.ObjectStore) (*models.ObjectStore, *errors.ServiceError)
	GetByID(ctx context.Context, ID string) (*models.ObjectStore, *errors.ServiceError)
	GetByName(ctx context.Context, organisationID, name string) (*models.ObjectStore, *errors.ServiceError)
	Update(ctx context.Context, objectStore *models.ObjectStore) (*models.ObjectStore, *errors.ServiceError)
	Delete(ctx context.Context, ID string) *errors.ServiceError
	ListByOrganisation(ctx context.Context, organisationID string) ([]*models.ObjectStore, *errors.ServiceError)
	ListByProjectID(ctx context.Context, projectID string) ([]*models.ObjectStore, *errors.ServiceError)
	ListByProjectIDs(ctx context.Context, projectIDs []string) ([]*models.ObjectStore, *errors.ServiceError)

	UpdateStatus(ctx context.Context, id string, status models.ObjectStoreStatus) *errors.ServiceError

	// Validation
	ValidateObjectStoreExists(ctx context.Context, objectStoreID string) (bool, *errors.ServiceError)
	ValidateObjectStoreNameUnique(ctx context.Context, organisationID, name, excludeID string) (bool, *errors.ServiceError)

	IsReferencedByAddon(ctx context.Context, objectStoreID string) (bool, *errors.ServiceError)
}

type OrgInviteStore interface {
	AtomicExecutor
	Create(ctx context.Context, invite *models.OrgInvite) (*models.OrgInvite, *errors.ServiceError)
	GetByID(ctx context.Context, id string) (*models.OrgInvite, *errors.ServiceError)
	GetByTokenHash(ctx context.Context, tokenHash string) (*models.OrgInvite, *errors.ServiceError)
	ListByOrgID(ctx context.Context, orgID string, params ListParams) (*PaginatedResult[*models.OrgInvite], *errors.ServiceError)
	UpdateStatus(ctx context.Context, id string, status models.InviteStatus) *errors.ServiceError
	MarkAccepted(ctx context.Context, id string) *errors.ServiceError
	MarkEmailSent(ctx context.Context, id string) *errors.ServiceError
	MarkEmailError(ctx context.Context, id string, errMsg string) *errors.ServiceError
	ResetEmailStatus(ctx context.Context, id string) *errors.ServiceError
	ListPendingUnsent(ctx context.Context, params ListParams) (*PaginatedResult[*models.OrgInvite], *errors.ServiceError)
	GetPendingByOrgAndEmail(ctx context.Context, orgID, email string) (*models.OrgInvite, *errors.ServiceError)
	DeleteIDs(ctx context.Context, ids []string) *errors.ServiceError
	ListExpiredOrPastDue(ctx context.Context, now time.Time, params ListParams) (*PaginatedResult[*models.OrgInvite], *errors.ServiceError)
}

type OrganisationDomainStore interface {
	CreateWithTx(ctx context.Context, domain *models.OrganisationDomain) (*models.OrganisationDomain, *errors.ServiceError)
	BulkCreate(ctx context.Context, domains []*models.OrganisationDomain) ([]*models.OrganisationDomain, *errors.ServiceError)
	Create(ctx context.Context, domain *models.OrganisationDomain) (*models.OrganisationDomain, *errors.ServiceError)
	Get(ctx context.Context, id string) (*models.OrganisationDomain, *errors.ServiceError)
	Delete(ctx context.Context, id string) *errors.ServiceError
	DeleteWithTx(ctx context.Context, id string) *errors.ServiceError
	Update(ctx context.Context, id string, domain *models.OrganisationDomain) (*models.OrganisationDomain, *errors.ServiceError)
	ListByOrganisationID(ctx context.Context, organisationID string) ([]*models.OrganisationDomain, *errors.ServiceError)
}

type OrganisationStore interface {
	GetPlatformOrg(ctx context.Context) (*models.Organisation, *errors.ServiceError)
	OrganisationNameExists(ctx context.Context, name string) (bool, *errors.ServiceError)
	Create(ctx context.Context, spec *models.Organisation) (*models.Organisation, *errors.ServiceError)
	Get(ctx context.Context, ID string) (*models.Organisation, *errors.ServiceError)
	// LockByID takes a row-level lock on the organisation. It must be called
	// inside a transaction to serialize topology mutations owned by that org.
	LockByID(ctx context.Context, ID string) *errors.ServiceError
	Delete(ctx context.Context, ID string) *errors.ServiceError
	Update(ctx context.Context, id string, org *models.Organisation) (*models.Organisation, *errors.ServiceError)
}

type PaginatedResult[T any] struct {
	Items      []T
	Total      int64
	Page       int
	PageSize   int
	TotalPages int
}

type PostgresAddonDatabaseStore interface {
	Create(ctx context.Context, database *models.PostgresAddonDatabase) (*models.PostgresAddonDatabase, *errors.ServiceError)
	CreateWithTx(ctx context.Context, database *models.PostgresAddonDatabase) (*models.PostgresAddonDatabase, *errors.ServiceError)
	GetByID(ctx context.Context, ID string) (*models.PostgresAddonDatabase, *errors.ServiceError)
	GetByName(ctx context.Context, postgresAddonID, name string) (*models.PostgresAddonDatabase, *errors.ServiceError)
	Update(ctx context.Context, database *models.PostgresAddonDatabase) (*models.PostgresAddonDatabase, *errors.ServiceError)
	UpdateWithTx(ctx context.Context, database *models.PostgresAddonDatabase) (*models.PostgresAddonDatabase, *errors.ServiceError)
	Delete(ctx context.Context, ID string) *errors.ServiceError
	DeleteWithTx(ctx context.Context, ID string) *errors.ServiceError
	ListByPostgresAddon(ctx context.Context, postgresAddonID string) ([]*models.PostgresAddonDatabase, *errors.ServiceError)

	// Validation
	ValidateDatabaseExists(ctx context.Context, databaseID string) (bool, *errors.ServiceError)
	ValidateDatabaseNameUnique(ctx context.Context, postgresAddonID, name, excludeID string) (bool, *errors.ServiceError)
}

type PostgresAddonStore interface {
	Create(ctx context.Context, addon *models.PostgresAddon) (*models.PostgresAddon, *errors.ServiceError)
	CreateWithTx(ctx context.Context, addon *models.PostgresAddon) (*models.PostgresAddon, *errors.ServiceError)
	GetByID(ctx context.Context, ID string) (*models.PostgresAddon, *errors.ServiceError)
	GetByName(ctx context.Context, organisationID, name string) (*models.PostgresAddon, *errors.ServiceError)
	Update(ctx context.Context, addon *models.PostgresAddon) (*models.PostgresAddon, *errors.ServiceError)
	UpdateWithTx(ctx context.Context, addon *models.PostgresAddon) (*models.PostgresAddon, *errors.ServiceError)
	Delete(ctx context.Context, ID string) *errors.ServiceError
	ListByOrganisation(ctx context.Context, organisationID string) ([]*models.PostgresAddon, *errors.ServiceError)
	ListByProjectID(ctx context.Context, projectID string) ([]*models.PostgresAddon, *errors.ServiceError)
	ListByProjectIDs(ctx context.Context, projectIDs []string) ([]*models.PostgresAddon, *errors.ServiceError)

	// Validation
	ValidateAddonExists(ctx context.Context, addonID string) (bool, *errors.ServiceError)
	ValidateAddonNameUnique(ctx context.Context, organisationID, name, excludeID string) (bool, *errors.ServiceError)

	// Status and lifecycle management
	UpdateStatus(ctx context.Context, id string, status *models.PostgresAddonStatus) *errors.ServiceError
	UpdateBackupRequestedAt(ctx context.Context, id string, timestamp *time.Time) *errors.ServiceError
	UpdateDeletionTimestamp(ctx context.Context, id string, timestamp *time.Time) *errors.ServiceError
	InternalList(ctx context.Context, query string, args ...any) ([]*models.PostgresAddon, *errors.ServiceError)

	// Transaction support
	WithTransaction(ctx context.Context, fn func(ctx context.Context) *errors.ServiceError) *errors.ServiceError
}

type PostgresBackupStore interface {
	Create(ctx context.Context, backup *models.PostgresBackup) (*models.PostgresBackup, *errors.ServiceError)
	GetByID(ctx context.Context, ID string) (*models.PostgresBackup, *errors.ServiceError)
	Update(ctx context.Context, backup *models.PostgresBackup) (*models.PostgresBackup, *errors.ServiceError)
	Delete(ctx context.Context, ID string) *errors.ServiceError
	ListByPostgresAddon(ctx context.Context, postgresAddonID string) ([]*models.PostgresBackup, *errors.ServiceError)

	GetByName(ctx context.Context, postgresAddonID string, name string) (*models.PostgresBackup, *errors.ServiceError)

	// Validation
	ValidateBackupExists(ctx context.Context, backupID string) (bool, *errors.ServiceError)
}

type PreviewStackStore interface {
	AtomicExecutor
	Create(ctx context.Context, preview *models.PreviewStack) (*models.PreviewStack, *errors.ServiceError)
	GetByID(ctx context.Context, id string) (*models.PreviewStack, *errors.ServiceError)
	Update(ctx context.Context, preview *models.PreviewStack) (*models.PreviewStack, *errors.ServiceError)
	GetByConfigAndPR(ctx context.Context, configID string, prNumber string) (*models.PreviewStack, *errors.ServiceError)
	CountActiveByConfigID(ctx context.Context, configID string) (int64, *errors.ServiceError)
	ListByConfigID(ctx context.Context, configID string, params ListParams) (*PaginatedResult[*models.PreviewStack], *errors.ServiceError)
	ListByProjectID(ctx context.Context, projectID string, params ListParams) (*PaginatedResult[*models.PreviewStack], *errors.ServiceError)
	ListNeedingReconciliation(ctx context.Context, page, pageSize int) ([]*models.PreviewStack, *errors.ServiceError)
	Delete(ctx context.Context, id string) *errors.ServiceError
}

type ProjectMembershipStore interface {
	Create(ctx context.Context, membership *models.ProjectMembership) (*models.ProjectMembership, *errors.ServiceError)
	GetByID(ctx context.Context, id string) (*models.ProjectMembership, *errors.ServiceError)
	GetByProjectAndUser(ctx context.Context, projectID, userID string) (*models.ProjectMembership, *errors.ServiceError)
	ListByProjectID(ctx context.Context, projectID string) ([]*models.ProjectMembership, *errors.ServiceError)
	ListByUserID(ctx context.Context, userID string) ([]*models.ProjectMembership, *errors.ServiceError)
	ListByUserIDAndOrgID(ctx context.Context, userID, orgID string) ([]*models.ProjectMembership, *errors.ServiceError)
	Update(ctx context.Context, id string, membership *models.ProjectMembership) (*models.ProjectMembership, *errors.ServiceError)
	Delete(ctx context.Context, id string) *errors.ServiceError
}

type ProjectStore interface {
	Create(ctx context.Context, project *models.Project) (*models.Project, *errors.ServiceError)
	GetByID(ctx context.Context, id string) (*models.Project, *errors.ServiceError)
	GetByOrgAndName(ctx context.Context, orgID, name string) (*models.Project, *errors.ServiceError)
	ListByOrgID(ctx context.Context, orgID string) ([]*models.Project, *errors.ServiceError)
	Update(ctx context.Context, id string, project *models.Project) (*models.Project, *errors.ServiceError)
	Delete(ctx context.Context, id string) *errors.ServiceError
	GetDefaultProjectForOrg(ctx context.Context, orgID string) (*models.Project, *errors.ServiceError)
}

type RefreshTokenStore interface {
	Create(ctx context.Context, token *models.RefreshToken) (*models.RefreshToken, *errors.ServiceError)
	GetByTokenHash(ctx context.Context, hash string) (*models.RefreshToken, *errors.ServiceError)
	Revoke(ctx context.Context, id string) *errors.ServiceError
	RevokeAllForUser(ctx context.Context, userID string) *errors.ServiceError
}

type RegistryCredentialStore interface {
	Create(ctx context.Context, credential *models.RegistryCredential) (*models.RegistryCredential, *errors.ServiceError)
	GetByID(ctx context.Context, ID string) (*models.RegistryCredential, *errors.ServiceError)
	// GetByOrgAndHost returns all credentials for the (org, normalized host)
	// pair; there can be up to one per purpose.
	GetByOrgAndHost(ctx context.Context, organisationID, host string) ([]*models.RegistryCredential, *errors.ServiceError)
	ListByOrgID(ctx context.Context, organisationID string) ([]*models.RegistryCredential, *errors.ServiceError)
	Update(ctx context.Context, credential *models.RegistryCredential) (*models.RegistryCredential, *errors.ServiceError)
	Delete(ctx context.Context, ID string) *errors.ServiceError
}

type ReleaseEventStore interface {
	// Insert assigns the next release-local sequence and inserts the event in
	// its own transaction. A duplicate (release_id, dedupe_key) is a no-op and
	// returns (nil, nil).
	Insert(ctx context.Context, event *models.ReleaseEvent) (*models.ReleaseEvent, *errors.ServiceError)
	// InsertWithTx is Insert joining the caller's ambient transaction.
	// Must run inside a transaction (db.TxFromContext must be non-nil).
	InsertWithTx(ctx context.Context, event *models.ReleaseEvent) (*models.ReleaseEvent, *errors.ServiceError)
	// ListByReleaseID returns events with sequence > afterSequence ordered by
	// sequence ASC, capped at limit.
	ListByReleaseID(ctx context.Context, releaseID string, afterSequence int, limit int) ([]*models.ReleaseEvent, *errors.ServiceError)
	AtomicExecutor
}

type ResourceReferenceStore interface {
	// ReplaceSpecWithTx deletes all spec-scoped rows (release_id IS NULL) for the
	// stack and reinserts refs. Must run inside a transaction.
	ReplaceSpecWithTx(ctx context.Context, stackID string, refs []models.ResourceReference) *errors.ServiceError
	// InsertReleaseWithTx inserts release-scoped rows. Must run inside a transaction.
	InsertReleaseWithTx(ctx context.Context, releaseID, stackID string, refs []models.ResourceReference) *errors.ServiceError
	// ListByReferent returns every reference row (any scope, org-wide) for a referent.
	ListByReferent(ctx context.Context, referentType models.ReferentType, referentID string) ([]models.ResourceReference, *errors.ServiceError)
}

type ResourceValidationRecordStore interface {
	Get(ctx context.Context, stackID, resourceName string, kind models.ResourceValidationCheckKind) (*models.ResourceValidationRecord, *errors.ServiceError)
	Upsert(ctx context.Context, record *models.ResourceValidationRecord) *errors.ServiceError
}

type SecretStore interface {
	Create(ctx context.Context, secret *models.Secret) (*models.Secret, *errors.ServiceError)
	GetByID(ctx context.Context, ID string) (*models.Secret, *errors.ServiceError)
	GetByName(ctx context.Context, organisationID, name string) (*models.Secret, *errors.ServiceError)
	Update(ctx context.Context, secret *models.Secret) (*models.Secret, *errors.ServiceError)
	UpdateEncryptedData(ctx context.Context, secretID string, encryptedData string, keys []string, dataHash string) *errors.ServiceError
	Delete(ctx context.Context, ID string) *errors.ServiceError
	ListByOrganisation(ctx context.Context, organisationID string, params ListParams) ([]*models.Secret, *errors.ServiceError)
	ListByProjectID(ctx context.Context, projectID string, params ListParams) ([]*models.Secret, *errors.ServiceError)
	ListByProjectIDs(ctx context.Context, projectIDs []string, params ListParams) ([]*models.Secret, *errors.ServiceError)
	ListByUser(ctx context.Context, organisationID, userID string) ([]*models.Secret, *errors.ServiceError)
	ListByType(ctx context.Context, organisationID, secretType models.SecretType) ([]*models.Secret, *errors.ServiceError)
	ValidateSecretExists(ctx context.Context, secretID string) (bool, *errors.ServiceError)
	GetSecretKeys(ctx context.Context, secretID string) ([]string, *errors.ServiceError)
	ValidateSecretHasKeys(ctx context.Context, secretID string, requiredKeys []string) (bool, []string, *errors.ServiceError)
}

type StackConnectionStore interface {
	ListByStackID(ctx context.Context, stackID string) (models.StackConnections, *errors.ServiceError)
	CreateWithTx(ctx context.Context, stackID string, connection *models.StackConnection) (*models.StackConnection, *errors.ServiceError)
	UpdateWithTx(ctx context.Context, stackID, connectionID string, connection *models.StackConnection) (*models.StackConnection, *errors.ServiceError)
	DeleteWithTx(ctx context.Context, stackID, connectionID string) *errors.ServiceError
	ReplaceByStackIDWithTx(ctx context.Context, stackID string, connections models.StackConnections) *errors.ServiceError
	IsNodeReferenced(ctx context.Context, stackID string, ref models.TopologyNodeRef) (bool, error)
	IsNodeReferencedAsSource(ctx context.Context, stackID string, ref models.TopologyNodeRef) (bool, error)
	IsNodeReferencedAsTarget(ctx context.Context, stackID string, ref models.TopologyNodeRef) (bool, error)
}

type StackDomainsStore interface {
	CreateWithTx(ctx context.Context, domain *models.StackDomain) (*models.StackDomain, *errors.ServiceError)
	BulkCreate(ctx context.Context, domains []*models.StackDomain) (models.StackDomainList, *errors.ServiceError)
	Create(ctx context.Context, domain *models.StackDomain) (*models.StackDomain, *errors.ServiceError)
	Get(ctx context.Context, id string) (*models.StackDomain, *errors.ServiceError)
	Delete(ctx context.Context, id string) *errors.ServiceError
	DeleteWithTx(ctx context.Context, id string) *errors.ServiceError
	Update(ctx context.Context, id string, domain *models.StackDomain) (*models.StackDomain, *errors.ServiceError)
	ListByStackID(ctx context.Context, stackID string) (models.StackDomainList, *errors.ServiceError)
	ListByStackResourceID(ctx context.Context, stackResourceID string) (models.StackDomainList, *errors.ServiceError)
	GetByStackResourceAndPort(ctx context.Context, stackResourceID string, port int) (*models.StackDomain, *errors.ServiceError)
	DeleteForStackResourceAndPort(ctx context.Context, stackResourceID string, port int) *errors.ServiceError
	DeleteForStackResourceAndPortWithTx(ctx context.Context, stackResourceID string, port int) *errors.ServiceError
	GetByFqdn(ctx context.Context, fqdn string) (*models.StackDomain, *errors.ServiceError)
	ListByOrganisationID(ctx context.Context, organisationID string) (models.StackDomainList, *errors.ServiceError)
	ListByFqdnPrefix(ctx context.Context, prefix string) (models.StackDomainList, *errors.ServiceError)
}

type StackPreviewConfigStore interface {
	AtomicExecutor
	Create(ctx context.Context, config *models.StackPreviewConfig) (*models.StackPreviewConfig, *errors.ServiceError)
	GetByID(ctx context.Context, id string) (*models.StackPreviewConfig, *errors.ServiceError)
	GetByProjectAndName(ctx context.Context, projectID, name string) (*models.StackPreviewConfig, *errors.ServiceError)
	GetByOrgAndRepo(ctx context.Context, organisationID, normalizedRepoURL string) (*models.StackPreviewConfig, *errors.ServiceError)
	Update(ctx context.Context, config *models.StackPreviewConfig) (*models.StackPreviewConfig, *errors.ServiceError)
	Delete(ctx context.Context, id string) *errors.ServiceError
	ListByProjectID(ctx context.Context, projectID string, params ListParams) (*PaginatedResult[*models.StackPreviewConfig], *errors.ServiceError)
}

type StackReleaseStore interface {
	// Create inserts a new release with sequence = max(sequence)+1.
	Create(ctx context.Context, release *models.StackRelease) (*models.StackRelease, *errors.ServiceError)

	GetByID(ctx context.Context, id string) (*models.StackRelease, *errors.ServiceError)

	ListByStackID(ctx context.Context, stackID string, params ListParams) (*PaginatedResult[*models.StackRelease], *errors.ServiceError)

	// ListActive returns all non-terminal releases across all stacks.
	ListActive(ctx context.Context) ([]*models.StackRelease, *errors.ServiceError)

	// GetActiveByStackID returns the single active (non-terminal) release for a stack,
	// or (nil, nil) if none exists.
	GetActiveByStackID(ctx context.Context, stackID string) (*models.StackRelease, *errors.ServiceError)

	// GetLatestByStackID returns the highest-sequence release for a stack, any state,
	// or (nil, nil) if the stack has no releases.
	GetLatestByStackID(ctx context.Context, stackID string) (*models.StackRelease, *errors.ServiceError)

	// GetLatestByStackIDs returns the highest-sequence release for each of the given
	// stack IDs, keyed by stack ID. Stacks with no releases are absent from the map.
	GetLatestByStackIDs(ctx context.Context, stackIDs []string) (map[string]*models.StackRelease, *errors.ServiceError)

	// GetByIDs returns releases keyed by release ID.
	GetByIDs(ctx context.Context, ids []string) (map[string]*models.StackRelease, *errors.ServiceError)

	MarkInProgress(ctx context.Context, id string) (bool, *errors.ServiceError)
	SaveManifest(ctx context.Context, id string, m *models.ReleaseManifest, rev string, pins models.ReleasePins, rendererVersion string) (bool, *errors.ServiceError)
	MarkReleased(ctx context.Context, id string, outcome models.ReleaseOutcome) (bool, *errors.ServiceError)
	MarkFailed(ctx context.Context, id string, message string, outcome *models.ReleaseOutcome) (bool, *errors.ServiceError)
	MarkFailedWithValidationErrors(ctx context.Context, id, message string, verrs models.ReleaseValidationErrors) (bool, *errors.ServiceError)
	Cancel(ctx context.Context, id string) (bool, *errors.ServiceError)
	MarkCancelled(ctx context.Context, id string, reason string) (bool, *errors.ServiceError)
	MarkSuperseded(ctx context.Context, id string, reason string) (bool, *errors.ServiceError)

	// AppendImageDigests merges image digests into the release pins.
	AppendImageDigests(ctx context.Context, id string, digests map[string]string) *errors.ServiceError

	// SetConvergeClockStartedAt stamps (nil: clears) the convergence timeout
	// clock on an InProgress release. See models.ReleaseWorkerStatus.
	SetConvergeClockStartedAt(ctx context.Context, id string, startedAt *time.Time) *errors.ServiceError

	// ListTerminalSummariesByStackID returns lightweight release summaries for GC decisions.
	// Only terminal-state releases are returned — active releases are never GC candidates.
	ListTerminalSummariesByStackID(ctx context.Context, stackID string) ([]models.ReleaseSummary, *errors.ServiceError)

	// DeleteByIDs removes releases by their IDs.
	DeleteByIDs(ctx context.Context, ids []string) *errors.ServiceError

	// ListStackIDsExceedingRetention returns stack IDs that have more than `cap`
	// terminal releases — candidates for periodic GC.
	ListStackIDsExceedingRetention(ctx context.Context, cap int) ([]string, *errors.ServiceError)

	AtomicExecutor
}

type StackResourceStore interface {
	Create(ctx context.Context, resource *models.StackResource) (*models.StackResource, *errors.ServiceError)
	CreateWithTx(ctx context.Context, resource *models.StackResource, stack *models.Stack) (*models.StackResource, *errors.ServiceError)
	GetByStackID(ctx context.Context, stackID string) ([]*models.StackResource, *errors.ServiceError)
	GetByID(ctx context.Context, ID string) (*models.StackResource, *errors.ServiceError)
	GetByStackIDAndResourceName(ctx context.Context, stackID, resourceName string) (*models.StackResource, *errors.ServiceError)
	Update(ctx context.Context, resourceID string, resource *models.StackResource, stack *models.Stack) (*models.StackResource, *errors.ServiceError)
	UpdateWithTx(ctx context.Context, resourceID string, resource *models.StackResource, stack *models.Stack) (*models.StackResource, *errors.ServiceError)
	UpdatePortsWithTx(ctx context.Context, resourceID string, resource *models.StackResource) *errors.ServiceError
	UpdateStatus(ctx context.Context, resourceID string, status *models.StackResourceStatus) *errors.ServiceError
	DeleteWithTx(ctx context.Context, ID string) *errors.ServiceError
	Delete(ctx context.Context, ID string) *errors.ServiceError
}

type StackStore interface {
	Create(ctx context.Context, spec *models.Stack) (*models.Stack, *errors.ServiceError)
	CreateWithTx(ctx context.Context, spec *models.Stack) (*models.Stack, *errors.ServiceError)
	GetByID(ctx context.Context, id string) (*models.Stack, *errors.ServiceError)
	// LockByID takes a row-level lock on the stack (SELECT ... FOR UPDATE).
	// Only meaningful inside WithTransaction; serializes concurrent mutations
	// that must observe each other (e.g. duplicate-name checks on create).
	LockByID(ctx context.Context, id string) *errors.ServiceError
	// GetByNameAndProjectID resolves a stack by name within a project scope. Stack
	// names are unique per project, so this is the canonical lookup for
	// name-addressed operations (e.g. declarative apply).
	GetByNameAndProjectID(ctx context.Context, name string, projectID string) (*models.Stack, *errors.ServiceError)
	Update(ctx context.Context, id string, spec *models.Stack) (*models.Stack, *errors.ServiceError)
	UpdateRevision(ctx context.Context, id string, revision string) *errors.ServiceError
	UpdateConnectionsWithTx(ctx context.Context, id string, connections models.StackConnections) *errors.ServiceError
	CreateConnectionWithTx(ctx context.Context, id string, connection *models.StackConnection) (*models.StackConnection, *errors.ServiceError)
	UpdateConnectionWithTx(ctx context.Context, id string, connectionID string, connection *models.StackConnection) (*models.StackConnection, *errors.ServiceError)
	DeleteConnectionWithTx(ctx context.Context, id string, connectionID string) *errors.ServiceError
	InternalList(ctx context.Context, query string, args ...any) ([]*models.Stack, *errors.ServiceError)
	UpdateWithTx(ctx context.Context, id string, spec *models.Stack) (*models.Stack, *errors.ServiceError)
	UpdateShellWithTx(ctx context.Context, id string, spec *models.Stack) (*models.Stack, *errors.ServiceError)
	UpdateStatus(ctx context.Context, id string, status *models.StackStatus) *errors.ServiceError
	UpdateForDelete(ctx context.Context, id string, spec *models.Stack) (*models.Stack, *errors.ServiceError)
	DeleteWithTx(ctx context.Context, id string) *errors.ServiceError
	Delete(ctx context.Context, id string) *errors.ServiceError
	ListByOrganisationID(ctx context.Context, organisationID string) ([]*models.Stack, *errors.ServiceError)
	ListByProjectID(ctx context.Context, projectID string) ([]*models.Stack, *errors.ServiceError)
	ListByProjectIDs(ctx context.Context, projectIDs []string) ([]*models.Stack, *errors.ServiceError)
	ListByUserID(ctx context.Context, userID string) ([]*models.Stack, *errors.ServiceError)
	AtomicExecutor
}

type StackVolumeStore interface {
	Create(ctx context.Context, sv *models.StackVolume) *errors.ServiceError
	Delete(ctx context.Context, stackID, volumeID string) *errors.ServiceError
	GetByVolumeID(ctx context.Context, volumeID string) (*models.StackVolume, *errors.ServiceError)
	ListVolumesByStackID(ctx context.Context, stackID string) ([]*models.Volume, *errors.ServiceError)
	CreateWithTx(ctx context.Context, sv *models.StackVolume) *errors.ServiceError
	DeleteWithTx(ctx context.Context, stackID, volumeID string) *errors.ServiceError
}

type StorageStore interface {
	Create(ctx context.Context, spec *models.StackStorage) (*models.StackStorage, *errors.ServiceError)
	CreateWithTx(ctx context.Context, spec *models.StackStorage) (*models.StackStorage, *errors.ServiceError)
	GetByID(ctx context.Context, id string) (*models.StackStorage, *errors.ServiceError)
	GetByWorkspaceName(ctx context.Context, workspaceName string, userID string) (*models.StackStorage, *errors.ServiceError)
	GetByIDorName(ctx context.Context, idOrName string, userID string) (*models.StackStorage, *errors.ServiceError)
	Update(ctx context.Context, id string, spec *models.StackStorage) (*models.StackStorage, *errors.ServiceError)
	UpdateWithTx(ctx context.Context, id string, spec *models.StackStorage) (*models.StackStorage, *errors.ServiceError)
	UpdateStatus(ctx context.Context, id string, status *models.StackStorageStatus) (*models.StackStorage, *errors.ServiceError)
	Delete(ctx context.Context, id string) *errors.ServiceError
	DeleteWithTx(ctx context.Context, id string) *errors.ServiceError
	DeleteByNameWithTx(ctx context.Context, name string, userID string) *errors.ServiceError
	ListByOrganisationID(ctx context.Context, organisationID string) ([]*models.StackStorage, *errors.ServiceError)
	ListByUserID(ctx context.Context, userID string) ([]*models.StackStorage, *errors.ServiceError)
	AtomicExecutor
}

type UserStore interface {
	Create(ctx context.Context, user *models.User) (*models.User, *errors.ServiceError)
	GetByID(ctx context.Context, id string) (*models.User, *errors.ServiceError)
	GetByEmail(ctx context.Context, email string) (*models.User, *errors.ServiceError)
	Update(ctx context.Context, id string, user *models.User) (*models.User, *errors.ServiceError)
	ListByOrgID(ctx context.Context, orgID string, params ListParams) (*PaginatedResult[*models.User], *errors.ServiceError)
	ListByOrgAndRole(ctx context.Context, orgID string, role models.UserRole) ([]*models.User, *errors.ServiceError)
}

type VolumeStore interface {
	Create(ctx context.Context, spec *models.Volume) (*models.Volume, *errors.ServiceError)
	CreateWithTx(ctx context.Context, spec *models.Volume) (*models.Volume, *errors.ServiceError)
	InternalList(ctx context.Context, ids []string) ([]*models.Volume, *errors.ServiceError)
	InternalListNotReady(ctx context.Context) ([]*models.Volume, *errors.ServiceError)
	GetByID(ctx context.Context, id string) (*models.Volume, *errors.ServiceError)
	UpdateGitRepoSourceRevision(ctx context.Context, id string, revision models.GitRepoRevision) (*models.Volume, *errors.ServiceError)
	UpdateGitRepoSourceRevisionWithTx(ctx context.Context, id string, revision models.GitRepoRevision) (*models.Volume, *errors.ServiceError)
	UpdateRemoteDirSourceHash(ctx context.Context, id string, remoteDirHash string) (*models.Volume, *errors.ServiceError)
	UpdateRemoteDirSourceHashWithTx(ctx context.Context, id string, remoteDirHash string) (*models.Volume, *errors.ServiceError)
	UpdateStatus(ctx context.Context, id string, status *models.VolumeStatus) *errors.ServiceError
	Delete(ctx context.Context, id string) *errors.ServiceError
	DeleteWithTx(ctx context.Context, id string) *errors.ServiceError
	GetByUserID(ctx context.Context, id string) ([]*models.Volume, *errors.ServiceError)
	GetByVolumeNameAndNamespace(ctx context.Context, volumeName string, namespace string) (*models.Volume, *errors.ServiceError)
	ListByProjectID(ctx context.Context, projectID string) ([]*models.Volume, *errors.ServiceError)
	AtomicExecutor
}