database

type Actor struct {
	Id           apid.ID
	Namespace    string
	Name         scommon.ResourceName
	ExternalId   string
	Permissions  Permissions
	Labels       Labels
	Annotations  Annotations
	EncryptedKey *encfield.EncryptedField
	CreatedAt    time.Time
	UpdatedAt    time.Time
	EncryptedAt  *time.Time
	DeletedAt    *time.Time
}

type ActorOrderByField string

type Annotations map[string]string

type ApiKeyCredential struct {
	Id                   apid.ID
	ConnectionId         apid.ID                  // FK to Connection; not enforced by DB
	EncryptedCredentials encfield.EncryptedField  // Opaque encrypted credential blob
	PlacementSnapshot    *cschema.ApiKeyPlacement // API-key placement config at submission time
	CreatedByActorId     *apid.ID                 // Actor who submitted (or rotated to) this credential
	LastValidatedAt      *time.Time               // Most recent successful probe against this credential
	CreatedAt            time.Time
	EncryptedAt          *time.Time
	DeletedAt            *time.Time
}

type ApiKeyCredentialPlaintext struct {
	ApiKey   string `json:"apiKey"`
	Username string `json:"username,omitempty"`
}

type Connection struct {
	Id                     apid.ID
	Namespace              string
	Name                   scommon.ResourceName
	State                  ConnectionState
	HealthState            ConnectionHealthState
	ConnectorId            apid.ID
	ConnectorVersion       uint64
	Labels                 Labels
	Annotations            Annotations
	EncryptedConfiguration *encfield.EncryptedField
	EncryptedAt            *time.Time
	SetupStep              *cschema.SetupStep
	SetupError             *string
	CreatedAt              time.Time
	UpdatedAt              time.Time
	DeletedAt              *time.Time
}

type ConnectionHealthState string

type ConnectionOrderByField string

type ConnectionProbeOutcome struct {
	Id           apid.ID
	ConnectionId apid.ID
	ProbeId      string
	Outcome      string
	ErrorMessage *string
	OccurredAt   time.Time
	CreatedAt    time.Time
}

type ConnectionState string

type ConnectionVersionMigrationUpdate struct {
	Id                     apid.ID
	ConnectorId            apid.ID
	ConnectorVersion       uint64
	EncryptedConfiguration *encfield.EncryptedField
	UserLabels             map[string]string
	Annotations            map[string]string
	SetupStep              *cschema.SetupStep
	SetupError             *string
	HealthState            *ConnectionHealthState
}

type Connector struct {
	Id          apid.ID
	Namespace   string
	Name        scommon.ResourceName
	Labels      Labels
	Annotations Annotations
	CreatedAt   time.Time
	UpdatedAt   time.Time
	DeletedAt   *time.Time
}

type ConnectorDefinitionVersion struct {
	Id                  apid.ID
	ConnectorId         apid.ID
	Version             uint64
	State               ConnectorDefinitionVersionState
	EncryptedDefinition encfield.EncryptedField
	CreatedAt           time.Time
	UpdatedAt           time.Time
	EncryptedAt         *time.Time
	DeletedAt           *time.Time
}

type ConnectorDefinitionVersionId struct {
	Id      apid.ID
	Version uint64
}

type ConnectorDefinitionVersionOrderByField string

type ConnectorDefinitionVersionState string

type ConnectorOrderByField string

type ConnectorWithDefinition struct {
	Id                  apid.ID
	Namespace           string
	Name                scommon.ResourceName
	DefinitionVersionId apid.ID
	Version             uint64
	State               ConnectorDefinitionVersionState
	EncryptedDefinition encfield.EncryptedField
	Labels              Labels
	Annotations         Annotations
	CreatedAt           time.Time
	UpdatedAt           time.Time
	DefinitionCreatedAt time.Time
	DefinitionUpdatedAt time.Time
	EncryptedAt         *time.Time
	DeletedAt           *time.Time
}

type DB interface {
	SetCursorEncryptor(e pagination.CursorEncryptor)
	Migrate(ctx context.Context) error
	Ping(ctx context.Context) bool
	SearchResources(ctx context.Context, params SearchResourcesParams) (SearchResourcesResult, error)

	GetNamespace(ctx context.Context, path string) (*Namespace, error)
	CreateNamespace(ctx context.Context, ns *Namespace) error
	EnsureNamespaceByPath(ctx context.Context, path string) error
	DeleteNamespace(ctx context.Context, path string) error
	SetNamespaceState(ctx context.Context, path string, state NamespaceState) error
	SetNamespaceKeyId(ctx context.Context, path string, ekId *apid.ID) (*Namespace, error)
	UpdateNamespaceLabels(ctx context.Context, path string, labels map[string]string) (*Namespace, error)
	PutNamespaceLabels(ctx context.Context, path string, labels map[string]string) (*Namespace, error)
	DeleteNamespaceLabels(ctx context.Context, path string, keys []string) (*Namespace, error)
	UpdateNamespaceAnnotations(ctx context.Context, path string, annotations map[string]string) (*Namespace, error)
	PutNamespaceAnnotations(ctx context.Context, path string, annotations map[string]string) (*Namespace, error)
	DeleteNamespaceAnnotations(ctx context.Context, path string, keys []string) (*Namespace, error)
	ListNamespacesBuilder() ListNamespacesBuilder
	ListNamespacesFromCursor(ctx context.Context, cursor string) (ListNamespacesExecutor, error)
	EnumerateNamespaceEncryptionTargets(
		ctx context.Context,
		callback func(targets []NamespaceEncryptionTarget, lastPage bool) (updates []NamespaceTargetDataEncryptionKeyUpdate, keepGoing pagination.KeepGoing, err error),
	) error

	GetActor(ctx context.Context, id apid.ID) (*Actor, error)
	GetActorByExternalId(ctx context.Context, namespace, externalId string) (*Actor, error)
	CreateActor(ctx context.Context, actor *Actor) error
	UpsertActor(ctx context.Context, actor IActorData) (*Actor, error)
	UpdateActorName(ctx context.Context, id apid.ID, name scommon.ResourceName) (*Actor, error)
	DeleteActor(ctx context.Context, id apid.ID) error
	PutActorLabels(ctx context.Context, id apid.ID, labels map[string]string) (*Actor, error)
	DeleteActorLabels(ctx context.Context, id apid.ID, keys []string) (*Actor, error)
	UpdateActorAnnotations(ctx context.Context, id apid.ID, annotations map[string]string) (*Actor, error)
	PutActorAnnotations(ctx context.Context, id apid.ID, annotations map[string]string) (*Actor, error)
	DeleteActorAnnotations(ctx context.Context, id apid.ID, keys []string) (*Actor, error)
	ListActorsBuilder() ListActorsBuilder
	ListActorsFromCursor(ctx context.Context, cursor string) (ListActorsExecutor, error)

	GetConnectorDefinitionVersion(ctx context.Context, id apid.ID, version uint64) (*ConnectorWithDefinition, error)
	GetConnectorDefinitionVersions(ctx context.Context, requested []ConnectorDefinitionVersionId) (map[ConnectorDefinitionVersionId]*ConnectorWithDefinition, error)
	GetConnectorDefinitionVersionForState(ctx context.Context, id apid.ID, state ConnectorDefinitionVersionState) (*ConnectorWithDefinition, error)
	NewestConnectorDefinitionVersionForId(ctx context.Context, id apid.ID) (*ConnectorWithDefinition, error)
	NewestPublishedConnectorDefinitionVersionForId(ctx context.Context, id apid.ID) (*ConnectorWithDefinition, error)
	UpsertConnectorDefinitionVersion(ctx context.Context, cv *ConnectorWithDefinition) error
	SetConnectorDefinitionVersionState(ctx context.Context, id apid.ID, version uint64, state ConnectorDefinitionVersionState) error
	UpdateConnectorName(ctx context.Context, id apid.ID, name scommon.ResourceName) error
	DeleteConnector(ctx context.Context, id apid.ID) error
	ListConnectorDefinitionVersionsBuilder() ListConnectorDefinitionVersionsBuilder
	ListConnectorDefinitionVersionsFromCursor(ctx context.Context, cursor string) (ListConnectorDefinitionVersionsExecutor, error)
	ListConnectorsBuilder() ListConnectorsBuilder
	ListConnectorsFromCursor(ctx context.Context, cursor string) (ListConnectorsExecutor, error)

	GetConnection(ctx context.Context, id apid.ID) (*Connection, error)
	CreateConnection(ctx context.Context, c *Connection) error
	UpdateConnectionName(ctx context.Context, id apid.ID, name scommon.ResourceName) (*Connection, error)
	DeleteConnection(ctx context.Context, id apid.ID) error
	SetConnectionState(ctx context.Context, id apid.ID, state ConnectionState) error
	SetConnectionHealthState(ctx context.Context, id apid.ID, state ConnectionHealthState) error
	SetConnectionSetupStep(ctx context.Context, id apid.ID, setupStep *cschema.SetupStep) error
	SetConnectionSetupError(ctx context.Context, id apid.ID, setupError *string) error
	SetConnectionEncryptedConfiguration(ctx context.Context, id apid.ID, encryptedConfig *encfield.EncryptedField) error
	UpdateConnectionLabels(ctx context.Context, id apid.ID, labels map[string]string) (*Connection, error)
	PutConnectionLabels(ctx context.Context, id apid.ID, labels map[string]string) (*Connection, error)
	DeleteConnectionLabels(ctx context.Context, id apid.ID, keys []string) (*Connection, error)
	UpdateConnectionAnnotations(ctx context.Context, id apid.ID, annotations map[string]string) (*Connection, error)
	PutConnectionAnnotations(ctx context.Context, id apid.ID, annotations map[string]string) (*Connection, error)
	DeleteConnectionAnnotations(ctx context.Context, id apid.ID, keys []string) (*Connection, error)
	UpdateConnectionForVersionMigration(ctx context.Context, update ConnectionVersionMigrationUpdate) (*Connection, error)
	ListConnectionsBuilder() ListConnectionsBuilder
	ListConnectionsFromCursor(ctx context.Context, cursor string) (ListConnectionsExecutor, error)

	/*
	 * Notifications
	 */
	UpsertNotification(ctx context.Context, upsert NotificationUpsert) (*Notification, error)
	GetNotification(ctx context.Context, id apid.ID) (*Notification, error)
	ListNotifications(ctx context.Context, opts ListNotificationsOptions) ([]Notification, error)
	MarkNotificationViewed(ctx context.Context, notificationID apid.ID, actorID apid.ID) error
	MarkNotificationsViewed(ctx context.Context, notificationIDs []apid.ID, actorID apid.ID) error
	NotificationViewedMap(ctx context.Context, actorID apid.ID, ids []apid.ID) (map[apid.ID]time.Time, error)
	ResolveNotificationsForResourceKeys(ctx context.Context, resourceType string, resourceID apid.ID, keys []string) error

	/*
	 * OAuth2 tokens
	 */
	GetOAuth2Token(ctx context.Context, connectionId apid.ID) (*OAuth2Token, error)
	InsertOAuth2Token(
		ctx context.Context,
		connectionId apid.ID,
		refreshedFrom *apid.ID,
		encryptedRefreshToken encfield.EncryptedField,
		encryptedAccessToken encfield.EncryptedField,
		accessTokenExpiresAt *time.Time,
		scopes string,
		requestedScopes string,
		createdByActorId *apid.ID,
	) (*OAuth2Token, error)
	DeleteOAuth2Token(ctx context.Context, tokenId apid.ID) error
	DeleteAllOAuth2TokensForConnection(ctx context.Context, connectionId apid.ID) error

	// EnumerateOAuth2TokensExpiringWithin enumerates OAuth2 tokens that are expiring within a specified time interval
	// of now. This includes tokens that are already expired. Deleted tokens are not considered, nor are tokens tied
	// to a deleted connection.
	EnumerateOAuth2TokensExpiringWithin(
		ctx context.Context,
		duration time.Duration,
		callback func(tokens []*OAuth2TokenWithConnection, lastPage bool) (keepGoing pagination.KeepGoing, err error),
	) error

	/*
	 * API Key credentials
	 */
	GetActiveApiKeyCredential(ctx context.Context, connectionId apid.ID) (*ApiKeyCredential, error)
	InsertApiKeyCredential(
		ctx context.Context,
		connectionId apid.ID,
		encryptedCredentials encfield.EncryptedField,
		placement *cschema.ApiKeyPlacement,
		createdByActorId *apid.ID,
	) (*ApiKeyCredential, error)
	UpdateApiKeyCredentialLastValidated(ctx context.Context, credentialId apid.ID, at time.Time) error
	DeleteAllApiKeyCredentialsForConnection(ctx context.Context, connectionId apid.ID) error

	/*
	 * Connection probe outcomes — append-only event log that drives the
	 * probe-driven health-check signal. The runtime walks the most-recent
	 * rows for each (connection_id, probe_id) to compute consecutive-success
	 * or -failure counts. A daily cleanup task caps growth (see
	 * internal/core/task_probe_outcome_cleanup.go).
	 */
	InsertProbeOutcome(ctx context.Context, connectionId apid.ID, probeId string, outcome string, errorMessage string) (*ConnectionProbeOutcome, error)
	GetRecentProbeOutcomes(ctx context.Context, connectionId apid.ID, probeId string, limit int) ([]*ConnectionProbeOutcome, error)
	DeleteOldProbeOutcomes(ctx context.Context, connectionId apid.ID, probeId string, keepMinimum int, olderThan time.Time) (int64, error)
	DistinctProbeIdsForConnection(ctx context.Context, connectionId apid.ID) ([]string, error)
	CountProbeOutcomes(ctx context.Context, connectionId apid.ID, probeId string) (int, error)

	GetKey(ctx context.Context, id apid.ID) (*Key, error)
	CreateKey(ctx context.Context, ek *Key) error
	UpdateKeyName(ctx context.Context, id apid.ID, name scommon.ResourceName) (*Key, error)
	UpdateKey(ctx context.Context, id apid.ID, updates map[string]interface{}) (*Key, error)
	DeleteKey(ctx context.Context, id apid.ID) error
	SetKeyState(ctx context.Context, id apid.ID, state KeyState) error
	UpdateKeyLabels(ctx context.Context, id apid.ID, labels map[string]string) (*Key, error)
	PutKeyLabels(ctx context.Context, id apid.ID, labels map[string]string) (*Key, error)
	DeleteKeyLabels(ctx context.Context, id apid.ID, keys []string) (*Key, error)
	UpdateKeyAnnotations(ctx context.Context, id apid.ID, annotations map[string]string) (*Key, error)
	PutKeyAnnotations(ctx context.Context, id apid.ID, annotations map[string]string) (*Key, error)
	DeleteKeyAnnotations(ctx context.Context, id apid.ID, keys []string) (*Key, error)
	ListKeysBuilder() ListKeysBuilder
	ListKeysFromCursor(ctx context.Context, cursor string) (ListKeysExecutor, error)

	// EnumerateKeysInDependencyOrder loads all non-deleted keys and walks them
	// in breadth-first order starting from the root key (the one with nil EncryptedKeyData).
	// The callback receives one depth-level of keys at a time, with depth 0 being the root.
	// Returns a slice of orphaned keys whose parent key could not be resolved.
	EnumerateKeysInDependencyOrder(
		ctx context.Context,
		callback func(keys []*Key, depth int) (keepGoing pagination.KeepGoing, err error),
	) ([]*Key, error)

	CreateDataEncryptionKey(ctx context.Context, dek *DataEncryptionKey) error
	GetDataEncryptionKey(ctx context.Context, id apid.ID) (*DataEncryptionKey, error)
	GetCurrentDataEncryptionKeyForKey(ctx context.Context, keyId apid.ID) (*DataEncryptionKey, error)
	UpdateDataEncryptionKeyWrapping(ctx context.Context, dek *DataEncryptionKey) error
	ClearCurrentDataEncryptionKeyFlagForKey(ctx context.Context, keyId apid.ID) error
	SetDataEncryptionKeyCurrentFlag(ctx context.Context, id apid.ID, isCurrent bool) error
	ListDataEncryptionKeysForKey(ctx context.Context, keyId apid.ID) ([]*DataEncryptionKey, error)
	EnumerateDataEncryptionKeysForKey(
		ctx context.Context,
		keyId apid.ID,
		callback func(deks []*DataEncryptionKey, lastPage bool) (keepGoing pagination.KeepGoing, err error),
	) error

	GetRateLimit(ctx context.Context, id apid.ID) (*RateLimit, error)
	CreateRateLimit(ctx context.Context, rl *RateLimit) error
	UpdateRateLimitName(ctx context.Context, id apid.ID, name scommon.ResourceName) (*RateLimit, error)
	UpdateRateLimitDefinition(ctx context.Context, id apid.ID, def rlschema.RateLimit) (*RateLimit, error)
	DeleteRateLimit(ctx context.Context, id apid.ID) error
	UpdateRateLimitLabels(ctx context.Context, id apid.ID, labels map[string]string) (*RateLimit, error)
	PutRateLimitLabels(ctx context.Context, id apid.ID, labels map[string]string) (*RateLimit, error)
	DeleteRateLimitLabels(ctx context.Context, id apid.ID, keys []string) (*RateLimit, error)
	UpdateRateLimitAnnotations(ctx context.Context, id apid.ID, annotations map[string]string) (*RateLimit, error)
	PutRateLimitAnnotations(ctx context.Context, id apid.ID, annotations map[string]string) (*RateLimit, error)
	DeleteRateLimitAnnotations(ctx context.Context, id apid.ID, keys []string) (*RateLimit, error)
	ListRateLimitsBuilder() ListRateLimitsBuilder
	ListRateLimitsFromCursor(ctx context.Context, cursor string) (ListRateLimitsExecutor, error)

	// EnumerateFieldsRequiringReEncryption walks all registered encrypted fields across all tables,
	// finding rows whose encrypted field EKV ID does not match the namespace's target EKV ID.
	EnumerateFieldsRequiringReEncryption(
		ctx context.Context,
		callback func(targets []ReEncryptionTarget, lastPage bool) (keepGoing pagination.KeepGoing, err error),
	) error

	// BatchUpdateReEncryptedFields updates encrypted field values after re-encryption,
	// setting the new value and updating encrypted_at.
	BatchUpdateReEncryptedFields(ctx context.Context, updates []ReEncryptedFieldUpdate) error

	// PurgeSoftDeletedRecords hard-deletes all soft-deleted records where deleted_at is before olderThan.
	// Returns the total number of records deleted across all tables.
	PurgeSoftDeletedRecords(ctx context.Context, olderThan time.Time) (int64, error)

	// RefreshNamespaceLabelsCarryForward re-derives the materialized apxy/
	// portion of every resource that inherits from nsPath, then walks each
	// direct child namespace, recomputes its labels, and recurses. Each
	// row's update runs in its own short transaction. Intended to be
	// invoked from a background asynq task — a label change on a deeply
	// nested namespace can fan out to many descendants.
	RefreshNamespaceLabelsCarryForward(ctx context.Context, nsPath string) error

	// RefreshConnectionsForConnector re-derives the materialized
	// apxy/ portion of every connection pointing at the given logical
	// connector. Each connection's update runs in its own short
	// transaction. Intended to be invoked from a background asynq task
	// after a connector's user labels change.
	RefreshConnectionsForConnector(ctx context.Context, id apid.ID) error

	// ReconcileCarryForwardLabels walks every labelled resource in batches
	// of `batchSize` and re-derives the materialized apxy/ portion of
	// each row. The optional `limiter` is consulted before each row is
	// processed, providing a per-row records/sec rate limit; nil means
	// unlimited. Drift is rare under normal operation, but this method
	// is the safety net for any propagation task that misfired or any
	// data path that bypassed the carry-forward triggers. Intended to be
	// invoked from a daily asynq cron task. Returns the total number of
	// rows whose labels were corrected.
	ReconcileCarryForwardLabels(ctx context.Context, batchSize int32, limiter *rate.Limiter) (corrected int64, err error)

	HasNonceBeenUsed(ctx context.Context, nonce apid.ID) (hasBeenUsed bool, err error)
	CheckNonceValidAndMarkUsed(ctx context.Context, nonce apid.ID, retainRecordUntil time.Time) (wasValid bool, err error)
	DeleteExpiredNonces(ctx context.Context) (err error)
}

type DataEncryptionKey struct {
	Id               apid.ID
	KeyId            apid.ID
	Provider         string
	ProviderID       string
	ProviderVersion  string
	ProviderMetadata DataEncryptionKeyProviderMetadata
	ProtectedData    *sconfig.KeyVersionProtectedData
	IsCurrent        bool
	CreatedAt        time.Time
	UpdatedAt        time.Time
	DeletedAt        *time.Time
}

type DataEncryptionKeyProviderMetadata map[string]string

type DeletedHandling bool

type EncryptedFieldRegistration struct {
	Table          string
	PrimaryKeyCols []string // e.g. ["id"] or ["id", "version"]
	EncryptedCols  []string // e.g. ["encrypted_access_token", "encrypted_refresh_token"]

	// Direct namespace resolution (most tables)
	NamespaceCol string // e.g. "namespace" — column on this table

	// Indirect namespace resolution via JOIN (e.g. oauth2_tokens → connections)
	JoinTable        string // e.g. "connections"
	JoinLocalCol     string // e.g. "connection_id" — FK column on this table
	JoinRemoteCol    string // e.g. "id" — PK column on join table
	JoinNamespaceCol string // e.g. "namespace" — namespace column on join table

}

type IActorData interface {
	GetId() apid.ID
	GetExternalId() string
	GetPermissions() []aschema.Permission
	GetNamespace() string
	GetLabels() map[string]string
	// GetAnnotations returns the annotations to apply on upsert. A nil return means
	// annotations should be left unchanged on existing actors (PATCH semantics);
	// a non-nil map (including empty) is treated as a full replacement.
	GetAnnotations() map[string]string
}

type IActorDataExtended interface {
	IActorData
	GetEncryptedKey() *encfield.EncryptedField
}

type Key struct {
	Id           apid.ID
	Namespace    string
	Name         scommon.ResourceName
	Usage        KeyUsage
	MaterialType KeyMaterialType
	// Key provider configuration is encrypted at rest, but it is not registered
	// with namespace re-encryption. It defines the key hierarchy, so rewrapping
	// it based on namespace targets can make a key depend on its own DEK.
	EncryptedKeyData *encfield.EncryptedField
	State            KeyState
	Labels           Labels
	Annotations      Annotations
	CreatedAt        time.Time
	UpdatedAt        time.Time
	EncryptedAt      *time.Time
	DeletedAt        *time.Time
}

type KeyMaterialType string

type KeyOrderByField string

type KeyState string

type KeyUsage string

type LabelOperator string

type LabelRequirement struct {
	Key      string
	Operator LabelOperator
	Value    string
}

type LabelSelector []LabelRequirement

type Labels map[string]string

type ListActorsBuilder interface {
	ListActorsExecutor
	ForExternalId(externalId string) ListActorsBuilder
	ForName(name scommon.ResourceName) ListActorsBuilder
	ForNamespaceMatcher(matcher string) ListActorsBuilder
	ForNamespaceMatchers(matchers []string) ListActorsBuilder
	Limit(int32) ListActorsBuilder
	OrderBy(ActorOrderByField, pagination.OrderBy) ListActorsBuilder
	IncludeDeleted() ListActorsBuilder
	ForLabelSelector(selector string) ListActorsBuilder
}

type ListActorsExecutor interface {
	FetchPage(context.Context) pagination.PageResult[*Actor]
	Enumerate(context.Context, pagination.EnumerateCallback[*Actor]) error
}

type ListConnectionsBuilder interface {
	ListConnectionsExecutor
	Limit(int32) ListConnectionsBuilder
	ForState(ConnectionState) ListConnectionsBuilder
	ForStates([]ConnectionState) ListConnectionsBuilder
	ForConnectorId(id apid.ID) ListConnectionsBuilder
	ForNamespaceMatcher(matcher string) ListConnectionsBuilder
	ForNamespaceMatchers(matchers []string) ListConnectionsBuilder
	ForName(name scommon.ResourceName) ListConnectionsBuilder
	OrderBy(ConnectionOrderByField, pagination.OrderBy) ListConnectionsBuilder
	IncludeDeleted() ListConnectionsBuilder
	WithDeletedHandling(DeletedHandling) ListConnectionsBuilder
	ForLabelSelector(selector string) ListConnectionsBuilder
	WithSetupStepNotNull() ListConnectionsBuilder
	UpdatedBefore(t time.Time) ListConnectionsBuilder
}

type ListConnectionsExecutor interface {
	FetchPage(context.Context) pagination.PageResult[Connection]
	Enumerate(context.Context, pagination.EnumerateCallback[Connection]) error
}

type ListConnectorDefinitionVersionsBuilder interface {
	ListConnectorDefinitionVersionsExecutor
	Limit(int32) ListConnectorDefinitionVersionsBuilder
	ForId(apid.ID) ListConnectorDefinitionVersionsBuilder
	ForVersion(uint64) ListConnectorDefinitionVersionsBuilder
	ForState(ConnectorDefinitionVersionState) ListConnectorDefinitionVersionsBuilder
	ForStates([]ConnectorDefinitionVersionState) ListConnectorDefinitionVersionsBuilder
	ForNamespaceMatcher(string) ListConnectorDefinitionVersionsBuilder
	ForNamespaceMatchers([]string) ListConnectorDefinitionVersionsBuilder
	ForName(name scommon.ResourceName) ListConnectorDefinitionVersionsBuilder
	OrderBy(ConnectorDefinitionVersionOrderByField, pagination.OrderBy) ListConnectorDefinitionVersionsBuilder
	IncludeDeleted() ListConnectorDefinitionVersionsBuilder
	ForLabelSelector(selector string) ListConnectorDefinitionVersionsBuilder
}

type ListConnectorDefinitionVersionsExecutor interface {
	FetchPage(context.Context) pagination.PageResult[ConnectorWithDefinition]
	Enumerate(context.Context, pagination.EnumerateCallback[ConnectorWithDefinition]) error
}

type ListConnectorsBuilder interface {
	ListConnectorsExecutor
	Limit(int32) ListConnectorsBuilder
	ForType(string) ListConnectorsBuilder
	ForId(apid.ID) ListConnectorsBuilder
	ForNamespaceMatcher(string) ListConnectorsBuilder
	ForNamespaceMatchers([]string) ListConnectorsBuilder
	ForName(name scommon.ResourceName) ListConnectorsBuilder
	ForState(ConnectorDefinitionVersionState) ListConnectorsBuilder
	ForStates([]ConnectorDefinitionVersionState) ListConnectorsBuilder
	OrderBy(ConnectorOrderByField, pagination.OrderBy) ListConnectorsBuilder
	IncludeDeleted() ListConnectorsBuilder
	ForLabelSelector(selector string) ListConnectorsBuilder
}

type ListConnectorsExecutor interface {
	FetchPage(context.Context) pagination.PageResult[ConnectorWithDefinition]
	Enumerate(context.Context, pagination.EnumerateCallback[ConnectorWithDefinition]) error
}

type ListKeysBuilder interface {
	ListKeysExecutor
	Limit(int32) ListKeysBuilder
	ForNamespaceMatcher(matcher string) ListKeysBuilder
	ForNamespaceMatchers(matchers []string) ListKeysBuilder
	ForName(name scommon.ResourceName) ListKeysBuilder
	ForState(KeyState) ListKeysBuilder
	OrderBy(KeyOrderByField, pagination.OrderBy) ListKeysBuilder
	IncludeDeleted() ListKeysBuilder
	ForLabelSelector(selector string) ListKeysBuilder
}

type ListKeysExecutor interface {
	FetchPage(context.Context) pagination.PageResult[Key]
	Enumerate(context.Context, pagination.EnumerateCallback[Key]) error
}

type ListNamespacesBuilder interface {
	ListNamespacesExecutor
	Limit(int32) ListNamespacesBuilder
	ForPathPrefix(path string) ListNamespacesBuilder
	ForDepth(depth uint64) ListNamespacesBuilder
	ForChildrenOf(path string) ListNamespacesBuilder
	ForNamespaceMatcher(matcher string) ListNamespacesBuilder
	ForNamespaceMatchers(matchers []string) ListNamespacesBuilder
	ForName(name scommon.ResourceName) ListNamespacesBuilder
	ForState(NamespaceState) ListNamespacesBuilder
	OrderBy(NamespaceOrderByField, pagination.OrderBy) ListNamespacesBuilder
	IncludeDeleted() ListNamespacesBuilder
	ForLabelSelector(selector string) ListNamespacesBuilder
}

type ListNamespacesExecutor interface {
	FetchPage(context.Context) pagination.PageResult[Namespace]
	Enumerate(context.Context, pagination.EnumerateCallback[Namespace]) error
}

type ListNotificationsOptions struct {
	States            []NotificationState
	ResourceType      string
	ResourceId        apid.ID
	NamespaceMatchers []string
	LabelSelector     *string
	Limit             uint64
	IncludeViewed     bool
	ActorId           apid.ID
}

type ListRateLimitsBuilder interface {
	ListRateLimitsExecutor
	Limit(int32) ListRateLimitsBuilder
	ForNamespaceMatcher(matcher string) ListRateLimitsBuilder
	ForNamespaceMatchers(matchers []string) ListRateLimitsBuilder
	ForName(name scommon.ResourceName) ListRateLimitsBuilder
	OrderBy(RateLimitOrderByField, pagination.OrderBy) ListRateLimitsBuilder
	IncludeDeleted() ListRateLimitsBuilder
	ForLabelSelector(selector string) ListRateLimitsBuilder
}

type ListRateLimitsExecutor interface {
	FetchPage(context.Context) pagination.PageResult[RateLimit]
	Enumerate(context.Context, pagination.EnumerateCallback[RateLimit]) error
}

type Namespace struct {
	Path string

	State                     NamespaceState
	KeyId                     *apid.ID
	TargetDataEncryptionKeyId *apid.ID
	Labels                    Labels
	Annotations               Annotations
	CreatedAt                 time.Time
	UpdatedAt                 time.Time
	DeletedAt                 *time.Time
	// contains filtered or unexported fields
}

type NamespaceEncryptionTarget struct {
	Path                      string
	Depth                     uint64
	KeyId                     *apid.ID
	TargetDataEncryptionKeyId *apid.ID
}

type NamespaceOrderByField string

type NamespaceState string

type NamespaceTargetDataEncryptionKeyUpdate struct {
	Path                      string
	TargetDataEncryptionKeyId apid.ID
}

type Notification struct {
	// Id is the stable notification id, e.g. "ntf_...".
	Id apid.ID

	// Key is the deterministic dedupe key for the notification condition.
	// Reusing the same key upserts the active row instead of creating another
	// notification; for example:
	// "connection:cxn_...:auth_required".
	Key string

	// Level describes severity for presentation, such as "info" or "warning".
	Level NotificationLevel

	// State is "active" while the notification is visible and "resolved" once
	// the underlying condition no longer applies.
	State NotificationState

	// ResourceType names the resource that owns this notification, e.g.
	// "connection".
	ResourceType string

	// ResourceId is the owning resource id, e.g. a "cxn_..." connection id.
	ResourceId apid.ID

	// Namespace is the owning resource namespace used for list filtering and
	// permission checks, e.g. "root.acme".
	Namespace string

	// Labels is a denormalized snapshot of the owning resource labels so
	// notification lists can use label selectors such as "env=prod".
	Labels Labels

	// Title is the short user-facing summary shown in notification lists.
	Title string

	// Message is the longer user-facing explanation shown in detail surfaces.
	Message string

	// ActionUrl is the relative route for the suggested action, e.g.
	// "/connections/cxn_...?action=reauth"; it is only returned to actors that
	// satisfy ActionPermissions.
	ActionUrl *string

	// ViewPermissions are the stored permissions an actor must satisfy before
	// seeing the notification, usually a resource "get" permission.
	ViewPermissions NotificationPermissions

	// ActionPermissions are the stored permissions an actor must satisfy before
	// receiving ActionUrl/can_action=true, usually a resource "update"
	// permission.
	ActionPermissions NotificationPermissions

	// Metadata is producer-specific structured context for debugging or UI
	// hints, e.g. {"target_version": 3, "requires_reauth": true}.
	Metadata NotificationMetadata

	// ResolvedAt is set when State transitions to resolved.
	ResolvedAt *time.Time

	// CreatedAt is when the notification row was first inserted.
	CreatedAt time.Time

	// UpdatedAt is when the notification was last changed or reactivated.
	UpdatedAt time.Time

	// DeletedAt is reserved for soft deletion; non-nil rows are excluded.
	DeletedAt *time.Time
}

type NotificationLevel string

type NotificationMetadata map[string]any

type NotificationPermissions []aschema.Permission

type NotificationState string

type NotificationUpsert struct {
	Key               string
	Level             NotificationLevel
	ResourceType      string
	ResourceId        apid.ID
	Namespace         string
	Labels            map[string]string
	Title             string
	Message           string
	ActionUrl         *string
	ViewPermissions   []aschema.Permission
	ActionPermissions []aschema.Permission
	Metadata          map[string]any
}

type OAuth2ClientCredentialsPlaintext struct {
	ClientId     string `json:"clientId"`
	ClientSecret string `json:"clientSecret,omitempty"`
}

type OAuth2Token struct {
	Id                    apid.ID
	ConnectionId          apid.ID // Foreign key to Connection; not enforced by database
	RefreshedFromId       *apid.ID
	EncryptedRefreshToken encfield.EncryptedField
	EncryptedAccessToken  encfield.EncryptedField
	AccessTokenExpiresAt  *time.Time
	Scopes                string
	RequestedScopes       string
	CreatedByActorId      *apid.ID // Actor who initiated this token (carried forward on refresh)
	CreatedAt             time.Time
	EncryptedAt           *time.Time
	DeletedAt             *time.Time
}

type OAuth2TokenWithConnection struct {
	Token      OAuth2Token
	Connection Connection
}

type ParentCarryForward struct {
	Rt     string
	Labels Labels
}

type Permissions []aschema.Permission

type RateLimit struct {
	Id          apid.ID
	Namespace   string
	Name        scommon.ResourceName
	Definition  rlschema.RateLimit
	Labels      Labels
	Annotations Annotations
	CreatedAt   time.Time
	UpdatedAt   time.Time
	DeletedAt   *time.Time
}

type RateLimitOrderByField string

type ReEncryptedFieldUpdate struct {
	Table            string
	PrimaryKeyCols   []string
	PrimaryKeyValues []any
	FieldColumn      string
	NewValue         encfield.EncryptedField
}

type ReEncryptionTarget struct {
	Table                     string
	PrimaryKeyCols            []string                // column names in PK order (from registration)
	PrimaryKeyValues          []any                   // values in PK column order
	FieldColumn               string                  // which encrypted column
	EncryptedFieldValue       encfield.EncryptedField // current value (contains the active DEK ID)
	TargetDataEncryptionKeyId apid.ID                 // target DEK for the namespace
}

type ResourceSearcher interface {
	SearchResources(ctx context.Context, params SearchResourcesParams) (SearchResourcesResult, error)
}

type SearchLabelMatch struct {
	Key   string
	Value string
}

type SearchResource struct {
	ResourceType  SearchResourceType
	ResourceID    string
	Name          string
	Namespace     string
	Labels        Labels
	MatchedLabels []SearchLabelMatch
	UpdatedAt     time.Time
	MatchRank     int
}

type SearchResourceType string

type SearchResourcesParams struct {
	ResourceType      SearchResourceType
	Query             string
	LabelSelector     string
	NamespaceMatchers []string
	Limit             int
}

type SearchResourcesResult struct {
	Items     []SearchResource
	Truncated bool
}

type UsedNonce struct {
	Id          apid.ID
	RetainUntil time.Time
	CreatedAt   time.Time
}