import CoreMedia
import Foundation
import NitroModules
import VisionCamera

/// Nitro entry point for camera PPG processing.
///
/// A `HybridFrameSpec` and its `CMSampleBuffer` exist only as local values during
/// `processFrame(frame:)`. Persistent state contains compact numeric metrics only.
final class HybridHaptikaPPGFrameProcessor: HybridHaptikaPPGFrameProcessorSpec {
  private enum SessionPhase {
    case idle
    case active
    case thermalStopped
    case finishing
  }

  private struct MeasurementConfiguration: Sendable {
    let sessionPurpose: PPGSessionPurpose
    let targetSampleRate: Double
    let minimumFrequencyHz: Double
    let maximumFrequencyHz: Double
    let stabilizationSeconds: Double
    let measurementSeconds: Double
    let emitEveryFrames: Int
    let minimumContactConfidence: Double
    let maximumInterpolationGapSeconds: Double
    let longGapLimitSeconds: Double
    let maximumBufferedSampleCount: Int

    init(native: NativePPGConfiguration) throws {
      guard native.targetSampleRate.isFinite,
            native.targetSampleRate >= 20,
            native.targetSampleRate <= 120
      else {
        throw HaptikaPPGFrameProcessorError.invalidConfiguration(
          "targetSampleRate must be between 20 and 120 Hz"
        )
      }
      guard native.minimumFrequencyHz.isFinite,
            native.maximumFrequencyHz.isFinite,
            native.minimumFrequencyHz > 0,
            native.maximumFrequencyHz > native.minimumFrequencyHz,
            native.maximumFrequencyHz < native.targetSampleRate / 2
      else {
        throw HaptikaPPGFrameProcessorError.invalidConfiguration(
          "the physiological band must be ordered and below Nyquist"
        )
      }
      guard native.stabilizationSeconds.isFinite,
            native.stabilizationSeconds >= 0,
            native.stabilizationSeconds <= 30
      else {
        throw HaptikaPPGFrameProcessorError.invalidConfiguration(
          "stabilizationSeconds must be between 0 and 30"
        )
      }
      let maximumDuration = PPGCoherencePolicy.maximumDurationSeconds(
        isCoherence: native.sessionPurpose == .coherence
      )
      guard native.measurementSeconds.isFinite,
            native.measurementSeconds >= 20,
            native.measurementSeconds <= maximumDuration
      else {
        throw HaptikaPPGFrameProcessorError.invalidConfiguration(
          "measurementSeconds exceeds the limit for this session purpose"
        )
      }
      guard native.emitEveryFrames.isFinite,
            native.emitEveryFrames >= 1,
            native.emitEveryFrames.rounded() == native.emitEveryFrames,
            native.emitEveryFrames <= 10_000
      else {
        throw HaptikaPPGFrameProcessorError.invalidConfiguration(
          "emitEveryFrames must be a positive integer"
        )
      }
      guard native.minimumContactConfidence.isFinite,
            (0...1).contains(native.minimumContactConfidence)
      else {
        throw HaptikaPPGFrameProcessorError.invalidConfiguration(
          "minimumContactConfidence must be between 0 and 1"
        )
      }

      sessionPurpose = native.sessionPurpose
      targetSampleRate = native.targetSampleRate
      minimumFrequencyHz = native.minimumFrequencyHz
      maximumFrequencyHz = native.maximumFrequencyHz
      stabilizationSeconds = native.stabilizationSeconds
      measurementSeconds = native.measurementSeconds
      emitEveryFrames = Int(native.emitEveryFrames)
      minimumContactConfidence = native.minimumContactConfidence
      maximumInterpolationGapSeconds = 0.25
      longGapLimitSeconds = 0.80

      // This bound permits a full measurement plus recovery time after contact interruptions.
      let maximumBufferedDuration = sessionPurpose == .coherence
        ? PPGCoherencePolicy.coherenceBufferDurationSeconds
        : stabilizationSeconds + measurementSeconds + 60
      maximumBufferedSampleCount = max(
        Int((targetSampleRate * maximumBufferedDuration).rounded(.up)),
        256
      )
    }

    var coreConfiguration: PPGProcessingConfiguration {
      PPGProcessingConfiguration(
        targetSampleRateHz: targetSampleRate,
        minimumFrequencyHz: minimumFrequencyHz,
        maximumFrequencyHz: maximumFrequencyHz,
        // The UI may finish as soon as 50 clean beats have been collected.
        // Keep a 45 s floor for HRV while allowing completion before the 90 s
        // safety limit on a clean signal.
        minimumAnalysisDurationSeconds: min(max(30, measurementSeconds * 0.75), 45),
        maximumInterpolationGapSeconds: maximumInterpolationGapSeconds,
        longGapLimitSeconds: longGapLimitSeconds,
        minimumContactConfidence: minimumContactConfidence,
        maximumSaturationRatio: 0.95,
        maximumMotionArtifactScore: 0.95,
        minimumPeakProminence: 0.35,
        minimumPeakAmplitude: 0.10,
        refractoryPeriodSeconds: 0.25,
        maximumMethodDisagreementBPM: 8,
        minimumQualityScore: 0.55,
        minimumIntervalsForPRV: 35,
        maximumRejectedIntervalRatioForPRV: 0.45
      )
    }
  }

  private struct SessionSnapshot: Sendable {
    let configuration: MeasurementConfiguration
    let samples: [PPGFrameSample]
    let startedAtMonotonicSeconds: Double
    let endedAtMonotonicSeconds: Double
    let processedFrameCount: Int
    let droppedFrameCount: Int
    let acquisitionDroppedFrameCount: Int
    let usableDurationSeconds: Double
    let maximumAcquisitionGapSeconds: Double
    let bufferLimitReached: Bool
    let terminalReason: String?
  }

  private let stateLock = NSLock()
  private let metricsExtractor = PPGFrameMetricsExtractor()
  private let thermalMonitor = PPGThermalMonitor()

  private var phase: SessionPhase = .idle
  private var configuration: MeasurementConfiguration?
  private var contactDetector: PPGFingerContactDetector?
  private var terminalThermalState: ThermalState?
  private var numericSamples: [PPGFrameSample] = []
  private var startedAtMonotonicSeconds = 0.0
  private var terminalReason: String?
  private var bufferLimitReached = false

  private var processedFrameCount = 0
  private var droppedFrameCount = 0
  private var acquisitionDroppedFrameCount = 0
  private var lastObservedTimestamp: Double?
  private var recentFrameIntervals: [Double] = []
  private var maximumAcquisitionGapSeconds = 0.0

  private var validContactStartedAt: Double?
  private var acquisitionStartedAt: Double?
  private var lastUsableTimestamp: Double?
  private var usableDurationSeconds = 0.0

  private var lastMetrics: PPGFrameColorMetrics?
  private var lastContactEvaluation: PPGContactEvaluation?
  private var liveBpm: Double?
  private var liveIpiMs: Double?
  private var liveBeatSequence = 0
  private var lastLiveAnalysisFrame = 0
  private var liveBeatTracker = PPGLiveBeatTracker()
  private var pendingLiveBeats: [NativeAcceptedBeat] = []
  private var liveWindowQuality: Double?
  private var totalCollectedSampleCount = 0

  override init() {
    recentFrameIntervals.reserveCapacity(90)
    super.init()
  }

  func startMeasurement(configuration nativeConfiguration: NativePPGConfiguration) throws {
    let parsedConfiguration = try MeasurementConfiguration(native: nativeConfiguration)
    let thermalState = thermalMonitor.currentState()
    guard !Self.isUnsafe(thermalState) else {
      throw HaptikaPPGFrameProcessorError.unsafeThermalState(thermalState.stringValue)
    }

    stateLock.lock()
    defer { stateLock.unlock() }
    resetLocked()

    configuration = parsedConfiguration
    contactDetector = PPGFingerContactDetector(
      minimumConfidence: parsedConfiguration.minimumContactConfidence
    )
    numericSamples.reserveCapacity(
      min(
        parsedConfiguration.maximumBufferedSampleCount,
        Int((parsedConfiguration.targetSampleRate * parsedConfiguration.measurementSeconds).rounded(.up))
      )
    )
    startedAtMonotonicSeconds = ProcessInfo.processInfo.systemUptime
    phase = .active
  }

  func processFrame(frame: any HybridFrameSpec) throws -> PPGFrameUpdate? {
    stateLock.lock()
    defer { stateLock.unlock() }

    let thermalState = thermalMonitor.currentState()
    if phase == .thermalStopped {
      // Keep notifying the worklet until React Native acknowledges the terminal state and tears
      // the capture session down. A single callback could be lost while the JS runtime is busy.
      return makeFrameUpdate(
        timestampSeconds: Self.finiteTimestamp(frame.timestamp, fallback: lastObservedTimestamp),
        thermalState: terminalThermalState ?? thermalState,
        metrics: lastMetrics,
        evaluation: lastContactEvaluation
      )
    }

    guard phase == .active, let configuration, let contactDetector else {
      // Camera teardown and Nitro calls can overlap by a frame; ignoring it is safe and avoids
      // retaining an already-finished frame.
      return nil
    }

    if Self.isUnsafe(thermalState) {
      phase = .thermalStopped
      terminalThermalState = thermalState
      terminalReason = "thermal_\(thermalState.stringValue)"
      processedFrameCount += 1
      return makeFrameUpdate(
        timestampSeconds: Self.finiteTimestamp(frame.timestamp, fallback: lastObservedTimestamp),
        thermalState: thermalState,
        metrics: lastMetrics,
        evaluation: lastContactEvaluation
      )
    }

    guard frame.isValid,
          let nativeFrame = frame as? any NativeFrame,
          let sampleBuffer = nativeFrame.sampleBuffer
    else {
      throw HaptikaPPGFrameProcessorError.frameUnavailable
    }

    // The sample buffer is intentionally scoped to this call. The extractor returns value-only
    // metrics and never stores the CMSampleBuffer or CVPixelBuffer.
    let metrics = try metricsExtractor.extract(from: sampleBuffer)
    processedFrameCount += 1
    let shouldEmit = processedFrameCount.isMultiple(of: configuration.emitEveryFrames)

    guard recordFrameTimingLocked(
      timestampSeconds: metrics.timestampSeconds,
      configuration: configuration
    ) else {
      if shouldEmit {
        return makeFrameUpdate(
          timestampSeconds: lastObservedTimestamp ?? metrics.timestampSeconds,
          thermalState: thermalState,
          metrics: lastMetrics,
          evaluation: lastContactEvaluation
        )
      }
      return nil
    }

    let evaluation = contactDetector.evaluate(metrics)
    lastMetrics = metrics
    lastContactEvaluation = evaluation
    updateAcquisitionLocked(
      metrics: metrics,
      evaluation: evaluation,
      configuration: configuration
    )
    updateLiveEstimateLocked(configuration: configuration)

    guard shouldEmit else { return nil }
    return makeFrameUpdate(
      timestampSeconds: metrics.timestampSeconds,
      thermalState: thermalState,
      metrics: metrics,
      evaluation: evaluation
    )
  }

  func finishMeasurement() throws -> NativePPGProcessingResult {
    let snapshot: SessionSnapshot

    stateLock.lock()
    switch phase {
    case .active, .thermalStopped:
      guard let configuration else {
        stateLock.unlock()
        throw HaptikaPPGFrameProcessorError.measurementNotStarted
      }
      phase = .finishing
      snapshot = SessionSnapshot(
        configuration: configuration,
        samples: numericSamples,
        startedAtMonotonicSeconds: startedAtMonotonicSeconds,
        endedAtMonotonicSeconds: ProcessInfo.processInfo.systemUptime,
        processedFrameCount: processedFrameCount,
        droppedFrameCount: droppedFrameCount,
        acquisitionDroppedFrameCount: acquisitionDroppedFrameCount,
        usableDurationSeconds: usableDurationSeconds,
        maximumAcquisitionGapSeconds: maximumAcquisitionGapSeconds,
        bufferLimitReached: bufferLimitReached,
        terminalReason: terminalReason
      )
      stateLock.unlock()
    case .idle, .finishing:
      stateLock.unlock()
      throw HaptikaPPGFrameProcessorError.measurementNotStarted
    }

    defer { resetAfterFinishing() }

    if let terminalReason = snapshot.terminalReason {
      return makeInvalidResult(
        snapshot: snapshot,
        reason: terminalReason,
        issue: "durationInsufficient"
      )
    }
    if snapshot.bufferLimitReached {
      return makeInvalidResult(
        snapshot: snapshot,
        reason: "The numeric measurement buffer reached its safety limit.",
        issue: "nonFiniteProcessingResult"
      )
    }

    do {
      let processor = try PPGSignalProcessor(
        configuration: snapshot.configuration.coreConfiguration
      )
      let analysis = try processor.analyze(samples: snapshot.samples)
      return makeNativeResult(analysis: analysis, snapshot: snapshot)
    } catch {
      let mapped = Self.mapProcessingError(error)
      return makeInvalidResult(
        snapshot: snapshot,
        reason: mapped.reason,
        issue: mapped.issue
      )
    }
  }

  func cancelMeasurement() throws {
    stateLock.lock()
    resetLocked()
    stateLock.unlock()
  }

  func getThermalState() throws -> ThermalState {
    thermalMonitor.currentState()
  }

  private func recordFrameTimingLocked(
    timestampSeconds: Double,
    configuration: MeasurementConfiguration
  ) -> Bool {
    guard timestampSeconds.isFinite, timestampSeconds >= 0 else {
      droppedFrameCount += 1
      if acquisitionStartedAt != nil { acquisitionDroppedFrameCount += 1 }
      return false
    }
    guard let previousTimestamp = lastObservedTimestamp else {
      lastObservedTimestamp = timestampSeconds
      return true
    }

    let interval = timestampSeconds - previousTimestamp
    guard interval > 0 else {
      droppedFrameCount += 1
      if acquisitionStartedAt != nil { acquisitionDroppedFrameCount += 1 }
      return false
    }

    if acquisitionStartedAt != nil {
      maximumAcquisitionGapSeconds = max(maximumAcquisitionGapSeconds, interval)
    }
    if recentFrameIntervals.count >= 5 {
      let expectedInterval = SignalStatistics.median(recentFrameIntervals)
      if expectedInterval > 0, interval > expectedInterval * 1.5 {
        let estimatedMissing = min(
          max((interval / expectedInterval).rounded() - 1, 0),
          100_000
        )
        let missingCount = Int(estimatedMissing)
        droppedFrameCount += missingCount
        if acquisitionStartedAt != nil { acquisitionDroppedFrameCount += missingCount }
      }
    }

    if interval <= max(configuration.maximumInterpolationGapSeconds, 0.25) {
      recentFrameIntervals.append(interval)
      if recentFrameIntervals.count > 90 {
        recentFrameIntervals.removeFirst(recentFrameIntervals.count - 90)
      }
    }
    lastObservedTimestamp = timestampSeconds
    return true
  }

  private func updateAcquisitionLocked(
    metrics: PPGFrameColorMetrics,
    evaluation: PPGContactEvaluation,
    configuration: MeasurementConfiguration
  ) {
    // Acquisition is intentionally clock-based rather than contact-gated. A
    // contact detector is useful feedback, but making it a hard gate can leave
    // a complete minute with zero samples on cameras whose color response is
    // different. The signal processor still rejects low-SNR, saturated and
    // motion-corrupted portions at the end.
    // Store compact numeric samples from the first camera frame. The final
    // processor decides which portions are usable. Do not derive a camera
    // frame count from the 100 Hz resampling target, and do not throw away a
    // good signal merely because the contact heuristic is conservative.
    if acquisitionStartedAt == nil {
      acquisitionStartedAt = metrics.timestampSeconds
      lastUsableTimestamp = nil
    }

    guard acquisitionStartedAt != nil else { return }

    let sample = PPGFrameSample(
          timestampSeconds: metrics.timestampSeconds,
          red: metrics.redMean,
          green: metrics.greenMean,
          blue: metrics.blueMean,
          luminance: metrics.luminanceMean,
          contactConfidence: evaluation.confidence,
          saturationRatio: metrics.saturationRatio,
          motionArtifactScore: evaluation.motionArtifactScore
        )
    totalCollectedSampleCount += 1
    if configuration.sessionPurpose == .coherence {
      numericSamples.append(sample)
      if numericSamples.count > configuration.maximumBufferedSampleCount {
        numericSamples.removeFirst(numericSamples.count - configuration.maximumBufferedSampleCount)
      }
    } else if numericSamples.count < configuration.maximumBufferedSampleCount {
      numericSamples.append(sample)
    } else {
      bufferLimitReached = true
    }

    let opticallyUsable = evaluation.confidence >= 0.35
      && metrics.saturationRatio <= 0.95
      && evaluation.motionArtifactScore <= 0.90
    if opticallyUsable {
      if let previousTimestamp = lastUsableTimestamp {
        let interval = metrics.timestampSeconds - previousTimestamp
        if interval > 0, interval <= configuration.maximumInterpolationGapSeconds {
          usableDurationSeconds += interval
        }
      }
      lastUsableTimestamp = metrics.timestampSeconds
    } else {
      // Never bridge quality time across a finger removal or a large movement.
      lastUsableTimestamp = nil
    }
  }

  private func makeFrameUpdate(
    timestampSeconds: Double,
    thermalState: ThermalState,
    metrics: PPGFrameColorMetrics?,
    evaluation: PPGContactEvaluation?
  ) -> PPGFrameUpdate {
    let signalLevel = min(max((evaluation?.pulsatileAmplitude ?? 0) / 0.03, 0), 1)
    let waveformValue: Double
    if let metrics {
      waveformValue = metrics.greenMean / max(metrics.redMean + metrics.greenMean + metrics.blueMean, 1)
    } else {
      waveformValue = 0
    }
    return PPGFrameUpdate(
      timestampSeconds: timestampSeconds,
      contactState: evaluation?.state ?? .absent,
      contactConfidence: min(max(evaluation?.confidence ?? 0, 0), 1),
      signalLevel: signalLevel,
      saturationRatio: min(max(metrics?.saturationRatio ?? 0, 0), 1),
      motionArtifactScore: min(max(evaluation?.motionArtifactScore ?? 0, 0), 1),
      collectedSampleCount: Double(totalCollectedSampleCount),
      usableDurationSeconds: usableDurationSeconds,
      droppedFrameCount: Double(droppedFrameCount),
      thermalState: thermalState,
      waveformValue: waveformValue,
      liveBpm: liveBpm,
      liveIpiMs: liveIpiMs,
      beatSequence: Double(liveBeatSequence),
      acceptedBeats: takePendingLiveBeatsLocked(),
      liveWindowQuality: liveWindowQuality
    )
  }

  private func takePendingLiveBeatsLocked() -> [NativeAcceptedBeat] {
    let beats = pendingLiveBeats
    pendingLiveBeats.removeAll(keepingCapacity: true)
    return beats
  }

  private func updateLiveEstimateLocked(configuration: MeasurementConfiguration) {
    // Camera input is constrained to 30 fps. The final 100 Hz configuration
    // is a resampling timebase and must not delay live BPM warm-up to 23 s.
    let liveInputSampleRate = 30.0
    guard numericSamples.count >= Int(liveInputSampleRate * 7),
          processedFrameCount - lastLiveAnalysisFrame >= 15
    else { return }
    lastLiveAnalysisFrame = processedFrameCount

    let maximumWindowCount = Int(liveInputSampleRate * 15)
    let window = Array(numericSamples.suffix(maximumWindowCount))
    let liveConfiguration = PPGProcessingConfiguration(
      // A lightweight 30 Hz pass is enough for the live display. The final
      // analysis still uses the regular 100 Hz timebase.
      targetSampleRateHz: min(configuration.targetSampleRate, 30),
      minimumFrequencyHz: configuration.minimumFrequencyHz,
      maximumFrequencyHz: configuration.maximumFrequencyHz,
      minimumAnalysisDurationSeconds: 6,
      maximumInterpolationGapSeconds: configuration.maximumInterpolationGapSeconds,
      longGapLimitSeconds: configuration.longGapLimitSeconds,
      minimumContactConfidence: min(configuration.minimumContactConfidence, 0.45),
      maximumSaturationRatio: 0.55,
      maximumMotionArtifactScore: 0.65,
      minimumPeakProminence: 0.28,
      minimumPeakAmplitude: 0.08,
      refractoryPeriodSeconds: 0.30,
      maximumMethodDisagreementBPM: 12,
      minimumQualityScore: 0.35,
      minimumIntervalsForPRV: 4,
      maximumRejectedIntervalRatioForPRV: 0.45,
      filterTapCount: 31
    )

    guard let analysis = try? PPGSignalProcessor(configuration: liveConfiguration)
      .analyze(samples: window)
    else { return }
    liveWindowQuality = analysis.quality.score

    if let bpm = analysis.bpm.bpm ?? analysis.bpm.temporalBpm,
       bpm.isFinite, (35...220).contains(bpm) {
      liveBpm = bpm
    }
    let acceptedIntervals = analysis.intervals.filter(\.isAccepted)
    if let interval = acceptedIntervals.last,
       interval.durationMilliseconds.isFinite {
      liveIpiMs = interval.durationMilliseconds
    }

    // The live analysis uses an overlapping window. Count every newly seen
    // accepted interval instead of incrementing only once per analysis pass;
    // otherwise a 90 BPM pulse sampled every 0.5 s loses real beats.
    let newlyAccepted = liveBeatTracker.ingest(acceptedIntervals)
    for beat in newlyAccepted {
      liveBeatSequence = beat.sequence
      pendingLiveBeats.append(
        NativeAcceptedBeat(
          sequence: Double(beat.sequence),
          timestampSeconds: beat.timestampSeconds,
          intervalMs: beat.intervalMs,
          confidence: beat.confidence
        )
      )
    }
  }

  private func makeNativeResult(
    analysis: PPGAnalysisResult,
    snapshot: SessionSnapshot
  ) -> NativePPGProcessingResult {
    var issues = analysis.quality.issues.map(Self.nativeIssue)
    if analysis.bpm.rejectedPeakCount > max(3, analysis.bpm.validPeakCount / 4) {
      Self.appendUnique("tooManyRejectedPeaks", to: &issues)
    }

    let observedDroppedRatio = snapshot.samples.isEmpty
      ? 0
      : Double(snapshot.acquisitionDroppedFrameCount)
        / Double(snapshot.samples.count + snapshot.acquisitionDroppedFrameCount)
    let droppedFrameRatio = min(
      max(max(analysis.quality.droppedFrameRatio, observedDroppedRatio), 0),
      1
    )
    if droppedFrameRatio > 0.12 {
      Self.appendUnique("droppedFrames", to: &issues)
    }

    let timestampJitterRatio = Self.timestampJitterRatio(analysis.timebase)
    let longestGapSeconds = max(
      analysis.timebase.maximumGapSeconds,
      snapshot.maximumAcquisitionGapSeconds
    )
    let isValid = analysis.status == .valid
    let invalidReason = isValid ? nil : Self.invalidReason(for: issues)
    let resampledSampleCount = max(
      Int((analysis.timebase.durationSeconds * snapshot.configuration.targetSampleRate).rounded(.down)) + 1,
      0
    )

    return NativePPGProcessingResult(
      valid: isValid,
      invalidReason: invalidReason,
      bpm: NativeBPMEstimate(
        bpm: analysis.bpm.bpm,
        temporalBpm: analysis.bpm.temporalBpm,
        frequencyBpm: analysis.bpm.frequencyBpm,
        methodAgreementBpm: analysis.bpm.methodAgreementBpm,
        validPeakCount: Double(analysis.bpm.validPeakCount),
        rejectedPeakCount: Double(analysis.bpm.rejectedPeakCount),
        confidence: analysis.bpm.confidence,
        selectedChannel: analysis.bpm.selectedChannel.rawValue
      ),
      prv: NativePRVMetrics(
        estimatedRmssdMs: analysis.prv.estimatedRmssdMs,
        estimatedSdnnMs: analysis.prv.estimatedSdnnMs,
        meanIpiMs: analysis.prv.meanIpiMs,
        medianIpiMs: analysis.prv.medianIpiMs,
        pnn50Percent: analysis.prv.pnn50Percent,
        rangeIpiMs: analysis.prv.rangeIpiMs,
        modeIpiMs: analysis.prv.modeIpiMs,
        amo50Percent: analysis.prv.amo50Percent,
        coefficientOfVariation: analysis.prv.coefficientOfVariation,
        validIntervalCount: Double(analysis.prv.validIntervalCount),
        rejectedIntervalCount: Double(analysis.prv.rejectedIntervalCount),
        rejectedIntervalRatio: analysis.prv.rejectedIntervalRatio,
        reliable: analysis.prv.reliable
      ),
      quality: NativeSignalQualityResult(
        score: analysis.quality.score,
        level: analysis.quality.level.rawValue,
        usableDurationSeconds: analysis.quality.usableDurationSeconds,
        droppedFrameRatio: droppedFrameRatio,
        saturationRatio: analysis.quality.saturationRatio,
        rejectedIntervalRatio: analysis.quality.rejectedIntervalRatio,
        signalToNoiseRatio: analysis.quality.signalToNoiseRatio,
        motionArtifactRatio: analysis.quality.motionArtifactRatio,
        methodAgreementScore: analysis.quality.methodAgreementScore,
        timestampJitterRatio: timestampJitterRatio,
        longestGapSeconds: longestGapSeconds,
        issues: issues
      ),
      startedAtMonotonicSeconds: snapshot.startedAtMonotonicSeconds,
      endedAtMonotonicSeconds: snapshot.endedAtMonotonicSeconds,
      rawSampleCount: Double(snapshot.samples.count),
      resampledSampleCount: Double(resampledSampleCount)
    )
  }

  private func makeInvalidResult(
    snapshot: SessionSnapshot,
    reason: String,
    issue: String
  ) -> NativePPGProcessingResult {
    let intervals = zip(snapshot.samples, snapshot.samples.dropFirst()).compactMap { pair -> Double? in
      let interval = pair.1.timestampSeconds - pair.0.timestampSeconds
      return interval.isFinite && interval > 0 ? interval : nil
    }
    let estimatedRate = intervals.isEmpty ? 0 : 1 / max(SignalStatistics.median(intervals), 1e-9)
    let intervalMAD = intervals.isEmpty ? 0 : SignalStatistics.mad(intervals)
    let jitterRatio = estimatedRate > 0 ? intervalMAD * estimatedRate : 0
    let saturation = snapshot.samples.isEmpty
      ? 0
      : SignalStatistics.mean(snapshot.samples.map(\.saturationRatio))
    let motion = snapshot.samples.isEmpty
      ? 0
      : SignalStatistics.mean(snapshot.samples.map(\.motionArtifactScore))
    let droppedRatio = snapshot.samples.isEmpty
      ? 0
      : Double(snapshot.acquisitionDroppedFrameCount)
        / Double(snapshot.samples.count + snapshot.acquisitionDroppedFrameCount)

    return NativePPGProcessingResult(
      valid: false,
      invalidReason: reason,
      bpm: NativeBPMEstimate(
        bpm: nil,
        temporalBpm: nil,
        frequencyBpm: nil,
        methodAgreementBpm: nil,
        validPeakCount: 0,
        rejectedPeakCount: 0,
        confidence: 0,
        selectedChannel: "none"
      ),
      prv: NativePRVMetrics(
        estimatedRmssdMs: nil,
        estimatedSdnnMs: nil,
        meanIpiMs: nil,
        medianIpiMs: nil,
        pnn50Percent: nil,
        rangeIpiMs: nil,
        modeIpiMs: nil,
        amo50Percent: nil,
        coefficientOfVariation: nil,
        validIntervalCount: 0,
        rejectedIntervalCount: 0,
        rejectedIntervalRatio: snapshot.samples.isEmpty ? 1 : 0,
        reliable: false
      ),
      quality: NativeSignalQualityResult(
        score: 0,
        level: "invalid",
        usableDurationSeconds: snapshot.usableDurationSeconds,
        droppedFrameRatio: min(max(droppedRatio, 0), 1),
        saturationRatio: min(max(saturation, 0), 1),
        rejectedIntervalRatio: snapshot.samples.isEmpty ? 1 : 0,
        signalToNoiseRatio: nil,
        motionArtifactRatio: min(max(motion, 0), 1),
        methodAgreementScore: 0,
        timestampJitterRatio: max(jitterRatio, 0),
        longestGapSeconds: snapshot.maximumAcquisitionGapSeconds,
        issues: [issue]
      ),
      startedAtMonotonicSeconds: snapshot.startedAtMonotonicSeconds,
      endedAtMonotonicSeconds: snapshot.endedAtMonotonicSeconds,
      rawSampleCount: Double(snapshot.samples.count),
      resampledSampleCount: 0
    )
  }

  private func resetAfterFinishing() {
    stateLock.lock()
    resetLocked()
    stateLock.unlock()
  }

  private func resetLocked() {
    contactDetector?.reset()
    contactDetector = nil
    configuration = nil
    terminalThermalState = nil
    numericSamples.removeAll(keepingCapacity: false)
    phase = .idle
    startedAtMonotonicSeconds = 0
    terminalReason = nil
    bufferLimitReached = false

    processedFrameCount = 0
    droppedFrameCount = 0
    acquisitionDroppedFrameCount = 0
    lastObservedTimestamp = nil
    recentFrameIntervals.removeAll(keepingCapacity: true)
    maximumAcquisitionGapSeconds = 0

    validContactStartedAt = nil
    acquisitionStartedAt = nil
    lastUsableTimestamp = nil
    usableDurationSeconds = 0

    lastMetrics = nil
    lastContactEvaluation = nil
    liveBpm = nil
    liveIpiMs = nil
    liveBeatSequence = 0
    liveBeatTracker.reset()
    lastLiveAnalysisFrame = 0
    pendingLiveBeats.removeAll(keepingCapacity: false)
    liveWindowQuality = nil
    totalCollectedSampleCount = 0
  }

  private static func isUnsafe(_ state: ThermalState) -> Bool {
    PPGThermalSafetyPolicy.shouldStopMeasurement(forStateName: state.stringValue)
  }

  private static func finiteTimestamp(_ timestamp: Double, fallback: Double?) -> Double {
    if timestamp.isFinite, timestamp >= 0 { return timestamp }
    return fallback ?? 0
  }

  private static func timestampJitterRatio(_ diagnostics: TimebaseDiagnostics) -> Double {
    guard diagnostics.estimatedSampleRateHz > 0 else { return 0 }
    return max(diagnostics.frameIntervalMADSeconds * diagnostics.estimatedSampleRateHz, 0)
  }

  private static func nativeIssue(_ issue: SignalQualityIssue) -> String {
    switch issue {
    case .insufficientDuration:
      return "durationInsufficient"
    case .invalidTimestamps, .irregularTimestamps:
      return "timestampJitter"
    case .longInterruption:
      return "longGap"
    case .tooManyDroppedFrames:
      return "droppedFrames"
    case .poorFingerContact:
      return "contactInsufficient"
    case .excessiveSaturation:
      return "saturation"
    case .motionArtifacts:
      return "motionArtifacts"
    case .lowPulsatileAmplitude:
      return "lowPulsatileAmplitude"
    case .lowSignalToNoise:
      return "lowSignalToNoiseRatio"
    case .tooFewPeaks:
      return "tooFewPeaks"
    case .inconsistentBPMMethods:
      return "methodDisagreement"
    case .tooManyRejectedIntervals:
      return "tooManyRejectedIntervals"
    case .unstableChannel:
      return "channelInstability"
    case .nonFiniteInput:
      return "nonFiniteProcessingResult"
    }
  }

  private static func appendUnique(_ issue: String, to issues: inout [String]) {
    if !issues.contains(issue) { issues.append(issue) }
  }

  private static func invalidReason(for issues: [String]) -> String {
    guard let issue = issues.first else {
      return "La qualité du signal est insuffisante."
    }
    switch issue {
    case "contactInsufficient", "contactInterrupted":
      return "Le contact du doigt a été insuffisant ou interrompu."
    case "durationInsufficient":
      return "La durée de signal exploitable est insuffisante."
    case "droppedFrames", "timestampJitter", "longGap":
      return "La capture comporte trop d’interruptions ou d’images manquantes."
    case "saturation":
      return "Le signal caméra est trop saturé."
    case "motionArtifacts":
      return "Trop de mouvements ont perturbé la mesure."
    case "lowPulsatileAmplitude", "lowSignalToNoiseRatio":
      return "Le signal pulsatile est trop faible ou trop bruité."
    case "tooFewPeaks", "tooManyRejectedPeaks", "tooManyRejectedIntervals":
      return "Trop peu de pulsations fiables ont été détectées."
    case "methodDisagreement":
      return "Les estimations temporelle et fréquentielle ne concordent pas."
    case "channelInstability":
      return "Aucun canal couleur n’est suffisamment stable."
    default:
      return "Le traitement numérique du signal a produit un résultat invalide."
    }
  }

  private static func mapProcessingError(_ error: Error) -> (reason: String, issue: String) {
    guard let signalError = error as? PPGSignalError else {
      return ("Le traitement numérique du signal a échoué.", "nonFiniteProcessingResult")
    }
    switch signalError {
    case .insufficientSamples, .insufficientDuration:
      return ("La durée de signal exploitable est insuffisante.", "durationInsufficient")
    case .invalidTimestamps:
      return ("Les horodatages caméra sont invalides.", "timestampJitter")
    case .noUsableChannel:
      return ("Aucun canal couleur n’est exploitable.", "channelInstability")
    case .invalidConfiguration:
      return ("La configuration du traitement du signal est invalide.", "nonFiniteProcessingResult")
    }
  }
}

private enum HaptikaPPGFrameProcessorError: LocalizedError {
  case invalidConfiguration(String)
  case unsafeThermalState(String)
  case frameUnavailable
  case measurementNotStarted

  var errorDescription: String? {
    switch self {
    case .invalidConfiguration(let reason):
      return "Invalid PPG configuration: \(reason)."
    case .unsafeThermalState(let state):
      return "PPG measurement refused because the iPhone thermal state is \(state)."
    case .frameUnavailable:
      return "The VisionCamera frame is invalid or does not expose a CMSampleBuffer."
    case .measurementNotStarted:
      return "No PPG measurement is currently active."
    }
  }
}