[SKEEP-005]: Ground-truth validation for stateful metrics

[michalharakal]

Proposal document: docs/modules/skeep/pages/005-ground-truth-stateful-metrics.adoc — not yet written; writing it is this issue's Lane 0 task
Status: Draft (proposal to be filed)
Branch: feature/skeep-005-ground-truth-stateful-metrics

Trigger

Compiler, graph-export, or runtime integration — specifically the test-integration
pattern every future Metric inherits. skainet-test-groundtruth's OperationExecutor
(skainet-test/skainet-test-groundtruth/src/commonMain/kotlin/sk/ainet/test/groundtruth/OperationExecutor.kt)
maps a test case's operation name to one stateless TensorOps call and returns one
Tensor<FP32, Float>. A Metric (sk.ainet.lang.nn.metrics.Metric) is stateful —
update() across many batches, compute() returning a scalar Double, reset() — and
there is no MetricExecutor or equivalent anywhere in the harness. That shape mismatch
is why the Precision/Recall/F1Score feature (#1222) ships with unit tests only and
never earns the "✅ ground-truth validated" badge tensor ops get.

Summary

Add a parallel MetricExecutor and GroundTruthMetricCase (predictions tensor, targets
tensor, expected scalar, metric parameters such as averaging mode) so metrics can be
cross-checked against sklearn / torchmetrics references the same way matmul is
cross-checked against PyTorch today, in the same CI job. Additive: OperationExecutor
and the existing GGUF op-fixture format are unchanged.

Improvising this inside whichever metric PR gets there first — instead of deciding its
shape once, durably — is exactly the drift SKEEP exists to prevent; hence a proposal
rather than a sub-issue of #1222.

Questions the proposal must answer (don't leave them to the implementer):

• Python-side fixture format: a new @ExecutableMetric decorator in skainet-ground-truth,
  or reuse of @Executable with a scalar-tensor convention?
• Does a metric case carry one batch or a sequence of batches (to exercise
  accumulation across update() calls)?
• Scalar tolerance semantics vs. tensor element-wise tolerance.
• Does this warrant its own GGUF metadata convention, or a lighter fixture format since
  metrics don't need the op-parameter machinery conv2d/pooling need?

Related DARC features

• [Feature]: Precision, Recall and F1Score metrics #1222 — Precision, Recall, F1Score (blocked for ground-truth coverage only; ships without it)
• Any future metric (AUC, MeanSquaredError, …) inherits whatever this decides
• Ground truth validation: Phase 2 roadmap (coverage, gradients, numcrux) #984 — Ground truth validation Phase 2 roadmap (this is a sibling concern to Ground truth: expand Python-side op coverage to match OperationExecutor #985–Ground truth: explore a single-source DSL generating both Kotlin and Python fixtures #988)

Sub-issues

To be filed once the proposal is Accepted. Suggested phases: (0) spike the fixture
format against Accuracy, which already ships; (1) MetricExecutor +
GroundTruthMetricCase; (2) wire Precision/Recall/F1Score.

Status upkeep

• Proposal registered in docs/modules/skeep/nav.adoc and the "Current Proposals" table
• Maintainer moved status to Accepted
• Implementation PR(s) linked here and flipped the proposal's Status: to Implemented