@@ -52,6 +52,37 @@ non-empty `tests` tuple or an explicit `exempt_reason` (for example a
 multi-rank NVLS collective that needs an NVLink peer group, or an allocator
 with no compute kernel). Exemptions are visible coverage debt, not silence.
 
+## Golden-value error diagnostics
+
+The functional comparison logs differences even when they pass tolerance. For
+each metric/check, it reports the check result, comparison precision, `atol`,
+`rtol`, and the number of samples outside tolerance. It shows the samples with
+the largest absolute and relative errors, plus the first sample outside
+tolerance if that sample is not already shown. Each sample includes its step,
+golden value, actual value, and allowed absolute error:
+
+- Absolute error: `abs(actual - golden)`.
+- Relative error: `abs(actual - golden) / abs(golden)`, also shown as a percentage.
+- Allowed absolute error: `atol + rtol * abs(golden)`.
+
+Relative error is undefined for a zero golden value and nonzero actual value;
+the absolute tolerance still applies. Non-finite or missing samples have
+undefined errors and are excluded from the finite-sample extrema.
+
+The diagnostics use the same precision and aggregation as the check. Exact
+checks honor the golden's precision marker, approximate checks retain their
+five-decimal comparison, and iteration-time errors compare unrounded medians
+over the selected steady-state samples. Existing tolerance, failure-budget,
+and legacy-placeholder policies are unchanged. In particular, an approximate
+check can pass with some samples outside tolerance; the report shows those
+outliers even when the check passes. Exact checks retain zero tolerance.
+
+A large error is a signal to investigate numerical correctness. A small
+historical-golden difference can also result from a valid change in reduction
+order. Use independent-reference correctness checks and same-implementation
+replay to assess the change before reviewing a golden refresh. Reporting an
+error never updates a golden value.
+
 ## How the requirement is enforced
 
 1. **Repository invariant** (`tests/unit_tests/determinism/kernels/test_manifest.py`,
 
@@ -216,6 +216,8 @@ decimals until they are regenerated from a CI run.
 
 ---
 
+Golden comparisons report absolute and relative errors; see [diagnostics](../../docs/developer/determinism/testing.md).
+
 ## Common Pitfalls
 
 | Problem | Cause | Fix |
 
@@ -247,6 +247,86 @@ def _round_values(values: List[Union[int, float, str]]) -> List[Union[int, float
     return [round(value, 5) if not isinstance(value, str) else value for value in values]
 
 
+def _log_comparison_errors(
+    metric_name: str,
+    test: Union[ApproximateTest, DeterministicTest],
+    steps: List[Union[int, str]],
+    actual: np.ndarray,
+    golden: np.ndarray,
+    is_close: np.ndarray,
+    precision: ValuePrecision,
+    passing: bool,
+) -> None:
+    """Report the largest errors at the precision and aggregation used by the check."""
+    if np.array_equal(actual, golden):
+        return
+
+    finite = np.isfinite(actual) & np.isfinite(golden)
+    absolute_error = np.full(actual.shape, np.nan)
+    relative_error = np.full(actual.shape, np.nan)
+    # Cast before subtracting so integer metrics cannot wrap. Invalid/missing samples
+    # retain undefined errors; they must not contaminate finite-sample extrema.
+    with np.errstate(over="ignore", invalid="ignore", divide="ignore"):
+        absolute_error[finite] = np.abs(
+            actual[finite].astype(np.float64) - golden[finite].astype(np.float64)
+        )
+        np.divide(
+            absolute_error, np.abs(golden.astype(np.float64)), out=relative_error, where=golden != 0
+        )
+    # Define an exact zero/zero match as zero relative error.
+    relative_error[finite & (golden == 0) & (actual == 0)] = 0
+
+    outside_tolerance = np.flatnonzero(~is_close)
+    logger.info(
+        "Golden comparison for %s [%s]: %s; %d/%d samples outside tolerance; "
+        "atol=%.9g, rtol=%.9g, precision=%s",
+        metric_name,
+        test.type_of_test_result.name,
+        "PASSED" if passing else "FAILED",
+        len(outside_tolerance),
+        len(actual),
+        test.atol,
+        test.rtol,
+        precision.value,
+    )
+
+    samples = {}
+    finite_indices = np.flatnonzero(finite)
+    if len(finite_indices):
+        index = int(finite_indices[np.argmax(absolute_error[finite])])
+        samples[index] = ["max_absolute_error"]
+    relative_indices = np.flatnonzero(finite & ~np.isnan(relative_error))
+    if len(relative_indices):
+        index = int(relative_indices[np.argmax(relative_error[relative_indices])])
+        samples.setdefault(index, []).append("max_relative_error")
+    if len(outside_tolerance) and outside_tolerance[0] not in samples:
+        samples[int(outside_tolerance[0])] = ["first_outside_tolerance"]
+
+    value_format = ".5f" if precision == ValuePrecision.ROUNDED_5_DECIMAL_PLACES else ".17g"
+    for index, labels in samples.items():
+        if not finite[index]:
+            abs_text = rel_text = allowed_text = "n/a (non-finite or missing)"
+        else:
+            abs_text = f"{absolute_error[index]:.9g}"
+            rel_text = (
+                "n/a (zero golden)"
+                if np.isnan(relative_error[index])
+                else f"{relative_error[index]:.9g} ({relative_error[index] * 100:.9g}%)"
+            )
+            allowed_text = f"{test.atol + test.rtol * abs(float(golden[index])):.9g}"
+        logger.info(
+            "  %s at %s: golden=%s, actual=%s, absolute_error=%s, "
+            "relative_error=%s, allowed_absolute_error=%s",
+            ", ".join(labels),
+            steps[index],
+            format(golden[index], value_format),
+            format(actual[index], value_format),
+            abs_text,
+            rel_text,
+            allowed_text,
+        )
+
+
 def pipeline(
     compare_approximate_results: bool,
     golden_values: Dict[str, GoldenValueMetric],
@@ -276,6 +356,7 @@ def pipeline(
                         f"Metric {metric_name} has no values in the golden file."
                     )
 
+                sample_labels: List[Union[int, str]] = list(golden_value.values)
                 golden_value_list = list(golden_value.values.values())
                 actual_value_list = [
                     actual_values[metric_name].values.get(value_step, "nan")
@@ -333,6 +414,8 @@ def pipeline(
                     actual_value_list = [
                         np.median([np.inf if isinstance(v, str) else v for v in actual_value_list])
                     ]
+                    sample_labels = [f"median over steps {', '.join(map(str, comparison_steps))}"]
+                    comparison_precision = ValuePrecision.FULL
                     total_steps_evaluated = 1
                 else:
                     total_steps_evaluated = len(golden_value.values)
@@ -361,13 +444,19 @@ def pipeline(
                         num_failing_steps_allowed / total_steps_evaluated
                     )
 
+                _log_comparison_errors(
+                    metric_name,
+                    test,
+                    sample_labels,
+                    actual,
+                    golden,
+                    is_close,
+                    comparison_precision,
+                    passing,
+                )
                 if not passing:
-                    logger.info(
-                        "Actual values: %s", ", ".join([str(v) for v in (*actual_value_list,)])
-                    )
-                    logger.info(
-                        "Golden values: %s", ", ".join([str(v) for v in (*golden_value_list,)])
-                    )
+                    logger.info("Actual values: %s", actual_value_list)
+                    logger.info("Golden values: %s", golden_value_list)
                     raise test.error_message(metric_name)
 
                 result = f"{test.type_of_test_result.name} test for metric {metric_name}: PASSED"
 
@@ -436,3 +436,173 @@ def test_failure_message_lists_all_failed_metrics(self):
                 {"loss": [DeterministicTest()], "num-zeros": [DeterministicTest()]},
             )
         assert "num-zeros" in str(exc_info.value)
+
+
+class TestGoldenErrorDiagnostics:
+    def test_reports_absolute_and_relative_extrema_at_their_own_steps(self, caplog):
+        caplog.set_level("INFO", logger=common.__name__)
+        golden = make_metric({10: 4.0, 30: -0.01, 60: 0.0}, value_precision=ValuePrecision.FULL)
+        # The observed samples are deliberately stored in a different order.
+        actual = make_metric({60: 0.0, 30: -0.02, 10: 5.0})
+
+        with pytest.raises(AssertionError, match="loss"):
+            run({"loss": golden}, {"loss": actual}, {"loss": [DeterministicTest()]})
+
+        assert "2/3 samples outside tolerance" in caplog.text
+        assert "max_absolute_error at 10: golden=4, actual=5, absolute_error=1" in caplog.text
+        assert "relative_error=0.25 (25%)" in caplog.text
+        assert "max_relative_error at 30:" in caplog.text
+        assert "absolute_error=0.01, relative_error=1 (100%)" in caplog.text
+        assert "allowed_absolute_error=0" in caplog.text
+        assert "first_outside_tolerance" not in caplog.text
+
+    def test_reports_small_difference_that_passes_tolerance(self, caplog):
+        caplog.set_level("INFO", logger=common.__name__)
+        run(
+            {"loss": make_metric({5: 1.0})},
+            {"loss": make_metric({5: 1.04})},
+            {"loss": [ApproximateTest(rtol=0.05)]},
+        )
+
+        assert "[APPROXIMATE]: PASSED; 0/1 samples outside tolerance" in caplog.text
+        assert "absolute_error=0.04, relative_error=0.04 (4%)" in caplog.text
+        assert "allowed_absolute_error=0.05" in caplog.text
+
+    @pytest.mark.parametrize("atol,passes", [(1.0, True), (0.25, False)])
+    def test_zero_golden_uses_absolute_tolerance(self, atol, passes, caplog):
+        caplog.set_level("INFO", logger=common.__name__)
+        args = (
+            {"loss": make_metric({5: 0.0})},
+            {"loss": make_metric({5: 0.5})},
+            {"loss": [ApproximateTest(atol=atol, rtol=0.05)]},
+        )
+        if passes:
+            run(*args)
+        else:
+            with pytest.raises(AssertionError, match="loss"):
+                run(*args)
+
+        assert "absolute_error=0.5, relative_error=n/a (zero golden)" in caplog.text
+        assert "max_relative_error" not in caplog.text
+
+    def test_near_zero_golden_reports_large_relative_error_within_atol(self, caplog):
+        caplog.set_level("INFO", logger=common.__name__)
+        run(
+            {"loss": make_metric({5: 0.00001})},
+            {"loss": make_metric({5: 0.00002})},
+            {"loss": [ApproximateTest(atol=0.001, rtol=0)]},
+        )
+
+        assert "[APPROXIMATE]: PASSED" in caplog.text
+        assert "absolute_error=1e-05, relative_error=1 (100%)" in caplog.text
+        assert "allowed_absolute_error=0.001" in caplog.text
+
+    @pytest.mark.parametrize("actual_value", ["nan", float("nan"), float("inf")])
+    def test_nonfinite_values_have_undefined_errors(self, actual_value, caplog):
+        caplog.set_level("INFO", logger=common.__name__)
+        with pytest.raises(AssertionError, match="loss"):
+            run(
+                {"loss": make_metric({5: 1.0})},
+                {"loss": make_metric({5: actual_value})},
+                {"loss": [DeterministicTest()]},
+            )
+
+        assert "first_outside_tolerance at 5:" in caplog.text
+        assert "absolute_error=n/a (non-finite or missing)" in caplog.text
+        assert "max_absolute_error" not in caplog.text
+
+    def test_missing_sample_is_identified_even_with_finite_extrema(self, caplog):
+        caplog.set_level("INFO", logger=common.__name__)
+        with pytest.raises(AssertionError, match="loss"):
+            run(
+                {"loss": make_metric({5: 1.0, 10: 1.0})},
+                {"loss": make_metric({10: 1.25})},
+                {"loss": [DeterministicTest()]},
+            )
+
+        assert "max_absolute_error, max_relative_error at 10:" in caplog.text
+        assert "first_outside_tolerance at 5:" in caplog.text
+        assert "absolute_error=n/a (non-finite or missing)" in caplog.text
+
+    def test_single_sample_extrema_share_one_precision_appropriate_row(self, caplog):
+        caplog.set_level("INFO", logger=common.__name__)
+        with pytest.raises(AssertionError):
+            run(
+                {"loss": make_metric({5: 10.83456})},
+                {"loss": make_metric({5: 10.83457})},
+                {"loss": [ApproximateTest(atol=0, rtol=0)]},
+            )
+        assert caplog.text.count(" at 5: golden=") == 1
+        assert "max_absolute_error, max_relative_error at 5:" in caplog.text
+        assert "golden=10.83456, actual=10.83457," in caplog.text
+        assert "Actual values: [10.83457]" in caplog.text
+        assert "Golden values: [10.83456]" in caplog.text
+
+    def test_legacy_golden_placeholder_retains_undefined_diagnostics(self, caplog):
+        caplog.set_level("INFO", logger=common.__name__)
+        with pytest.raises(AssertionError):
+            run(
+                {"loss": make_metric({5: "nan", 10: 1.0})},
+                {"loss": make_metric({5: 0.9, 10: 1.0})},
+                {"loss": [DeterministicTest()]},
+            )
+        assert "first_outside_tolerance at 5: golden=inf" in caplog.text
+        assert "absolute_error=n/a (non-finite or missing)" in caplog.text
+
+    def test_full_precision_error_is_not_rounded_away(self, caplog):
+        caplog.set_level("INFO", logger=common.__name__)
+        with pytest.raises(AssertionError, match="loss"):
+            run(
+                {"loss": make_metric({5: 0.5}, value_precision=ValuePrecision.FULL)},
+                {"loss": make_metric({5: 0.5 + 2**-24})},
+                {"loss": [DeterministicTest()]},
+            )
+
+        assert "precision=full" in caplog.text
+        assert "absolute_error=5.96046448e-08" in caplog.text
+
+    def test_reports_both_exact_failure_and_approximate_success(self, caplog):
+        caplog.set_level("INFO", logger=common.__name__)
+        with pytest.raises(AssertionError, match="loss"):
+            run(
+                {"loss": make_metric({5: 1.0}, value_precision=ValuePrecision.FULL)},
+                {"loss": make_metric({5: 1.01})},
+                {"loss": [DeterministicTest(), ApproximateTest(rtol=0.05)]},
+            )
+
+        assert "[DETERMINISTIC]: FAILED" in caplog.text
+        assert "[APPROXIMATE]: PASSED" in caplog.text
+
+    def test_approximate_failure_budget_is_visible(self, caplog):
+        caplog.set_level("INFO", logger=common.__name__)
+        values = {step: 1.0 for step in range(1, 101)}
+        run(
+            {"loss": make_metric(values)},
+            {"loss": make_metric({**values, 100: 999.0})},
+            {"loss": [ApproximateTest(rtol=0.05)]},
+        )
+
+        assert "[APPROXIMATE]: PASSED; 1/100 samples outside tolerance" in caplog.text
+        assert "max_absolute_error, max_relative_error at 100:" in caplog.text
+
+    def test_timing_error_is_labelled_as_a_median(self, caplog):
+        caplog.set_level("INFO", logger=common.__name__)
+        with pytest.raises(AssertionError, match="iteration-time"):
+            run(
+                {"iteration-time": make_metric({5: 0.25, 10: 0.25, 15: 0.25})},
+                {"iteration-time": make_metric({5: 0.5, 10: 0.5, 15: 0.5})},
+                {"iteration-time": [ApproximateTest(rtol=0.05)]},
+            )
+
+        assert (
+            "max_absolute_error, max_relative_error at median over steps 5, 10, 15:" in caplog.text
+        )
+        assert "absolute_error=0.25, relative_error=1 (100%)" in caplog.text
+        assert "precision=full" in caplog.text
+
+    def test_matching_values_do_not_emit_error_diagnostics(self, caplog):
+        caplog.set_level("INFO", logger=common.__name__)
+        metric = make_metric({1: 0.0, 5: 1.0})
+        run({"loss": metric}, {"loss": metric}, {"loss": [DeterministicTest()]})
+
+        assert "Golden comparison" not in caplog.text