fix(recognition): verify current released settlement HUD compatibility

[Teakowa]

Background

Current production recognition can lag behind the actually released Bastion settlement HUD even when OCRKit main already contains newer layout/parser support. The recent run-code field is the concrete example: OCRKit now has versioned run-code ROIs and a dedicated parser, but current production screenshots still need to be verified against the released game and deployed OCR service.

Do not assume model age is the root cause. The failure may be caused by production image drift, layout/ROI mismatch, preprocessing, parsing, or recognition accuracy.

Goal

Verify the currently released Bastion settlement screenshot contract against both OCRKit main and the deployed OCRKit path, identify the actual failure layer, and make the smallest evidence-driven fix required for reliable recognition.

Required investigation

Using representative private current-release screenshots through trusted/local tooling, compare at minimum:

• OCRKit application/image revision where observable;
• model_version;
• layout_version;
• fields.run_code.status and confidence;
• OCR warnings/quality output;
• trusted debug raw OCR text for the run-code ROIs;
• current 16:9 and 16:10 layouts when both are relevant.

Classify any failure explicitly as one or more of:

1. production deployment/image drift;
2. layout selection or ROI coordinates;
3. preprocessing;
4. parser/normalization;
5. OCR recognition model accuracy.

Do not jump directly to retraining when a deterministic layout/parser fix is sufficient.

Implementation boundary

• OCRKit owns recognition, ROI/layout support, parsing, confidence, and warnings.
• Bastion owns the visible settlement HUD contract.
• The platform owns submission/business decisions and training-feedback provenance.
• If model retraining is actually required, route production-derived corrections through the existing platform annotation -> reviewed snapshot -> OCRKit importer path. Do not create an ad-hoc production training dataset in this issue.

Regression coverage

Add or update safe regression fixtures/cases representing the currently supported settlement layout without committing private player screenshots or production evidence.

Preserve fail-closed behavior for:

• malformed run codes;
• cropped/missing run-code evidence;
• ambiguous duplicate values;
• low-confidence recognition;
• unsupported layouts.

Existing critical fields such as map, difficulty, player identity, completion state, version, time, deaths/skips, and achievement evidence must not regress as a side effect of the fix.

Acceptance criteria

• The current released settlement HUD is tested against OCRKit main and the deployed production path with traceable version/layout/model evidence.
• The root cause of the current recognition gap is explicitly identified as deployment, layout/ROI, preprocessing, parser/normalization, model accuracy, or a documented combination.
• Valid current-release run-code screenshots resolve to the exact normalized NNNN-NNNN-NNNN value when the visible evidence is readable.
• Relevant current 16:9 / 16:10 layouts select the intended versioned ROI config.
• Malformed, cropped, ambiguous, or low-confidence run-code evidence remains rejected or unresolved rather than fabricated.
• Existing critical settlement fields have regression coverage and do not materially regress.
• Any production-derived examples remain private; public fixtures are synthetic/sanitized and suitable for regression use.
• If retraining is required, the issue records the measured evidence showing deterministic fixes are insufficient and points to the existing reviewed-snapshot training path.
• Relevant OCRKit tests/evaluation gates pass.

Non-goals

• Redesigning the model lifecycle.
• Building a new annotation pipeline.
• Automatically training or publishing a model.
• Changing platform approval/mastery/title rules.
• Adding a general-purpose OCR mode.

[Teakowa]

Implementation is in Draft PR #11: #11

The inspected failure was an ROI geometry mismatch, not parser/model logic: the released settlement run-code panel was outside the prior 16:9 and 16:10 run-code ROI bounds. The config/manifest and sanitized geometry regression are corrected; local run-code fixtures are 8/8 exact and the full Python/Rust tests pass. Production-path verification remains blocked by repository evidence: no safe released private screenshot/R2 object key or service token is available, and the current health endpoint is anonymous-only while recognition returns 401 without the service token. The PR makes no production claim.