test(pdf): #204 extract Golden Master face->back matching to pure method + 8 tests

[jsboige]

Summary

Extract the Golden Master (commit 0087f0ec) face→back name-matching contract from AssembleCurrentCardImages (ImageFileGenerator.cs) into a pure, deterministic ResolveCardBack method and pin it with 8 unit tests.

Lane #204 (test/contract extractions, cont. po-2024) — same spirit/output-neutral pattern as #512 (page-grid geometry) and #521 (alternate-face-and-back).

The contract

When a card set ships several distinct back arts, the harvest must pair EACH face with the correct back by name, not randomly. ResolveCardBack encodes:

• No backs → face ships alone (null back).
• Single back → shared by every face.
• Multiple backs → the back whose (lower-cased) key is contained in the (lower-cased) face key wins, longest matching key first (tie-break via OrderByDescending(Length)).
• No name matches → falls back to the first available back.

Why it's a fragile contract

A regression here silently pairs the WRONG back art behind a face while leaving page count, geometry, and card ordering all correct — the defect surfaces only by inspecting which back sits behind which printed card. Previously inlined inside AssembleCurrentCardImages with zero unit coverage.

Output-neutral extraction

The call site assembles the exact same CardImages Front/Back pair as before. The Logger.LogWarning diagnostics and targetList.Add stay at the call site; ResolveCardBack surfaces the branch taken via out bool hadNoAvailableBack / out bool usedFallback so the caller emits its existing warnings without duplicating the branch logic. Verified by build + full suite.

Subtlety pinned by the tests

Back dictionary keys carry a leading hyphen: GenerateBacks (lines 124-130) strips to the suffix after the last hyphen, keeping the hyphen — e.g. harvested "scenarii-01-histoire" → key "-histoire". So the Contains match looks for "-histoire", not the bare token "histoire". This was not obvious from a read of AssembleCurrentCardImages alone; the tests now lock it in (e.g. a face "Face_histoire_titre" with bare histoire would not match a "-histoire" key).

Conceptual complement of #521

• test(pdf): #204 extract #119 alternate-face-and-back ordering to pure method + 9 tests #521 (PdfAlternateFaceAndBackContractTests, OrderImagesForAlternateFaceAndBack) — ORDERS fronts/backs back-then-front for recto-verso alignment.
• This PR (FaceToBackMatchingContractTests, ResolveCardBack) — CHOOSES which back each face gets.

Together they pin the full back contract: which back, then where it prints.

Tests (8)

Area	Test
No-back / single-back	NoBacks_ReturnsNull_AndFlagsNoAvailableBack, SingleBack_IsSharedByEveryFace
Name-matching	MultipleBacks_PicksBackWhoseKeyIsContainedInFaceKey, NameMatching_IsCaseInsensitive, MultipleBacks_PicksUnrelatedBackForUnrelatedFace
Longest-key tie-break	LongestMatchingKeyWins_WhenMultipleKeysMatch, ShorterOnlyMatch_StillPicked_WhenNoLongerMatch
Fallback	NoNameMatch_FallsBackToFirstBack_AndFlagsFallback

CI

• 359 passed / 0 failed / 5 skipped (baseline 351 + 8 new).
• Files: ImageFileGenerator.cs (extraction) + FaceToBackMatchingContractTests.cs (new tests).
• No CSV touched, no RowsetNb/rscount change, no .github/workflows or rules edit.

🤖 Worker po-2024 — gate-safe, ready for ai-01 review/merge.

[clusterManager-Myia]

[NanoClaw]

Good extraction: inlines the face->back name-matching logic from AssembleCurrentCardImages into a pure, deterministic ResolveCardBack method (output-neutral refactoring). 8 xUnit tests using FluentAssertions cover all branches: no-backs, single-back, substring matching, case-insensitivity, unrelated face, longest-key-first tie-break, shorter-only match, and fallback-to-first. The test names are descriptive and the helper Backs() factory keeps fixtures readable. The tie-break behavior (longest matching key wins) is the critical regression case — correctly tested. LGTM.