Illustration consensus: md5 identity-group pooling and sibling propagation, built in from the first line

[WilfordGrimley]

CardIllustrationVote (issue #524) has been WRITTEN since it landed and read by nothing but the admin and the human write path. printing_consensus.py / artist_consensus.py / tag_consensus.py each reconcile their own vote model; there was no illustration equivalent, so PR #565's projected ~10,277 machine rows would have been recorded rather than reasoned over — and two ratified rulings (the art hash resolves ARTWORK; illustration identity rules premium-vs-base conflicts) depend on them.

1. cardpicker/illustration_consensus.py

Modelled on its two siblings, built on the shared vote_consensus core. No weighting, quorum, or human-backed gate is re-derived here.

is_unknown is an ordinary outcome key, the UNKNOWN sentinel — exactly as artist_consensus treats CardArtistVote.is_unknown and printing_consensus treats is_no_match. The XOR constraint makes the outcome space {uuid} ∪ {UNKNOWN}, and the abstention on this model is the absence of a row (the calculator's skip paths write a CardScanLog and no vote; a human who doesn't answer leaves nothing). A present is_unknown=True row is a positive, falsifiable claim — "someone looked and there is no Scryfall artwork behind this" — so it must be able both to resolve on its own and to contest a uuid. Treating it as an abstention would make an UNKNOWN-vs-uuid disagreement read as an uncontested uuid, and would leave a card everyone agrees is unidentifiable sitting UNRESOLVED forever, indistinguishable from one nobody has looked at.

2. md5 pooling built in from the start

Every read path is group-scoped. resolve_illustration tallies card's whole md5 identity group, pooled per agent by vote_consensus.pool_group_votes, keyed on agent_dedupe_key — the versionless calculator family, not the raw anonymous_id. That is live, not hypothetical, for this calculator specifically: #565 bumped it stage-d-illustration-v1 → -v2, and a version bump re-votes incrementally, so an md5 group straddling the migration holds rows under both strings at once. A raw-id key would read that as two independent agents and let one calculator buy a whole quorum on a routine redeploy.

The group primitives (md5_group_card_ids, md5_group_cards, _require_full_md5_group, agent_dedupe_key) are imported from printing_consensus, not reimplemented — one definition of a group, one completeness guard, one agent-identity rule.

Doing this now rather than retrofitting is the point of the change. The printing side acquired pooling late and the defect that mattered lived in the seam between the un-pooled original and the retrofit (its own docstrings record both halves: human votes initially left unkeyed, and _require_full_md5_group's "a subset yields a DIFFERENT tally, not a weaker one"). A resolver that is group-scoped from its first line has no such seam — no un-pooled call path left behind, no caller that predates the contract.

md5 is strictly stronger than the perceptual art hash here. Byte-identical files are necessarily the same artwork: no threshold, no tolerance, no distance metric, because identical bytes decode to identical pixels. A phash match is a different claim — two cards can share one and be genuinely different artworks at any radius. Since pooling deliberately suppresses evidence and propagation pushes one member's answer onto another, both are sound only on byte identity. Nothing in the module reads content_phash, structurally: membership has exactly one source.

3. Propagation — a consequence of group-scoped resolution, not a separate step

The calculator needs BOTH evidence AND a candidate-name match. Evidence transfers across an md5 group (evidence_transfer); the decorated NAME does not — so a member whose name fails candidate resolution abstains with no-candidate-match (367 of 2,350 considered cards, ~15.6% in #565's 30,000-card replay) even though a byte-identical sibling resolved cleanly.

Closed by the tally being defined over the group: the abstainer's tally is its sibling's tally, and resolve_and_persist_illustration writes the outcome to every member. It ends up with a resolved inferred_illustration_id with no code path aware it abstained.

The rejected alternative — an explicit step writing a copied CardIllustrationVote row onto the abstainer — is worse on three counts, in order of weight:

1. It would buy nothing. The row carries the calculator's own fixed anonymous_id, so it pools under the same dedupe_key and collapses to the same event: exactly zero added weight. The only thing it could change is per-card display, which group-scoped persistence already provides. Tested, not merely argued (TestPropagatedVoteRowsWouldBeWeightNeutral).
2. It manufactures evidence. A vote row records that an agent made a claim. No agent made this one. The pipeline's posture throughout is withhold-never-manufacture.
3. It collides by construction. CardIllustrationVote's unique constraint on (card, anonymous_id) is unconditional (stage-d-illustration-v1 at N>1 casts N full-weight votes for mutually exclusive printings; the /N confidence spread never reaches the tally #525). A propagated row occupies the exact slot the calculator wants when that member later becomes resolvable, and _purge_and_write_illustration_votes compares the stored value — it could not tell a propagated row from the calculator's own stale answer.

Honest limit, stated as a test (test_machine_only_evidence_does_not_propagate): nothing propagates until the group actually RESOLVES, and the human-backed gate means a machine-only group never does. The ~15.6% are cards that become resolvable once a human weighs in on any member, not cards resolved from machine votes alone.

Persistence, thresholds, reference data

Card.inferred_illustration_id (plain UUIDField, not an FK — no CanonicalIllustration table, mirroring the vote model and CanonicalPrintingMetadata.illustration_id) plus Card.illustration_vote_status (IllustrationVoteStatus, the four members ArtistVoteStatus has), migration 0096. Written for every group member, in pk order so concurrent votes on two members queue rather than deadlock.

ILLUSTRATION_MIN_VOTES / ILLUSTRATION_MIN_SHARE default to PRINTING_TAG_MIN_VOTES / _MIN_SHARE, so this ships changing nothing and the illustration bar can later move without moving the printing bar. Whether it should differ is genuinely open — an illustration claim is strictly coarser (1:N, ~2.2 printings per illustration) so easier to get right, but does less work once resolved — and with 3 votes in production there is no data to settle it, so the defaults settle it by changing nothing. No ILLUSTRATION_MACHINE_WEIGHT: a vote's weight is a property of who cast it and by what method, never of what is being voted on (same argument resolve_vote_weight makes against confidence-scaled weight); per-vote-type weights would also count one agent's CardIllustrationVote and its derived CardPrintingTag differently for one judgement.

Reference data (owner ruling 2026-07-29). This module reads neither CanonicalCard nor CanonicalPrintingMetadata — it tallies uuids off vote rows and stores the winner verbatim, asserted directly by TestReferenceDataIndependence (consensus resolves with zero canonical rows in existence, and for a uuid no metadata row references). What a stale snapshot does, precisely: upstream it changes which uuids exist to be voted for, so the pipeline under-resolves and never mis-resolves from that cause; downstream it changes what a resolved uuid maps to, a consumer-side narrowing done by a live join each consumer performs itself. What it cannot do is change a tally, flip a winner, or move a propagation. If reference data is later found wrong, the votes stand and re-running reproduces the same outcome — the correction belongs at the calculator, which is where it was consulted.

Tests — 50 new, every one proven able to fail

Production holds 3 illustration votes, so this cannot be validated by observation. 24 mutations were applied to the implementation and each of the 50 tests was verified RED under at least one; the full mutation table is in the thread below. Highlights:

Mutation	Tests turned red
is_unknown rows dropped (abstention reading)	5
pool_group_votes bypassed	8
agent_dedupe_key → raw anonymous_id	2 (the v1/v2 pair)
only machine votes keyed for pooling	6
tally card-scoped instead of group-scoped	11
persist writes only the caller's card	4
grouping switched from md5 to content_phash	3
is_human_backed=True for every vote	3
every card in one giant group	6
consensus gated on CanonicalPrintingMetadata	15
write path no longer recomputes	2

The phash tests carry a positive control (test_the_same_pair_with_a_matching_md5_does_propagate) that changes only the md5 — without it both negatives would stay green against an implementation that propagates to nothing at all. test_lowering_the_illustration_quorum_does_not_lower_the_printing_one is stated behaviourally (one human vote resolves the illustration, the same voter's printing vote does not resolve the printing) rather than as a comparison of two settings values, which could not fail.

Harness fix — not incidental

test_shared_cache.py::TestSharedCacheTableMigration carries @pytest.mark.django_db(transaction=True), so its migration round-trip really commits — and its finally restored only as far as 0092, leaving every later migration unapplied for the remainder of the pytest session, in a database later tests go on using.

Latent and free until now purely by alphabetical luck: 0093/0094 are data-only RunPython, and 0095 (face_illustrations) is read only by modules sorting before test_shared_cache.py. A migration adding a Card column is the first thing to step on it — test_sources.py and test_stage_e_dispatch.py sort later and use transactional_db, so they write real Card rows through a connection no rollback can save, and failed with column "inferred_illustration_id" ... does not exist: a message pointing squarely at this branch for a defect entirely in that finally. Now restores to graph.leaf_nodes("cardpicker") — derived, so it stays correct for every future migration without anyone remembering this file exists.

Verification

• Full cardpicker/tests/ suite: 3,090 passed, 9 skipped, 0 failed, against a 3,040-passed baseline on the same commit of master (85d88bf).
• black / isort / ruff / mypy clean; docs_lint.py clean (no new *_ANONYMOUS_ID, so no roster entry is required — docs/theory.md §4 item 3 and §10a's neighbourhood-lookup list are updated instead, the latter from four live instances to five).
• Rebased onto master after Per-face illustration ids; delete the border-colour "multi-faced" gate; stage-d-illustration-v2 #565 merged; migration renumbered 0095 → 0096 behind 0095_canonicalprintingmetadata_face_illustrations, makemigrations --check reports no pending changes.

Not in this PR

consensus_recompute is not wired to the illustration domain — the human write path (cast_illustration_vote) recomputes inline, which is the path that actually produces resolutions, but there is no batch recompute over the ~10,277 machine rows yet. Deliberate: a machine-only group cannot resolve, so a batch pass over them today would write nothing, and the wiring touches a file under concurrent edit. Flagged rather than silently omitted.

🤖 Generated with Claude Code

https://claude.ai/code/session_013NhYmT1PxCcyemA16dFDxN

[WilfordGrimley]

Mutation proofs — all 24, and the per-test coverage map

Method: apply one mutation to the implementation (never to the tests), run pytest cardpicker/tests/test_illustration_consensus.py -p no:randomly, record the reds, git checkout -- to restore, confirm green again. Baseline is 50 passed every time.

#	Mutation	Result	Tests turned RED
M1	build_group_illustration_vote_tuples skips is_unknown rows (the abstention reading)	5 failed / 45 passed	agreeing_unknown_votes_resolve_to_unknown, unknown_can_outvote_a_named_illustration, resolved_unknown_stores_no_illustration_id, a_contradiction_between_named_and_unknown_is_also_withheld, an_unknown_answer_through_the_write_path_persists_unknown
M2	pool_group_votes never called (return vote_tuples)	8 / 42	one_agent_agreeing_across_two_members_counts_once, pooling_keeps_the_agents_highest_weight, a_self_contradicting_agent_contributes_to_neither_side, withholding_is_order_independent, a_contradiction_between_named_and_unknown_is_also_withheld, a_version_bump_does_not_create_a_second_agent, a_corrective_re_vote_across_a_version_bump_is_withheld, a_copied_sibling_row_changes_no_tally
M3	dedupe_key = vote.anonymous_id instead of agent_dedupe_key(...)	2 / 48	a_version_bump_does_not_create_a_second_agent, a_corrective_re_vote_across_a_version_bump_is_withheld
M4	only machine votes keyed for pooling (humans left unkeyed)	6 / 44	one_agent_agreeing_across_two_members_counts_once, pooling_keeps_the_agents_highest_weight, a_self_contradicting_agent_contributes_to_neither_side, withholding_is_order_independent, a_contradiction_between_named_and_unknown_is_also_withheld, human_uuids_key_on_themselves
M5	group_illustration_votes always card-scoped (card.illustration_votes.all())	11 / 39	distinct_agents_across_two_members_still_sum, pooling_keeps_the_agents_highest_weight, a_self_contradicting_agent_contributes_to_neither_side, a_consistent_agent_in_the_same_shape_does_resolve, withholding_is_order_independent, a_contradiction_between_named_and_unknown_is_also_withheld, a_corrective_re_vote_across_a_version_bump_is_withheld, human_uuids_key_on_themselves, the_voteless_sibling_resolves_from_its_own_entry_point_too, a_de_resolution_propagates_too, two_internally_consistent_members_disagreeing_reads_as_contested
M6	persist writes only the caller's card, not the group	4 / 46	a_voteless_sibling_inherits_the_groups_resolution, a_de_resolution_propagates_too, the_same_pair_with_a_matching_md5_does_propagate, two_internally_consistent_members_disagreeing_reads_as_contested
M7	md5_group_card_ids groups on content_phash when present	3 / 47	an_identical_phash_does_not_propagate, an_identical_phash_with_no_md5_does_not_propagate, test_module_never_reads_the_perceptual_hash
M8	is_human_backed=True for every vote	3 / 47	machine_votes_alone_never_resolve_however_many_agents, machine_votes_alone_never_resolve_across_an_md5_group, machine_pile_never_overrides_a_human_quorum
M9	threshold captured at import instead of read at call time	1 / 49	the_quorum_setting_is_read_at_call_time
M10	unresolved always UNRESOLVED, never CONTESTED	3 / 47	unknown_contests_a_named_illustration, a_de_resolution_propagates_too, two_internally_consistent_members_disagreeing_reads_as_contested
M11	_require_full_md5_group + the members identity check removed	3 / 47	a_partial_group_raises_rather_than_resolving_differently, a_duplicated_member_raises, persist_rejects_a_substituted_card_instance
M12	cast_illustration_vote no longer recomputes consensus	2 / 48	two_human_votes_through_the_write_path_resolve_and_persist, an_unknown_answer_through_the_write_path_persists_unknown
M13	unresolved always CONTESTED (the inverse of M10)	3 / 47	the_absence_of_a_row_is_the_abstention, machine_only_evidence_does_not_propagate, a_single_vote_is_unresolved_not_contested
M14	machine votes dropped entirely	2 / 48	one_human_vote_promotes_agreeing_machine_weight, a_version_bump_does_not_create_a_second_agent
M15	singleton branch removed — a group of one takes the group query and is pooled	3 / 47	a_checksum_less_card_is_its_own_group_and_is_not_pooled, a_unique_checksum_card_is_its_own_group, the_singleton_read_honours_a_prefetch
M16	resolve_vote_weight bypassed — every vote at machine weight	20 / 30	(broad) incl. two_agents_on_a_singleton_resolve_exactly_as_before, both TestReferenceDataIndependence tests, both write-path tests
M17	every card in one giant group	6 / 44	a_unique_checksum_card_is_its_own_group, the_singleton_read_honours_a_prefetch, a_non_sibling_does_not_inherit, an_identical_phash_does_not_propagate, an_identical_phash_with_no_md5_does_not_propagate, an_empty_string_md5_is_not_an_identity
M18	ILLUSTRATION_MIN_VOTES default diverges from the printing one (3.0)	17 / 33	(broad) incl. defaults_match_the_printing_thresholds
M19	printing_consensus.resolve_printing wired to illustration_min_votes()	1 / 49	lowering_the_illustration_quorum_does_not_lower_the_printing_one
M20	display tally becomes group-scoped and drops is_unknown rows	2 / 48	the_tally_is_card_scoped_not_group_scoped, the_tally_counts_unknown_as_its_own_outcome
M21	contested query loses its is_unknown sentinel	1 / 49	contested_card_ids_flags_a_named_illustration_against_unknown
M22	contested query's outcome_field → card_id (distinct outcomes always 1)	1 / 49	contested_card_ids_flags_two_illustrations
M23	resolution gated on a CanonicalPrintingMetadata row carrying the winning uuid	15 / 35	(broad) incl. both TestReferenceDataIndependence tests

Coverage: 50 of 50 tests fail under at least one mutation. Two were strengthened after the first batch showed them passing for the wrong reason, and are re-proven above:

• machine_only_evidence_does_not_propagate originally used 2 machine agents (1.0 weight) and stayed green under M8 — it was falling short of quorum, not being stopped by the human-backed gate. Now uses 6 agents (3.0 weight, 100% share) so the gate is the only thing in the way.
• lowering_the_illustration_quorum_does_not_lower_the_printing_one originally compared two settings values inside an override_settings block, which could not fail. Restated behaviourally against resolve_printing; M19 is the plausible wiring mistake it now catches.

[WilfordGrimley]

Rebased onto master; migration renumbered 0096 → 0098

Migration

0096_card_illustration_consensus_fields → 0098_card_illustration_consensus_fields, dependency repointed from 0095 to 0097_freeze_deductive_backfill_zero_weight_cohort.

Two migrations named 0096 are already on master (#568's 0096_card_scan_log_anon_skip_idx and #570's freeze migration). #576 linearises them as 0096 → 0097_freeze, making 0098 the next free number.

Verified: graph.leaf_nodes("cardpicker") returns exactly [('cardpicker', '0098_card_illustration_consensus_fields')], makemigrations --check --dry-run reports No changes detected, and showmigrations --plan is a single chain 0095 → 0096 → 0097 → 0098.

⚠️ Merge-order requirement

This PR must not merge before #576. Its dependency names 0097_freeze_…, which only exists once #576 lands. Until then CI here will fail at the migrate step — that is expected, not a defect in this branch. (Happy to retarget this PR's base onto fix/migration-graph-single-leaf instead if you'd prefer green CI now; left on master because it was not asked for.)

Semantic conflict fixed

The rebase brought in #570, which re-scoped the deductive-backfill zero-weight rule from the calculator FAMILY to one RUN and so changed the signature to resolve_vote_weight(source, anonymous_id, run_id). illustration_consensus.py is a new file, so git had no conflict to report — but its call still passed two arguments:

TypeError: resolve_vote_weight() missing 1 required positional argument: 'run_id'

50 tests failed on the raw rebase (38 in test_illustration_consensus.py, 12 in test_illustration_vote.py), all from this single cause.

Fixed by passing vote.run_id straight off the row — identical to the sibling call in printing_consensus.py, which #570 updated the same way. CardIllustrationVote inherits run_id from AbstractWeightedVote, and this file's own docstring already states the ruling has exactly one enforcement site and should be honoured "without this file being touched" — withholding the discriminator would have quietly broken that.

Verification

• cardpicker/tests/: 3157 passed, 11 skipped, 0 failed (with Linearise the cardpicker migration graph: two 0096 leaf nodes block every deploy #576 layered, since the suite cannot build a test database on unmodified master).
• ruff, isort, black, mypy, prettier, docs-lint all clean.