Edition variants & classification priority

Card-design identity (Luffy from OP01) is one thing; the specific edition of that card (regular print, alt-art, parallel foil, manga-style, pre-release stamped) is another. The edition is what decides the market value, the scarcity, and often the meaning of the listing — so Cambridge TCG models it as a first-class attribute on every row in the cards substrate.

Where this lives in code. The denormalized winner columns are cards.edition_variant and cards.promo_origin (+ their *_source companions) in the wholesale RDS. The witness log is card_classification_log. The pure decision logic is packages/data-ingest/src/classifier.ts. The per-app writer is apps/wholesale/src/lib/cards/classify.ts. The drift detector is pnpm audit:classifier-disagreement.

The four sources, ordered

Four kinds of actor can claim an edition variant or a promo origin for a card. They are ordered by trust:

The priority rule

When a new claim arrives, the writer compares its priority to the current winner's:

• Higher or equal priority → claim becomes the new winner; the previous winner is still recorded in the log (so the history is complete).
• Lower priority → claim is logged with shadowed: true. The cards row is not updated. The claim is kept, not discarded — because a heuristic that disagrees with a publisher feed is signal that the heuristic is broken, and the audit pnpm audit:classifier-disagreement surfaces those rows for review.

Equal-priority claims promote (most-recent same-tier overrides). This lets a publisher re-publish a correction, or an operator update their own override, without going through an explicit revoke-then-replace dance.

Operator override and revoke

When an operator classifies a card via the admin override page, their claim is recorded with source: 'operator' and becomes the winner (unless a publisher claim already exists). The prior heuristic claim is now shadowed in the log — kept, not deleted.

If the operator later decides their override was wrong, they can revoke it. The revoke marks the operator's claim as superseded_at = now() and re-promotes the next-highest claim — usually the heuristic that was previously shadowed. If no other claim exists, the column falls back to its default.

The two attributes, strictly separate

Edition variant and promo origin describe different facets of a card and are stored in separate columns. A card can be both alt-art and a pre-release promo — the two columns disagreeing doesn't mean either is wrong.

edition_variant — visual / structural treatment

• regular — default print.
• parallel — alternate-foil reprint of the same art.
• alt-art — entirely different artwork from the regular print.
• manga-style — comic / manga-frame border treatment.
• box-topper — oversized or sleeve-card included with a product.
• serial-numbered — explicitly numbered (e.g. 1/500).

promo_origin — distribution channel

• pre-release — handed out at pre-release events, usually stamped.
• event-prize — non-tournament event prize (launch parties, conventions).
• tournament-prize — competitive tournament prizes.
• preconstructed-deck — only available in a starter / structure deck.
• magazine-insert — promotional insert from a magazine or comic.
• promotional-pack — promo pack distributed by retailers / publishers.
• special-product — limited collector products, anniversary boxes, etc.

Why we keep shadowed claims

A heuristic that disagrees with a publisher's official designation is the most useful signal we have for improving the heuristic. Throwing the shadowed claim away would mean the next iteration of the heuristic starts blind. Keeping it means the audit can show: “cardrush-ingest tagged N cards as alt-art that the publisher says are regular” — and we know exactly which subdomain or URL pattern needs revisiting.

This is the same Witnesses' Book discipline used in card_price_change_log: delta-only, append-only, never-deleted. The cards columns are caches of the log's most recent winning claim per attribute.

What's not yet wired

• The publisher feed (priority 3) is not yet ingested for any game. Until it lands, the heuristic and operator override are the only two non-default sources.
• The CardRush subdomain → variant heuristic is partially wired today (kingdom-079 enumerated 12 subdomains). The full mapping ships in a later kingdom.
• Backfilling existing rows: today's cards default to regular /NULL. The operator can classify high-value cards by hand via the admin override page. Bulk re-classification awaits the heuristic.