trunking

type ActiveCall struct {
	Device      *VoiceDevice
	Grant       Grant
	Talkgroup   *TalkGroup
	StartedAt   time.Time
	LastHeardAt time.Time
	// EncReleaseAt is the deadline at which the encrypted-call-handling
	// policy (trunking.encrypted_calls mode: metadata) releases this
	// voice SDR. Zero means unarmed — either the call is clear, the mode
	// is follow/ignore, or the operator holds a decryption key for it.
	// Armed by ArmEncryptedRelease, cleared by DisarmEncryptedRelease,
	// and reaped by the engine watchdog via EncryptedReleasesDue. Issue
	// #711.
	EncReleaseAt time.Time
	// SignalDbFS is the call's mean received channel power in dBFS,
	// measured by the voice composer over the call's baseband IQ and
	// stamped in via UpdateSignal shortly before end-of-call. nil until
	// measured — calls ended by non-composer paths (watchdog timeout,
	// preemption, shutdown) leave it nil. See composer.boundaryTracker
	// for the semantics (channel power, not calibrated RSSI or SNR).
	SignalDbFS *float64
}

type Affiliation struct {
	System            string              // System name, matches trunking.System.Name
	Protocol          string              // "p25" / "dmr" / "nxdn"
	SourceID          uint32              // radio unit being affiliated
	GroupID           uint32              // talkgroup the unit is joining
	AnnouncementGroup uint32              // optional announcement-group association (0 if unused)
	Response          AffiliationResponse // accepted / failed / denied / refused
	// RFSSID and SiteID identify the P25 site that handled this
	// affiliation, decoded from the control channel's RFSS Status
	// Broadcast. Unlike a grant (announced on every site participating
	// in a wide-area call), an affiliation is handled by the radio's
	// actual serving site — so these are a genuine RID→site location
	// fix for mobility tracking (issue #698). NAC is the control
	// channel's Network Access Code (Phase 2: the NSB Color Code); it
	// is not unique per site, so consumers must key on (RFSSID, SiteID).
	// All three stay zero on non-P25 affiliations and until the site's
	// RFSS Status / Network Status broadcast has been decoded.
	RFSSID uint8
	SiteID uint8
	NAC    uint16
	At     time.Time
}

type AffiliationResponse uint8

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

type AffiliationTrackerOptions struct {
	Bus *events.Bus
	// TTL is how long a unit stays in the table after it was last
	// seen. Default 30 minutes.
	TTL time.Duration
	// Now is injectable for tests; defaults to time.Now.
	Now func() time.Time
}

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

type CachedSystem struct {
	LastFrequencyHz uint32    `json:"last_frequency_hz"`
	LastLockAt      time.Time `json:"last_lock_at,omitempty"`
	NAC             uint16    `json:"nac,omitempty"`
}

type CallComplete struct {
	Grant        Grant
	Talkgroup    *TalkGroup
	DeviceSerial string
	StartedAt    time.Time
	EndedAt      time.Time
	Reason       EndReason
	AudioPath    string
	SampleRate   uint32
}

type CallEncryption struct {
	DeviceSerial     string
	System           string // filled in by the engine on republish
	Protocol         string
	GroupID          uint32
	AlgorithmID      uint8
	KeyID            uint16
	MessageIndicator [9]byte
	At               time.Time
}

type CallEnd struct {
	Grant        Grant
	Talkgroup    *TalkGroup
	DeviceSerial string
	StartedAt    time.Time
	EndedAt      time.Time
	Reason       EndReason
	// SignalDbFS is the call's mean received channel power in dBFS,
	// measured by the voice composer over the call's baseband IQ. nil when
	// no measurement was taken (calls ended by the watchdog, preemption, or
	// shutdown, or decoded outside the composer). It is a channel-power /
	// RSSI-style figure — NOT calibrated absolute RSSI and NOT SNR/EVM.
	SignalDbFS *float64
}

type CallSegment struct {
	DeviceSerial string
	At           time.Time
}

type CallSourceUpdate struct {
	DeviceSerial string
	System       string // filled in by the engine on republish
	Protocol     string
	GroupID      uint32 // filled in by the engine on republish from the bound Grant
	SourceID     uint32
	Encrypted    bool
	At           time.Time
}

type CallStart struct {
	Grant        Grant
	Talkgroup    *TalkGroup // resolved via the engine's TalkgroupDB; nil if unknown
	DeviceSerial string     // which Voice SDR is following the call
	StartedAt    time.Time
}

type ConfiguredSite struct {
	RFSS uint8
	Site uint8
	Name string
}

type DMRBandPlan struct {
	Linear *DMRLinearBandPlan      // regular base+spacing grid
	Table  []DMRBandPlanTableEntry // irregular hand-coded LCN→Hz map
}

type DMRBandPlanTableEntry struct {
	LCN    uint16
	FreqHz uint32
}

type DMRLinearBandPlan struct {
	BaseHz    uint32
	SpacingHz uint32
	Offset    int8
}

type EncryptedMode uint8

type EndReason uint8

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

type EngineOptions struct {
	Bus        *events.Bus
	Log        *slog.Logger
	VoicePool  *VoicePool
	Talkgroups *TalkgroupDB
	// CallTimeout is how long a call can run without a Touch before
	// the watchdog reaps it. Default 30 s. The end reason depends on
	// whether the call ever decoded frames: EndReasonNormal when
	// frames arrived and the carrier later dropped (P25's natural
	// end-of-call mechanism, since the CC has no explicit channel
	// release); EndReasonTimeout when no frames ever arrived (silent
	// decode failure).
	CallTimeout time.Duration
	// Now is injectable for tests; defaults to time.Now.
	Now func() time.Time
	// ScanMode controls whether HandleGrant respects the per-talkgroup
	// Scan flag. Default ScanModeAll keeps every non-locked-out grant
	// flowing through; ScanModeList enforces the talkgroup scan list.
	ScanMode ScanMode
	// EncryptedModes maps system name -> how encrypted calls on that
	// system are handled. EncryptedFollow (the default for a system absent
	// from the map) holds a voice SDR for the full call (legacy
	// behaviour); EncryptedMetadata follows briefly then releases;
	// EncryptedIgnore never allocates a voice SDR to an encrypted call.
	// Per-system (trunking.systems[].encrypted_calls). Issue #711.
	EncryptedModes map[string]EncryptedMode
	// EncryptedFollows maps system name -> how long an encrypted call on
	// that system is followed under EncryptedMetadata before its voice SDR
	// is released, measured from when the call is first known to be
	// encrypted. A system absent from the map (or mapped to <= 0) uses
	// defaultEncryptedMetadataFollow (1.5 s). Issue #711.
	EncryptedFollows map[string]time.Duration
	// ConfiguredKeys maps system name -> set of configured encryption key
	// IDs. Calls whose KeyID matches are exempt from the encrypted-call
	// policy (always followed). nil disables the exemption. Issue #711.
	ConfiguredKeys map[string]map[uint16]bool
}

type FrequencyChecker interface {
	CanTune(hz uint32) bool
}

type Grant struct {
	System      string // System name, matches trunking.System.Name
	Protocol    string // "p25" / "dmr" / "nxdn"
	GroupID     uint32 // talkgroup or destination subscriber address
	SourceID    uint32 // originator (subscriber unit)
	FrequencyHz uint32 // voice channel frequency
	ChannelID   uint8  // raw channel ID (P25 band-plan ID, DMR LCN high)
	ChannelNum  uint16 // raw channel number within the ID
	// RFSSID and SiteID identify the P25 site whose control channel
	// granted the call, decoded from the site's RFSS Status Broadcast
	// (TSBK 0x3A) and accumulated in the control channel's NetworkModel.
	// They let downstream consumers (Prometheus exporters, dashboards)
	// label a grant by site instead of resolving the opaque ChannelID
	// against a manual lookup table (issue #698). Both stay zero on
	// non-P25 grants and until the first RFSS Status TSBK has landed.
	RFSSID uint8
	SiteID uint8
	// NAC is the control channel's Network Access Code (Phase 2: the
	// Network Status Broadcast Color Code, equal to the Phase 1 NAC per
	// spec). It is a coarse sanity-check field — not unique per site —
	// so site labelling must key on (RFSSID, SiteID) (issue #698). Zero
	// on non-P25 grants.
	NAC uint16
	// Timeslot identifies the TDMA logical channel a call occupies on
	// its carrier, 1-based: 0 = not applicable / unknown (P25 Phase 1,
	// NXDN, analog — frequency alone identifies the call), 1 = TS1,
	// 2 = TS2. DMR Tier III carries two independent calls on one
	// 12.5 kHz carrier (TS1 + TS2), so the engine treats
	// (FrequencyHz, Timeslot) as the call identity rather than
	// frequency alone. Populated by the protocol layer; the DMR CSBK
	// parser maps its 0-based slot bit (0 = TS1, 1 = TS2) onto this
	// 1-based convention so 0 stays reserved for "no slot".
	Timeslot  uint8
	Encrypted bool
	Emergency bool
	// DMRInterleavedVoice mirrors the system-level
	// trunking.System.DMRInterleavedVoice opt-in onto the grant so the
	// voice composer selects the 2-slot interleaved decoder and routes
	// this call to its timeslot by matching the embedded Link Control's
	// talkgroup to GroupID. Set by the DMR Tier III control channel;
	// false (the default) keeps the single-slot decoder. Ignored for
	// non-DMR grants.
	DMRInterleavedVoice bool
	// AlgorithmID and KeyID carry the encryption parameters the
	// protocol's privacy header advertises (the DMR PI header, etc.).
	// They are meaningful only when Encrypted is true and stay zero
	// until a privacy header has been parsed. Persisted to the call
	// log so an operator can see which key a recorded call needs.
	AlgorithmID uint8
	KeyID       uint16
	DataCall    bool // false = voice call (default)
	// Individual marks a grant whose GroupID is NOT a talkgroup but an
	// individual destination — a unit-to-unit target radio (WUID), a
	// telephone-interconnect target, or an SNDCP data unit. P25 group
	// talkgroups are 16-bit; these targets are 24-bit subscriber addresses,
	// so recording them as "talkgroups" produces phantom >16-bit entries
	// (e.g. a unit-to-unit call surfacing as bogus TG 140957). Discovery /
	// hunt skips individual grants when building the talkgroup list. False
	// (the default) for group calls and Motorola patch grants, which ARE
	// talkgroups.
	Individual bool
	// ProVoice marks the grant as an EDACS ProVoice (digital) call. The
	// vocoder is patent + trade-secret encumbered so we cannot ship a
	// built-in decoder; the recorder treats this flag as a directive to
	// emit a `.raw` frame sidecar regardless of its global WriteRaw
	// setting, so researchers can decode out-of-band.
	ProVoice bool
	// PatchedGroups, when non-empty, lists the member talkgroups of a
	// patch / dynamic-regroup super-group: the call on GroupID is
	// physically the shared traffic of these groups. The engine fills
	// it from its PatchRegistry so the call can be attributed to every
	// member. Empty for an ordinary (non-patched) grant.
	PatchedGroups []uint32
	// P25Phase1DemodMode mirrors the system-level
	// trunking.System.P25Phase1DemodMode setting so the voice composer
	// can pick the matching symbol-recovery path on grants for the
	// system (C4FM vs CQPSK / LSM). The control-channel decoder
	// already honours the setting via the ccdecoder connector; without
	// this field every voice grant landed in a hardcoded C4FM voice
	// receiver and never decoded on LSM-modulated simulcast sites
	// (issue #356 follow-up). Populated by the protocol layer when it
	// publishes the grant; ignored for non-P25-Phase-1 grants.
	P25Phase1DemodMode string
	// P25Phase2Decode carries the per-channel FEC parameters the voice
	// composer's Phase 2 chain needs to decode MAC PDUs that
	// interleave with voice subframes on the traffic channel (talker
	// alias, in-call signalling). Populated by the Phase 2 control
	// channel when publishing the grant; zero on non-Phase-2 grants.
	P25Phase2Decode P25Phase2Decode
	At              time.Time
	// CallID is a process-monotonic identifier the voice pool assigns when
	// it binds a device to this grant (VoicePool.Bind); a real handoff
	// (VoicePool.Retune) preserves it so a followed call keeps one identity.
	// It lets the downstream voice chain tag each decoded frame with the
	// call it belongs to and the recorder reject a frame whose CallID
	// doesn't match the open session — closing the cross-call audio-bleed
	// window when a voice-tap serial is immediately reused for the next
	// call. Zero on grants that never went through the voice pool (synthetic
	// / conventional follows); a zero-vs-zero match is a no-op, preserving
	// prior behaviour.
	CallID uint64
}

type HuntDiagnostics struct {
	// IQObserved is true when the decoder saw at least one IQ sample
	// for this system during the hunt. False is the strongest single
	// signal that the SDR isn't streaming at all.
	IQObserved bool `json:"iq_observed"`
	// IQSamples is the cumulative raw IQ sample count the decoder
	// processed for this system since it became the active pipeline.
	IQSamples int64 `json:"iq_samples"`
	// IQPowerDbFS is the last window-averaged IQ power in dBFS. Very
	// low (≲ -55) points at antenna / gain / USB; near 0 with a high
	// clip ratio is front-end overload.
	IQPowerDbFS float64 `json:"iq_power_dbfs"`
	// IQClipRatio is the last window's fraction of ADC-rail-clipped
	// samples — front-end overload when sustained (≳ 0.002).
	IQClipRatio float64 `json:"iq_clip_ratio"`
	// IQDCRatioDb is the last window's DC-bin power relative to total
	// channel power, in dB — an on-channel DC spike when ≳ -10.
	IQDCRatioDb float64 `json:"iq_dc_ratio_db"`
	// PipelineActive is true when a live decode pipeline for the
	// system's protocol was running during the hunt. (A protocol with
	// no wired pipeline sits in state=hunting rather than failing, so
	// this is rarely false on a real failure.)
	PipelineActive bool `json:"pipeline_active"`
	// Diagnosis is a one-line, human-readable best guess at the cause,
	// derived from the fields above. Empty when no decoder is wired.
	Diagnosis string `json:"diagnosis,omitempty"`
}

type HuntFailed struct {
	System    string    `json:"system"`
	At        time.Time `json:"at"`
	BackoffMs int       `json:"backoff_ms"`
	// Diagnostics is a best-effort IQ-health snapshot captured when the
	// hunt failed, so a `cchunt.failed` event/log explains *why* without
	// a round-trip to the operator. Zero value (and an empty Diagnosis)
	// when no decoder is wired to the supervisor — e.g. in unit tests.
	Diagnostics HuntDiagnostics `json:"diagnostics"`
}

type HuntProgress struct {
	System          string    `json:"system"`
	AttemptedFreqHz uint32    `json:"attempted_freq_hz"`
	AttemptIndex    int       `json:"attempt_index"`
	TotalCandidates int       `json:"total_candidates"`
	At              time.Time `json:"at"`
}

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

type HunterOptions struct {
	System System
	Tuner  Tuner
	Bus    *events.Bus
	Cache  *Cache
	Log    *slog.Logger
	// Dwell is how long to wait on each candidate before giving up.
	// Defaults to 3 seconds.
	Dwell time.Duration
}

type Location struct {
	System     string  // trunking system name
	Protocol   string  // "p25", "dmr", ...
	RadioID    uint32  // reporting subscriber unit
	Talkgroup  uint32  // associated talkgroup; 0 when not call-associated
	Latitude   float64 // decimal degrees, positive north
	Longitude  float64 // decimal degrees, positive east
	SpeedKnots float64 // 0 when not reported
	HeadingDeg float64 // 0 when not reported
	At         time.Time
}

type LockResult struct {
	System    string
	Frequency uint32
	NAC       uint16
	At        time.Time
}

type LockedPayload interface {
	LockedFrequencyHz() uint32
	LockedNAC() uint16
}

type NetworkReport struct {
	Name     string // system name/label ("" → "(unnamed)")
	Protocol string // "p25" etc.; uppercased in the header

	// Network identity.
	WACN     uint32
	SystemID uint32
	NAC      uint16
	LRA      uint8

	Sites []ReportSite // 1 for a single control channel; N for an aggregated hunt
	Bands []ReportBand // frequency bands (band plan), system-wide
}

type P25BandPlanEntry struct {
	ChannelID   uint8  // 0..15; matches the 4-bit IDEN_UP slot index
	BaseHz      uint64 // downlink base frequency for channel 0, Hz
	SpacingHz   uint32 // channel-to-channel step, Hz
	TxOffsetHz  int64  // signed uplink offset (uplink = downlink + offset), Hz
	BandwidthHz uint32 // informational; not consulted by BandPlan.Frequency
}

type P25Phase2Decode struct {
	Trellis    uint8
	RS         uint8
	Interleave uint8
	Scrambler  uint8
	Seed       uint64
}

type Patch struct {
	System     string
	Protocol   string
	SuperGroup uint32
	Members    []uint32
	Vendor     string
	Add        bool // true = patch now active, false = patch cancelled
	At         time.Time
}

type PatchGroup struct {
	SuperGroup uint32
	Members    []uint32
	Vendor     string // "motorola" | "harris"
	UpdatedAt  time.Time
}

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

type Protocol uint8

type RID struct {
	ID          uint32 `json:"id"`
	Alias       string `json:"alias"`
	Description string `json:"description,omitempty"`
	Tag         string `json:"tag,omitempty"`   // department / role
	Group       string `json:"group,omitempty"` // top-level grouping (agency)
	Owner       string `json:"owner,omitempty"` // operator/badge assigned to the radio
	Priority    int    `json:"priority,omitempty"`
	// Lockout marks the radio as stale / decommissioned / known-bad so
	// the UI can de-emphasise it. RIDs are not gated like talkgroups
	// today — Lockout is informational only.
	Lockout bool `json:"lockout,omitempty"`
	// Watch flags RIDs of operator interest so they can be surfaced in
	// a watch-list UI. Defaults to true on every loader so a plain
	// catalogue without a Watch column keeps every RID visible.
	Watch bool `json:"watch"`
	// Icon is an optional glyph identifier used by the operator UIs to
	// render a per-RID icon.
	Icon string `json:"icon,omitempty"`
}

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

type ReacquireFunc func(serial string) (Tuner, error)

type RegistrationResponse uint8

type ReportBand struct {
	ChannelID   uint8
	BaseHz      uint64
	SpacingHz   uint32
	BandwidthHz uint32
	TxOffsetHz  int64
	AccessTDMA  bool
}

type ReportChannel struct {
	ChannelID     uint8
	ChannelNumber uint16
	DownlinkHz    uint32
	UplinkHz      uint32
}

type ReportNeighbor struct {
	RFSS    uint8
	Site    uint8
	Channel ReportChannel
}

type ReportSite struct {
	RFSS        uint8
	Site        uint8
	LRA         uint8
	PrimaryCC   ReportChannel
	SecondaryCC []ReportChannel
	Neighbors   []ReportNeighbor
}

type ScanMode uint8

type SiteInfo struct {
	System           string `json:"system"`
	RFSSID           uint8  `json:"rfss_id"`
	SiteID           uint8  `json:"site_id"`
	ControlChannelHz uint32 `json:"control_channel_hz,omitempty"`
	// ControlChannelCarrierOffsetHz is the demod's measured carrier offset (Hz)
	// of the locked control carrier relative to the tuned centre, as of LastSeen.
	// A large value flags a control lock sitting well off the configured
	// frequency — e.g. an adjacent site bleeding through (issue #815).
	ControlChannelCarrierOffsetHz int32 `json:"control_channel_carrier_offset_hz,omitempty"`
	// ControlChannelTSBKErrorRate is the cumulative percentage of TSBK blocks
	// that failed Viterbi/CRC on this site's control channel, as of LastSeen —
	// a frame-error rate, not a pre-FEC bit-error rate (issue #858).
	// ControlChannelTSBKCount is the total attempts it was measured over; zero
	// means no TSBK data yet (fresh lock, or a non-TSBK Phase 2 path).
	ControlChannelTSBKErrorRate float64   `json:"control_channel_tsbk_error_rate,omitempty"`
	ControlChannelTSBKCount     int64     `json:"control_channel_tsbk_count,omitempty"`
	WACN                        uint32    `json:"wacn,omitempty"`
	SystemID                    uint16    `json:"system_id,omitempty"`
	FirstSeen                   time.Time `json:"first_seen"`
	LastSeen                    time.Time `json:"last_seen"`
}

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

type SiteTrackerOptions struct {
	Bus *events.Bus
	// Now is injectable for tests; defaults to time.Now.
	Now func() time.Time
}

type SiteUpdate struct {
	System           string
	RFSSID           uint8
	SiteID           uint8
	ControlChannelHz uint32
	// ControlChannelCarrierOffsetHz is the demodulator's measured carrier
	// offset (signed Hz) of the locked control carrier relative to the tuned
	// centre, as of this update. A large value means the locked carrier sits
	// well off the configured frequency — e.g. a stronger neighbouring site
	// bleeding through at 12.5 kHz spacing (issue #815) — so the reported site
	// identity may not belong to the configured frequency. Zero on demod paths
	// without an AFC stage (CQPSK) or when the offset is genuinely ~0.
	ControlChannelCarrierOffsetHz int32 `json:"control_channel_carrier_offset_hz,omitempty"`
	// ControlChannelTSBKErrorRate is the percentage (0..100) of TSBK blocks on
	// this control channel that failed Viterbi or CRC, cumulative since the
	// decoder started — a frame-error rate, not a pre-FEC bit-error rate. It
	// tracks decode quality independently of carrier lock: a well-locked carrier
	// at range can still show a high rate (issue #858). ControlChannelTSBKCount
	// is the total attempts the rate was measured over (the denominator, and a
	// confidence weight); zero means no TSBK has been attempted yet — a fresh
	// lock, or a non-TSBK path such as Phase 2 TDMA — and the rate is undefined.
	ControlChannelTSBKErrorRate float64 `json:"control_channel_tsbk_error_rate,omitempty"`
	ControlChannelTSBKCount     int64   `json:"control_channel_tsbk_count,omitempty"`
	WACN                        uint32
	SystemID                    uint16
	// Hex renderings of the identity numbers (P25 field convention),
	// alongside the decimal fields above so JSON consumers get both. Empty
	// when the corresponding value is unknown (zero).
	WACNHex     string `json:"WACNHex,omitempty"`
	SystemIDHex string `json:"SystemIDHex,omitempty"`
	RFSSIDHex   string `json:"RFSSIDHex,omitempty"`
	SiteIDHex   string `json:"SiteIDHex,omitempty"`
	// Topology, when non-nil, is the full network-configuration snapshot of the
	// camped site (identity + primary/secondary control channels + neighbours +
	// band plan) as of this update. It is built on the decoder's Process
	// goroutine and handed off here, so the SiteTracker can render the live
	// network-configuration report without touching the decoder's internals.
	Topology *TopologySnapshot
	At       time.Time
}

type System struct {
	Name            string
	Protocol        Protocol
	ControlChannels []uint32 // candidate CC frequencies in Hz
	WACN            uint32   // 20-bit Wide-Area Communication Network ID (P25)
	SystemID        uint16   // 12-bit system identifier (P25 SYSID)
	RFSS            uint8    // RF SubSystem ID (P25)
	Site            uint8    // Site ID

	// Sites is the operator's optional catalogue of human-readable site
	// names, keyed by (RFSS, Site), surfaced through GET /api/v1/sites
	// so a discovered P25 site can carry a name instead of an opaque
	// ID (issue #698). The decoder does not consult these — they are
	// pure presentation metadata merged into the sites listing.
	Sites []ConfiguredSite

	// TETRAColourCode is the low 30 bits of the extended colour code
	// the TETRA scrambler uses to seed its LFSR per ETSI EN 300 392-2
	// §8.2.5 ("ec" in the spec). The ccdecoder connector forwards this
	// into tetra.ControlChannel.SetColourCode under ChannelCodingOn.
	// Zero is valid only for BSCH (§8.2.5.2). For all other channel
	// types the colour code is the per-cell secret the descrambler
	// needs to recover the type-3 stream — leaving it at zero with
	// channel coding on produces garbage. Bits 30..31 are silently
	// ignored downstream.
	TETRAColourCode uint32
	// TETRAChannel selects which TETRA logical channel lives in each
	// burst window under ChannelCodingOn. Recognised values:
	// "sch/hd" | "sch/f" | "sch/hu" | "bsch" | "aach" (case-insensitive,
	// "/" optional). Empty defaults to "sch/hd" — the most common
	// signaling carrier for cc.locked / Grant events. Forwarded into
	// tetra.ControlChannel.SetExpectedChannel by the ccdecoder
	// connector after parsing via tetra.ParseChannelType.
	TETRAChannel string
	// TETRAChannelCoding gates the full ETSI EN 300 392-2 §8.3.1
	// channel-coding chain (descramble + deinterleave + depuncture +
	// Viterbi + CRC-16 verify + tail strip). Recognised values
	// (case-insensitive): "" / "on" / "true" / "1" → ChannelCodingOn
	// (the new default; required for live on-air captures); "off" /
	// "false" / "0" → ChannelCodingOff (legacy raw-dibit path, opt-out
	// for operators feeding pre-stripped DSD-FME / OP25 fixtures).
	// Forwarded into tetra.ControlChannel.SetChannelCoding by the
	// ccdecoder connector after parsing via tetra.ParseChannelCoding.
	TETRAChannelCoding string

	// LTRFCSMode enables CRC-7 FCS verification on the LTR Status
	// Ingest path (per DSheirer/sdrtrunk's CRCLTR.java layout).
	// Recognised values (case-insensitive): "" / "on" / "true" / "1" →
	// FCSOn (the new default; drop Status words whose 7-bit FCS
	// trailer doesn't match the CRC over the 24-bit message vector);
	// "off" / "false" / "0" → FCSOff (no verification — opt-out for
	// pre-stripped fixtures). Forwarded into
	// ltr.ControlChannel.SetFCSMode by the ccdecoder connector after
	// parsing via ltr.ParseFCSMode.
	LTRFCSMode string
	// LTRManchesterMode controls Manchester decoding of the LTR
	// sub-audible bit stream. Recognised values (case-insensitive):
	// "" / "on" / "soft" → ManchesterSoft (the new default —
	// majority-decode each pair; matches the dominant on-air
	// encoding for sub-audible LTR signaling); "strict" —
	// require a mid-bit transition per pair, drop transition-less
	// pairs; "off" / "nrz" → ManchesterOff (raw NRZ — opt-out for
	// synthesized NRZ fixtures). Forwarded into
	// ltr.ControlChannel.SetManchesterMode by the ccdecoder
	// connector after parsing via ltr.ParseManchesterMode.
	LTRManchesterMode string

	// P25BandPlan seeds the Phase 1 receiver's BandPlan with operator-
	// supplied IdentifierUpdate entries before the decoder runs.
	// Useful for sites that don't broadcast an IDEN_UP TSBK for every
	// channel ID their grants reference (issue #345 — Mt Anakie
	// broadcasts grants on id=10 but never the matching IDEN_UP, so
	// the receiver has nothing to resolve the frequency against).
	// Over-the-air IDEN_UPs naturally override these via the same
	// BandPlan.Apply path; entries here are the floor, not the ceiling.
	// Ignored for non-P25-Phase-1 protocols.
	P25BandPlan []P25BandPlanEntry

	// DMRBandPlan resolves the LCN in DMR Tier III voice grants to a
	// downlink frequency. Required for T3 voice — without it every
	// grant is dropped with decode.error stage=no-bandplan. Ignored
	// for non-DMR-Tier-III protocols.
	DMRBandPlan *DMRBandPlan

	// DMRInterleavedVoice opts the system into the experimental 2-slot
	// interleaved voice decoder (mirrors config.System.DMRInterleavedVoice).
	// When true the DMR Tier III control channel tags its voice grants
	// so the composer decodes each timeslot from the carrier's
	// interleaved burst stream and routes it to the call by embedded-LC
	// talkgroup. Default false keeps the single-slot decoder. Pending a
	// real-capture cross-check of the on-air constants — see
	// docs/status.md. Ignored for non-DMR protocols.
	DMRInterleavedVoice bool

	// P25Phase1DemodMode selects the symbol-recovery path for the
	// P25 Phase 1 receiver. Recognised values (case-insensitive):
	// "" / "c4fm" / "fm" → DemodC4FM (the default — FM
	// discriminator + 4-level slicer; matches every previously
	// shipping config and works on conventional non-simulcast P25
	// transmitters); "cqpsk" / "lsm" / "linear" → DemodCQPSK (the
	// linear / LSM path — complex RRC + Gardner + differential
	// QPSK; required for simulcast P25 deployments whose control
	// channel transmits Linear Simulcast Modulation rather than
	// straight C4FM, see issue #275 and TIA-102.BAAA). Forwarded
	// into p25phase1rx.Options.DemodMode by the ccdecoder connector
	// after parsing via p25phase1rx.ParseDemodMode.
	P25Phase1DemodMode string

	// P25Phase2TrellisMode enables the 4-state ½-rate trellis FEC
	// decoder on the P25 Phase 2 MAC PDU window. Recognised values
	// (case-insensitive): "" / "on" / "true" / "1" → TrellisOn (the
	// new default — 146 channel dibits via the TIA-102.AABF trellis
	// decoder); "off" / "false" / "0" → TrellisOff (legacy 72-dibit
	// raw-MAC-PDU path, opt-out for pre-stripped fixtures). Forwarded
	// into p25phase2.ControlChannel.SetTrellisMode by the ccdecoder
	// connector after parsing via p25phase2.ParseTrellisMode.
	P25Phase2TrellisMode string
	// P25Phase2RSMode enables the outer Reed-Solomon RS(24, 16, 9)
	// verification layer on top of the trellis-decoded MAC PDU.
	// Recognised values (case-insensitive): "" / "off" / "false" /
	// "0" → RSOff (the default — no outer RS verification; matches
	// historical decoder behaviour); "on" / "true" / "1" → RSOn
	// (verify RS syndromes per TIA-102.BAAA-A §5.9; drop MAC PDUs
	// whose syndromes are non-zero before parsing). Forwarded into
	// p25phase2.ControlChannel.SetRSMode by the ccdecoder connector
	// after parsing via p25phase2.ParseRSMode.
	P25Phase2RSMode string
	// P25Phase2InterleaveMode enables the TIA-102.BBAC per-burst block
	// deinterleaver applied to the MAC-burst dibits before trellis
	// decoding. Recognised values (case-insensitive): "" / "off" /
	// "false" / "0" → InterleaveOff (the default); "on" / "true" / "1"
	// → InterleaveOn. Forwarded into p25phase2.ControlChannel.
	// SetInterleaveMode by the ccdecoder connector after parsing via
	// p25phase2.ParseInterleaveMode.
	P25Phase2InterleaveMode string
	// P25Phase2ScramblerMode enables the PN44 descrambler per
	// TIA-102.BBAC-1 §7.2.5 on the trellis-decoded MAC PDU bits.
	// Recognised values (case-insensitive): "" / "on" / "true" /
	// "1" → ScramblerOn (the default — live Phase 2 traffic is
	// always scrambled); "off" / "false" / "0" → ScramblerOff
	// (opt-out for unscrambled fixtures). The seed is computed from
	// (WACN, SystemID, low 12 bits of Site as the spec's Color
	// Code = NAC) per spec equation (5). Forwarded into
	// p25phase2.ControlChannel.SetScramblerMode +
	// SetScramblerSeed by the ccdecoder connector.
	P25Phase2ScramblerMode string
	// P25Phase2ClockMode selects the symbol-timing-recovery strategy
	// for the P25 Phase 2 receiver. Recognised values (case-
	// insensitive): "" / "gardner" / "on" → ClockGardner (the new
	// default — non-data-aided Gardner loop; recommended for live
	// SDR captures); "naive" / "off" → ClockNaive (decimate every
	// sps-th sample; works on sample-aligned synthesized IQ).
	// Forwarded into p25phase2rx.Options.ClockMode by the ccdecoder
	// connector after parsing via p25phase2rx.ParseClockMode.
	P25Phase2ClockMode string
	// TETRAClockMode mirrors P25Phase2ClockMode for the TETRA
	// receiver. Same recognised values + parser semantics; the
	// underlying ClockMode enums in the two receivers share the
	// same name + values but are independent types.
	TETRAClockMode string
	// NXDNViterbiMode enables the K=5 ½-rate Viterbi FEC decoder
	// on the NXDN CAC region. Recognised values (case-insensitive):
	// "" / "spec" → ViterbiSpec (the new default — full NXDN-TS-1-A
	// §4.5.1.1 outbound CAC chain); "on" / "true" / "1" → ViterbiOn
	// (intermediate 92-dibit K=5 Viterbi path for older
	// MMDVMHost / DSDcc fixtures); "off" / "false" / "0" → ViterbiOff
	// (legacy 44-dibit raw-CAC path, opt-out for pre-stripped
	// fixtures). Forwarded into nxdn.ControlChannel.SetViterbiMode
	// by the ccdecoder connector after parsing via
	// nxdn.ParseViterbiMode.
	NXDNViterbiMode string
	// NXDNDeviationHz overrides the peak frequency deviation (Hz)
	// the NXDN receiver's slicer is calibrated against. Spec value
	// is 1800 Hz (matches the FM-discriminator output level so live
	// captures slice correctly out of the box). Operators with
	// on-air captures whose dibit distribution is bimodal (outer
	// ±3 dominate, inner ±1 underrepresented) can override here —
	// see samples/nxdn/README.md for the calibration recipe.
	// Forwarded into nxdnrx.Options.DeviationHz by the ccdecoder
	// connector; values <= 0 fall back to the spec default.
	NXDNDeviationHz float64
	// EDACSBCHMode enables the BCH(40, 28, 2) FEC layer on the
	// EDACS CCW. Recognised values (case-insensitive): "" / "on" /
	// "true" / "1" → BCHOn (the new default — 40-bit on-wire
	// BCH(40, 28, 2) decode + single/double-bit correction); "off" /
	// "false" / "0" → BCHOff (legacy pre-stripped 40-bit CCW path,
	// opt-out for pre-stripped fixtures). Forwarded into
	// edacs.ControlChannel.SetBCHMode by the ccdecoder connector
	// after parsing via edacs.ParseBCHMode.
	EDACSBCHMode string
	// MPT1327BCHMode enables the BCH(63, 38) FEC layer on the MPT
	// 1327 codeword. Recognised values (case-insensitive): "" /
	// "on" / "true" / "1" → BCHOn (the new default — 64-bit on-wire
	// BCH(63, 38) decode); "off" / "false" / "0" → BCHOff (legacy
	// 38-bit pre-stripped codeword path, opt-out for pre-stripped
	// fixtures). Forwarded into mpt1327.ControlChannel.SetBCHMode
	// by the ccdecoder connector after parsing via
	// mpt1327.ParseBCHMode.
	MPT1327BCHMode string
	// MPT1327CWSCTolerance sets the Hamming-distance threshold the
	// MPT 1327 Process adapter uses when matching the 16-bit
	// Codeword Synchronisation Code. Recognised values
	// (case-insensitive): "" → 2-bit tolerance (the new default,
	// matches commercial MPT 1327 receivers on noisy on-air
	// captures); "0" / "exact" / "off" → exact match (for
	// pre-stripped synthesized fixtures); a decimal integer in
	// [0, 15]. Forwarded into mpt1327.ControlChannel.SetCWSCTolerance
	// by the ccdecoder connector after parsing via
	// mpt1327.ParseCWSCTolerance.
	MPT1327CWSCTolerance string
	// MotorolaBCHMode enables the BCH(64, 16, 11) FEC layer on the
	// Motorola Type II OSW. Recognised values (case-insensitive):
	// "" / "on" / "true" / "1" → BCHOn (the new default — two
	// 64-bit BCH(64, 16, 11) codewords reassembled into the 32-bit
	// OSW, with up to 11 bit errors corrected per codeword); "off" /
	// "false" / "0" → BCHOff (legacy 32-bit raw-OSW path, opt-out
	// for pre-stripped fixtures). Forwarded into
	// motorola.ControlChannel.SetBCHMode by the ccdecoder
	// connector after parsing via motorola.ParseBCHMode.
	MotorolaBCHMode string
	// DStarFECMode enables the JARL DV-mode header FEC chain on the
	// D-STAR Process adapter. Recognised values (case-insensitive):
	// "" / "off" / "false" / "0" → FECOff (the default — reads 328
	// info bits straight off the wire, matches synthesized fixtures
	// + pre-FEC-stripped inputs); "on" / "true" / "1" → FECOn (660
	// on-wire bits → deinterleave 22×30 → PN15 descramble →
	// depuncture → K=5 R=1/2 Viterbi → 328 info bits → ParseHeader).
	// Forwarded into dstar.ControlChannel.SetFECMode by the
	// ccdecoder connector after parsing via dstar.ParseFECMode.
	DStarFECMode string
}

type TalkGroup struct {
	ID          uint32 `json:"id"`
	AlphaTag    string `json:"alpha_tag"`
	Description string `json:"description,omitempty"`
	Tag         string `json:"tag,omitempty"`      // department / category
	Group       string `json:"group,omitempty"`    // top-level group
	Mode        string `json:"mode,omitempty"`     // D=digital, A=analog, M=mixed
	Priority    int    `json:"priority,omitempty"` // 1 = highest, 10 = lowest, 0 = unset
	Lockout     bool   `json:"lockout,omitempty"`
	Scan        bool   `json:"scan"`
	// Stream gates whether completed calls on this talkgroup are
	// uploaded to the outbound broadcast aggregators
	// (internal/broadcast). Defaults to true on every loader so a
	// legacy CSV/JSON without a Stream column keeps streaming every
	// call; an explicit "no"/"false" in the CSV (or `"stream": false`
	// in JSON) opts a sensitive talkgroup out of all feeds.
	Stream bool `json:"stream"`
	// Record gates whether calls on this talkgroup are written to
	// disk by the per-call WAV recorder. Defaults to true on every
	// loader; an explicit "no"/"false" excludes a talkgroup from
	// recording (the call is still followed and played live).
	Record bool `json:"record"`
	// Mute, when true, suppresses this talkgroup's calls from the
	// live audio player — the call is still followed, recorded, and
	// streamed, just not played on the host's speakers. Defaults to
	// false (not muted).
	Mute bool `json:"mute,omitempty"`
	// Icon is an optional icon name assigned to this talkgroup, used
	// by the operator UIs to render a per-talkgroup glyph (the data
	// model behind SDRtrunk's Icon Manager). Empty = default icon.
	Icon string `json:"icon,omitempty"`
}

type TalkerAlias struct {
	System   string // System name, matches trunking.System.Name
	Protocol string // "p25-phase2"
	SourceID uint32 // radio unit the alias names
	Alias    string // the reassembled display name
	// Unreliable is true when the decode passed CRC but the reassembled
	// alias held non-ASCII-printable characters — a hallmark of
	// bit-error corruption (#711). Consumers should surface it as
	// suspect rather than as a confirmed name.
	Unreliable bool
	At         time.Time
}

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

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

type TopoChannelRef struct {
	ChannelID     uint8  `json:"channel_id" yaml:"channel_id"`
	ChannelNumber uint16 `json:"channel_number" yaml:"channel_number"`
	FrequencyHz   uint32 `json:"frequency_hz,omitempty" yaml:"frequency_hz,omitempty"`
}

type TopoNeighborRef struct {
	RFSS          uint8  `json:"rfss" yaml:"rfss"`
	Site          uint8  `json:"site" yaml:"site"`
	ChannelID     uint8  `json:"channel_id,omitempty" yaml:"channel_id,omitempty"`
	ChannelNumber uint16 `json:"channel_number,omitempty" yaml:"channel_number,omitempty"`
	FrequencyHz   uint32 `json:"frequency_hz,omitempty" yaml:"frequency_hz,omitempty"`
}

type TopologyProvider interface {
	TopologySnapshot() *TopologySnapshot
}

type TopologySnapshot struct {
	// Display metadata (populated where the decoder knows it). These name the
	// run for the human-readable network-configuration report and are not part
	// of the topology's Empty() contract.
	SystemName string `json:"system_name,omitempty" yaml:"system_name,omitempty"`
	Protocol   string `json:"protocol,omitempty" yaml:"protocol,omitempty"`

	// P25 identity.
	WACN     uint32 `json:"wacn,omitempty" yaml:"wacn,omitempty"`
	SystemID uint32 `json:"system_id,omitempty" yaml:"system_id,omitempty"`
	NAC      uint16 `json:"nac,omitempty" yaml:"nac,omitempty"` // Network Access Code (P25)
	RFSS     uint8  `json:"rfss,omitempty" yaml:"rfss,omitempty"`
	Site     uint8  `json:"site,omitempty" yaml:"site,omitempty"`
	LRA      uint8  `json:"lra,omitempty" yaml:"lra,omitempty"`

	// PrimaryCC is the camped site's primary control channel (P25), with its
	// resolved downlink frequency when the band plan was known.
	PrimaryCC *TopoChannelRef `json:"primary_cc,omitempty" yaml:"primary_cc,omitempty"`

	// Per-protocol identity (populated where applicable).
	ColorCode    uint8  `json:"color_code,omitempty" yaml:"color_code,omitempty"`       // DMR
	RAN          uint8  `json:"ran,omitempty" yaml:"ran,omitempty"`                     // NXDN
	MCC          uint16 `json:"mcc,omitempty" yaml:"mcc,omitempty"`                     // TETRA
	MNC          uint16 `json:"mnc,omitempty" yaml:"mnc,omitempty"`                     // TETRA
	LocationArea uint16 `json:"location_area,omitempty" yaml:"location_area,omitempty"` // TETRA LA / NXDN location

	// Secondary control channels advertised for the camped site.
	Secondary []TopoChannelRef `json:"secondary,omitempty" yaml:"secondary,omitempty"`
	// Neighbors are adjacent sites the control channel advertised.
	Neighbors []TopoNeighborRef `json:"neighbors,omitempty" yaml:"neighbors,omitempty"`
	// BandPlan maps channel IDs to frequencies (P25 IDEN_UP and equivalents).
	BandPlan []TopoBandPlanSlot `json:"band_plan,omitempty" yaml:"band_plan,omitempty"`
}

type Tuner interface {
	SetCenterFreq(hz uint32) error
}

type UnitActivity struct {
	RadioID   uint32 `json:"radio_id"`
	Talkgroup uint32 `json:"talkgroup"`
	System    string `json:"system"`
	Protocol  string `json:"protocol"`
	// Explicit is true when the association came from a decoded
	// affiliation message (P25 Group Affiliation Response); false when
	// it was observed from a voice-channel grant naming the unit as
	// the source. Both are ground truth — a grant proves the unit is
	// transmitting on that talkgroup — but the distinction is useful
	// in the UI.
	Explicit bool `json:"explicit"`
	// Registered is true once the unit has been seen in a unit
	// registration message.
	Registered bool      `json:"registered"`
	FirstSeen  time.Time `json:"first_seen"`
	LastSeen   time.Time `json:"last_seen"`
	// CallCount counts grants observed for this unit since it entered
	// the table — a simple "recurring radio" signal for the RID list
	// (issue #376).
	CallCount uint64 `json:"call_count"`
	// TalkerAlias is the most-recently-decoded over-the-air talker
	// alias for this unit (the radio's own display name), distinct
	// from any operator-assigned alias in the RIDDB.
	TalkerAlias   string    `json:"talker_alias,omitempty"`
	TalkerAliasAt time.Time `json:"talker_alias_at,omitempty"`
	// TalkerAliasUnreliable is true when the stored alias decode passed
	// CRC but held non-ASCII-printable characters (bit-error
	// corruption, #711); a consumer should render it as suspect.
	TalkerAliasUnreliable bool `json:"talker_alias_unreliable,omitempty"`
}

type UnitRegistration struct {
	System   string               // System name, matches trunking.System.Name
	Protocol string               // "p25" / "dmr" / "nxdn"
	SourceID uint32               // radio unit's WUID
	WACN     uint32               // 20-bit Wide Area Communications Network ID
	SystemID uint16               // 12-bit system identifier
	Response RegistrationResponse // accepted / failed / denied / refused
	// RFSSID and SiteID identify the P25 site that handled this
	// registration — the radio's actual serving site, so a genuine
	// RID→site location fix for mobility tracking (issue #698). NAC is
	// the control channel's Network Access Code (Phase 2: the NSB Color
	// Code); not unique per site, so consumers must key on (RFSSID,
	// SiteID). All three stay zero on non-P25 registrations and until
	// the site's RFSS Status / Network Status broadcast has decoded.
	RFSSID uint8
	SiteID uint8
	NAC    uint16
	At     time.Time
}

type UnitToUnitRequest struct {
	System         string // System name, matches trunking.System.Name
	Protocol       string // "p25"
	SourceID       uint32 // calling unit
	TargetID       uint32 // called unit being asked to answer
	ServiceOptions uint8  // P25 service-options octet (priority / encryption flags)
	At             time.Time
}

type VoiceDevice struct {
	Tuner  Tuner
	Serial string
}

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