atelier/domains/ai-ml/model-evaluation.md

Model Evaluation — Derived Rules

Derives from domains/ai-ml/first-principles.md. Covers P4 (Evaluation is Defined Before Training) and the eval-as-a-gate discipline. Referenced by serving.md (promotion gate) and monitoring-drift.md (online eval). Scope per D-023: evaluation methodology, not metric math or model-family benchmarks.

Evaluation is a Gate, Not a Report (P4 Evaluation Defined Before Training)

• The eval spec — metrics, splits, thresholds, and pass/fail criteria — is declared in code before the model is trained. It is versioned with the data and the code; it is reviewable; it is the contract the model must satisfy to leave the experiment.
• Cherry-picking metrics after seeing results is a correctness violation: the eval is no longer measuring the model, it is rationalizing it. The a-priori spec is what makes the eval trustworthy.
• This is the ML angle on domains/testing/first-principles.md P1 (Tests as Specification): the eval declares the model's contract, the model does not declare its own success.

The Eval Input Contract (P8 Inference Inputs are Validated, cross domains/data/schema-design.md)

• The eval set has a schema: feature names, types, ranges, and categorical domains. That schema is the same schema the serving boundary enforces (serving.md, domains/security/input-validation.md).
• An eval set whose schema drifted from the serving schema is measuring a different model than the one in production. Schema parity is part of the versioned eval artifact.
• Cross domains/data/schema-design.md: the eval input contract is a schema-design problem, versioned and reviewed like any schema.

Holdout Integrity (P4, P2 Data is Versioned)

• The held-out eval set is never touched by training, feature selection, or threshold tuning. A "held out" set that influenced any training decision is not held out — it is a third training set, and the eval is measuring memorization.
• Splits are versioned with the dataset (data-versioning.md). Recreating splits ad-hoc per run breaks comparability across runs.
• Reusing a held-out set across many model iterations leaks it incrementally. Rotate or re-split on a cadence; record the rotation in lineage.

Offline vs Online Evaluation (P6 Serving is Observable)

• Offline eval runs before promotion: held-out data, pinned model, declared metrics, pass/fail gate. It answers "should this model ship?"
• Online eval runs after promotion, on live traffic: shadow scoring, A/B, canary metrics. It answers "is this model behaving in production?" It is the bridge to monitoring-drift.md.
• A model that passed offline and regressed online is not a contradiction — it is a signal that the offline distribution differs from the live one (a P7 drift signal). Both eval layers are required; neither substitutes for the other.

Bias and Fairness Checks (Engineering Angle, P4)

• Bias/fairness checks are part of the a-priori eval spec, not an afterthought. They are metrics with thresholds, declared before training, gated the same as any metric.
• This doc covers the engineering discipline: the checks are versioned, gated, and recorded in lineage. The choice of which fairness metrics and what thresholds are policy decisions, not engineering principles, and are out of scope here (D-023).

Eval-as-a-Gate in the Pipeline (P9 Pipelines Compose)

• The eval is a pipeline stage with a contract: input = model digest + eval dataset version; output = pass/fail + metric report. It composes with the training stage and the promotion stage.
• A promotion that bypasses the eval stage is a P4 violation, regardless of who approved it. The gate is in the pipeline, not in a human sign-off sheet.

train -> eval(gate) -> register(promote) -> serve
                 |
                 +-- fail -> abort, no promote

What Violates Evaluation Discipline

Violation	Principle
Metrics chosen after seeing the scores	P4 Evaluation Defined Before Training
Held-out set used in feature selection or threshold tuning	P4, P2
Eval schema differs from serving schema	P8 Inference Inputs are Validated
Promotion by human approval, bypassing the eval stage	P4, P9 Pipelines Compose
A "passing" model with no online eval in production	P6 Serving is Observable
Fairness checks added after a model shipped	P4 Evaluation Defined Before Training