api

type ADSBProvider interface {
	RecentAircraftReports(limit int) ([]storage.AircraftReport, error)
	// CurrentAircraft returns the coalesced latest state per ICAO seen
	// within maxAge (≤ 0 → provider default).
	CurrentAircraft(maxAge time.Duration) ([]storage.AircraftReport, error)
}

type AISMessageDTO struct {
	ID         int64     `json:"id"`
	ReceivedAt time.Time `json:"received_at"`
	MMSI       uint32    `json:"mmsi"`
	Type       string    `json:"type"`
	Body       string    `json:"body,omitempty"`

	Latitude         float64 `json:"latitude,omitempty"`
	Longitude        float64 `json:"longitude,omitempty"`
	SpeedOverGround  float64 `json:"sog,omitempty"`
	CourseOverGround float64 `json:"cog,omitempty"`
	Heading          int     `json:"heading,omitempty"`
	HasPosition      bool    `json:"has_position"`

	VesselName  string `json:"vessel_name,omitempty"`
	Callsign    string `json:"callsign,omitempty"`
	Destination string `json:"destination,omitempty"`
	ShipType    int    `json:"ship_type,omitempty"`
	IMO         uint32 `json:"imo,omitempty"`

	RawHex string `json:"raw_hex,omitempty"`
	FCSOK  bool   `json:"fcs_ok"`
}

type AISProvider interface {
	RecentAISMessages(limit int) ([]storage.AISMessage, error)
}

type APRSPacketDTO struct {
	ID         int64     `json:"id"`
	ReceivedAt time.Time `json:"received_at"`
	Src        string    `json:"src"`
	Dst        string    `json:"dst"`
	Path       string    `json:"path,omitempty"`
	Type       string    `json:"type"`
	Body       string    `json:"body,omitempty"`
	Latitude   float64   `json:"latitude,omitempty"`
	Longitude  float64   `json:"longitude,omitempty"`
	RawInfo    string    `json:"raw_info,omitempty"`
	FCSOK      bool      `json:"fcs_ok"`
}

type APRSProvider interface {
	RecentAPRSPackets(limit int) ([]storage.APRSPacket, error)
}

type ActiveCallDTO struct {
	Grant        GrantDTO      `json:"grant"`
	Talkgroup    *TalkgroupDTO `json:"talkgroup,omitempty"`
	DeviceSerial string        `json:"device_serial"`
	StartedAt    time.Time     `json:"started_at"`
	LastHeardAt  time.Time     `json:"last_heard_at"`
}

type AffiliationDTO struct {
	System            string `json:"system"`
	Protocol          string `json:"protocol"`
	SourceID          uint32 `json:"source_id"`
	GroupID           uint32 `json:"group_id"`
	AnnouncementGroup uint32 `json:"announcement_group,omitempty"`
	Response          string `json:"response"`
}

type AffiliationProvider interface {
	Affiliations() []trunking.UnitActivity
}

type AircraftReportDTO struct {
	ID         int64     `json:"id"`
	ReceivedAt time.Time `json:"received_at"`
	ICAO       uint32    `json:"icao"`
	ICAOHex    string    `json:"icao_hex"`
	Kind       string    `json:"kind"`
	Body       string    `json:"body,omitempty"`
	CRCValid   bool      `json:"crc_valid"`

	Callsign string `json:"callsign,omitempty"`
	Category int    `json:"category,omitempty"`

	Latitude    float64 `json:"latitude,omitempty"`
	Longitude   float64 `json:"longitude,omitempty"`
	Altitude    int     `json:"altitude_ft,omitempty"`
	HasPosition bool    `json:"has_position"`
	HasAltitude bool    `json:"has_altitude"`

	GroundSpeedKn   int     `json:"ground_speed_kn,omitempty"`
	TrackDeg        float64 `json:"track_deg,omitempty"`
	VerticalRateFPM int     `json:"vertical_rate_fpm,omitempty"`

	RawHex string `json:"raw_hex,omitempty"`
}

type AudioController interface {
	// Volume returns the current software gain (0..1).
	Volume() float32
	// SetVolume clamps to 0..1 and applies immediately.
	SetVolume(v float32)
	// Muted reports the mute state.
	Muted() bool
	// SetMuted toggles mute. Mute is a software-gain bypass, not a
	// device-level operation — toggling is instant.
	SetMuted(m bool)
	// RecordingEnabled reports whether the recorder's "create new
	// sessions" gate is open. In-flight sessions are not affected
	// by this gate.
	RecordingEnabled() bool
	// SetRecordingEnabled flips the recorder gate. False stops new
	// WAVs from landing on disk; in-flight sessions complete.
	SetRecordingEnabled(enabled bool)
	// DropsTotal is a monotonically increasing counter of PCM
	// samples lost because the playback queue was full. Surfaced
	// so operators can spot scheduling-jitter problems from the
	// TUI without reaching for /metrics.
	DropsTotal() uint64
	// SampleRate is the host playback rate the player was opened
	// at, in Hz. Read-only; reopening the device with a different
	// rate requires a daemon restart.
	SampleRate() uint32
	// BackendEnabled reports whether a real audio backend is
	// attached. False means audio.enabled was off in config or the
	// backend failed to init, and writes are silently dropped.
	BackendEnabled() bool
}

type AudioPublisher struct {
	// contains filtered or unexported fields
}

type AudioPublisherStats struct {
	Subscribers   int
	DroppedTotal  uint64
	TrackedGrants int
}

type AudioStatusDTO struct {
	// BackendEnabled is true when a real audio sink is attached.
	// False = audio.enabled was off in config or the backend
	// failed to init; PATCH still works but takes effect only on
	// the recorder gate.
	BackendEnabled bool `json:"backend_enabled"`
	// SampleRate is the host playback rate in Hz.
	SampleRate uint32 `json:"sample_rate"`
	// Volume is the software gain (0..1).
	Volume float32 `json:"volume"`
	// Muted reports the mute state.
	Muted bool `json:"muted"`
	// RecordingEnabled is the recorder's "create new sessions"
	// gate. In-flight sessions are unaffected.
	RecordingEnabled bool `json:"recording_enabled"`
	// DropsTotal is a monotonically increasing counter of PCM
	// samples lost because the playback queue was full.
	DropsTotal uint64 `json:"drops_total"`
}

type AudioSubFilter struct {
	DeviceSerials []string
	TalkgroupIDs  []uint32
	// IncludeRaw mirrors the proto flag. Until WriteRawFrame is
	// wired into the publisher (digital-voice raw frames are a
	// follow-up), this just selects whether to surface PCM frames
	// at all — false is the safe default that's never going to
	// break a caller that didn't ask for audio.
	IncludeRaw bool
}

type AuthConfig struct {
	// Mode picks the policy. See AuthMode for the trade-offs.
	Mode AuthMode
	// Token is the inline bearer token. Compared with
	// crypto/subtle.ConstantTimeCompare. Prefer TokenFile so the
	// token doesn't live in config.yaml — but inline is supported
	// for ephemeral / test setups.
	Token string
	// TokenFile is a path to a file containing the bearer token
	// (whitespace stripped). Read at startup; the daemon reloads it
	// on every request so operators can rotate tokens without a
	// restart. Empty disables file-based tokens.
	TokenFile string
	// TrustedNetworks is a list of CIDRs whose source addresses
	// bypass the bearer-token check under AuthModeAuto. Loopback
	// (127.0.0.1/32 and ::1/128) is implicitly trusted under
	// AuthModeAuto and does not need to be listed here.
	TrustedNetworks []string
}

type AuthMode uint8

type BookmarkDTO struct {
	ID        int64     `json:"id"`
	Name      string    `json:"name"`
	FreqHz    uint32    `json:"freq_hz"`
	Mode      string    `json:"mode"`
	CTCSSHz   float64   `json:"ctcss_hz,omitempty"`
	DCSCode   uint16    `json:"dcs_code,omitempty"`
	Notes     string    `json:"notes,omitempty"`
	Group     string    `json:"group,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type BookmarkProvider interface {
	ListBookmarks() ([]storage.Bookmark, error)
	GetBookmark(id int64) (storage.Bookmark, error)
	CreateBookmark(b storage.Bookmark) (storage.Bookmark, error)
	UpdateBookmark(b storage.Bookmark) (storage.Bookmark, error)
	DeleteBookmark(id int64) error
}

type BroadcastStatusProvider interface {
	BroadcastStats() any
}

type CORSConfig struct {
	AllowedOrigins []string
}

type CallEncryptionDTO struct {
	DeviceSerial string    `json:"device_serial"`
	System       string    `json:"system,omitempty"`
	Protocol     string    `json:"protocol,omitempty"`
	GroupID      uint32    `json:"group_id,omitempty"`
	AlgorithmID  uint8     `json:"algorithm_id"`
	KeyID        uint16    `json:"key_id"`
	At           time.Time `json:"at"`
}

type CallEndDTO struct {
	Grant        GrantDTO      `json:"grant"`
	Talkgroup    *TalkgroupDTO `json:"talkgroup,omitempty"`
	DeviceSerial string        `json:"device_serial"`
	StartedAt    time.Time     `json:"started_at"`
	EndedAt      time.Time     `json:"ended_at"`
	Reason       string        `json:"reason"`
}

type CallRow struct {
	ID             int64     `json:"id"`
	System         string    `json:"system"`
	Protocol       string    `json:"protocol"`
	GroupID        uint32    `json:"group_id"`
	SourceID       uint32    `json:"source_id"`
	FrequencyHz    uint32    `json:"frequency_hz"`
	Encrypted      bool      `json:"encrypted"`
	Emergency      bool      `json:"emergency"`
	DataCall       bool      `json:"data_call"`
	DeviceSerial   string    `json:"device_serial"`
	StartedAt      time.Time `json:"started_at"`
	EndedAt        time.Time `json:"ended_at,omitempty"`
	DurationMs     int64     `json:"duration_ms,omitempty"`
	EndReason      string    `json:"end_reason,omitempty"`
	TalkgroupAlpha string    `json:"talkgroup_alpha,omitempty"`
}

type CallStartDTO struct {
	Grant        GrantDTO      `json:"grant"`
	Talkgroup    *TalkgroupDTO `json:"talkgroup,omitempty"`
	DeviceSerial string        `json:"device_serial"`
	StartedAt    time.Time     `json:"started_at"`
}

type ConfigWriter interface {
	// WritePatch applies the patch to the backing config.yaml and
	// returns the merged config so callers can route hot-reloadable
	// fields to the in-memory applier.
	WritePatch(p config.Patch) (config.Config, error)
	// Path is the path to the config.yaml the writer mutates.
	// Empty means "no config file backs this daemon" (the SPA / TUI
	// should render the Settings panel read-only).
	Path() string
}

type ConvChannelStatusDTO struct {
	Index       int       `json:"index"`
	Label       string    `json:"label"`
	FrequencyHz uint32    `json:"frequency_hz"`
	Mode        string    `json:"mode"`
	Active      bool      `json:"active"`
	LockedOut   bool      `json:"locked_out,omitempty"`
	LastBreakAt time.Time `json:"last_break_at,omitempty"`
}

type ConvScannerStatusDTO struct {
	Enabled      bool                   `json:"enabled"`
	State        string                 `json:"state,omitempty"`
	DeviceSerial string                 `json:"device_serial,omitempty"`
	CursorIndex  int                    `json:"cursor_index,omitempty"`
	Channels     []ConvChannelStatusDTO `json:"channels"`
}

type DSCMessageDTO struct {
	ID         int64     `json:"id"`
	ReceivedAt time.Time `json:"received_at"`
	Format     string    `json:"format"`
	Category   string    `json:"category"`
	SelfMMSI   uint64    `json:"self_mmsi"`
	TargetMMSI uint64    `json:"target_mmsi,omitempty"`
	Nature     string    `json:"nature,omitempty"`
	TimeUTC    string    `json:"time_utc,omitempty"`

	Latitude    float64 `json:"latitude,omitempty"`
	Longitude   float64 `json:"longitude,omitempty"`
	HasPosition bool    `json:"has_position"`

	Body   string `json:"body,omitempty"`
	RawHex string `json:"raw_hex,omitempty"`
}

type DSCProvider interface {
	RecentDSCMessages(limit int) ([]storage.DSCMessage, error)
}

type DevicesProvider interface {
	Snapshot() []sdr.SDRStatus
}

type DiagProvider interface {
	// OpenIQStream starts a per-request decimator on the named
	// device. TargetRateSPS clamps the output rate (≤ device
	// sample_rate). Returns the wire-frame channel and a cleanup
	// func the caller MUST invoke on disconnect.
	OpenIQStream(ctx context.Context, serial string, targetRateSPS uint32) (<-chan IQFrame, func(), error)
}

type EngineMutator interface {
	EndCall(deviceSerial string, reason trunking.EndReason) bool
}

type EngineSnapshot interface {
	ActiveCalls() []*trunking.ActiveCall
}

type EventDTO struct {
	Kind      string    `json:"kind"`
	Timestamp time.Time `json:"timestamp"`
	Payload   any       `json:"payload"`
}

type GRPCServer struct {
	apiv1.UnimplementedSystemServiceServer
	apiv1.UnimplementedTalkgroupServiceServer
	apiv1.UnimplementedRIDServiceServer
	apiv1.UnimplementedAudioServiceServer
	// contains filtered or unexported fields
}

type GRPCServerOptions struct {
	Addr       string
	Systems    []trunking.System
	Talkgroups *trunking.TalkgroupDB
	// RIDs is the operator-configured radio-ID alias table. When nil
	// the server allocates an empty one so RIDService still serves a
	// stable shape.
	RIDs *trunking.RIDDB
	// Affiliations is the read side of the affiliation tracker —
	// supplies the live UnitActivity overlay for RIDService. Optional.
	Affiliations AffiliationProvider
	// History supplies per-RID call history for ListRIDHistory.
	// Optional; without it ListRIDHistory returns Unavailable.
	History HistoryQuery
	Engine  EngineSnapshot
	// Audio is the optional AudioPublisher backing StreamAudio.
	// When nil the RPC still registers (so clients don't churn
	// at the wire-protocol layer if audio is configured off) but
	// returns Unavailable rather than streaming frames.
	Audio *AudioPublisher
	Log   *slog.Logger
	// TLSCert and TLSKey, when both non-empty, switch the gRPC
	// server to TLS using credentials.NewServerTLSFromFile. Same
	// disk-loaded-once semantics as the HTTP server's TLS support.
	// Leave both empty for plain TCP (default; appropriate for
	// loopback / private-network deployments).
	TLSCert string
	TLSKey  string
}

type GrantDTO struct {
	System        string `json:"system"`
	Protocol      string `json:"protocol"`
	GroupID       uint32 `json:"group_id"`
	SourceID      uint32 `json:"source_id"`
	FrequencyHz   uint32 `json:"frequency_hz"`
	ChannelID     uint8  `json:"channel_id,omitempty"`
	ChannelNumber uint16 `json:"channel_number,omitempty"`
	Encrypted     bool   `json:"encrypted,omitempty"`
	Emergency     bool   `json:"emergency,omitempty"`
	DataCall      bool   `json:"data_call,omitempty"`
	// AlgorithmID / KeyID surface the P25 encryption parameters
	// recovered from the in-call signalling. Zero when Encrypted is
	// false; also zero on a Phase 1 grant until the LDU2 Encryption
	// Sync has been parsed and the engine has backfilled the active
	// call (see KindCallEncryption).
	AlgorithmID uint8  `json:"algorithm_id,omitempty"`
	KeyID       uint16 `json:"key_id,omitempty"`
}

type HealthDTO struct {
	// Status is always "ok" for a serving daemon — present so old
	// callers that only check `.status == "ok"` keep working.
	Status string `json:"status"`
	// Now is the daemon-side timestamp in UTC. Useful for detecting
	// clock skew between probe and daemon.
	Now time.Time `json:"now"`
	// Version is the daemon build version, redundant with the
	// dedicated /api/v1/version endpoint but useful so probes can
	// confirm process identity in one round-trip.
	Version string `json:"version,omitempty"`
	// PoolAttachedCount is the number of currently-attached SDR
	// devices. Zero means no Devices provider is wired OR every
	// device has detached — both are operator-actionable signals.
	PoolAttachedCount int `json:"pool_attached_count"`
	// ActiveCalls is the count of in-flight voice calls.
	ActiveCalls int `json:"active_calls"`
	// DBConnected reports whether the call-history database is
	// wired. A daemon configured without `db_path` legitimately
	// runs with DBConnected = false.
	DBConnected bool `json:"db_connected"`
	// MetricsEnabled reports whether /metrics is mounted.
	MetricsEnabled bool `json:"metrics_enabled"`
	// AuthMode echoes the bearer-token auth policy
	// ("auto" / "required" / "disabled") so probes can flag a
	// misconfigured production deployment.
	AuthMode string `json:"auth_mode,omitempty"`
}

type HistoryFilter struct {
	System    string
	GroupID   uint32
	SourceID  uint32
	Since     time.Time
	Until     time.Time
	Limit     int
	OnlyEnded bool
}

type HistoryQuery interface {
	History(ctx context.Context, f HistoryFilter) ([]CallRow, error)
}

type IQFrame struct {
	TimestampNs  int64     `json:"ts_ns"`
	SampleRateHz uint32    `json:"sample_rate"`
	CenterHz     uint32    `json:"center_hz"`
	Points       []IQPoint `json:"points"`
	EnergyDBFS   float32   `json:"energy_dbfs"`
}

type IQPoint struct {
	I float32 `json:"i"`
	Q float32 `json:"q"`
}

type ImportCommitResult struct {
	SystemsAdded    []string `json:"systems_added"`
	SystemsReplaced []string `json:"systems_replaced"`
	CSVPaths        []string `json:"csv_paths,omitempty"`
	ConfigPath      string   `json:"config_path,omitempty"`
}

type ImportPreviewResponse struct {
	ID      string            `json:"id"`
	Systems []ParsedSystemDTO `json:"systems"`
}

type ImportSource struct {
	Filename string
	Kind     ImportSourceKind
	Data     []byte
}

type ImportSourceKind string

type Importer interface {
	// Parse runs the relevant parser (PDF or CSV) against the
	// supplied source and returns a preview DTO.
	Parse(s ImportSource) (ParsedSystemDTO, error)
	// Commit finalises a previously-parsed batch by merging it
	// into config.yaml and refreshing the in-memory talkgroup DB.
	// The implementer is responsible for serialising commits with
	// any other config writer (settings PATCH) so two callers
	// can't race the on-disk file.
	Commit(sources []ImportSource, force bool) (ImportCommitResult, error)
}

type LocationFix struct {
	System     string  `json:"system"`
	Protocol   string  `json:"protocol"`
	RadioID    uint32  `json:"radio_id"`
	Talkgroup  uint32  `json:"talkgroup"`
	Latitude   float64 `json:"latitude"`
	Longitude  float64 `json:"longitude"`
	SpeedKnots float64 `json:"speed_knots"`
	HeadingDeg float64 `json:"heading_deg"`
	ReportedAt string  `json:"reported_at"` // RFC3339
}

type LocationQuery interface {
	RecentLocations(limit int) ([]LocationFix, error)
}

type M17LinkSetupDTO struct {
	ID         int64     `json:"id"`
	ReceivedAt time.Time `json:"received_at"`
	Src        string    `json:"src"`
	Dst        string    `json:"dst"`
	Mode       string    `json:"mode"`
	CAN        uint8     `json:"can"`
	Meta       string    `json:"meta,omitempty"`
	CRCOK      bool      `json:"crc_ok"`
	Body       string    `json:"body,omitempty"`
}

type M17Provider interface {
	RecentM17LinkSetups(limit int) ([]storage.M17LinkSetup, error)
}

type MDC1200MessageDTO struct {
	ID         int64     `json:"id"`
	ReceivedAt time.Time `json:"received_at"`
	Op         uint8     `json:"op"`
	Arg        uint8     `json:"arg"`
	UnitID     uint16    `json:"unit_id"`
	Operation  string    `json:"operation,omitempty"`
	Body       string    `json:"body,omitempty"`
	RawHex     string    `json:"raw_hex,omitempty"`
	CRCOK      bool      `json:"crc_ok"`
}

type MDC1200Provider interface {
	RecentMDC1200Messages(limit int) ([]storage.MDC1200Message, error)
}

type ManualTuneRequest struct {
	FrequencyHz uint32  `json:"frequency_hz"`
	Label       string  `json:"label"`
	Mode        string  `json:"mode"`
	SquelchDbFS float64 `json:"squelch_dbfs"`
	HangtimeMs  int     `json:"hangtime_ms"`
}

type PagerMessageDTO struct {
	ID         int64     `json:"id"`
	ReceivedAt time.Time `json:"received_at"`
	Protocol   string    `json:"protocol"`
	RIC        uint32    `json:"ric"`
	Func       uint8     `json:"func"`
	Encoding   string    `json:"encoding"`
	Body       string    `json:"body"`
	Corrected  int       `json:"corrected"`
}

type PagerProvider interface {
	RecentPagerMessages(limit int) ([]storage.PagerMessage, error)
}

type ParsedSystemDTO struct {
	Name        string                 `json:"name"`
	Location    string                 `json:"location,omitempty"`
	County      string                 `json:"county,omitempty"`
	SysID       string                 `json:"sysid,omitempty"`
	WACN        string                 `json:"wacn,omitempty"`
	SystemType  string                 `json:"system_type,omitempty"`
	Protocol    string                 `json:"protocol"`
	SiteCount   int                    `json:"site_count"`
	TalkgroupCt int                    `json:"talkgroup_count"`
	SourcePath  string                 `json:"source_path,omitempty"`
	Extra       map[string]interface{} `json:"extra,omitempty"`
}

type PatchDTO struct {
	System     string    `json:"system"`
	Protocol   string    `json:"protocol"`
	SuperGroup uint32    `json:"super_group"`
	Members    []uint32  `json:"members"`
	Vendor     string    `json:"vendor,omitempty"`
	Add        bool      `json:"add"`
	At         time.Time `json:"at"`
}

type RIDDTO struct {
	ID          uint32 `json:"id"`
	Alias       string `json:"alias,omitempty"`
	Description string `json:"description,omitempty"`
	Tag         string `json:"tag,omitempty"`
	Group       string `json:"group,omitempty"`
	Owner       string `json:"owner,omitempty"`
	Priority    int    `json:"priority,omitempty"`
	Lockout     bool   `json:"lockout,omitempty"`
	Watch       bool   `json:"watch"`
	Icon        string `json:"icon,omitempty"`

	// Configured is true when this row is backed by an entry in the
	// static RIDDB (rid_alias_file). Used by the UI to distinguish
	// known radios from RIDs only ever seen over the air.
	Configured bool `json:"configured"`

	// Live observation fields — empty/zero when the RID has not been
	// seen since the daemon started (or since the affiliation tracker
	// swept it).
	System        string    `json:"system,omitempty"`
	Protocol      string    `json:"protocol,omitempty"`
	LastTalkgroup uint32    `json:"last_talkgroup,omitempty"`
	TalkerAlias   string    `json:"talker_alias,omitempty"`
	TalkerAliasAt time.Time `json:"talker_alias_at,omitempty"`
	CallCount     uint64    `json:"call_count,omitempty"`
	FirstSeen     time.Time `json:"first_seen,omitempty"`
	LastSeen      time.Time `json:"last_seen,omitempty"`
}

type RetentionSweeper interface {
	SweepOnce(ctx context.Context)
}

type RuntimeDTO struct {
	// API listener addresses (empty when disabled).
	HTTPAddr       string `json:"http_addr,omitempty"`
	GRPCAddr       string `json:"grpc_addr,omitempty"`
	WSPath         string `json:"ws_path,omitempty"`
	SSEPath        string `json:"sse_path,omitempty"`
	MetricsPath    string `json:"metrics_path,omitempty"`
	AllowMutations bool   `json:"allow_mutations"`

	// Daemon log + version.
	LogLevel  string `json:"log_level"`
	LogFormat string `json:"log_format"`
	Version   string `json:"version,omitempty"`

	// Storage paths (sanitised — paths only, never contents).
	StorageDBPath  string `json:"storage_db_path,omitempty"`
	StorageCCCache string `json:"storage_cc_cache,omitempty"`

	// Retention windows.
	RetentionCallLogDays int           `json:"retention_call_log_days"`
	RetentionFilesDays   int           `json:"retention_files_days"`
	RetentionInterval    time.Duration `json:"retention_interval_ns"`

	// Recording config.
	RecordingDir        string `json:"recording_dir,omitempty"`
	RecordingSampleRate int    `json:"recording_sample_rate"`
	RecordingWriteRaw   bool   `json:"recording_write_raw"`
	RecordingEQEnabled  bool   `json:"recording_eq_enabled"`
	RecordingEQTaps     int    `json:"recording_eq_taps,omitempty"`
	RecordingEQStepSize string `json:"recording_eq_step_size,omitempty"`

	// Audio runtime (mirrors AudioStatus but adds device list +
	// backend identity so operators can confirm whether the Linux
	// fallback path took effect).
	AudioEnabled       bool     `json:"audio_enabled"`
	AudioDevice        string   `json:"audio_device,omitempty"`
	AudioSampleRate    int      `json:"audio_sample_rate"`
	AudioBufferMs      int      `json:"audio_buffer_ms"`
	AudioBackends      []string `json:"audio_backends"`
	AudioDisableFallbk bool     `json:"audio_disable_fallback"`

	// SDR pool config (the live status is on /api/v1/devices).
	SDRSampleRate int      `json:"sdr_sample_rate"`
	SDRBackends   []string `json:"sdr_backends"`

	// Scanner config (the live state is on /api/v1/scanner).
	ScannerScanMode          string `json:"scanner_scan_mode"`
	ScannerCCHuntEnabled     bool   `json:"scanner_cc_hunt_enabled"`
	ScannerCCHuntDwellMs     int    `json:"scanner_cc_hunt_dwell_ms"`
	ScannerCCHuntBackoffMs   int    `json:"scanner_cc_hunt_backoff_ms"`
	ScannerCCMaxBackoffMs    int    `json:"scanner_cc_max_backoff_ms"`
	ScannerManualTuneEnabled bool   `json:"scanner_manual_tune_enabled"`

	// Tone-out profiles (names only, plus tone counts + cooldown).
	ToneProfiles []ToneProfileDTO `json:"tone_profiles,omitempty"`

	// Vocoder map by protocol — operator-facing names like
	// "p25-phase2" → "ambe2".
	VocoderMap map[string]string `json:"vocoder_map"`

	// MetricsEnabled mirrors metrics.enabled config.
	MetricsEnabled bool `json:"metrics_enabled"`

	// ConfigPath is the absolute path to the config.yaml backing this
	// daemon, or empty when the daemon was started without a -config
	// file. The SPA / TUI use it to gate the editable Settings panel:
	// empty = render read-only ("daemon running on built-in defaults").
	ConfigPath string `json:"config_path,omitempty"`
	// StartupWarnings carries the non-fatal observations the daemon
	// collected during NewDaemon (missing talkgroup CSV, SDR pool
	// failed to open, etc.). Surfaced so the SPA Dashboard can pin
	// them until the operator dismisses them.
	StartupWarnings []string `json:"startup_warnings,omitempty"`

	// HiddenTabs lists the navigation tab keys the operator switched
	// off via web.tabs in config. Both the web SPA and the TUI filter
	// these out of their nav. Empty/omitted means every tab is shown.
	HiddenTabs []string `json:"hidden_tabs,omitempty"`
}

type RuntimeProvider interface {
	Runtime() RuntimeDTO
}

type ScannerCockpit interface {
	// Status returns the unified read snapshot the TUI panel renders.
	Status() ScannerStatus
	// SetScanMode flips the global TG-scan-list mode at runtime.
	// Returns the previous mode for audit / UX feedback.
	SetScanMode(mode string) (prev string, err error)
	// HoldHunt / ResumeHunt / ForceRetuneHunt apply to a single
	// trunked system. Returns false when the system isn't configured.
	HoldHunt(system string) bool
	ResumeHunt(system string) bool
	ForceRetuneHunt(system string) bool
	// HoldConventional / ResumeConventional / DwellConventional
	// drive the conventional FM scanner. DwellConventional indexes
	// into the configured Channels list. The Hold/Resume operations
	// return false when the conventional scanner isn't configured.
	HoldConventional() bool
	ResumeConventional() bool
	DwellConventional(index int) bool
	// LockoutConventional / UnlockoutConventional toggle the per-
	// channel lockout flag the scan loop respects. Locked-out
	// channels are skipped by pickNextChannel. Returns false when
	// the conventional scanner isn't configured or the index is
	// out of range.
	LockoutConventional(index int) bool
	UnlockoutConventional(index int) bool
	// ManualTune appends a VFO-style temporary channel to the
	// conventional scanner and forces dwell on it. Returns the new
	// index + ok=true on success; ok=false when the conventional
	// scanner isn't configured (no Voice SDR carved out for it).
	ManualTune(req ManualTuneRequest) (index int, ok bool)
	// ClearManualTune removes a previously-added temp channel by
	// index. Returns false if the index isn't a temp channel or
	// the scanner isn't configured.
	ClearManualTune(index int) bool
}

type ScannerStatus struct {
	ScanMode            string                `json:"scan_mode"`
	Systems             []SystemHuntStatusDTO `json:"systems"`
	Conventional        ConvScannerStatusDTO  `json:"conventional"`
	TalkgroupScanCount  int                   `json:"tg_scan_count"`
	TalkgroupTotalCount int                   `json:"tg_total"`
}

type Server struct {
	// contains filtered or unexported fields
}

type ServerOptions struct {
	// Addr is the listen address (e.g. ":8080" or "127.0.0.1:9000").
	Addr       string
	Bus        *events.Bus
	Engine     EngineSnapshot
	Talkgroups *trunking.TalkgroupDB
	// RIDs is the operator-configured radio-ID alias table. When nil
	// the server allocates an empty one so the routes serve a stable
	// shape; the daemon passes a populated DB loaded from each
	// system's rid_alias_file.
	RIDs    *trunking.RIDDB
	Systems []trunking.System
	// History is optional. When non-nil the server exposes
	// GET /api/v1/calls/history.
	History HistoryQuery
	// Locations is optional. When non-nil the server exposes
	// GET /api/v1/locations for the web map.
	Locations LocationQuery
	// Affiliations is optional. When non-nil the server exposes
	// GET /api/v1/affiliations (the unit-activity table).
	Affiliations AffiliationProvider
	// MetricsHandler is optional. When non-nil it is mounted at
	// GET /metrics; the daemon passes internal/metrics.Metrics.Handler()
	// here. Decoupling via http.Handler keeps the api package free of a
	// hard dependency on the metrics package.
	MetricsHandler http.Handler
	Log            *slog.Logger
	// Version is reported by GET /api/v1/version.
	Version string
	// AllowMutations is the legacy mutation gate. Deprecated in
	// favour of Auth — set Auth.Mode = AuthModeDisabled to get the
	// same wide-open semantics, or AuthModeAuto / AuthModeRequired
	// for the bearer-token middleware. When Auth.Mode is the zero
	// value (AuthModeAuto) and AllowMutations is true, the daemon
	// emits a deprecation warning and treats the daemon as
	// AuthModeDisabled to preserve the existing behaviour.
	AllowMutations bool
	// Auth configures the mutation auth middleware. See AuthMode
	// for the policy semantics. Zero-value is AuthModeAuto, which
	// requires a token on non-loopback binds and bypasses the
	// check on loopback (peer-cred trust on a single-host
	// deployment).
	Auth AuthConfig
	// Mutator is the engine's write side (end call). Optional;
	// when nil the corresponding routes return 503.
	Mutator EngineMutator
	// Retention is the storage sweeper's write side (run a sweep
	// now). Optional.
	Retention RetentionSweeper
	// Tones is the tone-out detector's write side (reset per-device
	// match state). Optional.
	Tones ToneDetectorReset
	// Devices exposes the SDR pool snapshot for GET /api/v1/devices.
	// Optional; the route returns 503 when nil.
	Devices DevicesProvider
	// Scanner exposes the police-scanner cockpit (CC hunter,
	// conventional FM scanner, TG scan list) for GET + PATCH
	// /api/v1/scanner and the related mutation routes. Optional;
	// when nil, the routes return 503.
	Scanner ScannerCockpit
	// Audio exposes the live-audio player + recorder gate for
	// GET + PATCH /api/v1/audio. Optional; when nil, the routes
	// return 503.
	Audio AudioController
	// Broadcast exposes the outbound call-streaming subsystem's
	// counters for GET /api/v1/broadcast. Optional; when nil, the
	// route reports the subsystem as disabled.
	Broadcast BroadcastStatusProvider
	// Runtime exposes the read-only daemon config snapshot served at
	// GET /api/v1/runtime. The TUI's tabbed Settings inspector uses
	// it to surface every config knob. Optional; when nil, the
	// route returns 503.
	Runtime RuntimeProvider
	// ConfigWriter, when supplied, enables PATCH /api/v1/settings:
	// the daemon writes the operator's edits to config.yaml
	// (preserving comments) and feeds the result back to
	// SettingsApplier for hot-reload. nil disables the endpoint
	// (returns 503) so daemons started without a -config file don't
	// pretend the SPA's edits will persist.
	ConfigWriter ConfigWriter
	// SettingsApplier is the in-process hot-reload surface invoked
	// by handleSettingsPatch after the on-disk write succeeds.
	// Optional: when nil, every field is reported as
	// "restart_required" in the response.
	SettingsApplier SettingsApplier
	// Importer enables the live system-import endpoints
	// (POST /api/v1/import, POST /api/v1/import/{id}/commit,
	// DELETE /api/v1/import/{id}). nil disables the endpoints —
	// the daemon emits 503 so the SPA can present a clear "import
	// disabled" message.
	Importer Importer
	// WebAssets, when non-nil and containing an `index.html`, is
	// served from `/` (and as the SPA fallback for any non-/api
	// path). Set this to the embedded web/dist filesystem so the
	// daemon hosts the operator console without a sibling
	// gophertrunk-web/ directory. Leave nil to keep the SPA
	// out-of-process.
	WebAssets fs.FS
	// AudioPublisher, when non-nil, enables the
	// GET /api/v1/audio/stream HTTP endpoint that streams live
	// composed PCM as a continuous WAV body. Reuses the same
	// publisher that backs gRPC StreamAudio so the HTTP stream is
	// a parallel subscriber rather than a second fan-out.
	AudioPublisher *AudioPublisher
	// Spectrum, when non-nil, enables the
	// GET /api/v1/spectrum/devices read endpoint and the
	// WS /api/v1/spectrum/stream live FFT frame stream. The daemon
	// implements this on top of its iqtap.Broker map; nil keeps the
	// routes returning 503 so a build without SDRs doesn't pretend
	// to have a waterfall.
	Spectrum SpectrumProvider
	// Bookmarks, when non-nil, enables the
	// GET/POST/PATCH/DELETE /api/v1/bookmarks routes for operator-
	// managed conventional channel bookmarks. nil keeps the routes
	// returning 503. Wired by the daemon over the SQLite-backed
	// storage.BookmarkStore.
	Bookmarks BookmarkProvider
	// Diag, when non-nil, enables the
	// WS /api/v1/diag/iq decimated-IQ live stream that backs the
	// web Constellation panel. The daemon implements this over
	// the iqtap broker + internal/dsp/diag; nil keeps the route
	// returning 503.
	Diag DiagProvider
	// Pager, when non-nil, enables the
	// GET /api/v1/pager/messages route serving recent decoded
	// POCSAG (and eventually FLEX) pager messages. Wired by the
	// daemon over the SQLite-backed storage.PagerLog.
	Pager PagerProvider
	// APRS, when non-nil, enables the
	// GET /api/v1/aprs/packets route serving recent decoded
	// APRS / AX.25 packets. Wired by the daemon over the SQLite-
	// backed storage.APRSLog.
	APRS APRSProvider
	// AIS, when non-nil, enables the
	// GET /api/v1/ais/vessels route serving recent decoded
	// AIS messages. Wired by the daemon over the SQLite-backed
	// storage.VesselLog.
	AIS AISProvider
	// DSC, when non-nil, enables the
	// GET /api/v1/dsc/messages route serving recent decoded
	// marine DSC sequences. Wired by the daemon over the
	// SQLite-backed storage.DSCLog.
	DSC DSCProvider
	// M17, when non-nil, enables the
	// GET /api/v1/m17/linksetups route serving recent decoded M17
	// link-setup frames. Wired by the daemon over the SQLite-backed
	// storage.M17Log.
	M17 M17Provider
	// ADSB, when non-nil, enables the
	// GET /api/v1/adsb/aircraft route serving recent decoded
	// Mode-S frames. Wired by the daemon over the SQLite-backed
	// storage.AircraftLog.
	ADSB ADSBProvider
	// MDC1200, when non-nil, enables the
	// GET /api/v1/mdc1200/messages route serving recent decoded
	// MDC1200 signaling bursts. Wired by the daemon over the
	// SQLite-backed storage.MDC1200Log.
	MDC1200 MDC1200Provider
	// CORS configures the cross-origin middleware. Off when
	// AllowedOrigins is empty (the daemon emits no CORS headers).
	// Set this when the browser-served SPA is loaded from an
	// origin different to the daemon's (most commonly file://,
	// whose Origin header is the literal string "null").
	CORS CORSConfig
	// TLSCert and TLSKey, when both non-empty, switch the HTTP
	// server to TLS. Paths point at PEM-encoded files on disk that
	// the daemon reads at start-up. Leaving either empty serves
	// plain HTTP (the default — appropriate for loopback / private-
	// network deployments where the bearer-token auth gate is the
	// only protection on mutations).
	TLSCert string
	TLSKey  string
}

type SettingsApplier interface {
	SetLogLevel(level string) error
	SetAudioVolume(volume float32)
	SetAudioMuted(muted bool)
	SetAudioEnabled(enabled bool)
	SetRecordingEnabled(enabled bool)
	SetScannerScanMode(mode string) error
}

type SettingsPatchRequest struct {
	LogLevel  *string `json:"log_level,omitempty"`
	LogFormat *string `json:"log_format,omitempty"`

	APIHTTPAddr *string `json:"api_http_addr,omitempty"`
	APIGRPCAddr *string `json:"api_grpc_addr,omitempty"`
	APIAuthMode *string `json:"api_auth_mode,omitempty"`

	AudioEnabled  *bool    `json:"audio_enabled,omitempty"`
	AudioDevice   *string  `json:"audio_device,omitempty"`
	AudioVolume   *float32 `json:"audio_volume,omitempty"`
	AudioMuted    *bool    `json:"audio_muted,omitempty"`
	AudioBufferMs *int     `json:"audio_buffer_ms,omitempty"`

	RecordingsDir        *string `json:"recordings_dir,omitempty"`
	RecordingsSampleRate *uint32 `json:"recordings_sample_rate,omitempty"`
	RecordingsWriteRaw   *bool   `json:"recordings_write_raw,omitempty"`

	RetentionCallLogDays *int    `json:"retention_call_log_days,omitempty"`
	RetentionFilesDays   *int    `json:"retention_files_days,omitempty"`
	RetentionInterval    *string `json:"retention_interval,omitempty"`

	SDRSampleRate *uint32 `json:"sdr_sample_rate,omitempty"`

	ScannerScanMode          *string `json:"scanner_scan_mode,omitempty"`
	ScannerManualTuneEnabled *bool   `json:"scanner_manual_tune_enabled,omitempty"`
	ScannerCCHuntEnabled     *bool   `json:"scanner_cc_hunt_enabled,omitempty"`
	ScannerCCHuntDwellMs     *int    `json:"scanner_cc_hunt_dwell_ms,omitempty"`
	ScannerCCHuntBackoffMs   *int    `json:"scanner_cc_hunt_backoff_ms,omitempty"`
	ScannerCCHuntMaxBackoff  *int    `json:"scanner_cc_hunt_max_backoff_ms,omitempty"`

	StoragePath        *string `json:"storage_path,omitempty"`
	StorageCCCacheFile *string `json:"storage_cc_cache_file,omitempty"`

	MetricsEnabled *bool `json:"metrics_enabled,omitempty"`
}

type SettingsResponse struct {
	Applied         []string   `json:"applied"`
	RestartRequired []string   `json:"restart_required"`
	ConfigPath      string     `json:"config_path,omitempty"`
	Runtime         RuntimeDTO `json:"runtime"`
}

type SpectrumDevice struct {
	Serial       string `json:"serial"`
	Driver       string `json:"driver"`
	Product      string `json:"product,omitempty"`
	Role         string `json:"role"`
	CenterHz     uint32 `json:"center_hz"`
	SampleRateHz uint32 `json:"sample_rate_hz"`
}

type SpectrumFrame struct {
	TimestampNs  int64     `json:"ts_ns"`
	CenterHz     uint32    `json:"center_hz"`
	SampleRateHz uint32    `json:"sample_rate_hz"`
	Bins         []float32 `json:"bins"`
}

type SpectrumProvider interface {
	// Devices returns the list of SDRs that can be streamed.
	Devices() []SpectrumDevice
	// OpenStream starts a per-request producer for the given device.
	// FFTSize must be a positive power of two; fps caps the frame
	// rate (zero picks a default). Returns an output channel that
	// closes when ctx cancels or the device disappears, and a
	// cleanup func the caller MUST invoke on disconnect.
	OpenStream(ctx context.Context, serial string, fftSize int, fps float64) (<-chan SpectrumFrame, func(), error)
	// Tune programs the named SDR's centre frequency in Hz. Used by
	// the web panel's click-to-tune handler. Returns an error if the
	// serial isn't known or the underlying device rejects the value.
	Tune(serial string, centerHz uint32) error
}

type SystemDTO struct {
	Name            string   `json:"name"`
	Protocol        string   `json:"protocol"`
	ControlChannels []uint32 `json:"control_channels"`
	WACN            uint32   `json:"wacn,omitempty"`
	SystemID        uint16   `json:"system_id,omitempty"`
	RFSS            uint8    `json:"rfss,omitempty"`
	Site            uint8    `json:"site,omitempty"`

	// Per-protocol FEC opt-out surface. Empty strings indicate the
	// new spec-correct default is active (channel coding / FEC on
	// for every protocol). Non-empty values that parse to "off" /
	// "false" / "0" opt the operator into the legacy raw-bit path
	// per-protocol. The TUI Settings panel renders these so operators
	// can verify their config landed; runtime mutation is a follow-up
	// (currently requires editing config.yaml + restarting the
	// daemon).
	TETRAColourCode        uint32  `json:"tetra_colour_code,omitempty"`
	TETRAChannel           string  `json:"tetra_channel,omitempty"`
	TETRAChannelCoding     string  `json:"tetra_channel_coding,omitempty"`
	LTRFCSMode             string  `json:"ltr_fcs_mode,omitempty"`
	LTRManchesterMode      string  `json:"ltr_manchester_mode,omitempty"`
	P25Phase1DemodMode     string  `json:"p25_phase1_demod_mode,omitempty"`
	P25Phase2TrellisMode   string  `json:"p25_phase2_trellis_mode,omitempty"`
	P25Phase2RSMode        string  `json:"p25_phase2_rs_mode,omitempty"`
	P25Phase2ScramblerMode string  `json:"p25_phase2_scrambler_mode,omitempty"`
	NXDNViterbiMode        string  `json:"nxdn_viterbi_mode,omitempty"`
	NXDNDeviationHz        float64 `json:"nxdn_deviation_hz,omitempty"`
	EDACSBCHMode           string  `json:"edacs_bch_mode,omitempty"`
	MPT1327BCHMode         string  `json:"mpt1327_bch_mode,omitempty"`
	MPT1327CWSCTolerance   string  `json:"mpt1327_cwsc_tolerance,omitempty"`
	MotorolaBCHMode        string  `json:"motorola_bch_mode,omitempty"`
}

type SystemHuntStatusDTO struct {
	Name            string    `json:"name"`
	Protocol        string    `json:"protocol"`
	State           string    `json:"state"`
	AttemptedFreqHz uint32    `json:"attempted_freq_hz,omitempty"`
	AttemptIndex    int       `json:"attempt_index,omitempty"`
	TotalCandidates int       `json:"total_candidates,omitempty"`
	LockedFreqHz    uint32    `json:"locked_freq_hz,omitempty"`
	LockedAt        time.Time `json:"locked_at,omitempty"`
	NAC             uint16    `json:"nac,omitempty"`
	LastFailedAt    time.Time `json:"last_failed_at,omitempty"`
	BackoffMs       int       `json:"backoff_ms,omitempty"`
	LastGrantAt     time.Time `json:"last_grant_at,omitempty"`
}

type TalkgroupDTO struct {
	ID          uint32 `json:"id"`
	AlphaTag    string `json:"alpha_tag"`
	Description string `json:"description,omitempty"`
	Tag         string `json:"tag,omitempty"`
	Group       string `json:"group,omitempty"`
	Mode        string `json:"mode,omitempty"`
	Priority    int    `json:"priority,omitempty"`
	Lockout     bool   `json:"lockout,omitempty"`
	Scan        bool   `json:"scan"`
	Stream      bool   `json:"stream"`
	Record      bool   `json:"record"`
	Mute        bool   `json:"mute"`
	Icon        string `json:"icon,omitempty"`
}

type ToneDetectorReset interface {
	ResetDevice(serial string)
}

type ToneProfileDTO struct {
	Name      string        `json:"name"`
	AlphaTag  string        `json:"alpha_tag,omitempty"`
	Cooldown  time.Duration `json:"cooldown_ns"`
	ToneCount int           `json:"tone_count"`
}

type TuneRequest struct {
	CenterHz uint32 `json:"center_hz"`
}

type UnitRegistrationDTO struct {
	System   string `json:"system"`
	Protocol string `json:"protocol"`
	SourceID uint32 `json:"source_id"`
	WACN     uint32 `json:"wacn"`
	SystemID uint16 `json:"system_id"`
	Response string `json:"response"`
}