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
	ConnectorGeneration    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 ConnectionGenerationMigrationUpdate struct {
	Id                     apid.ID
	ConnectorId            apid.ID
	ConnectorGeneration    uint64
	EncryptedConfiguration *encfield.EncryptedField
	UserLabels             map[string]string
	Annotations            map[string]string
	SetupStep              *cschema.SetupStep
	SetupError             *string
	HealthState            *ConnectionHealthState
}

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 Connector struct {
	Id          apid.ID
	Namespace   string
	Name        scommon.ResourceName
	Labels      Labels
	Annotations Annotations
	CreatedAt   time.Time
	UpdatedAt   time.Time
	DeletedAt   *time.Time
}

type ConnectorGeneration struct {
	Id                  apid.ID
	ConnectorId         apid.ID
	Generation          uint64
	State               ConnectorGenerationState
	EncryptedDefinition encfield.EncryptedField
	CreatedAt           time.Time
	UpdatedAt           time.Time
	EncryptedAt         *time.Time
	DeletedAt           *time.Time
}

type ConnectorGenerationId struct {
	Id         apid.ID
	Generation uint64
}

type ConnectorGenerationOrderByField string

type ConnectorGenerationState string

type ConnectorOrderByField string

type ConnectorWithDefinition struct {
	Id                     apid.ID
	Namespace              string
	Name                   scommon.ResourceName
	DefinitionGenerationId apid.ID
	Generation             uint64
	State                  ConnectorGenerationState
	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)
	Ping(ctx context.Context) bool
	SearchResources(ctx context.Context, params SearchResourcesParams) (SearchResourcesResult, error)

	ResolveActorReference(ctx context.Context, reference meta.ObjectReference) (*Actor, error)
	ResolveConnectionReference(ctx context.Context, reference meta.ObjectReference) (*Connection, error)
	ResolveConnectorReference(ctx context.Context, reference meta.ObjectReference) (*Connector, error)
	ResolveKeyReference(ctx context.Context, reference meta.ObjectReference) (*Key, error)
	ResolveNamespaceReference(ctx context.Context, reference meta.ObjectReference) (*Namespace, error)
	ResolveRateLimitReference(ctx context.Context, reference meta.ObjectReference) (*RateLimit, 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)

	GetConnectorGeneration(ctx context.Context, id apid.ID, generation uint64) (*ConnectorWithDefinition, error)
	GetConnectorGenerations(ctx context.Context, requested []ConnectorGenerationId) (map[ConnectorGenerationId]*ConnectorWithDefinition, error)
	GetConnectorGenerationForState(ctx context.Context, id apid.ID, state ConnectorGenerationState) (*ConnectorWithDefinition, error)
	NewestConnectorGenerationForId(ctx context.Context, id apid.ID) (*ConnectorWithDefinition, error)
	NewestPublishedConnectorGenerationForId(ctx context.Context, id apid.ID) (*ConnectorWithDefinition, error)
	UpsertConnectorGeneration(ctx context.Context, cv *ConnectorWithDefinition) error
	SetConnectorGenerationState(ctx context.Context, id apid.ID, generation uint64, state ConnectorGenerationState) error
	UpdateConnectorName(ctx context.Context, id apid.ID, name scommon.ResourceName) error
	UpdateConnectorLabels(
		ctx context.Context,
		id apid.ID,
		labels map[string]string,
	) (*Connector, error)
	UpdateConnectorAnnotations(
		ctx context.Context,
		id apid.ID,
		annotations map[string]string,
	) (*Connector, error)
	DeleteConnector(ctx context.Context, id apid.ID) error
	ListConnectorGenerationsBuilder() ListConnectorGenerationsBuilder
	ListConnectorGenerationsFromCursor(ctx context.Context, cursor string) (ListConnectorGenerationsExecutor, error)
	ListConnectorsBuilder() ListConnectorsBuilder
	ListConnectorsFromCursor(ctx context.Context, cursor string) (ListConnectorsExecutor, error)

	CreateToolSet(ctx context.Context, toolSet *ToolSet) error
	GetToolSet(ctx context.Context, id apid.ID) (*ToolSet, error)
	GetToolSetByName(ctx context.Context, namespace string, name scommon.ResourceName) (*ToolSet, error)
	UpdateToolSetConnectionSelector(ctx context.Context, id apid.ID, expectedRevision uint64, selector toolsetschema.ConnectionSelector) (*ToolSet, error)
	DeleteToolSet(ctx context.Context, id apid.ID) error

	// UpdateToolSetMetadata replaces the logical name, user labels, and
	// annotations without touching the selector or any generation.
	UpdateToolSetMetadata(ctx context.Context, id apid.ID, name scommon.ResourceName, userLabels map[string]string, annotations map[string]string) (*ToolSet, error)

	// ListToolSetsBuilder pages through live logical ToolSets within a namespace scope.
	ListToolSetsBuilder() ListToolSetsBuilder
	ListToolSetsFromCursor(ctx context.Context, cursor string) (ListToolSetsExecutor, error)

	// ListToolSetGenerationsBuilder pages through one live ToolSet's generations, newest first.
	ListToolSetGenerationsBuilder() ListToolSetGenerationsBuilder
	ListToolSetGenerationsFromCursor(ctx context.Context, cursor string) (ListToolSetGenerationsExecutor, error)

	// CreateToolSetGeneration allocates a new draft under a live parent. Only one
	// live draft may exist, and historical generation numbers are never reused.
	CreateToolSetGeneration(ctx context.Context, id apid.ID, definition encfield.EncryptedField) (*ToolSetGeneration, error)

	// GetToolSetGeneration returns one generation if it and its parent are live.
	GetToolSetGeneration(ctx context.Context, id apid.ID, generation uint64) (*ToolSetGeneration, error)

	// GetToolSetGenerationByState finds the sole draft or primary generation.
	GetToolSetGenerationByState(ctx context.Context, id apid.ID, state toolsetschema.ToolSetReleaseState) (*ToolSetGeneration, error)

	// UpdateToolSetGenerationDraft replaces only the expected editable revision
	// and advances its revision. Published plaintext cannot be changed here.
	UpdateToolSetGenerationDraft(ctx context.Context, id apid.ID, generation uint64, expectedRevision uint64, definition encfield.EncryptedField) (*ToolSetGeneration, error)

	// PublishToolSetGeneration atomically promotes the expected draft revision and
	// demotes the former primary. The caller must validate the definition and any
	// imported source snapshot before publishing; bindings are not migrated here.
	PublishToolSetGeneration(ctx context.Context, id apid.ID, generation uint64, expectedRevision uint64) (*ToolSetGeneration, error)

	// CreateToolSetBinding creates a pending assignment from the current matched
	// selector snapshot. It does not install a generation or inventory.
	CreateToolSetBinding(ctx context.Context, toolSetId apid.ID, connectionId apid.ID, expectedSelectorRevision uint64) (*ToolSetBinding, error)

	// GetToolSetBinding returns a live assignment whose two parents are live.
	GetToolSetBinding(ctx context.Context, id apid.ID) (*ToolSetBinding, error)

	// GetToolSetBindingForConnection finds the current assignment for a parent pair.
	GetToolSetBindingForConnection(ctx context.Context, toolSetId apid.ID, connectionId apid.ID) (*ToolSetBinding, error)

	// ListToolSetBindingsBuilder starts a listing of one connection's live assignments.
	ListToolSetBindingsBuilder() ListToolSetBindingsBuilder

	// ListToolSetBindingsFromCursor continues a binding listing with its saved filters.
	ListToolSetBindingsFromCursor(ctx context.Context, cursor string) (ListToolSetBindingsExecutor, error)

	// InstallExplicitToolSetInventory atomically pins a pending binding to its
	// prepared primary generation and installs its complete first Tool inventory.
	InstallExplicitToolSetInventory(ctx context.Context, install ToolSetInventoryInstall) (*ToolSetBinding, error)

	// ReplaceExplicitToolSetInventory replaces an installed inventory at its
	// captured epoch/generation, preserving identities for retained source keys.
	ReplaceExplicitToolSetInventory(ctx context.Context, install ToolSetInventoryInstall, expectedGeneration uint64) (*ToolSetBinding, error)

	// DeleteToolSetBinding retires a no-longer-matching assignment using its epoch
	// and current selector snapshot. Deleted-parent cleanup ignores selector revision.
	DeleteToolSetBinding(ctx context.Context, id apid.ID, expectedEpoch uint64, expectedSelectorRevision uint64) error

	// CreateStandaloneTool atomically stores an identity and its first active definition.
	CreateStandaloneTool(ctx context.Context, tool *Tool, definition encfield.EncryptedField, digest string) (*ToolRevision, error)

	// GetTool reads a live identity, including those whose connection was deleted.
	GetTool(ctx context.Context, id apid.ID) (*Tool, error)

	// ListToolCandidates scans bounded current metadata for later authorization;
	// its internal pages and cursors must not be exposed as discovery results.
	ListToolCandidates(ctx context.Context, query ToolCandidateQuery) (ToolCandidatePage, error)

	// ListToolCandidatesFromCursor resumes a candidate scan with its saved filters
	// and limit. Callers must still authorize each returned candidate.
	ListToolCandidatesFromCursor(ctx context.Context, cursor string) (ToolCandidatePage, error)

	// ListToolsBuilder pages live Tool identities for management, independent of
	// connection liveness. Callers must still check per-resource permissions.
	ListToolsBuilder() ListToolsBuilder

	// ListToolsFromCursor resumes a management listing with its saved filters.
	ListToolsFromCursor(ctx context.Context, cursor string) (ListToolsExecutor, error)

	// UpdateStandaloneTool appends a revision and switches the pointer only if the observed revision is current.
	UpdateStandaloneTool(ctx context.Context, tool *Tool, expectedRevision uint64, definition encfield.EncryptedField, digest string) (*ToolRevision, error)

	// DeleteStandaloneTool removes the observed identity while retaining its revision history.
	DeleteStandaloneTool(ctx context.Context, id apid.ID, expectedRevision uint64) error

	// GetCurrentToolRevision reads the active definition and its connection identity in one SQL snapshot.
	GetCurrentToolRevision(ctx context.Context, id apid.ID) (*ToolRevision, error)

	// GetToolExecutionSnapshot captures the active definition, connection configuration,
	// pinned connector definition, and ToolSet provenance together for invocation admission.
	// Callers still authorize the revision and check expected revision and readiness.
	GetToolExecutionSnapshot(ctx context.Context, id apid.ID) (*ToolExecutionSnapshot, error)

	// GetToolRevision inspects retained history; it does not select a definition for invocation.
	GetToolRevision(ctx context.Context, id apid.ID, revision uint64) (*ToolRevision, 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)
	UpdateConnectionForGenerationMigration(ctx context.Context, update ConnectionGenerationMigrationUpdate) (*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,
		refreshTokenExpiry OAuth2RefreshTokenExpiry,
		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. It also includes tokens whose refresh token is due for
	// a proactive refresh (refresh_token_refresh_at has passed) regardless of access-token expiry. 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
	// DeleteUnusedKey refuses keys with namespace references or any DEK history.
	DeleteUnusedKey(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.RateLimitSpec) (*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 sets the new value and encrypted_at only on live
	// rows whose encrypted field still matches ExpectedValue. Stale updates are
	// skipped without error; earlier updates may be applied if a later one fails.
	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", "generation"]
	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 ListConnectorGenerationsBuilder interface {
	ListConnectorGenerationsExecutor
	Limit(int32) ListConnectorGenerationsBuilder
	ForId(apid.ID) ListConnectorGenerationsBuilder
	ForGeneration(uint64) ListConnectorGenerationsBuilder
	ForState(ConnectorGenerationState) ListConnectorGenerationsBuilder
	ForStates([]ConnectorGenerationState) ListConnectorGenerationsBuilder
	ForNamespaceMatcher(string) ListConnectorGenerationsBuilder
	ForNamespaceMatchers([]string) ListConnectorGenerationsBuilder
	ForName(name scommon.ResourceName) ListConnectorGenerationsBuilder
	OrderBy(ConnectorGenerationOrderByField, pagination.OrderBy) ListConnectorGenerationsBuilder
	IncludeDeleted() ListConnectorGenerationsBuilder
	ForLabelSelector(selector string) ListConnectorGenerationsBuilder
}

type ListConnectorGenerationsExecutor 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(ConnectorGenerationState) ListConnectorsBuilder
	ForStates([]ConnectorGenerationState) 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 ListToolSetBindingsBuilder interface {
	ListToolSetBindingsExecutor

	// Limit sets the page size. Non-positive values select the default and values
	// above MaxToolSetBindingListLimit are capped.
	Limit(int32) ListToolSetBindingsBuilder

	// ForConnectionId selects the connection whose assignments are listed.
	ForConnectionId(apid.ID) ListToolSetBindingsBuilder

	// ForToolSetNamespaceMatchers replaces the scope of visible parent ToolSets.
	// This scopes the ToolSet's namespace, which can be an ancestor of the
	// connection's. Replacing means a later call can never widen an earlier scope.
	ForToolSetNamespaceMatchers([]string) ListToolSetBindingsBuilder
}

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

type ListToolSetGenerationsBuilder interface {
	ListToolSetGenerationsExecutor

	// Limit sets the page size. Non-positive values select the default and values
	// above MaxToolSetListLimit are capped.
	Limit(int32) ListToolSetGenerationsBuilder

	// ForToolSetId selects the parent ToolSet.
	ForToolSetId(apid.ID) ListToolSetGenerationsBuilder

	// OrderBy selects the sort column and direction. Generation number always
	// breaks ties, newest first, so pages stay deterministic.
	OrderBy(ToolSetGenerationOrderByField, pagination.OrderBy) ListToolSetGenerationsBuilder
}

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

type ListToolSetsBuilder interface {
	ListToolSetsExecutor

	// Limit sets the page size. Non-positive values select the default and values
	// above MaxToolSetListLimit are capped.
	Limit(int32) ListToolSetsBuilder

	// ForNamespaceMatcher replaces the namespace scope with one matcher.
	ForNamespaceMatcher(string) ListToolSetsBuilder

	// ForNamespaceMatchers replaces the namespace scope. Replacing, rather than
	// adding to it, means a later call can never widen an earlier scope.
	ForNamespaceMatchers([]string) ListToolSetsBuilder

	// ForName selects one exact resource name.
	ForName(common.ResourceName) ListToolSetsBuilder

	// ForLabelSelector matches the logical ToolSet's labels, including inherited
	// namespace labels and self-implicit identity labels.
	ForLabelSelector(string) ListToolSetsBuilder

	// OrderBy selects the sort column and direction. Results always fall back to
	// ID so pages stay deterministic when sort values tie; the default sorts by ID.
	OrderBy(ToolSetOrderByField, pagination.OrderBy) ListToolSetsBuilder
}

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

type ListToolsBuilder interface {
	ListToolsExecutor

	// Limit sets the page size. Non-positive values select the default and values
	// above MaxToolListLimit are capped.
	Limit(int32) ListToolsBuilder

	// ForNamespaceMatcher replaces the namespace scope with one matcher.
	ForNamespaceMatcher(string) ListToolsBuilder

	// ForNamespaceMatchers replaces the namespace scope. Replacing, rather than
	// adding to it, means a later call can never widen an earlier scope.
	ForNamespaceMatchers([]string) ListToolsBuilder

	// ForName selects one exact resource name.
	ForName(common.ResourceName) ListToolsBuilder

	// ForConnectionId selects Tools currently bound to one connection.
	ForConnectionId(apid.ID) ListToolsBuilder

	// ForLabelSelector matches Tool labels, including inherited connection identity.
	ForLabelSelector(string) ListToolsBuilder

	// OrderBy selects the sort column and direction. Results always fall back to
	// ID so pages stay deterministic when sort values tie; the default sorts by ID.
	OrderBy(ToolOrderByField, pagination.OrderBy) ListToolsBuilder
}

type ListToolsExecutor interface {
	FetchPage(context.Context) pagination.PageResult[Tool]
	Enumerate(context.Context, pagination.EnumerateCallback[Tool]) 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_generation": 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 OAuth2RefreshTokenExpiry struct {
	// ExpiresAt is when the refresh token stops working.
	ExpiresAt *time.Time
	// RefreshAt is when to proactively refresh to keep the connection alive.
	RefreshAt *time.Time
}

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
	// RefreshTokenExpiresAt is when the provider says the refresh token
	// stops working, derived from refresh_token_expires_in and related
	// token-response fields. Nil when the provider did not say.
	RefreshTokenExpiresAt *time.Time
	// RefreshTokenRefreshAt is when the background refresh task should
	// proactively refresh this token so that a new (or renewed) refresh
	// token is obtained before RefreshTokenExpiresAt. Nil when refreshing
	// cannot extend the refresh token's life or background refresh is off.
	RefreshTokenRefreshAt *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 PreparedToolSetTool struct {
	Tool                Tool
	EncryptedDefinition encfield.EncryptedField
	DefinitionDigest    string
}

type RateLimit struct {
	Id          apid.ID
	Namespace   string
	Name        scommon.ResourceName
	Definition  rlschema.RateLimitSpec
	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

	// ExpectedValue is the nonzero encrypted value read before re-encryption.
	// Both its key ID and ciphertext must still match when NewValue is written.
	ExpectedValue encfield.EncryptedField
	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 Tool struct {
	Id             apid.ID
	Namespace      string
	Name           common.ResourceName
	ConnectionId   apid.ID
	ActiveRevision uint64
	CreatedAt      time.Time
	UpdatedAt      time.Time
	DeletedAt      *time.Time

	// Labels contains user labels plus derived apxy/ labels. Standalone writes
	// regenerate the system portion instead of trusting supplied projections.
	Labels Labels
	// Annotations belong to the Tool; parent annotations are never inherited.
	Annotations Annotations

	// Description is the active definition's public descriptive text. The trusted
	// preparer supplies it from the same plaintext it encrypts; this layer cannot
	// verify that correspondence. Never put resolved configuration or credentials
	// into this projection. Legacy rows may be empty until a definition update.
	Description string
	// Verbs are exact permission aliases, stored in sorted order. They support
	// candidate filtering, not authorization by themselves. Legacy nil values
	// mean unprepared, never unrestricted access. Historical aliases remain in
	// the encrypted revision; this list always describes ActiveRevision.
	Verbs []string

	// BindingId identifies the controller assignment that owns this Tool; nil
	// means standalone. A binding's removal/recreation creates a new identity.
	BindingId apid.ID
	// SourceKey is the exact source identity within a binding, independent of
	// display name. It is empty only for standalone Tools. The pair stays unique
	// across tombstones so a later inventory can restore the original Tool ID.
	SourceKey string
}

type ToolCandidate struct {
	Id             apid.ID
	Namespace      string
	Name           common.ResourceName
	ConnectionId   apid.ID
	ConnectionName common.ResourceName
	ActiveRevision uint64
	Description    string
	Verbs          []string
	Labels         Labels
	// ConnectionLabels is the current connection row's own label snapshot,
	// rather than the Tool's potentially lagging inherited label projection.
	ConnectionLabels Labels
}

type ToolCandidatePage struct {
	Items []ToolCandidate
	// Cursor resumes through ListToolCandidatesFromCursor with the same filters
	// and limit. It is empty at the end. The opaque cursor preserves a position
	// in the producing database's ID order; it does not confer authorization.
	Cursor string
}

type ToolCandidateQuery struct {
	// NamespaceMatchers is an explicit scan scope. Nil or empty matches nothing.
	NamespaceMatchers []string `json:"namespaceMatchers"`

	// LabelSelector matches Tool labels, including inherited connection identity.
	LabelSelector string `json:"labelSelector"`

	// AnyVerbs matches exact literal aliases, never permission wildcard patterns.
	// Nil omits this prefilter; a nonnil empty slice matches nothing. The caller
	// must still check actor/JWT permission intersection for the same Tool alias.
	// Preserve nil versus empty when serializing a continuation cursor.
	AnyVerbs []string `json:"anyVerbs"`

	// Limit must be between one and MaxToolCandidateLimit; there is no default.
	Limit int `json:"limit"`
}

type ToolExecutionSnapshot struct {
	// Revision is the active Tool definition, including its schemas, aliases,
	// and captured source generation. It belongs to Connection.Id.
	Revision ToolRevision

	// Connection captures configuration ciphertext, effective stored labels,
	// annotations, lifecycle/setup/health state, and the pinned connector
	// identity. For example, a tenant configuration changed after this read does
	// not replace the tenant used by this invocation's templates.
	Connection Connection

	// Connector is the exact generation referenced by Connection, with its
	// logical metadata and encrypted definition. Hydration can build the
	// connection client from these rows without rereading its generation pin.
	Connector ConnectorWithDefinition

	// ToolSetId identifies the live installed binding's owner for a generated
	// Tool. It is apid.Nil for a standalone Tool; Revision.SourceGeneration
	// supplies the corresponding ToolSet generation.
	ToolSetId apid.ID
}

type ToolOrderByField string

type ToolRevision struct {
	ToolId              apid.ID
	Revision            uint64
	ConnectionId        apid.ID
	EncryptedDefinition encfield.EncryptedField

	// DefinitionDigest is lowercase SHA-256 of the caller's canonical plaintext
	// definition, independent of randomized encryption and later key rotation.
	DefinitionDigest string
	CreatedAt        time.Time
	EncryptedAt      *time.Time
	DeletedAt        *time.Time

	// SourceGeneration is nil for standalone Tools and identifies the published
	// generation used to prepare a generated revision. The Tool's immutable
	// binding supplies its source ToolSet; later installations do not rewrite it.
	SourceGeneration *uint64
}

type ToolSet struct {
	Id                 apid.ID
	Namespace          string
	Name               common.ResourceName
	Labels             Labels
	Annotations        Annotations
	ConnectionSelector toolsetschema.ConnectionSelector

	// SelectorRevision starts at one and advances with each accepted selector
	// replacement. It fences membership work independently of generation numbers.
	SelectorRevision uint64
	CreatedAt        time.Time
	UpdatedAt        time.Time
	DeletedAt        *time.Time
}

type ToolSetBinding struct {
	Id           apid.ID
	ToolSetId    apid.ID
	ConnectionId apid.ID

	// Epoch starts at one and advances on inventory installation and removal.
	// Future inventory and context changes must advance it too.
	// It protects one assignment's lifetime, not the lifetime of the parent pair.
	Epoch     uint64
	CreatedAt time.Time
	UpdatedAt time.Time
	DeletedAt *time.Time

	// AppliedGeneration is nil until the first complete inventory is installed.
	// Removed bindings retain their last installed generation for inspection.
	AppliedGeneration *uint64
	// InventoryRevision is zero while pending and advances with complete
	// inventories. It differs from Epoch, which also advances on removal.
	InventoryRevision uint64
}

type ToolSetBindingListing struct {
	ToolSetBinding
	ConnectionNamespace string
	ToolSetNamespace    string
	ToolSetName         common.ResourceName
}

type ToolSetGeneration struct {
	ToolSetId           apid.ID
	Generation          uint64
	State               toolsetschema.ToolSetReleaseState
	EncryptedDefinition encfield.EncryptedField

	// Revision starts at one and advances on every accepted draft replacement.
	// Publication compares the revision the caller validated. It is independent
	// of the logical ToolSet's selector revision and of encryption-key rotation.
	Revision    uint64
	CreatedAt   time.Time
	UpdatedAt   time.Time
	EncryptedAt *time.Time
	DeletedAt   *time.Time
}

type ToolSetGenerationOrderByField string

type ToolSetInventoryInstall struct {
	BindingId                apid.ID
	ExpectedEpoch            uint64
	ExpectedSelectorRevision uint64
	Generation               uint64
	Tools                    []PreparedToolSetTool
}

type ToolSetOrderByField string

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