storage

type AgentCertPins struct {
	Serial       string
	SPKI         []byte
	PrevSerial   string
	PrevSPKI     []byte
	OverlapUntil *time.Time
}

type AgentCertificateRecoveryGrantRecord struct {
	AgentID   string
	IssuedBy  string
	IssuedAt  time.Time
	ExpiresAt time.Time
	UsedAt    *time.Time
	RevokedAt *time.Time
}

type AgentCertificateRecoveryGrantStore interface {
	PutAgentCertificateRecoveryGrant(ctx context.Context, grant AgentCertificateRecoveryGrantRecord) error
	ListAgentCertificateRecoveryGrants(ctx context.Context) ([]AgentCertificateRecoveryGrantRecord, error)
	GetAgentCertificateRecoveryGrant(ctx context.Context, agentID string) (AgentCertificateRecoveryGrantRecord, error)
	UseAgentCertificateRecoveryGrant(ctx context.Context, agentID string, usedAt time.Time) (AgentCertificateRecoveryGrantRecord, error)
	RevokeAgentCertificateRecoveryGrant(ctx context.Context, agentID string, revokedAt time.Time) (AgentCertificateRecoveryGrantRecord, error)
}

type AgentConfigTargetRecord struct {
	ScopeType    string
	ScopeID      string
	SectionsJSON string
	CreatedAt    time.Time
	UpdatedAt    time.Time
}

type AgentFallbackStateRecord struct {
	AgentID   string
	EnteredAt time.Time
}

type AgentFallbackStateStore interface {
	PutAgentFallbackState(ctx context.Context, rec AgentFallbackStateRecord) error
	DeleteAgentFallbackState(ctx context.Context, agentID string) error
	GetAgentFallbackState(ctx context.Context, agentID string) (AgentFallbackStateRecord, error)
	// TODO(cursor): add ListAgentFallbackStateCursor next sprint. This is the
	// boot-time restore path; deferred from S25 T1 because the bound is
	// "agents in fallback simultaneously" which is small in practice.
	ListAgentFallbackState(ctx context.Context) ([]AgentFallbackStateRecord, error)
}

type AgentRecord struct {
	ID            string
	NodeName      string
	FleetGroupID  string
	Version       string
	ReadOnly      bool
	LastSeenAt    time.Time
	CertIssuedAt  *time.Time
	CertExpiresAt *time.Time
	// CertSerial pins the latest issued certificate's serial number so a
	// previously-issued cert (e.g. a not-yet-expired old one harvested
	// from a backup or rotation log) cannot impersonate the agent
	// (Q4.U-S-04). Hex-encoded big-endian serial.
	CertSerial string
	// CertSPKISHA256 is the SHA-256 hash of the agent's serving cert SPKI,
	// set on first successful enroll (S-02). Empty bytes mean "not yet
	// pinned"; subsequent dials must verify the served cert hashes to this
	// value via storage.UpdateAgentCertPin.
	CertSPKISHA256 []byte
	// BootstrapState is the enrollment lifecycle state ("pending",
	// "expired", "active"; empty for legacy inbound rows). Written by the
	// bootstrap token/enroll paths; surfaced so a half-added node restores
	// and renders as pending rather than offline (R9a).
	BootstrapState string
	// TransportMode is the persisted dial mode ("inbound"/"outbound").
	TransportMode string
	// DialAddress is the panel-dials-agent target for outbound rows.
	DialAddress string
}

type AgentRevocationRecord struct {
	AgentID       string
	RevokedAt     time.Time
	CertExpiresAt time.Time
}

type AgentRevocationStore interface {
	PutAgentRevocation(ctx context.Context, revocation AgentRevocationRecord) error
	ListAgentRevocations(ctx context.Context) ([]AgentRevocationRecord, error)
	DeleteExpiredAgentRevocations(ctx context.Context, before time.Time) (int64, error)
}

type AgentUpdateStrategyRecord struct {
	AgentID     string
	Mode        string
	RestartSpec string
	BinaryPath  string
	AssetFlavor string
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

type AuditEventRecord struct {
	ID        string
	ActorID   string
	Action    string
	TargetID  string
	CreatedAt time.Time
	Details   map[string]any
	PrevHash  string
	EventHash string
}

type AuditStore interface {
	AppendAuditEvent(ctx context.Context, event AuditEventRecord) error
	// AppendAuditEventsBulk inserts a batch of audit events in one
	// transaction (P6-6.1b, finding #10). Rows are inserted in slice
	// order; hash-chain fields (PrevHash/EventHash) are computed by the
	// producer BEFORE buffering, so bulk insertion does not affect chain
	// integrity. IDs are unique — no conflict clause.
	AppendAuditEventsBulk(ctx context.Context, events []AuditEventRecord) error
	// ListAuditEvents returns the most recent audit events in ascending
	// chronological order. limit caps the number of rows returned; values
	// <= 0 fall back to a hard maximum of 1024.
	ListAuditEvents(ctx context.Context, limit int) ([]AuditEventRecord, error)
	// ListAuditEventsCursor returns one page in (created_at DESC, id DESC)
	// order — newest first — for keyset pagination. The returned next cursor
	// is non-empty iff a further page may exist. Limit follows
	// DefaultCursorPageSize / MaxCursorPageSize. Note this differs from
	// ListAuditEvents which returns ASCENDING for legacy timeline replay;
	// the cursor variant goes newest-first because that's the operator's
	// audit-page reading order.
	ListAuditEventsCursor(ctx context.Context, params ListAuditEventsCursorParams) ([]AuditEventRecord, ListAuditEventsCursorParams, error)
	// PruneAuditEvents deletes audit_events rows with created_at strictly
	// before the cutoff and returns the number of deleted rows. Used by the
	// retention worker (P2-REL-04 / finding M-R2) to keep audit_events from
	// growing unbounded.
	PruneAuditEvents(ctx context.Context, before time.Time) (int64, error)
	// LatestAuditChainHash returns the event_hash of the most recently
	// persisted audit row, or "" when the table is empty (no chain yet).
	// Producers read this once before each batch flush so each new row's
	// PrevHash is the previous row's EventHash. Migration 0038 added the
	// underlying columns.
	LatestAuditChainHash(ctx context.Context) (string, error)
}

type CPSecretRecord struct {
	Key       string
	Value     []byte
	UpdatedAt time.Time
}

type CPSecretStore interface {
	GetCPSecret(ctx context.Context, key string) ([]byte, error)
	PutCPSecret(ctx context.Context, key string, value []byte) error
	// ListCPSecrets returns every cp_secrets row. cp_secrets has no
	// natural listing method on the runtime path (callers always know
	// the key); this exists for the offline migrate tooling so the
	// table-complete copy can enumerate and re-Put every secret
	// verbatim. Values are raw bytes — never re-encoded.
	ListCPSecrets(ctx context.Context) ([]CPSecretRecord, error)
}

type CertificateAuthorityRecord struct {
	CAPEM         string
	PrivateKeyPEM string
	UpdatedAt     time.Time
}

type CertificateAuthorityStore interface {
	PutCertificateAuthority(ctx context.Context, authority CertificateAuthorityRecord) error
	GetCertificateAuthority(ctx context.Context) (CertificateAuthorityRecord, error)
}

type ClientAssignmentRecord struct {
	ID           string
	ClientID     string
	TargetType   string
	FleetGroupID string
	AgentID      string
	CreatedAt    time.Time
}

type ClientDeploymentRecord struct {
	ClientID           string
	AgentID            string
	DesiredOperation   string
	Status             string
	LastError          string
	ConnectionLinks    []string
	LinkDiagnostic     string
	LastAppliedAt      *time.Time
	UpdatedAt          time.Time
	LastResetEpochSecs uint64
}

type ClientIPAggregateRecord struct {
	IPAddress string
	FirstSeen time.Time
	LastSeen  time.Time
}

type ClientIPHistoryRecord struct {
	AgentID   string
	ClientID  string
	IPAddress string
	FirstSeen time.Time
	LastSeen  time.Time
}

type ClientRecord struct {
	ID                string
	Name              string
	SecretCiphertext  string
	UserADTag         string
	Enabled           bool
	MaxTCPConns       int
	MaxUniqueIPs      int
	DataQuotaBytes    int64
	ExpirationRFC3339 string
	SubscriptionToken string // opaque /sub/<token> handle; "" means not yet generated
	CreatedAt         time.Time
	UpdatedAt         time.Time
	DeletedAt         *time.Time
}

type ClientUsageRecord struct {
	ClientID           string
	AgentID            string
	TrafficUsedBytes   uint64
	UniqueIPsUsed      int
	ActiveTCPConns     int
	ActiveUniqueIPs    int
	QuotaUsedBytes     uint64
	QuotaLastResetUnix uint64
	AgentBootID        string
	LastTotalBytes     uint64
	ObservedAt         time.Time
}

type ConfigApplyBatchRecord struct {
	ID               string
	FleetGroupID     string
	Mode             string
	WaveSize         int
	ExpectedRevision string
	Status           string
	CreatedAt        time.Time
	UpdatedAt        time.Time
}

type ConfigApplyBatchStore interface {
	// CreateConfigApplyBatch inserts a batch row and its full target set
	// atomically: either every row lands or none does. Implementations
	// MUST run this inside a single transaction.
	CreateConfigApplyBatch(ctx context.Context, b ConfigApplyBatchRecord, targets []ConfigApplyBatchTargetRecord) error
	// GetConfigApplyBatch returns the batch plus every target row, ordered
	// by wave_index then agent_id. Returns ErrNotFound when no batch with
	// the given id exists.
	GetConfigApplyBatch(ctx context.Context, id string) (ConfigApplyBatchRecord, []ConfigApplyBatchTargetRecord, error)
	// ListRunningConfigApplyBatches returns every batch whose status is
	// ConfigApplyBatchStatusRunning. Used by the coordinator to resume
	// in-flight rollouts after a restart.
	ListRunningConfigApplyBatches(ctx context.Context) ([]ConfigApplyBatchRecord, error)
	// ActiveConfigApplyBatchForGroup returns the running batch for a fleet
	// group, if any. The bool is false (with a zero-value record) when the
	// group has no batch in ConfigApplyBatchStatusRunning.
	ActiveConfigApplyBatchForGroup(ctx context.Context, fleetGroupID string) (ConfigApplyBatchRecord, bool, error)
	// UpdateConfigApplyBatchStatus transitions a batch's status and bumps
	// updated_at. Returns ErrNotFound when no batch with the given id exists.
	UpdateConfigApplyBatchStatus(ctx context.Context, id, status string, now time.Time) error
	// SetConfigApplyBatchTargetJob records the job enqueued for one target
	// (wave enqueue) and updates its status in the same write.
	SetConfigApplyBatchTargetJob(ctx context.Context, batchID, agentID, jobID, status string) error
	// UpdateConfigApplyBatchTargetStatus updates one target's delivery
	// status and message without touching its job id. message is typically
	// the agent's own failure text (empty for succeeded/skipped targets) and
	// is persisted so it survives eviction of the underlying job from the
	// in-memory jobs store, keeping the batch-status view resumable.
	UpdateConfigApplyBatchTargetStatus(ctx context.Context, batchID, agentID, status, message string) error
	// PruneConfigApplyBatches deletes batches in a terminal status
	// (succeeded/failed/halted) whose updated_at predates the cutoff.
	// Targets are removed via ON DELETE CASCADE. Returns the number of
	// batches deleted.
	PruneConfigApplyBatches(ctx context.Context, before time.Time) (int64, error)
}

type ConfigApplyBatchTargetRecord struct {
	BatchID   string
	AgentID   string
	WaveIndex int
	JobID     string
	Status    string
	Message   string
}

type ConsumedTotpRecord struct {
	UserID string
	Code   string
	UsedAt time.Time
}

type ConsumedTotpStore interface {
	UpsertConsumedTotp(ctx context.Context, record ConsumedTotpRecord) error
	ListConsumedTotp(ctx context.Context) ([]ConsumedTotpRecord, error)
	DeleteExpiredConsumedTotp(ctx context.Context, before time.Time) error
}

type DCHealthPointRecord struct {
	AgentID         string
	CapturedAt      time.Time
	DC              int
	CoveragePctAvg  float64
	CoveragePctMin  float64
	RTTMsAvg        float64
	RTTMsMax        float64
	AliveWritersMin int
	RequiredWriters int
	LoadMax         int
	SampleCount     int
}

type DiscoveredClientRecord struct {
	ID                 string
	AgentID            string
	ClientName         string
	Secret             string
	Status             string
	TotalOctets        uint64
	CurrentConnections int
	ActiveUniqueIPs    int
	ConnectionLinks    []string
	MaxTCPConns        int
	MaxUniqueIPs       int
	DataQuotaBytes     int64
	Expiration         string
	DiscoveredAt       time.Time
	UpdatedAt          time.Time
}

type EnrollmentStore interface {
	PutEnrollmentToken(ctx context.Context, token EnrollmentTokenRecord) error
	ListEnrollmentTokens(ctx context.Context) ([]EnrollmentTokenRecord, error)
	GetEnrollmentToken(ctx context.Context, value string) (EnrollmentTokenRecord, error)
	ConsumeEnrollmentToken(ctx context.Context, value string, consumedAt time.Time) (EnrollmentTokenRecord, error)
	RevokeEnrollmentToken(ctx context.Context, value string, revokedAt time.Time) (EnrollmentTokenRecord, error)
	// PruneEnrollmentTokens deletes tokens that can never be consumed
	// again: consumed or revoked before the cutoff, or expired before
	// the cutoff while never consumed. Live tokens are never touched.
	// Returns the number of deleted rows (C4).
	PruneEnrollmentTokens(ctx context.Context, before time.Time) (int64, error)
}

type EnrollmentTokenRecord struct {
	Value        string
	FleetGroupID string
	IssuedAt     time.Time
	ExpiresAt    time.Time
	ConsumedAt   *time.Time
	RevokedAt    *time.Time
}

type FleetGroupIntegrationRecord struct {
	ID           string
	FleetGroupID string
	Kind         string
	ProviderID   *string
	Config       []byte
	Enabled      bool
	CreatedAt    time.Time
	UpdatedAt    time.Time
}

type FleetGroupRecord struct {
	ID          string
	Name        string
	Label       string
	Description string
	CreatedAt   time.Time
	UpdatedAt   time.Time
}

type FleetStore interface {
	// PutFleetGroup upserts a fleet group by id. Used by migration/copy
	// helpers and tests. HTTP-layer CRUD calls the explicit
	// Create/Update/Delete methods below, which enforce uniqueness and
	// bump updated_at.
	PutFleetGroup(ctx context.Context, group FleetGroupRecord) error
	CreateFleetGroup(ctx context.Context, group FleetGroupRecord) error
	UpdateFleetGroup(ctx context.Context, group FleetGroupRecord) error
	GetFleetGroup(ctx context.Context, id string) (FleetGroupRecord, error)
	GetFleetGroupByName(ctx context.Context, name string) (FleetGroupRecord, error)
	ListFleetGroups(ctx context.Context) ([]FleetGroupRecord, error)
	// DeleteFleetGroup removes the row. Callers are responsible for
	// reassigning or detaching dependents first (agents, enrollment
	// tokens, client_assignments); the DB enforces FK integrity so a
	// non-reassigned delete fails with a constraint error.
	DeleteFleetGroup(ctx context.Context, id string) error
	// ReassignFleetGroupMembers moves every FK reference to `fromID`
	// (agents.fleet_group_id, enrollment_tokens.fleet_group_id,
	// client_assignments.fleet_group_id) to `toID` in one transaction.
	// Returns the number of rows touched per table for audit logging.
	ReassignFleetGroupMembers(ctx context.Context, fromID, toID string) (ReassignCounts, error)
	// CountFleetGroupMembers returns how many rows in each dependent
	// table reference `fleetGroupID`. Powers the deletion-preview HTTP
	// endpoint so the operator sees the blast radius before confirming.
	CountFleetGroupMembers(ctx context.Context, fleetGroupID string) (ReassignCounts, error)
	PutAgent(ctx context.Context, agent AgentRecord) error
	// PutAgentsBulk upserts a batch of agents in a single transaction. Semantics
	// match PutAgent per row (UPSERT on id); when the same ID appears twice the
	// last occurrence wins. A nil/empty slice is a no-op that returns nil. Used
	// by the control-plane batch writer (P3-PERF-01a) to avoid N individual
	// INSERTs per flush. See also storage/postgres and storage/sqlite
	// implementations which chunk large batches.
	PutAgentsBulk(ctx context.Context, agents []AgentRecord) error
	// TODO(cursor): add ListAgentsCursor next sprint. ListAgents is currently
	// only called at boot and from the operator agents-page; the boot path is
	// safe because the table is small, but the operator path can grow without
	// bound on large fleets. S25 deferred this to keep T1 scope to the two
	// worst offenders (jobs + audit) — see commit feat(server): cursor
	// pagination for ListJobs and ListAuditEvents.
	ListAgents(ctx context.Context) ([]AgentRecord, error)
	// EarliestAgentCertExpiry returns the minimum cert_expires_at across
	// all enrolled agents, or nil when no agent has one recorded
	// (P6-6.3f, finding #14 — replaces the metrics poller's full
	// ListAgents scan with a single-scalar MIN query).
	EarliestAgentCertExpiry(ctx context.Context) (*time.Time, error)
	DeleteAgent(ctx context.Context, agentID string) error
	UpdateAgentNodeName(ctx context.Context, agentID string, nodeName string) error
	// UpdateAgentFleetGroup reassigns the agent to a different fleet
	// group. Empty fleetGroupID detaches the agent (NULL on the column).
	// Returns ErrNotFound when the agent doesn't exist; FK-constraint
	// errors surface verbatim so the HTTP layer can map them to 4xx.
	UpdateAgentFleetGroup(ctx context.Context, agentID, fleetGroupID string) error
	// UpdateAgentCertSerial pins the latest-issued client cert serial
	// for the agent so the gRPC connect path can reject any cert that
	// does not match (Q4.U-S-04).
	UpdateAgentCertSerial(ctx context.Context, agentID string, serial string) error
	// GetAgentCertSerial returns the pinned serial; "" means unpinned
	// (legacy agent whose cert pre-dates the schema migration).
	GetAgentCertSerial(ctx context.Context, agentID string) (string, error)
	// UpdateAgentCertPin persists the SPKI SHA-256 hash for an agent. Set
	// after first successful enroll; subsequent dials verify against this
	// value. Empty pin means "not yet pinned" (S-02). Returns ErrNotFound
	// if no agent with the given ID exists, matching the convention of
	// every other Update* method on this interface.
	UpdateAgentCertPin(ctx context.Context, agentID string, pin []byte) error
	// GetAgentCertPin returns the SPKI pin previously stored via
	// UpdateAgentCertPin. Returns ErrNotFound if no agent with the given
	// ID exists; returns empty bytes (no error) if the agent exists but
	// is not yet pinned.
	GetAgentCertPin(ctx context.Context, agentID string) ([]byte, error)
	// RotateAgentCert records a freshly issued agent credential (serial +
	// SPKI pin) and keeps the PREVIOUS one valid until overlapUntil.
	//
	// Issuance used to overwrite the pin outright, but the agent only learns
	// about its new certificate when the renewal response reaches it. An
	// interrupted exchange therefore left the panel expecting the new
	// credential while the agent still held the old one — and the fail-closed
	// verifier refused it. An inbound agent could ask for a new signature and
	// self-heal; a listen-mode node could not, and stayed stranded until an
	// operator issued a recovery grant (R11 / R-1).
	//
	// The overlap is bounded in time and in size: at most two credentials are
	// accepted at once, and the first connection presenting the new one closes
	// the window (CloseAgentCertOverlap). Outside that pair the verifier is
	// fail-closed exactly as before.
	//
	// presentedSerial is the serial of the certificate the agent authenticated
	// with on the connection that carried this renewal ("" when no presented
	// credential exists — enrollment, recovery). When an overlap window is
	// already OPEN and the presenter is the PREVIOUS credential, the agent has
	// just proven it never took delivery of the current one: shifting
	// prev := current would evict the only certificate the agent holds from
	// the accepted set (two consecutive lost renewal responses then strand a
	// listen-mode node — R11-1). In that case only the current credential
	// moves; prev and its overlap deadline stay untouched, so the credential
	// the agent demonstrably holds stays accepted until the original window
	// closes.
	RotateAgentCert(ctx context.Context, agentID string, serial string, spki []byte, overlapUntil time.Time, presentedSerial string) error
	// GetAgentCertPins returns the credentials the panel accepts for the agent:
	// the current one, plus the previous one while the overlap window is open.
	GetAgentCertPins(ctx context.Context, agentID string) (AgentCertPins, error)
	// CloseAgentCertOverlap drops the previous credential. Called the first
	// time an agent connects presenting the CURRENT one — proof that it has
	// taken delivery of the new certificate.
	CloseAgentCertOverlap(ctx context.Context, agentID string) error
	// UpdateAgentTransportMode changes the agent's transport_mode and
	// dial_address. dialAddress is empty when switching to inbound mode.
	// Returns ErrNotFound when the agent doesn't exist.
	UpdateAgentTransportMode(ctx context.Context, agentID, transportMode, dialAddress string) error
	PutInstance(ctx context.Context, instance InstanceRecord) error
	// PutInstancesBulk upserts a batch of Telemt instances in a single
	// transaction. Same semantics as PutInstance per row; empty slice is a
	// no-op. See P3-PERF-01a.
	PutInstancesBulk(ctx context.Context, instances []InstanceRecord) error
	// TODO(cursor): add ListInstancesCursor next sprint. Same rationale as
	// ListAgents above — deferred from S25 T1 to bound the change footprint.
	ListInstances(ctx context.Context) ([]InstanceRecord, error)
	DeleteInstancesByAgent(ctx context.Context, agentID string) error
	// GetAgentConfigTarget returns the desired config for one scope, or
	// storage.ErrNotFound when none is set.
	GetAgentConfigTarget(ctx context.Context, scopeType, scopeID string) (AgentConfigTargetRecord, error)
	// ListAgentConfigTargets returns all config targets (group + agent scopes).
	ListAgentConfigTargets(ctx context.Context) ([]AgentConfigTargetRecord, error)
	// UpsertAgentConfigTarget creates or replaces the config target for a scope.
	UpsertAgentConfigTarget(ctx context.Context, rec AgentConfigTargetRecord) error
	// DeleteAgentConfigTarget removes the config target for a scope; returns rows deleted.
	DeleteAgentConfigTarget(ctx context.Context, scopeType, scopeID string) (int64, error)
	// GetAgentUpdateStrategy returns the persisted Telemt update strategy for
	// one agent, or storage.ErrNotFound when none is set.
	GetAgentUpdateStrategy(ctx context.Context, agentID string) (AgentUpdateStrategyRecord, error)
	// UpsertAgentUpdateStrategy creates or replaces the update strategy for an
	// agent. CreatedAt is preserved across replaces of an existing row.
	UpsertAgentUpdateStrategy(ctx context.Context, rec AgentUpdateStrategyRecord) error
	// DeleteAgentUpdateStrategy removes the update strategy for an agent.
	// Idempotent: deleting an absent row is not an error.
	DeleteAgentUpdateStrategy(ctx context.Context, agentID string) error
}

type InstanceRecord struct {
	ID                string
	AgentID           string
	Name              string
	Version           string
	ConfigFingerprint string
	Connections       int
	ReadOnly          bool
	UpdatedAt         time.Time
}

type IntegrationProviderRecord struct {
	ID        string
	Kind      string
	Label     string
	Config    []byte
	CreatedAt time.Time
	UpdatedAt time.Time
}

type IntegrationStore interface {
	CreateIntegrationProvider(ctx context.Context, provider IntegrationProviderRecord) error
	UpdateIntegrationProvider(ctx context.Context, provider IntegrationProviderRecord) error
	GetIntegrationProvider(ctx context.Context, id string) (IntegrationProviderRecord, error)
	ListIntegrationProviders(ctx context.Context) ([]IntegrationProviderRecord, error)
	ListIntegrationProvidersByKind(ctx context.Context, kind string) ([]IntegrationProviderRecord, error)
	DeleteIntegrationProvider(ctx context.Context, id string) error

	CreateFleetGroupIntegration(ctx context.Context, integration FleetGroupIntegrationRecord) error
	UpdateFleetGroupIntegration(ctx context.Context, integration FleetGroupIntegrationRecord) error
	GetFleetGroupIntegration(ctx context.Context, id string) (FleetGroupIntegrationRecord, error)
	ListFleetGroupIntegrations(ctx context.Context, fleetGroupID string) ([]FleetGroupIntegrationRecord, error)
	DeleteFleetGroupIntegration(ctx context.Context, id string) error
}

type JobRecord struct {
	ID             string
	Action         string
	ActorID        string
	Status         string
	CreatedAt      time.Time
	TTL            time.Duration
	IdempotencyKey string
	PayloadJSON    string
}

type JobStore interface {
	PutJob(ctx context.Context, job JobRecord) error
	// GetJob returns a single job row by primary key, or ErrNotFound.
	// P8.1 (audit #24): backs jobs.Service.GetWithContext — terminal jobs
	// evicted from the in-memory maps are read back from here until the
	// retention worker deletes them (PruneTerminalJobs).
	GetJob(ctx context.Context, id string) (JobRecord, error)
	// ListJobs returns every job. S25 T1: capped defensively at
	// DefaultListLimit by the SQL backends so a long-lived store cannot
	// stream millions of rows even if a caller forgets to paginate. New
	// callers should use ListJobsCursor (keyset pagination) instead.
	ListJobs(ctx context.Context) ([]JobRecord, error)
	// ListJobsCursor returns one page of jobs in (created_at DESC, id DESC)
	// order. The returned next cursor is non-empty iff a further page may
	// exist; callers thread it back through params.AfterCreatedAt /
	// params.AfterID. Limit follows DefaultCursorPageSize / MaxCursorPageSize.
	ListJobsCursor(ctx context.Context, params ListJobsCursorParams) ([]JobRecord, ListJobsCursorParams, error)
	PutJobTarget(ctx context.Context, target JobTargetRecord) error
	ListJobTargets(ctx context.Context, jobID string) ([]JobTargetRecord, error)
	// ListAllJobTargets returns every job_targets row in one round-trip.
	// Used by Service.restore() to avoid the per-job N+1 SELECT pattern.
	// Empty result is fine — callers must not assume the slice is non-nil.
	ListAllJobTargets(ctx context.Context) ([]JobTargetRecord, error)
	// PruneTerminalJobs deletes jobs in succeeded/failed/expired status
	// whose created_at predates the cutoff (Q2.U-P-02). Returns the
	// number of rows deleted; the bound also cascades to job_targets via
	// ON DELETE CASCADE in the schema.
	PruneTerminalJobs(ctx context.Context, before time.Time) (int64, error)
}

type JobTargetRecord struct {
	JobID      string
	AgentID    string
	Status     string
	ResultText string
	ResultJSON string
	UpdatedAt  time.Time
}

type ListAuditEventsCursorParams struct {
	Limit          int
	AfterCreatedAt time.Time
	AfterID        string
}

type ListJobsCursorParams struct {
	Limit          int
	AfterCreatedAt time.Time
	AfterID        string
}

type LoginLockoutRecord struct {
	Username  string
	Failures  int
	LockedAt  *time.Time
	UpdatedAt time.Time
}

type LoginLockoutStore interface {
	UpsertLoginLockout(ctx context.Context, record LoginLockoutRecord) error
	GetLoginLockout(ctx context.Context, username string) (LoginLockoutRecord, error)
	DeleteLoginLockout(ctx context.Context, username string) error
	ListLoginLockouts(ctx context.Context) ([]LoginLockoutRecord, error)
	DeleteExpiredLoginLockouts(ctx context.Context, before time.Time) (int64, error)
}

type MetricSnapshotRecord struct {
	ID         string
	AgentID    string
	InstanceID string
	CapturedAt time.Time
	Values     map[string]uint64
}

type MetricStore interface {
	AppendMetricSnapshot(ctx context.Context, snapshot MetricSnapshotRecord) error
	// AppendMetricSnapshotsBulk inserts a batch of metric snapshots in a
	// single transaction. Empty slice is a no-op. See P3-PERF-01a.
	AppendMetricSnapshotsBulk(ctx context.Context, snapshots []MetricSnapshotRecord) error
	// TODO(cursor): add ListMetricSnapshotsCursor next sprint. The current
	// implementations cap the result at 512 rows internally so this is not
	// catastrophically unbounded, but operators viewing more than 512 most-
	// recent snapshots silently lose history. Deferred from S25 T1.
	ListMetricSnapshots(ctx context.Context) ([]MetricSnapshotRecord, error)
	// PruneMetricSnapshots deletes metric_snapshots rows with captured_at
	// strictly before the cutoff and returns the number of deleted rows.
	// Used by the retention worker (P2-REL-05).
	PruneMetricSnapshots(ctx context.Context, before time.Time) (int64, error)
}

type MigrationStore interface {
	Store
	ClientStore
}

type PanelSettingsRecord struct {
	HTTPPublicURL      string
	GRPCPublicEndpoint string
	// PasswordMinLength is the operator-configured minimum password length.
	// Zero is sentinel for "not configured" — callers should treat it as
	// the compiled-in default (auth.DefaultPasswordMinLength).
	PasswordMinLength int32
	UpdatedAt         time.Time
}

type PanelSettingsStore interface {
	PutPanelSettings(ctx context.Context, settings PanelSettingsRecord) error
	GetPanelSettings(ctx context.Context) (PanelSettingsRecord, error)
}

type ReassignCounts struct {
	Agents            int64
	EnrollmentTokens  int64
	ClientAssignments int64
}

type RetentionSettings = RetentionSettingsRecord

type RetentionSettingsRecord struct {
	TSRawSeconds          int `json:"ts_raw_seconds"`
	TSHourlySeconds       int `json:"ts_hourly_seconds"`
	TSDCSeconds           int `json:"ts_dc_seconds"`
	IPHistorySeconds      int `json:"ip_history_seconds"`
	EventSeconds          int `json:"event_history_seconds"`
	AuditEventSeconds     int `json:"audit_event_seconds"`
	MetricSnapshotSeconds int `json:"metric_snapshot_seconds"`
	// JobsSeconds bounds how long terminal jobs (succeeded/failed/
	// expired) live in the jobs table before the rollup loop deletes
	// them via PruneTerminalJobs (Q2.U-P-02). Zero disables job
	// pruning so existing dev fixtures keep their full history.
	JobsSeconds int `json:"jobs_seconds"`
	// WebhookOutboxSeconds bounds how long terminal webhook_outbox rows
	// (delivered or dead) are kept for operator audit before the rollup
	// loop prunes them via webhooks.Storage.PruneOutbox (C4).
	WebhookOutboxSeconds int `json:"webhook_outbox_seconds"`
	// EnrollmentTokenSeconds bounds how long dead enrollment tokens
	// (consumed, revoked, or expired-unconsumed) are kept for operator
	// forensics before the rollup loop prunes them via
	// PruneEnrollmentTokens (C4).
	EnrollmentTokenSeconds int `json:"enrollment_token_seconds"`
	// ConfigApplyBatchSeconds bounds how long terminal group config-apply
	// batches (succeeded/failed/halted) and their targets live before the
	// rollup loop deletes them via PruneConfigApplyBatches (Phase A / A5).
	// Zero disables the prune, matching JobsSeconds's zero-disables
	// convention, so existing dev fixtures keep their full history.
	ConfigApplyBatchSeconds int `json:"config_apply_batch_seconds"`
}

type RetentionSettingsStore interface {
	GetRetentionSettings(ctx context.Context) (RetentionSettings, error)
	PutRetentionSettings(ctx context.Context, settings RetentionSettings) error
}

type ServerLoadHourlyRecord struct {
	AgentID        string
	BucketHour     time.Time
	CPUPctAvg      float64
	CPUPctMax      float64
	MemPctAvg      float64
	MemPctMax      float64
	ConnectionsAvg float64
	ConnectionsMax int
	ActiveUsersAvg float64
	ActiveUsersMax int
	DCCoverageMin  float64
	DCCoverageAvg  float64
	SampleCount    int
}

type ServerLoadPointRecord struct {
	AgentID                string
	CapturedAt             time.Time
	CPUPctAvg              float64
	CPUPctMax              float64
	MemPctAvg              float64
	MemPctMax              float64
	DiskPctAvg             float64
	DiskPctMax             float64
	Load1M                 float64
	Load5M                 float64
	Load15M                float64
	ConnectionsAvg         int
	ConnectionsMax         int
	ConnectionsMEAvg       int
	ConnectionsDirectAvg   int
	ActiveUsersAvg         int
	ActiveUsersMax         int
	ConnectionsTotal       uint64
	ConnectionsBadTotal    uint64
	HandshakeTimeoutsTotal uint64
	DCCoverageMinPct       float64
	DCCoverageAvgPct       float64
	HealthyUpstreams       int
	TotalUpstreams         int
	NetBytesSent           uint64
	NetBytesRecv           uint64
	SampleCount            int
}

type SessionRecord struct {
	ID        string
	UserID    string
	CreatedAt time.Time
	// LastSeenAt is the persisted sliding-refresh timestamp (Q2.U-S-12).
	// Updated by SessionStore.TouchSession at most every
	// sessionTouchThrottle so the idle-timeout survives a restart
	// without thrashing the store on every authenticated request.
	LastSeenAt time.Time
}

type SessionStore interface {
	PutSession(ctx context.Context, session SessionRecord) error
	GetSession(ctx context.Context, sessionID string) (SessionRecord, error)
	DeleteSession(ctx context.Context, sessionID string) error
	ListSessions(ctx context.Context) ([]SessionRecord, error)
	DeleteExpiredSessions(ctx context.Context, before time.Time) error
	// TouchSession persists a refreshed LastSeenAt so the sliding idle
	// timeout survives a control-plane restart (Q2.U-S-12). Implementations
	// must update only the last_seen_at column to avoid contention on
	// the rest of the row.
	TouchSession(ctx context.Context, sessionID string, lastSeenAt time.Time) error
}

type Store interface {
	UserStore
	UserFleetGroupScopeStore
	UserAppearanceStore
	SessionStore
	CPSecretStore
	ConsumedTotpStore
	LoginLockoutStore
	AgentRevocationStore
	AgentFallbackStateStore
	FleetStore
	JobStore
	AuditStore
	MetricStore
	TelemetryStore
	EnrollmentStore
	AgentCertificateRecoveryGrantStore
	PanelSettingsStore
	RetentionSettingsStore
	UpdateConfigStore
	CertificateAuthorityStore
	TimeseriesStore
	IntegrationStore
	ConfigApplyBatchStore

	// Transact runs fn inside a single database transaction. The tx
	// argument is a Store implementation bound to the transaction:
	// all mutations performed through it either commit as a unit or
	// roll back together.
	//
	// Contract:
	//   - On fn returning nil, the transaction commits.
	//   - On fn returning a non-nil error, the transaction rolls back
	//     and the error is returned to the caller.
	//   - On panic inside fn, the transaction rolls back and the panic
	//     is re-raised.
	//   - Context cancellation during fn aborts the transaction.
	//   - PostgreSQL: serialization failures (SQLSTATE 40001) are
	//     retried up to 3 times automatically. Default isolation is
	//     read-committed.
	//   - SQLite: uses BEGIN IMMEDIATE so the writer lock is acquired
	//     up front. No retry loop (single-writer semantics).
	//   - TxFn MUST NOT call tx.Transact; nested calls return
	//     ErrNestedTransact immediately.
	Transact(ctx context.Context, fn TxFn) error

	// Ping verifies that the database connection is alive.
	Ping(ctx context.Context) error
	Close() error
}

type TelemetryDiagnosticsCurrentRecord struct {
	AgentID             string
	ObservedAt          time.Time
	State               string
	StateReason         string
	SystemInfoJSON      string
	EffectiveLimitsJSON string
	SecurityPostureJSON string
	MinimalAllJSON      string
	MEPoolJSON          string
	DcsJSON             string
}

type TelemetryRuntimeCurrentRecord struct {
	AgentID     string
	ObservedAt  time.Time
	RuntimeJSON string
}

type TelemetryRuntimeDCRecord struct {
	AgentID            string
	DC                 int
	ObservedAt         time.Time
	AvailableEndpoints int
	AvailablePct       float64
	RequiredWriters    int
	AliveWriters       int
	CoveragePct        float64
	RTTMs              float64
	Load               float64
}

type TelemetryRuntimeEventRecord struct {
	AgentID    string
	Sequence   int64
	ObservedAt time.Time
	Timestamp  time.Time
	EventType  string
	Context    string
	Severity   string
}

type TelemetryRuntimeUpstreamRecord struct {
	AgentID            string
	UpstreamID         int
	ObservedAt         time.Time
	RouteKind          string
	Address            string
	Healthy            bool
	Fails              int
	EffectiveLatencyMs float64
}

type TelemetrySecurityInventoryCurrentRecord struct {
	AgentID      string
	ObservedAt   time.Time
	State        string
	StateReason  string
	Enabled      bool
	EntriesTotal int
	EntriesJSON  string
}

type TelemetryStore interface {
	PutTelemetryRuntimeCurrent(ctx context.Context, record TelemetryRuntimeCurrentRecord) error
	GetTelemetryRuntimeCurrent(ctx context.Context, agentID string) (TelemetryRuntimeCurrentRecord, error)
	ListTelemetryRuntimeCurrent(ctx context.Context) ([]TelemetryRuntimeCurrentRecord, error)
	ReplaceTelemetryRuntimeDCs(ctx context.Context, agentID string, records []TelemetryRuntimeDCRecord) error
	ListTelemetryRuntimeDCs(ctx context.Context, agentID string) ([]TelemetryRuntimeDCRecord, error)
	// ListAllTelemetryRuntimeDCs returns DC rows for every agent in one
	// query. Cold-start rehydration groups the result by agent_id in
	// memory instead of issuing one query per agent (A2).
	ListAllTelemetryRuntimeDCs(ctx context.Context) ([]TelemetryRuntimeDCRecord, error)
	ReplaceTelemetryRuntimeUpstreams(ctx context.Context, agentID string, records []TelemetryRuntimeUpstreamRecord) error
	ListTelemetryRuntimeUpstreams(ctx context.Context, agentID string) ([]TelemetryRuntimeUpstreamRecord, error)
	// ListAllTelemetryRuntimeUpstreams returns upstream rows for every
	// agent in one query (A2 cold-start rehydration).
	ListAllTelemetryRuntimeUpstreams(ctx context.Context) ([]TelemetryRuntimeUpstreamRecord, error)
	AppendTelemetryRuntimeEvents(ctx context.Context, agentID string, records []TelemetryRuntimeEventRecord) error
	ListTelemetryRuntimeEvents(ctx context.Context, agentID string, limit int) ([]TelemetryRuntimeEventRecord, error)
	// ListAllTelemetryRuntimeEventsPerAgent returns the most recent
	// perAgentLimit events PER agent (a windowed query, NOT a global
	// limit) for every agent in one round-trip (A2 cold-start
	// rehydration). When perAgentLimit <= 0 all events are returned.
	ListAllTelemetryRuntimeEventsPerAgent(ctx context.Context, perAgentLimit int) ([]TelemetryRuntimeEventRecord, error)
	PruneTelemetryRuntimeEvents(ctx context.Context, olderThan time.Time) (int64, error)
	PutTelemetryDiagnosticsCurrent(ctx context.Context, record TelemetryDiagnosticsCurrentRecord) error
	GetTelemetryDiagnosticsCurrent(ctx context.Context, agentID string) (TelemetryDiagnosticsCurrentRecord, error)
	PutTelemetrySecurityInventoryCurrent(ctx context.Context, record TelemetrySecurityInventoryCurrentRecord) error
	GetTelemetrySecurityInventoryCurrent(ctx context.Context, agentID string) (TelemetrySecurityInventoryCurrentRecord, error)

	// PutTelemetryRuntimeCurrentBulk upserts a batch of runtime JSON blobs
	// in a single transaction (P6-6.1a, finding #10). Per-row semantics match
	// PutTelemetryRuntimeCurrent; duplicate AgentIDs inside one batch
	// collapse to last-wins on BOTH backends (Postgres cannot upsert the
	// same conflict key twice in one statement, so implementations dedup
	// before inserting).
	PutTelemetryRuntimeCurrentBulk(ctx context.Context, records []TelemetryRuntimeCurrentRecord) error
	// ReplaceTelemetryRuntimeDCsBulk applies the ReplaceTelemetryRuntimeDCs
	// semantics for many agents in ONE transaction: every agent key present
	// in byAgent has its DC rows deleted and re-inserted from the mapped
	// slice (an empty slice clears the agent's rows). Agents absent from the
	// map are untouched.
	ReplaceTelemetryRuntimeDCsBulk(ctx context.Context, byAgent map[string][]TelemetryRuntimeDCRecord) error
	// ReplaceTelemetryRuntimeUpstreamsBulk: see ReplaceTelemetryRuntimeDCsBulk.
	ReplaceTelemetryRuntimeUpstreamsBulk(ctx context.Context, byAgent map[string][]TelemetryRuntimeUpstreamRecord) error
	// AppendTelemetryRuntimeEventsBulk inserts/upserts runtime events for
	// MANY agents in one transaction. Records carry their own AgentID.
	// Conflict target (agent_id, sequence) matches the single-agent
	// AppendTelemetryRuntimeEvents; duplicates within one batch collapse
	// to last-wins.
	AppendTelemetryRuntimeEventsBulk(ctx context.Context, records []TelemetryRuntimeEventRecord) error
	// PutTelemetryDiagnosticsCurrentBulk upserts a batch of diagnostics
	// snapshots in one transaction. Duplicate AgentIDs collapse last-wins.
	PutTelemetryDiagnosticsCurrentBulk(ctx context.Context, records []TelemetryDiagnosticsCurrentRecord) error
	// PutTelemetrySecurityInventoryCurrentBulk upserts a batch of security
	// inventory snapshots in one transaction. Duplicate AgentIDs collapse
	// last-wins.
	PutTelemetrySecurityInventoryCurrentBulk(ctx context.Context, records []TelemetrySecurityInventoryCurrentRecord) error
}

type TimeseriesStore interface {
	AppendServerLoadPoint(ctx context.Context, record ServerLoadPointRecord) error
	// AppendServerLoadPointsBulk inserts a batch of server-load points in a
	// single transaction. Same ON-CONFLICT DO NOTHING semantics as the
	// single-row variant. Empty slice is a no-op. See P3-PERF-01a.
	AppendServerLoadPointsBulk(ctx context.Context, records []ServerLoadPointRecord) error
	ListServerLoadPoints(ctx context.Context, agentID string, from time.Time, to time.Time) ([]ServerLoadPointRecord, error)
	PruneServerLoadPoints(ctx context.Context, olderThan time.Time) (int64, error)
	AppendDCHealthPoint(ctx context.Context, record DCHealthPointRecord) error
	// AppendDCHealthPointsBulk inserts a batch of DC-health points in a
	// single transaction. Same ON-CONFLICT DO NOTHING semantics. Empty
	// slice is a no-op. See P3-PERF-01a.
	AppendDCHealthPointsBulk(ctx context.Context, records []DCHealthPointRecord) error
	ListDCHealthPoints(ctx context.Context, agentID string, from time.Time, to time.Time) ([]DCHealthPointRecord, error)
	PruneDCHealthPoints(ctx context.Context, olderThan time.Time) (int64, error)
	UpsertClientIPHistory(ctx context.Context, record ClientIPHistoryRecord) error
	// UpsertClientIPHistoryBulk upserts a batch of client-ip history rows in
	// a single transaction. Same semantics as the single-row UPSERT
	// (last_seen is updated on conflict). Empty slice is a no-op. See
	// P3-PERF-01a.
	UpsertClientIPHistoryBulk(ctx context.Context, records []ClientIPHistoryRecord) error
	ListClientIPHistory(ctx context.Context, clientID string, from time.Time, to time.Time) ([]ClientIPHistoryRecord, error)
	// AggregateClientIPHistory folds the per-(agent, ip) rows into one
	// per IP using SQL GROUP BY: MIN(first_seen) and MAX(last_seen).
	// Sorted last_seen DESC. Pushes the work into the database so the
	// CP no longer holds the full raw set in memory just to collapse
	// duplicates.
	AggregateClientIPHistory(ctx context.Context, clientID string, from time.Time, to time.Time, limit int) ([]ClientIPAggregateRecord, error)
	CountUniqueClientIPs(ctx context.Context, clientID string) (int, error)
	// CountUniqueClientIPsForClients returns the unique-IP count for
	// each client ID in a single SQL round-trip (Q2.U-P-03). The
	// returned map only carries entries for client IDs with at least
	// one history row; missing entries should be treated as zero.
	// Empty input is a no-op that returns an empty map.
	CountUniqueClientIPsForClients(ctx context.Context, clientIDs []string) (map[string]int, error)
	// ListServerLoadPointsForAgents fetches the raw load points for a
	// batch of agents in a single SQL round-trip (Q2.U-P-01). The
	// per-agent slices stay sorted by captured_at ascending to match
	// the single-agent shape. Missing agents return no key.
	ListServerLoadPointsForAgents(ctx context.Context, agentIDs []string, from time.Time, to time.Time) (map[string][]ServerLoadPointRecord, error)
	PruneClientIPHistory(ctx context.Context, olderThan time.Time) (int64, error)
	RollupServerLoadHourly(ctx context.Context, bucketHour time.Time) error
	ListServerLoadHourly(ctx context.Context, agentID string, from time.Time, to time.Time) ([]ServerLoadHourlyRecord, error)
	PruneServerLoadHourly(ctx context.Context, olderThan time.Time) (int64, error)
}

type TxFn func(tx Store) error

type UpdateConfigStore interface {
	PutUpdateSettings(ctx context.Context, settings json.RawMessage) error
	GetUpdateSettings(ctx context.Context) (json.RawMessage, error)
	PutUpdateState(ctx context.Context, state json.RawMessage) error
	GetUpdateState(ctx context.Context) (json.RawMessage, error)
	// PutPanelSelfUpdate and GetPanelSelfUpdate persist the panel
	// self-update phase (updates.SelfUpdateState) under its own
	// update_config key, independent of the settings/state keys above.
	PutPanelSelfUpdate(ctx context.Context, raw json.RawMessage) error
	GetPanelSelfUpdate(ctx context.Context) (json.RawMessage, error)
	// PutPendingAgentUpdates and GetPendingAgentUpdates persist the
	// agent-ID -> requested-version map behind the reconcile-on-reconnect
	// of operator-requested agent self-updates, under its own
	// update_config key.
	PutPendingAgentUpdates(ctx context.Context, raw json.RawMessage) error
	GetPendingAgentUpdates(ctx context.Context) (json.RawMessage, error)
	// PutPendingTelemtUpdates and GetPendingTelemtUpdates mirror
	// PutPendingAgentUpdates/GetPendingAgentUpdates for telemt.update jobs
	// (Task 11), under their own update_config key.
	PutPendingTelemtUpdates(ctx context.Context, raw json.RawMessage) error
	GetPendingTelemtUpdates(ctx context.Context) (json.RawMessage, error)
	PutGeoIPSettings(ctx context.Context, settings json.RawMessage) error
	GetGeoIPSettings(ctx context.Context) (json.RawMessage, error)
	PutGeoIPState(ctx context.Context, state json.RawMessage) error
	GetGeoIPState(ctx context.Context) (json.RawMessage, error)
}

type UserAppearanceRecord struct {
	UserID    string
	Theme     string
	Density   string
	HelpMode  string
	UpdatedAt time.Time
}

type UserAppearanceStore interface {
	PutUserAppearance(ctx context.Context, appearance UserAppearanceRecord) error
	GetUserAppearance(ctx context.Context, userID string) (UserAppearanceRecord, error)
	ListUserAppearances(ctx context.Context) ([]UserAppearanceRecord, error)
}

type UserFleetGroupScopeRecord struct {
	UserID       string
	FleetGroupID string
	GrantedBy    string
	GrantedAt    time.Time
}

type UserFleetGroupScopeStore interface {
	// ListUserFleetGroupScopes returns every fleet-group id the given
	// user is scoped to. An empty slice means "global" — the user sees
	// every fleet group.
	ListUserFleetGroupScopes(ctx context.Context, userID string) ([]string, error)
	// SetUserFleetGroupScopes replaces the user's scope set with the
	// supplied list. An empty input clears the scope (back to global).
	// Caller is expected to pre-validate that every fleet group id
	// exists; the store relies on FK integrity for the runtime guarantee.
	SetUserFleetGroupScopes(ctx context.Context, userID string, fleetGroupIDs []string, grantedBy string, grantedAt time.Time) error
	// ListAllUserFleetGroupScopes returns every scope grant across all
	// users with full provenance (granted_by / granted_at). Exists for
	// the offline migrate tooling so the copy preserves audit fields the
	// per-user ListUserFleetGroupScopes drops. No runtime caller.
	ListAllUserFleetGroupScopes(ctx context.Context) ([]UserFleetGroupScopeRecord, error)
}

type UserRecord struct {
	ID           string
	Username     string
	PasswordHash string
	Role         string
	TotpEnabled  bool
	TotpSecret   string
	CreatedAt    time.Time
}

type UserStore interface {
	PutUser(ctx context.Context, user UserRecord) error
	DeleteUser(ctx context.Context, userID string) error
	GetUserByID(ctx context.Context, userID string) (UserRecord, error)
	GetUserByUsername(ctx context.Context, username string) (UserRecord, error)
	ListUsers(ctx context.Context) ([]UserRecord, error)
}