test(recognition): gate releases against supported Bastion screenshot revisions

[Teakowa]

Depends on: OWBastion/Bastion#161
Related: #7

Background

OCRKit already versions ROI layouts and regression-tests recognition behavior, but there is not yet one explicit release gate framed around the Bastion screenshot HUD revisions OCRKit promises to support. That leaves room for a parser/model/layout change to improve aggregate OCR metrics while silently breaking a released game screenshot or one critical field.

OWBastion/Bastion#161 establishes the producer-side versioned screenshot HUD contract. This issue adds the OCRKit consumer-side compatibility gate.

Goal

Define a supported Bastion screenshot-revision compatibility matrix and make OCRKit recognition/model releases fail when a supported released revision regresses on required critical fields or layout behavior.

The gate should distinguish layout compatibility, parser behavior, and OCR-model quality rather than collapsing everything into one aggregate score.

Compatibility matrix

Derive the initial supported-revision set from the current Bastion screenshot contract and OCRKit's existing layout configs/fixtures. At minimum model the relevant dimensions:

Bastion screenshot revision
× OCRKit layout/aspect variant
× critical field family

Critical fields should reflect actual current platform/OCR contracts, including where applicable:

• completion state;
• viewer/player name;
• map;
• difficulty;
• game version;
• duration;
• deaths/skips;
• run code;
• achievement/title evidence.

Do not duplicate Bastion's contract as a second source of truth. OCRKit should record which producer revisions it supports and map them to OCRKit-owned layout/parser/evaluation coverage.

Required behavior

The compatibility gate should exercise representative supported cases for:

• normal current settlement screenshots;
• supported 16:9 / 16:10 layouts as applicable;
• scaled/compressed inputs within supported quality bounds;
• cropped/missing critical regions;
• malformed or ambiguous strict-format fields such as run code;
• unsupported/unknown layout behavior.

Prefer a small high-value regression corpus over a large brittle snapshot suite. Private production screenshots must not be committed; use existing safe fixtures plus synthetic/sanitized additions as needed.

Failure classification

Evaluation/report output should make it possible to tell whether a release candidate failed because of:

• unsupported/wrong layout selection;
• ROI/preprocessing regression;
• parser/normalization regression;
• recognition/model accuracy regression;
• quality/rejection behavior regression.

Do not permit an improved aggregate character metric to hide a regression in a critical field.

Integration with model release

This gate should be reusable by the existing model evaluation/release path and by #8 candidate-to-stable promotion. Once implemented, a candidate that fails a supported released screenshot revision must not be promoted to stable.

Application-only OCRKit changes that affect recognition/layout/parsers should run the same relevant compatibility coverage.

Support/deprecation semantics

Preserve existing supported old layouts unless an explicit deprecation decision is made. If a Bastion screenshot revision becomes unsupported, record that deliberately with the reason/minimum compatibility boundary rather than silently dropping its fixtures.

Unsupported revisions should fail closed through the existing warning/rejection contract where possible rather than being parsed confidently as a different supported layout.

Acceptance criteria

• OCRKit has an explicit supported Bastion screenshot-revision compatibility matrix tied to, but not duplicating, the producer contract in OWBastion/Bastion#161.
• The matrix covers the critical fields and currently supported layout/aspect variants required by released gameplay screenshots.
• Regression coverage distinguishes layout/ROI, parser/normalization, model accuracy, and quality/rejection failures.
• A regression in a critical field fails the compatibility gate even if aggregate OCR/CER metrics improve.
• Current run-code behavior includes exact valid cases and malformed/cropped/ambiguous/low-confidence fail-closed cases.
• Unsupported screenshot revisions/layouts are reported/rejected explicitly rather than silently accepted as another layout.
• Private production evidence is not added to the public repository; new committed fixtures are safe synthetic/sanitized cases.
• The gate can be invoked from application recognition CI/evaluation and from the model candidate promotion workflow in feat(model): add candidate-to-stable model promotion workflow #8.
• Supported-layout deprecation requires an explicit recorded change rather than fixture deletion alone.
• Relevant unit, fixture, integration, and model-evaluation tests pass.

Non-goals

• Owning or editing the Bastion HUD contract.
• Adding every historical Bastion screenshot ever produced to permanent support.
• Replacing field-level evaluation with one aggregate OCR metric.
• Storing production player screenshots in the public repository.
• Changing platform challenge/mastery acceptance rules.

[Teakowa]

Implementation is in stacked Draft PR #12: #12

The reusable gate records the Bastion producer revision/layout matrix, per-critical-field results, failure classification, and baseline-only historical coverage. After #7 ROI correction, the current public run-code fixtures pass 8/8. The gate intentionally remains fail-closed because its current-release 16:10 fixture set is missing 1280x800-v1; the historical private corpus is pre-run-code 16:9 baseline only and is not treated as current compatibility evidence. This is the concrete remaining blocker before the gate can certify the full supported matrix. PR #12 is stacked on #11 and Bastion #161.