api

type AuditLogPageReader interface {
	ListAuditLogsAfter(ctx context.Context, tenant, dagID string, after domain.PageCursor, limit int) ([]domain.AuditLogEntry, int, error)
}

type AuditLogReader interface {
	ListAuditLogs(ctx context.Context, tenant, dagID string, limit, offset int) ([]domain.AuditLogEntry, int, error)
}

type AuditWriter interface {
	RecordTaskActionAudit(ctx context.Context, tenant, userID, action, dagID, runID, taskID string, tryNumber int) error
	// RecordRunActionAudit logs a run-level action with extra metadata
	// fields, such as the state a PATCH asked for when it stored another.
	RecordRunActionAudit(ctx context.Context, tenant, userID, action, dagID, runID string, metadata map[string]string) error
}

type AuthAuditWriter interface {
	RecordAuthEvent(ctx context.Context, tenant, actorUserID, action, email, outcome string, extra map[string]string) error
}

type AuthDeps struct {
	// Authenticator verifies every request's session and issues the token of
	// POST /auth/token. Required, also under DevNoAuth, which still serves
	// that route.
	Authenticator auth.Authenticator
	// RateLimiter caps the failed logins of POST /auth/token per client.
	// Required.
	RateLimiter  *auth.RateLimiter
	TokenTTLSecs int
	// TokenRenewer re-mints a still-valid user bearer with a fresh short TTL so a
	// long CLI/dev session need not re-login every TokenTTLSecs (aresta #5). Nil
	// leaves the renew route unregistered (renewal simply unavailable). In practice
	// it is the same *auth.JWTAuthenticator as Authenticator.
	TokenRenewer TokenRenewer
	// TokenMaxLifetimeSecs is the hard ceiling on a renewed session's total age
	// since first login; past it, renewal is refused and the user must
	// re-authenticate. Non-positive disables the ceiling.
	TokenMaxLifetimeSecs int
	// DevNoAuth replaces JWT auth with a dev-only bypass that authenticates every
	// request as an admin (no login). It is for `dexaflow lite` only and must never
	// be set in production. See DevBypassAuth.
	DevNoAuth bool
	// JWTSecret is the HS256 secret the OIDC callback mints the app's _token with.
	JWTSecret string
	// SessionCookieInsecure drops the Secure attribute from the session and OIDC
	// state cookies (auth.session_cookie_insecure). It is stated negatively so the
	// zero value is the hardened one: a caller that forgets the field gets Secure.
	// See cookieSecure for why this is a setting and not derived from the request.
	SessionCookieInsecure bool
	// SessionCookieName is the session cookie's name (auth.session_cookie_name,
	// #1405). Empty is _token, the name every earlier release used.
	SessionCookieName string

	// OIDC wiring (registered only when OIDCFlow is non-nil, provider: oidc).
	// The JWT authenticator above stays the request-path verifier in both modes.
	//
	// OIDCFlow is the discovered Authorization Code + PKCE flow; nil in JWT mode,
	// in which case the /api/v2/auth/oidc/* routes are not registered.
	OIDCFlow *oidc.Flow
	// OIDCEnabled is true when auth.provider is "oidc". It makes the credential
	// path break-glass-only: with OIDC on, an empty break-glass allowlist means
	// SSO-only (every password login rejected), NOT ungated: the secure default.
	OIDCEnabled bool
	// OIDCSettings carries the role mappings, JIT policy, default_role, and
	// break-glass allowlist the login flow and the credential gate read.
	OIDCSettings OIDCSettings
	// ExternalSignInURL and ExternalSignOutURL are auth.external_signin_url and
	// auth.external_signout_url (#1288): the operator's own sign-in and
	// sign-out, used in place of Dexaflow's pages. Empty keeps Dexaflow's.
	ExternalSignInURL  string
	ExternalSignOutURL string
	// OIDCUsers resolves and JIT-provisions OIDC identities (the storage repo).
	OIDCUsers OIDCUserStore
	// CLIDevices keeps the device sign-ins of the CLI (ADR 0081, the storage
	// repo). With single sign-on configured it serves `dexaflow auth login
	// --device`; nil leaves the device sign-in unserved.
	CLIDevices CLIDeviceStore
	// AuthAudit records authentication events (login, tenant-pin rejection, JIT,
	// break-glass, logout) to the audit sink.
	AuthAudit AuthAuditWriter
}

type CIOIDCExchangeRecorder interface {
	RecordCIOIDCExchange(issuer, outcome string)
}

type CIOIDCVerifier interface {
	// Verify returns what the token may act as, or a *cioidc.Error.
	Verify(ctx context.Context, raw string) (*cioidc.Identity, error)
	// Advertised returns the entries of tenant for GET /api/v2/deployDefaults.
	Advertised(tenant string) []domain.CIOIDCIssuer
}

type CLIDeviceStore interface {
	// CreateCLIDeviceAuthorization starts a sign-in as req describes. It is
	// auth.ErrDeviceSignInsFull or auth.ErrDeviceSignInsFromRequester over a
	// cap, and domain.ErrConflict when the user code is taken.
	CreateCLIDeviceAuthorization(ctx context.Context, req auth.DeviceAuthorizationRequest) (auth.DeviceAuthorization, error)
	// FindCLIDeviceByUserCode returns the pending, unexpired sign-in of a
	// user code, or domain.ErrNotFound.
	FindCLIDeviceByUserCode(ctx context.Context, userCodeHash string) (auth.DeviceAuthorization, error)
	// DecideCLIDeviceAuthorization approves a pending sign-in as user, or
	// cancels it. It is domain.ErrNotFound when the sign-in is not pending,
	// expired, or the user is not in user.TenantID.
	DecideCLIDeviceAuthorization(ctx context.Context, id string, approve bool, user auth.User) error
	// PollCLIDeviceAuthorization answers one poll; an approved sign-in is
	// redeemed by exactly one.
	PollCLIDeviceAuthorization(ctx context.Context, deviceCodeHash string) (auth.DevicePoll, error)
}

type ConnectionStore interface {
	ListConnections(ctx context.Context, tenant string, limit, offset int) ([]domain.Connection, int, error)
	ListConnectionsFiltered(ctx context.Context, tenant, pattern, prefixPattern string, limit, offset int) ([]domain.Connection, int, error)
	GetConnection(ctx context.Context, tenant, connID string) (domain.Connection, error)
	SetConnectionPatch(ctx context.Context, tenant string, p domain.ConnectionPatch) error
	DeleteConnection(ctx context.Context, tenant, connID string) error
}

type ConnectionTester interface {
	Test(ctx context.Context, c domain.Connection) (ok bool, message string)
}

type DagLatestRunsReader interface {
	LatestRunsForDags(ctx context.Context, tenant string, dagIDs []string, perDag int) (map[string][]domain.DagRun, error)
}

type DagRepository interface {
	ListDags(ctx context.Context, tenant string, limit, offset int) ([]domain.DAG, int, error)
	GetDag(ctx context.Context, tenant, dagID string) (domain.DAG, error)
	// SetPausedBy sets is_paused on behalf of the user actorUserID, who a
	// change is audited for.
	SetPausedBy(ctx context.Context, tenant, actorUserID, dagID string, paused bool) (domain.DAG, error)
	DeleteDag(ctx context.Context, tenant, dagID string) error
	ClearDagHistory(ctx context.Context, tenant, dagID string) error
	ListDagsFiltered(ctx context.Context, tenant, runState string, paused *bool, limit, offset int) ([]domain.DAG, int, error)
	ListDagsWithFilter(ctx context.Context, tenant string, filter domain.DagFilter) ([]domain.DAG, int, error)
	ListDagTags(ctx context.Context, tenant, pattern, prefixPattern string, limit, offset int) (tags []string, total int, err error)
}

type DagRunPageReader interface {
	ListDagRunsAfter(ctx context.Context, tenant, dagID string, states []string, after domain.PageCursor, limit int) ([]domain.DagRun, int, error)
}

type DagRunRepository interface {
	ListDagRuns(ctx context.Context, tenant, dagID string, limit, offset int) ([]domain.DagRun, int, error)
	ListDagRunsWithFilter(ctx context.Context, tenant, dagID string, filter domain.DagRunFilter) ([]domain.DagRun, int, error)
	GetDagRun(ctx context.Context, tenant, dagID, runID string) (domain.DagRun, error)
	CreateDagRun(ctx context.Context, tenant, dagID string, run domain.DagRun) (domain.DagRun, error)
	SetDagRunState(ctx context.Context, tenant, dagID, runID, state string) error
	DeleteDagRun(ctx context.Context, tenant, dagID, runID string) error
}

type DagSourceReader interface {
	GetDagVersionSpec(ctx context.Context, tenant, dagID string, versionNumber int) (domain.DagVersion, domain.DAGSpec, error)
}

type DagSpecReader interface {
	GetCurrentSpec(ctx context.Context, tenant, dagID string) (domain.DAGSpec, error)
}

type DagVersionLister interface {
	ListDagVersions(ctx context.Context, tenant, dagID string) ([]domain.DagVersion, error)
}

type DagVersionRepository interface {
	// RegisterDagVersionAs upserts the DAG and inserts a version keyed by
	// reg.SpecHash on behalf of reg.ActorUserID, reporting whether a new
	// version was created (false if the hash already existed: the push is
	// idempotent) and the DAG's is_paused afterwards. reg.IsPaused, when set,
	// is the DAG's state after the register.
	RegisterDagVersionAs(ctx context.Context, tenant string, reg domain.DagRegistration) (domain.DagRegistered, error)
	// SetCurrentDagVersionAs makes the version req.Selector names current,
	// after req.Admit accepts its spec, on behalf of req.ActorUserID. Runs
	// that already exist keep their version; is_paused is never changed.
	SetCurrentDagVersionAs(ctx context.Context, tenant string, req domain.DagSetCurrent) (domain.CurrentVersionChange, error)
}

type DashboardStatsReader interface {
	DagStats(ctx context.Context, tenant string) (domain.DagStats, error)
	HistoricalMetrics(ctx context.Context, tenant string, since, until time.Time) (domain.HistoricalMetrics, error)
}

type Dependencies struct {
	Observability ObservabilityDeps
	Server        ServerDeps
	Auth          AuthDeps
	Issuers       IssuerDeps
	UI            UIDeps
	Execution     ExecutionDeps
	Stores        StoreDeps
}

type ExecutionDeps struct {
	// ResourceUnit is executor.unit (ADR 0066 §3). When set, registering a DAG
	// whose task declares more than pool_slots x unit answers 400 naming the
	// size it needs (under enforce: warn it is accepted, logged and counted).
	// Nil: no unit, no check.
	ResourceUnit *domain.ResourceUnit
	// UnitMisfits counts a task registered under executor.unit.enforce=warn
	// although it does not fit its size. Nil: not counted.
	UnitMisfits UnitMisfitRecorder
	// SourceModeImage is the runtime image when execution.source_mode is on
	// (ADR 0067 §3), "" when it is off. Registering a version on that image
	// answers 400 when its source is empty or over domain.MaxSourceModeBytes.
	SourceModeImage string
	// RequireDigest is deploy.require_digest (#1703): what registering a
	// version, or making one current again, does with an image not pinned by
	// a full sha256 digest. Off (and the zero value) accepts it; warn accepts
	// it with a warning in the answer, a log line and a count; enforce
	// answers 400.
	RequireDigest domain.DigestRequirement
	// UnpinnedImages counts the unpinned images deploy.require_digest warned
	// about or refused. Nil: not counted.
	UnpinnedImages UnpinnedImageRecorder
	// DeployDefaults are what the server advertises from deploy.defaults
	// (config.ServerConfig.AdvertisedDeployDefaults), served on
	// GET /api/v2/deployDefaults (#1704, #1890). The zero value serves empty
	// fields.
	DeployDefaults domain.DeployDefaults
	// ExecutionPolicy is executor.defaults.execution_allowlist (issue #629).
	// When set, registering a DAG whose task sets an execution field (or
	// priority class) outside it answers 400 naming the task and the field.
	// Nil: everything allowed.
	ExecutionPolicy *domain.ExecutionPolicy
	// WarmPolicy is the warm placement decision the dispatcher applies
	// (dispatch.Dispatcher.WarmPolicy, built from the same configuration). The
	// register response reports each task's execution mode with it (#1707).
	// The zero value reports warm pools off.
	WarmPolicy domain.WarmPolicy
	// WarmPools are the operator's warm pool settings (execution.*), read
	// for the pool state of the register response.
	WarmPools domain.WarmPoolDefaults
	// WarmWorkersAbsent says why no warm worker runs although warm pools are
	// on (the subprocess executor starts no warm pool reconciler; neither does
	// a server whose pod dispatch is disabled), "" when they run. The register
	// response then reports every task on a dedicated pod, with this reason.
	WarmWorkersAbsent string
	// TaskPods is how this server starts task pods, which the register dry
	// run reports (#1889): whether they refuse an image that runs as root,
	// and the ServiceAccount each task would run as, looked up. The zero
	// value reports a server that starts no task pods.
	TaskPods TaskPodSettings
}

type ExecutorInfo struct {
	PodDispatchEnabled    bool
	TaskNamespace         string
	AgentControlPlaneAddr string
}

type FavoriteStore interface {
	AddFavorite(ctx context.Context, tenant, userID, dagID string) error
	RemoveFavorite(ctx context.Context, tenant, userID, dagID string) error
	FavoriteDagIDs(ctx context.Context, tenant, userID string) (map[string]bool, error)
}

type HealthChecker interface {
	Ping(ctx context.Context) error
}

type Heartbeater interface {
	Heartbeat() (healthy bool, last time.Time)
}

type ImportErrorStore interface {
	ListImportErrors(ctx context.Context, tenant string) ([]domain.ImportError, error)
	ListImportErrorsFiltered(ctx context.Context, tenant, filename, bundleName string, limit, offset int) ([]domain.ImportError, int, error)
	SetImportError(ctx context.Context, tenant string, e domain.ImportError) error
	ClearImportError(ctx context.Context, tenant, filename string) error
}

type IssuerDeps struct {
	// TrustedIssuer, when set, enables POST /api/v2/auth/session: a token from
	// the operator's trusted issuer opens a UI session for a linked user
	// (#1284). TrustedIssuerUsers resolves those users (the storage repo).
	TrustedIssuer      TrustedIssuer
	TrustedIssuerUsers TrustedIssuerUserStore
	// TrustedIssuerBearer, when set, also accepts the trusted issuer's tokens
	// for a bearer audience as the Authorization bearer of any protected
	// request (#1468). It resolves users through TrustedIssuerUsers.
	TrustedIssuerBearer TrustedIssuerBearer
	// DeployViaIssuer is set when auth.trusted_issuer.deploy_audience is
	// (#1773): the deploy routes and deleting a DAG then take only a
	// TrustedIssuerBearer token of that audience. With no TrustedIssuerBearer every deploy is refused,
	// so a wiring mistake fails closed.
	DeployViaIssuer bool
	// TrustedIssuerOrigins are the only Origins a handoff may be posted from
	// (scheme://host[:port]), so another site cannot sign a browser in.
	TrustedIssuerOrigins []string
	// TrustedIssuerHostPattern is auth.trusted_issuer.host_pattern (#1463),
	// such as "{tenant}.example.com": when set, a handoff and a session cookie
	// are accepted only on the host of their tenant. Empty binds nothing.
	TrustedIssuerHostPattern string
	// CIOIDC, when set, verifies the OIDC tokens of the configured CI
	// issuers (ADR 0092, auth.ci_oidc): POST /api/v2/auth/ciToken exchanges
	// one for a session, and GET /api/v2/deployDefaults lists the caller's
	// tenant's issuers. Nil leaves both off. CIOIDCRoles reads the role a
	// rule names (the storage repo), CIOIDCSessionTTL is the session's
	// lifetime (an hour when zero), and CIOIDCExchanges counts the
	// exchanges (nil: not counted).
	CIOIDC           CIOIDCVerifier
	CIOIDCRoles      auth.RolePermissionStore
	CIOIDCSessionTTL time.Duration
	CIOIDCExchanges  CIOIDCExchangeRecorder
	// ServiceToken, when set, enables the operator service API under
	// /api/v2/service/ (#1283), authenticated by this bearer token instead of a
	// user session. ServiceTenants is its storage (the repo).
	ServiceToken   string
	ServiceTenants ServiceTenantStore
	// ServiceAllowedTenants are the tenants the service API may link issuer
	// users in: auth.trusted_issuer.allowed_tenants, where "*" allows all.
	ServiceAllowedTenants []string
	// ServiceUsage serves GET /api/v2/service/usage (ADR 0096); nil leaves
	// the route absent.
	ServiceUsage UsageEventReader
}

type LivenessCheck func() error

type LogReader interface {
	ReadLogs(ctx context.Context, tenant, dagID, runID, taskID string, tryNumber int) (io.ReadCloser, error)
	Tail(ctx context.Context, tenant, dagID, runID, taskID string, tryNumber int) (<-chan string, func(), error)
}

type Metrics interface {
	RecordHTTPRequest(method, path string, status int, dur time.Duration)
}

type OIDCSettings struct {
	// Issuer is auth.oidc.issuer, the pinned issuer of every ID token.
	Issuer string
	// RedirectURL is auth.oidc.redirect_url, this server's callback URL.
	RedirectURL string
	// RoleMappings is auth.oidc.role_mappings: an IdP group to a role name.
	RoleMappings map[string]string
	// DefaultRole is auth.oidc.default_role, granted to a user no mapping
	// gives a role; empty grants none.
	DefaultRole string
	// BreakGlassEmails is auth.oidc.break_glass_emails, the local password
	// logins permitted while provider is "oidc".
	BreakGlassEmails []string
	// JITProvisioning is auth.oidc.jit_provisioning: create a user on first
	// OIDC login.
	JITProvisioning bool
	// AutoRedirect is auth.oidc.auto_redirect: start the login flow on the
	// sign-in page instead of rendering it.
	AutoRedirect bool
}

type OIDCUserStore interface {
	// FindUserByOIDCSubject resolves a returning identity by its (provider,
	// subject) pair, returning the user, whether it is active, and
	// auth.ErrUserNotFound when no row matches.
	FindUserByOIDCSubject(ctx context.Context, provider, subject string) (*auth.User, bool, error)
	// CreateOIDCUser JIT-provisions an OIDC-only user with the given roles.
	CreateOIDCUser(ctx context.Context, tenant, email, provider, subject string, roles []string) (*auth.User, error)
	// RoleExists reports whether a role name exists for the tenant, used to fail
	// closed on a misconfigured default_role or role mapping.
	RoleExists(ctx context.Context, tenant, role string) (bool, error)
	// ReconcileUserRoles sets the user's DB roles to EXACTLY roleNames (the IdP is
	// authoritative). It fails closed on a name that is not a role in the tenant,
	// leaving the prior grants intact.
	ReconcileUserRoles(ctx context.Context, userID string, roleNames []string) error
}

type ObservabilityDeps struct {
	// Logger receives one line per request and the server's own warnings.
	// Required.
	Logger   *slog.Logger
	Registry *prometheus.Registry
	Metrics  Metrics
	Tracer   trace.Tracer
	// HealthChecks back /readyz and /api/v2/monitor/health.
	HealthChecks map[string]HealthChecker
	// SchedulerHealth reports the scheduler's heartbeat for /monitor/health.
	// When nil the component reports healthy (single-process role assumption).
	SchedulerHealth Heartbeater
	// Liveness, when set, can fail /healthz (server.liveness_scheduler_stall).
	// Nil keeps /healthz unconditional.
	Liveness LivenessCheck
	// ProbeBudget (server.probe_budget) bounds /readyz and the dependency
	// checks of /api/v2/monitor/health. Non-positive means 2s.
	ProbeBudget time.Duration
	// ExecutorInfo is served on /api/v2/monitor/executor.
	ExecutorInfo ExecutorInfo
}

type ObservabilityOption func(*observabilityOptions)

type PoolStore interface {
	ListPools(ctx context.Context, tenant string, limit, offset int) ([]domain.Pool, int, error)
	GetPool(ctx context.Context, tenant, name string) (domain.Pool, error)
	SetPool(ctx context.Context, tenant string, p domain.Pool) error
	DeletePool(ctx context.Context, tenant, name string) error
	PoolSlotUsage(ctx context.Context, tenant string) (map[string]domain.PoolUsage, error)
}

type Problem struct {
	Type     string `json:"type"`
	Title    string `json:"title"`
	Status   int    `json:"status"`
	Detail   string `json:"detail,omitempty"`
	Instance string `json:"instance,omitempty"`
}

type SchemaChecker interface {
	SchemaReady(ctx context.Context) error
}

type ServerDeps struct {
	CORSOrigins []string
	// TrustedProxies is the set of proxy IPs/CIDRs whose X-Forwarded-For header
	// gin will honor when resolving c.ClientIP(). Empty/nil trusts NO proxy, so
	// ClientIP is the direct peer and a spoofed XFF cannot forge the client IP
	// (audit H1). A Pro deployment behind an ingress sets this to the ingress
	// CIDR so per-client rate-limiting and audit see the real client.
	TrustedProxies []string
	// GzipResponses (server.gzip_responses) gzips JSON and NDJSON responses of
	// 1 KB or more for clients that accept it; streams are never compressed.
	// False (the default) sends every body as identity.
	GzipResponses bool
	// MaxPageLimit (server.max_page_limit) caps the limit of every list
	// endpoint and the dag_runs_limit of /ui/dags. Non-positive (the default)
	// leaves them uncapped.
	MaxPageLimit int
	// MaxRequestBodyBytes (server.max_request_body_bytes) and
	// MaxUploadBodyBytes (server.max_upload_body_bytes) cap request bodies,
	// the second on the routes that take a DAG's code or spec (BodyLimit).
	// Non-positive (the default) leaves those routes unlimited.
	MaxRequestBodyBytes int64
	MaxUploadBodyBytes  int64
	// Pools registers the named-pool CRUD as real endpoints (ADR 0053). The
	// server sets it from scheduler.pools.enabled, the same condition as the
	// scheduler's pool gate; otherwise the Pools screen gets the graceful
	// empty-collection stub.
	Pools bool
	// PoolsReadOnly is server.pools_read_only: the pool API serves reads only and
	// every create, resize and delete answers 403 with PoolsReadOnlyDetail, for
	// every role including tenant admin. False keeps the write:pool-gated CRUD.
	PoolsReadOnly bool
}

type ServiceAccountReader interface {
	// ImagePullSecrets returns how many imagePullSecrets the ServiceAccount
	// name carries, and found false when it does not exist. An error means
	// the lookup could not tell.
	ImagePullSecrets(ctx context.Context, name string) (count int, found bool, err error)
}

type ServiceTenantStore interface {
	// EnsureTenant creates a tenant with the built-in roles and default pool,
	// or fills in what is missing; created reports whether it was new.
	// limits sets the tenant limits it carries and leaves the others.
	EnsureTenant(ctx context.Context, name, displayName string, defaultPoolSlots int, limits domain.TenantLimitsUpdate) (created bool, err error)
	// EnsureIssuerUser makes sure a passwordless user linked to (provider,
	// subject) exists in tenant with exactly roles.
	EnsureIssuerUser(ctx context.Context, tenant, email, provider, subject string, roles []string) (*auth.User, bool, error)
	// SuspendTenant suspends tenant or changes its suspension (#2181);
	// ResumeTenant lifts it, and TenantSuspension reads it (the zero value is
	// a tenant that is not suspended). An unknown tenant is ErrNotFound.
	SuspendTenant(ctx context.Context, tenant string, s domain.TenantSuspension) error
	ResumeTenant(ctx context.Context, tenant string) error
	TenantSuspension(ctx context.Context, tenant string) (domain.TenantSuspension, error)
}

type StoreDeps struct {
	Dags     DagRepository
	DagRuns  DagRunRepository
	Tasks    TaskInstanceRepository
	Versions DagVersionRepository
	Xcoms    XComReader
	Logs     LogReader
	// EphemeralLogs indicates that task logs reside on an ephemeral storage volume
	// (such as an emptyDir PVC fallback) that is lost on pod restart. When true,
	// missing logs for terminal task instances explain that logs did not survive
	// a control plane restart.
	EphemeralLogs bool
	Specs         DagSpecReader
	// DagSources reads one version of a DAG with its spec, for the Code view
	// (GET /api/v2/dagSources/{dag_id}). Nil leaves that route unregistered.
	DagSources     DagSourceReader
	LatestRuns     DagLatestRunsReader
	TaskSummary    TaskSummaryReader
	DagVersions    DagVersionLister
	DashboardStats DashboardStatsReader
	AuditLog       AuditLogReader
	Variables      VariableStore
	Users          UserStore
	UserAudit      UserAuditWriter
	// APITokens keeps the long-lived API tokens (ADR 0074). Nil leaves the
	// /api/v2/apiTokens routes unregistered.
	APITokens      TokenStore
	Connections    ConnectionStore
	ConnectionTest ConnectionTester
	Pools          PoolStore
	Favorites      FavoriteStore
	ImportErrors   ImportErrorStore
	Audit          AuditWriter
}

type TaskInstanceRepository interface {
	ListTaskInstances(ctx context.Context, tenant, dagID, runID string, limit, offset int) ([]domain.TaskInstance, int, error)
	ListTaskInstancesWithFilter(ctx context.Context, tenant, dagID, runID string, filter domain.TaskInstanceFilter) ([]domain.TaskInstance, int, error)
	// ListTaskInstanceAttempts returns every attempt for (run, task), oldest
	// first — the current row UNIONed with the archived history. The UI's
	// /tries endpoint needs all attempts to render its navigable tabs.
	ListTaskInstanceAttempts(ctx context.Context, tenant, dagID, runID, taskID string) ([]domain.TaskInstance, error)
	ClearTaskInstances(ctx context.Context, tenant, dagID, runID string, taskIDs []string, onlyFailed bool, opts domain.ClearOptions) (int, error)
	// RunsKeepingVersion lists, without writing, the runs among runIDs that a
	// clear with opts asks to move to the DAG's current version and that keep
	// their own, with the reason (ADR 0086); domain.ErrNotFound for a run the
	// tenant does not have.
	RunsKeepingVersion(ctx context.Context, tenant, dagID string, runIDs []string, opts domain.ClearOptions) ([]domain.ClearVersionKept, error)
	SetTaskInstanceState(ctx context.Context, tenant, dagID, runID, taskID, state string) error
}

type TaskPodSettings struct {
	// Enabled is true when this server dispatches tasks to pods.
	Enabled bool
	// RunAsNonRoot is executor.run_tasks_as_non_root: task pods refuse an
	// image that runs as root, or as a user that is not a number.
	RunAsNonRoot bool
	// DefaultServiceAccount is executor.task_service_account, the account
	// of a task that names none; "" runs it as the namespace's default.
	DefaultServiceAccount string
	// ServiceAccounts reads the task ServiceAccounts; nil reports each one
	// unchecked, with Unread as the reason.
	ServiceAccounts ServiceAccountReader
	// Unread says why ServiceAccounts is nil.
	Unread string
}

type TaskSummaryReader interface {
	TaskInstancesForRuns(ctx context.Context, tenant, dagID string, runIDs []string) ([]domain.TaskInstance, error)
}

type TokenRenewer interface {
	RenewUserToken(ctx context.Context, token string, ttl, maxLifetime time.Duration) (renewed string, ok bool, err error)
}

type TokenStore interface {
	CreateAPIToken(ctx context.Context, tenant, userID, name, hash string, scopes []string, expiresAt time.Time) (auth.APIToken, error)
	ListAPITokens(ctx context.Context, tenant, ownerID string, limit, offset int) ([]auth.APIToken, int, error)
	RevokeAPIToken(ctx context.Context, tenant, id, ownerID string) (auth.APIToken, error)
}

type TrustedIssuer interface {
	// Provider is the key the issuer's users are linked under.
	Provider() string
	// Verify checks a token and returns the identity it carries.
	Verify(ctx context.Context, raw string) (*issuer.Identity, error)
}

type TrustedIssuerBearer interface {
	// Provider is the key the issuer's users are linked under.
	Provider() string
	// VerifyBearer checks a token sent as a request bearer and returns the
	// identity it carries.
	VerifyBearer(ctx context.Context, raw string) (*issuer.Identity, error)
}

type TrustedIssuerUserStore interface {
	FindUserByOIDCSubject(ctx context.Context, provider, subject string) (*auth.User, bool, error)
}

type UIDeps struct {
	// InstanceName is shown in the UI navbar (Airflow's instance_name). Empty
	// falls back to "Dexaflow"; `dexaflow lite` sets it to mark the DEV environment.
	InstanceName string
	// AutoRefreshIntervalSeconds controls the SPA's polling cadence for DAG /
	// DagRun / task-instance state refresh (Airflow's auto_refresh_interval).
	// Non-positive (the zero default) falls back to DefaultUIAutoRefreshIntervalSeconds
	// (30s, production-safe). `dexaflow lite` sets it to ~5s for a snappy inner loop.
	AutoRefreshIntervalSeconds int
	// Theme is the Chakra theme /ui/config hands the UI (Airflow's `[api]
	// theme`: tokens, globalCss, icon, icon_dark_mode), already validated as a
	// JSON object at boot. Nil serves null, the stock look (#1289).
	Theme json.RawMessage
	// ETagRevalidation (ui.etag_revalidation) relaxes no-store to
	// "private, no-cache" with Vary: Authorization, Cookie on the routes that
	// compute an ETag, so the browser can revalidate them and get a 304. False
	// (the default) keeps no-store on every UI route.
	ETagRevalidation bool

	// SPA serves the embedded SPA. When nil the server is API-only.
	SPA UIServer

	// Workspace backs the Lite web editor (ADR 0025). When nil the editor's
	// filesystem API is not registered (Production, or Lite without a workspace).
	Workspace WorkspaceFS

	// MonacoDir is the directory holding the pinned Monaco bundle that
	// `dexaflow setup` fetched; the editor page is served Monaco from it. Empty or
	// missing makes the page show a setup hint instead of a broken editor.
	MonacoDir string

	// ExamplesFS backs the IDE's "Download examples" button, typically the
	// `embed.FS` shipped from the leoflow root package. Nil disables the button.
	ExamplesFS fs.FS
}

type UIServer interface {
	StaticHandler() http.Handler
	Index(w http.ResponseWriter, basePath string)
}

type UnitMisfitRecorder interface {
	RecordUnitMisfit(stage string)
}

type UnpinnedImageRecorder interface {
	RecordUnpinnedImage(stage, outcome string)
}

type UsageEventReader interface {
	// ReadEvents returns up to limit events after the cursor in serving
	// order, or a page that says recording is off or that the cursor is
	// older than the events kept.
	ReadEvents(ctx context.Context, after domain.UsageCursor, limit int) (domain.UsagePage, error)
}

type UserAuditWriter interface {
	RecordUserCreatedAudit(ctx context.Context, tenant, actorUserID, createdUserID, email, roles string) error
}

type UserStore interface {
	CreateUser(ctx context.Context, tenant, email, password string, roles []string) (domain.User, error)
	ListUsers(ctx context.Context, tenant string, limit, offset int) ([]domain.User, int, error)
}

type VariableStore interface {
	ListVariables(ctx context.Context, tenant string, limit, offset int) ([]domain.Variable, int, error)
	ListVariablesFiltered(ctx context.Context, tenant, pattern, prefixPattern string, limit, offset int) ([]domain.Variable, int, error)
	GetVariable(ctx context.Context, tenant, key string) (domain.Variable, error)
	SetVariablePatch(ctx context.Context, tenant string, p domain.VariablePatch) error
	DeleteVariable(ctx context.Context, tenant, key string) error
}

type WorkspaceFS interface {
	Tree() ([]workspace.Entry, error)
	Read(rel string) ([]byte, error)
	Write(rel string, data []byte) error
	Create(rel string, dir bool) error
	Move(from, to string) error
	Delete(rel string) error
}

type XComReader interface {
	GetXCom(ctx context.Context, tenant, dagID, runID, taskID, key string) (xcom.Entry, error)
	ListXComEntries(ctx context.Context, tenant, dagID, runID, taskID string) ([]domain.XComEntryMeta, error)
}