models

type ActorType string

type Agent struct {
	UID string `bun:"uid,pk,type:varchar(36)"`
	// OrganizationUID is nil exactly for system agents.
	OrganizationUID *string `bun:"organization_uid"`
	// Kind is AgentKindOrg or AgentKindSystem.
	Kind string `bun:"kind,notnull"`
	// Region is the region slug the agent is bound to; all its claims are
	// hard-scoped to it. Fully-qualified `@<org>/<region>` for an org agent, a
	// plain cloud region slug for a system agent.
	Region string `bun:"region,notnull"`
	Name   string `bun:"name,notnull"`
	// Ed25519PublicKey is the base64 identity public key used to verify reconnect
	// signatures.
	Ed25519PublicKey string `bun:"ed25519_public_key,notnull"`
	// X25519PublicKey is the age recipient string ("age1…") credentials are
	// sealed to.
	X25519PublicKey string `bun:"x25519_public_key,notnull"`
	// Fingerprint is a short hash of the Ed25519 key, shown in UI/logs.
	Fingerprint string     `bun:"fingerprint,notnull"`
	Status      string     `bun:"status,notnull"`
	LastSeenAt  *time.Time `bun:"last_seen_at"`
	EnrolledAt  time.Time  `bun:"enrolled_at,notnull,default:current_timestamp"`
	RevokedAt   *time.Time `bun:"revoked_at"`
	CreatedAt   time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt   time.Time  `bun:"updated_at,notnull,default:current_timestamp"`
	DeletedAt   *time.Time `bun:"deleted_at"`
}

type AgentEnrollmentToken struct {
	UID string `bun:"uid,pk,type:varchar(36)"`
	// OrganizationUID is nil exactly for system tokens.
	OrganizationUID *string `bun:"organization_uid"`
	// Kind is AgentKindOrg or AgentKindSystem.
	Kind string `bun:"kind,notnull"`
	// Region is the region the enrolled agent will be bound to:
	// `@<org>/<region>` for an org token, a cloud region slug for a system one.
	Region string `bun:"region,notnull"`
	// TokenHash is the SHA-256 hex of the spe_ token — never the token itself.
	TokenHash string    `bun:"token_hash,notnull"`
	ExpiresAt time.Time `bun:"expires_at,notnull"`
	// MaxUses bounds a system token's enrollments (nil = unlimited). Never set
	// on an org token, which is one-shot by construction.
	MaxUses *int `bun:"max_uses"`
	// UseCount is how many agents enrolled with this token (0 or 1 for org).
	UseCount int `bun:"use_count,notnull"`
	// UsedAt / UsedByAgentUID record the LAST enrollment. For an org token they
	// are also the single-use marker.
	UsedAt           *time.Time `bun:"used_at"`
	UsedByAgentUID   *string    `bun:"used_by_agent_uid"`
	CreatedByUserUID *string    `bun:"created_by_user_uid"`
	CreatedAt        time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	DeletedAt        *time.Time `bun:"deleted_at"`
}

type AgentNonce struct {
	AgentUID string    `bun:"agent_uid,pk"`
	Nonce    string    `bun:"nonce,pk"`
	SeenAt   time.Time `bun:"seen_at,notnull"`
}

type AggregateResultsFunc func(sources []*Result) (rollup *Result, sourceUIDs []string, err error)

type AppSetting struct {
	Key       string    `bun:"key,pk,type:text"`
	Value     string    `bun:"value,notnull,type:text"`
	UpdatedAt time.Time `bun:"updated_at,notnull,default:current_timestamp"`
}

type AutoResolvePolicy string

type AvailabilityCounts struct {
	Success int64
	Total   int64
}

type AvailabilitySettings struct {
	// ThresholdUp is the green floor (pct >= this renders "up"). nil = 99.9.
	ThresholdUp *float64 `json:"thresholdUp,omitempty"`
	// ThresholdDegraded is the amber floor (pct >= this and < ThresholdUp
	// renders "degraded"; below it renders "down", subject to the
	// small-bucket calibration guard). nil = 99.0.
	ThresholdDegraded *float64 `json:"thresholdDegraded,omitempty"`
}

type BrandingSettings struct {
	// LogoFileUID is the `files.uid` of the page's own logo. nil = wear the
	// SolidPing logo.
	LogoFileUID *string `json:"logoFileUid,omitempty"`
	// FaviconFileUID is the `files.uid` of the page's own favicon. nil = the
	// default favicon.
	FaviconFileUID *string `json:"faviconFileUid,omitempty"`
	// HideBranding is the page's HALF of the white-label decision: the
	// "powered by SolidPing" footer disappears only when this is true AND the
	// org holds the `whiteLabel` entitlement. Keeping the two halves separate
	// means a downgrade silently restores the badge without rewriting the page.
	HideBranding bool `json:"hideBranding,omitempty"`
}

type Capabilities struct {
	// CanNotify reports whether the integration can receive outbound
	// notifications (i.e. it can act as a "channel" / notification target).
	CanNotify bool
	// CanSource reports whether the integration provides data that checks
	// read from (e.g. the Freebox line-quality source).
	CanSource bool
	// CanSendSMS / CanPlaceCall report the two PHONE capabilities, resolved
	// independently of each other. They are separate because the providers
	// are: OVHcloud sells SMS but has no voice API, so an instance can run OVH
	// for SMS and Twilio for voice at the same time. Binding them would mean
	// giving up escalation calls in exchange for cheaper SMS.
	CanSendSMS   bool
	CanPlaceCall bool
}

type CapabilityState uint8

type Check struct {
	UID             string  `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string  `bun:"organization_uid,notnull"`
	CheckGroupUID   *string `bun:"check_group_uid"`
	Name            *string `bun:"name"`
	Slug            *string `bun:"slug"`
	Description     *string `bun:"description"`
	Type            string  `bun:"type,notnull"`
	Config          JSONMap `bun:"config,type:jsonb,nullzero"`
	// ConfigPrivate holds the AES-GCM envelope (JSON) for the secret keys
	// split out of Config at write time. NULL when no encrypted secrets exist
	// on this row — distinct from "encryption disabled at the server".
	ConfigPrivate *string `bun:"config_private,type:text,nullzero"`
	// ConfigPrivateKeys is a JSON array of the key names (e.g. `["password"]`)
	// whose values live in ConfigPrivate. Non-secret by construction; surfaced
	// to the dashboard so it can render placeholder hints without decrypting.
	ConfigPrivateKeys *string `bun:"config_private_keys,type:text,nullzero"`
	// ConfigSealed holds the region-sealed (age X25519, v2) envelope of the same
	// secret keys when the check targets one or more org-private regions (spec
	// 2026-07-16-02): sealed to the X25519 keys of the region's active agents.
	// A check targeting ONLY private regions stores secrets sealed-only
	// (ConfigPrivate stays NULL — the server cannot decrypt them after write);
	// a mixed private+cloud check dual-stores (v1 envelope for cloud dispatch +
	// this sealed blob for agents).
	ConfigSealed *string            `bun:"config_sealed,type:text,nullzero"`
	Regions      []string           `bun:"regions,type:text[],array"`
	Enabled      bool               `bun:"enabled,notnull"`
	Internal     bool               `bun:"internal,notnull"`
	Period       timeutils.Duration `bun:"period,notnull"`

	// CreatedBy is the users.uid of whoever created this check, or NULL when
	// nobody did — the startup job's seeded samples, and every check that
	// predates the column (spec 2026-09-06-02). It is recorded for EVERY
	// creator, not only demo sessions: "who made this" is useful audit data in
	// its own right, and a column populated on one code path only is a column
	// nobody can trust.
	//
	// Deliberately not a foreign key: a check outlives the account that made
	// it, and users are soft-deleted. This is a historical attribution.
	//
	// It is also what makes seeded demo checks immutable to a demo session
	// without any "protected" flag: the ownership rule is
	// `created_by == claims.UserUID`, and NULL never equals a UID.
	CreatedBy *string `bun:"created_by,nullzero"`

	// RegionSpread is the optional inter-region scheduling offset ("spread")
	// applied between consecutive regions' phases (spec 2026-07-20-05). NULL =
	// the default of Period / region_count (even coverage across the period);
	// a non-null value forces a fixed offset (e.g. 0 = all regions fire
	// together for comparative cross-region sampling), validated
	// 0 <= RegionSpread < Period. It is a first-class scheduling input (it
	// drives check_jobs phase), not checker config, hence a column like Period.
	RegionSpread *timeutils.Duration `bun:"region_spread,nullzero"`

	// Incident tracking — wall-clock periods (seconds). Replaces the old
	// count-based thresholds per spec
	// 2026-05-08-02-time-based-confirmation-and-recovery-periods.md.
	// `0` means "open / resolve immediately on the first opposite signal".
	ConfirmationPeriodSeconds int `bun:"confirmation_period_seconds,notnull"`
	RecoveryPeriodSeconds     int `bun:"recovery_period_seconds,notnull"`
	// EscalationThreshold remains streak-based for now — it gates the *second*
	// notification step, not the incident open. Will be re-modeled when the
	// escalation-severity primitive ships. No `default:` clause even though
	// the column has one — see the StatusPage.AutoPublishDelaySeconds note:
	// `default:3` made `escalation_threshold: 0` unwritable on create.
	EscalationThreshold int `bun:"escalation_threshold,notnull"`
	// FirstFailureAt is set on the result that flips the streak from 0 to 1
	// on a failing check (no active incident yet). Cleared on the next success.
	// The incident opens when now - FirstFailureAt >= ConfirmationPeriod.
	FirstFailureAt *time.Time `bun:"first_failure_at"`
	// FirstSuccessSinceFailureAt is set on the first success arriving while
	// an incident is open. Cleared by any subsequent failure during the
	// recovery window. Auto-resolve fires when
	// now - FirstSuccessSinceFailureAt >= RecoveryPeriod.
	FirstSuccessSinceFailureAt *time.Time `bun:"first_success_since_failure_at"`

	// Adaptive resolution settings.
	//
	// ReopenCooldownMultiplier (nil = code default) drives the short
	// blip-dedup window: a fast relapse reattaches to the just-resolved
	// incident instead of paging again. Independent of the flapping layer.
	ReopenCooldownMultiplier *int `bun:"reopen_cooldown_multiplier"`

	// Flapping (adaptive recovery) config — spec 2026-06-30-07. When a check
	// flaps (repeated outages over a short horizon) the required stability
	// before auto-resolving grows per flap, bounded by a cap. Off-by-default-
	// equivalent: FlapBackoffFactor==1 or FlappingWindowSeconds==0 reproduces
	// the constant RecoveryPeriodSeconds behavior.
	//
	// Which is precisely why none of the three carries a `default:` clause,
	// even though all three columns have one — see the
	// StatusPage.AutoPublishDelaySeconds note. With `default:21600` on the tag,
	// `flappingWindowSeconds: 0` never reached the database, so flapping could
	// not be turned off at creation time (spec 2026-08-30-04). NewCheck
	// supplies the 21600/2/8 defaults instead.
	FlappingWindowSeconds int `bun:"flapping_window_seconds,notnull"`
	FlapBackoffFactor     int `bun:"flap_backoff_factor,notnull"`
	MaxRecoveryMultiplier int `bun:"max_recovery_multiplier,notnull"`

	// Flap state, updated only on the rare incident-open/reopen (never per
	// result). FlapCount is the number of outages accumulated inside the
	// rolling flapping window; LastOutageAt is the wall-clock of the most
	// recent outage onset and gates the window reset.
	FlapCount    int        `bun:"flap_count,notnull"`
	LastOutageAt *time.Time `bun:"last_outage_at"`

	// Optional escalation policy. Falls back to the check_group's policy
	// (and ultimately to no escalation) when nil.
	EscalationPolicyUID *string `bun:"escalation_policy_uid"`

	// TracerouteOnFailure is the per-check override for the MTR-style path
	// capture taken when this check goes down on a network-reachability
	// failure (spec 2026-08-21-10).
	//
	// THREE STATES, AND nil IS THE INTERESTING ONE:
	//
	//	nil     inherit the org default (org parameter
	//	        `diagnostics.traceroute.enabled`, itself ON per the spec)
	//	&true   always trace this check
	//	&false  never trace this check, whatever the org default says
	//
	// A plain bool would collapse "not decided" into "no", which would make
	// the org-level default unreachable for every check that already exists.
	TracerouteOnFailure *bool `bun:"traceroute_on_failure"`

	// Status tracking
	Status          CheckStatus `bun:"status,notnull"`
	StatusStreak    int         `bun:"status_streak,notnull"`
	StatusChangedAt *time.Time  `bun:"status_changed_at"`

	CreatedAt time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt time.Time  `bun:"updated_at,notnull,default:current_timestamp"`
	DeletedAt *time.Time `bun:"deleted_at"`

	// GroupSortKey is the effective group-ordering key populated only by the
	// sort=group ListChecks path: the check's group sort_order, or a large
	// sentinel (int16 max is 32767, so ungrouped sorts strictly last). Scan-only
	// and transient — never selected, inserted, or updated outside that query.
	GroupSortKey int64 `bun:"group_sort_key,scanonly"`

	// TargetHostSortKey is the effective sort=targetHost ordering key: the
	// check's config host/url/target text (best-effort, not hostname-parsed —
	// see targetHostSortKeyExpr), or a sentinel that sorts strictly last for
	// checks with none of those fields. Scan-only and transient; distinct from
	// the response's TargetHost (checkerdef.ExtractTargetHost), which is the
	// precise, hostname-parsed value clients bucket by.
	TargetHostSortKey string `bun:"target_host_sort_key,scanonly"`
}

type CheckConnection struct {
	bun.BaseModel `bun:"table:check_channels,alias:check_channel"`

	UID             string    `bun:"uid,pk,type:varchar(36)"`
	CheckUID        string    `bun:"check_uid,notnull"`
	ConnectionUID   string    `bun:"integration_uid,notnull"`
	OrganizationUID string    `bun:"organization_uid,notnull"`
	Settings        *JSONMap  `bun:"settings,type:jsonb"`
	CreatedAt       time.Time `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt       time.Time `bun:"updated_at,notnull,default:current_timestamp"`

	// Relations (optional, for eager loading)
	Check        *Check        `bun:"rel:belongs-to,join:check_uid=uid"`
	Connection   *Integration  `bun:"rel:belongs-to,join:integration_uid=uid"`
	Organization *Organization `bun:"rel:belongs-to,join:organization_uid=uid"`
}

type CheckConnectionUpdate struct {
	Settings *JSONMap
}

type CheckDependency struct {
	UID             string              `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string              `bun:"organization_uid,notnull"`
	ParentCheckUID  string              `bun:"parent_check_uid,notnull"`
	ChildCheckUID   string              `bun:"child_check_uid,notnull"`
	Kind            CheckDependencyKind `bun:"kind,notnull"`
	Description     *string             `bun:"description"`
	CreatedAt       time.Time           `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt       time.Time           `bun:"updated_at,notnull,default:current_timestamp"`
	DeletedAt       *time.Time          `bun:"deleted_at"`
}

type CheckDependencyKind string

type CheckDependencyUpdate struct {
	Kind             *CheckDependencyKind
	Description      *string
	ClearDescription bool
}

type CheckGroup struct {
	UID             string  `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string  `bun:"organization_uid,notnull"`
	Name            string  `bun:"name,notnull"`
	Slug            string  `bun:"slug,notnull"`
	Description     *string `bun:"description"`
	SortOrder       int16   `bun:"sort_order,notnull"`
	// Optional escalation policy. NULL = no group-level policy.
	EscalationPolicyUID *string    `bun:"escalation_policy_uid"`
	CreatedAt           time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt           time.Time  `bun:"updated_at,notnull,default:current_timestamp"`
	DeletedAt           *time.Time `bun:"deleted_at"`

	// Computed field (not stored in DB)
	CheckCount int `bun:"check_count,scanonly"`
}

type CheckGroupUpdate struct {
	Name                *string
	Slug                *string
	Description         *string
	SortOrder           *int16
	EscalationPolicyUID *string

	ClearEscalationPolicyUID bool
}

type CheckJob struct {
	UID             string  `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string  `bun:"organization_uid,notnull"`
	CheckUID        string  `bun:"check_uid"`
	Region          *string `bun:"region"`
	Type            string  `bun:"type"`
	Config          JSONMap `bun:"config,type:jsonb,nullzero"`
	// ConfigPrivate / ConfigPrivateKeys mirror the columns on Check — the
	// scheduler copies them when materializing a job so workers never see
	// plaintext secrets in the row at rest.
	ConfigPrivate     *string `bun:"config_private,type:text,nullzero"`
	ConfigPrivateKeys *string `bun:"config_private_keys,type:text,nullzero"`
	// ConfigSealed mirrors Check.ConfigSealed: the region-sealed (age X25519)
	// envelope shipped VERBATIM to deported agents — the server never decrypts
	// it on the agent dispatch path (spec 2026-07-16-02).
	ConfigSealed   *string            `bun:"config_sealed,type:text,nullzero"`
	Encrypted      bool               `bun:"encrypted,notnull"`
	Period         timeutils.Duration `bun:"period,notnull"`
	ScheduledAt    *time.Time         `bun:"scheduled_at"`
	LeaseWorkerUID *string            `bun:"lease_worker_uid"`
	LeaseExpiresAt *time.Time         `bun:"lease_expires_at"`
	LeaseStarts    int                `bun:"lease_starts,notnull"`
	UpdatedAt      time.Time          `bun:"updated_at,notnull,default:current_timestamp"`

	// Cost-aware, plan-weighted scheduling (spec 2026-06-30-09).
	//
	// CostEWMAMs is an exponentially-weighted moving average of execution
	// duration in milliseconds, updated in the post-exec write (ReleaseLease).
	// Timeouts pin it to the ceiling. Drives slow-lane classification and the
	// cost-aware execution timeout. 0 until the job's first run.
	CostEWMAMs float64 `bun:"cost_ewma_ms,notnull"`
	// DelayEWMAMs is an EWMA of how late the job actually started relative to
	// its real scheduled_at (probe start − scheduled_at, floored at 0), updated
	// in the post-exec write. Pure telemetry (spec 2026-07-01-02): it feeds the
	// cost-distribution endpoint and the lane-split go/no-go but never the claim
	// order — delay is a victim signal, and folding it into the offset punished
	// starved checks and spiraled unboundedly under overload. 0 until the job's
	// first run. Added by migration 007.
	DelayEWMAMs float64 `bun:"delay_ewma_ms,notnull"`
	// PlanWeight is the denormalized plan tier copied from org_entitlements
	// (0 = free; higher = more protected). Reserved capacity + deadline credit
	// for paid orgs. Refreshed on entitlement change and reconcile.
	PlanWeight int `bun:"plan_weight,notnull"`
	// EffectiveScheduledAt is scheduled_at + cost_ewma×CostOffsetWeight −
	// tier_credit, with the offset clamped to scheduling.MaxDeprioritizeOffset.
	// The claim SELECT gates on scheduled_at but orders by this column, so
	// de-prioritization only bites under contention (D2/Option A). Backfilled to
	// scheduled_at by migration 006; delay-era offsets healed by migration 008.
	//
	// A rate-limited deferral deliberately does NOT re-anchor this column
	// (checkjobsvc.DeferLeaseRateLimited, spec 2026-08-26-02): a job the per-org
	// bucket turned away keeps the tick it missed as its ordering key, so it
	// grows more overdue every window it loses and wins the next contended slot.
	// That is what makes an over-cap org rotate its deficit instead of starving
	// the same UID-hash phases forever.
	EffectiveScheduledAt *time.Time `bun:"effective_scheduled_at"`
	// Lane is the scheduling class (spec 2026-07-01-03): 0 = fast, 1 = slow
	// (scheduling.LaneFast / LaneSlow). Classified from the cost EWMA with
	// hysteresis in the post-exec write; new rows start fast (first run is
	// FIFO; one execution reclassifies). The claim runs two lane-filtered
	// SELECTs so slow jobs can never occupy more than pool_size −
	// fast_lane_reserved slots on a worker. Added by migration 009.
	Lane uint8 `bun:"lane,notnull"`

	// Check is the check this job executes, populated at claim time by
	// ClaimJobs / ClaimJobsForCheck so the incident hot path can skip a
	// per-result GetCheck round-trip. Transient: never persisted (bun:"-").
	// May be nil if the check was deleted between scheduling and claim.
	Check *Check `bun:"-"`
}

type CheckJobUpdate struct {
	Region            *string
	Config            *JSONMap
	ConfigPrivate     *string
	ConfigPrivateKeys *string
	Encrypted         *bool
	Period            *timeutils.Duration
	ScheduledAt       *time.Time
	LeaseWorkerUID    *string
	LeaseExpiresAt    *time.Time
	LeaseStarts       *int
}

type CheckLabel struct {
	UID       string    `bun:"uid,pk,type:varchar(36)"`
	CheckUID  string    `bun:"check_uid,notnull"`
	LabelUID  string    `bun:"label_uid,notnull"`
	CreatedAt time.Time `bun:"created_at,notnull,default:current_timestamp"`
}

type CheckRate struct {
	// UID identifies the row so a caller can project a hypothetical change:
	// drop the check being edited out of the sum and add its proposed shape
	// back (spec 2026-08-26-05's validate-time rate warning).
	UID     string             `bun:"uid"`
	Enabled bool               `bun:"enabled"`
	Period  timeutils.Duration `bun:"period"`
	Regions []string           `bun:"regions,type:text[],array"`
	Type    string             `bun:"type"`
}

type CheckStatus int

type CheckStatusCount struct {
	Status  CheckStatus `bun:"status"`
	Enabled bool        `bun:"enabled"`
	Count   int         `bun:"count"`
}

type CheckUpdate struct {
	CheckGroupUID      *string
	Name               *string
	Slug               *string
	Description        *string
	Type               *string
	Config             *JSONMap
	ConfigPrivate      *string
	ConfigPrivateKeys  *string
	ClearConfigPrivate bool
	ConfigSealed       *string
	ClearConfigSealed  bool
	Regions            *[]string
	Enabled            *bool
	Internal           *bool
	Period             *timeutils.Duration
	// RegionSpread sets the inter-region offset override; ClearRegionSpread
	// resets it to NULL (revert to the period/region_count default).
	RegionSpread      *timeutils.Duration
	ClearRegionSpread bool

	// Incident tracking — wall-clock periods replacing the legacy count
	// thresholds. EscalationThreshold stays count-based for now.
	ConfirmationPeriodSeconds *int
	RecoveryPeriodSeconds     *int
	EscalationThreshold       *int

	// FirstFailureAt / FirstSuccessSinceFailureAt drive the open/resolve
	// clocks; ProcessCheckResult sets/clears them as the streak signal flips.
	FirstFailureAt                  *time.Time
	FirstSuccessSinceFailureAt      *time.Time
	ClearFirstFailureAt             bool
	ClearFirstSuccessSinceFailureAt bool

	// Adaptive resolution settings
	ReopenCooldownMultiplier *int

	// Flapping (adaptive recovery) config — spec 2026-06-30-07.
	FlappingWindowSeconds *int
	FlapBackoffFactor     *int
	MaxRecoveryMultiplier *int

	// Optional escalation policy override (nil = inherit from group / none)
	EscalationPolicyUID *string

	// TracerouteOnFailure sets the per-check path-trace override;
	// ClearTracerouteOnFailure resets it to NULL (inherit the org default).
	TracerouteOnFailure      *bool
	ClearTracerouteOnFailure bool

	// Clear* fields set the corresponding column to NULL on update.
	ClearEscalationPolicyUID bool

	// Status tracking (internal use)
	Status          *CheckStatus
	StatusStreak    *int
	StatusChangedAt *time.Time
}

type CompactResultsOutcome struct {
	// Fetched is the number of source rows read for the bucket.
	Fetched int
	// SourceCount is the number of measurable source rows the aggregate function
	// selected for deletion (its returned sourceUIDs). Zero for a marker-only
	// bucket.
	SourceCount int
	// Compacted is true when the rollup row was upserted and the source rows
	// deleted (the whole transaction committed). False when there was nothing to
	// compact (no fetched rows, or a marker-only bucket).
	Compacted bool
	// DeletedCount is the number of source rows actually deleted.
	DeletedCount int64
}

type ConnectionType string

type DeliveryDetails struct {
	// HTTPStatusCode is the HTTP response status (e.g. 200, 503). Zero/omitted
	// for non-HTTP channels or when no response was received.
	HTTPStatusCode int `json:"httpStatusCode,omitempty"`
	// RequestURL is the target URL with the query string and any credentials
	// stripped (host + path only). Never the raw URL.
	RequestURL string `json:"requestUrl,omitempty"`
	// RequestBody is the payload sent to the receiver, capped at
	// DeliveryDetailsBodyCap bytes.
	RequestBody string `json:"requestBody,omitempty"`
	// ResponseBody is the receiver's response body, capped at
	// DeliveryDetailsBodyCap bytes.
	ResponseBody string `json:"responseBody,omitempty"`
	// DurationMs is the wall-clock time of the delivery attempt in milliseconds.
	DurationMs int64 `json:"durationMs,omitempty"`
	// ResponseHeaders is a small allowlisted set of response headers (e.g.
	// Retry-After, Content-Type). Never carries request-side secret headers.
	ResponseHeaders map[string]string `json:"responseHeaders,omitempty"`
}

type DeviceAuthRequest struct {
	bun.BaseModel `bun:"table:device_auth_requests,alias:device_auth_request"`

	UID             string     `bun:"uid,pk,type:varchar(36)"`
	DeviceCode      string     `bun:"device_code,notnull"`
	UserCode        string     `bun:"user_code,notnull"`
	ClientName      string     `bun:"client_name,notnull"`
	Status          string     `bun:"status,notnull"`
	OrganizationUID *string    `bun:"organization_uid"`
	UserUID         *string    `bun:"user_uid"`
	TokenUID        *string    `bun:"token_uid"`
	TokenValue      *string    `bun:"token_value"`
	LastPolledAt    *time.Time `bun:"last_polled_at"`
	ExpiresAt       time.Time  `bun:"expires_at,notnull"`
	CreatedAt       time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt       time.Time  `bun:"updated_at,notnull,default:current_timestamp"`
}

type DeviceAuthResolution struct {
	Status          string
	UserUID         string
	OrganizationUID string
	TokenUID        string
	TokenValue      string
}

type DiscordSettings struct {
	// WebhookURL is the legacy, one-way mode. Kept first and unchanged so a
	// pre-bot row decodes exactly as it always did.
	WebhookURL string `json:"webhook_url,omitempty"`

	// GuildID / GuildName identify the Discord server the bot was installed
	// into. GuildID is the identity the org mapping is keyed on (see
	// organization_providers, ProviderTypeDiscord).
	GuildID   string `json:"guild_id,omitempty"`
	GuildName string `json:"guild_name,omitempty"`

	// BotUserID is the application's own user id inside the guild, used to
	// recognize "this message is ours" on the Gateway.
	BotUserID string `json:"bot_user_id,omitempty"`

	// ChannelID / ChannelName are the default notification destination — the
	// Discord counterpart of SlackSettings.ChannelID.
	ChannelID   string `json:"channel_id,omitempty"`
	ChannelName string `json:"channel_name,omitempty"`

	// InstalledByUserID records the Discord user who performed the install.
	InstalledByUserID string `json:"installed_by_user_id,omitempty"`

	// MentionOnCall makes channel alerts ping the humans the escalation policy
	// would page first (`<@123>`). Zero value is deliberately false so every
	// integration stored before this field existed keeps behaving exactly as
	// before; the bot install flow writes `true` explicitly for new installs.
	MentionOnCall bool `json:"mention_on_call,omitempty"`

	// CommentIngestion selects how inbound Discord thread replies are treated,
	// with the same explicit/all semantics as SlackSettings.CommentIngestion.
	// Zero value ("") means explicit — the safe direction.
	CommentIngestion string `json:"comment_ingestion,omitempty"`
}

type DiscoveredCheck struct {
	UID                string          `bun:"uid,pk,type:varchar(36)"                         json:"uid"`
	OrganizationUID    string          `bun:"organization_uid,notnull"                        json:"organizationUid"`
	JobUID             string          `bun:"job_uid,notnull"                                 json:"jobUid"`
	Source             DiscoverySource `bun:"source,notnull"                                  json:"source"`
	GroupKey           string          `bun:"group_key,notnull"                               json:"groupKey"`
	GroupLabel         string          `bun:"group_label,notnull"                             json:"groupLabel"`
	Name               string          `bun:"name,notnull"                                    json:"name"`
	Slug               string          `bun:"slug,notnull"                                    json:"slug"`
	Type               string          `bun:"type,notnull"                                    json:"type"`
	Config             json.RawMessage `bun:"config,type:jsonb"                               json:"config"`
	Metadata           json.RawMessage `bun:"metadata,type:jsonb"                             json:"metadata,omitempty"`
	PromotedToCheckUID *string         `bun:"promoted_to_check_uid"                           json:"promotedToCheckUid,omitempty"` //nolint:lll // aligned tag width
	DiscoveredAt       time.Time       `bun:"discovered_at,notnull,default:current_timestamp" json:"discoveredAt"`
	CreatedAt          time.Time       `bun:"created_at,notnull,default:current_timestamp"    json:"createdAt"`
	UpdatedAt          time.Time       `bun:"updated_at,notnull,default:current_timestamp"    json:"updatedAt"`
	DeletedAt          *time.Time      `bun:"deleted_at,soft_delete"                          json:"deletedAt,omitempty"`
}

type DiscoverySource string

type EmailSuppression struct {
	bun.BaseModel `bun:"table:email_suppressions,alias:email_suppression"`

	UID             string    `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string    `bun:"organization_uid,notnull"`
	Email           string    `bun:"email,notnull"`
	CheckUID        *string   `bun:"check_uid"` // NULL = suppresses all checks in the org
	Source          string    `bun:"source,notnull"`
	CreatedAt       time.Time `bun:"created_at,notnull,default:current_timestamp"`
}

type EntitlementLimits struct {
	MaxChecks          *int `json:"maxChecks,omitempty"`
	MaxUsers           *int `json:"maxUsers,omitempty"`
	MaxChecksPerMinute *int `json:"maxChecksPerMinute,omitempty"`
	// MaxDeportedAgents caps the org's active deported (private-location)
	// agents across all private regions. nil = unlimited.
	MaxDeportedAgents *int `json:"maxDeportedAgents,omitempty"`
	// MaxCustomDomains caps the org's status pages served on a customer-owned
	// domain. nil = unlimited (self-hosted default); SaaS defaults to 0 and
	// billing raises it per plan.
	MaxCustomDomains *int `json:"maxCustomDomains,omitempty"`
	// MaxSmsPerMonth / MaxCallsPerMonth cap the org's outbound SMS and voice
	// calls per UTC calendar month. nil = unlimited (self-hosted default,
	// bring-your-own Twilio); SaaS defaults to 0 and billing raises it per plan.
	MaxSmsPerMonth   *int `json:"maxSmsPerMonth,omitempty"`
	MaxCallsPerMonth *int `json:"maxCallsPerMonth,omitempty"`
	// MaxWhatsappPerMonth caps the org's outbound WhatsApp template messages
	// per UTC calendar month. nil = unlimited (self-hosted default, the
	// operator brings their own WABA); SaaS defaults to 0 and billing raises
	// it per plan.
	MaxWhatsappPerMonth *int `json:"maxWhatsappPerMonth,omitempty"`
	// MaxSlos caps the org's service-level objectives (spec 2026-08-20-01).
	// nil = unlimited (self-hosted default); SaaS defaults to 2 and billing
	// raises it per plan.
	MaxSlos *int `json:"maxSlos,omitempty"`
	// WhiteLabel is the one non-numeric entitlement: whether the org may drop
	// the "powered by SolidPing" badge from its status pages (spec
	// 2026-08-21-07). It lives here rather than in a sibling struct because
	// this IS the entitlement payload billing writes, and splitting the shape
	// in two would mean a second wire contract to rotate.
	//
	// nil means "use the deployment default" — true self-hosted (nobody should
	// have to pay to unbrand their own instance), false on the SaaS, where
	// paying is what unlocks it. Note the asymmetry with the *int fields: nil
	// there means UNLIMITED, here it means DEFAULT, because a boolean has no
	// "unbounded" reading.
	WhiteLabel *bool `json:"whiteLabel,omitempty"`
}

type EntitlementSource string

type EntitlementsPayload struct {
	Version int               `json:"version"`
	Source  EntitlementSource `json:"source,omitempty"`
	Limits  EntitlementLimits `json:"limits"`
	// DisplayName / DisplayEmoji are billing-supplied plan identity, shown
	// in the dashboard (e.g. "🚀 Team"). Display-only — never enforced.
	DisplayName  *string `json:"displayName,omitempty"`
	DisplayEmoji *string `json:"displayEmoji,omitempty"`
}

type EscalationPolicy struct {
	UID                string     `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID    string     `bun:"organization_uid,notnull"`
	Name               string     `bun:"name,notnull"`
	Description        *string    `bun:"description"`
	RepeatMax          int        `bun:"repeat_max,notnull"`
	RepeatAfterSeconds *int       `bun:"repeat_after_seconds"`
	CreatedAt          time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt          time.Time  `bun:"updated_at,notnull,default:current_timestamp"`
	DeletedAt          *time.Time `bun:"deleted_at"`
}

type EscalationPolicyStep struct {
	UID          string `bun:"uid,pk,type:varchar(36)"`
	PolicyUID    string `bun:"policy_uid,notnull"`
	Position     int    `bun:"position,notnull"`
	DelaySeconds int    `bun:"delay_seconds,notnull"`
	// SeverityUID points to the severity that decides the channel-set
	// for this step. NULL = "fall back to the org default severity for
	// user/all_admins targets, or the connection's own channel for
	// connection targets". Spec 2026-05-08-03.
	SeverityUID *string   `bun:"severity_uid"`
	CreatedAt   time.Time `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt   time.Time `bun:"updated_at,notnull,default:current_timestamp"`
}

type EscalationPolicyTarget struct {
	UID        string               `bun:"uid,pk,type:varchar(36)"`
	StepUID    string               `bun:"step_uid,notnull"`
	TargetType EscalationTargetType `bun:"target_type,notnull"`
	TargetUID  *string              `bun:"target_uid"`
	Position   int                  `bun:"position,notnull"`
}

type EscalationPolicyUpdate struct {
	Name               *string
	Description        *string
	RepeatMax          *int
	RepeatAfterSeconds *int

	ClearDescription        bool
	ClearRepeatAfterSeconds bool
}

type EscalationTargetType string

type Event struct {
	UID             string    `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string    `bun:"organization_uid,notnull"`
	IncidentUID     *string   `bun:"incident_uid"`
	CheckUID        *string   `bun:"check_uid"`
	JobUID          *string   `bun:"job_uid"`
	EventType       EventType `bun:"event_type,notnull"`
	ActorType       ActorType `bun:"actor_type,notnull"`
	// ActorUID is the acting user's UID — this column IS the spec's
	// `actor_user_uid` (2026-08-21-09). It predates that spec as an FK to
	// users(uid); a second column of the same meaning would only create a
	// split brain, so the API exposes it under the `actorUserUid` parameter
	// name while the column keeps its original name.
	ActorUID *string `bun:"actor_uid"`
	Payload  JSONMap `bun:"payload,type:jsonb,nullzero"`
	// SourceIP is the client address the action came from, when the request
	// had one and audit.capture_ip is on. Nil for system-originated events and
	// for deployments that turned IP capture off for GDPR reasons.
	SourceIP *string `bun:"source_ip"`
	// UserAgent is the raw User-Agent header, truncated. Nil when absent.
	UserAgent *string   `bun:"user_agent"`
	CreatedAt time.Time `bun:"created_at,notnull,default:current_timestamp"`
}

type EventType string

type File struct {
	UID             string     `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string     `bun:"organization_uid,notnull"`
	Name            string     `bun:"name,notnull"`
	MimeType        string     `bun:"mime_type,notnull"`
	Size            int64      `bun:"size,notnull"`
	FileURI         string     `bun:"file_uri,notnull"`
	SHA256          *string    `bun:"sha256"`
	CreatedBy       *string    `bun:"created_by"`
	CreatedAt       time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	DeletedAt       *time.Time `bun:"deleted_at"`

	// Topic is the ATTACHMENT KEY (spec 2026-08-21-01): a path-like
	// `<entity>/<uid>/<kind>`, e.g.
	// `incidents/9a1eb273-0a95-4d6b-b967-9af076c1f8e8/screenshot`.
	//
	// NIL IS THE NORM. A file that is not an attachment — an org logo, a
	// feedback screenshot — carries no topic and is invisible to every
	// attachment query. The path shape is what makes both accesses cheap on
	// one index: an exact match lists one entity's attachments of one kind, a
	// prefix match reaps everything hanging off an entity when it is deleted.
	Topic *string `bun:"topic"`

	// Details is a free metadata bag for the attachment kind — for a
	// screenshot: capturedAt, region, checkUid, trigger. Unconstrained on
	// purpose so the next attachment kind needs no migration.
	//
	// SECURITY: operator-facing evidence, exactly like incidents.details. It
	// must never be serialized onto a public surface.
	Details JSONMap `bun:"details,type:jsonb,nullzero"`
}

type FreeboxPrivateSettings struct {
	AppToken string `json:"appToken"`
}

type FreeboxSettings struct {
	BaseURL    string `json:"baseUrl"`              // e.g. "http://mafreebox.freebox.fr"
	AppID      string `json:"appId"`                // "io.solidping"
	DeviceName string `json:"deviceName,omitempty"` // user-visible label on the Freebox admin
	TrackID    int    `json:"trackId,omitempty"`    // only set while pairing; cleared on grant
	Status     string `json:"status,omitempty"`     // pairing | granted | denied | timeout
}

type Incident struct {
	UID string `bun:"uid,pk,type:varchar(36)"`
	// Number is the short, per-org, monotonically increasing reference rendered
	// as `#42` in the dashboard, Slack and Telegram. Nobody types a 36-char UUID
	// into a chat on a phone, so every human-facing surface addresses an
	// incident by this instead. Assigned once at creation and never reused —
	// soft-deleted incidents keep theirs.
	Number          int64         `bun:"number,notnull"`
	OrganizationUID string        `bun:"organization_uid,notnull"`
	CheckUID        string        `bun:"check_uid,notnull"`
	Region          *string       `bun:"region"`
	State           IncidentState `bun:"state,notnull"`
	StartedAt       time.Time     `bun:"started_at,notnull"`
	ResolvedAt      *time.Time    `bun:"resolved_at"`
	ResolvedBy      *string       `bun:"resolved_by"`
	ResolutionType  *string       `bun:"resolution_type"`
	EscalatedAt     *time.Time    `bun:"escalated_at"`
	AcknowledgedAt  *time.Time    `bun:"acknowledged_at"`
	AcknowledgedBy  *string       `bun:"acknowledged_by"`
	SnoozedUntil    *time.Time    `bun:"snoozed_until"`
	SnoozedBy       *string       `bun:"snoozed_by"`
	SnoozeReason    *string       `bun:"snooze_reason"`
	FailureCount    int           `bun:"failure_count,notnull"`
	RelapseCount    int           `bun:"relapse_count,notnull"`
	// FlapLevel is the check's FlapCount at the moment this incident opened
	// or last reopened (spec 2026-08-24-05) — the "at what flap level did
	// this page fire" record. 0 = not flapping (first outage in the rolling
	// window). Unlike checks.flap_count this is a point-in-time snapshot, not
	// a live value, so it never needs lazy-reset handling.
	FlapLevel      int        `bun:"flap_level,notnull"`
	LastReopenedAt *time.Time `bun:"last_reopened_at"`
	Title          *string    `bun:"title"`
	Description    *string    `bun:"description"`
	Details        JSONMap    `bun:"details,type:jsonb,nullzero"`
	// CheckGroupUID is set on group incidents — NULL keeps the existing per-check semantics.
	CheckGroupUID *string `bun:"check_group_uid"`
	// CausedByIncidentUID points to the root-cause incident this one was rolled up under.
	CausedByIncidentUID *string `bun:"caused_by_incident_uid"`
	// PagingSuppressed gates notifications and escalation: TRUE = skip.
	PagingSuppressed bool `bun:"paging_suppressed,notnull"`
	// Kind is IncidentKindCheck or IncidentKindSLOBurn.
	Kind string `bun:"kind,notnull"`
	// SLOUID / SLOAlertPolicyUID bind a burn incident to what produced it.
	// Both are NULL on a check incident. Both are `on delete set null`: losing
	// the SLO must not erase the record of the pages it sent.
	SLOUID            *string    `bun:"slo_uid"`
	SLOAlertPolicyUID *string    `bun:"slo_alert_policy_uid"`
	CreatedAt         time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt         time.Time  `bun:"updated_at,notnull,default:current_timestamp"`
	DeletedAt         *time.Time `bun:"deleted_at"`
}

type IncidentClockUpdate struct {
	FirstFailureAt                  *time.Time
	ClearFirstFailureAt             bool
	FirstSuccessSinceFailureAt      *time.Time
	ClearFirstSuccessSinceFailureAt bool
}

type IncidentMemberCheck struct {
	IncidentUID    string     `bun:"incident_uid,pk"`
	CheckUID       string     `bun:"check_uid,pk"`
	JoinedAt       time.Time  `bun:"joined_at,notnull,default:current_timestamp"`
	FirstFailureAt time.Time  `bun:"first_failure_at,notnull"`
	LastFailureAt  time.Time  `bun:"last_failure_at,notnull"`
	LastRecoveryAt *time.Time `bun:"last_recovery_at"`
	FailureCount   int        `bun:"failure_count,notnull"`
	// No `default:true` on the tag even though the column has one — see the
	// StatusPage.AutoPublishDelaySeconds note. A member row that is inserted
	// already recovered is legal, and the tag silently rewrote it to failing.
	CurrentlyFailing bool `bun:"currently_failing,notnull"`
}

type IncidentMemberUpdate struct {
	LastFailureAt    *time.Time
	LastRecoveryAt   *time.Time
	FailureCount     *int
	CurrentlyFailing *bool
}

type IncidentNotification struct {
	bun.BaseModel `bun:"table:incident_notifications"`

	UID             string  `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string  `bun:"organization_uid,notnull,type:varchar(36)"`
	IncidentUID     string  `bun:"incident_uid,notnull,type:varchar(36)"`
	EventType       string  `bun:"event_type,notnull"`
	StepUID         *string `bun:"step_uid,type:varchar(36)"`
	RepeatIndex     *int    `bun:"repeat_index"`
	Source          string  `bun:"source,notnull"`
	UserUID         *string `bun:"user_uid,type:varchar(36)"`
	ConnectionUID   *string `bun:"connection_uid,type:varchar(36)"`
	ChannelType     string  `bun:"channel_type,notnull"`
	Status          string  `bun:"status,notnull"`
	SkipReason      *string `bun:"skip_reason"`
	Error           *string `bun:"error"`
	JobUID          *string `bun:"job_uid,type:varchar(36)"`
	MessageID       *string `bun:"message_id"`
	// DeliveryDetails holds structured per-attempt artifacts (HTTP status,
	// stripped URL, capped request/response bodies, duration). NULL for rows
	// from before the feature and for channels that produce no artifacts.
	DeliveryDetails *DeliveryDetails `bun:"delivery_details,type:jsonb,nullzero"`
	CreatedAt       time.Time        `bun:"created_at,notnull,default:current_timestamp"`
	SentAt          *time.Time       `bun:"sent_at"`
	CanceledAt      *time.Time       `bun:"cancelled_at"` //nolint:misspell // DB column uses British English
	FailedAt        *time.Time       `bun:"failed_at"`
}

type IncidentNotificationRow struct {
	IncidentNotification

	// Joined from users (non-nil when user_uid IS NOT NULL)
	UserName *string

	// Joined from integration_connections (non-nil when connection_uid IS NOT NULL)
	ConnectionName *string
	ConnectionType *string

	// Joined from incidents for user-scoped queries
	IncidentTitle     *string
	IncidentState     *int
	IncidentStartedAt *time.Time

	// Joined from checks for user-scoped queries
	CheckName *string
}

type IncidentPublication struct {
	UID             string `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string `bun:"organization_uid,notnull"`
	// IncidentUID links the publication to the operational incident. NULL
	// means the publication was authored by hand and tracks nothing.
	IncidentUID   *string `bun:"incident_uid"`
	StatusPageUID string  `bun:"status_page_uid,notnull"`
	// PublicTitle is templated at creation from the resource's PUBLIC display
	// name and is freely editable afterwards. It is never derived from the
	// incident title, which is internal.
	PublicTitle string           `bun:"public_title,notnull"`
	PublicState PublicationState `bun:"public_state,notnull"`
	// Severity is the display-only public badge. nil = no badge.
	Severity *string `bun:"severity"`
	// AutoCreated marks a publication minted by the auto-publish pipeline.
	// It gates group CONSOLIDATION only: the automation never appends "also
	// affecting X" notes to a narrative a person wrote. Auto-RESOLVE and
	// relapse REOPEN are keyed on IncidentUID instead — a publication linked to
	// an incident is in scope of the page's autoResolve policy whether a
	// machine or a person created it, and the two directions must agree or a
	// hand-published entry gets closed by a recovery and never reopened by the
	// relapse (spec 2026-09-02-05).
	AutoCreated bool `bun:"auto_created,notnull"`
	// HumanTouchedAt is stamped the first time a person edits the publication
	// or posts an update on it. It is the whole basis of the `if_untouched`
	// auto-resolve policy.
	//
	// Publishing an incident to a page does NOT stamp it: choosing to make an
	// outage public is not the same as taking over its narrative, and treating
	// it as such turned `if_untouched` into `never` for every hand-published
	// entry.
	HumanTouchedAt *time.Time `bun:"human_touched_at"`
	PublishedAt    time.Time  `bun:"published_at,notnull,default:current_timestamp"`
	ResolvedAt     *time.Time `bun:"resolved_at"`
	// NotifyWindowStart / NotifyWindowCount implement the per-publication
	// subscriber storm cap: at most N fan-out waves per rolling hour. Internal
	// bookkeeping — never serialized publicly.
	NotifyWindowStart *time.Time `bun:"notify_window_start"`
	NotifyWindowCount int        `bun:"notify_window_count,notnull"`
	CreatedAt         time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt         time.Time  `bun:"updated_at,notnull,default:current_timestamp"`
	DeletedAt         *time.Time `bun:"deleted_at"`
}

type IncidentPublicationUpdate struct {
	PublicTitle     *string
	PublicState     *PublicationState
	Severity        *string
	ClearSeverity   bool
	HumanTouchedAt  *time.Time
	ResolvedAt      *time.Time
	ClearResolvedAt bool
	// NotifyWindowStart / NotifyWindowCount are written together by the storm
	// cap; a nil NotifyWindowStart with NotifyWindowCount set is not a valid
	// combination and is ignored.
	NotifyWindowStart *time.Time
	NotifyWindowCount *int
}

type IncidentState int

type IncidentUpdate struct {
	Region              *string
	State               *IncidentState
	ResolvedAt          *time.Time
	ResolvedBy          *string
	ResolutionType      *string
	EscalatedAt         *time.Time
	AcknowledgedAt      *time.Time
	AcknowledgedBy      *string
	SnoozedUntil        *time.Time
	SnoozedBy           *string
	SnoozeReason        *string
	FailureCount        *int
	RelapseCount        *int
	FlapLevel           *int
	LastReopenedAt      *time.Time
	Title               *string
	Description         *string
	Details             *JSONMap
	CausedByIncidentUID *string
	PagingSuppressed    *bool

	// Clear* fields set columns to NULL on reopen
	ClearResolvedAt          bool
	ClearResolvedBy          bool
	ClearResolutionType      bool
	ClearAcknowledgedAt      bool
	ClearAcknowledgedBy      bool
	ClearSnoozedUntil        bool
	ClearSnoozedBy           bool
	ClearSnoozeReason        bool
	ClearCausedByIncidentUID bool
}

type Integration struct {
	bun.BaseModel `bun:"table:integrations,alias:integration"`

	UID             string         `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string         `bun:"organization_uid,notnull"`
	Type            ConnectionType `bun:"type,notnull"`
	Name            string         `bun:"name,notnull"`
	// No `default:true` on the tag even though the column has one — see the
	// StatusPage.AutoPublishDelaySeconds note: it made an integration
	// impossible to CREATE disabled (spec 2026-08-30-04). NewIntegration
	// supplies the enabled-by-default.
	Enabled   bool    `bun:"enabled,notnull"`
	IsDefault bool    `bun:"is_default,notnull"`
	Settings  JSONMap `bun:"settings,type:jsonb,notnull"`
	// SettingsPrivate / SettingsPrivateKeys mirror the credential-encryption
	// shape used on Check.Config. Tokens, webhook URLs, API keys live here
	// as an AES-GCM envelope at rest.
	SettingsPrivate     *string    `bun:"settings_private,type:text,nullzero"`
	SettingsPrivateKeys *string    `bun:"settings_private_keys,type:text,nullzero"`
	CreatedAt           time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt           time.Time  `bun:"updated_at,notnull,default:current_timestamp"`
	DeletedAt           *time.Time `bun:"deleted_at"`

	// Relations
	Organization *Organization `bun:"rel:belongs-to,join:organization_uid=uid"`
}

type IntegrationUpdate struct {
	Name                 *string
	Enabled              *bool
	IsDefault            *bool
	Settings             *JSONMap
	SettingsPrivate      *string
	SettingsPrivateKeys  *string
	ClearSettingsPrivate bool
}

type JSONMap map[string]any

type Job struct {
	UID             string     `bun:"uid,pk,type:varchar(36)"                        json:"uid"`
	OrganizationUID *string    `bun:"organization_uid"                               json:"organizationUid"`
	Type            string     `bun:"type,notnull"                                   json:"type"`
	Config          JSONMap    `bun:"config,type:jsonb,nullzero"                     json:"config"`
	RetryCount      int        `bun:"retry_count,notnull"                            json:"retryCount"`
	ScheduledAt     time.Time  `bun:"scheduled_at,notnull,default:current_timestamp" json:"scheduledAt"`
	Status          JobStatus  `bun:"status,notnull"                                 json:"status"`
	Output          JSONMap    `bun:"output,type:jsonb,nullzero"                     json:"output"`
	PreviousJobUID  *string    `bun:"previous_job_uid"                               json:"previousJobUid"`
	CreatedAt       time.Time  `bun:"created_at,notnull,default:current_timestamp"   json:"createdAt"`
	UpdatedAt       time.Time  `bun:"updated_at,notnull,default:current_timestamp"   json:"updatedAt"`
	DeletedAt       *time.Time `bun:"deleted_at"                                     json:"deletedAt,omitempty"`
}

type JobStatus string

type JobUpdate struct {
	Config         *JSONMap
	RetryCount     *int
	ScheduledAt    *time.Time
	Status         *JobStatus
	Output         *JSONMap
	PreviousJobUID *string
}

type KubernetesPrivateSettings struct {
	// Token is a bearer token (typically a service-account token) presented to
	// the API server.
	Token string `json:"token,omitempty"`
	// Kubeconfig is a full kubeconfig YAML document that resolves to an API
	// server + credentials. Takes precedence over Token when set.
	Kubeconfig string `json:"kubeconfig,omitempty"`
}

type KubernetesSettings struct {
	// APIServer is the cluster API server URL (e.g. "https://10.0.0.1:6443").
	// Empty when InCluster is true.
	APIServer string `json:"apiServer,omitempty"`
	// CACert is the PEM-encoded cluster CA bundle used to verify the API
	// server certificate. Optional; ignored when InsecureSkipTLSVerify is set.
	CACert string `json:"caCert,omitempty"`
	// InsecureSkipTLSVerify disables API-server certificate verification.
	// Use only for clusters with self-signed certs you cannot pin.
	InsecureSkipTLSVerify bool `json:"insecureSkipTLSVerify,omitempty"`
	// InCluster resolves the connection from the pod's mounted service-account
	// token (rest.InClusterConfig). Only works when solidping runs inside the
	// target cluster; needs no stored secret.
	InCluster bool `json:"inCluster,omitempty"`
}

type Label struct {
	UID             string     `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string     `bun:"organization_uid,notnull"`
	Key             string     `bun:"key,notnull"`
	Value           string     `bun:"value,notnull"`
	CreatedAt       time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	DeletedAt       *time.Time `bun:"deleted_at"`
}

type LabelSuggestion struct {
	Value string
	Count int
}

type ListChecksFilter struct {
	Labels          map[string]string // key:value pairs for AND filtering
	CheckGroupUID   *string           // filter by check group UID; "none" = ungrouped checks only
	Query           string            // search term for name/slug (case-insensitive substring)
	Types           []string          // optional filter by check type (e.g. ["ssh"]); empty = every type
	Internal        *string           // "true", "false", or "all" — filter by internal status
	Statuses        []CheckStatus     // optional filter by current status (up/down/etc.)
	Limit           int               // max results to return (0 = no limit)
	CursorCreatedAt *time.Time        // cursor: created_at of last item from previous page
	CursorUID       *string           // cursor: uid of last item from previous page

	// SortByGroup opts into display-order pagination (sort=group): group
	// sort_order asc, ungrouped last, then created_at DESC / uid DESC within a
	// bucket. Off = the default created_at DESC / uid DESC ordering.
	SortByGroup bool
	// CursorGroupSortKey is the effective group sort key of the last item from
	// the previous page — the leading component of the composite sort=group
	// cursor. Only set alongside CursorCreatedAt/CursorUID when SortByGroup.
	CursorGroupSortKey *int64

	// SortByTargetHost opts into the by-host-view pagination (sort=targetHost):
	// targetHost sort key ascending (checks with none of host/url/target last),
	// then name ascending, then uid ascending as the final tiebreaker.
	SortByTargetHost bool
	// CursorTargetHostKey and CursorTargetHostName are the leading two
	// components of the composite sort=targetHost cursor (the third, uid, reuses
	// CursorUID). Only set alongside CursorUID when SortByTargetHost.
	CursorTargetHostKey  *string
	CursorTargetHostName *string
}

type ListEventsFilter struct {
	OrganizationUID string      // Required: organization scope
	IncidentUID     *string     // Optional: filter by incident UID
	CheckUID        *string     // Optional: filter by check UID
	EventTypes      []EventType // Optional: filter by exact event types
	// EventTypePrefixes filters by event-type FAMILY: "auth" matches every
	// auth.* type. Combined with EventTypes as an OR (either predicate may
	// admit a row); empty means "no family restriction".
	EventTypePrefixes []string
	// ExcludeEventTypePrefixes hides whole families. This is the server-side
	// half of "auth events are admin-only": a non-admin caller always carries
	// ExcludeEventTypePrefixes=["auth"], so neither an unfiltered listing nor
	// an explicit ?type=auth can leak them.
	ExcludeEventTypePrefixes []string
	ActorType                *ActorType // Optional: filter by actor type
	// ActorUID filters to the events one user caused (API: actorUserUid).
	ActorUID *string
	// TargetUID filters to the events about one object, matched against the
	// payload's target_uid. Stored in JSON rather than a column because the
	// target is polymorphic (a check, a policy, a token, a member…), so this
	// is a payload predicate rather than an indexed one.
	TargetUID *string
	// TargetType filters to one kind of object ("integration", "member", …).
	TargetType *string
	// TargetSearch is the operator-facing free-text target filter: it matches
	// an exact target_uid OR a case-insensitive substring of the target_name
	// captured on the event.
	//
	// Both halves, because an operator has one box and two things they might
	// paste into it — the UID from a URL, or the name they remember. A
	// UID-only filter behind a box labeled "name or UID" is a promise the
	// query silently breaks.
	TargetSearch *string
	// SourceIP filters to the events that came from one client address.
	//
	// ADMIN-ONLY at the service layer, for the same reason the column is
	// withheld from non-admins: without that gate a viewer who cannot SEE the
	// addresses could still use this filter as an oracle — ask for an IP, get
	// a non-empty page, and you have confirmed a colleague was working from
	// it. A withheld column plus an open filter is not a gate.
	SourceIP *string
	Since    *time.Time // Optional: events created after this time
	Until    *time.Time // Optional: events created before this time

	// Cursor-based pagination
	CursorTimestamp *time.Time // Optional: events with created_at < this timestamp
	CursorUID       *string    // Optional: for same timestamp, events with UID < this

	Limit int // Optional: pagination limit
}

type ListFilesFilter struct {
	Q string
	// Topic restricts the listing to attachments with this EXACT topic.
	// Mutually exclusive with TopicPrefix in practice; both may be set and
	// both are then applied.
	Topic string
	// TopicPrefix restricts the listing to attachments whose topic starts with
	// this string — the entity-scoped form, e.g. `incidents/<uid>/`.
	TopicPrefix string
	Offset      int
	Limit       int
}

type ListIncidentPublicationsFilter struct {
	OrganizationUID string
	StatusPageUID   string
	IncidentUID     string
	// State filters to a single public state when non-empty.
	State string
	// ActiveOnly restricts to publications that are not resolved.
	ActiveOnly bool
	Limit      int
	Offset     int
}

type ListIncidentsFilter struct {
	OrganizationUID string          // Required: organization scope
	CheckUIDs       []string        // Optional: filter by check UIDs
	CheckGroupUID   string          // Optional: filter to group incidents on this group
	MemberCheckUID  string          // Optional: incidents that contain this check (per-check or group member)
	States          []IncidentState // Optional: filter by states (active, resolved)
	// Kinds restricts to these incident kinds. EMPTY MEANS ALL, on purpose:
	// the dashboard's incident list is meant to show burn alerts alongside
	// check outages. Callers that compute DOWNTIME from incidents (availability,
	// SLO status, uptime reports) pass IncidentKindCheck, or a burn alert would
	// count as downtime against the very objective that produced it.
	Kinds          []string
	Since          *time.Time // Optional: incidents started after this time
	Until          *time.Time // Optional: incidents started before this time
	HideSuppressed bool       // Optional: hide rolled-up (paging-suppressed) incidents
	CausedByUID    string     // Optional: only incidents whose caused_by_incident_uid equals this
	// AckedOnly returns only incidents with non-NULL acknowledged_at (and
	// expired snoozes, since snoozed-but-expired is just acked again). Set by
	// the handler when ?state=acked is requested.
	AckedOnly bool
	// SnoozedOnly returns only incidents currently snoozed (snoozed_until in
	// the future). Set by the handler when ?state=snoozed is requested.
	SnoozedOnly bool

	// Cursor-based pagination
	CursorTimestamp *time.Time // Optional: incidents with started_at < this timestamp
	CursorUID       *string    // Optional: for same timestamp, incidents with UID < this

	Limit int // Optional: pagination limit
}

type ListIntegrationsFilter struct {
	OrganizationUID string
	Type            *ConnectionType
	Enabled         *bool
}

type ListMaintenanceWindowsFilter struct {
	Status string // "active", "upcoming", "past", or "" for all
	Limit  int    // max results (0 = no limit)
}

type ListMembershipRequestsFilter struct {
	OrganizationUID string
	UserUID         string
	Status          MembershipRequestStatus
	Limit           int
	Offset          int
}

type ListOrgEntitlementAuditsFilter struct {
	OrganizationUID string
	Limit           int
	Offset          int
}

type ListResultsFilter struct {
	OrganizationUID string   // Required: organization scope
	CheckUIDs       []string // Optional: filter by multiple check UIDs
	CheckTypes      []string // Optional: filter by check types (requires join with checks table)
	Regions         []string // Optional: filter by multiple regions
	PeriodTypes     []string // Optional: filter by multiple period_types ('raw', 'hour', 'day', 'month')
	Statuses        []int    // Optional: filter by multiple status integers (inclusion)
	// ExcludeStatuses drops rows whose status is in this set (NULL status is
	// never excluded). Used by aggregation work-discovery to skip buckets whose
	// only rows are lifecycle markers (created/running), which would otherwise
	// re-aggregate into degenerate rollups forever (poison-pill loop, spec
	// 2026-07-11-16). Applied independently of Statuses.
	ExcludeStatuses []int
	// RequireCheckExists, when true, drops rows whose check_uid no longer has a
	// row in `checks` (`check_uid IN (SELECT uid FROM checks)`). Soft-deleted
	// checks still have a row and keep their history — only rows orphaned by a
	// hard delete are excluded. Used by aggregation work-discovery so a single
	// FK-orphan raw row can't become a deterministic poison pill that fails the
	// rollup INSERT and permanently halts the org's aggregation (spec
	// 2026-07-12-01 §2). A no-op on Postgres by FK construction; implemented on
	// both backends for parity and defense in depth.
	RequireCheckExists bool
	PeriodStartAfter   *time.Time // Optional: filter period_start >= this value
	// Optional: filter period_start < this value (filters by period_start, not period_end)
	PeriodEndBefore *time.Time

	// Cursor-based pagination
	CursorTimestamp *time.Time // Optional: results with period_start < this timestamp
	CursorUID       *string    // Optional: for same timestamp, results with UID < this

	// Limit
	Limit int // Optional: pagination limit

	// Include check info (for joining with checks table to get slug/name)
	IncludeCheckInfo bool // Optional: whether to join with checks table

	// SkipBlobs, when true, drops the two JSON blob columns (`metrics`,
	// `output`) from the SELECT projection: the scanned rows come back with
	// Metrics and Output nil regardless of what is stored. Only for consumers
	// that need status/counts/duration and never render a blob (uptime bars,
	// badges, status-page recent results) — it trims per-request I/O on the
	// largest table in the system (spec 2026-07-24-02 §5). Default (false)
	// keeps the full row, so every other reader is unaffected.
	SkipBlobs bool
}

type ListResultsResponse struct {
	Results []*Result // The result records
}

type ListSLOsFilter struct {
	// CheckUID, when set, restricts to SLOs scoped directly to that check.
	CheckUID string
	// EnabledOnly restricts to enabled SLOs.
	EnabledOnly bool
	Limit       int
}

type ListSeveritiesFilter struct {
	OrganizationUID string
}

type ListSupportThreadsFilter struct {
	Status  string
	Channel string
	Query   string
	Limit   int
}

type MSTeamsBotSettings struct {
	TenantID   string `json:"tenant_id"`
	TenantName string `json:"tenant_name,omitempty"`
	// BotID is the bot's own Bot Framework user id inside this tenant
	// (`28:<app-id>`), used to recognize "the member added is us".
	BotID string `json:"bot_id,omitempty"`
	// AppID records which Entra app performed the install, so a credential
	// rotation that changes the app id is visible rather than silent.
	AppID string `json:"app_id,omitempty"`
	// ServiceURL is the tenant's regional Bot Connector base URL, captured at
	// install and refreshed on every inbound activity.
	ServiceURL string `json:"service_url,omitempty"`
	// ChannelID / ChannelName / TeamID are the default notification
	// destination — the Teams counterpart of SlackSettings.ChannelID.
	ChannelID   string `json:"channel_id,omitempty"`
	ChannelName string `json:"channel_name,omitempty"`
	TeamID      string `json:"team_id,omitempty"`
	DisplayName string `json:"display_name,omitempty"`

	InstalledByUserID string `json:"installed_by_user_id,omitempty"`
	// UninstalledAt is set (RFC3339) when the tenant removes the app. The row
	// is kept so the dashboard can render "uninstalled — reinstall to resume"
	// instead of the integration silently vanishing.
	UninstalledAt string `json:"uninstalled_at,omitempty"`

	Destinations []MSTeamsDestination `json:"destinations,omitempty"`
}

type MSTeamsDestination struct {
	ID         string `json:"id"`
	Name       string `json:"name"`
	TeamID     string `json:"team_id,omitempty"`
	TeamName   string `json:"team_name,omitempty"`
	ServiceURL string `json:"service_url,omitempty"`
	// Type is "channel" today. Personal-scope DMs are phase 2 and would add
	// "personal" here without changing the shape.
	Type string `json:"type,omitempty"`
}

type MSTeamsSettings struct {
	WebhookURL string `json:"webhook_url"`
}

type MaintenanceWindow struct {
	UID             string     `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string     `bun:"organization_uid,notnull"`
	Title           string     `bun:"title,notnull"`
	Description     *string    `bun:"description"`
	StartAt         time.Time  `bun:"start_at,notnull"`
	EndAt           time.Time  `bun:"end_at,notnull"`
	Recurrence      string     `bun:"recurrence,notnull"`
	RecurrenceEnd   *time.Time `bun:"recurrence_end"`
	CreatedBy       *string    `bun:"created_by"`
	CreatedAt       time.Time  `bun:"created_at,notnull"`
	UpdatedAt       time.Time  `bun:"updated_at,notnull"`
	DeletedAt       *time.Time `bun:"deleted_at"`
}

type MaintenanceWindowCheck struct {
	UID                  string    `bun:"uid,pk,type:varchar(36)"`
	MaintenanceWindowUID string    `bun:"maintenance_window_uid,notnull"`
	CheckUID             *string   `bun:"check_uid"`
	CheckGroupUID        *string   `bun:"check_group_uid"`
	CreatedAt            time.Time `bun:"created_at,notnull"`
}

type MaintenanceWindowUpdate struct {
	Title         *string
	Description   *string
	StartAt       *time.Time
	EndAt         *time.Time
	Recurrence    *string
	RecurrenceEnd *time.Time
}

type MemberRole string

type MembershipRequest struct {
	UID             string                  `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string                  `bun:"organization_uid,notnull"`
	UserUID         string                  `bun:"user_uid,notnull"`
	Message         *string                 `bun:"message"`
	Status          MembershipRequestStatus `bun:"status,notnull"`
	DecisionReason  *string                 `bun:"decision_reason"`
	DecidedAt       *time.Time              `bun:"decided_at"`
	DecidedByUID    *string                 `bun:"decided_by_uid"`
	CreatedAt       time.Time               `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt       time.Time               `bun:"updated_at,notnull,default:current_timestamp"`

	Organization *Organization `bun:"rel:belongs-to,join:organization_uid=uid"`
	User         *User         `bun:"rel:belongs-to,join:user_uid=uid"`
	DecidedBy    *User         `bun:"rel:belongs-to,join:decided_by_uid=uid"`
}

type MembershipRequestStatus string

type OAuthClient struct {
	bun.BaseModel `bun:"table:oauth_clients,alias:oauth_client"`

	UID          string    `bun:"uid,pk,type:varchar(36)"`
	ClientID     string    `bun:"client_id,notnull"`
	SecretHash   *string   `bun:"secret_hash"`
	ClientName   string    `bun:"client_name"`
	RedirectURIs []string  `bun:"redirect_uris,type:jsonb,nullzero"`
	GrantTypes   []string  `bun:"grant_types,type:jsonb,nullzero"`
	Scopes       []string  `bun:"scopes,type:jsonb,nullzero"`
	IsPublic     bool      `bun:"is_public,notnull"`
	CreatedAt    time.Time `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt    time.Time `bun:"updated_at,notnull,default:current_timestamp"`
}

type Occurrence struct {
	StartAt time.Time `json:"startAt"`
	EndAt   time.Time `json:"endAt"`
}

type OnCallSchedule struct {
	UID             string       `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string       `bun:"organization_uid,notnull"`
	Name            string       `bun:"name,notnull"`
	Description     *string      `bun:"description"`
	Timezone        string       `bun:"timezone,notnull"`
	RotationType    RotationType `bun:"rotation_type,notnull"`
	HandoffTime     string       `bun:"handoff_time,notnull"` // HH:MM in schedule timezone
	HandoffWeekday  *int         `bun:"handoff_weekday"`      // 0–6 (Mon=0); required for weekly
	StartAt         time.Time    `bun:"start_at,notnull"`     // First handoff in the rotation cycle
	ICalSecret      *string      `bun:"ical_secret"`          // NULL = feed disabled
	CreatedAt       time.Time    `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt       time.Time    `bun:"updated_at,notnull,default:current_timestamp"`
	DeletedAt       *time.Time   `bun:"deleted_at"`
}

type OnCallScheduleOverride struct {
	UID          string    `bun:"uid,pk,type:varchar(36)"`
	ScheduleUID  string    `bun:"schedule_uid,notnull"`
	UserUID      string    `bun:"user_uid,notnull"`
	StartAt      time.Time `bun:"start_at,notnull"` // inclusive
	EndAt        time.Time `bun:"end_at,notnull"`   // exclusive
	Reason       *string   `bun:"reason"`
	CreatedByUID *string   `bun:"created_by_uid"`
	CreatedAt    time.Time `bun:"created_at,notnull,default:current_timestamp"`
}

type OnCallScheduleUpdate struct {
	Name           *string
	Description    *string
	Timezone       *string
	RotationType   *RotationType
	HandoffTime    *string
	HandoffWeekday *int
	StartAt        *time.Time
	ICalSecret     *string

	ClearDescription    bool
	ClearHandoffWeekday bool
	ClearICalSecret     bool
}

type OnCallScheduleUser struct {
	UID         string    `bun:"uid,pk,type:varchar(36)"`
	ScheduleUID string    `bun:"schedule_uid,notnull"`
	UserUID     string    `bun:"user_uid,notnull"`
	Position    int       `bun:"position,notnull"`
	CreatedAt   time.Time `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt   time.Time `bun:"updated_at,notnull,default:current_timestamp"`
}

type OrgEntitlementAudit struct {
	UID             string    `bun:"uid,pk,type:varchar(36)"                      json:"uid"`
	OrganizationUID string    `bun:"organization_uid,notnull"                     json:"organizationUid"`
	Source          string    `bun:"source,notnull"                               json:"source"`
	Actor           string    `bun:"actor,notnull"                                json:"actor"`
	BeforeSnapshot  JSONMap   `bun:"before_snapshot,type:jsonb,nullzero"          json:"beforeSnapshot,omitempty"`
	AfterSnapshot   JSONMap   `bun:"after_snapshot,type:jsonb,notnull"            json:"afterSnapshot"`
	Reason          *string   `bun:"reason"                                       json:"reason,omitempty"`
	CreatedAt       time.Time `bun:"created_at,notnull,default:current_timestamp" json:"createdAt"`
}

type OrgEntitlements struct {
	UID             string `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string `bun:"organization_uid,notnull,unique"`

	Payload EntitlementsPayload `bun:"payload,type:jsonb,notnull"`

	ExternalRef  *string    `bun:"external_ref"`
	ExpiresAt    *time.Time `bun:"expires_at"`
	LastSyncedAt *time.Time `bun:"last_synced_at"`
	Metadata     JSONMap    `bun:"metadata,type:jsonb,nullzero"`

	CreatedAt time.Time `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt time.Time `bun:"updated_at,notnull,default:current_timestamp"`
}

type OrgUsageCounter struct {
	bun.BaseModel `bun:"table:org_usage_counters"`

	OrganizationUID string `bun:"organization_uid,pk"`
	Kind            string `bun:"kind,pk"`
	PeriodStart     string `bun:"period_start,pk"`
	Count           int    `bun:"count,notnull"`
}

type Organization struct {
	UID  string `bun:"uid,pk,type:varchar(36)"`
	Slug string `bun:"slug,notnull"`
	Name string `bun:"name"`
	// DefaultEscalationPolicyUID is the org-wide fallback escalation policy for
	// checks that resolve to no policy of their own (check → group → org default
	// → none). NULL = no org default (legacy behavior). FK `on delete set null`.
	DefaultEscalationPolicyUID *string `bun:"default_escalation_policy_uid"`
	// LogoURL is the organization's logo: either an external http(s) URL, or
	// "/pub/assets/<file uid>" for a logo uploaded through the files
	// subsystem. NULL means "no logo", and every surface falls back to the
	// product default.
	LogoURL *string `bun:"logo_url"`
	// LogoFileUID points at the uploaded file backing LogoURL. It is NULL for
	// external-URL logos. Replacing an uploaded logo retires the previous blob
	// through it. It is NO LONGER an authorization input: since spec
	// 2026-08-22-03 the unsigned public route reads the FILE's own attachment
	// topic (`organizations/<uid>/logo`) and serves live rows only.
	LogoFileUID *string    `bun:"logo_file_uid"`
	CreatedAt   time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt   time.Time  `bun:"updated_at,notnull,default:current_timestamp"`
	DeletedAt   *time.Time `bun:"deleted_at"`
}

type OrganizationMember struct {
	UID             string     `bun:"uid,pk,type:varchar(36)"`
	UserUID         string     `bun:"user_uid,notnull"`
	OrganizationUID string     `bun:"organization_uid,notnull"`
	Role            MemberRole `bun:"role,notnull"`
	InvitedByUID    *string    `bun:"invited_by_uid"`
	InvitedAt       *time.Time `bun:"invited_at"`
	JoinedAt        *time.Time `bun:"joined_at"`
	CreatedAt       time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt       time.Time  `bun:"updated_at,notnull,default:current_timestamp"`
	DeletedAt       *time.Time `bun:"deleted_at"`

	// Relations (for eager loading)
	User         *User         `bun:"rel:belongs-to,join:user_uid=uid"`
	Organization *Organization `bun:"rel:belongs-to,join:organization_uid=uid"`
	InvitedBy    *User         `bun:"rel:belongs-to,join:invited_by_uid=uid"`
}

type OrganizationMemberUpdate struct {
	Role     *MemberRole
	JoinedAt *time.Time
}

type OrganizationPreviousSlug struct {
	bun.BaseModel `bun:"table:organization_previous_slugs,alias:org_previous_slug"`

	UID             string     `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string     `bun:"organization_uid,notnull"`
	Slug            string     `bun:"slug,notnull"`
	CreatedAt       time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	DeletedAt       *time.Time `bun:"deleted_at"`
}

type OrganizationProvider struct {
	UID             string       `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string       `bun:"organization_uid,notnull"`
	ProviderType    ProviderType `bun:"provider_type,notnull"`
	ProviderID      string       `bun:"provider_id,notnull"` // e.g., Slack Team ID T0123456789
	ProviderName    string       `bun:"provider_name"`       // e.g., "Acme Corp Slack Workspace"
	Metadata        JSONMap      `bun:"metadata,type:jsonb,nullzero"`
	// MetadataPrivate / MetadataPrivateKeys mirror the credential-encryption
	// shape used on Check.Config — OAuth client secrets and similar live
	// here as an AES-GCM envelope at rest.
	MetadataPrivate     *string    `bun:"metadata_private,type:text,nullzero"`
	MetadataPrivateKeys *string    `bun:"metadata_private_keys,type:text,nullzero"`
	CreatedAt           time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt           time.Time  `bun:"updated_at,notnull,default:current_timestamp"`
	DeletedAt           *time.Time `bun:"deleted_at"`

	// Relations (for eager loading)
	Organization *Organization `bun:"rel:belongs-to,join:organization_uid=uid"`
}

type OrganizationProviderUpdate struct {
	ProviderName         *string
	Metadata             *JSONMap
	MetadataPrivate      *string
	MetadataPrivateKeys  *string
	ClearMetadataPrivate bool
}

type OrganizationUpdate struct {
	Slug *string
	Name *string
	// DefaultEscalationPolicyUID sets the org-wide default escalation policy.
	// ClearDefaultEscalationPolicyUID takes precedence and clears it to NULL
	// (mirrors the check-group clear-flag pattern).
	DefaultEscalationPolicyUID      *string
	ClearDefaultEscalationPolicyUID bool
	// LogoURL / LogoFileUID follow the same set-or-clear pattern: the Clear*
	// flag wins and writes NULL, a non-nil pointer writes the value, and nil
	// with no flag leaves the column untouched (PATCH semantics).
	LogoURL          *string
	ClearLogoURL     bool
	LogoFileUID      *string
	ClearLogoFileUID bool
}

type PageResourceStatus struct {
	Status        CheckStatus
	InMaintenance bool
}

type PageStatus string

type PageStatusCounts struct {
	Operational int
	Degraded    int
	Down        int
	Maintenance int
	Unknown     int
}

type Parameter struct {
	UID             string     `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID *string    `bun:"organization_uid"`
	Key             string     `bun:"key,notnull"`
	Value           JSONMap    `bun:"value,type:jsonb,notnull"`
	Secret          *bool      `bun:"secret"`
	CreatedAt       time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt       time.Time  `bun:"updated_at,notnull,default:current_timestamp"`
	DeletedAt       *time.Time `bun:"deleted_at"`
}

type ParameterUpdate struct {
	Key    *string
	Value  *JSONMap
	Secret *bool
}

type PeriodTierSide int

type ProviderType string

type PublicationSeverity string

type PublicationState string

type ReapAbandonedResultsOutcome struct {
	// Candidates is the number of raw rows found sitting in ResultStatusCreated
	// (see abandonedResultLifecycleStatuses), before threshold filtering.
	Candidates int
	// Reaped is the number of those candidates that were past
	// AbandonedResultThreshold for their check and got finalized this sweep.
	Reaped int
}

type RecentResultsPerCheckFilter struct {
	// OrganizationUID scopes every branch. Required.
	OrganizationUID string
	// CheckUIDs are the checks to fetch for. An empty list yields no rows.
	CheckUIDs []string
	// Tiers are the tier-aligned branches, UNION ALLed together. Required, and
	// each one must be single-sided.
	Tiers []RecentResultsTier
	// PerCheckLimits is the per-check row budget, per branch. A check absent
	// from the map uses DefaultPerCheckLimit.
	PerCheckLimits map[string]int
	// DefaultPerCheckLimit is the budget for a check with no explicit entry.
	// Required (> 0) — an unbounded branch defeats the whole point.
	DefaultPerCheckLimit int
}

type RecentResultsTier struct {
	// PeriodTypes are the tiers this branch reads. They MUST all sit on one
	// side of the raw/rollup split (see PeriodTypesTierSide) — the
	// implementation restates that side as an explicit predicate so both
	// Postgres and SQLite can use the matching partial index.
	PeriodTypes []string
	// Since is this branch's inclusive period_start lower bound.
	Since time.Time
}

type ReportSchedule struct {
	UID             string `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string `bun:"organization_uid,notnull"`
	Name            string `bun:"name,notnull"`
	Frequency       string `bun:"frequency,notnull"`
	Timezone        string `bun:"timezone,notnull"`
	// Recipients is PII, held to the same bar as status-page subscriber
	// addresses: never logged, never emitted into events, only ever read back
	// to the org's own admins.
	Recipients []string `bun:"recipients,type:jsonb,nullzero"`
	// CheckUIDs / CheckGroupUIDs scope the digest. Both empty means org-wide.
	CheckUIDs      []string `bun:"check_uids,type:jsonb,nullzero"`
	CheckGroupUIDs []string `bun:"check_group_uids,type:jsonb,nullzero"`
	IncludeSLOs    bool     `bun:"include_slos,notnull"`
	Enabled        bool     `bun:"enabled,notnull"`
	// LastPeriodStart is the UTC start of the last period actually reported.
	// It is the duplicate-run suppression key: a second job fire for the same
	// closed period is a no-op, which is what makes multi-replica scheduling
	// safe without leader election.
	LastPeriodStart *time.Time `bun:"last_period_start"`
	LastRunAt       *time.Time `bun:"last_run_at"`
	CreatedAt       time.Time  `bun:"created_at,notnull"`
	UpdatedAt       time.Time  `bun:"updated_at,notnull"`
	DeletedAt       *time.Time `bun:"deleted_at"`
}

type ReportScheduleUpdate struct {
	Name           *string
	Frequency      *string
	Timezone       *string
	Recipients     *[]string
	CheckUIDs      *[]string
	CheckGroupUIDs *[]string
	IncludeSLOs    *bool
	Enabled        *bool
}

type Result struct {
	UID             string     `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string     `bun:"organization_uid,notnull"`
	CheckUID        string     `bun:"check_uid,notnull"`
	PeriodType      string     `bun:"period_type,notnull"`
	PeriodStart     time.Time  `bun:"period_start,notnull"`
	PeriodEnd       *time.Time `bun:"period_end"`
	Region          *string    `bun:"region"`

	// Raw result fields (period_type = 'raw')
	WorkerUID *string  `bun:"worker_uid"`
	Status    *int     `bun:"status"`
	Duration  *float32 `bun:"duration"`
	Metrics   JSONMap  `bun:"metrics,type:jsonb,nullzero"`
	Output    JSONMap  `bun:"output,type:jsonb,nullzero"`

	// Maintenance records that an active maintenance window covered this
	// check at the moment the probe was recorded (spec 2026-08-20-01). It is
	// set at ingest and never backfilled: rollup buckets cannot be sliced
	// after the fact, so the tag has to exist before aggregation runs. Raw
	// rows only.
	//
	// It changes NO existing availability number. Status pages, badges and the
	// availability API keep counting maintenance probes exactly as before;
	// only an SLO with ExcludeMaintenance set subtracts them.
	Maintenance bool `bun:"maintenance,notnull"`

	// Diagnostics is the opt-in capture of what the probe saw (spec
	// 2026-08-20-01). It is TRANSIENT by construction: `bun:"-"` keeps it out
	// of every INSERT/UPDATE/SELECT so it can never reach the `output` JSONB
	// column or any other column, and `json:"-"` keeps it off every API
	// response built from this struct. It exists on the model only so the
	// result-submission path can hand it to the incident pipeline, which is
	// the ONLY thing allowed to persist it (onto incidents.details, and only
	// on an incident open/reopen).
	Diagnostics *checkerdef.Diagnostics `bun:"-" json:"-"`

	// Aggregated fields (period_type = 'hour', 'day', 'month', 'year').
	// availability_pct is intentionally absent: it is derived at read time from
	// successful_checks / total_checks rather than stored (spec 2026-07-24-02).
	TotalChecks      *int `bun:"total_checks"`
	SuccessfulChecks *int `bun:"successful_checks"`
	// MaintenanceChecks / MaintenanceSuccessfulChecks are SUBSETS of the two
	// counters above: how many of the probes folded into this bucket were
	// recorded while an active maintenance window covered the check
	// (spec 2026-08-20-01).
	//
	// They are additive across tiers exactly like their parents, and the tiers
	// are disjoint by construction (the aggregation job compacts and deletes in
	// one transaction), so a month row's counters are the exact count of raw
	// probes it descends from — no double counting.
	//
	// Being subsets rather than replacements is what keeps this change inert
	// for every existing consumer: availability stays successful/total.
	MaintenanceChecks           *int     `bun:"maintenance_checks"`
	MaintenanceSuccessfulChecks *int     `bun:"maintenance_successful_checks"`
	DurationMin                 *float32 `bun:"duration_min"`
	DurationMax                 *float32 `bun:"duration_max"`
	DurationP95                 *float32 `bun:"duration_p95"`
	DurationAvg                 *float32 `bun:"duration_avg"`

	CreatedAt time.Time `bun:"created_at,notnull,default:current_timestamp"`

	// CheckSlug and CheckName are populated only when the query joined
	// `checks` (ListResultsFilter.IncludeCheckInfo, set when the results
	// endpoint's caller requests with=checkSlug,checkName). Scan-only and
	// transient — never selected, inserted, or updated outside that query;
	// bun scans the joined `check_slug`/`check_name` aliases straight into
	// these tags without a real relation. A LEFT JOIN leaves both nil for a
	// result whose check has since been hard-deleted (results can outlive a
	// hard-deleted check, see ListResultsFilter.RequireCheckExists) rather
	// than dropping the row from the page.
	CheckSlug *string `bun:"check_slug,scanonly"`
	CheckName *string `bun:"check_name,scanonly"`
}

type ResultStatus int

type RotationType string

type SLO struct {
	UID             string `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string `bun:"organization_uid,notnull"`
	Name            string `bun:"name,notnull"`
	Slug            string `bun:"slug,notnull"`
	// Exactly one of CheckUID / CheckGroupUID is set — enforced by the
	// slos_scope_xor CHECK constraint, not merely by convention.
	CheckUID      *string `bun:"check_uid"`
	CheckGroupUID *string `bun:"check_group_uid"`
	// TargetPct is the objective, e.g. 99.9. 0 < TargetPct <= 100.
	TargetPct float64 `bun:"target_pct,notnull"`
	// Timezone is the IANA zone the calendar month is resolved in.
	Timezone string `bun:"timezone,notnull"`
	// ExcludeMaintenance subtracts probes tagged results.maintenance from this
	// SLO's denominator. It affects nothing outside the SLO read path.
	ExcludeMaintenance bool       `bun:"exclude_maintenance,notnull"`
	Enabled            bool       `bun:"enabled,notnull"`
	CreatedAt          time.Time  `bun:"created_at,notnull"`
	UpdatedAt          time.Time  `bun:"updated_at,notnull"`
	DeletedAt          *time.Time `bun:"deleted_at"`
}

type SLOAlertPolicy struct {
	// Named explicitly rather than left to the inflector: "SLOAlertPolicy" is
	// exactly the acronym-prefixed shape struct-name pluralization gets wrong.
	bun.BaseModel `bun:"table:slo_alert_policies,alias:slo_alert_policies"`

	UID             string `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string `bun:"organization_uid,notnull"`
	SLOUID          string `bun:"slo_uid,notnull"`
	// Kind is the built-in identity, unique per SLO.
	Kind string `bun:"kind,notnull"`
	// Enabled defaults to false: upgrading to a version that has alerting must
	// never start paging on its own.
	Enabled bool `bun:"enabled,notnull"`
	// LongWindowSeconds / ShortWindowSeconds bound the two rolling windows the
	// evaluator measures, both ending at "now".
	LongWindowSeconds  int `bun:"long_window_seconds,notnull"`
	ShortWindowSeconds int `bun:"short_window_seconds,notnull"`
	// Threshold is the burn-rate multiple both windows must exceed. 1.0 spends
	// the calendar budget exactly by period end; 14.4 spends a 30-day budget in
	// about two hours.
	Threshold float64 `bun:"threshold,notnull"`
	Severity  string  `bun:"severity,notnull"`
	// MinSamples is the per-window probe floor. Below it the window is
	// INCONCLUSIVE: it does not fire, and it equally does not count as "below
	// threshold" for the resolution hysteresis.
	MinSamples int `bun:"min_samples,notnull"`
	// LastEvaluatedAt / LastLongBurnRate / LastShortBurnRate are the live
	// readout the dashboard's Alerting section renders. Stored so the UI and
	// the evaluator cannot disagree about what the burn rate was a minute ago.
	LastEvaluatedAt   *time.Time `bun:"last_evaluated_at"`
	LastLongBurnRate  *float64   `bun:"last_long_burn_rate"`
	LastShortBurnRate *float64   `bun:"last_short_burn_rate"`
	// BelowThresholdSince is the hysteresis anchor: the instant BOTH windows
	// first dropped below Threshold. Resolution waits until that has held for a
	// full short window; it is cleared the moment either window goes back over,
	// so a flapping burn never resolves.
	BelowThresholdSince *time.Time `bun:"below_threshold_since"`
	CreatedAt           time.Time  `bun:"created_at,notnull"`
	UpdatedAt           time.Time  `bun:"updated_at,notnull"`
}

type SLOAlertPolicyDefault struct {
	Kind               string
	LongWindowSeconds  int
	ShortWindowSeconds int
	Threshold          float64
	Severity           string
}

type SLOAlertPolicyUpdate struct {
	Enabled            *bool
	LongWindowSeconds  *int
	ShortWindowSeconds *int
	Threshold          *float64
	Severity           *string
	MinSamples         *int

	LastEvaluatedAt   *time.Time
	LastLongBurnRate  *float64
	LastShortBurnRate *float64

	BelowThresholdSince *time.Time
	// ClearBelowThresholdSince sets the hysteresis anchor back to NULL — used
	// the instant either window climbs back over the threshold.
	ClearBelowThresholdSince bool
	// ClearLastBurnRates nulls the live readout when a window turns
	// inconclusive, so the UI shows "no data" rather than a stale number.
	ClearLastBurnRates bool
}

type SLOUpdate struct {
	Name               *string
	Slug               *string
	CheckUID           *string
	CheckGroupUID      *string
	TargetPct          *float64
	Timezone           *string
	ExcludeMaintenance *bool
	Enabled            *bool
}

type SectionSelector struct {
	// All selects every check in the organization. Internal checks are
	// excluded (see Filter) — auto-publishing an internal probe onto a public
	// page is precisely the disclosure footgun this feature has to avoid.
	All bool `json:"all,omitempty"`
	// Labels selects checks carrying ALL of these exact key=value labels.
	Labels map[string]string `json:"labels,omitempty"`
}

type Severity struct {
	UID             string     `bun:"uid,pk,type:varchar(36)"`
	OrganizationUID string     `bun:"organization_uid,notnull"`
	Slug            string     `bun:"slug,notnull"`
	Name            string     `bun:"name,notnull"`
	Description     *string    `bun:"description"`
	Channels        string     `bun:"channels,notnull"`
	IsDefault       bool       `bun:"is_default,notnull"`
	CreatedAt       time.Time  `bun:"created_at,notnull,default:current_timestamp"`
	UpdatedAt       time.Time  `bun:"updated_at,notnull,default:current_timestamp"`
	DeletedAt       *time.Time `bun:"deleted_at"`
}

type SeveritySeed struct {
	Slug      string
	Name      string
	Channels  []string
	IsDefault bool
}

type SeverityUpdate struct {
	Slug         *string
	Name         *string
	Description  *string
	Channels     *[]string
	IsDefault    *bool
	ClearDefault bool
}

type SignupAttribution struct {
	Source   string `json:"utmSource,omitempty"`
	Medium   string `json:"utmMedium,omitempty"`
	Campaign string `json:"utmCampaign,omitempty"`
	Term     string `json:"utmTerm,omitempty"`
	Content  string `json:"utmContent,omitempty"`
	// ClickIDKind names the query parameter the click id arrived in — gclid,
	// gbraid, wbraid (Google) or msclkid (Microsoft) — so the upload goes to
	// the right network.
	ClickIDKind string `json:"clickIdKind,omitempty"`
	ClickID     string `json:"clickId,omitempty"`
	// LandingPath is the dashboard path the tagged link opened, without its
	// query string. Useful for telling an ad landing from a docs deep link.
	LandingPath string `json:"landingPath,omitempty"`
	// CapturedAt is when the dashboard first saw the tags, which can be days
	// before the account exists (the confirmation email is not always opened
	// at once).
	CapturedAt *time.Time `json:"capturedAt,omitempty"`
}