fix(freshness): send freshness diagnostics in milliseconds with measure=time (#2770)

V4 (contract-scan) freshness checks rendered in Soda Cloud check charts as
raw, unitless floats (e.g. "11.15...") instead of a human-readable duration.
The diagnostics payload was wrong in two ways:

1. measure missing: diagnostics never set a `measure` key, so Soda Cloud and
   the frontend formatted the value as a plain number rather than a duration.
2. wrong unit: `value` (and the `fail` threshold bounds) were emitted in the
   check's configured unit (fractional hours/days) instead of milliseconds.

The frontend formats a "time" measure by dividing the wire value by 1000 and
rendering it as "X days and Y hours", so it relies on the value being in
milliseconds and tagged with `measure="time"` — exactly the V3 (SodaCL) wire
contract, where freshness sends round(total_seconds * 1000) ms + measure="time".

This adds two opt-in hooks on the base CheckResult — `get_soda_cloud_measure()`
(default None) and `to_soda_cloud_measure_value()` (identity) — overridden by
the freshness result to return "time" and scale the configured-unit value to
milliseconds. The diagnostics builder routes the value and fail bounds through
the converter and only emits a `measure` key when non-None, so payloads for all
non-time check types are byte-for-byte unchanged. The unit scale lookup falls
back to the default ("hour") for a missing/unknown unit so it can never KeyError
mid-upload and abort the whole scan's result upload.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: m1n0

soda-core/src/soda_core/common/soda_cloud.py

@@ -1774,14 +1774,25 @@ def _build_diagnostics_json_dict(check_result: CheckResult) -> Optional[dict]:
     # if check_result.outcome == CheckOutcome.EXCLUDED:
     # return None
 
-    return {
+    raw_value = (
         #  TODO: this default 0 value is here only because check.diagnostics.value is a required non-nullable field in the api.
-        "value": int(check_result.threshold_value)
+        int(check_result.threshold_value)
         if isinstance(check_result.threshold_value, bool)
-        else (check_result.threshold_value or 0),
+        else (check_result.threshold_value or 0)
+    )
+    diagnostics: dict = {
+        # ``value`` (and the fail thresholds below) are converted into the measure's
+        # wire unit — identity for plain numbers, milliseconds for "time".
+        "value": check_result.to_soda_cloud_measure_value(raw_value),
         "fail": _build_fail_threshold(check_result),
         "v4": _build_v4_diagnostics_check_type_json_dict(check_result),
     }
+    # Unit/type marker so Soda Cloud can format the value (e.g. freshness as a
+    # duration rather than a raw float). Omitted for plain-number checks.
+    measure: Optional[str] = check_result.get_soda_cloud_measure()
+    if measure is not None:
+        diagnostics["measure"] = measure
+    return diagnostics
 
 
 def _build_v4_diagnostics_check_type_json_dict(check_result: CheckResult) -> Optional[dict]:
@@ -1900,11 +1911,15 @@ def _build_schema_column(column_metadata: ColumnMetadata) -> Optional[dict]:
 def _build_fail_threshold(check_result: CheckResult) -> Optional[dict]:
     threshold: Threshold = check_result.check.threshold
     if threshold:
+        # Bounds are expressed in the check's native unit; convert into the measure's
+        # wire unit so the chart's threshold line matches the value (ms for "time").
+        # Identity for plain-number checks, so existing payloads are unchanged.
+        convert = check_result.to_soda_cloud_measure_value
         return {
-            "greaterThan": threshold.must_be_less_than_or_equal,
-            "greaterThanOrEqual": threshold.must_be_less_than,
-            "lessThan": threshold.must_be_greater_than_or_equal,
-            "lessThanOrEqual": threshold.must_be_greater_than,
+            "greaterThan": convert(threshold.must_be_less_than_or_equal),
+            "greaterThanOrEqual": convert(threshold.must_be_less_than),
+            "lessThan": convert(threshold.must_be_greater_than_or_equal),
+            "lessThanOrEqual": convert(threshold.must_be_greater_than),
         }
     return None
 

soda-core/src/soda_core/contracts/contract_verification.py

@@ -403,6 +403,24 @@ def is_not_evaluated(self) -> bool:
     def is_excluded(self) -> bool:
         return self.outcome == CheckOutcome.EXCLUDED
 
+    def get_soda_cloud_measure(self) -> Optional[str]:
+        """Unit/type marker Soda Cloud uses to format this check's value.
+
+        ``None`` (the default) means "render as a plain number". Subtypes whose
+        value represents a duration return ``"time"`` so Soda Cloud formats it as a
+        human-readable duration instead of a raw float.
+        """
+        return None
+
+    def to_soda_cloud_measure_value(self, value: Optional[Number]) -> Optional[Number]:
+        """Convert a value (the check value or a threshold bound) into the unit Soda
+        Cloud expects for ``get_soda_cloud_measure()``.
+
+        Identity by default. Overridden where the wire unit differs from the check's
+        native unit — e.g. the ``"time"`` measure is always milliseconds.
+        """
+        return value
+
     def log_table_row(self) -> dict:
         row = {}
         row["Column"] = self.check.column_name if self.check.column_name else "[dataset-level]"

soda-core/src/soda_core/contracts/impl/check_types/freshness_check.py

@@ -305,6 +305,29 @@ def __init__(
         self.freshness_in_seconds: Optional[int] = freshness_in_seconds
         self.unit: Optional[str] = unit
 
+    # Seconds per freshness unit, mirroring _convert_freshness_seconds_to_check_unit.
+    _UNIT_SECONDS: dict[str, int] = {"second": 1, "minute": 60, "hour": 60 * 60, "day": 60 * 60 * 24}
+    # Matches FreshnessCheckImplBase.__init__, which defaults the unit to "hour".
+    _DEFAULT_UNIT: str = "hour"
+
+    def get_soda_cloud_measure(self) -> Optional[str]:
+        # Freshness is semantically a duration: tag it so Soda Cloud formats the
+        # value as "X days and Y hours" instead of a raw float.
+        return "time"
+
+    def to_soda_cloud_measure_value(self, value: Optional[float | int]) -> Optional[int]:
+        # Soda Cloud's "time" measure expects milliseconds — this is the V3 wire
+        # contract (soda-library FreshnessCheck sent round(total_seconds * 1000)).
+        # The check value and its thresholds are expressed in the configured ``unit``,
+        # so scale unit -> milliseconds.
+        if value is None:
+            return None
+        # ``unit`` is set from the check (default "hour"), but it is typed Optional and
+        # an unknown value would KeyError mid-upload — fall back to the configured
+        # default so a bad/missing unit never aborts the whole scan's result upload.
+        unit_seconds: int = self._UNIT_SECONDS.get(self.unit, self._UNIT_SECONDS[self._DEFAULT_UNIT])
+        return round(value * unit_seconds * 1000)
+
     # def log_summary(self, logs: Logs) -> None:
     #     super().log_summary(logs)
     #

soda-tests/tests/integration/test_freshness_check.py

@@ -69,6 +69,13 @@ def test_freshness(data_source_test_helper: DataSourceTestHelper):
             "expectedTimestampUtc": "2025-01-04T10:00:00+00:00",
             "datasetRowsTested": 6,
         }
+        # Freshness diagnostics must carry the "time" measure marker, and (matching the
+        # V3 soda-library wire contract) the value + fail threshold must be in
+        # milliseconds so Soda Cloud renders a duration instead of a raw float.
+        assert check_json["diagnostics"]["measure"] == "time"
+        assert check_json["diagnostics"]["value"] == 3_600_000  # 1 hour in ms
+        # threshold "must_be_less_than: 2" (hours) -> fail when >= 2h -> 7_200_000 ms
+        assert check_json["diagnostics"]["fail"]["greaterThanOrEqual"] == 7_200_000
 
 
 def test_freshness_in_days(data_source_test_helper: DataSourceTestHelper):

soda-tests/tests/unit/test_soda_cloud.py

@@ -769,6 +769,71 @@ def test_build_diagnostics_json_dict_casts_bool_to_int(threshold_value, expected
     assert not isinstance(diagnostics["value"], bool)
 
 
+def _build_freshness_check_result(unit: str, threshold_value: float) -> "FreshnessCheckResult":
+    from soda_core.contracts.impl.check_types.freshness_check import (
+        FreshnessCheckResult,
+    )
+
+    return FreshnessCheckResult(
+        check=mock.MagicMock(),
+        outcome=CheckOutcome.PASSED,
+        threshold_value=threshold_value,
+        diagnostic_metric_values={
+            "dataset_rows_tested": 6,
+            "check_rows_tested": 6,
+            f"freshness_in_{unit}s": threshold_value,
+        },
+        max_timestamp=datetime(2025, 1, 4, 9, 0, 0, tzinfo=timezone.utc),
+        max_timestamp_utc=datetime(2025, 1, 4, 9, 0, 0, tzinfo=timezone.utc),
+        data_timestamp=datetime(2025, 1, 4, 10, 0, 0, tzinfo=timezone.utc),
+        data_timestamp_utc=datetime(2025, 1, 4, 10, 0, 0, tzinfo=timezone.utc),
+        freshness="1:00:00",
+        freshness_in_seconds=3600,
+        unit=unit,
+    )
+
+
+def test_build_diagnostics_json_dict_sets_measure_time_for_freshness():
+    # V4 (contract-scan) freshness values rendered as raw floats in the check charts
+    # because soda-core never emitted a unit/type marker. Soda Cloud reads
+    # ``diagnostics.measure`` (BE ``GenericCoreCheckDiagnostics.getMeasure()``);
+    # for freshness it must be ``"time"`` so the value is formatted as a duration.
+    check_result = _build_freshness_check_result(unit="hour", threshold_value=1.0)
+
+    diagnostics = _build_diagnostics_json_dict(check_result)
+
+    assert diagnostics["measure"] == "time"
+    # V3 wire contract (soda-library FreshnessCheck): the "time" measure value is in
+    # milliseconds, scaled from the check's configured `unit`. 1.0 hour -> 3_600_000 ms.
+    assert diagnostics["value"] == 3_600_000
+
+
+def test_build_diagnostics_json_dict_scales_freshness_days_to_milliseconds():
+    # Locks the unit -> milliseconds scale table for the largest unit. 1.0 day ->
+    # 86_400_000 ms. This is the float the ticket showed rendered raw ("11.15...").
+    check_result = _build_freshness_check_result(unit="day", threshold_value=1.0)
+
+    diagnostics = _build_diagnostics_json_dict(check_result)
+
+    assert diagnostics["measure"] == "time"
+    assert diagnostics["value"] == 86_400_000
+
+
+def test_build_diagnostics_json_dict_omits_measure_for_non_time_checks():
+    # Non-duration checks (e.g. row_count) carry no measure marker, so the key is
+    # absent and Soda Cloud keeps formatting the value as a plain number. This keeps
+    # the existing payload byte-for-byte unchanged for all non-time check types.
+    check_result = CheckResult(
+        check=mock.MagicMock(),
+        outcome=CheckOutcome.PASSED,
+        threshold_value=42,
+    )
+
+    diagnostics = _build_diagnostics_json_dict(check_result)
+
+    assert "measure" not in diagnostics
+
+
 def test_build_token_usage_dicts_serialization():
     from soda_core.common.soda_cloud import _build_token_usage_dicts