untappd-mcp 2.3.2 → 2.5.0

package/dist/cache/store.js

@@ -17,12 +17,21 @@
 // schema/queries back any engine: `node:sqlite` is the one that ships, and a
 // different deployment can adapt another driver to the same surface. This
 // module imports nothing platform-specific.
+/** Default radius for a lat/lng has-visited query. */
+export const DEFAULT_VISIT_RADIUS_M = 150;
+export const FAVORITE_KINDS = ['beer', 'brewery', 'venue'];
 function asDict(v) {
     return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
 }
 function num(v) {
     return typeof v === 'number' && Number.isFinite(v) ? v : null;
 }
+/** A number, or a numeric string (coordinates sometimes arrive as strings). */
+function numLoose(v) {
+    if (typeof v === 'string' && v.trim() !== '')
+        return num(Number(v));
+    return num(v);
+}
 function str(v) {
     return typeof v === 'string' && v.length > 0 ? v : null;
 }
@@ -82,6 +91,107 @@ export function mapBeerRow(username, item) {
         last_had: normaliseDate(c.recent_created_at ?? c.first_created_at),
     };
 }
+/**
+ * Normalise a raw `/user/venues` item to the shared venue facts plus the user's
+ * visit summary. Dates become ISO-8601 UTC (sortable, comparable across syncs).
+ * Returns null without a venue id (Untappd sends `venue: []` for none).
+ */
+export function mapUserVenueItem(_username, item) {
+    const c = asDict(item);
+    const v = asDict(c.venue);
+    const venue_id = num(v.venue_id);
+    if (venue_id === null)
+        return null;
+    const loc = asDict(v.location);
+    const verified = v.is_verified;
+    return {
+        venue: {
+            venue_id,
+            name: str(v.venue_name),
+            category: str(v.primary_category),
+            address: str(loc.venue_address),
+            city: str(loc.venue_city),
+            state: str(loc.venue_state),
+            country: str(loc.venue_country),
+            lat: numLoose(loc.lat),
+            lng: numLoose(loc.lng),
+            is_verified: typeof verified === 'boolean' || typeof verified === 'number' ? (verified ? 1 : 0) : null,
+        },
+        visit: {
+            venue_id,
+            first_visit: normaliseDate(c.first_visit),
+            first_checkin_id: num(c.first_checkin_id),
+            recent_visit: normaliseDate(c.recent_visit),
+            recent_checkin_id: num(c.recent_checkin_id),
+            total_count: num(c.total_count),
+        },
+    };
+}
+/**
+ * Map one brewery/beer_list item to a {@link BreweryBeerRow}. Takes only the
+ * global facts: the item's `has_had` / `total_user_count` are the AUTHENTICATED
+ * account's and are deliberately dropped. Returns null without a bid.
+ */
+export function mapBreweryBeerItem(breweryId, item, fetchedAt, popularityRank) {
+    const i = asDict(item);
+    const b = asDict(i.beer);
+    const bid = num(b.bid);
+    if (bid === null)
+        return null;
+    const inProd = num(b.is_in_production);
+    return {
+        brewery_id: breweryId,
+        bid,
+        beer_name: str(b.beer_name),
+        style: str(b.beer_style),
+        abv: num(b.beer_abv),
+        ibu: num(b.beer_ibu),
+        rating_score: num(b.rating_score),
+        rating_count: num(b.rating_count),
+        checkin_count: num(i.total_count),
+        in_production: inProd === null ? null : inProd !== 0,
+        popularity_rank: popularityRank,
+        fetched_at: fetchedAt,
+    };
+}
+/** Map one user/wishlist item; null without a bid. */
+export function mapWishlistItem(item) {
+    const i = asDict(item);
+    const b = asDict(i.beer);
+    const bid = num(b.bid);
+    if (bid === null)
+        return null;
+    const brw = asDict(i.brewery);
+    return {
+        bid,
+        beer_name: str(b.beer_name),
+        brewery_id: num(brw.brewery_id),
+        brewery_name: str(brw.brewery_name),
+        style: str(b.beer_style),
+        abv: num(b.beer_abv),
+        added_at: normaliseDate(i.created_at),
+    };
+}
+/** Map one user/brewerylikes item; null without a brewery_id. */
+export function mapBreweryLikeItem(item) {
+    const i = asDict(item);
+    const b = asDict(i.brewery);
+    const id = num(b.brewery_id);
+    if (id === null)
+        return null;
+    const loc = asDict(b.location);
+    return {
+        brewery_id: id,
+        brewery_name: str(b.brewery_name),
+        brewery_type: str(b.brewery_type),
+        country: str(b.country_name),
+        city: str(loc.brewery_city),
+        state: str(loc.brewery_state),
+        lat: num(loc.lat),
+        lng: num(loc.lng),
+        liked_at: normaliseDate(i.created_at),
+    };
+}
 /**
  * Normalise a beer object (from beer/info's `beer`, or a search/list item's
  * `beer` with a sibling `brewery`) to {@link BeerMeta}. `fetchedAt` stamps when
@@ -180,7 +290,11 @@ export const SCHEMA_STATEMENTS = [
      beers_rescan_target INTEGER
    )`,
 ];
-/** Columns added after the initial release, each applied idempotently on open. */
+/**
+ * Columns added to the v1 tables before the schema was versioned. A database
+ * at user_version 0 may predate any of them, so each is applied idempotently
+ * (ADD COLUMN throws harmlessly when the column already exists).
+ */
 export const MIGRATIONS = [
     'ALTER TABLE sync_state ADD COLUMN catchup_max_id INTEGER',
     'ALTER TABLE sync_state ADD COLUMN checkins_truncated INTEGER NOT NULL DEFAULT 0',
@@ -191,6 +305,207 @@ export const MIGRATIONS = [
     'ALTER TABLE sync_state ADD COLUMN beers_accepted_gap INTEGER NOT NULL DEFAULT 0',
     'ALTER TABLE sync_state ADD COLUMN beers_rescan_target INTEGER',
 ];
+/**
+ * Forward-only, versioned migrations, tracked in SQLite's `PRAGMA user_version`.
+ * Version 1 is the baseline (SCHEMA_STATEMENTS + the legacy MIGRATIONS above);
+ * every later change is appended here with the next version number and is
+ * ADDITIVE — a migration never drops or rewrites user rows, so upgrading can't
+ * silently wipe a cache that took an hour of rate-limited calls to fill.
+ */
+export const VERSIONED_MIGRATIONS = [
+    {
+        version: 2,
+        statements: [
+            `CREATE TABLE IF NOT EXISTS item_resolutions (
+         key         TEXT PRIMARY KEY,
+         item        TEXT NOT NULL,
+         status      TEXT NOT NULL,
+         bid         INTEGER,
+         data        TEXT,
+         resolved_at TEXT NOT NULL
+       )`,
+        ],
+    },
+    {
+        // untappd_cache_query's default (and date-range) ordering.
+        version: 3,
+        statements: ['CREATE INDEX IF NOT EXISTS idx_checkins_user_created ON checkins(username, created_at)'],
+    },
+    {
+        // Venue history, list syncs, TTL caches, favorites and the API call log.
+        // New tables only — nothing existing is altered.
+        version: 4,
+        statements: [
+            // Global venue facts from user/venues (and venue/info), shared across users.
+            `CREATE TABLE IF NOT EXISTS venues (
+         venue_id    INTEGER PRIMARY KEY,
+         name        TEXT,
+         category    TEXT,
+         address     TEXT,
+         city        TEXT,
+         state       TEXT,
+         country     TEXT,
+         lat         REAL,
+         lng         REAL,
+         is_verified INTEGER,
+         updated_at  TEXT
+       )`,
+            `CREATE INDEX IF NOT EXISTS idx_venues_city ON venues(city COLLATE NOCASE)`,
+            `CREATE INDEX IF NOT EXISTS idx_venues_lat_lng ON venues(lat, lng)`,
+            // One row per (user, venue) from user/venues: the user's visit summary there.
+            `CREATE TABLE IF NOT EXISTS user_venues (
+         username          TEXT NOT NULL,
+         venue_id          INTEGER NOT NULL,
+         first_visit       TEXT,
+         first_checkin_id  INTEGER,
+         recent_visit      TEXT,
+         recent_checkin_id INTEGER,
+         total_count       INTEGER,
+         synced_at         TEXT,
+         PRIMARY KEY (username, venue_id)
+       )`,
+            `CREATE INDEX IF NOT EXISTS idx_user_venues_recent ON user_venues(username, recent_visit)`,
+            // Resumable cursor + reported total for offset-paged per-user lists
+            // (list = 'venues' | 'wishlist' | …). Kept out of sync_state so each list
+            // owns its own bookkeeping.
+            `CREATE TABLE IF NOT EXISTS list_sync_state (
+         username       TEXT NOT NULL,
+         list           TEXT NOT NULL,
+         next_offset    INTEGER,
+         total_count    INTEGER,
+         complete       INTEGER NOT NULL DEFAULT 0,
+         last_synced_at TEXT,
+         PRIMARY KEY (username, list)
+       )`,
+            // brewery/beer_list results, per brewery, with a TTL on the list as a whole.
+            // The response's have_had reflects the AUTHENTICATED account, so it is not stored.
+            // fetched_at is when the current snapshot STARTED (its TTL clock);
+            // ranked_count is how many beers from the top of Untappd's default
+            // (popularity) order are cached contiguously.
+            `CREATE TABLE IF NOT EXISTS brewery_beer_lists (
+         brewery_id   INTEGER PRIMARY KEY,
+         brewery_name TEXT,
+         total_count  INTEGER,
+         ranked_count INTEGER NOT NULL DEFAULT 0,
+         fetched_at   TEXT NOT NULL
+       )`,
+            `CREATE TABLE IF NOT EXISTS brewery_beers (
+         brewery_id    INTEGER NOT NULL,
+         bid           INTEGER NOT NULL,
+         beer_name     TEXT,
+         style         TEXT,
+         abv           REAL,
+         rating_score  REAL,
+         rating_count  INTEGER,
+         checkin_count INTEGER,
+         in_production INTEGER,
+         popularity_rank INTEGER,
+         fetched_at    TEXT NOT NULL,
+         PRIMARY KEY (brewery_id, bid)
+       )`,
+            // Short-TTL raw response cache (venue menus / activity), keyed e.g. 'venue_menu:123'.
+            `CREATE TABLE IF NOT EXISTS response_cache (
+         key        TEXT PRIMARY KEY,
+         kind       TEXT NOT NULL,
+         data       TEXT NOT NULL,
+         fetched_at TEXT NOT NULL
+       )`,
+            `CREATE TABLE IF NOT EXISTS wishlist (
+         username     TEXT NOT NULL,
+         bid          INTEGER NOT NULL,
+         beer_name    TEXT,
+         brewery_id   INTEGER,
+         brewery_name TEXT,
+         style        TEXT,
+         abv          REAL,
+         added_at     TEXT,
+         synced_at    TEXT NOT NULL,
+         PRIMARY KEY (username, bid)
+       )`,
+            // Manual favorites — local only, never written to Untappd.
+            `CREATE TABLE IF NOT EXISTS favorites (
+         username   TEXT NOT NULL,
+         kind       TEXT NOT NULL CHECK (kind IN ('beer', 'brewery', 'venue')),
+         id         INTEGER NOT NULL,
+         note       TEXT,
+         created_at TEXT NOT NULL,
+         PRIMARY KEY (username, kind, id)
+       )`,
+            // What a user drank at a venue, from checkin/view of the user_venues first/recent check-ins.
+            `CREATE TABLE IF NOT EXISTS venue_drinks (
+         username     TEXT NOT NULL,
+         venue_id     INTEGER NOT NULL,
+         checkin_id   INTEGER NOT NULL,
+         bid          INTEGER,
+         beer_name    TEXT,
+         brewery_id   INTEGER,
+         brewery_name TEXT,
+         created_at   TEXT,
+         fetched_at   TEXT NOT NULL,
+         PRIMARY KEY (username, checkin_id)
+       )`,
+            `CREATE INDEX IF NOT EXISTS idx_venue_drinks_user_venue ON venue_drinks(username, venue_id)`,
+            // Every API response's time/status/rate-limit headers (src/ratelimit.ts),
+            // shared by all processes using this file. Pruned to ~2 hours.
+            `CREATE TABLE IF NOT EXISTS api_calls (
+         at            INTEGER NOT NULL,
+         status        INTEGER NOT NULL,
+         remaining     INTEGER,
+         limit_hdr     INTEGER,
+         reset_at      INTEGER,
+         retry_after_s INTEGER
+       )`,
+            `CREATE INDEX IF NOT EXISTS idx_api_calls_at ON api_calls(at)`,
+        ],
+    },
+    {
+        // Untappd brewery likes (user/brewerylikes, the app's "following") — the
+        // "untappd" favorite source. A new table only; nothing existing is altered.
+        version: 5,
+        statements: [
+            `CREATE TABLE IF NOT EXISTS brewery_likes (
+         username     TEXT NOT NULL,
+         brewery_id   INTEGER NOT NULL,
+         brewery_name TEXT,
+         brewery_type TEXT,
+         country      TEXT,
+         city         TEXT,
+         state        TEXT,
+         lat          REAL,
+         lng          REAL,
+         liked_at     TEXT,
+         synced_at    TEXT NOT NULL,
+         PRIMARY KEY (username, brewery_id)
+       )`,
+        ],
+    },
+    {
+        // brewery/beer_list items carry `beer_ibu`, which the old live-only compact
+        // projection returned; caching it keeps untappd_brewery_beers' compact shape
+        // identical with and without the cache. Additive: rows cached before this
+        // read back ibu null until the list next refreshes (7-day TTL).
+        version: 6,
+        statements: [`ALTER TABLE brewery_beers ADD COLUMN ibu REAL`],
+    },
+];
+/** Tables holding one user's data, cleared by {@link CheckinStoreCore.forgetUser}. */
+export const PER_USER_TABLES = [
+    'checkins',
+    'distinct_beers',
+    'sync_state',
+    'user_venues',
+    'list_sync_state',
+    'wishlist',
+    'favorites',
+    'venue_drinks',
+    'brewery_likes',
+];
+/** How long short-TTL cached responses are kept at all (longer than any TTL that can serve them). */
+export const RESPONSE_CACHE_RETENTION_MS = 48 * 60 * 60 * 1000;
+/** How long the persisted API call log is kept (it only needs the rolling hour). */
+const API_CALL_LOG_RETENTION_MS = 2 * 60 * 60 * 1000;
+/** The schema version this code writes. */
+export const SCHEMA_VERSION = VERSIONED_MIGRATIONS.reduce((v, m) => Math.max(v, m.version), 1);
 /**
  * The cache logic over a synchronous {@link SqlDriver}. Usernames are keyed
  * case-insensitively via a lowercased key so `Mer1331` and `mer1331` share one
@@ -198,20 +513,63 @@ export const MIGRATIONS = [
  */
 export class CheckinStoreCore {
     db;
+    version = 0;
     constructor(db) {
         this.db = db;
-        for (const stmt of SCHEMA_STATEMENTS)
-            this.db.execScript(stmt);
-        // Forward-compat for a table created before a column existed; each ADD COLUMN
-        // throws harmlessly if the column is already present.
-        for (const mig of MIGRATIONS) {
-            try {
-                this.db.execScript(mig);
+        this.migrate();
+    }
+    /**
+     * Bring the schema up to {@link SCHEMA_VERSION}. Runs in ONE write
+     * transaction and re-reads the version inside it, so two processes opening a
+     * fresh file at once can't both apply the same step. A file written by a
+     * NEWER build is left untouched (its migrations are additive, so this build's
+     * queries still work) rather than "repaired" downwards.
+     */
+    migrate() {
+        this.db.transaction(() => {
+            const current = Number(this.db.get('PRAGMA user_version', [])?.user_version ?? 0);
+            if (current > SCHEMA_VERSION) {
+                console.error(`[untappd-mcp] cache schema v${current} is newer than this build (v${SCHEMA_VERSION}); using it as-is.`);
+                this.version = current;
+                return;
             }
-            catch {
-                /* column already exists */
+            if (current < 1) {
+                for (const stmt of SCHEMA_STATEMENTS)
+                    this.db.execScript(stmt);
+                // A pre-versioning file may lack any of these columns; each ADD COLUMN
+                // throws harmlessly if the column is already present.
+                for (const mig of MIGRATIONS) {
+                    try {
+                        this.db.execScript(mig);
+                    }
+                    catch {
+                        /* column already exists */
+                    }
+                }
             }
-        }
+            for (const m of VERSIONED_MIGRATIONS) {
+                if (m.version <= current)
+                    continue;
+                for (const stmt of m.statements) {
+                    try {
+                        this.db.execScript(stmt);
+                    }
+                    catch (e) {
+                        // An ADD COLUMN step is idempotent: a file whose user_version lags
+                        // its real schema (e.g. reset by hand) already has the column.
+                        if (!/ADD COLUMN/i.test(stmt) || !/duplicate column/i.test(String(e?.message)))
+                            throw e;
+                    }
+                }
+            }
+            if (current !== SCHEMA_VERSION)
+                this.db.execScript(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+            this.version = SCHEMA_VERSION;
+        });
+    }
+    /** The schema version of the open database. */
+    schemaVersion() {
+        return this.version;
     }
     /**
      * Upsert real check-in rows (dedupe on checkin_id) in one transaction; return
@@ -221,7 +579,7 @@ export class CheckinStoreCore {
         if (rows.length === 0)
             return 0;
         const key = username.toLowerCase();
-        const before = this.cachedCount(username);
+        let added = 0;
         const sql = `
       INSERT INTO checkins
         (checkin_id, username, bid, beer_name, brewery_id, brewery_name, beer_style, abv, rating, comment, venue_id, venue_name, created_at)
@@ -231,7 +589,14 @@ export class CheckinStoreCore {
         brewery_id=excluded.brewery_id, brewery_name=excluded.brewery_name, beer_style=excluded.beer_style,
         abv=excluded.abv, rating=excluded.rating, comment=excluded.comment,
         venue_id=excluded.venue_id, venue_name=excluded.venue_name, created_at=excluded.created_at`;
+        // "Net new" = ids this user didn't already have, read inside the write
+        // transaction so another process's concurrent inserts can't skew it. It
+        // looks up only this batch's ids; COUNT(*)-before/after scanned the user's
+        // whole history on every page, which made a long backfill quadratic.
         this.db.transaction(() => {
+            const ids = [...new Set(rows.map((r) => r.checkin_id))];
+            const had = this.existing('checkins', 'checkin_id', key, ids);
+            added = ids.filter((id) => !had.has(id)).length;
             for (const r of rows) {
                 this.db.run(sql, [
                     r.checkin_id, key, r.bid, r.beer_name, r.brewery_id, r.brewery_name, r.beer_style,
@@ -239,14 +604,14 @@ export class CheckinStoreCore {
                 ]);
             }
         });
-        return this.cachedCount(username) - before;
+        return added;
     }
     /** Upsert distinct-beer rows (dedupe on username+bid); return the NET new count. */
     upsertDistinctBeers(username, rows) {
         if (rows.length === 0)
             return 0;
         const key = username.toLowerCase();
-        const before = this.distinctBeersCount(username);
+        let added = 0;
         const sql = `
       INSERT INTO distinct_beers
         (username, bid, beer_name, brewery_id, brewery_name, beer_style, abv, rating, had_count, first_had, last_had)
@@ -256,6 +621,9 @@ export class CheckinStoreCore {
         beer_style=excluded.beer_style, abv=excluded.abv, rating=excluded.rating,
         had_count=excluded.had_count, first_had=excluded.first_had, last_had=excluded.last_had`;
         this.db.transaction(() => {
+            const bids = [...new Set(rows.map((r) => r.bid))];
+            const had = this.existing('distinct_beers', 'bid', key, bids);
+            added = bids.filter((b) => !had.has(b)).length;
             for (const r of rows) {
                 this.db.run(sql, [
                     key, r.bid, r.beer_name, r.brewery_id, r.brewery_name, r.beer_style, r.abv,
@@ -263,7 +631,17 @@ export class CheckinStoreCore {
                 ]);
             }
         });
-        return this.distinctBeersCount(username) - before;
+        return added;
+    }
+    /** Which of `ids` already exist in `table.column` for this (lowercased) user. */
+    existing(table, column, key, ids) {
+        const found = new Set();
+        for (const part of chunks(ids)) {
+            const rows = this.db.all(`SELECT ${column} AS id FROM ${table} WHERE username = ? AND ${column} IN (${part.map(() => '?').join(', ')})`, [key, ...part]);
+            for (const r of rows)
+                found.add(Number(r.id));
+        }
+        return found;
     }
     /** Total cached check-in rows for a user. */
     cachedCount(username) {
@@ -275,6 +653,197 @@ export class CheckinStoreCore {
         const row = this.db.get('SELECT COUNT(*) AS n FROM distinct_beers WHERE username = ?', [username.toLowerCase()]);
         return Number(row?.n ?? 0);
     }
+    /**
+     * Upsert user/venues items in one transaction: the shared venue facts (the
+     * latest copy wins) and this user's visit rows. "added"/"updated" are taken
+     * against the rows already cached for just this batch's venue ids.
+     */
+    upsertUserVenues(username, items, now = new Date().toISOString()) {
+        if (items.length === 0)
+            return { added: 0, updated: 0 };
+        const key = username.toLowerCase();
+        const venueSql = `
+      INSERT INTO venues (venue_id, name, category, address, city, state, country, lat, lng, is_verified, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(venue_id) DO UPDATE SET
+        name=excluded.name, category=excluded.category, address=excluded.address, city=excluded.city,
+        state=excluded.state, country=excluded.country, lat=excluded.lat, lng=excluded.lng,
+        is_verified=excluded.is_verified, updated_at=excluded.updated_at`;
+        const visitSql = `
+      INSERT INTO user_venues
+        (username, venue_id, first_visit, first_checkin_id, recent_visit, recent_checkin_id, total_count, synced_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(username, venue_id) DO UPDATE SET
+        first_visit=excluded.first_visit, first_checkin_id=excluded.first_checkin_id,
+        recent_visit=excluded.recent_visit, recent_checkin_id=excluded.recent_checkin_id,
+        total_count=excluded.total_count, synced_at=excluded.synced_at`;
+        let added = 0;
+        let updated = 0;
+        this.db.transaction(() => {
+            const prior = new Map(this.getUserVenueVisits(key, items.map((i) => i.visit.venue_id)).map((r) => [r.venue_id, r]));
+            const seen = new Set();
+            for (const { venue: v, visit: u } of items) {
+                this.db.run(venueSql, [v.venue_id, v.name, v.category, v.address, v.city, v.state, v.country, v.lat, v.lng, v.is_verified, now]);
+                this.db.run(visitSql, [key, u.venue_id, u.first_visit, u.first_checkin_id, u.recent_visit, u.recent_checkin_id, u.total_count, now]);
+                if (seen.has(u.venue_id))
+                    continue;
+                seen.add(u.venue_id);
+                const p = prior.get(u.venue_id);
+                if (!p)
+                    added++;
+                else if (p.recent_visit !== u.recent_visit || p.total_count !== u.total_count)
+                    updated++;
+            }
+        });
+        return { added, updated };
+    }
+    getUserVenueVisits(username, venueIds) {
+        const out = [];
+        for (const ids of chunks([...new Set(venueIds)])) {
+            if (ids.length === 0)
+                continue;
+            const rows = this.db.all(`SELECT venue_id, first_visit, first_checkin_id, recent_visit, recent_checkin_id, total_count
+         FROM user_venues WHERE username = ? AND venue_id IN (${ids.map(() => '?').join(', ')})`, [username.toLowerCase(), ...ids]);
+            for (const r of rows)
+                out.push(visitFrom(r));
+        }
+        return out;
+    }
+    userVenuesCount(username) {
+        return Number(this.db.get('SELECT COUNT(*) AS n FROM user_venues WHERE username = ?', [username.toLowerCase()])?.n ?? 0);
+    }
+    getVenues(venueIds) {
+        const out = [];
+        for (const c of chunks([...new Set(venueIds)])) {
+            if (c.length === 0)
+                continue;
+            const rows = this.db.all(`SELECT * FROM venues WHERE venue_id IN (${c.map(() => '?').join(', ')})`, c);
+            for (const r of rows) {
+                out.push({
+                    venue_id: Number(r.venue_id),
+                    name: str(r.name),
+                    category: str(r.category),
+                    address: str(r.address),
+                    city: str(r.city),
+                    state: str(r.state),
+                    country: str(r.country),
+                    lat: num(r.lat),
+                    lng: num(r.lng),
+                    is_verified: num(r.is_verified),
+                });
+            }
+        }
+        return out;
+    }
+    getListState(username, list) {
+        const r = this.db.get('SELECT * FROM list_sync_state WHERE username = ? AND list = ?', [username.toLowerCase(), list]);
+        if (!r)
+            return undefined;
+        return {
+            username: String(r.username),
+            list: String(r.list),
+            next_offset: num(r.next_offset),
+            total_count: num(r.total_count),
+            complete: Number(r.complete) === 1,
+            last_synced_at: str(r.last_synced_at),
+        };
+    }
+    /** Read-merge-write in one write transaction (see {@link setState}). */
+    setListState(username, list, patch) {
+        const key = username.toLowerCase();
+        this.db.transaction(() => {
+            const cur = this.getListState(key, list);
+            const pick = (k, fallback) => k in patch ? patch[k] : (cur?.[k] ?? fallback);
+            this.db.run(`INSERT INTO list_sync_state (username, list, next_offset, total_count, complete, last_synced_at)
+         VALUES (?, ?, ?, ?, ?, ?)
+         ON CONFLICT(username, list) DO UPDATE SET
+           next_offset=excluded.next_offset, total_count=excluded.total_count,
+           complete=excluded.complete, last_synced_at=excluded.last_synced_at`, [
+                key,
+                list,
+                pick('next_offset', null),
+                pick('total_count', null),
+                pick('complete', false) ? 1 : 0,
+                pick('last_synced_at', null),
+            ]);
+        });
+    }
+    /**
+     * Cached venues the user has visited that match `q` (see {@link VenueQuery}),
+     * most-visited first. Name matching is deliberately loose — a brewery's
+     * taproom is its own venue (a brewery_id is not a venue_id), and Untappd keeps
+     * "… (duplicate of …)" copies — so a venue matches when the name is a literal
+     * case-insensitive substring of it, OR when every significant word of the name
+     * (ignoring "co", "company", "inc", "llc", "the") is a whole word of it.
+     */
+    findVisitedVenues(username, q) {
+        const key = username.toLowerCase();
+        const select = `SELECT v.venue_id AS venue_id, v.name, v.category, v.address, v.city, v.state, v.country,
+        v.lat, v.lng, v.is_verified, u.first_visit, u.first_checkin_id, u.recent_visit, u.recent_checkin_id, u.total_count
+      FROM user_venues u JOIN venues v ON v.venue_id = u.venue_id WHERE u.username = ?`;
+        const found = new Map();
+        if (q.venue_ids && q.venue_ids.length > 0) {
+            for (const ids of chunks([...new Set(q.venue_ids)])) {
+                const rows = this.db.all(`${select} AND u.venue_id IN (${ids.map(() => '?').join(', ')})`, [key, ...ids]);
+                for (const r of rows)
+                    found.set(Number(r.venue_id), visitedFrom(r));
+            }
+        }
+        const hasName = q.name !== undefined && q.name.trim() !== '';
+        const hasGeo = q.lat !== undefined && q.lng !== undefined;
+        if (hasName || hasGeo) {
+            const where = [];
+            const params = [key];
+            let tokens = [];
+            if (hasName) {
+                const name = q.name.trim();
+                tokens = significantTokens(name);
+                // Prefilter: the literal substring, or the longest significant word.
+                const longest = tokens.slice().sort((a, b) => b.length - a.length)[0];
+                if (longest) {
+                    where.push(`(v.name ${LIKE_MATCH} OR v.name ${LIKE_MATCH})`);
+                    params.push(`%${escapeLike(name)}%`, `%${escapeLike(longest)}%`);
+                }
+                else {
+                    where.push(`v.name ${LIKE_MATCH}`);
+                    params.push(`%${escapeLike(name)}%`);
+                }
+            }
+            if (q.city !== undefined && q.city.trim() !== '') {
+                where.push(`v.city ${LIKE_MATCH}`);
+                params.push(`%${escapeLike(q.city.trim())}%`);
+            }
+            if (q.state !== undefined && q.state.trim() !== '') {
+                where.push(`v.state ${LIKE_MATCH}`);
+                params.push(`%${escapeLike(q.state.trim())}%`);
+            }
+            const radius = q.radius_m ?? DEFAULT_VISIT_RADIUS_M;
+            if (hasGeo) {
+                // Bounding-box prefilter; the exact great-circle check runs below.
+                const dLat = radius / 111_320;
+                const dLng = radius / (111_320 * Math.max(0.01, Math.cos((q.lat * Math.PI) / 180)));
+                where.push('v.lat BETWEEN ? AND ? AND v.lng BETWEEN ? AND ?');
+                params.push(q.lat - dLat, q.lat + dLat, q.lng - dLng, q.lng + dLng);
+            }
+            const rows = this.db.all(`${select}${where.length ? ` AND ${where.join(' AND ')}` : ''}`, params);
+            for (const r of rows) {
+                const v = visitedFrom(r);
+                if (hasName && !nameMatches(q.name.trim(), tokens, v.name))
+                    continue;
+                if (hasGeo) {
+                    if (v.lat === null || v.lng === null)
+                        continue;
+                    const d = haversineM(q.lat, q.lng, v.lat, v.lng);
+                    if (d > radius)
+                        continue;
+                    v.distance_m = Math.round(d);
+                }
+                const prior = found.get(v.venue_id);
+                found.set(v.venue_id, prior && v.distance_m === undefined ? prior : v);
+            }
+        }
+        return [...found.values()].sort((a, b) => (b.total_count ?? 0) - (a.total_count ?? 0) || (b.recent_visit ?? '').localeCompare(a.recent_visit ?? '') || a.venue_id - b.venue_id);
+    }
     /** Distinct bids appearing in the checkins table. */
     checkinsBeerCount(username) {
         const row = this.db.get('SELECT COUNT(DISTINCT bid) AS n FROM checkins WHERE username = ? AND bid IS NOT NULL', [username.toLowerCase()]);
@@ -312,6 +881,11 @@ export class CheckinStoreCore {
      * merge could not do that.
      */
     setState(username, patch) {
+        // Read-merge-write in one write transaction, so a second process's patch
+        // can't land between the read and the write and be silently reverted.
+        this.db.transaction(() => this.mergeState(username, patch));
+    }
+    mergeState(username, patch) {
         const key = username.toLowerCase();
         const cur = this.getState(key);
         const pick = (k, fallback) => k in patch ? patch[k] : (cur?.[k] ?? fallback);
@@ -421,6 +995,46 @@ export class CheckinStoreCore {
             matches,
         };
     }
+    /**
+     * {@link hasHad} for many bids at once, in two grouped queries per chunk
+     * instead of ~4 per bid. Same merge rules: a hit in either source counts,
+     * `count` prefers user/beers' authoritative had_count, dates and ratings take
+     * the max across both. No per-check-in `matches` — callers of the batch form
+     * only want the verdict. Every requested bid gets an entry.
+     */
+    hasHadMany(username, bids) {
+        const key = username.toLowerCase();
+        const out = new Map();
+        const unique = [...new Set(bids)];
+        for (const bid of unique)
+            out.set(bid, { had: false, count: 0, last_date: null, best_rating: null, sources: [] });
+        for (const part of chunks(unique)) {
+            const ph = part.map(() => '?').join(', ');
+            for (const r of this.db.all(`SELECT bid, COUNT(*) AS c, MAX(rating) AS best, MAX(created_at) AS last
+         FROM checkins WHERE username = ? AND bid IN (${ph}) GROUP BY bid`, [key, ...part])) {
+                const v = out.get(Number(r.bid));
+                v.had = true;
+                v.count = Number(r.c);
+                v.best_rating = num(r.best);
+                v.last_date = str(r.last);
+                v.sources.push('checkins');
+            }
+            for (const r of this.db.all(`SELECT bid, had_count, rating, last_had, first_had FROM distinct_beers WHERE username = ? AND bid IN (${ph})`, [key, ...part])) {
+                const v = out.get(Number(r.bid));
+                v.had = true;
+                // Prefer the user/beers count; else keep the check-in-derived count; else 1.
+                v.count = num(r.had_count) ?? (v.count || 1);
+                const rating = num(r.rating);
+                if (rating !== null && (v.best_rating === null || rating > v.best_rating))
+                    v.best_rating = rating;
+                const last = str(r.last_had) ?? str(r.first_had);
+                if (last && (v.last_date === null || last > v.last_date))
+                    v.last_date = last;
+                v.sources.push('beers');
+            }
+        }
+        return out;
+    }
     query(username, filters) {
         const where = ['username = ?'];
         const params = [username.toLowerCase()];
@@ -466,22 +1080,635 @@ export class CheckinStoreCore {
         const limit = Math.min(Math.max(filters.limit ?? 25, 1), 200);
         return this.db.all(`SELECT * FROM checkins WHERE ${where.join(' AND ')} ORDER BY ${order} LIMIT ?`, [...params, limit]);
     }
-    /** Delete one user's cached rows (case-insensitive) in a single transaction. */
+    /**
+     * Delete one user's cached rows (case-insensitive) from every per-user table
+     * in a single transaction. Shared tables (beer_meta, venues, brewery lists,
+     * response cache, the API call log) hold no personal history and are kept.
+     */
     forgetUser(username) {
         const key = username.toLowerCase();
-        const count = (table) => Number(this.db.get(`SELECT COUNT(*) AS n FROM ${table} WHERE username = ?`, [key])?.n ?? 0);
-        const removed = {
-            checkins: count('checkins'),
-            distinct_beers: count('distinct_beers'),
-            sync_state: count('sync_state'),
+        const removed = {};
+        this.db.transaction(() => {
+            for (const table of PER_USER_TABLES) {
+                removed[table] = Number(this.db.get(`SELECT COUNT(*) AS n FROM ${table} WHERE username = ?`, [key])?.n ?? 0);
+                this.db.run(`DELETE FROM ${table} WHERE username = ?`, [key]);
+            }
+        });
+        return removed;
+    }
+    /** Append API call observations to the shared log, pruning entries past retention. */
+    recordApiCalls(rows) {
+        if (rows.length === 0)
+            return;
+        this.db.transaction(() => {
+            for (const r of rows) {
+                this.db.run('INSERT INTO api_calls (at, status, remaining, limit_hdr, reset_at, retry_after_s) VALUES (?, ?, ?, ?, ?, ?)', [r.at, r.status, r.remaining, r.limit, r.reset_at, r.retry_after_s]);
+            }
+            this.db.run('DELETE FROM api_calls WHERE at < ?', [Date.now() - API_CALL_LOG_RETENTION_MS]);
+        });
+    }
+    /** Logged API calls at or after `sinceMs`, oldest first. */
+    recentApiCalls(sinceMs) {
+        return this.db
+            .all('SELECT * FROM api_calls WHERE at >= ? ORDER BY at, rowid', [sinceMs])
+            .map((r) => ({
+            at: Number(r.at),
+            status: Number(r.status),
+            remaining: num(r.remaining),
+            limit: num(r.limit_hdr),
+            reset_at: num(r.reset_at),
+            retry_after_s: num(r.retry_after_s),
+        }));
+    }
+    getDistinctBeers(username, bids) {
+        if (bids.length === 0)
+            return [];
+        const placeholders = bids.map(() => '?').join(', ');
+        return this.db.all(`SELECT * FROM distinct_beers WHERE username = ? AND bid IN (${placeholders})`, [username.toLowerCase(), ...bids]);
+    }
+    getResolutions(keys) {
+        if (keys.length === 0)
+            return [];
+        const placeholders = keys.map(() => '?').join(', ');
+        return this.db.all(`SELECT * FROM item_resolutions WHERE key IN (${placeholders})`, keys);
+    }
+    upsertResolutions(rows) {
+        if (rows.length === 0)
+            return;
+        const sql = `
+      INSERT INTO item_resolutions (key, item, status, bid, data, resolved_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(key) DO UPDATE SET
+        item=excluded.item, status=excluded.status, bid=excluded.bid,
+        data=excluded.data, resolved_at=excluded.resolved_at`;
+        this.db.transaction(() => {
+            for (const r of rows)
+                this.db.run(sql, [r.key, r.item, r.status, r.bid, r.data, r.resolved_at]);
+        });
+    }
+    stats() {
+        const n = (sql) => Number(this.db.get(sql, [])?.n ?? 0);
+        const names = this.db
+            .all(`SELECT username FROM sync_state
+         UNION SELECT DISTINCT username FROM distinct_beers
+         UNION SELECT DISTINCT username FROM checkins
+         UNION SELECT DISTINCT username FROM user_venues
+         UNION SELECT username FROM list_sync_state WHERE list IN ('venues', 'wishlist', 'brewery_likes')
+         UNION SELECT DISTINCT username FROM wishlist
+         UNION SELECT DISTINCT username FROM brewery_likes
+         ORDER BY username`, [])
+            .map((r) => String(r.username));
+        const users = names.map((username) => {
+            const st = this.getState(username);
+            return {
+                username,
+                cached_distinct_beers: this.distinctBeersCount(username),
+                total_distinct_beers: st?.beers_total ?? null,
+                cached_checkins: this.cachedCount(username),
+                coverage_complete: (st?.beers_complete ?? false) || (st?.backfill_complete ?? false),
+                beers_offset: st?.beers_offset ?? null,
+                last_synced_at: st?.last_synced_at ?? null,
+                venues: this.venueCoverage(username),
+                wishlist: this.wishlistCoverage(username),
+                brewery_likes: this.breweryLikesCoverage(username),
+            };
+        });
+        return {
+            schema_version: this.version,
+            users,
+            resolution_cache_entries: n('SELECT COUNT(*) AS n FROM item_resolutions'),
+            beer_meta_entries: n('SELECT COUNT(*) AS n FROM beer_meta'),
+            venue_entries: n('SELECT COUNT(*) AS n FROM venues'),
+            brewery_lists: n('SELECT COUNT(*) AS n FROM brewery_beer_lists'),
+            response_cache_entries: n('SELECT COUNT(*) AS n FROM response_cache'),
         };
+    }
+    /** The user's user/venues coverage, or null if their venue history was never synced. */
+    venueCoverage(username) {
+        // Literal keys: VENUES_LIST / VENUES_REFRESH_LIST in sync-venues.ts.
+        const st = this.getListState(username, 'venues');
+        const cached = this.userVenuesCount(username);
+        if (!st && cached === 0)
+            return null;
+        const refresh = this.getListState(username, 'venues_refresh');
+        const refreshing = (st?.complete ?? false) && !!refresh && !refresh.complete;
+        const total = st?.total_count ?? null;
+        const complete = (st?.complete ?? false) && !refreshing;
+        return {
+            cached_venues: cached,
+            total_venues: total,
+            complete,
+            refresh_in_progress: refreshing,
+            percent: total && total > 0 ? Math.min(100, Math.round((cached / total) * 100)) : complete ? 100 : null,
+            next_offset: refreshing ? refresh.next_offset : (st?.next_offset ?? null),
+            last_synced_at: st?.last_synced_at ?? null,
+        };
+    }
+    getBreweryBeerList(breweryId) {
+        const h = this.db.get('SELECT * FROM brewery_beer_lists WHERE brewery_id = ?', [breweryId]);
+        if (!h)
+            return undefined;
+        const beers = this.db
+            .all(`SELECT * FROM brewery_beers WHERE brewery_id = ?
+         ORDER BY popularity_rank IS NULL, popularity_rank, checkin_count IS NULL, checkin_count DESC, bid`, [breweryId])
+            .map((r) => ({
+            brewery_id: Number(r.brewery_id),
+            bid: Number(r.bid),
+            beer_name: str(r.beer_name),
+            style: str(r.style),
+            abv: num(r.abv),
+            ibu: num(r.ibu),
+            rating_score: num(r.rating_score),
+            rating_count: num(r.rating_count),
+            checkin_count: num(r.checkin_count),
+            in_production: r.in_production === null || r.in_production === undefined ? null : Number(r.in_production) !== 0,
+            popularity_rank: num(r.popularity_rank),
+            fetched_at: String(r.fetched_at),
+        }));
+        return {
+            brewery_id: breweryId,
+            brewery_name: str(h.brewery_name),
+            total_count: num(h.total_count),
+            ranked_count: Number(h.ranked_count ?? 0),
+            fetched_at: String(h.fetched_at),
+            beers,
+        };
+    }
+    /**
+     * Store one brewery/beer_list page in one transaction. `restart` (a stale or
+     * refreshed list) drops the old rows and restarts the TTL clock; otherwise the
+     * page is merged into the current snapshot, which keeps its fetched_at. A page
+     * fetched in popularity order at an offset inside the ranked prefix extends it.
+     */
+    saveBreweryBeerPage(page) {
         this.db.transaction(() => {
-            this.db.run('DELETE FROM checkins WHERE username = ?', [key]);
-            this.db.run('DELETE FROM distinct_beers WHERE username = ?', [key]);
-            this.db.run('DELETE FROM sync_state WHERE username = ?', [key]);
+            const cur = this.db.get('SELECT * FROM brewery_beer_lists WHERE brewery_id = ?', [page.brewery_id]);
+            const fresh = page.restart || !cur;
+            if (page.restart)
+                this.db.run('DELETE FROM brewery_beers WHERE brewery_id = ?', [page.brewery_id]);
+            let ranked = fresh ? 0 : Number(cur.ranked_count ?? 0);
+            if (page.ranked_offset !== null && page.ranked_offset <= ranked) {
+                ranked = Math.max(ranked, page.ranked_offset + page.item_count);
+            }
+            this.db.run(`INSERT INTO brewery_beer_lists (brewery_id, brewery_name, total_count, ranked_count, fetched_at)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(brewery_id) DO UPDATE SET
+           brewery_name = COALESCE(excluded.brewery_name, brewery_beer_lists.brewery_name),
+           total_count = COALESCE(excluded.total_count, brewery_beer_lists.total_count),
+           ranked_count = excluded.ranked_count,
+           fetched_at = excluded.fetched_at`, [
+                page.brewery_id,
+                page.brewery_name,
+                page.total_count,
+                ranked,
+                fresh ? page.fetched_at : String(cur.fetched_at),
+            ]);
+            for (const r of page.rows) {
+                this.db.run(`INSERT INTO brewery_beers (brewery_id, bid, beer_name, style, abv, ibu, rating_score, rating_count,
+             checkin_count, in_production, popularity_rank, fetched_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(brewery_id, bid) DO UPDATE SET
+             beer_name = excluded.beer_name, style = excluded.style, abv = excluded.abv, ibu = excluded.ibu,
+             rating_score = excluded.rating_score, rating_count = excluded.rating_count,
+             checkin_count = excluded.checkin_count, in_production = excluded.in_production,
+             popularity_rank = COALESCE(excluded.popularity_rank, brewery_beers.popularity_rank),
+             fetched_at = excluded.fetched_at`, [
+                    r.brewery_id,
+                    r.bid,
+                    r.beer_name,
+                    r.style,
+                    r.abv,
+                    r.ibu,
+                    r.rating_score,
+                    r.rating_count,
+                    r.checkin_count,
+                    r.in_production === null ? null : r.in_production ? 1 : 0,
+                    r.popularity_rank,
+                    r.fetched_at,
+                ]);
+            }
+        });
+    }
+    getCachedResponse(key) {
+        const r = this.db.get('SELECT * FROM response_cache WHERE key = ?', [key]);
+        if (!r)
+            return undefined;
+        let data;
+        try {
+            data = JSON.parse(String(r.data));
+        }
+        catch {
+            return undefined;
+        }
+        return { key, kind: String(r.kind), data, fetched_at: String(r.fetched_at) };
+    }
+    putCachedResponse(key, kind, data, fetchedAt) {
+        this.db.transaction(() => {
+            this.db.run(`INSERT INTO response_cache (key, kind, data, fetched_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT(key) DO UPDATE SET kind = excluded.kind, data = excluded.data, fetched_at = excluded.fetched_at`, [key, kind, JSON.stringify(data ?? null), fetchedAt]);
+            // These responses hold other people's recent check-ins; keep them only
+            // as long as any TTL could still serve them.
+            const cutoff = new Date(Date.parse(fetchedAt) - RESPONSE_CACHE_RETENTION_MS).toISOString();
+            this.db.run('DELETE FROM response_cache WHERE fetched_at < ?', [cutoff]);
+        });
+    }
+    upsertWishlist(username, rows, passStamp) {
+        if (rows.length === 0)
+            return 0;
+        const key = username.toLowerCase();
+        let added = 0;
+        this.db.transaction(() => {
+            const bids = rows.map((r) => r.bid);
+            const known = new Set();
+            for (const c of chunks(bids)) {
+                for (const r of this.db.all(`SELECT bid FROM wishlist WHERE username = ? AND bid IN (${c.map(() => '?').join(', ')})`, [key, ...c])) {
+                    known.add(Number(r.bid));
+                }
+            }
+            for (const r of rows) {
+                if (!known.has(r.bid)) {
+                    added++;
+                    known.add(r.bid);
+                }
+                this.db.run(`INSERT INTO wishlist (username, bid, beer_name, brewery_id, brewery_name, style, abv, added_at, synced_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(username, bid) DO UPDATE SET
+             beer_name = excluded.beer_name, brewery_id = excluded.brewery_id, brewery_name = excluded.brewery_name,
+             style = excluded.style, abv = excluded.abv, added_at = excluded.added_at, synced_at = excluded.synced_at`, [key, r.bid, r.beer_name, r.brewery_id, r.brewery_name, r.style, r.abv, r.added_at, passStamp]);
+            }
+        });
+        return added;
+    }
+    pruneWishlist(username, passStamp) {
+        let removed = 0;
+        this.db.transaction(() => {
+            const key = username.toLowerCase();
+            removed = Number(this.db.get('SELECT COUNT(*) AS n FROM wishlist WHERE username = ? AND synced_at <> ?', [key, passStamp])?.n ?? 0);
+            this.db.run('DELETE FROM wishlist WHERE username = ? AND synced_at <> ?', [key, passStamp]);
+        });
+        return removed;
+    }
+    wishlistCount(username) {
+        return Number(this.db.get('SELECT COUNT(*) AS n FROM wishlist WHERE username = ?', [username.toLowerCase()])?.n ?? 0);
+    }
+    getWishlist(username, bids) {
+        const key = username.toLowerCase();
+        const map = (r) => ({
+            bid: Number(r.bid),
+            beer_name: str(r.beer_name),
+            brewery_id: num(r.brewery_id),
+            brewery_name: str(r.brewery_name),
+            style: str(r.style),
+            abv: num(r.abv),
+            added_at: str(r.added_at),
+        });
+        if (bids === undefined) {
+            return this.db.all('SELECT * FROM wishlist WHERE username = ? ORDER BY added_at DESC, bid', [key]).map(map);
+        }
+        const out = [];
+        for (const c of chunks(bids)) {
+            if (c.length === 0)
+                continue;
+            out.push(...this.db
+                .all(`SELECT * FROM wishlist WHERE username = ? AND bid IN (${c.map(() => '?').join(', ')})`, [key, ...c])
+                .map(map));
+        }
+        return out;
+    }
+    /** The user's wishlist mirror coverage, or null if it was never synced. */
+    wishlistCoverage(username) {
+        // Literal key: WISHLIST_LIST in sync-wishlist.ts.
+        const st = this.getListState(username, 'wishlist');
+        const cached = this.wishlistCount(username);
+        if (!st && cached === 0)
+            return null;
+        return {
+            cached,
+            total: st?.total_count ?? null,
+            complete: st?.complete ?? false,
+            next_offset: st?.next_offset ?? null,
+            last_synced_at: st?.last_synced_at ?? null,
+        };
+    }
+    upsertBreweryLikes(username, rows, passStamp) {
+        if (rows.length === 0)
+            return 0;
+        const key = username.toLowerCase();
+        let added = 0;
+        this.db.transaction(() => {
+            const known = new Set();
+            for (const c of chunks(rows.map((r) => r.brewery_id))) {
+                for (const r of this.db.all(`SELECT brewery_id FROM brewery_likes WHERE username = ? AND brewery_id IN (${c.map(() => '?').join(', ')})`, [key, ...c])) {
+                    known.add(Number(r.brewery_id));
+                }
+            }
+            for (const r of rows) {
+                if (!known.has(r.brewery_id)) {
+                    added++;
+                    known.add(r.brewery_id);
+                }
+                this.db.run(`INSERT INTO brewery_likes (username, brewery_id, brewery_name, brewery_type, country, city, state, lat, lng, liked_at, synced_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(username, brewery_id) DO UPDATE SET
+             brewery_name = excluded.brewery_name, brewery_type = excluded.brewery_type, country = excluded.country,
+             city = excluded.city, state = excluded.state, lat = excluded.lat, lng = excluded.lng,
+             liked_at = excluded.liked_at, synced_at = excluded.synced_at`, [key, r.brewery_id, r.brewery_name, r.brewery_type, r.country, r.city, r.state, r.lat, r.lng, r.liked_at, passStamp]);
+            }
+        });
+        return added;
+    }
+    pruneBreweryLikes(username, passStamp) {
+        let removed = 0;
+        this.db.transaction(() => {
+            const key = username.toLowerCase();
+            removed = Number(this.db.get('SELECT COUNT(*) AS n FROM brewery_likes WHERE username = ? AND synced_at <> ?', [key, passStamp])?.n ?? 0);
+            this.db.run('DELETE FROM brewery_likes WHERE username = ? AND synced_at <> ?', [key, passStamp]);
+        });
+        return removed;
+    }
+    breweryLikesCount(username) {
+        return Number(this.db.get('SELECT COUNT(*) AS n FROM brewery_likes WHERE username = ?', [username.toLowerCase()])?.n ?? 0);
+    }
+    getBreweryLikes(username, breweryIds) {
+        const key = username.toLowerCase();
+        const map = (r) => ({
+            brewery_id: Number(r.brewery_id),
+            brewery_name: str(r.brewery_name),
+            brewery_type: str(r.brewery_type),
+            country: str(r.country),
+            city: str(r.city),
+            state: str(r.state),
+            lat: num(r.lat),
+            lng: num(r.lng),
+            liked_at: str(r.liked_at),
+        });
+        const order = 'ORDER BY liked_at IS NULL, liked_at DESC, brewery_id';
+        if (breweryIds === undefined) {
+            return this.db.all(`SELECT * FROM brewery_likes WHERE username = ? ${order}`, [key]).map(map);
+        }
+        const out = [];
+        for (const c of chunks(breweryIds)) {
+            if (c.length === 0)
+                continue;
+            out.push(...this.db
+                .all(`SELECT * FROM brewery_likes WHERE username = ? AND brewery_id IN (${c.map(() => '?').join(', ')}) ${order}`, [key, ...c])
+                .map(map));
+        }
+        return out;
+    }
+    /** The user's Untappd brewery-likes coverage, or null if it was never synced. */
+    breweryLikesCoverage(username) {
+        // Literal key: BREWERY_LIKES_LIST in sync-brewery-likes.ts.
+        const st = this.getListState(username, 'brewery_likes');
+        const cached = this.breweryLikesCount(username);
+        if (!st && cached === 0)
+            return null;
+        const total = st?.total_count ?? null;
+        const complete = st?.complete ?? false;
+        return {
+            cached,
+            total,
+            complete,
+            percent: total && total > 0 ? Math.min(100, Math.round((cached / total) * 100)) : complete ? 100 : null,
+            next_offset: st?.next_offset ?? null,
+            last_synced_at: st?.last_synced_at ?? null,
+        };
+    }
+    venueDrinkCandidates(username, opts = {}) {
+        const key = username.toLowerCase();
+        const which = opts.which ?? 'both';
+        const venueFilter = (ids) => (ids.length ? ` AND u.venue_id IN (${ids.map(() => '?').join(', ')})` : '');
+        const parts = [];
+        if (which !== 'recent')
+            parts.push({ col: 'first_checkin_id', kind: 'first' });
+        if (which !== 'first')
+            parts.push({ col: 'recent_checkin_id', kind: 'recent' });
+        const idSets = opts.venueIds && opts.venueIds.length > 0 ? chunks([...new Set(opts.venueIds)]) : [[]];
+        const rows = [];
+        for (const ids of idSets) {
+            for (const { col, kind } of parts) {
+                rows.push(...this.db
+                    .all(`SELECT u.venue_id AS venue_id, u.${col} AS checkin_id, u.total_count AS total_count, u.recent_visit AS recent_visit
+               FROM user_venues u
+               WHERE u.username = ? AND u.${col} IS NOT NULL${venueFilter(ids)}
+                 AND NOT EXISTS (SELECT 1 FROM venue_drinks d WHERE d.username = u.username AND d.checkin_id = u.${col})`, [key, ...ids])
+                    .map((r) => ({ ...r, kind })));
+            }
+        }
+        rows.sort((a, b) => Number(b.total_count ?? 0) - Number(a.total_count ?? 0) ||
+            String(b.recent_visit ?? '').localeCompare(String(a.recent_visit ?? '')) ||
+            Number(a.venue_id) - Number(b.venue_id) ||
+            (a.kind === b.kind ? 0 : a.kind === 'first' ? -1 : 1));
+        const seen = new Set();
+        const out = [];
+        for (const r of rows) {
+            const id = Number(r.checkin_id);
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            out.push({ venue_id: Number(r.venue_id), checkin_id: id, kind: r.kind });
+        }
+        return out;
+    }
+    upsertVenueDrinks(username, rows, fetchedAt) {
+        if (rows.length === 0)
+            return;
+        const key = username.toLowerCase();
+        const sql = `
+      INSERT INTO venue_drinks (username, venue_id, checkin_id, bid, beer_name, brewery_id, brewery_name, created_at, fetched_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(username, checkin_id) DO UPDATE SET
+        venue_id=excluded.venue_id, bid=excluded.bid, beer_name=excluded.beer_name, brewery_id=excluded.brewery_id,
+        brewery_name=excluded.brewery_name, created_at=excluded.created_at, fetched_at=excluded.fetched_at`;
+        this.db.transaction(() => {
+            for (const r of rows) {
+                this.db.run(sql, [key, r.venue_id, r.checkin_id, r.bid, r.beer_name, r.brewery_id, r.brewery_name, r.created_at, fetchedAt]);
+            }
+        });
+    }
+    getVenueDrinks(username, venueIds) {
+        const key = username.toLowerCase();
+        const out = [];
+        for (const ids of chunks([...new Set(venueIds)])) {
+            if (ids.length === 0)
+                continue;
+            const rows = this.db.all(`SELECT venue_id, checkin_id, bid, beer_name, brewery_id, brewery_name, created_at FROM venue_drinks
+         WHERE username = ? AND venue_id IN (${ids.map(() => '?').join(', ')})
+           AND NOT (bid IS NULL AND beer_name IS NULL)`, [key, ...ids]);
+            for (const r of rows) {
+                out.push({
+                    venue_id: Number(r.venue_id),
+                    checkin_id: Number(r.checkin_id),
+                    bid: num(r.bid),
+                    beer_name: str(r.beer_name),
+                    brewery_id: num(r.brewery_id),
+                    brewery_name: str(r.brewery_name),
+                    created_at: str(r.created_at),
+                });
+            }
+        }
+        return out.sort((a, b) => String(b.created_at ?? '').localeCompare(String(a.created_at ?? '')) || b.checkin_id - a.checkin_id);
+    }
+    addFavorite(username, kind, id, note, createdAt) {
+        const key = username.toLowerCase();
+        let out = { added: false, note: null, created_at: createdAt };
+        this.db.transaction(() => {
+            const cur = this.db.get('SELECT note, created_at FROM favorites WHERE username = ? AND kind = ? AND id = ?', [key, kind, id]);
+            if (!cur) {
+                const n = note ?? null;
+                this.db.run('INSERT INTO favorites (username, kind, id, note, created_at) VALUES (?, ?, ?, ?, ?)', [key, kind, id, n, createdAt]);
+                out = { added: true, note: n, created_at: createdAt };
+                return;
+            }
+            const n = note === undefined ? str(cur.note) : note;
+            this.db.run('UPDATE favorites SET note = ? WHERE username = ? AND kind = ? AND id = ?', [n, key, kind, id]);
+            out = { added: false, note: n, created_at: String(cur.created_at) };
+        });
+        return out;
+    }
+    removeFavorite(username, kind, id) {
+        let removed = false;
+        this.db.transaction(() => {
+            const key = username.toLowerCase();
+            removed = !!this.db.get('SELECT 1 AS x FROM favorites WHERE username = ? AND kind = ? AND id = ?', [key, kind, id]);
+            if (removed)
+                this.db.run('DELETE FROM favorites WHERE username = ? AND kind = ? AND id = ?', [key, kind, id]);
         });
         return removed;
     }
+    getManualFavorites(username, opts = {}) {
+        const key = username.toLowerCase();
+        // Best-effort display name from whatever the cache already holds.
+        const nameSql = `CASE f.kind
+        WHEN 'beer' THEN COALESCE(
+          (SELECT beer_name FROM distinct_beers d WHERE d.username = f.username AND d.bid = f.id),
+          (SELECT name FROM beer_meta m WHERE m.bid = f.id),
+          (SELECT beer_name FROM checkins c WHERE c.username = f.username AND c.bid = f.id LIMIT 1),
+          (SELECT beer_name FROM wishlist w WHERE w.username = f.username AND w.bid = f.id))
+        WHEN 'brewery' THEN COALESCE(
+          (SELECT brewery_name FROM brewery_beer_lists l WHERE l.brewery_id = f.id),
+          (SELECT brewery_name FROM distinct_beers d WHERE d.username = f.username AND d.brewery_id = f.id LIMIT 1),
+          (SELECT brewery FROM beer_meta m WHERE m.brewery_id = f.id LIMIT 1),
+          (SELECT brewery_name FROM checkins c WHERE c.username = f.username AND c.brewery_id = f.id LIMIT 1))
+        ELSE (SELECT name FROM venues v WHERE v.venue_id = f.id) END`;
+        const where = ['f.username = ?'];
+        const params = [key];
+        if (opts.kind) {
+            where.push('f.kind = ?');
+            params.push(opts.kind);
+        }
+        const run = (extra, extraParams) => this.db
+            .all(`SELECT f.kind AS kind, f.id AS id, f.note AS note, f.created_at AS created_at, ${nameSql} AS name
+           FROM favorites f WHERE ${[...where, ...(extra ? [extra] : [])].join(' AND ')}`, [...params, ...extraParams])
+            .map((r) => ({
+            kind: String(r.kind),
+            id: Number(r.id),
+            note: str(r.note),
+            created_at: String(r.created_at),
+            name: str(r.name),
+        }));
+        let rows;
+        if (opts.ids === undefined)
+            rows = run('', []);
+        else {
+            rows = [];
+            for (const c of chunks([...new Set(opts.ids)])) {
+                if (c.length)
+                    rows.push(...run(`f.id IN (${c.map(() => '?').join(', ')})`, c));
+            }
+        }
+        return rows.sort((a, b) => b.created_at.localeCompare(a.created_at) || a.kind.localeCompare(b.kind) || a.id - b.id);
+    }
+    /**
+     * One row per distinct beer the user has had, from BOTH sources: user/beers
+     * (rating = the user's rating, times = had_count) and check-ins for beers
+     * user/beers doesn't hold. `best` is the max rating across both (as
+     * hasHadMany), `avg_basis` the rating used for brewery averages.
+     */
+    perBeerSql(bidFilter) {
+        return `WITH c AS (
+        SELECT bid, COUNT(*) AS n, MAX(NULLIF(rating, 0)) AS best, AVG(NULLIF(rating, 0)) AS avg_r,
+               MAX(beer_name) AS beer_name, MAX(brewery_id) AS brewery_id, MAX(brewery_name) AS brewery_name
+        FROM checkins WHERE username = ? AND bid IS NOT NULL${bidFilter} GROUP BY bid),
+      d AS (
+        SELECT bid, had_count, NULLIF(rating, 0) AS rating, beer_name, brewery_id, brewery_name
+        FROM distinct_beers WHERE username = ?${bidFilter}),
+      ids AS (SELECT bid FROM c UNION SELECT bid FROM d)
+      SELECT ids.bid AS bid,
+             COALESCE(d.beer_name, c.beer_name) AS beer_name,
+             COALESCE(d.brewery_id, c.brewery_id) AS brewery_id,
+             COALESCE(d.brewery_name, c.brewery_name) AS brewery_name,
+             CASE WHEN d.rating IS NULL THEN c.best WHEN c.best IS NULL THEN d.rating
+                  WHEN d.rating > c.best THEN d.rating ELSE c.best END AS best,
+             COALESCE(d.rating, c.avg_r) AS avg_basis,
+             COALESCE(d.had_count, c.n, 1) AS times_had
+      FROM ids LEFT JOIN d ON d.bid = ids.bid LEFT JOIN c ON c.bid = ids.bid`;
+    }
+    breweryHadStats(username, breweryIds) {
+        const key = username.toLowerCase();
+        const sql = (filter) => `SELECT brewery_id, MAX(brewery_name) AS brewery_name, COUNT(*) AS beers, COUNT(avg_basis) AS rated,
+              AVG(avg_basis) AS avg_rating
+       FROM (${this.perBeerSql('')}) WHERE brewery_id IS NOT NULL${filter} GROUP BY brewery_id`;
+        const map = (r) => ({
+            brewery_id: Number(r.brewery_id),
+            brewery_name: str(r.brewery_name),
+            beers: Number(r.beers),
+            rated_beers: Number(r.rated),
+            avg_rating: num(r.avg_rating),
+        });
+        if (breweryIds === undefined)
+            return this.db.all(sql(''), [key, key]).map(map);
+        const out = [];
+        for (const c of chunks([...new Set(breweryIds)])) {
+            if (c.length)
+                out.push(...this.db.all(sql(` AND brewery_id IN (${c.map(() => '?').join(', ')})`), [key, key, ...c]).map(map));
+        }
+        return out;
+    }
+    beerHadStats(username, opts) {
+        const key = username.toLowerCase();
+        const map = (r) => ({
+            bid: Number(r.bid),
+            beer_name: str(r.beer_name),
+            brewery_id: num(r.brewery_id),
+            brewery_name: str(r.brewery_name),
+            rating: num(r.best),
+            times_had: Number(r.times_had),
+        });
+        if (opts.bids !== undefined) {
+            const out = [];
+            for (const c of chunks([...new Set(opts.bids)])) {
+                if (c.length === 0)
+                    continue;
+                const f = ` AND bid IN (${c.map(() => '?').join(', ')})`;
+                out.push(...this.db.all(this.perBeerSql(f), [key, ...c, key, ...c]).map(map));
+            }
+            return out;
+        }
+        return this.db
+            .all(`SELECT * FROM (${this.perBeerSql('')}) WHERE best >= ? OR times_had >= ?`, [
+            key,
+            key,
+            opts.minRating ?? Number.MAX_VALUE,
+            opts.minTimesHad ?? Number.MAX_SAFE_INTEGER,
+        ])
+            .map(map);
+    }
+    venueVisitStats(username, opts) {
+        const key = username.toLowerCase();
+        const base = `SELECT u.*, v.name, v.category, v.address, v.city, v.state, v.country, v.lat, v.lng, v.is_verified
+       FROM user_venues u LEFT JOIN venues v ON v.venue_id = u.venue_id
+       WHERE u.username = ? AND COALESCE(u.total_count, 0) >= ?`;
+        const min = opts.minCheckins ?? 0;
+        if (opts.venueIds === undefined)
+            return this.db.all(base, [key, min]).map(visitedFrom);
+        const out = [];
+        for (const c of chunks([...new Set(opts.venueIds)])) {
+            if (c.length)
+                out.push(...this.db.all(`${base} AND u.venue_id IN (${c.map(() => '?').join(', ')})`, [key, min, ...c]).map(visitedFrom));
+        }
+        return out;
+    }
     getBeerMeta(bids) {
         if (bids.length === 0)
             return [];
@@ -547,6 +1774,9 @@ export class LocalCacheStore {
     async hasHad(username, opts) {
         return this.core.hasHad(username, opts);
     }
+    async hasHadMany(username, bids) {
+        return this.core.hasHadMany(username, bids);
+    }
     async query(username, filters) {
         return this.core.query(username, filters);
     }
@@ -559,6 +1789,120 @@ export class LocalCacheStore {
     async forgetUser(username) {
         return this.core.forgetUser(username);
     }
+    async getDistinctBeers(username, bids) {
+        return this.core.getDistinctBeers(username, bids);
+    }
+    async getResolutions(keys) {
+        return this.core.getResolutions(keys);
+    }
+    async upsertResolutions(rows) {
+        this.core.upsertResolutions(rows);
+    }
+    async stats() {
+        return this.core.stats();
+    }
+    async upsertUserVenues(username, items) {
+        return this.core.upsertUserVenues(username, items);
+    }
+    async getUserVenueVisits(username, venueIds) {
+        return this.core.getUserVenueVisits(username, venueIds);
+    }
+    async userVenuesCount(username) {
+        return this.core.userVenuesCount(username);
+    }
+    async getVenues(venueIds) {
+        return this.core.getVenues(venueIds);
+    }
+    async getListState(username, list) {
+        return this.core.getListState(username, list);
+    }
+    async setListState(username, list, patch) {
+        this.core.setListState(username, list, patch);
+    }
+    async findVisitedVenues(username, q) {
+        return this.core.findVisitedVenues(username, q);
+    }
+    async getBreweryBeerList(breweryId) {
+        return this.core.getBreweryBeerList(breweryId);
+    }
+    async saveBreweryBeerPage(page) {
+        this.core.saveBreweryBeerPage(page);
+    }
+    async getCachedResponse(key) {
+        return this.core.getCachedResponse(key);
+    }
+    async putCachedResponse(key, kind, data, fetchedAt) {
+        this.core.putCachedResponse(key, kind, data, fetchedAt);
+    }
+    async upsertWishlist(username, rows, passStamp) {
+        return this.core.upsertWishlist(username, rows, passStamp);
+    }
+    async pruneWishlist(username, passStamp) {
+        return this.core.pruneWishlist(username, passStamp);
+    }
+    async wishlistCount(username) {
+        return this.core.wishlistCount(username);
+    }
+    async getWishlist(username, bids) {
+        return this.core.getWishlist(username, bids);
+    }
+    async upsertBreweryLikes(username, rows, passStamp) {
+        return this.core.upsertBreweryLikes(username, rows, passStamp);
+    }
+    async pruneBreweryLikes(username, passStamp) {
+        return this.core.pruneBreweryLikes(username, passStamp);
+    }
+    async breweryLikesCount(username) {
+        return this.core.breweryLikesCount(username);
+    }
+    async getBreweryLikes(username, breweryIds) {
+        return this.core.getBreweryLikes(username, breweryIds);
+    }
+    async breweryLikesCoverage(username) {
+        return this.core.breweryLikesCoverage(username);
+    }
+    async venueDrinkCandidates(username, opts) {
+        return this.core.venueDrinkCandidates(username, opts);
+    }
+    async upsertVenueDrinks(username, rows, fetchedAt) {
+        this.core.upsertVenueDrinks(username, rows, fetchedAt);
+    }
+    async getVenueDrinks(username, venueIds) {
+        return this.core.getVenueDrinks(username, venueIds);
+    }
+    async addFavorite(username, kind, id, note, createdAt) {
+        return this.core.addFavorite(username, kind, id, note, createdAt);
+    }
+    async removeFavorite(username, kind, id) {
+        return this.core.removeFavorite(username, kind, id);
+    }
+    async getManualFavorites(username, opts) {
+        return this.core.getManualFavorites(username, opts);
+    }
+    async breweryHadStats(username, breweryIds) {
+        return this.core.breweryHadStats(username, breweryIds);
+    }
+    async beerHadStats(username, opts) {
+        return this.core.beerHadStats(username, opts);
+    }
+    async venueVisitStats(username, opts) {
+        return this.core.venueVisitStats(username, opts);
+    }
+    async recordApiCalls(rows) {
+        this.core.recordApiCalls(rows);
+    }
+    async recentApiCalls(sinceMs) {
+        return this.core.recentApiCalls(sinceMs);
+    }
+}
+// SQLite caps bound parameters per statement (999 on older builds); IN-lists
+// are split well under that.
+const IN_CHUNK = 500;
+function chunks(xs) {
+    const out = [];
+    for (let i = 0; i < xs.length; i += IN_CHUNK)
+        out.push(xs.slice(i, i + IN_CHUNK));
+    return out;
 }
 // Case-insensitive substring match whose pattern is built by escapeLike(): the
 // ESCAPE clause makes a backslash-prefixed %, _ or backslash match itself literally.
@@ -568,3 +1912,59 @@ const LIKE_MATCH = "LIKE ? COLLATE NOCASE ESCAPE '\\'";
 function escapeLike(s) {
     return s.replace(/[\\%_]/g, (c) => `\\${c}`);
 }
+function visitFrom(r) {
+    return {
+        venue_id: Number(r.venue_id),
+        first_visit: str(r.first_visit),
+        first_checkin_id: num(r.first_checkin_id),
+        recent_visit: str(r.recent_visit),
+        recent_checkin_id: num(r.recent_checkin_id),
+        total_count: num(r.total_count),
+    };
+}
+function visitedFrom(r) {
+    const name = str(r.name);
+    return {
+        name,
+        category: str(r.category),
+        address: str(r.address),
+        city: str(r.city),
+        state: str(r.state),
+        country: str(r.country),
+        lat: num(r.lat),
+        lng: num(r.lng),
+        is_verified: num(r.is_verified),
+        ...visitFrom(r),
+        is_duplicate: name !== null && /\(duplicate of\b/i.test(name),
+    };
+}
+// Words that don't distinguish one venue name from another ("Green Bench
+// Brewing Co." vs "Green Bench Brewing Company").
+const NAME_STOP_WORDS = new Set(['co', 'company', 'inc', 'llc', 'ltd', 'the', 'and']);
+/** Lowercased alphanumeric words of a name, minus {@link NAME_STOP_WORDS}. */
+function significantTokens(name) {
+    return wordsOf(name).filter((w) => !NAME_STOP_WORDS.has(w));
+}
+function wordsOf(s) {
+    return s.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((w) => w.length > 0);
+}
+/** See {@link CheckinStoreCore.findVisitedVenues}: literal substring, or every significant word whole. */
+function nameMatches(query, tokens, venueName) {
+    if (venueName === null)
+        return false;
+    if (venueName.toLowerCase().includes(query.toLowerCase()))
+        return true;
+    if (tokens.length === 0)
+        return false;
+    const words = new Set(wordsOf(venueName));
+    return tokens.every((t) => words.has(t));
+}
+/** Great-circle distance in metres. */
+export function haversineM(lat1, lng1, lat2, lng2) {
+    const R = 6_371_008.8;
+    const rad = Math.PI / 180;
+    const dLat = (lat2 - lat1) * rad;
+    const dLng = (lng2 - lng1) * rad;
+    const a = Math.sin(dLat / 2) ** 2 + Math.cos(lat1 * rad) * Math.cos(lat2 * rad) * Math.sin(dLng / 2) ** 2;
+    return 2 * R * Math.asin(Math.min(1, Math.sqrt(a)));
+}