detect

type AnalysisResult struct {
	// MessageLength is the estimated hidden message size, if detected.
	// Nil if the image is classified as clean.
	MessageLength *MessageLengthEstimate `json:"message_length,omitempty"`

	// PerModeBetas contains the beta estimate for each DCT frequency mode.
	// Useful for detailed analysis and debugging.
	PerModeBetas map[string]float64 `json:"per_mode_betas,omitempty"`

	// Calibration contains calibration results if multi-QF analysis was performed.
	// Nil if single-QF analysis was used.
	Calibration *CalibrationResult `json:"calibration,omitempty"`

	// Signatures holds the structural detection signatures (JPEG format, chroma
	// subsampling, James/f5.jar marker fingerprints, quantization tables,
	// embedding capacity) for the analyzed image. These are independent of the
	// statistical Beta estimate and together describe whether the image is a
	// plausible F5 carrier and what encoder produced it. Nil if signature
	// analysis could not run.
	Signatures *SignatureReport `json:"signatures,omitempty"`

	// QualityReliability indicates how reliable the analysis results are based
	// on the detected JPEG quality factor. The Fridrich method works best at
	// Q=60-91; results outside this range should be interpreted with caution.
	QualityReliability QualityReliability `json:"quality_reliability"`

	// Verdict is the tri-state classification: VerdictClean, VerdictStego, or
	// VerdictInconclusive. This is the field court-defensible callers should
	// branch on. A hidden payload is asserted ONLY by VerdictStego;
	// VerdictInconclusive means the method could not decide for this image (the
	// reconstruction diverged or quality is out of range) and must never be
	// reported as a detection.
	Verdict Verdict `json:"verdict"`

	// InconclusiveReason is a short human-readable explanation populated only
	// when Inconclusive is true (e.g. "beta saturated", "beta above F5
	// capacity ceiling", "quality factor out of reliable range"). Empty
	// otherwise.
	InconclusiveReason string `json:"inconclusive_reason,omitempty"`

	// Warnings contains non-fatal issues detected during analysis that may
	// affect result reliability. Empty when quality is in the optimal range
	// and no issues are detected.
	Warnings []Warning `json:"warnings,omitempty"`

	// Beta is the estimated modification rate in range [0, 1].
	// Higher values indicate more steganographic content.
	Beta float64 `json:"beta"`

	// RawBeta is the unclamped β estimate before the [0, 1] clamp. Values
	// outside [0, 1] indicate the cover-image histogram reconstruction has
	// diverged (small images, very high quality factors, double JPEG
	// compression). When RawBeta differs substantially from Beta, the
	// downstream message-length estimate is unreliable; check Saturated
	// before trusting it.
	RawBeta float64 `json:"raw_beta"`

	// Confidence indicates the overall reliability of the analysis in [0.0, 1.0].
	// Derived from the least-squares denominator magnitude (normalized via log10)
	// and scaled by quality reliability (full confidence only for Q=60-91).
	Confidence float64 `json:"confidence"`

	// Quality is the detected JPEG compression quality factor (1-100).
	Quality int `json:"quality"`

	// Saturated reports whether the RawBeta fell outside [0, 1] before the
	// public clamp. True is a strong signal that downstream estimates
	// (message length, k inference) are unreliable for this image.
	Saturated bool `json:"saturated"`

	// IsClean indicates whether the image is classified as clean.
	// True only when Verdict == VerdictClean (β below threshold AND the
	// reconstruction was reliable). False for both VerdictStego and
	// VerdictInconclusive — so a false IsClean no longer implies "stego". Use
	// Verdict for the three-way distinction; treat IsClean as "confidently
	// clean" only.
	IsClean bool `json:"is_clean"`

	// Inconclusive is a convenience boolean equal to (Verdict ==
	// VerdictInconclusive). When true, Beta / MessageLength / k are unreliable
	// and InconclusiveReason explains why.
	Inconclusive bool `json:"inconclusive"`
}

type BetaEstimationResult struct {
	// PerModeBetas contains the beta estimate for each DCT frequency mode.
	// Key format: "row,col" (e.g., "1,2", "2,1", "2,2")
	// Value: beta estimate for that mode
	//
	// Per-mode analysis is more sensitive than aggregate analysis because
	// F5 modifications are concentrated in specific frequency bands.
	//
	// Note: Reading from a nil PerModeBetas map returns 0 (Go map semantics).
	PerModeBetas map[string]float64 `json:"per_mode_betas"`

	// PerModeRawBetas mirrors PerModeBetas but holds the unclamped values
	// per DCT mode. Useful for diagnosing which mode is driving saturation.
	PerModeRawBetas map[string]float64 `json:"per_mode_raw_betas,omitempty"`

	// Beta is the overall estimated modification rate in range [0, 1].
	// This is the average of valid per-mode betas.
	//
	// Interpretation:
	//   - Beta = 0: No modifications detected (clean image)
	//   - Beta = 0.1: ~10% of usable coefficients were modified
	//   - Beta = 0.5: ~50% of usable coefficients were modified
	//   - Beta = 1.0: Maximum theoretical modification rate
	Beta float64 `json:"beta"`

	// Confidence indicates the reliability of the beta estimate.
	// Higher values indicate more reliable estimates.
	// Based on the denominator magnitude in the least-squares formula.
	Confidence float64 `json:"confidence"`

	// MinBeta is the minimum of positive per-mode betas.
	// When per-mode beta variance is high (BetaCV > BetaVarianceCVThreshold),
	// MinBeta may be more accurate than the averaged Beta for message length
	// estimation, especially for non-photographic images (cartoons, illustrations).
	MinBeta float64 `json:"min_beta"`

	// BetaCV is the coefficient of variation (std/mean) of positive per-mode betas.
	// A high CV (>0.30) indicates that the per-mode betas disagree significantly,
	// suggesting the crop-and-recompress calibration may be inaccurate.
	// This typically occurs with non-photographic images.
	BetaCV float64 `json:"beta_cv"`

	// RawBeta is the unclamped estimator output before the [0, 1] clamp
	// applied to Beta. Values outside [0, 1] indicate the cover-image
	// histogram reconstruction has diverged — typically caused by small
	// images, very high quality factors (Q > 91), or double JPEG
	// compression. When RawBeta differs substantially from Beta, the
	// downstream message-length estimate is unreliable; check Saturated
	// before trusting it.
	RawBeta float64 `json:"raw_beta"`

	// IsClean indicates whether the image is classified as clean (no steganography).
	// True if Beta < threshold (default threshold: 0.125 from Fridrich paper).
	IsClean bool `json:"is_clean"`

	// Saturated reports whether the RawBeta fell outside [0, 1] before the
	// public clamp. True is a strong signal that downstream estimates
	// (message length, k inference) are unreliable for this image.
	Saturated bool `json:"saturated"`
}

type BetaEstimator interface {
	// EstimateBeta calculates beta by analyzing multiple DCT frequency modes.
	//
	// The method:
	//  1. Calculates beta for each of the low-frequency modes (1,2), (2,1), (2,2)
	//  2. Filters out negative betas (indicating estimation error for that mode)
	//  3. Averages the valid (positive) betas to get the final estimate
	//
	// Parameters:
	//   - stegoHistograms: DCT coefficient histograms from the suspected stego-image
	//   - coverHistograms: DCT coefficient histograms from the estimated cover-image
	//
	// Returns:
	//   - *BetaEstimationResult: Contains overall beta, per-mode betas, confidence, and clean classification
	//   - error: If histograms are empty or invalid
	//
	// Example:
	//   result, err := estimator.EstimateBeta(stegoHists, coverHists)
	//   if err != nil { return err }
	//   if result.IsClean {
	//       fmt.Println("Image appears clean")
	//   } else {
	//       fmt.Printf("Detected modification rate: %.2f%%\n", result.Beta * 100)
	//   }
	EstimateBeta(stegoHistograms, coverHistograms []DCTHistogram) (*BetaEstimationResult, error)

	// EstimateBetaForMode implements the Fridrich least-squares formula for a single DCT mode.
	//
	// Formula (Equation 3 from paper):
	//   beta = [h(1)*[H(0) - h(0)] + [H(1) - h(1)]*[h(2) - h(1)]] / [h(1)^2 + [h(2) - h(1)]^2]
	//
	// Where:
	//   - H(d) = stego-image histogram at coefficient value d
	//   - h(d) = estimated cover-image histogram at coefficient value d
	//
	// Parameters:
	//   - stegoHist: DCT coefficient histogram from stego-image for this mode
	//   - coverHist: DCT coefficient histogram from estimated cover-image for this mode
	//
	// Returns:
	//   - beta: Estimated modification rate in range [0, 1]
	//   - confidence: Estimation confidence (based on denominator magnitude)
	//   - error: If calculation cannot be performed
	EstimateBetaForMode(stegoHist, coverHist DCTHistogram) (beta, confidence float64, err error)
}

type CalibrationResult struct {
	// QualityDistances maps each tested quality factor to its L2 distance.
	// Lower distance indicates better fit.
	//
	// Note: Reading from a nil QualityDistances map returns 0 (Go map semantics).
	QualityDistances map[int]float64 `json:"quality_distances"`

	// BestQuality is the quality factor that produced the best (lowest) L2 distance.
	// This may differ from the detected quality if the image was double-compressed.
	BestQuality int `json:"best_quality"`

	// CalibratedBeta is the beta estimate using the best quality factor.
	// This is typically more accurate than UncalibratedBeta for double-compressed images.
	CalibratedBeta float64 `json:"calibrated_beta"`

	// UncalibratedBeta is the beta estimate assuming single compression.
	// This uses only the detected quality factor without calibration.
	UncalibratedBeta float64 `json:"uncalibrated_beta"`

	// Confidence indicates the reliability of the calibration.
	// Based on the separation between best and second-best distances.
	Confidence float64 `json:"confidence"`

	// IsDoubleCompressed indicates if double compression was detected.
	// True if BestQuality differs from the detected quality by at least DoubleCompressionThreshold (3).
	IsDoubleCompressed bool `json:"is_double_compressed"`
}

type CoefficientExtractor interface {
	// Extract retrieves all DCT coefficients from a JPEG file.
	//
	// The returned coefficients include position information for per-mode analysis.
	// Coefficients are returned for all color components (Y, Cb, Cr).
	//
	// Parameters:
	//   - data: Complete JPEG file data
	//
	// Returns:
	//   - coefficients: Slice of DCT coefficients with position metadata
	//   - error: If extraction fails or data is not valid JPEG
	//
	// Note: This is a computationally expensive operation. For large images,
	// consider caching results if multiple analyzes are needed.
	Extract(data []byte) ([]DCTCoefficient, error)
}

type DCTCoefficient struct {
	// Row is the row position in the 8x8 DCT block (0-7).
	// Row 0 contains the DC coefficient (at col 0) and low-frequency AC coefficients.
	Row int `json:"row"`

	// Col is the column position in the 8x8 DCT block (0-7).
	// Col 0 contains the DC coefficient (at row 0) and low-frequency AC coefficients.
	Col int `json:"col"`

	// Component indicates which color component this coefficient belongs to.
	// 0 = Y (luminance), 1 = Cb (blue chrominance), 2 = Cr (red chrominance)
	Component int `json:"component"`

	// Value is the quantized DCT coefficient value.
	// Typical range after quantization: [-1024, +1024] for most images.
	// F5 modifications affect only non-zero AC coefficients.
	Value int16 `json:"value"`
}

type DCTHistogram struct {
	// Counts maps DCT coefficient values to their occurrence count.
	// Key: coefficient value (e.g., -5 to +5)
	// Value: number of coefficients with that value
	//
	// Note: Reading from a nil Counts map returns 0 (Go map semantics).
	Counts map[int]int `json:"counts"`

	// Component indicates which color component this histogram represents.
	// 0 = Y (luminance), 1 = Cb (blue chrominance), 2 = Cr (red chrominance)
	//
	// The Fridrich attack focuses on the luminance component (Y = 0) because
	// F5 steganography only modifies luminance coefficients.
	Component int `json:"component"`

	// FrequencyBand encodes the DCT frequency position as row*8 + col using
	// 0-indexed (row, col) in the 8x8 DCT block. Examples:
	//   - (0,0) = DC coefficient, FrequencyBand = 0
	//   - (0,1) = paper mode (1,2), FrequencyBand = 1  (first horizontal AC)
	//   - (1,0) = paper mode (2,1), FrequencyBand = 8  (first vertical AC)
	//   - (1,1) = paper mode (2,2), FrequencyBand = 9  (first diagonal AC)
	//
	// The Fridrich attack uses paper modes (1,2), (2,1), and (2,2) — the three
	// lowest AC frequencies — where the statistical signal of F5 modifications
	// is strongest. Paper notation is 1-indexed; this field uses 0-indexed.
	FrequencyBand int `json:"frequency_band"`
}

type DCTMode string

type Detection struct {
	// Verdict is the tri-state classification (clean / stego_detected /
	// inconclusive). Assert a hidden payload ONLY on VerdictStego.
	Verdict Verdict `json:"verdict"`

	// InconclusiveReason explains why Verdict is inconclusive; empty otherwise.
	InconclusiveReason string `json:"inconclusive_reason,omitempty"`

	// Warnings carries every non-fatal issue surfaced during analysis (quality,
	// saturation, variance, inconclusive cause). This is the "surface warnings"
	// path the bare DetectF5 boolean cannot provide.
	Warnings []Warning `json:"warnings,omitempty"`

	// Beta is the (clamped) modification-rate estimate. Meaningful only when
	// Verdict == VerdictStego; for inconclusive results it is unreliable.
	Beta float64 `json:"beta"`

	// Confidence is the overall reliability of the estimate in [0,1].
	Confidence float64 `json:"confidence"`
}

type Error struct {
	// Cause is the underlying error that caused this error, if any.
	// Used for error chain support via Unwrap().
	Cause error

	// Message is the human-readable error description.
	// This is the default English message used when no translator is configured.
	Message string

	// I18nKey is the translation key for localized error messages.
	// Keys follow the pattern: "error.<error_type>"
	// For example: "error.empty_histogram", "error.invalid_quality"
	I18nKey string

	// Code is the error category for programmatic handling.
	Code ErrorCode
}

type ErrorCode int

type HistogramCalibrator interface {
	// CalculateL2Distance computes the L2 distance between observed stego histogram
	// and expected histogram based on cover estimate and modification rate.
	//
	// Formula (Section 4 from paper):
	//   E = sum_j[(H(0) - h(0) - beta*h(1))^2 + (H(j) - (1-beta)*h(j) - beta*h(j+1))^2]
	//
	// Parameters:
	//   - stegoHist: Observed stego-image histogram
	//   - coverHist: Estimated cover-image histogram
	//   - beta: Modification rate to test
	//
	// Returns:
	//   - distance: L2 distance (lower = better fit)
	//   - error: If beta is out of range [0, 1]
	CalculateL2Distance(stegoHist, coverHist DCTHistogram, beta float64) (float64, error)

	// CalibrateWithMultipleQF tests multiple quality factors to find the best beta estimate.
	//
	// This handles double-compressed images where the original quality factor
	// differs from the current quality factor.
	//
	// Parameters:
	//   - stegoImage: Complete JPEG file data
	//   - stegoQuality: Detected quality factor of the stego-image
	//   - stegoHistograms: Pre-computed stego-image histograms
	//   - qualityFactors: List of quality factors to test
	//
	// Returns:
	//   - *CalibrationResult: Contains best quality, calibrated beta, and confidence
	//   - error: If calibration fails
	CalibrateWithMultipleQF(
		stegoImage []byte,
		stegoQuality int,
		stegoHistograms []DCTHistogram,
		qualityFactors []int,
	) (*CalibrationResult, error)
}

type HistogramEstimator interface {
	// EstimateCoverHistogram implements the complete crop-and-recompress pipeline.
	//
	// Parameters:
	//   - stegoImage: Complete JPEG file data of the suspected stego-image
	//
	// Returns:
	//   - stegoHistograms: DCT coefficient histograms from the original stego-image (3 low-frequency modes)
	//   - coverHistograms: DCT coefficient histograms from the recompressed (estimated cover) image (3 low-frequency modes)
	//   - quality: Detected JPEG quality factor of the original image
	//   - coverTotalP: Total non-zero luminance AC coefficients across ALL frequency modes in the estimated cover image.
	//     This is the global P needed for message length estimation per the Fridrich paper.
	//   - coverTotalAbsH1: Total |value|=1 luminance AC coefficients across ALL frequency modes in the estimated cover image.
	//     This is the global h(1) needed for shrinkage probability computation.
	//   - error: If any step of the pipeline fails
	//
	// Example:
	//   stegoHists, coverHists, quality, coverP, coverH1, err := estimator.EstimateCoverHistogram(jpegData)
	//   if err != nil { return err }
	//   fmt.Printf("Detected quality: %d, global P: %d\n", quality, coverP)
	EstimateCoverHistogram(stegoImage []byte) (
		stegoHistograms []DCTHistogram,
		coverHistograms []DCTHistogram,
		quality int,
		coverTotalP int,
		coverTotalAbsH1 int,
		err error,
	)
}

type ImageProcessor interface {
	// ConvertToYCbCr converts RGB pixels to YCbCr color space.
	//
	// Parameters:
	//   - rgbPixels: Raw RGB pixel data (row-major, 3 bytes per pixel)
	//   - width: Image width in pixels
	//   - height: Image height in pixels
	//
	// Returns:
	//   - ycbcrPixels: YCbCr pixel data (row-major, 3 bytes per pixel: Y, Cb, Cr)
	//   - error: If conversion fails
	ConvertToYCbCr(rgbPixels []byte, width, height int) (ycbcrPixels []byte, err error)

	// ConvertToRGB converts YCbCr pixels to RGB color space.
	//
	// Parameters:
	//   - ycbcrPixels: YCbCr pixel data (row-major, 3 bytes per pixel)
	//   - width: Image width in pixels
	//   - height: Image height in pixels
	//
	// Returns:
	//   - rgbPixels: Raw RGB pixel data (row-major, 3 bytes per pixel)
	//   - error: If conversion fails
	ConvertToRGB(ycbcrPixels []byte, width, height int) (rgbPixels []byte, err error)

	// CropImage shifts the image origin by cropSize pixels from the top-left
	// and returns the trimmed pixel buffer (the right and bottom edges are
	// preserved). This implements the Fridrich/Goljan/Hogea (2002) §3.2
	// crop-by-4-pixels step that misaligns the recompression DCT grid with
	// the original 8x8 block structure.
	//
	// Parameters:
	//   - pixels: Raw pixel data (row-major)
	//   - width: Current image width
	//   - height: Current image height
	//   - channels: Number of color channels (typically 3 for RGB or YCbCr)
	//   - cropSize: Number of pixels to shift the origin by (4 for the paper)
	//
	// Returns:
	//   - croppedPixels: Cropped pixel data
	//   - newWidth: Width after cropping (width - cropSize)
	//   - newHeight: Height after cropping (height - cropSize)
	//   - error: If crop size is too large or dimensions are invalid
	CropImage(pixels []byte, width, height, channels, cropSize int) (
		croppedPixels []byte, newWidth, newHeight int, err error,
	)

	// ApplyBlur applies a smoothing blur to reduce quantization noise.
	//
	// Parameters:
	//   - pixels: Raw pixel data (row-major)
	//   - width: Image width
	//   - height: Image height
	//   - channels: Number of color channels
	//   - epsilon: Blur strength parameter (typical value: 0.01)
	//
	// Returns:
	//   - blurredPixels: Blurred pixel data
	//   - error: If dimensions are invalid
	ApplyBlur(pixels []byte, width, height, channels int, epsilon float64) (
		blurredPixels []byte, err error,
	)
}

type JPEGCodec interface {
	// Decode decompresses JPEG data to raw pixel values.
	//
	// The returned pixels are in RGB format, row-major order:
	//   - pixels[y*width*3 + x*3 + 0] = Red
	//   - pixels[y*width*3 + x*3 + 1] = Green
	//   - pixels[y*width*3 + x*3 + 2] = Blue
	//
	// Parameters:
	//   - data: Complete JPEG file data
	//
	// Returns:
	//   - pixels: Raw RGB pixel data
	//   - width: Image width in pixels
	//   - height: Image height in pixels
	//   - error: If decoding fails or data is not valid JPEG
	Decode(data []byte) (pixels []byte, width, height int, err error)

	// Encode compresses raw pixel data to JPEG format.
	//
	// The input pixels must be in RGB format, row-major order.
	//
	// Parameters:
	//   - pixels: Raw RGB pixel data
	//   - width: Image width in pixels
	//   - height: Image height in pixels
	//   - quality: JPEG quality factor (1-100)
	//
	// Returns:
	//   - data: Complete JPEG file data
	//   - error: If encoding fails or dimensions are invalid
	Encode(pixels []byte, width, height, quality int) (data []byte, err error)

	// QualityFactor returns the detected quality factor of the last decoded image.
	//
	// This method must be called after Decode() to get meaningful results.
	// The quality factor is estimated from the quantization tables.
	//
	// Returns:
	//   - quality: Estimated quality factor (1-100), or 0 if not detected
	QualityFactor() int

	// IsBaseline returns whether the last decoded image was baseline JPEG.
	//
	// This method must be called after Decode() to get meaningful results.
	// F5 steganalysis only works on baseline JPEGs (SOF0).
	//
	// Returns:
	//   - baseline: True if baseline JPEG, false otherwise
	IsBaseline() bool
}

type MatrixKCandidate struct {
	K                    int  `json:"k"`
	MessageBits          int  `json:"message_bits"`
	MessageBytes         int  `json:"message_bytes"`
	PayloadBits          int  `json:"payload_bits"`
	PayloadBytes         int  `json:"payload_bytes"`
	ModifiedCoefficients int  `json:"modified_coefficients"`
	SelfConsistent       bool `json:"self_consistent"`
	FitsCapacity         bool `json:"fits_capacity"`
}

type MessageLengthEstimate struct {
	// Candidates holds per-k message-size hypotheses produced when the
	// caller used WithAutoMatrixK. Each element mirrors the headline
	// fields above for one candidate k value, plus a SelfConsistent flag
	// indicating whether F5's own optimal-k selection algorithm would
	// pick that k for the predicted message size. Nil when auto-k mode
	// is not enabled.
	Candidates []MatrixKCandidate `json:"candidates,omitempty"`

	// MessageBits is the estimated total bit length from Fridrich §3.3:
	// M̂ = W(k) · β · (P − h(1)). The F5 header (32 bits — encrypted k
	// and message length, Westfeld 2001 §3) is embedded via direct
	// coefficient modification, not matrix encoding, but its modifications
	// are indistinguishably counted in β, so M̂ may be slightly inflated.
	// Use this to validate against the paper formula or against capacity;
	// use PayloadBits for the user-visible plaintext length.
	MessageBits int `json:"message_bits"`

	// MessageBytes = MessageBits / 8. Includes header.
	MessageBytes int `json:"message_bytes"`

	// PayloadBits is the user-visible plaintext bit length: MessageBits
	// minus the 32-bit F5 header. Use this when comparing the estimate
	// against a known plaintext file size. Clamped to zero when M < 32.
	PayloadBits int `json:"payload_bits"`

	// PayloadBytes = PayloadBits / 8. Excludes header.
	PayloadBytes int `json:"payload_bytes"`

	// UsableCoefficients is the total number of non-zero coefficients.
	// These are the coefficients that can potentially carry hidden data.
	UsableCoefficients int `json:"usable_coefficients"`

	// ModifiedCoefficients is the estimated number of coefficients that were modified.
	// Calculated as: ModificationRate × UsableCoefficients × (1 − ShrinkageProbability)
	ModifiedCoefficients int `json:"modified_coefficients"`

	// MatrixEmbeddingK is the matrix embedding parameter k used in the estimate
	// (valid F5 range 1–7). A value of 0 means UNDETERMINED: β diverged or
	// saturated for this image, so there is no reliable k or message length —
	// MessageBits/Bytes and PayloadBits/Bytes are 0 and BelowReliableFloor is
	// true. Inspect Candidates for the per-k hypothesis space in that case. Do
	// not treat k=0 as "no matrix encoding"; treat it as "not recoverable."
	MatrixEmbeddingK int `json:"matrix_embedding_k"`

	// MatrixEmbeddingEfficiency is W(k) = k * 2^k / (2^k - 1).
	// This represents how many bits are embedded per coefficient modification.
	MatrixEmbeddingEfficiency float64 `json:"matrix_embedding_efficiency"`

	// ShrinkageProbability is the estimated probability that a modified coefficient
	// "shrinks" to zero. This happens when a coefficient with value +/-1 is modified.
	ShrinkageProbability float64 `json:"shrinkage_probability"`

	// ModificationRate is the beta value used for this estimate.
	ModificationRate float64 `json:"modification_rate"`

	// ReliableFloor is the β value below which this estimate is considered
	// unreliable: the Fridrich cover-histogram reconstruction error (the
	// "phantom β floor", ~0.05 at the default 4-px crop, lower with
	// WithCoverCrop(1)) dominates the true modification signal. It is a
	// property of the crop setting, not the image.
	ReliableFloor float64 `json:"reliable_floor"`

	// BelowReliableFloor is true when ModificationRate ≤ ReliableFloor. When
	// set, MessageBits/Bytes, PayloadBits/Bytes and MatrixEmbeddingK are still
	// populated but should be treated as an order-of-magnitude guess, not a
	// trustworthy figure — the same condition raises WarningLowBetaFloor. This
	// is the honest signal for "β is too small for this method to resolve a
	// length or k," which otherwise manifests as a confidently-wrong number.
	BelowReliableFloor bool `json:"below_reliable_floor"`
}

type MessageLengthEstimator interface {
	// EstimateMessageLength calculates the estimated hidden message size.
	//
	// The formula: M = W(k) * m, where:
	//   - M = message length in bits
	//   - W(k) = matrix embedding efficiency = k * 2^k / (2^k - 1)
	//   - m = number of modified coefficients = beta * P * (1 - P_S)
	//   - P = total usable (non-zero) AC coefficients from ALL modes in the estimated cover image
	//   - P_S = shrinkage probability = h(1) / P, where h(1) is from ALL AC modes
	//
	// Parameters:
	//   - beta: Estimated modification rate from BetaEstimator
	//   - stegoHistograms: DCT coefficient histograms from stego-image (3 low-frequency modes, for validation)
	//   - coverHistograms: DCT coefficient histograms from estimated cover (3 low-frequency modes, for validation)
	//   - matrixK: Matrix embedding parameter k (1-9 per F5 spec, Westfeld 2001)
	//   - coverTotalP: Total non-zero luminance AC coefficients across ALL frequency modes in the estimated cover image
	//   - coverTotalAbsH1: Total |value|=1 luminance AC coefficients across ALL frequency modes in the estimated cover image
	//
	// Returns:
	//   - *MessageLengthEstimate: Contains message size in bits/bytes and intermediate values
	//   - error: If inputs are invalid
	EstimateMessageLength(
		beta float64,
		stegoHistograms, coverHistograms []DCTHistogram,
		matrixK int,
		coverTotalP int,
		coverTotalAbsH1 int,
	) (*MessageLengthEstimate, error)

	// CalculateMatrixEfficiency returns the matrix embedding efficiency W(k).
	//
	// Formula: W(k) = k * 2^k / (2^k - 1)
	//
	// Values for common k:
	//   - k=1: W(1) = 2.0 (1 change embeds 1 bit)
	//   - k=2: W(2) = 8/3 = 2.67 (1 change embeds ~2.67 bits)
	//   - k=3: W(3) = 24/7 = 3.43 (1 change embeds ~3.43 bits)
	//   - k=4: W(4) = 64/15 = 4.27 (1 change embeds ~4.27 bits)
	//   - k=9: W(9) = 4608/511 = 9.02 (1 change embeds ~9.02 bits)
	//
	// Parameters:
	//   - k: Matrix embedding parameter (must be 1-9, per F5 spec)
	//
	// Returns:
	//   - efficiency: Matrix embedding efficiency
	//   - error: If k is out of valid range
	CalculateMatrixEfficiency(k int) (float64, error)
}

type Option func(*analyzerConfig)

type QualityReliability string

type Signature struct {
	// Name is a stable machine-readable identifier (e.g. "weeks_com").
	Name string `json:"name"`
	// Description explains what the signature checks for.
	Description string `json:"description"`
	// Detail is a human-readable note about this image's result.
	Detail string `json:"detail"`
	// Weight is this signature's contribution to the report Score when matched.
	Weight float64 `json:"weight"`
	// Matched is true when the signature fired for this image.
	Matched bool `json:"matched"`
}

type SignatureReport struct {
	// Subsampling is the detected chroma subsampling label (e.g. "4:2:0").
	Subsampling string `json:"subsampling"`
	// Signatures lists every checked signature with its result.
	Signatures []Signature `json:"signatures"`
	// Score is the sum of matched signature weights, in [0,1]. Higher means the
	// image looks more like a James/f5.jar-produced JPEG that could carry F5.
	Score float64 `json:"score"`
	// StandardQuality is the IJG quality factor matched by the luminance
	// quantization table, or 0 if the table is non-standard.
	StandardQuality int `json:"standard_quality"`
	// CarrierViable is true only if F5 could physically be present: the format
	// is decodable and (for baseline) there is real embedding capacity. When
	// false, any positive β is noise — F5 cannot live here.
	CarrierViable bool `json:"carrier_viable"`
	// Baseline is true for a baseline (SOF0) frame. A baseline frame still carries
	// its original encoder's markers, so a low Score on a baseline frame is strong
	// evidence the file is NOT f5.jar/PixelKnot output. A progressive frame may be
	// a losslessly transcoded carrier whose marker fingerprint was rewritten, so a
	// low Score there is not conclusive.
	Baseline bool `json:"baseline"`
}

type Stream struct {
	In  chan<- StreamRequest
	Out <-chan StreamResult
}

type StreamRequest struct {
	ID    string
	Image []byte
}

type StreamResult struct {
	Err    error
	Result *AnalysisResult
	ID     string
}

type TranslatorProvider interface {
	// Translate returns the translated string for the given key.
	Translate(key string) string

	// TranslateWithArgs returns the translated string with format arguments.
	TranslateWithArgs(key string, args ...interface{}) string

	// HasKey returns true if the translation key exists.
	HasKey(key string) bool

	// SetLocale changes the current locale.
	SetLocale(locale string)

	// GetLocale returns the current locale.
	GetLocale() string
}

type Verdict string

type Warning struct {
	// Code categorizes the warning for programmatic handling.
	Code WarningCode `json:"code"`

	// Message provides a human-readable description of the warning.
	// Messages support i18n when a translator is configured.
	Message string `json:"message"`
}

type WarningCode string