Per-item report plus batch-level notes: keep one source of truth, derive the other
Smell: a per-page report kept a generic reason code ('page_unreadable') while the real cause ('ocr_timed_out') sat in a separate notes tail; the batch-level notes were then rebuilt from both, so one timed-out page produced two batch notes. Fix: give the per-page report an issues: tuple[(field_name | None, Note), ...] where issues[0] is always the cause (why the page belongs to no record) and the rest are other problems found on that page. Make reason a read-only @property returning issues[0].code, so existing report.reason == X tests still read well but can never disagree with the issues. Batch notes are then derived: [note for r in reports for _, note in r.issues], and a test asserts exactly that equality. Keeping the field name with each issue lets a later manual 'assign this page to record X' step route those notes onto the right fields of X. When renaming log/message wording, grep tests for substring assertions on caplog text first (e.g. 'unassigned', 'OCR callback'), and keep those keywords.