The Song Graph

Robert Johnson still earns in 1986

The chain — Beastie Boys ← Led Zeppelin ← Robert Johnson — is real, and it's the perfect seed demo. Licensed to Ill (1986) lifted the drums of Led Zeppelin's "When the Levee Breaks" into "Rhymin' & Stealin'"; Led Zeppelin's "The Lemon Song" (1969) carries the "squeeze my lemon" verse from Robert Johnson's "Travelling Riverside Blues" (1937). Two edges, two different legal species, two very different payment histories:

Notice what the two edges disagree about. A sample reuses the actual recording, so it touches both copyrights — the master (label side) and the composition (publisher side). An interpolation re-performs the material, so it touches only the composition. Any Song Graph that wants to route royalties correctly has to carry this distinction on the edge itself — it is the difference between who gets paid.

The edges are the missing table

bushido already holds everything around the edge: rightsholder identity and the LOD portal (the authoritative, editable source of rights truth), effective-dated splits with provenance, streaming signals per work, the HOLY GRAIL identity-and-credits backbone, the reconciliation engine, waveform-comparison tooling from the graphite work, and payout rails. WhoSampled has none of that — it's a citation site that can't verify with the parties and can't move money. The open-source play is to publish the graph (nodes, edges, evidence) as open data, and keep the two things only bushido can do as the business: rightsholder verification and settlement.

That's also the moat logic: open data recruits the crowd that WhoSampled keeps behind a paywall; verification and payment make bushido the place where the data becomes worth something.

Nodes you already have; edges you don't

Nodes stay exactly what the catalogue already models: Work (composition, ISWC, writers, splits) and Recording (master, ISRC, artist, label). The Song Graph adds one first-class entity:

Every field is effective-dated and carries provenance — the same discipline the split system already enforces. And the same rule that governs CWR applies verbatim here: external feeds and community assertions propose; only verified parties apply. Nothing a scraper or a fan submits ever mutates the graph of record directly.

Three layers, one graph

Derivation edges are the first layer. The full Song Graph is three, stacked on the same nodes:

The credit layer is what makes "reverse-engineer the hit" a query instead of a vibe: hits stop being isolated points and become subgraphs — this writer room, that producer, this label→distributor path, these features and co-signs, this sample ancestry. Recurring substructure across the hit cohort is findable, and drawable. The commercial layer is what makes the graph honest: expected flow (splits × cleared edges × usage) is computable from the first two layers, and every place the observed money disagrees with it is a finding.

HOLY GRAIL holds the nodes together

The graph above needs one thing under it: a way to say that Spotify's track, YouTube's video, the CWR work, the MLC song code, and the MusicBrainz recording are the same song. That is exactly what HOLY GRAIL already is in the stack — entities with external_ids spanning ISRC, ISWC, MusicBrainz, YouTube, YouTube Music and the DSPs, plus work_data and rights shares. The Song Graph doesn't invent an identity fabric; it rides HOLY GRAIL's:

• Nodes resolve through HOLY GRAIL. Every Work/Recording/Person/Company node keys to a HOLY GRAIL entity where one exists; its external ids are the join keys that let derivation edges, credit edges, and platform usage all land on the same node. Join keys, not proof — ISRC/ISWC identify, they never prove ownership or payment.
• HOLY GRAIL corroborates, never confirms. The rule is already frozen in the reconciliation spec — "Holy Grail may corroborate work and rights metadata, never claim monetisation or payout" — and it maps one-to-one onto the edge lifecycle: a HOLY GRAIL response is corroboration-class evidence that can lift an edge to CORROBORATED, and can never be the basis of CONFIRMED. Same slot as every other algorithm in the permissions table.
• Presentation channels come from the audience providers. HOLY GRAIL entities carry no artwork and no popularity — so the lantern keeps reading its audience channels (popularity beads, followers, markets) from the Spotify/Deezer providers, while HOLY GRAIL supplies identity, credits, and rights corroboration underneath. Two providers, two jobs, one glyph.
• Mismatches become first-class. When HOLY GRAIL, CWR, and a DSP disagree about which work a recording embodies, that's not a bug to hide — it's a MISMATCHED finding on the node, queued and visualized like any other low-trust fact. The recording-linked-to-wrong-work error is one of the biggest silent royalty leaks in publishing.

The edge lifecycle

One state machine answers "how do users update and verify" for edges and for every metadata channel on the lantern. An assertion enters cheap, hardens with independent evidence, and only becomes financially real when a rightsholder puts their name on it.

Metadata on the glyph is the same problem

Every channel of the Provenance Lantern — writer cubes, artist-match tetrahedron, markets disc, match-score halo — maps to a field with its own provenance. So "update the metadata attached to a glyph" is not a separate system: a wrong writer count is an assertion against that field, it enters the same queue, and a rightsholder attestation resolves it the same way. One lifecycle, two kinds of object: fields on nodes, and edges between nodes. The F07 scenes already visualize exactly this — the trust cage and dim halos are the review queue, drawn in space.

What a confirmed edge unlocks

The edge is the relationship, so the edge is where the deals live:

• Clearance offers. The derivative side opens an offer on an uncleared edge ("license this sample retroactively / for the re-release"); the original side counters or accepts. On acceptance the edge gets terms and flips to CLEARED.
• Split routing. A cleared edge writes an effective-dated split share on the derivative work that references the edge — Johnson's estate appears in "The Lemon Song"'s splits because of the edge, with the edge as provenance. Same SplitShare machinery, same MFN discipline, new source type.
• Exposure alerts, both directions. "Works sampling yours are earning and you have no cleared edge" (you're owed) and "your work carries a corroborated uncleared sample and it's charting" (you owe — settle before it's a lawsuit). This is the single strongest reason a rightsholder logs in weekly.
• Pre-cleared inventory. A rightsholder can mark parts of the catalogue sample-ready at posted terms — turning clearance from litigation into checkout, on rails bushido already operates.

Payment mechanics reuse what exists: platform-hold for parties with bank details only, the standard payout flow for onboarded ones. Nothing new below the edge.

Reconciliation is the commercial layer, already running

Uncovering misallocated, unclaimed, and mismatched royalties is not a future feature — bushido's royalty reconciliation engine already runs. It detects every plausible use of a work, then refuses to call anything "recoverable" until evidence proves it, at the accounting grain that matters:

platform use × right × territory × period

One YouTube video can be paid on the master and unpaid on the composition; one work can be covered in the US and leaking in Germany. It keeps tri-state evidence (true / false / unknown — and unknown is never zero) across four payment gates, and sorts every use into three lanes. Those lanes map straight onto the scene grammar:

The leak taxonomy

"Misallocated, unclaimed, mismatched" are three different failures, and the graph localizes each one to a different element:

The reconciliation is a single computable statement: expected flow (credit shares × cleared derivation edges × observed usage) minus observed flow (statements, claims, payouts) should be zero on every edge. Everywhere it isn't, the difference is a colored, sized, clickable object in space — with the evidence trail behind the click. Conservative by construction: no fabricated rates, no unknown-collapsed-to-zero, no money claimed without usage, rate, share, and currency all sourced.

How a royalty relation becomes rows in a CSV

This is the part that makes the whole thing buildable tonight: the exact mapping from Song Graph objects to the data viz engine node-CSV rows, proven by loading a real scene into the data viz web viewer. A derivation edge — the relation that ties an original copyright to a derivative work — is one row:

Edge states are fixed RGBA values so every scene reads identically: grey 110,110,130 gold 240,180,60 blue 93,143,221 green 80,200,140 red 230,60,60. Three real rows from the working demo — a work, its unpaid debt, and a corroborated claim:

F08-0 · The marquee chain, shipped

The demo scene exists and renders: F08_0_marquee_chain_gv_node.csv + cheat sheet, in the shared CSV + cheat-sheet pair format. Nine recordings from Memphis Minnie (1929) to the Beastie Boys (1986) as a lineage tower — Z is release year — with all six derivation edges colored by state: the credited Levee Breaks cover and the settled Killing Floor dispute in green, the Sweet Leaf sample gold awaiting attestation, and Robert Johnson's uncredited lemon verse as the one red chord in the scene, with the red exposure cone sitting on "The Lemon Song" fifty years up. Drag the folder onto the data viz web viewer and click the red edge: ASSERTED - NEVER CREDITED - $0 routed, with a bushido deep link in the panel. That's the product, nine nodes at a time.

The claim console — built and working

The data viz engine is our partner's app; we can't add buttons inside it. So the "add this song to a list" UI lives where mutation always lives — on a bushido page — and the link column is the seam that gets you there without losing your place. A working prototype exists and is verified in a browser:

• Entry 1 — from the viz. Select a glyph, press U, and the console opens with that work loaded into a claim card: title, artist, year, and every derivation edge touching it, each colored by state and stating its claim in words ("borrows from Travelling Riverside Blues — INTERPOLATES · never credited · $0 routed"). One control: add this song to a list.
• Entry 2 — from the catalogue. A filterable song list where every row carries its worst-edge state chip and a list picker. Pick a list, the song lands in it; the picker collapses back. No modal, no page change — a worklist is built by walking down the rows. Filtering also arms a bulk control (add all 10 to…), because triage is a set operation: the ten audit works go into a list in one action and one write.
• Entry 3 — back into the viz. Each list exports as a data viz scene CSV (sunflower layout, audit works in gold, links pointing back at the console). Save it, drag it onto the data viz web viewer, and your list is a scene you can fly — the loop closed in both directions.
• Entry 4 — record a verdict. The audit chip is itself the control: click it anywhere it appears and that work's claim card opens, stating why it is in the queue (match score 0.50, title-only; no artist confirmation; popular — real money moves on this) and offering the three answers that resolve it — match is correct wrong work can't tell yet — plus a note for the evidence. The verdict is stamped, reversible, and immediately recolors the chip, the list dot, the "N of 10 triaged" counter, and the next export.

Worked end to end, on real data: filtering the console to the ten unconfirmed audit works, bulk-adding them to an "Audit top 10" list, exporting, and dropping the file onto the data viz web viewer yields ten gold glyphs in a sunflower; clicking one reads AHORA | — (unconfirmed) | UMLE – Latino | LIST: Audit top 10 and carries the link straight back to its claim page. That scene ships as F08-1; F08-2 is the same ten after triage, where colour is no longer "these are suspects" but what a human decided — gold unresolved, green confirmed, red wrong-work.

"Wrong work" is only half a finding

The other half is which work it should be — and that is what HOLY GRAIL is for. Choosing wrong work opens a resolve step that models the real client call, not an invented one:

HolyGrailClient.enrichRights({isrc, title, artist})
→ GET /enrich?isrc=…&title=…&artist=…&providers=bwarm,musicbrainz,mlc

That allowlist is not a choice I made — it is the constant the codebase already defines for exactly this job (HOLY_GRAIL_RIGHTS_PROVIDERS, "a deliberately bounded metadata-only set for reconciliation corroboration"). The panel shows the request it would issue, then lists candidate works ranked by confidence with the fields that decide a rights question: ISWC, writers, publishers, society. Picking one records a proposed correction on the assertion — and the ISWC travels into the exported scene label, so the glyph states not just this is broken but this is what it should be.

The guardrail is the one the reconciliation spec already froze: HOLY GRAIL corroborates, never confirms. A proposal is evidence attached to a claim, not a re-link. So the console makes the handoff explicit rather than implying the fix has landed.

Who may apply it — and what "applied" means

A proposal moves through four states, and only the last one changes anything: proposed → sent → accepted (or rejected, with a reason). The curator can propose and send; only a rightsholder can accept, and acceptance is the moment the recording→work link is rewritten. The console gates this on the actor and tells a curator plainly that the decision is not theirs — in production that gate is the session, not a switch.

The applied correction is not a silent overwrite. It carries its whole trail — who asserted the mismatch and on what note, which provider proposed the replacement and at what confidence, who sent it, who accepted it and when — and the rightsholder can withdraw the decision. This is the same discipline the splits already enforce: effective-dated, attributable, reversible. In the scene, a corrected work turns blue and its label reads LINK CORRECTED -> NOW … [ISWC].

That completes the sentence the whole system exists to finish: this popular recording is matched to the wrong composition, here is the right one on two independent providers' evidence, the rightsholder agreed, and the link now points there — which is the difference between a dashboard that counts problems and a pipeline that ends with the correct people being paid.

The naming matters more than the widget. A verdict is an assertion, not an edit: it never mutates the graph of record, it carries author, timestamp and note, and it can be withdrawn. wrong work is precisely the mismatched node-level finding from the leak taxonomy — the recording→work link is broken, so composition royalties are routing to the wrong song or to nobody. That is the whole point of making a chip clickable: one click turns a data-quality suspicion into a filed, attributable claim that the review queue can act on.

Lists are shared and live: they live in the artifact's own store, so every viewer sees the same lists update in real time, and the page degrades to per-browser storage when that store isn't available. That is deliberately the prototype's shape — in production the same three surfaces sit on bushido, where the list is a real record with auth, provenance, and effective dates, and "add to list" is the lightest possible first rung on the same ladder that ends in CLEARED.

Lists rank by money, count signatures, and organise by topic

A worklist earns its order: items sort by highest est. collectable royalty first (the exposure-ledger figure for the work — the sunflower centre and the biggest glyph in the exported scene), and every row carries the shareholder count as approved/total ✓. The claim card expands that into the roster the money is actually blocked on: each holder with role, share and an APPROVED (LOD-attested) or WAITING chip — so "who approved, who is waiting" is one glance, and a list header totals it ($24,650 est. collectable · 9/16 holders approved · 0 of 3 triaged).

Lists organise under topics — an artist, a campaign, any phrase. The search box is the topic engine: terms score independently, so typing britney spears toxic sample remix edits ranks the Toxic cluster first, and one click on new list from this filter creates a list named and topic-tagged by the phrase with everything shown in it. The demo catalogue carries that exact cluster: the Bollywood string sample under "Toxic" (cleared, credited), the official club remix (cleared), and the viral "Toxic Pony" mashup edit — $23,800 est. collectable with one approval and seven shareholders waiting across both the Toxic and Pony sides, which is precisely the many-signature clearance case the roster view exists for.

The design point worth keeping: adding a song to a list is an assertion like any other — the cheapest one, requiring no evidence, reversible, and private to the list. It is how a curator or a rightsholder starts a session, and it feeds the same queue everything else does.

The viz is a lens, never the editor

the data viz engine stays what it's brilliant at — a free, run-anywhere projection of the graph. All mutation happens on bushido claim pages, so there is exactly one source of truth and every change carries auth, provenance, and effective dates. The bridge between the two worlds is now verified: every glyph part and every edge row carries a bushido URL in its link column, and pressing U on a selected glyph opens it. Lists, tables (the engine's own Node Table, selection-synced both ways with the 3D view), and diagrams are all projections of the same rows — so "acting from the table" and "acting from the diagram" are the same claim page reached two ways.

Three phases, demo-first

• P0 — seed & show. DerivationEdge schema keyed to HOLY GRAIL entities; import candidate edges for the 1,414-work UMPG/Chord set from open sources (MusicBrainz relations, SecondHandSongs, citations) and credit edges from HOLY GRAIL work_data + CWR; hand-curate the marquee blues→rock→hip-hop chains; ship F08-1, F08-4, and F09-1 as the next scene drop for the partner scene pipeline. No product surface yet — the viz is the demo, and the credit layer costs almost nothing extra because the data already flows through enrichment.
• P1 — verify. Claim pages + review queue (graphite's confidence contract and the admin waveform-comparison view, reused); LOD-portal attestation flow; deep links from tag ids; community assertions open with evidence required; HOLY GRAIL responses wired in as corroboration-class evidence. Ship F08-2, F08-3, and F09-2.
• P2 — transact & reconcile. Clearance offers, edge-sourced split shares, exposure alerts, pre-cleared inventory. The detection engine for this phase already exists inside bushido, so the work is wiring its three lanes into the scene bakes and the alert surface, not building reconciliation. Ship F08-5 and F09-3 once real quarterly lanes exist to animate.

Open-data question to settle early (P0, because it shapes the license header on every export): the graph — nodes, edges, evidence, states — is published open; confidence models, bushido signals, and settlement rails stay the product.

The open questions, answered from the docs and a live test

These were resolved from the engine's reference docs, the examples gallery (the RFC Genealogy lineage scenes are the closest existing relative of the Song Graph), and by building and loading the F08-0 demo into the data viz web viewer:

Our data viz partner confirmed the last three, and each is now proven in a shipped scene (F08-0 v2 "money flows" — 14 works, 10 edges, 14/14 textures loading in the data viz web viewer):

• Link width: yes. “The ratio sets the size for the links” (per the engine's author) — and links can take any geometry. Edge thickness now carries $ at stake: cylinder rods, ratio = 0.10 + 0.95·(stake/max). The two fattest pipes in the scene are the two unsettled debts — Johnson → Lemon Song and Toxic → Toxic Pony.
• Textures: media/ folder + texture_id (1-based, alphabetical — numeric-prefix the filenames), on a texturable geometry (sphere/cube; the engine's author advised switching off the dodecahedron). And the colour rule, confirmed by the engine's author: a textured object must be white or the texture is tinted by the node colour. Our bodies ship 255,255,255 so the artwork shows true — and the tint is a deliberate channel held in reserve: washing a cover toward red is a legitimate way to make an earning-but-unsettled work's own artwork carry the warning. Not used yet; the exposure cone owns that job for now.
• Artwork vs colour channel: both survive. The genre/era colour moved to a wide disc under each body (worst-edge-state disc beneath it) — settled empirically, not by argument.
• Curved edges: “there are no curved lines… yet.” Straight rods remain the grammar; the lineage tower was designed for exactly that.