latency_evidence.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/audio/analysis/audio_metrics.hpp>
#include <pulp/audio/buffer.hpp>
 
#include <cstdint>
#include <optional>
#include <string>
 
namespace pulp::test::audio {

enum class LatencyReportStatus {
    available,     
    unsupported,   
    query_failed,  
    invalid,       
};

enum class LatencyReportObservation {
    stable,        
    changed,       
    unobservable,  
};

enum class LatencyObservationMode {
    processor_flag_and_poll,  
    per_block_poll,           
    none,                     
};

enum class LatencyPolicy {
    none,
    delayed_passthrough_null,
    marker_offset,
};

enum class LatencyMeasurementStatus {
    match,           
    mismatch,        
    not_measurable,  
    not_requested,   
};

enum class LatencyContractOutcome {
    satisfied,      
    violated,       
    inconclusive,   
    not_requested,  
};

struct LatencyEvidence {
    // ── Facts read from the processor / host ────────────────────────────────
    LatencyReportStatus report_status = LatencyReportStatus::unsupported;
    std::optional<int> reported_samples;
    std::optional<int> final_reported_samples;
    LatencyReportObservation report_observation = LatencyReportObservation::unobservable;
    LatencyObservationMode observation_mode = LatencyObservationMode::none;
 
    // ── The measurement ─────────────────────────────────────────────────────
    LatencyPolicy policy = LatencyPolicy::none;
    LatencyMeasurementStatus measurement_status = LatencyMeasurementStatus::not_requested;
    std::optional<std::int64_t> measured_samples;
    std::optional<std::int64_t> delta_samples;
    std::int64_t tolerance_samples = 0;
 
    // ── How much to trust the measurement ───────────────────────────────────
    //
    // Both are populated by the delayed-null policy only; the marker policy
    // finds an onset rather than nulling, so neither number exists for it.
    //
    // They are the difference between "the measurement passed" and "the
    // measurement passed, and here is how far it was from being a coin flip."
    // An agent reading the artifact should treat a 2 dB margin as a hair's
    // breadth from ambiguous even though it technically cleared the bar.

    std::optional<double> null_depth_db;

    std::optional<double> ambiguity_margin_db;

    std::optional<int> expected_samples;
 
    // ── The verdict ─────────────────────────────────────────────────────────
    LatencyContractOutcome contract_outcome = LatencyContractOutcome::not_requested;
    std::string reason;

    bool gates_failure() const {
        return contract_outcome == LatencyContractOutcome::violated ||
               contract_outcome == LatencyContractOutcome::inconclusive;
    }
};

struct DelayedNullOptions {
    std::int64_t max_delay_samples = 8192;
    double null_floor_db = -60.0;
    double ambiguity_margin_db = 12.0;
    std::int64_t tolerance_samples = 0;
};

LatencyEvidence measure_delayed_passthrough(const pulp::audio::Buffer<float>& input,
                                            const pulp::audio::Buffer<float>& output,
                                            std::optional<int> reported_samples,
                                            const DelayedNullOptions& options = {});

struct MarkerOffsetOptions {
    std::int64_t input_marker_frame = 0;
    std::int64_t intrinsic_response_offset = 0;
    double onset_threshold = 1e-3;
    std::int64_t tolerance_samples = 0;
};

LatencyEvidence measure_marker_offset(const pulp::audio::Buffer<float>& input,
                                      const pulp::audio::Buffer<float>& output,
                                      std::optional<int> reported_samples,
                                      const MarkerOffsetOptions& options = {});

LatencyEvidence& apply_report_observation(LatencyEvidence& evidence);

LatencyEvidence& apply_expected_samples(LatencyEvidence& evidence, int expected,
                                        std::int64_t tolerance_samples = 0);
 
// ── Serialization ───────────────────────────────────────────────────────────
// One schema, shared by tests, the CLI, and MCP, so a verdict cannot drift
// between surfaces.
 
const char* to_string(LatencyReportStatus status);
const char* to_string(LatencyReportObservation observation);
const char* to_string(LatencyObservationMode mode);
const char* to_string(LatencyPolicy policy);
const char* to_string(LatencyMeasurementStatus status);
const char* to_string(LatencyContractOutcome outcome);

inline constexpr int kLatencyEvidenceSchemaVersion = 1;

std::string latency_evidence_to_json(const LatencyEvidence& evidence);

std::string latency_evidence_summary(const LatencyEvidence& evidence);
 
} // namespace pulp::test::audio