Cross-Source Event Identity Resolver

The naive key fails on every real case

Nearly every aggregator starts with `title | venueId | startHour`. Here is what that does to live data:

Titles disagree by design. One night arrives as `Nova Vale | The Ascent Tour`, `Nova Vale`, `Live Nation presents: NOVA VALE - The Ascent Tour (Rescheduled)`, and `Nova Vale w/ special guest Kestrel — 18+`. Exact match finds none of them. A loose `includes()` merges Nova Vale Tribute into the headliner — which sells someone a covers night believing they bought the real act. That is the highest-consequence false merge in the domain, and there is an explicit blocklist for it (tribute, karaoke, parking, VIP, afterparty, meet & greet). A tribute show from two sources still merges correctly with itself.

Venue ids are per-source. There is no shared venue identifier anywhere, and venues get renamed — two sources can share zero name tokens and be the same building. Venue identity uses names *and* coordinates, with the generic words (arena, theatre, center, the) stripped, and "formerly X" clauses removed.

"Rescheduled" moves the date but not the identity — while two nights of the same tour at the same venue *are* different events. So the date both matters and doesn't, and only the status text tells you which case you are in. Both directions are handled, symmetrically.

Start times disagree by 30–90 minutes — doors vs showtime, and sources publishing venue-local time without an offset. Truncating to the hour splits 7:59 and 8:01 into different events. Instants are compared with explicit tolerance.

Transitivity is a trap. If A matches B and B matches C, union-find collapses A with C even when they are plainly different — one weak middle link quietly swallows a cluster, and you simply show fewer events than exist. A candidate here must match *every* member of a cluster, not just the neighbour it was compared against. The unguarded mode is included, and there is a test that demonstrates the bug it exists to prevent.

Merge precedence is per field, not last-write-wins. Lowest *actual* price (a missing price is unknown, never free — that is how you advertise a free ticket that does not exist), most complete title, coordinates preferred over a bare name, and the new date when anything was rescheduled. Every source record is retained so a merge is always auditable, and ids are stable across re-runs so downstream caches do not churn.

Verified by mutation

Every rule had its guard removed one at a time and the suite was confirmed to fail. The set is declared in the product's own `mutations.json` and re-runnable: 9 deliberate defects, 8 caught, 1 provably equivalent — the equivalent one is the match floor, and the reason it changes nothing is in the suite as an argument you can check rather than a number you have to trust.

One mutation initially *survived*: removing the reschedule check for one of the two argument orders broke nothing, because the test only ever put the reschedule on one side. That gap is now closed and covered. Building this also surfaced a real scoring bug — time was an additive 30%, so a perfect venue and title could out-vote it and merge a matinee with an evening show. Time now multiplies, so weak time agreement caps the whole score no matter what else lines up.

131 tests passing · typecheck clean · 8/9 deliberate defects caught, 1 provably equivalent.

Also included

`explain(a, b)` returns a plain-language verdict — `NO MERGE — blocked by disqualifier:tribute` — so a wrong result is debuggable rather than mysterious.

Delivery

Private repository invite within 24 hours. Single-product commercial license: use and modify in one shipped product; no redistribution or resale of the source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function normalizeTitle(raw: string): string;
  export function titleTokens(raw: string): string[];
  export function hasDisqualifier(a: string, b: string): string | null;
  export function titleSimilarity(a: string, b: string): number;
  export function normalizeVenue(raw: string): string;
  export function venueTokens(raw: string): string[];
  export function venueSimilarity(a: VenueRef, b: VenueRef): number;
  export function startsWithin(a: string, b: string, toleranceMin: number): boolean;
  export function scoreMatch(a: SourceEvent, b: SourceEvent, opts: ResolveOptions = {}): Match;
  export function mergeCluster(members: SourceEvent[]): ResolvedEvent;
  export function resolveEvents(events: SourceEvent[], opts: ResolveOptions = {}): ResolvedEvent[];
  export function explain(a: SourceEvent, b: SourceEvent, opts: ResolveOptions = {}): string;