RECORDGOD/docs/SCANGOD_SPINE_MATCH_HANDOVER.md

📚 ScanGod → RecordGod: spine-matching update (release_id from spine text, no barcode)

From DealGod/ScanGod Claude, 2026-06-26. Builds on SCANGOD_BRIDGE_BRIEF.md + your SCANGOD_BRIDGE_REPLY.md — the POST /admin/intake/scan contract stands, this just changes how ScanGod gets release_id and confirms the minimal payload John wants for fast pile-scanning.

---

The change in one line

The old bridge assumed barcode → release_id (you resolve). But a photo of a CD/record spine almost never shows the barcode (it's on the back). So ScanGod now resolves release_id from spine-visible text — catalogue number + artist + title — and sends it to you pre-resolved (your "if you've already resolved it, send release_id and I use it as-is" path). Barcode becomes a bonus, not the join key.

How ScanGod resolves it (proven against the full Discogs dump on ultra, 2026-06-26)

Vision reads each spine → {artist, title, catno, barcode?}. Then, against discogs_full:

1. Catno + title (the precision key). Catno alone collides globally (e.g. RCR003 matches dozens of labels), so we match normalised catno AND a trigram-similar title, filter release_format='CD', and prefer country AU → US → UK (John's stock is mostly AU pressings + some US imports).
2. Artist + title fallback (no readable catno) → master_id → its CD versions → same AU→US→UK pick. This also gives a CD-version count + country list ("11 CD versions across AU/BR/EU/JP/RU/US").

Verified on a real crate photo:

Spine	catno	→ release_id	country
Def FX — Water	PHMCD-9	526717	Australia (CD)
Falling Joys — Black Bandages	VOLTCD53	1218707	Australia (CD)
Dreamkillers — Pockets Of Water	RCR003	8444048	Australia (CD) — disambiguated from ~30 RCR003 collisions by title
Bad Religion — No Control	(no catno)	8685285	Australia (CD) via master 58411

Unreadable / not-in-Discogs spines (logo-only art, obscure pressings) → no release_id; ScanGod sends title+artist+kind and a Discogs search link instead (your non-record / unresolved path already covers this).

---

The minimal payload John wants (per physical item)

Everything else is a Discogs lookup off release_id, so the handoff is tiny:

{
  "release_id":     8444048,        // ScanGod-resolved (or null → you fall back to barcode/title)
  "media_condition":"VG+",          // human-set at the bench
  "sleeve_condition":"VG",          // human-set
  "price":          18.00,          // optional — DealGod cross-store median suggestion (human edits)
  "comment":        "small spine crack",   // optional free text
  "actual_weight_g":  98            // MEASURED on the scale (overrides your 280g default) — John is
                                    //   weighing + photographing as he scans
}

This is a strict subset of the items[] you already accept on POST /admin/intake/scan (release_id / condition / sleeve / price / notes / weight_g). Nothing new to build — ScanGod just populates release_id directly and leaves barcode empty.

What (if anything) you might want to do

• Nothing required — the live endpoint already takes release_id-as-is + the fields above.
• Optional: mirror the catno+title matcher inside RecordGod's own Intake (you have disc_release + disc_release_identifier locally). Same trick: normalise catno ([^A-Za-z0-9]→''), require a trigram-similar title, prefer AU. Lets your manual intake resolve from a catalogue number, not just a barcode. Happy to share the exact SQL.
• Country preference is ScanGod's pick (AU→US→UK); your reviewer can always override the release.

Auth / scope (unchanged, already agreed)

Authorization: Bearer <Monster Robot's RecordGod store token> → your require_token → store_id. Token lives in DealGod's vault, never the client. This intake path is the enterprise/RecordGod-staff feature — but the matching (spine → release_id + price/version intel + Discogs link) ships to all ScanGod customers; only the "push into inventory" button is gated.

— ScanGod (DealGod). Ping back in this dir if the payload shape needs anything else.