hunt

type Acquirer func(ctx context.Context, opts LiveHuntOptions) (src IQSource, release func(), err error)

type AutoGainOptions struct {
	Gains        []int             // tenths of dB to try; empty ⇒ defaultGainSet
	DwellSeconds float64           // capture per (freq, gain); 0 ⇒ 1.0
	Protocol     trunking.Protocol // force the decoder (skip identify) when known
	SampleRateHz float64
	AutoTune     bool
	Log          *slog.Logger
}

type Band struct {
	LowHz  uint32
	HighHz uint32
}

type BandPlanEntry struct {
	ChannelID   uint8  `json:"channel_id"`
	BaseHz      uint64 `json:"base_hz"`
	SpacingHz   uint32 `json:"spacing_hz"`
	BandwidthHz uint32 `json:"bandwidth_hz,omitempty"`
	TxOffsetHz  int64  `json:"tx_offset_hz,omitempty"`
}

type Candidate struct {
	FreqHz uint32  `json:"freq_hz"`
	SNRDb  float32 `json:"snr_db"`
	// IsWideband marks a stitched wideband-occupancy span (cellular/WiFi/wide
	// data) rather than a narrowband carrier. Such a span is named by allocation
	// + shape, not decoded.
	IsWideband bool `json:"is_wideband,omitempty"`
	// BwHz is the occupied bandwidth of a wideband span (0 for narrow carriers).
	BwHz uint32 `json:"bw_hz,omitempty"`
}

type CaptureInput struct {
	Path         string
	Format       siglab.SampleFormat
	SampleRateHz float64
	// FrequencyHz is the capture's nominal center frequency (informational;
	// the decoded lock frequency is what gets recorded).
	FrequencyHz uint32
	AutoTune    bool
	Conjugate   bool
	IQCorrect   bool
	// Protocol forces a decoder; trunking.ProtocolUnknown (the zero value)
	// triggers auto-identification across every protocol.
	Protocol trunking.Protocol
	// IdentifyMaxSamples caps the prefix the identifier scans (0 ⇒ a built-in
	// default prefix). Only consulted when Protocol is unknown.
	IdentifyMaxSamples int64
}

type CaptureReport struct {
	Path       string  `json:"path"`
	Protocol   string  `json:"protocol"`
	Confidence float64 `json:"confidence"`
	Locked     bool    `json:"locked"`
	ControlHz  uint32  `json:"control_hz,omitempty"`
	Talkgroups int     `json:"talkgroups"`
	// ErrorRate is the decode-error events per 1000 symbols from the decode
	// (siglab Signal.DecodeErrorRate), a protocol-neutral demod-quality proxy.
	// Zero when no signal analysis was produced. Used by the auto-gain sweep.
	ErrorRate float64 `json:"error_rate,omitempty"`
	// Encrypted is true when any grant on the control channel was encrypted;
	// EncType names the algorithm when known (e.g. AES-256, ADP/RC4), empty when
	// the protocol surfaces encryption without the ALGID (P25 P1 ALGID is in the
	// voice LDU2, not the CC grant).
	Encrypted  bool   `json:"encrypted,omitempty"`
	EncType    string `json:"enc_type,omitempty"`
	Skipped    bool   `json:"skipped"`
	SkipReason string `json:"skip_reason,omitempty"`
	Error      string `json:"error,omitempty"`
	// Verdict is the wideband survey's system-level summary line (set only by
	// DiscoverWideband). Empty for single-carrier captures.
	Verdict string `json:"verdict,omitempty"`
	// IdentityNote explains a locked P25 capture whose WACN/System ID are still
	// blank — naming which identity broadcasts decoded so the operator knows
	// whether to widen the dwell or improve the signal. Empty when identity
	// resolved (or the capture isn't a locked P25 control channel).
	IdentityNote string `json:"identity_note,omitempty"`
}

type DetectedSignal struct {
	FreqHz       uint32             `json:"freq_hz"`
	SNRDb        float32            `json:"snr_db"`
	OccupiedBwHz uint32             `json:"occupied_bw_hz"`
	Class        survey.SignalClass `json:"class"`
	Confidence   float64            `json:"confidence"`
	BaudHz       float64            `json:"baud_hz,omitempty"`

	// Inventory naming — the consolidated "what is this" the full-spectrum
	// survey shows for every signal, decodable or not.
	//   Name    — human label: the decoded protocol, else the best-guess signal
	//             from the reference catalog (sigref), else the modulation class.
	//   Service — what the frequency is allocated to (sigref allocation table).
	//   Purpose — what that service is used for.
	Name    string `json:"name,omitempty"`
	Service string `json:"service,omitempty"`
	Purpose string `json:"purpose,omitempty"`

	// Encrypted / EncType report whether the signal is encrypted and, when known,
	// the algorithm (AES-256, ADP/RC4, …). Set from the trunking decode's grants;
	// EncType is empty when the protocol exposes encryption without an ALGID.
	Encrypted bool   `json:"encrypted,omitempty"`
	EncType   string `json:"enc_type,omitempty"`

	// Wideband marks a signal far wider than a channel (cellular/WiFi/OFDM)
	// recovered by the occupancy-stitching pass. Such a signal is named and
	// captured but never decoded; OccupiedBwHz is its stitched bandwidth (a lower
	// bound when the signal ran past the swept range).
	Wideband bool `json:"wideband,omitempty"`

	// Decode summary — set by the router for the carriers it could decode.
	Trunking *TrunkingRef         `json:"trunking,omitempty"`
	Analog   *survey.AnalogReport `json:"analog,omitempty"`
	Pages    []survey.PageRef     `json:"pages,omitempty"`

	// Features carries the raw classifier measurements for diagnostics.
	Features survey.ClassFeatures `json:"features"`
	// Error notes a per-carrier failure (tune/capture), leaving Class as-is.
	Error string `json:"error,omitempty"`
}

type DiscoverConfig struct {
	Name          string
	State         string
	County        string
	Location      string
	MinConfidence float64 // skip auto-identified captures below this (0 ⇒ 0.40)
	Log           *slog.Logger
}

type DiscoveredChannel struct {
	FrequencyHz uint32  `json:"frequency_hz"`
	IsControl   bool    `json:"is_control"`
	Confidence  float64 `json:"confidence,omitempty"`
}

type DiscoveredSite struct {
	RFSS            uint8               `json:"rfss"`
	SiteID          uint8               `json:"site_id"`
	SiteName        string              `json:"site_name"`
	County          string              `json:"county,omitempty"`
	ControlChannels []DiscoveredChannel `json:"control_channels"`
	Secondary       []uint32            `json:"secondary,omitempty"`
	Neighbors       []NeighborRef       `json:"neighbors,omitempty"`
	// VoiceChannels are the distinct voice/traffic-channel frequencies (Hz)
	// seen granted on this site, resolved from each grant's (ChannelID,
	// ChannelNumber) against the band plan. Empty until a grant resolves.
	VoiceChannels []uint32 `json:"voice_channels,omitempty"`
}

type DiscoveredSystem struct {
	// Name is operator-assigned, or synthesized from the identity when blank.
	Name string `json:"name"`
	// Protocol is the trunking.Protocol.String() spelling (e.g. "p25").
	Protocol string `json:"protocol"`

	// P25 / generic identity. Zero ⇒ unknown.
	WACN     uint32 `json:"wacn,omitempty"`
	SystemID uint16 `json:"system_id,omitempty"`
	NAC      uint16 `json:"nac,omitempty"`

	// Identity carries the remaining per-protocol identity fields the decoder
	// surfaced (DMR ColorCode, NXDN RAN, TETRA MCC/MNC, Motorola/EDACS system
	// id, …) keyed by the decoder's field name. It is informational and is
	// rendered into the RR package.
	Identity map[string]any `json:"identity,omitempty"`

	// Geography — operator-supplied; used by the RR duplicate check and the
	// submission package.
	State    string `json:"state,omitempty"`
	County   string `json:"county,omitempty"`
	Location string `json:"location,omitempty"`

	Sites      []DiscoveredSite      `json:"sites"`
	Talkgroups []DiscoveredTalkgroup `json:"talkgroups"`
	BandPlan   []BandPlanEntry       `json:"band_plan,omitempty"`

	// Confidence is the min protocol-identification confidence across the
	// control channels folded into this system (0..1).
	Confidence float64   `json:"confidence"`
	FirstSeen  time.Time `json:"first_seen"`
	LastSeen   time.Time `json:"last_seen"`
}

type DiscoveredTalkgroup struct {
	Dec       uint32    `json:"dec"`
	Hex       string    `json:"hex"`
	Encrypted bool      `json:"encrypted,omitempty"`
	Count     int       `json:"count"`
	FirstSeen time.Time `json:"first_seen"`
}

type DuplicateHint struct {
	SID        int     `json:"sid"`        // RadioReference system id
	Name       string  `json:"name"`       // existing system name
	Reason     string  `json:"reason"`     // why it matched (WACN+SYSID, overlapping CC, name/county)
	Confidence float64 `json:"confidence"` // 0..1
}

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

type Format int

type FreqOffset struct {
	DiscoveredHz uint32 `json:"discovered_hz"`
	RRHz         uint32 `json:"rr_hz"`
	DeltaHz      int64  `json:"delta_hz"` // discovered - RR
}

type GainRecommendation struct {
	FreqHz          uint32      `json:"freq_hz"`
	BestGainTenthDB int         `json:"best_gain_tenth_db"`
	BestErrorRate   float64     `json:"best_error_rate"`
	Locked          bool        `json:"locked"`
	PerGain         []GainScore `json:"per_gain"`
}

type GainScore struct {
	GainTenthDB int     `json:"gain_tenth_db"`
	ErrorRate   float64 `json:"error_rate"`
	Locked      bool    `json:"locked"`
	Err         string  `json:"error,omitempty"`
}

type GainSettable interface {
	// SetGain sets the front-end gain in tenths of a dB (-1 ⇒ AGC).
	SetGain(tenthDB int) error
}

type IQSource interface {
	// Tune retunes the source to centerHz. Subsequent Capture calls return IQ
	// centered there.
	Tune(centerHz uint32) error
	// Capture returns the next n complex samples at the current center, or an
	// error (including ctx cancellation). Implementations may return fewer than
	// n only at end-of-stream, in which case they return what remains.
	Capture(ctx context.Context, n int) ([]complex64, error)
	// SampleRateHz is the source's IQ sample rate.
	SampleRateHz() uint32
}

type LiveHuntOptions struct {
	Source IQSource
	// Bands to sweep. Ignored when Candidates is non-empty.
	Bands []Band
	// Candidates, when set, are explicit control-channel frequencies to probe
	// directly (the sweep is skipped). Mirrors the offline -no-sweep path.
	Candidates []uint32
	// Protocol forces a decoder; trunking.ProtocolUnknown auto-identifies.
	Protocol trunking.Protocol
	// Survey selects the signal-survey pipeline (RunLiveSurvey): classify and
	// decode every detected carrier, not just trunking control channels. The
	// daemon Manager reads this to dispatch the right run.
	Survey bool
	// ClassifyConfig tunes the survey classifier thresholds. The zero value
	// uses survey.DefaultClassifyConfig.
	ClassifyConfig survey.ClassifyConfig
	// IdentifyMinConfidence, when > 0, skips the (expensive) trunking identify
	// for a digital carrier whose classifier confidence is below it — unless it
	// is at a paging baud. 0 ⇒ always identify (never drop a possible CC).
	IdentifyMinConfidence float64
	// ClassifyOnly records the classifier verdict for every carrier and skips
	// all decoding (trunking identify, paging, analog tone scan) for a fast
	// inventory.
	ClassifyOnly bool
	// SkipFreqs, when non-empty, drops candidate carriers whose center
	// frequency is already present (a resumed survey reads these from the
	// existing NDJSON output so it doesn't re-survey carriers it already has).
	SkipFreqs map[uint32]struct{}
	// PersistSurvey requests the daemon Manager stream this survey run's
	// classified carriers to a crash-safe NDJSON file (in ManagerOptions.SurveyDir),
	// so it can be resumed. Ignored for a plain (non-survey) hunt or when no
	// SurveyDir is configured. The CLI persists via its own -survey-ndjson flag.
	PersistSurvey bool
	// Resume, with PersistSurvey, preloads the frequencies already in the run's
	// NDJSON file into SkipFreqs so an interrupted survey continues.
	Resume bool
	// AutoGain requests a post-run gain sweep: after the hunt/survey, each locked
	// control channel is decoded across a set of front-end gains and the gain
	// minimising the decode error rate is recommended (advisory; nothing is
	// applied). Requires a gain-controllable, exclusively-held SDR — a no-op with
	// a clear note when the SDR is shared (the daemon's borrowed control SDR).
	AutoGain bool
	// AutoGainSet is the gain ladder to sweep (tenths of dB); empty uses a default.
	AutoGainSet []int
	// SurveyDeep hands narrowband carriers the blind classifier called analog
	// (am/nbfm/wfm ≤ NBFM bandwidth) to the authoritative siglab identify before
	// the analog tone scan, so a trunked DMR/TETRA/MPT control channel the blind
	// classifier missed is still discovered. Slower (an extra identify per
	// borderline carrier); the accurate-survey opt-in for digital-dense bands.
	SurveyDeep bool
	// Serial requests a specific SDR for the run. Empty ⇒ the daemon
	// auto-selects (spare SDR, else borrow the control SDR). Consumed by the
	// daemon Acquirer; RunLiveHunt itself ignores it (the IQSource is already
	// resolved by the time RunLiveHunt runs).
	Serial string
	// ConfirmBorrow authorizes a hunt that would borrow an SDR currently
	// decoding live wideband traffic (a widebandt2 engine). Borrowing retunes
	// that SDR, so the live control-channel + voice decode is suspended for the
	// hunt's duration. The daemon Acquirer refuses such a borrow unless this is
	// set, so the operator is prompted before knocking the live system offline
	// rather than having it happen silently. Consumed by the daemon Acquirer;
	// RunLiveHunt itself ignores it.
	ConfirmBorrow bool

	FFTSize    int
	SweepDwell time.Duration
	GuardFrac  float64
	PeakOpts   PeakOptions
	// DetectCarriers expands a wideband OFFLINE capture into every carrier it
	// contains (FFT peak-detect) instead of treating the whole file as one
	// channel — so an off-centre / non-dominant control channel is found and
	// the rest of the band is inventoried. Live sweeps already do this via the
	// SDR; this is the offline equivalent. Ignored for live runs.
	DetectCarriers bool
	// DetectWideband adds the wideband-occupancy pass to a live survey sweep:
	// signals far wider than a channel (cellular/WiFi/OFDM) are detected,
	// stitched across tunes, and surfaced as named-but-not-decoded inventory
	// rows. Off by default; the whole-device survey turns it on.
	DetectWideband bool
	// DetectEncryption runs an entropy triage on every digital carrier that no
	// decoder identified: a high-entropy, near-uniform recovered payload marks
	// the row encrypted (EncType "high-entropy (likely encrypted)"). Decoded
	// protocols already surface encryption from their grants; this covers the
	// unknown digital bursts. Off by default (adds a blind demod per carrier).
	DetectEncryption bool

	// DwellSeconds is how much IQ to capture per candidate for identify+decode.
	// 0 ⇒ 3 s.
	DwellSeconds float64
	// MaxDwellSeconds, when > DwellSeconds, lets a survey candidate extend its
	// capture (in DwellSeconds chunks) until carrier activity is seen or this
	// ceiling is reached — useful for bursty paging. 0 ⇒ a single fixed dwell.
	MaxDwellSeconds float64
	// MonitorSeconds, when > 0, switches each candidate from the buffered
	// fixed-dwell capture to a streaming long-dwell control-channel monitor:
	// live IQ is decoded in real time (bounded memory, no multi-GB capture) for
	// up to this many seconds, stopping early once identity + neighbors + band
	// plan settle. The short DwellSeconds prefix is still captured first to
	// identify the protocol. Opt-in: 0 ⇒ today's buffered behavior.
	MonitorSeconds float64
	MinConfidence  float64
	AutoTune       bool

	// SurveyAudioDir, when set, makes a survey write a WAV clip per active
	// analog-FM carrier into this directory.
	SurveyAudioDir string

	// System metadata for the resulting map.
	Name, State, County, Location string

	OnProgress func(LiveHuntProgress)
	// OnSignal, when set, is called once per classified carrier during a survey
	// run (RunLiveSurvey), after its decode summary is filled in. The daemon
	// uses it to publish per-signal events and to persist decoded pages; the CLI
	// leaves it nil. Ignored by RunLiveHunt.
	OnSignal func(DetectedSignal)
	Log      *slog.Logger
}

type LiveHuntPhase string

type LiveHuntProgress struct {
	Phase      LiveHuntPhase `json:"phase"`
	CenterHz   uint32        `json:"center_hz,omitempty"`
	CandidateN int           `json:"candidate_n,omitempty"`
	Candidates int           `json:"candidates,omitempty"`
	Detail     string        `json:"detail,omitempty"`
}

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

type ManagerOptions struct {
	// Acquire obtains the run's IQSource. Required.
	Acquire Acquirer
	Bus     *events.Bus
	Log     *slog.Logger
	// SurveyDir, when set, is the directory the manager streams a survey run's
	// classified carriers into as crash-safe NDJSON (one file per band set), so a
	// web survey can resume after an interruption. Empty disables persistence.
	SurveyDir string
}

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

type NeighborRef struct {
	RFSS          uint8  `json:"rfss"`
	Site          uint8  `json:"site"`
	ChannelID     uint8  `json:"channel_id,omitempty"`
	ChannelNumber uint16 `json:"channel_number,omitempty"`
	// FrequencyHz is the neighbour's control-channel frequency, resolved from
	// (ChannelID, ChannelNumber) against the system band plan at finish. Zero
	// when the band plan doesn't cover the channel (e.g. no IDEN_UP seen yet).
	FrequencyHz uint32 `json:"frequency_hz,omitempty"`
}

type Observation struct {
	// Protocol is the trunking.Protocol.String() spelling of the decoded CC.
	Protocol string
	// Confidence is the protocol-identification confidence (0..1). When the
	// protocol was supplied by the operator rather than auto-identified, pass
	// 1.0.
	Confidence float64
	// Result is the signal-lab decode of the capture. Lock + Grants + Events
	// are mined for identity and talkgroups.
	Result *siglab.Result
	// FallbackFreqHz is the capture's nominal center frequency, used as the
	// control-channel frequency when the decoder's lock payload doesn't carry
	// one (e.g. a baseband capture). 0 ⇒ no fallback.
	FallbackFreqHz uint32
	// At is the wall-clock time the capture was taken (defaults to now).
	At time.Time
}

type Occupancy = carriers.Occupancy

type OccupancyOptions = carriers.OccupancyOptions

type OnStep func(centerHz uint32, peaks []Peak)

type Peak = carriers.Peak

type PeakOptions = carriers.PeakOptions

type RRDiff struct {
	SID               int          `json:"sid"`
	Name              string       `json:"name"`
	FreqOffsets       []FreqOffset `json:"freq_offsets,omitempty"`
	FreqsNotInRR      []uint32     `json:"freqs_not_in_rr,omitempty"`
	TalkgroupsNotInRR []uint32     `json:"talkgroups_not_in_rr,omitempty"`
}

type RunState string

type RunStatus struct {
	RunID      int              `json:"run_id"`
	State      RunState         `json:"state"`
	Running    bool             `json:"running"`
	Mode       string           `json:"mode"` // "hunt" | "survey"
	Progress   LiveHuntProgress `json:"progress"`
	Sites      int              `json:"sites"`
	Talkgroups int              `json:"talkgroups"`
	SystemName string           `json:"system_name,omitempty"`
	// Signals is the classified-carrier inventory of a survey run (nil for a
	// plain hunt). It is the survey's primary result, rendered by the cockpit.
	Signals []DetectedSignal `json:"signals,omitempty"`
	Error   string           `json:"error,omitempty"`

	// GainRecommendations is the per-control-channel result of an -auto-gain run
	// (nil when auto-gain wasn't requested or no CC locked). GainNote explains
	// why auto-gain produced nothing (e.g. the SDR is shared).
	GainRecommendations []GainRecommendation `json:"gain_recommendations,omitempty"`
	GainNote            string               `json:"gain_note,omitempty"`

	StartedAt  time.Time `json:"started_at,omitempty"`
	FinishedAt time.Time `json:"finished_at,omitempty"`
}

type SignalSurvey struct {
	StartedAt  time.Time        `json:"started_at"`
	FinishedAt time.Time        `json:"finished_at"`
	Signals    []DetectedSignal `json:"signals"`
	// System is the trunked system accumulated from the trunk-control carriers,
	// or nil when none was found. It is exported exactly like a hunt result.
	System *DiscoveredSystem `json:"system,omitempty"`
}

type SurveyFormat int

type SweepOptions struct {
	Source IQSource
	Bands  []Band
	// FFTSize is the bins per step (power of two). 0 ⇒ 4096.
	FFTSize int
	// SweepDwell is how long to accumulate per step before detecting peaks.
	// Captures one FFT frame per ~10 ms of dwell, averaged. 0 ⇒ one frame.
	SweepDwell time.Duration
	// GuardFrac reserves this fraction of each step's bandwidth at the edges
	// (where the SDR rolloff lives) when advancing the center. 0 ⇒ 0.1.
	GuardFrac float64
	PeakOpts  PeakOptions
	// DetectWideband enables the wideband-occupancy pass: alongside the
	// narrowband peak detector, each step is scanned for contiguous occupancy
	// spans (OFDM cellular/WiFi blocks), and spans clipped at a step edge are
	// stitched across adjacent overlapping steps to recover a signal wider than
	// the tune. Off by default — the whole-device survey turns it on.
	DetectWideband bool
	// OccupancyOpts tune the wideband detector (see carriers.OccupancyOptions).
	// The sweeper supplies the sweep-wide floor itself, so FloorDbFS is ignored.
	OccupancyOpts OccupancyOptions
	// WidebandFullStepClipDb is how far a step's own noise floor must sit above
	// the sweep-wide floor before the whole step counts as occupied (a signal
	// too wide to leave any quiet region in one tune). 0 ⇒ 6 dB.
	WidebandFullStepClipDb float32
	Log                    *slog.Logger
}

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

type TrunkingRef struct {
	Protocol   string  `json:"protocol"`
	Confidence float64 `json:"confidence"`
	Locked     bool    `json:"locked"`
	ControlHz  uint32  `json:"control_hz,omitempty"`
	// Encrypted / EncType mirror the decode's grant encryption onto the
	// inventory row (also copied to DetectedSignal for the flat view).
	Encrypted bool   `json:"encrypted,omitempty"`
	EncType   string `json:"enc_type,omitempty"`
}