api

type APITokenInsert struct {
	ID              uuid.UUID
	Name            string
	Prefix          string
	Hash            string
	Scopes          []string
	CreatedByUserID uuid.UUID
	ExpiresAt       *time.Time
	// BoundCloudAccountID is set when minting a vm-collector PAT
	// (ADR-0015). The store persists it on the api_tokens row;
	// nullable for every other token kind.
	BoundCloudAccountID *uuid.UUID
}

type APITokenListFilter struct {
	Name *string
}

type ApiToken struct {
	CreatedAt       *time.Time          `json:"created_at,omitempty"`
	CreatedByUserId *openapi_types.UUID `json:"created_by_user_id,omitempty"`
	ExpiresAt       *time.Time          `json:"expires_at,omitempty"`
	Id              *openapi_types.UUID `json:"id,omitempty"`
	LastUsedAt      *time.Time          `json:"last_used_at,omitempty"`

	// Name Human-chosen label (e.g., `"ci-release-pipeline"`).
	Name string `json:"name"`

	// Prefix First 8 characters of the plaintext token. Displayed alongside
	// the token name so operators can identify which token is in use
	// without revealing the full value.
	Prefix    *string    `json:"prefix,omitempty"`
	RevokedAt *time.Time `json:"revoked_at,omitempty"`
	Scopes    []string   `json:"scopes"`
}

type ApiTokenCreate struct {
	// ExpiresAt Optional expiry. If absent, the token is valid until revoked.
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
	Name      string     `json:"name"`

	// Scopes Scopes to grant. Admin scope cannot be granted to tokens —
	// admin-only endpoints are session-only for accountability.
	Scopes []ApiTokenCreateScopes `json:"scopes"`
}

type ApiTokenCreateScopes string

type ApiTokenList struct {
	Items      []ApiToken `json:"items"`
	NextCursor *string    `json:"next_cursor,omitempty"`
}

type ApiTokenMint struct {
	CreatedAt       *time.Time          `json:"created_at,omitempty"`
	CreatedByUserId *openapi_types.UUID `json:"created_by_user_id,omitempty"`
	ExpiresAt       *time.Time          `json:"expires_at,omitempty"`
	Id              *openapi_types.UUID `json:"id,omitempty"`
	LastUsedAt      *time.Time          `json:"last_used_at,omitempty"`

	// Name Human-chosen label (e.g., `"ci-release-pipeline"`).
	Name string `json:"name"`

	// Prefix First 8 characters of the plaintext token. Displayed alongside
	// the token name so operators can identify which token is in use
	// without revealing the full value.
	Prefix    *string    `json:"prefix,omitempty"`
	RevokedAt *time.Time `json:"revoked_at,omitempty"`
	Scopes    []string   `json:"scopes"`

	// Token Plaintext token, format `lv_pat_<8chars>_<random>`.
	// Presented exactly once. Store in a secrets manager; do
	// not commit to source control.
	Token string `json:"token"`
}

type Application struct {
	ID                 uuid.UUID  `json:"id"`
	Name               string     `json:"name"`
	DisplayName        *string    `json:"display_name,omitempty"`
	Description        *string    `json:"description,omitempty"`
	ApplicationBlockID *uuid.UUID `json:"application_block_id,omitempty"`
	// Denormalised on list responses (ADR-0027).
	ApplicationBlockName *string `json:"application_block_name,omitempty"`

	Owner       *string           `json:"owner,omitempty"`
	Criticality *string           `json:"criticality,omitempty"`
	Notes       *string           `json:"notes,omitempty"`
	RunbookURL  *string           `json:"runbook_url,omitempty"`
	Annotations map[string]string `json:"annotations"`

	SecDisponibilite   *int    `json:"sec_disponibilite,omitempty"`
	SecIntegrite       *int    `json:"sec_integrite,omitempty"`
	SecConfidentialite *int    `json:"sec_confidentialite,omitempty"`
	SecTracabilite     *int    `json:"sec_tracabilite,omitempty"`
	SecNotes           *string `json:"sec_notes,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`

	MemberCounts ApplicationMemberCounts `json:"member_counts"`
}

type ApplicationBlock struct {
	ID          uuid.UUID         `json:"id"`
	Name        string            `json:"name"`
	DisplayName *string           `json:"display_name,omitempty"`
	Description *string           `json:"description,omitempty"`
	Owner       *string           `json:"owner,omitempty"`
	Notes       *string           `json:"notes,omitempty"`
	Annotations map[string]string `json:"annotations"`
	CreatedAt   time.Time         `json:"created_at"`
	UpdatedAt   time.Time         `json:"updated_at"`

	// Denormalised for list responses (ADR-0027 pattern).
	ApplicationCount int `json:"application_count,omitempty"`
}

type ApplicationBlockCreate struct {
	Name        string             `json:"name"`
	DisplayName *string            `json:"display_name,omitempty"`
	Description *string            `json:"description,omitempty"`
	Owner       *string            `json:"owner,omitempty"`
	Notes       *string            `json:"notes,omitempty"`
	Annotations *map[string]string `json:"annotations,omitempty"`
}

type ApplicationBlockId = openapi_types.UUID

type ApplicationBlockListFilter struct {
	Name  *string
	Owner *string
}

type ApplicationBlockPatch struct {
	DisplayName *string            `json:"display_name,omitempty"`
	Description *string            `json:"description,omitempty"`
	Owner       *string            `json:"owner,omitempty"`
	Notes       *string            `json:"notes,omitempty"`
	Annotations *map[string]string `json:"annotations,omitempty"`
}

type ApplicationCreate struct {
	Name                 string             `json:"name"`
	DisplayName          *string            `json:"display_name,omitempty"`
	Description          *string            `json:"description,omitempty"`
	ApplicationBlockID   *uuid.UUID         `json:"application_block_id,omitempty"`
	ApplicationBlockName *string            `json:"application_block_name,omitempty"`
	Owner                *string            `json:"owner,omitempty"`
	Criticality          *string            `json:"criticality,omitempty"`
	Notes                *string            `json:"notes,omitempty"`
	RunbookURL           *string            `json:"runbook_url,omitempty"`
	Annotations          *map[string]string `json:"annotations,omitempty"`
	SecDisponibilite     *int               `json:"sec_disponibilite,omitempty"`
	SecIntegrite         *int               `json:"sec_integrite,omitempty"`
	SecConfidentialite   *int               `json:"sec_confidentialite,omitempty"`
	SecTracabilite       *int               `json:"sec_tracabilite,omitempty"`
	SecNotes             *string            `json:"sec_notes,omitempty"`
}

type ApplicationEOLRow struct {
	// Cycle Release cycle from endoflife.date, when known (eol rows only).
	Cycle *string `json:"cycle,omitempty"`

	// EolStatus Lifecycle status. `eol` / `approaching_eol` / `supported`
	// come from the endoflife.date enricher on VMs (signal=eol rows).
	// Always `unknown` on signal=freshness rows.
	EolStatus ApplicationEOLRowEolStatus `json:"eol_status"`

	// EvaluatedAt When the underlying signal was last evaluated (RFC 3339).
	EvaluatedAt *string `json:"evaluated_at,omitempty"`

	// Freshness Version-distance freshness bucket for workload container images
	// (signal=freshness rows). `up_to_date` (same minor or patch-only
	// delta), `outdated` (one minor behind), `far_behind` (two or more
	// minors behind or any major gap), `unknown` (not enriched).
	// Absent on signal=eol rows.
	Freshness *ApplicationEOLRowFreshness `json:"freshness,omitempty"`

	// LatestAvailable Newest published version / tag known for the product.
	LatestAvailable *string `json:"latest_available,omitempty"`

	// Product Normalised product key (kebab-case) or container name.
	Product string `json:"product"`

	// Signal Discriminator for the lifecycle signal kind.
	// `eol` rows come from VM endoflife.date annotations;
	// `freshness` rows come from workload image-versions enrichment.
	Signal ApplicationEOLRowSignal `json:"signal"`

	// Sources Member assets contributing this product's lifecycle signal.
	Sources []ApplicationEOLSource `json:"sources"`
}

type ApplicationEOLRowEolStatus string

type ApplicationEOLRowFreshness string

type ApplicationEOLRowSignal string

type ApplicationEOLSource struct {
	// Id Asset identifier. A UUID for workloads / VMs; a composite
	// `<vm-uuid>#<product>` for VM-application entries.
	Id   string                   `json:"id"`
	Kind ApplicationEOLSourceKind `json:"kind"`
	Name string                   `json:"name"`
}

type ApplicationEOLSourceKind string

type ApplicationExtractStore interface {
	ListApplications(ctx context.Context, filter ApplicationListFilter, page ListPage) ([]Application, string, error)
}

type ApplicationId = openapi_types.UUID

type ApplicationListFilter struct {
	Name                 *string // case-insensitive substring on name + display_name
	ApplicationBlockID   *uuid.UUID
	ApplicationBlockName *string
	Criticality          *string
	HasDICT              *bool
	DICTMin              *int // MAX(sec_*) >= N
}

type ApplicationMember struct {
	Kind     ApplicationMemberKind `json:"kind"`
	ID       string                `json:"id"` // UUID for workload/VM; "<vm_id>#<product>#<name>" for vm_application
	Name     string                `json:"name"`
	Parent   *ApplicationMemberRef `json:"parent,omitempty"`
	Linked   time.Time             `json:"linked_at"`
	LinkedBy string                `json:"linked_by"`
}

type ApplicationMemberCounts struct {
	Workloads       int `json:"workloads"`
	VirtualMachines int `json:"virtual_machines"`
	VMApplications  int `json:"vm_applications"`
}

type ApplicationMemberKind string

type ApplicationMemberRef struct {
	Kind string `json:"kind"`
	ID   string `json:"id"`
	Name string `json:"name"`
}

type ApplicationPatch struct {
	DisplayName          *string            `json:"display_name,omitempty"`
	Description          *string            `json:"description,omitempty"`
	ApplicationBlockID   *uuid.UUID         `json:"application_block_id,omitempty"`
	ApplicationBlockName *string            `json:"application_block_name,omitempty"`
	Owner                *string            `json:"owner,omitempty"`
	Criticality          *string            `json:"criticality,omitempty"`
	Notes                *string            `json:"notes,omitempty"`
	RunbookURL           *string            `json:"runbook_url,omitempty"`
	Annotations          *map[string]string `json:"annotations,omitempty"`
	SecDisponibilite     *int               `json:"sec_disponibilite,omitempty"`
	SecIntegrite         *int               `json:"sec_integrite,omitempty"`
	SecConfidentialite   *int               `json:"sec_confidentialite,omitempty"`
	SecTracabilite       *int               `json:"sec_tracabilite,omitempty"`
	SecNotes             *string            `json:"sec_notes,omitempty"`
}

type ApplicationStore interface {
	// Application blocks (ADR-0029).
	CreateApplicationBlock(ctx context.Context, in ApplicationBlockCreate) (ApplicationBlock, error)
	GetApplicationBlock(ctx context.Context, id uuid.UUID) (ApplicationBlock, error)
	GetApplicationBlockByName(ctx context.Context, name string) (ApplicationBlock, error)
	ListApplicationBlocks(
		ctx context.Context,
		filter ApplicationBlockListFilter,
		page ListPage,
	) (items []ApplicationBlock, nextCursor string, err error)
	UpdateApplicationBlock(ctx context.Context, id uuid.UUID, in ApplicationBlockPatch) (ApplicationBlock, error)
	DeleteApplicationBlock(ctx context.Context, id uuid.UUID) error

	// Applications (ADR-0029).
	CreateApplication(ctx context.Context, in ApplicationCreate) (Application, error)
	GetApplication(ctx context.Context, id uuid.UUID) (Application, error)
	// GetApplicationsByIDs bulk-fetches applications by id in a single query,
	// returned keyed by id. Unknown ids are silently omitted from the map
	// (no error). Used by the effective-DICT decoration on workload + VM
	// list responses to avoid an N+1 (ADR-0029 §6).
	GetApplicationsByIDs(ctx context.Context, ids []uuid.UUID) (map[uuid.UUID]Application, error)
	GetApplicationByName(ctx context.Context, name string) (Application, error)
	ListApplications(ctx context.Context, filter ApplicationListFilter, page ListPage) (items []Application, nextCursor string, err error)
	UpdateApplication(ctx context.Context, id uuid.UUID, in ApplicationPatch) (Application, error)
	DeleteApplication(ctx context.Context, id uuid.UUID) error
	ListApplicationMembers(
		ctx context.Context,
		id uuid.UUID,
		kind string,
		limit int,
		cursor string,
	) (items []ApplicationMember, nextCursor string, err error)
	// DICTCoverageCounts returns the number of workloads in each
	// effective-DICT source bucket (application | workload | none), feeding
	// the longue_vue_dict_coverage gauge (ADR-0029 §6).
	DICTCoverageCounts(ctx context.Context) (application, workload, none int, err error)
}

type AuditEvent struct {
	// Action Dot-separated verb such as `user.create`, `cluster.update`,
	// `auth.login.success`, `auth.login.failure`.
	Action string `json:"action"`

	// ActorId Null for unauthenticated requests (e.g. failed logins).
	ActorId       *openapi_types.UUID `json:"actor_id,omitempty"`
	ActorKind     AuditEventActorKind `json:"actor_kind"`
	ActorRole     *string             `json:"actor_role,omitempty"`
	ActorUsername *string             `json:"actor_username,omitempty"`

	// Details Action-specific payload. Always an object when present.
	Details    *map[string]interface{} `json:"details,omitempty"`
	HttpMethod string                  `json:"http_method"`
	HttpPath   string                  `json:"http_path"`
	HttpStatus int                     `json:"http_status"`
	Id         openapi_types.UUID      `json:"id"`
	OccurredAt time.Time               `json:"occurred_at"`

	// ResourceId Stringified id of the target — may not be a UUID for all kinds.
	ResourceId *string `json:"resource_id,omitempty"`

	// ResourceType Kind of the target entity (e.g. `cluster`, `user`, `api_token`).
	ResourceType *string `json:"resource_type,omitempty"`

	// Source Which listener served the request. `api` is longue-vue's public
	// listener (humans, admins, trusted-zone collectors). `ingest_gw`
	// is the mTLS-only ingest listener fronted by the DMZ gateway
	// (ADR-0016). `system` is for synthetic events emitted by longue-vue
	// itself, not driven by an HTTP request.
	Source    *AuditEventSource `json:"source,omitempty"`
	SourceIp  *string           `json:"source_ip,omitempty"`
	UserAgent *string           `json:"user_agent,omitempty"`
}

type AuditEventActorKind string

type AuditEventFilter struct {
	ActorID      *uuid.UUID
	ResourceType *string
	ResourceID   *string
	Action       *string
	// Source filters by listener — "api", "ingest_gw", or "system"
	// (ADR-0016 §11). Nil = any source.
	Source *string
	Since  *time.Time
	Until  *time.Time
}

type AuditEventInsert struct {
	ID            uuid.UUID
	OccurredAt    time.Time
	ActorID       *uuid.UUID
	ActorKind     string // "user" | "token" | "anonymous" | "system"
	ActorUsername string
	ActorRole     string
	Action        string // dot-separated verb, e.g. "user.create", "cluster.update"
	ResourceType  string // kind name, e.g. "cluster", "user", "api_token"
	ResourceID    string // stringified id — UUID for most kinds, session public_id, token id, …
	HTTPMethod    string
	HTTPPath      string
	HTTPStatus    int
	// Source identifies which listener served the request:
	//   "api"       — the public listener serving humans, admins, and trusted-zone collectors
	//   "ingest_gw" — the mTLS-only ingest listener fronted by the DMZ gateway (ADR-0016)
	//   "system"    — synthetic events emitted by longue-vue itself, not driven by a request
	// Empty string is treated as "api" for backwards compatibility with rows
	// inserted before ADR-0016 added this column.
	Source    string
	SourceIP  string
	UserAgent string
	Details   map[string]any // JSONB payload, nil-friendly
}

type AuditEventList struct {
	Items      []AuditEvent `json:"items"`
	NextCursor *string      `json:"next_cursor,omitempty"`
}

type AuditEventSource string

type AuditRecorder interface {
	InsertAuditEvent(ctx context.Context, in AuditEventInsert) error
}

type AuditStore interface {
	// InsertAuditEvent appends one row to audit_events. Called from the
	// audit middleware after the wrapped handler has produced a status.
	// Never returns ErrConflict — id collisions are caller bugs.
	InsertAuditEvent(ctx context.Context, in AuditEventInsert) error

	// ListAuditEvents returns audit events paged by opaque cursor. filter
	// fields are AND-combined; nil fields are ignored. page.Sort selects
	// the sort column (default: occurred_at DESC); ErrInvalidSort is
	// returned for unknown keys and ErrInvalidCursor for stale/mismatched
	// cursors.
	ListAuditEvents(ctx context.Context, filter AuditEventFilter, page ListPage) (items []AuditEvent, nextCursor string, err error)
}

type AuthConfig struct {
	Oidc struct {
		Enabled bool `json:"enabled"`

		// Label Button label on the login page, e.g. "Sign in with
		// Okta". Controlled by `LONGUE_VUE_OIDC_LABEL`.
		Label *string `json:"label,omitempty"`
	} `json:"oidc"`
}

type AuthStore interface {
	// CountActiveAdmins returns the number of `admin`-role users without a
	// `disabled_at` timestamp. Used by the first-install bootstrap check.
	CountActiveAdmins(ctx context.Context) (int, error)

	// CountActiveUnlockedAdmins returns the number of admins with
	// disabled_at IS NULL AND locked_at IS NULL.
	CountActiveUnlockedAdmins(ctx context.Context) (int, error)

	// PickRescueTarget returns the most-recently-active admin row.
	// Used by the boot-time rescue when CountActiveUnlockedAdmins == 0.
	// ORDER BY last_login_at DESC NULLS LAST, created_at ASC, LIMIT 1.
	PickRescueTarget(ctx context.Context) (User, error)

	// RescueAdmin atomically resets the rescue target: sets the new
	// password hash, clears locked_at, zeroes failed_login_count, sets
	// disabled_at = NULL, forces must_change_password = true, deletes
	// all of the user's sessions.
	RescueAdmin(ctx context.Context, id uuid.UUID, hash string) error

	// CreateUser inserts a new human user. Returns ErrConflict on
	// case-insensitive username collision.
	CreateUser(ctx context.Context, in UserInsert) (User, error)

	// GetUser fetches by id. ErrNotFound if absent.
	GetUser(ctx context.Context, id uuid.UUID) (User, error)

	// GetUserByUsername looks up by case-insensitive username — the login
	// path. Returns ErrNotFound when no such user exists or the account
	// is disabled, to prevent username enumeration via timing differences
	// (callers always do an argon2 verify regardless).
	GetUserByUsername(ctx context.Context, username string) (UserWithSecret, error)

	// ListUsers returns a page of users (admin view), sorted and filtered per ListPage/UserListFilter.
	ListUsers(ctx context.Context, filter UserListFilter, page ListPage) (items []User, nextCursor string, err error)

	// UpdateUser applies merge-patch on role / disabled / must_change_password.
	// Password changes go through SetUserPassword because they need the
	// hashed form, not plaintext.
	UpdateUser(ctx context.Context, id uuid.UUID, in UserPatch) (User, error)

	// UpdateUserGuarded is the transactional wrapper around UpdateUser
	// that enforces the last-admin invariant atomically. If the patch
	// would demote (role != admin) or disable an active admin and no
	// other active admin exists, it returns ErrLastAdmin without
	// mutating the row. Implementations MUST hold a row-level lock on
	// the candidate-admin set across the count + update so two
	// concurrent demotions cannot both observe `n=2` and commit.
	UpdateUserGuarded(ctx context.Context, id uuid.UUID, in UserPatch) (User, error)

	// SetUserPassword stores a new argon2id hash, toggling the
	// must_change_password flag as specified. On success also deletes every
	// active session for the user so a password change effectively logs
	// out other tabs/devices.
	SetUserPassword(ctx context.Context, id uuid.UUID, hash string, mustChange bool) error

	// TouchUserLogin refreshes last_login_at — called on successful login.
	TouchUserLogin(ctx context.Context, id uuid.UUID, now time.Time) error

	// IncrementFailedLogin bumps users.failed_login_count by one. If the
	// new count is >= threshold and the account was not already locked,
	// sets locked_at = now() in the same statement and returns
	// (locked=true). Idempotent on already-locked accounts: returns
	// (locked=false) and leaves the row untouched.
	//
	// No last-admin guard; the lockout fires uniformly. Recovery is via
	// the boot-time admin-rescue hook (cmd/longue-vue/main.go).
	IncrementFailedLogin(ctx context.Context, id uuid.UUID, threshold int) (locked bool, err error)

	// ResetFailedLogin sets failed_login_count = 0 and locked_at = NULL.
	// Called on a successful password verification. Safe when already
	// at zero (UPDATE is a no-op on the row).
	ResetFailedLogin(ctx context.Context, id uuid.UUID) error

	// DeleteUser removes a user. ON DELETE CASCADE sweeps their sessions
	// and identities; api_tokens they minted are retained (ON DELETE
	// RESTRICT) so CI pipelines don't silently break on admin churn.
	DeleteUser(ctx context.Context, id uuid.UUID) error

	// DeleteUserGuarded is the transactional wrapper around DeleteUser
	// that enforces the last-admin invariant atomically (audit finding
	// H1). Returns ErrLastAdmin when the target is the only currently
	// active admin. Implementations MUST hold a row-level lock on the
	// active-admin set across the count + delete.
	DeleteUserGuarded(ctx context.Context, id uuid.UUID) error

	// CreateSession inserts a new session row.
	CreateSession(ctx context.Context, in SessionInsert) error

	// GetActiveSession, TouchSession — the auth.Store methods, declared
	// here so a single PG implementation satisfies both interfaces.
	GetActiveSession(ctx context.Context, id string) (auth.Session, error)
	TouchSession(ctx context.Context, id string, now time.Time, newExpiry time.Time) error

	// GetUserForAuth — auth.Store lookup: lightweight view the middleware
	// needs after a session resolves.
	GetUserForAuth(ctx context.Context, id uuid.UUID) (auth.User, error)

	// DeleteSession revokes a single session by its cookie-value id.
	// Used by the logout handler which reads the cookie from ctx.
	DeleteSession(ctx context.Context, id string) error

	// DeleteSessionByPublicID revokes by the UUID public handle. Used
	// by the admin revoke endpoint so cookie values never leave the DB.
	DeleteSessionByPublicID(ctx context.Context, publicID uuid.UUID) error

	// DeleteSessionsForUser revokes all active sessions for a user. Called
	// when the user is disabled or changes their password.
	DeleteSessionsForUser(ctx context.Context, userID uuid.UUID) error

	// ListSessions returns a page of active sessions with denormalised
	// username for admin display.
	ListSessions(ctx context.Context, filter SessionListFilter, page ListPage) (items []Session, nextCursor string, err error)

	// CreateAPIToken inserts a new token row. `hash` is argon2id of the
	// full plaintext; `prefix` is the first 8 chars of the plaintext
	// stored in the clear for O(1) lookup.
	CreateAPIToken(ctx context.Context, in APITokenInsert) (ApiToken, error)

	// GetActiveTokenByPrefix, TouchToken — auth.Store lookup path.
	GetActiveTokenByPrefix(ctx context.Context, prefix string) (auth.APIToken, error)
	TouchToken(ctx context.Context, id uuid.UUID, now time.Time) error

	// ListAPITokens (admin view, metadata only — plaintext is never in
	// responses except at creation).
	ListAPITokens(ctx context.Context, filter APITokenListFilter, page ListPage) (items []ApiToken, nextCursor string, err error)

	// RevokeAPIToken sets revoked_at. Idempotent: revoking an
	// already-revoked token returns nil.
	RevokeAPIToken(ctx context.Context, id uuid.UUID, now time.Time) error

	// GetUserByIdentity returns the user linked to (issuer, subject) via
	// the user_identities table, or ErrNotFound when no identity row is
	// present — i.e., the IdP user has never logged in before. Disabled
	// users are treated as NotFound to match local-login semantics.
	GetUserByIdentity(ctx context.Context, issuer, subject string) (User, error)

	// CreateUserWithIdentity inserts a user and its OIDC identity row in
	// one transaction. On username collision the caller is expected to
	// pick a new one and retry.
	CreateUserWithIdentity(ctx context.Context, in UserInsert, ident UserIdentityInsert) (User, error)

	// TouchUserIdentity refreshes last_seen_at on the identity row.
	TouchUserIdentity(ctx context.Context, userID uuid.UUID, issuer, subject string, now time.Time) error

	// CreateOidcAuthState persists the in-flight auth-code state.
	CreateOidcAuthState(ctx context.Context, in OidcAuthStateInsert) error

	// ConsumeOidcAuthState atomically reads and deletes the row keyed on
	// state, returning the code_verifier + nonce. Rejects expired rows
	// with ErrNotFound. One-shot by design.
	ConsumeOidcAuthState(ctx context.Context, state string) (codeVerifier, nonce string, err error)
}

type BadRequest = Problem

type BadRequestApplicationProblemPlusJSONResponse Problem

type CascadeCounts struct {
	Namespaces             int `json:"namespaces"`
	Nodes                  int `json:"nodes"`
	Pods                   int `json:"pods"`
	Workloads              int `json:"workloads"`
	Services               int `json:"services"`
	Ingresses              int `json:"ingresses"`
	PersistentVolumes      int `json:"persistent_volumes"`
	PersistentVolumeClaims int `json:"persistent_volume_claims"`
}

type ChangePassword204Response struct {
}

type ChangePassword400ApplicationProblemPlusJSONResponse struct {
	BadRequestApplicationProblemPlusJSONResponse
}

type ChangePassword401ApplicationProblemPlusJSONResponse struct {
	UnauthorizedApplicationProblemPlusJSONResponse
}

type ChangePassword403ApplicationProblemPlusJSONResponse struct {
	ForbiddenApplicationProblemPlusJSONResponse
}

type ChangePasswordJSONRequestBody = ChangePasswordRequest

type ChangePasswordRequest struct {
	CurrentPassword string `json:"current_password"`

	// NewPassword Minimum 12 characters per NIST 800-63B guidance. No other
	// composition rules — a long passphrase is acceptable and
	// preferred over short complex strings.
	NewPassword string `json:"new_password"`
}

type ChangePasswordRequestObject struct {
	Body *ChangePasswordJSONRequestBody
}

type ChangePasswordResponseObject interface {
	VisitChangePasswordResponse(w http.ResponseWriter) error
}

type CloudAccount struct {
	ID          uuid.UUID         `json:"id"`
	Provider    string            `json:"provider"`
	Name        string            `json:"name"`
	Region      string            `json:"region"`
	Status      string            `json:"status"`
	AccessKey   *string           `json:"access_key,omitempty"`
	LastSeenAt  *time.Time        `json:"last_seen_at,omitempty"`
	LastError   *string           `json:"last_error,omitempty"`
	LastErrorAt *time.Time        `json:"last_error_at,omitempty"`
	Owner       *string           `json:"owner,omitempty"`
	Criticality *string           `json:"criticality,omitempty"`
	Notes       *string           `json:"notes,omitempty"`
	RunbookURL  *string           `json:"runbook_url,omitempty"`
	Annotations map[string]string `json:"annotations,omitempty"`
	CreatedAt   time.Time         `json:"created_at"`
	UpdatedAt   time.Time         `json:"updated_at"`
	DisabledAt  *time.Time        `json:"disabled_at,omitempty"`
}

type CloudAccountListFilter struct {
	Name *string
}

type CloudAccountPatch struct {
	Name        *string
	Region      *string
	Owner       *string
	Criticality *string
	Notes       *string
	RunbookURL  *string
	Annotations *map[string]string
	Status      *string
	LastSeenAt  *time.Time
	LastError   *string
	LastErrorAt *time.Time
}

type CloudAccountStore interface {
	// UpsertCloudAccount idempotently registers a cloud account by
	// (provider, name). New rows are created in status='pending_credentials'.
	UpsertCloudAccount(ctx context.Context, in CloudAccountUpsert) (CloudAccount, error)

	// GetCloudAccount fetches by id. ErrNotFound when absent.
	GetCloudAccount(ctx context.Context, id uuid.UUID) (CloudAccount, error)

	// GetCloudAccountByName fetches by (provider, name). ErrNotFound when absent.
	GetCloudAccountByName(ctx context.Context, provider, name string) (CloudAccount, error)

	// GetCloudAccountByNameAny fetches by name across every provider
	// in a single query. Used by credential-fetch handlers so a
	// caller-by-name lookup doesn't fan out to one SQL round-trip per
	// supported provider. Returns ErrNotFound when no row matches.
	GetCloudAccountByNameAny(ctx context.Context, name string) (CloudAccount, error)

	// ListCloudAccounts returns a cursor-paginated page of cloud accounts,
	// optionally filtered by CloudAccountListFilter.
	ListCloudAccounts(ctx context.Context, filter CloudAccountListFilter, page ListPage) (items []CloudAccount, nextCursor string, err error)

	// UpdateCloudAccount applies merge-patch on curated metadata + name.
	// Status transitions to/from `disabled` and `pending_credentials` are
	// rejected here — see DisableCloudAccount / EnableCloudAccount and
	// SetCloudAccountCredentials. Status field on the patch is allowed
	// only between `active` and `error`.
	UpdateCloudAccount(ctx context.Context, id uuid.UUID, in CloudAccountPatch) (CloudAccount, error)

	// SetCloudAccountCredentials writes AK plaintext + SK ciphertext+nonce+kid
	// and transitions status to `active`. ErrNotFound if the account is missing.
	SetCloudAccountCredentials(ctx context.Context, id uuid.UUID, accessKey string, encSK secrets.Ciphertext) (CloudAccount, error)

	// GetCloudAccountCredentials returns AK + SK ciphertext for callers
	// (the handler decrypts). Returns ErrNotFound when status =
	// `pending_credentials` or the row is absent. Returns ErrConflict
	// when status = `disabled` (caller maps to 403).
	GetCloudAccountCredentials(ctx context.Context, id uuid.UUID) (accessKey string, encSK secrets.Ciphertext, err error)

	// UpdateCloudAccountStatus is the collector heartbeat path. Only
	// allows transitions between `active` and `error`; rejects to/from
	// `disabled` or `pending_credentials`.
	UpdateCloudAccountStatus(ctx context.Context, id uuid.UUID, status string, lastSeenAt *time.Time, lastError *string) error

	// DisableCloudAccount sets disabled_at and status='disabled'.
	DisableCloudAccount(ctx context.Context, id uuid.UUID) error

	// EnableCloudAccount clears disabled_at and resets status (active if
	// credentials are present, otherwise pending_credentials).
	EnableCloudAccount(ctx context.Context, id uuid.UUID) error

	// DeleteCloudAccount removes a cloud account (cascades to VMs and tokens).
	DeleteCloudAccount(ctx context.Context, id uuid.UUID) error

	// CountCloudAccountsWithSecrets is used at startup to decide whether
	// missing master-key configuration is fatal (see ADR-0015 §4).
	CountCloudAccountsWithSecrets(ctx context.Context) (int, error)
}

type CloudAccountUpsert struct {
	Provider string
	Name     string
	Region   string
}

type Cluster struct {
	// Annotations Free-form k/v for metadata not worth its own column. Values
	// are strings. Collector writes never touch this field.
	Annotations *map[string]string `json:"annotations,omitempty"`

	// ApiEndpoint Kubernetes API server URL (informational).
	ApiEndpoint *string    `json:"api_endpoint,omitempty"`
	CreatedAt   *time.Time `json:"created_at,omitempty"`

	// Criticality Free-form tier label. Common values: `critical`, `high`,
	// `medium`, `low`. Not enum-enforced so operators can slot in
	// their own taxonomy (P0/P1/…).
	Criticality *string `json:"criticality,omitempty"`

	// DisplayName Human-friendly label, free-form.
	DisplayName *string `json:"display_name,omitempty"`

	// Environment Free-form environment tag (e.g., dev, staging, prod).
	Environment *string             `json:"environment,omitempty"`
	Id          *openapi_types.UUID `json:"id,omitempty"`

	// KubernetesVersion Cluster API server version reported by Kubernetes (e.g. "1.29.5").
	KubernetesVersion *string `json:"kubernetes_version,omitempty"`

	// Labels Arbitrary user-supplied string key/value labels.
	Labels *map[string]string `json:"labels,omitempty"`

	// LastSeenAt Collector heartbeat: refreshed on every successful collector
	// tick for this cluster (in-process pull, or push mode via
	// POST /v1/clusters through the ingest gateway). Also set on
	// creation.
	LastSeenAt *time.Time `json:"last_seen_at,omitempty"`

	// Layer Always `infrastructure_logical` for Cluster. Set by the server.
	Layer *Layer `json:"layer,omitempty"`
	Name  string `json:"name"`

	// Notes Long-form prose. Any markdown is rendered client-side.
	Notes *string `json:"notes,omitempty"`

	// Owner Free-form handle for the team / on-call that owns this
	// cluster. Surfaced on the detail page so incident responders
	// know who to wake up.
	Owner *string `json:"owner,omitempty"`

	// Provider Underlying Kubernetes distribution or hosting provider.
	// Open-ended; common values: gke, eks, aks, openshift, rke, kubeadm, onprem, other.
	Provider *string `json:"provider,omitempty"`
	Region   *string `json:"region,omitempty"`

	// RunbookUrl Link to the owning team's runbook for this cluster.
	RunbookUrl *string `json:"runbook_url,omitempty"`

	// Stale Derived at read time: true when `last_seen_at` is older
	// than the `cluster_stale_after_days` admin setting. Always
	// false when the feature is disabled (threshold 0). Set by
	// the server; never persisted.
	Stale     *bool      `json:"stale,omitempty"`
	UpdatedAt *time.Time `json:"updated_at,omitempty"`
}

type ClusterCreate struct {
	// Annotations Free-form k/v for metadata not worth its own column. Values
	// are strings. Collector writes never touch this field.
	Annotations *map[string]string `json:"annotations,omitempty"`

	// ApiEndpoint Kubernetes API server URL (informational).
	ApiEndpoint *string `json:"api_endpoint,omitempty"`

	// Criticality Free-form tier label. Common values: `critical`, `high`,
	// `medium`, `low`. Not enum-enforced so operators can slot in
	// their own taxonomy (P0/P1/…).
	Criticality *string `json:"criticality,omitempty"`

	// DisplayName Human-friendly label, free-form.
	DisplayName *string `json:"display_name,omitempty"`

	// Environment Free-form environment tag (e.g., dev, staging, prod).
	Environment *string `json:"environment,omitempty"`

	// KubernetesVersion Cluster API server version reported by Kubernetes (e.g. "1.29.5").
	KubernetesVersion *string `json:"kubernetes_version,omitempty"`

	// Labels Arbitrary user-supplied string key/value labels.
	Labels *map[string]string `json:"labels,omitempty"`

	// Name Stable slug-like identifier, unique across the CMDB.
	// Immutable after creation.
	Name string `json:"name"`

	// Notes Long-form prose. Any markdown is rendered client-side.
	Notes *string `json:"notes,omitempty"`

	// Owner Free-form handle for the team / on-call that owns this
	// cluster. Surfaced on the detail page so incident responders
	// know who to wake up.
	Owner *string `json:"owner,omitempty"`

	// Provider Underlying Kubernetes distribution or hosting provider.
	// Open-ended; common values: gke, eks, aks, openshift, rke, kubeadm, onprem, other.
	Provider *string `json:"provider,omitempty"`
	Region   *string `json:"region,omitempty"`

	// RunbookUrl Link to the owning team's runbook for this cluster.
	RunbookUrl *string `json:"runbook_url,omitempty"`
}

type ClusterId = openapi_types.UUID

type ClusterList struct {
	Items []Cluster `json:"items"`

	// NextCursor Opaque cursor to pass as `?cursor=` to fetch the next page.
	// Absent or null when no more pages remain.
	NextCursor *string `json:"next_cursor,omitempty"`
}

type ClusterListFilter struct {
	Name              *string
	IncludeTerminated bool
	// Stale filters on the derived staleness state: true keeps only
	// clusters whose last_seen_at is strictly older than StaleCutoff,
	// false keeps only fresh ones. StaleCutoff must be set whenever
	// Stale is non-nil; handlers compute it from the
	// cluster_stale_after_days setting and leave Stale nil when the
	// feature is disabled.
	Stale       *bool
	StaleCutoff time.Time
}

type ClusterMutable struct {
	// Annotations Free-form k/v for metadata not worth its own column. Values
	// are strings. Collector writes never touch this field.
	Annotations *map[string]string `json:"annotations,omitempty"`

	// ApiEndpoint Kubernetes API server URL (informational).
	ApiEndpoint *string `json:"api_endpoint,omitempty"`

	// Criticality Free-form tier label. Common values: `critical`, `high`,
	// `medium`, `low`. Not enum-enforced so operators can slot in
	// their own taxonomy (P0/P1/…).
	Criticality *string `json:"criticality,omitempty"`

	// DisplayName Human-friendly label, free-form.
	DisplayName *string `json:"display_name,omitempty"`

	// Environment Free-form environment tag (e.g., dev, staging, prod).
	Environment *string `json:"environment,omitempty"`

	// KubernetesVersion Cluster API server version reported by Kubernetes (e.g. "1.29.5").
	KubernetesVersion *string `json:"kubernetes_version,omitempty"`

	// Labels Arbitrary user-supplied string key/value labels.
	Labels *map[string]string `json:"labels,omitempty"`

	// Notes Long-form prose. Any markdown is rendered client-side.
	Notes *string `json:"notes,omitempty"`

	// Owner Free-form handle for the team / on-call that owns this
	// cluster. Surfaced on the detail page so incident responders
	// know who to wake up.
	Owner *string `json:"owner,omitempty"`

	// Provider Underlying Kubernetes distribution or hosting provider.
	// Open-ended; common values: gke, eks, aks, openshift, rke, kubeadm, onprem, other.
	Provider *string `json:"provider,omitempty"`
	Region   *string `json:"region,omitempty"`

	// RunbookUrl Link to the owning team's runbook for this cluster.
	RunbookUrl *string `json:"runbook_url,omitempty"`
}