siglab

type Acceptance struct {
	// Lock, when non-nil, requires the run to (true) or to not (false) lock
	// the control channel.
	Lock *bool `json:"lock,omitempty" yaml:"lock,omitempty"`
	// LockLatencyMaxSec caps the time-to-first-lock (0 ⇒ unchecked).
	LockLatencyMaxSec float64 `json:"lock_latency_max_sec,omitempty" yaml:"lock_latency_max_sec,omitempty"`
	// LockFields are expected lock-payload fields (NAC, ColorCode,
	// SystemID, …). Values may be given as numbers or hex strings
	// ("0x293"); comparison is hex-tolerant. Matched as a subset of the
	// observed lock fields (and the common frequency_hz).
	LockFields map[string]any `json:"lock_fields,omitempty" yaml:"lock_fields,omitempty"`
	// MinGrants requires at least this many grants (0 ⇒ unchecked).
	MinGrants int `json:"min_grants,omitempty" yaml:"min_grants,omitempty"`
	// BaudTolerancePct caps |effective − expected| / expected (0 ⇒ unchecked).
	BaudTolerancePct float64 `json:"baud_tolerance_pct,omitempty" yaml:"baud_tolerance_pct,omitempty"`
	// MaxDecodeErrorRate caps decode errors per 1000 symbols (0 ⇒ unchecked).
	MaxDecodeErrorRate float64 `json:"max_decode_error_rate,omitempty" yaml:"max_decode_error_rate,omitempty"`
	// MaxEVMPct caps the demod error-vector magnitude percentage (0 ⇒
	// unchecked). Grades demod quality directly — a capture whose eye is too
	// closed fails even if it happens to lock.
	MaxEVMPct float64 `json:"max_evm_pct,omitempty" yaml:"max_evm_pct,omitempty"`
	// MinSNRdB requires the estimated demod SNR to be at least this many dB
	// (0 ⇒ unchecked).
	MinSNRdB float64 `json:"min_snr_db,omitempty" yaml:"min_snr_db,omitempty"`
}

type BandPlanSlot = trunking.TopoBandPlanSlot

type CCStatsBreakdown struct {
	NIDTrusted        int64 `json:"nid_trusted" yaml:"nid_trusted"`
	NIDMarginal       int64 `json:"nid_marginal" yaml:"nid_marginal"`
	NIDFailed         int64 `json:"nid_failed" yaml:"nid_failed"`
	TSBKDecoded       int64 `json:"tsbk_decoded" yaml:"tsbk_decoded"`
	TSBKTrellisFailed int64 `json:"tsbk_trellis_failed" yaml:"tsbk_trellis_failed"`
	TSBKCRCFailed     int64 `json:"tsbk_crc_failed" yaml:"tsbk_crc_failed"`
	// NetStatusSeen, RFSSStatusSeen, and AdjacentSeen count the identity
	// broadcasts decoded (0x3B / 0x3A / 0x3C). NetStatusSeen == 0 on a locked
	// CC explains a blank WACN/System ID: the periodic NSB never landed.
	NetStatusSeen  int64 `json:"net_status_seen" yaml:"net_status_seen"`
	RFSSStatusSeen int64 `json:"rfss_status_seen" yaml:"rfss_status_seen"`
	AdjacentSeen   int64 `json:"adjacent_seen" yaml:"adjacent_seen"`
	// LocRegSeen counts accepted Location Registration Responses (0x2B), the
	// high-rate RFSS/Site source. RFSS/Site resolved via LocRegSeen while
	// NetStatusSeen == 0 is the normal shape of a site that names itself in
	// registrations but withholds the WACN-bearing NSB.
	LocRegSeen int64 `json:"loc_reg_seen" yaml:"loc_reg_seen"`
}

type CandidateScore struct {
	Protocol       string  `json:"protocol"`
	Locked         bool    `json:"locked"`
	LockLatencySec float64 `json:"lock_latency_sec"`
	SyncHits       int     `json:"sync_hits"`
	SyncVariant    string  `json:"sync_variant"`
	ModalSpacing   int     `json:"modal_spacing"`
	FECPassRate    float64 `json:"fec_pass_rate"`
	Score          float64 `json:"score"`
	// contains filtered or unexported fields
}

type CarrierResult struct {
	OffsetHz     float64       `json:"offset_hz" yaml:"offset_hz"`
	FreqHz       uint32        `json:"freq_hz" yaml:"freq_hz"`
	SNRDb        float32       `json:"snr_db" yaml:"snr_db"`
	Protocol     string        `json:"protocol" yaml:"protocol"`
	Confidence   float64       `json:"confidence" yaml:"confidence"`
	Inconclusive bool          `json:"inconclusive" yaml:"inconclusive"`
	Locked       bool          `json:"locked" yaml:"locked"`
	Role         CarrierRole   `json:"role" yaml:"role"`
	ColorCode    uint8         `json:"color_code,omitempty" yaml:"color_code,omitempty"`
	SystemID     uint32        `json:"system_id,omitempty" yaml:"system_id,omitempty"`
	Grants       []GrantRecord `json:"grants,omitempty" yaml:"grants,omitempty"`
	Score        float64       `json:"score" yaml:"score"`

	// Blind / ReferenceMatches name a carrier that did NOT decode, via the
	// offline signal-ID reference DB (Protocol is blanked for such carriers and
	// Role is RoleUnknown). Populated from the per-carrier identify fallback.
	Blind            *blind.BlindEstimate `json:"blind,omitempty" yaml:"blind,omitempty"`
	ReferenceMatches []sigref.Match       `json:"reference_matches,omitempty" yaml:"reference_matches,omitempty"`
	// contains filtered or unexported fields
}

type CarrierRole string

type ChannelRef = trunking.TopoChannelRef

type Config struct {
	// Protocol selects the production pipeline to drive. Every protocol the
	// ccdecoder factory map registers is supported.
	Protocol trunking.Protocol
	// System carries per-protocol knobs (demod mode, colour code, band
	// plan, FEC modes, …) exactly as the daemon reads them off a configured
	// trunking.System. SystemName/FrequencyHz are surfaced separately
	// because every factory consumes them.
	System      trunking.System
	SystemName  string
	FrequencyHz uint32

	// SampleRateHz is the capture's IQ sample rate (input rate, before any
	// down-conversion). Required.
	SampleRateHz float64
	// Format is the on-disk sample encoding.
	Format SampleFormat

	// TuneHz frequency-shifts the capture so a channel at +TuneHz lands at
	// 0 Hz before demod. AutoTune estimates it from a prefix of the file
	// (and overrides TuneHz when set).
	TuneHz   float64
	AutoTune bool

	// Conjugate negates Q before channelization (spectrum-inverted /
	// I-Q-swapped front-end, issue #264). IQCorrect applies blind
	// I/Q-imbalance correction to the raw IQ before decimation (issue #402).
	Conjugate bool
	IQCorrect bool

	// CollectIQDiag enables the protocol-agnostic signal-quality analyzer
	// (symbol histogram, IQ imbalance, soft-sample distribution where
	// available). Off by default since it buffers per-symbol observations.
	CollectIQDiag bool

	// DemodMode is the P25 Phase 1 symbol-recovery path: "c4fm" (default) or
	// "cqpsk". Empty ⇒ c4fm.
	DemodMode string
	// NIDSearchSpan overrides the NID-alignment search radius in dibits
	// (issue #275 bisect knob). 0 ⇒ the production default.
	NIDSearchSpan int
	// EnableDDA opts the C4FM path into the experimental decision-directed
	// AFC (issue #402; off in production).
	EnableDDA bool
	// EnableAdaptiveSlicer opts the C4FM path into the adaptive slicer
	// (issue #402; off in production).
	EnableAdaptiveSlicer bool
	// EnableSoftSync opts the P25 control channel into the wider FSW-fallback
	// tolerance: sync words carrying 5–8 symbol errors are decoded if the
	// frame's TSBK CRC corroborates the NID, extending lock reach into
	// marginal-SNR captures. Gated by the existing NID/CRC validation, so it
	// cannot manufacture a false lock (issue #771; off in production).
	EnableSoftSync bool
	// CollectReceiverState captures a per-(stream-)second snapshot of the P25
	// receiver's AFC/AGC/clock/slicer state into the Result (the per-second
	// state log replay emitted to stderr, now structured + exportable).
	CollectReceiverState bool

	// ChunkSamples is the read-loop chunk size in IQ samples; 0 ⇒ default.
	ChunkSamples int

	// RecordDDCPath, when non-empty, writes the post-DDC narrowband IQ (the
	// exact channelized complex stream the receiver decodes, at the DDC output
	// rate — 144 kHz for TETRA, ~48 kHz for the C4FM family) to a two-channel
	// 16-bit baseband WAV at that path. This is the offline half of the "record
	// the digital down-converter output" tooling: point it at a fat 2.5/10 MS/s
	// cfile and it emits a small narrowband WAV that `replay -format wav`
	// decodes bit-for-bit the same way — a shareable, reproducible fixture that
	// is orders of magnitude smaller than the wideband capture. Empty ⇒ no
	// recording.
	RecordDDCPath string

	// CaptureIQ enables buffering a stride-decimated copy of the
	// post-DDC (channelized) IQ and the pre-slicer soft samples into
	// Result.IQTaps, so a web/visualization consumer can render the
	// constellation, spectrogram, PSD and eye diagram client-side. Off
	// by default since it is O(captured points) memory. The capture is
	// always decimated and hard-capped (see CaptureIQMaxPoints), so it
	// never ships full-rate IQ.
	CaptureIQ bool
	// CaptureIQMaxPoints caps the number of decimated IQ points (and,
	// separately, soft samples) retained when CaptureIQ is set. 0 ⇒
	// defaultCaptureIQMaxPoints. The read loop strides the channelized
	// stream so the retained density targets visualization fidelity
	// rather than faithful reconstruction.
	CaptureIQMaxPoints int

	// MaxSamples caps the number of input IQ samples processed (0 ⇒ whole
	// file). The signal identifier sets this to scan only a prefix of a
	// capture, bounding per-candidate cost regardless of capture length.
	MaxSamples int64

	// CollectPDUs retains a per-signaling-block dissection (Result.PDUs) of the
	// data PDUs the decoder parses — the data-over-RF inspector feed. Off by
	// default; P25 Phase 1 (TSBK) only for now. Capped at pduMaxRecords.
	CollectPDUs bool

	// Acceptance, when non-nil, is evaluated against the Result to produce a
	// pass/fail Verdict (the `test` harness sets it).
	Acceptance *Acceptance

	// Log receives the production pipeline's structured diagnostics. nil ⇒
	// a discard logger (the engine never wants a nil *slog.Logger reaching a
	// factory that does not nil-guard it).
	Log *slog.Logger
}

type DemodMetrics struct {
	// Modulation names the estimator that produced these numbers: "c4fm" (the
	// 4-level soft eye) or "cqpsk" (the complex π/4-DQPSK constellation).
	Modulation string `json:"modulation" yaml:"modulation"`
	// EVMPct is the RMS error-vector magnitude as a percentage of the ideal
	// symbol level. A clean lock sits at a few percent; it climbs toward the
	// inter-rail half-spacing (~33% for C4FM) as the eye closes.
	EVMPct float64 `json:"evm_pct" yaml:"evm_pct"`
	// SNREstimateDB is the symbol SNR implied by the residual, in dB. For
	// C4FM this is the post-discriminator soft-axis SNR (lower than the input
	// Es/N0 by the FM detection loss); for CQPSK it is the constellation SNR.
	// Capped at demodSNRCapDB for a noise-free synthetic input.
	SNREstimateDB float64 `json:"snr_estimate_db" yaml:"snr_estimate_db"`
	// SymbolsAnalyzed is the soft-sample count the estimate was formed over
	// (after the warmup skip).
	SymbolsAnalyzed int64 `json:"symbols_analyzed" yaml:"symbols_analyzed"`

	// PeakEVMPct is the worst single-symbol EVM (≥ EVMPct).
	PeakEVMPct float64 `json:"peak_evm_pct" yaml:"peak_evm_pct"`
	// MagErrPct / PhaseErrDeg split the error vector into its amplitude
	// (RMS magnitude error, %) and angular (RMS phase error, degrees) parts.
	MagErrPct   float64 `json:"mag_err_pct" yaml:"mag_err_pct"`
	PhaseErrDeg float64 `json:"phase_err_deg" yaml:"phase_err_deg"`
	// CarrierFreqErrorHz is the residual carrier-frequency error the receiver's
	// AFC/CQPSK loop settled at, in Hz (surfaced from the receiver, not
	// re-estimated). Zero when the deep receiver did not expose it.
	CarrierFreqErrorHz float64 `json:"carrier_freq_error_hz" yaml:"carrier_freq_error_hz"`
	// IQGainImbalanceDB / QuadratureErrorDeg are the I/Q gain imbalance and
	// quadrature-skew measured on the *recovered* constellation — distinct from
	// SignalQuality's pre-DDC front-end IQ figures.
	IQGainImbalanceDB  float64 `json:"iq_gain_imbalance_db" yaml:"iq_gain_imbalance_db"`
	QuadratureErrorDeg float64 `json:"quadrature_error_deg" yaml:"quadrature_error_deg"`
	// OriginOffsetPct is the residual DC (carrier-leakage) offset as a percent
	// of the reference radius.
	OriginOffsetPct float64 `json:"origin_offset_pct" yaml:"origin_offset_pct"`
	// EVMTrace is the per-symbol EVM% time series, stride-decimated to the IQ
	// cap. ErrorVectorSpectrum is the FFT-shifted magnitude spectrum (dB) of
	// the residual error vectors — a spur in it points at a periodic
	// impairment rather than white noise. Both omitempty so the CSV/summary
	// path is unaffected.
	EVMTrace            []float32 `json:"evm_trace,omitempty" yaml:"evm_trace,omitempty"`
	ErrorVectorSpectrum []float32 `json:"error_vector_spectrum,omitempty" yaml:"error_vector_spectrum,omitempty"`
}

type EventRecord struct {
	Seq       int            `json:"seq" yaml:"seq"`
	OffsetSec float64        `json:"offset_sec" yaml:"offset_sec"`
	Kind      string         `json:"kind" yaml:"kind"`
	Fields    map[string]any `json:"fields" yaml:"fields"`
}

type FECStat struct {
	Stage         string `json:"stage" yaml:"stage"`
	Frames        int    `json:"frames" yaml:"frames"`
	Clean         int    `json:"clean" yaml:"clean"`
	Corrected     int    `json:"corrected" yaml:"corrected"`
	Uncorrectable int    `json:"uncorrectable" yaml:"uncorrectable"`
	CRCPass       int    `json:"crc_pass,omitempty" yaml:"crc_pass,omitempty"`
	CRCFail       int    `json:"crc_fail,omitempty" yaml:"crc_fail,omitempty"`
}

type Format int

type GrantRecord struct {
	OffsetSec   float64 `json:"offset_sec" yaml:"offset_sec"`
	GroupID     uint32  `json:"group_id" yaml:"group_id"`
	SourceID    uint32  `json:"source_id" yaml:"source_id"`
	ChannelID   uint8   `json:"channel_id" yaml:"channel_id"`
	ChannelNum  uint16  `json:"channel_num" yaml:"channel_num"`
	Timeslot    uint8   `json:"timeslot" yaml:"timeslot"`
	FrequencyHz uint32  `json:"frequency_hz" yaml:"frequency_hz"`
	Encrypted   bool    `json:"encrypted" yaml:"encrypted"`
	// AlgorithmID / KeyID mirror trunking.Grant: the encryption algorithm id and
	// key selector when Encrypted (0 / 0 otherwise). They let the survey name the
	// encryption type (e.g. AES-256, ADP/RC4) rather than just "encrypted".
	AlgorithmID uint8  `json:"algorithm_id,omitempty" yaml:"algorithm_id,omitempty"`
	KeyID       uint16 `json:"key_id,omitempty" yaml:"key_id,omitempty"`
	Emergency   bool   `json:"emergency" yaml:"emergency"`
	// Individual mirrors trunking.Grant.Individual: the GroupID is a
	// unit-to-unit / telephone / data destination, not a talkgroup. Hunt
	// skips these when accumulating the talkgroup list.
	Individual bool `json:"individual,omitempty" yaml:"individual,omitempty"`
}

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

type IQTaps struct {
	// DecimatedIQ is the channelized IQ sampled every Stride samples.
	DecimatedIQ []IQPoint `json:"decimated_iq" yaml:"decimated_iq"`
	// SoftSamples is the pre-slicer soft-sample stream (deep P25 path);
	// empty for protocols/paths that do not emit soft samples.
	SoftSamples []float32 `json:"soft_samples" yaml:"soft_samples"`
	// DecimatedRateHz is the effective sample rate of DecimatedIQ
	// (PipelineRate / Stride).
	DecimatedRateHz float64 `json:"decimated_rate_hz" yaml:"decimated_rate_hz"`
	// Stride is the input-to-output downsample ratio applied to the
	// channelized stream.
	Stride int `json:"stride" yaml:"stride"`

	// SymbolDibits is the recovered-symbol decision stream (values
	// 0..SymbolCardinality-1), decimated to the same cap as the IQ. It
	// backs the offline Symbol-scope viz (the OP25-style time series).
	// Empty for protocols/paths that buffer no symbols.
	SymbolDibits []uint8 `json:"symbol_dibits,omitempty" yaml:"symbol_dibits,omitempty"`
	// SymbolSoft is the pre-slicer soft waveform aligned index-for-index
	// with SymbolDibits (deep P25 C4FM path). Empty when the demod path
	// emits no soft samples (e.g. CQPSK); the viz then shows the dibit
	// rows only.
	SymbolSoft []float32 `json:"symbol_soft,omitempty" yaml:"symbol_soft,omitempty"`
	// SymbolCardinality is 4 for the dibit (4-level) protocols, 2 for the
	// bit (2-level) protocols.
	SymbolCardinality int `json:"symbol_cardinality,omitempty" yaml:"symbol_cardinality,omitempty"`

	// DiffPhase is the per-symbol differential phase (radians, in (-π, π]) of
	// the complex constellation — angle(z[i]·conj(z[i-1])) — decimated to the
	// same cap as the IQ. It is the rotation signal that backs the offline
	// rotation-tracker viz: a π/4-DQPSK control channel clusters these around
	// ±π/4 and ±3π/4. Populated only on the CQPSK / π4-DQPSK path (the deep
	// constellation buffer); empty for C4FM and the 2-level paths.
	DiffPhase []float32 `json:"diff_phase,omitempty" yaml:"diff_phase,omitempty"`
}

type IdentifyConfig struct {
	SampleRateHz float64
	Format       SampleFormat
	AutoTune     bool
	Conjugate    bool
	IQCorrect    bool
	// MaxSamples caps the input samples each candidate processes (0 ⇒ whole
	// capture). Set it to scan a fast prefix when identifying.
	MaxSamples int64
	// Candidates restricts the protocols tried. nil ⇒ every registered
	// protocol whose channel rate fits the capture sample rate.
	Candidates []trunking.Protocol
	Log        *slog.Logger
}

type IdentifyResult struct {
	Source       string  `json:"source"`
	SampleRateHz float64 `json:"sample_rate_hz"`
	Winner       string  `json:"winner"`
	Confidence   float64 `json:"confidence"`
	Inconclusive bool    `json:"inconclusive"`
	// TuneHz is the carrier offset the winning candidate locked at — the one
	// the decode should reuse (under -auto-tune this may be an off-centre,
	// non-dominant carrier, not the band's loudest). 0 when no shift was used.
	TuneHz     float64          `json:"tune_hz"`
	Candidates []CandidateScore `json:"candidates"`

	// Blind / ReferenceMatches are the offline-signal-ID fallback, populated
	// only when the decode-based identification is Inconclusive: the blind
	// symbol-rate/modulation estimate and the reference-database candidates it
	// ranks (so an undecodable carrier is still named a best guess).
	Blind            *blind.BlindEstimate `json:"blind,omitempty"`
	ReferenceMatches []sigref.Match       `json:"reference_matches,omitempty"`
}

type LockInfo struct {
	FrequencyHz uint32         `json:"frequency_hz" yaml:"frequency_hz"`
	Fields      map[string]any `json:"fields" yaml:"fields"`
}

type Metadata struct {
	// Protocol is the CLI/config protocol name (p25, p25-phase2, dmr,
	// dmr-tier2, nxdn, dpmr, edacs, motorola, ltr, mpt1327, tetra, ysf,
	// dstar; the replay aliases p25p1/dmr-tier3 are also accepted).
	Protocol string `json:"protocol" yaml:"protocol"`
	// Source / ToolCrossCheck are free-text provenance (where the capture
	// came from, which reference receiver it was validated against).
	Source         string `json:"source,omitempty" yaml:"source,omitempty"`
	ToolCrossCheck string `json:"tool_cross_check,omitempty" yaml:"tool_cross_check,omitempty"`
	// SampleRateHz is required — a raw cfile/u8 carries no rate of its own.
	SampleRateHz float64 `json:"sample_rate_hz" yaml:"sample_rate_hz"`
	// CenterFreqHz is informational (the capture's nominal centre).
	CenterFreqHz uint32 `json:"center_freq_hz,omitempty" yaml:"center_freq_hz,omitempty"`
	// Format is the on-disk encoding (u8|f32); empty defaults to u8.
	Format string `json:"format,omitempty" yaml:"format,omitempty"`
	// TuneHz / AutoTune / Conjugate / IQCorrect mirror the engine knobs for
	// captures that need them.
	TuneHz    float64 `json:"tune_hz,omitempty" yaml:"tune_hz,omitempty"`
	AutoTune  bool    `json:"auto_tune,omitempty" yaml:"auto_tune,omitempty"`
	Conjugate bool    `json:"conjugate,omitempty" yaml:"conjugate,omitempty"`
	IQCorrect bool    `json:"iq_correct,omitempty" yaml:"iq_correct,omitempty"`
	// System carries per-protocol decoder knobs by their YAML config-key
	// names (e.g. "tetra_colour_code": "1", "p25_phase1_demod_mode":
	// "cqpsk"), applied onto the trunking.System the engine drives.
	System map[string]string `json:"system,omitempty" yaml:"system,omitempty"`
	// Expected is the acceptance contract graded against the decode.
	Expected Acceptance `json:"expected" yaml:"expected"`
}

type NIDDecode struct {
	Pos  int    `json:"pos" yaml:"pos"`
	Errs int    `json:"errs" yaml:"errs"`
	NAC  uint16 `json:"nac" yaml:"nac"`
	DUID uint8  `json:"duid" yaml:"duid"`
	OK   bool   `json:"ok" yaml:"ok"`
}

type NeighborRef = trunking.TopoNeighborRef

type P25P1Detail struct {
	DibitsBuffered  int             `json:"dibits_buffered" yaml:"dibits_buffered"`
	DibitHistogram  [4]int64        `json:"dibit_histogram" yaml:"dibit_histogram"`
	Rotations       [4]RotationStat `json:"rotations" yaml:"rotations"`
	WinningRotation int             `json:"winning_rotation" yaml:"winning_rotation"`
	WinningHits     int             `json:"winning_hits" yaml:"winning_hits"`
	// NIDDecodes are the NAC/DUID results from BCH-decoding the NID at the
	// cleanest (distance-0) FSW hits under the winning rotation. A mix of
	// successes and failures points at signal quality; zero successes
	// despite perfect FSW alignment points at framing.
	NIDDecodes []NIDDecode `json:"nid_decodes" yaml:"nid_decodes"`

	// CCStats is the per-frame NID/TSBK outcome breakdown the control channel
	// accumulates (the replay EOF summary's "nid trusted/marginal/…" lines).
	// Non-nil only on the deep path.
	CCStats *CCStatsBreakdown `json:"cc_stats,omitempty" yaml:"cc_stats,omitempty"`
	// SoftEye is the pre-slicer soft-sample analysis (DC, per-rail
	// distribution, true-symbol outer-rail eye + mechanism verdict). Non-nil
	// only when soft samples were captured (the deep C4FM path).
	SoftEye *SoftEye `json:"soft_eye,omitempty" yaml:"soft_eye,omitempty"`
	// ReceiverStates is the per-(stream-)second receiver-state series the
	// deep path captures when Config.CollectReceiverState is set.
	ReceiverStates []ReceiverState `json:"receiver_states,omitempty" yaml:"receiver_states,omitempty"`
}

type PDURecord struct {
	Seq        int            `json:"seq" yaml:"seq"`
	OffsetSec  float64        `json:"offset_sec" yaml:"offset_sec"`
	Protocol   string         `json:"protocol" yaml:"protocol"`
	Opcode     uint8          `json:"opcode" yaml:"opcode"`
	OpcodeName string         `json:"opcode_name" yaml:"opcode_name"`
	MFID       uint8          `json:"mfid,omitempty" yaml:"mfid,omitempty"`
	NAC        uint16         `json:"nac,omitempty" yaml:"nac,omitempty"`
	SourceID   uint32         `json:"source_id,omitempty" yaml:"source_id,omitempty"`
	DestID     uint32         `json:"dest_id,omitempty" yaml:"dest_id,omitempty"`
	Talkgroup  uint32         `json:"talkgroup,omitempty" yaml:"talkgroup,omitempty"`
	Fields     map[string]any `json:"fields,omitempty" yaml:"fields,omitempty"`
	RawHex     string         `json:"raw_hex" yaml:"raw_hex"`
	CRCOK      bool           `json:"crc_ok" yaml:"crc_ok"`
	FECMetric  int            `json:"fec_metric" yaml:"fec_metric"`
	DibitStart int            `json:"dibit_start" yaml:"dibit_start"`
	DibitLen   int            `json:"dibit_len" yaml:"dibit_len"`
}

type ProtocolDetail struct {
	Protocol           string         `json:"protocol" yaml:"protocol"`
	SymbolsBuffered    int            `json:"symbols_buffered" yaml:"symbols_buffered"`
	SymbolCardinality  int            `json:"symbol_cardinality" yaml:"symbol_cardinality"`
	SymbolHistogram    []int64        `json:"symbol_histogram" yaml:"symbol_histogram"`
	SymbolHistogramPct []float64      `json:"symbol_histogram_pct" yaml:"symbol_histogram_pct"`
	Sync               *SyncLandscape `json:"sync,omitempty" yaml:"sync,omitempty"`
	FEC                []FECStat      `json:"fec,omitempty" yaml:"fec,omitempty"`
	Notes              string         `json:"notes,omitempty" yaml:"notes,omitempty"`
}

type RailStat struct {
	Label string  `json:"label" yaml:"label"`
	N     int     `json:"n" yaml:"n"`
	Mean  float64 `json:"mean" yaml:"mean"`
	Std   float64 `json:"std" yaml:"std"`
	P10   float64 `json:"p10" yaml:"p10"`
	P50   float64 `json:"p50" yaml:"p50"`
	P90   float64 `json:"p90" yaml:"p90"`
}

type ReceiverState struct {
	TimeSec float64 `json:"time_sec" yaml:"time_sec"`
	CQPSK   bool    `json:"cqpsk" yaml:"cqpsk"`

	// C4FM path.
	AFCHzEst         float64    `json:"afc_hz_est" yaml:"afc_hz_est"`
	AGCLevel         float64    `json:"agc_level" yaml:"agc_level"`
	AGCTarget        float64    `json:"agc_target" yaml:"agc_target"`
	MMMu             float64    `json:"mm_mu" yaml:"mm_mu"`
	MMSPS            float64    `json:"mm_sps" yaml:"mm_sps"`
	DDAActive        bool       `json:"dda_active" yaml:"dda_active"`
	SlicerLevels     [4]float64 `json:"slicer_levels" yaml:"slicer_levels"`
	SlicerThresholds [3]float64 `json:"slicer_thresholds" yaml:"slicer_thresholds"`

	// CQPSK path.
	CarrierHzEst float64 `json:"carrier_hz_est,omitempty" yaml:"carrier_hz_est,omitempty"`
	GardnerMu    float64 `json:"gardner_mu,omitempty" yaml:"gardner_mu,omitempty"`
	GardnerSPS   float64 `json:"gardner_sps,omitempty" yaml:"gardner_sps,omitempty"`
	CQPSKAGCGain float64 `json:"cqpsk_agc_gain,omitempty" yaml:"cqpsk_agc_gain,omitempty"`
	CMAError     float64 `json:"cma_error,omitempty" yaml:"cma_error,omitempty"`
}

type Result struct {
	// Provenance.
	Source         string  `json:"source" yaml:"source"`
	Protocol       string  `json:"protocol" yaml:"protocol"`
	SampleRateHz   float64 `json:"sample_rate_hz" yaml:"sample_rate_hz"`
	PipelineRateHz float64 `json:"pipeline_rate_hz" yaml:"pipeline_rate_hz"`
	TuneHz         float64 `json:"tune_hz" yaml:"tune_hz"`
	DurationSec    float64 `json:"duration_sec" yaml:"duration_sec"`

	// Throughput.
	TotalSamples     int64   `json:"total_samples" yaml:"total_samples"`
	Symbols          int64   `json:"symbols" yaml:"symbols"`
	EffectiveBaud    float64 `json:"effective_baud" yaml:"effective_baud"`
	ExpectedBaud     float64 `json:"expected_baud" yaml:"expected_baud"`
	BaudDeviationPct float64 `json:"baud_deviation_pct" yaml:"baud_deviation_pct"`

	// Lock.
	Locked         bool      `json:"locked" yaml:"locked"`
	LockLatencySec float64   `json:"lock_latency_sec" yaml:"lock_latency_sec"`
	Lock           *LockInfo `json:"lock,omitempty" yaml:"lock,omitempty"`

	// Grants + events.
	Grants       []GrantRecord  `json:"grants" yaml:"grants"`
	Events       []EventRecord  `json:"events" yaml:"events"`
	EventCounts  map[string]int `json:"event_counts" yaml:"event_counts"`
	DecodeErrors map[string]int `json:"decode_errors" yaml:"decode_errors"`

	// Analysis (nil unless CollectIQDiag).
	Signal *SignalQuality `json:"signal,omitempty" yaml:"signal,omitempty"`
	// Detail is the protocol-specific deep dive (a *P25P1Detail, *DMRDetail,
	// *NXDNDetail, …) populated when CollectIQDiag is set and a per-protocol
	// detail builder exists. Consumers type-switch on it (keyed by Protocol).
	Detail any `json:"detail,omitempty" yaml:"detail,omitempty"`

	// Topology is the protocol-neutral system topology accumulated from the
	// control channel during the run — identity (WACN/SYSID/RFSS/Site or the
	// per-protocol equivalent), neighbor sites, and band plan. It is the only
	// path by which a caller learns WACN/SYSID/RFSS/Site, which never appear in
	// event payloads (they live in the decoder's network model). nil when the
	// protocol's pipeline does not implement TopologyProvider.
	Topology *TopologySnapshot `json:"topology,omitempty" yaml:"topology,omitempty"`

	// Verdict (nil unless Config.Acceptance supplied).
	Verdict *Verdict `json:"verdict,omitempty" yaml:"verdict,omitempty"`

	// NoLockReason is a human-readable classification of why the control
	// channel did not lock, populated only when !Locked. It turns a bare "did
	// not lock" into a named cause — SNR-limited capture / frame sync not
	// aligned / not the control channel / no signal — from the demod and
	// frame-decode metrics already gathered, so a capture-quality failure is
	// not misread as a tuning or AGC bug (issues #764 / #771).
	NoLockReason string `json:"no_lock_reason,omitempty" yaml:"no_lock_reason,omitempty"`

	// IQTaps is the optional decimated signal capture (channelized IQ +
	// pre-slicer soft samples) populated when Config.CaptureIQ is set. It
	// backs the web visualization views (constellation, spectrogram, PSD,
	// eye diagram). It can be large, so the API/export layer strips it
	// before serializing the summary or running the exporters and serves
	// it from a dedicated endpoint instead.
	IQTaps *IQTaps `json:"iq_taps,omitempty" yaml:"iq_taps,omitempty"`

	// PDUs is the optional per-signaling-block (TSBK) dissection populated when
	// Config.CollectPDUs is set — the data-over-RF inspector feed. Capped at
	// pduMaxRecords; PDUsTruncated marks an overflow. P25 Phase 1 only for now.
	PDUs          []PDURecord `json:"pdus,omitempty" yaml:"pdus,omitempty"`
	PDUsTruncated bool        `json:"pdus_truncated,omitempty" yaml:"pdus_truncated,omitempty"`
}

type RotationStat struct {
	BestDist int `json:"best_dist" yaml:"best_dist"`
	BestPos  int `json:"best_pos" yaml:"best_pos"`
	Hits     int `json:"hits" yaml:"hits"` // positions with distance ≤ tolerance
}

type SampleDecoder func(buf []byte, out []complex64)

type SampleFormat int

type SignalQuality struct {
	// SymbolCardinality is 4 for the dibit (4-level) protocols and 2 for
	// the bit (2-level) protocols.
	SymbolCardinality int `json:"symbol_cardinality" yaml:"symbol_cardinality"`
	// SymbolHistogram counts recovered symbols per value (len ==
	// SymbolCardinality). A clean 4-level C4FM control channel sits near
	// 25% per bin; a near-empty bin means the slicer collapsed, a single
	// dominant bin means the signal is below the slicer thresholds.
	SymbolHistogram []int64 `json:"symbol_histogram" yaml:"symbol_histogram"`
	// SymbolHistogramPct is SymbolHistogram normalised to percentages.
	SymbolHistogramPct []float64 `json:"symbol_histogram_pct" yaml:"symbol_histogram_pct"`

	// Raw (pre-DDC) front-end I/Q imbalance. A clean front-end is balanced
	// (≈0 dB gain, ≈0° phase) with image rejection ≳ 40 dB. Populated only
	// when raw IQ was observed.
	IQGainImbalanceDB   float64 `json:"iq_gain_imbalance_db" yaml:"iq_gain_imbalance_db"`
	IQPhaseImbalanceDeg float64 `json:"iq_phase_imbalance_deg" yaml:"iq_phase_imbalance_deg"`
	IQImageRejectionDB  float64 `json:"iq_image_rejection_db" yaml:"iq_image_rejection_db"`
	IQObserved          bool    `json:"iq_observed" yaml:"iq_observed"`

	// RMSPowerDBFS is the raw-capture RMS power in dBFS (20·log10 of the RMS
	// amplitude; 0 dBFS = a full-scale signal). It is the capture-level power
	// figure the `spectrum` CLI reports; populated only when raw IQ was observed.
	RMSPowerDBFS float64 `json:"rms_power_dbfs" yaml:"rms_power_dbfs"`

	// DecodeErrorRate is decode-error events per recovered 1000 symbols — a
	// protocol-neutral proxy for FEC stress.
	DecodeErrorRate float64 `json:"decode_error_rate_per_ksym" yaml:"decode_error_rate_per_ksym"`

	// Demod is the demodulator-quality measurement (EVM + estimated SNR)
	// derived from the per-symbol soft samples on the P25 deep path. Nil for
	// protocols / runs that do not surface the soft stream. It is what turns
	// "the audio sounds bad" into "the eye is N% open / the demod is M dB from
	// the noise floor."
	Demod *DemodMetrics `json:"demod,omitempty" yaml:"demod,omitempty"`
}

type SoftEye struct {
	SoftSamples  int     `json:"soft_samples" yaml:"soft_samples"`
	SignedMeanDC float64 `json:"signed_mean_dc" yaml:"signed_mean_dc"`
	StdDev       float64 `json:"std_dev" yaml:"std_dev"`
	MeanAbs      float64 `json:"mean_abs" yaml:"mean_abs"`
	MaxAbs       float64 `json:"max_abs" yaml:"max_abs"`
	// MagnitudeHistogram bins |soft| into 10 deciles of MaxAbs — bimodal ⇒ a
	// clean 4-level eye, unimodal-saturated ⇒ everything piled near ±max.
	MagnitudeHistogram [10]int64 `json:"magnitude_histogram" yaml:"magnitude_histogram"`
	// PerDecidedSymbol is the soft distribution grouped by the slicer's
	// decision (rails -3,-1,+1,+3). Clean ⇒ symmetric, |outer| ≈ 3·|inner|.
	PerDecidedSymbol []RailStat `json:"per_decided_symbol" yaml:"per_decided_symbol"`
	// TrueOuterRail is the slicer-independent outer-rail (+3,-3) distribution
	// from the known FSW symbols.
	TrueOuterRail []RailStat `json:"true_outer_rail" yaml:"true_outer_rail"`
	// OuterSpread splits each true outer rail into steady vs post-transition
	// standard deviation — the ISI / timing discriminator.
	OuterSpread []SpreadStat `json:"outer_spread" yaml:"outer_spread"`
	// Verdict points at the dominant outer-spread mechanism.
	Verdict string `json:"verdict" yaml:"verdict"`
}

type SpreadStat struct {
	Label     string  `json:"label" yaml:"label"`
	SteadyStd float64 `json:"steady_std" yaml:"steady_std"`
	SteadyN   int     `json:"steady_n" yaml:"steady_n"`
	TransStd  float64 `json:"trans_std" yaml:"trans_std"`
	TransN    int     `json:"trans_n" yaml:"trans_n"`
	Ratio     float64 `json:"ratio" yaml:"ratio"`
}

type SurveySpectrum struct {
	CenterHz     uint32    `json:"center_hz" yaml:"center_hz"`
	SampleRateHz uint32    `json:"sample_rate_hz" yaml:"sample_rate_hz"`
	Bins         []float32 `json:"bins" yaml:"bins"`
}

type SyncLandscape struct {
	SyncLen        int        `json:"sync_len" yaml:"sync_len"`
	Tolerance      int        `json:"tolerance" yaml:"tolerance"`
	Stats          []SyncStat `json:"stats" yaml:"stats"`
	WinnerVariant  string     `json:"winner_variant" yaml:"winner_variant"`
	WinnerRotation int        `json:"winner_rotation" yaml:"winner_rotation"`
	WinnerHits     int        `json:"winner_hits" yaml:"winner_hits"`
	// ModalSpacing is the most common symbol delta between consecutive clean
	// hits under the winner — a real control channel emits sync at a fixed
	// frame interval, so a single dominant spacing means genuine frames while
	// scattered spacings mean false positives.
	ModalSpacing int `json:"modal_spacing" yaml:"modal_spacing"`
	// contains filtered or unexported fields
}

type SyncStat struct {
	Variant  string `json:"variant" yaml:"variant"`
	Rotation int    `json:"rotation" yaml:"rotation"`
	BestDist int    `json:"best_dist" yaml:"best_dist"`
	BestPos  int    `json:"best_pos" yaml:"best_pos"`
	Hits     int    `json:"hits" yaml:"hits"`
}

type SyncVariant struct {
	Name    string  `json:"name" yaml:"name"`
	Pattern []uint8 `json:"-" yaml:"-"`
}

type SynthOptions struct {
	Protocol trunking.Protocol
	Format   SampleFormat
	// Impairments applied to the ideal IQ (SNR, carrier offset, DC spike,
	// I/Q imbalance, multipath). The zero value is a clean capture.
	Impairments demod.Impairments
	// Modulation optionally overrides the fixture's default modulator. Empty
	// uses the per-protocol default. For P25 Phase 1, "lsm" (or "cqpsk")
	// selects the linear π/4-DQPSK (LSM) waveform instead of C4FM, so a
	// capture can exercise the linear CQPSK demod path (issue #492).
	Modulation string
}

type SystemRollup struct {
	Protocol     string `json:"protocol" yaml:"protocol"`
	Tier3        bool   `json:"tier3" yaml:"tier3"`
	SystemID     uint32 `json:"system_id,omitempty" yaml:"system_id,omitempty"`
	ColorCode    uint8  `json:"color_code,omitempty" yaml:"color_code,omitempty"`
	ControlCount int    `json:"control_count" yaml:"control_count"`
	VoiceCount   int    `json:"voice_count" yaml:"voice_count"`
	LoHz         uint32 `json:"lo_hz" yaml:"lo_hz"`
	HiHz         uint32 `json:"hi_hz" yaml:"hi_hz"`
	CarrierIdx   []int  `json:"carrier_idx" yaml:"carrier_idx"`
	Verdict      string `json:"verdict" yaml:"verdict"`
}

type TopologyProvider = trunking.TopologyProvider

type TopologySnapshot = trunking.TopologySnapshot

type Verdict struct {
	Pass     bool     `json:"pass" yaml:"pass"`
	Failures []string `json:"failures" yaml:"failures"`
	Checks   []string `json:"checks" yaml:"checks"`
}

type WidebandConfig struct {
	SampleRateHz       float64             // wideband input rate (required)
	CenterHz           uint32              // absolute capture center (0 ⇒ offsets only)
	Format             SampleFormat        //
	ChannelRateHz      float64             // per-carrier target; 0 ⇒ 48 kHz
	FFTSize            int                 // spectrum FFT; 0 ⇒ 4096
	GuardFrac          float64             // band-edge guard; 0 ⇒ 0.05
	PeakThresholdDb    float32             // 0 ⇒ 10
	MinSpacingHz       uint32              // 0 ⇒ 6.25 kHz
	TunerStrategy      string              // "" | "auto" | "ddc" | "polyphase"
	Candidates         []trunking.Protocol // per-carrier identify set; nil ⇒ all
	IdentifyMaxSamples int64               // per-carrier identify cap; 0 ⇒ whole carrier
	MaxCarriers        int                 // defensive cap on taps; 0 ⇒ no cap
	Conjugate          bool                //
	IQCorrect          bool                //
	// CollectSpectrum retains the Welch-averaged power spectrum on the result
	// (WidebandResult.Spectrum) so callers can plot the band with the detected
	// carriers overlaid. Off by default to keep the offline hunt path lean.
	CollectSpectrum bool         //
	Log             *slog.Logger //
}

type WidebandResult struct {
	Source        string  `json:"source" yaml:"source"`
	SampleRateHz  float64 `json:"sample_rate_hz" yaml:"sample_rate_hz"`
	CenterHz      uint32  `json:"center_hz" yaml:"center_hz"`
	ChannelRateHz float64 `json:"channel_rate_hz" yaml:"channel_rate_hz"`
	Strategy      string  `json:"strategy" yaml:"strategy"`
	// Spectrum is the averaged band power spectrum for display; nil unless
	// WidebandConfig.CollectSpectrum was set.
	Spectrum *SurveySpectrum `json:"spectrum,omitempty" yaml:"spectrum,omitempty"`
	// DetectedCount is the number of spectral carrier peaks before the
	// per-carrier identify filter dropped the ones that didn't decode to a
	// real protocol (leakage / noise peaks).
	DetectedCount int             `json:"detected_count" yaml:"detected_count"`
	Carriers      []CarrierResult `json:"carriers" yaml:"carriers"`
	Systems       []SystemRollup  `json:"systems" yaml:"systems"`
}