hunt

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

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"`
}

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"`
	Skipped    bool    `json:"skipped"`
	SkipReason string  `json:"skip_reason,omitempty"`
	Error      string  `json:"error,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"`

	// 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"`
}

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     // RadioReference system id
	Name       string  // existing system name
	Reason     string  // why it matched (WACN+SYSID, overlapping CC, name/county)
	Confidence float64 // 0..1
}

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

type Format int

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
	// 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

	FFTSize    int
	SweepDwell time.Duration
	GuardFrac  float64
	PeakOpts   PeakOptions

	// 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
	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
}

type NeighborRef struct {
	RFSS          uint8  `json:"rfss"`
	Site          uint8  `json:"site"`
	ChannelID     uint8  `json:"channel_id,omitempty"`
	ChannelNumber uint16 `json:"channel_number,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 OnStep func(centerHz uint32, peaks []Peak)

type Peak struct {
	FreqHz    uint32
	PowerDbFS float32
	SNRDb     float32
}

type PeakOptions struct {
	// ThresholdDb is the minimum power above the estimated noise floor for a
	// local maximum to count as a carrier. 0 ⇒ a sensible default (10 dB).
	ThresholdDb float32
	// MinSpacingHz is the minimum separation between reported peaks; when two
	// maxima fall closer than this the stronger one wins. 0 ⇒ 6.25 kHz (the
	// tightest trunking channel step).
	MinSpacingHz uint32
	// GuardBins drops this many bins at each band edge (rolloff) from
	// consideration. 0 ⇒ a default proportional to the FFT size.
	GuardBins int
}

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"`

	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
	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"`
}