Add hosted matchup commands

package-lock.json

@@ -11,6 +11,7 @@
         "chart.js": "^4.5.0",
         "discord.js": "^14.25.1",
         "dotenv": "^17.2.3",
+        "hyparquet": "^1.25.5",
         "pdfjs-dist": "^5.6.205",
         "pg": "^8.16.3",
         "skia-canvas": "^3.0.8",
@@ -867,6 +868,12 @@
         "node": ">= 14"
       }
     },
+    "node_modules/hyparquet": {
+      "version": "1.25.5",
+      "resolved": "https://registry.npmjs.org/hyparquet/-/hyparquet-1.25.5.tgz",
+      "integrity": "sha512-YHEmaVX9ctI4uGzCdXHCPu8tEu2TJmO0H9s59z2JSe3kkc/S0Ltm+zpbJRCCLQWNu1SaocFcGCPTT2vl52BnTg==",
+      "license": "MIT"
+    },
     "node_modules/idb-keyval": {
       "version": "6.2.2",
       "resolved": "https://registry.npmjs.org/idb-keyval/-/idb-keyval-6.2.2.tgz",

package.json

@@ -15,6 +15,7 @@
     "chart.js": "^4.5.0",
     "discord.js": "^14.25.1",
     "dotenv": "^17.2.3",
+    "hyparquet": "^1.25.5",
     "pdfjs-dist": "^5.6.205",
     "pg": "^8.16.3",
     "skia-canvas": "^3.0.8",

src/commands.js

@@ -158,6 +158,62 @@ function addMarketIntelligenceFilters(command, options = {}) {
   return command;
 }
 
+function addMatchupOptions(command, options = {}) {
+  if (options.includePlayer) {
+    command.addStringOption((option) =>
+      option
+        .setName('player')
+        .setDescription('Player name to look up.')
+        .setRequired(true)
+    );
+  }
+
+  if (options.includePlayerType) {
+    command.addStringOption((option) =>
+      option
+        .setName('player_type')
+        .setDescription('Optionally force hitter or pitcher context.')
+        .setRequired(false)
+        .addChoices(
+          { name: 'Auto', value: 'auto' },
+          { name: 'Hitter', value: 'hitter' },
+          { name: 'Pitcher', value: 'pitcher' }
+        )
+    );
+  }
+
+  if (options.includeTeam) {
+    command.addStringOption((option) =>
+      option
+        .setName('team')
+        .setDescription('Optional team filter, for example CHC or KCR.')
+        .setRequired(false)
+    );
+  }
+
+  if (options.includeDate !== false) {
+    command.addStringOption((option) =>
+      option
+        .setName('date')
+        .setDescription('Optional slate date in YYYY-MM-DD format. Defaults to the latest available slate.')
+        .setRequired(false)
+    );
+  }
+
+  if (options.includeLimit !== false) {
+    command.addIntegerOption((option) =>
+      option
+        .setName('limit')
+        .setDescription('Optional result limit.')
+        .setRequired(false)
+        .setMinValue(1)
+        .setMaxValue(15)
+    );
+  }
+
+  return command;
+}
+
 export const commands = [
   new SlashCommandBuilder()
     .setName('bet')
@@ -518,6 +574,33 @@ export const commands = [
       .setDescription('Show coverage and market quality by supported market.'),
     { includeMarket: true, includeLimit: true }
   ),
+  addMatchupOptions(
+    new SlashCommandBuilder()
+      .setName('matchuphitters')
+      .setDescription('Show the best hitter matchups from the hosted MLB artifact slate.'),
+    { includeTeam: true, includeDate: true, includeLimit: true }
+  ),
+  addMatchupOptions(
+    new SlashCommandBuilder()
+      .setName('matchuppitchers')
+      .setDescription('Show the best pitcher matchups from the hosted MLB artifact slate.'),
+    { includeTeam: true, includeDate: true, includeLimit: true }
+  ),
+  addMatchupOptions(
+    new SlashCommandBuilder()
+      .setName('playercontext')
+      .setDescription('Show matchup context for one hitter or pitcher.'),
+    { includePlayer: true, includePlayerType: true, includeDate: true, includeLimit: false }
+  ),
+  addMatchupOptions(
+    new SlashCommandBuilder()
+      .setName('bestmatchups')
+      .setDescription('Show a compact board of the best hitter matchups for the active slate.'),
+    { includeTeam: true, includeDate: true, includeLimit: true }
+  ),
+  new SlashCommandBuilder()
+    .setName('matchuphealth')
+    .setDescription('Show hosted artifact freshness and Cockroach fallback status for matchup data.'),
   new SlashCommandBuilder()
     .setName('alerts')
     .setDescription('Post the analyst alert-role embed to the welcome channel.'),

src/config.js

@@ -42,6 +42,9 @@ export function getConfig() {
   const circaTimeZone = process.env.CIRCA_TIMEZONE?.trim() || 'America/Chicago';
   const circaRetryMinutes = Number(process.env.CIRCA_RETRY_MINUTES || 30);
   const circaMovementFrequencyMinutes = Number(process.env.CIRCA_MOVEMENT_FREQUENCY_MINUTES || 5);
+  const matchupHostedBaseUrl = process.env.MLB_HOSTED_BASE_URL?.trim() || null;
+  const matchupArtifactCacheTtlMs = Number(process.env.MATCHUP_ARTIFACT_CACHE_TTL_MS || 300000);
+  const matchupFallbackDays = Number(process.env.MATCHUP_FALLBACK_DAYS || 7);
 
   if (!token) {
     throw new Error('Missing DISCORD_TOKEN in environment.');
@@ -57,6 +60,15 @@ export function getConfig() {
     databaseUrl,
     port,
     adminRoleName,
+    matchups: {
+      enabled: Boolean(matchupHostedBaseUrl || databaseUrl),
+      hosted: {
+        baseUrl: matchupHostedBaseUrl,
+        cacheTtlMs: matchupArtifactCacheTtlMs,
+        fallbackDays: matchupFallbackDays,
+      },
+      databaseUrl,
+    },
     scanner: {
       enabled: Boolean(
         circaDropboxUrl

src/embeds.js

@@ -922,6 +922,214 @@ export function buildCircaMovementEmbed(movement, snapshot) {
     .setFooter({ text: 'Posted only because this Circa prop moved from the prior seen snapshot.' });
 }
 
+export function buildMatchupHittersEmbed(result, filters = {}) {
+  const embed = new EmbedBuilder()
+    .setColor(PALETTE.primary)
+    .setTitle('Matchup Hitters')
+    .setDescription(
+      buildFilterBanner(
+        filters,
+        `Top hitter matchups from **${String(result.source ?? 'unknown').toUpperCase()}** for **${result.resolvedDate ?? 'unknown slate'}**.`
+      )
+    );
+
+  if (result.warning) {
+    embed.addFields({ name: 'Source Note', value: truncate(result.warning, 256), inline: false });
+  }
+
+  if (!result.rows?.length) {
+    return embed.addFields({ name: 'Board', value: 'No hitter matchup rows were available for that filter set.' });
+  }
+
+  embed.addFields(
+    result.rows.map((row, index) => ({
+      name: `${index + 1}. ${row.hitter_name ?? 'Unknown Hitter'}${row.team ? ` (${row.team})` : ''}`,
+      value: [
+        `Matchup: ${formatMetricNumber(row.matchup_score)} | Ceiling: ${formatMetricNumber(row.ceiling_score)} | Zone Fit: ${formatMetricNumber(row.zone_fit_score)}`,
+        `xwOBA: ${formatMetricDecimal(row.xwoba)} | Likely: ${formatMetricNumber(row.likely_starter_score)} | HH%: ${formatMetricPercent(row.hard_hit_pct)}`,
+        `Opponent: ${row.opponent_team ?? 'N/A'}${row.opposing_pitcher_name ? ` vs ${row.opposing_pitcher_name}` : ''}${row.opposing_pitcher_hand ? ` (${row.opposing_pitcher_hand})` : ''}`,
+      ].join('\n'),
+      inline: false,
+    }))
+  );
+
+  return embed;
+}
+
+export function buildMatchupPitchersEmbed(result, filters = {}) {
+  const embed = new EmbedBuilder()
+    .setColor(PALETTE.secondary)
+    .setTitle('Matchup Pitchers')
+    .setDescription(
+      buildFilterBanner(
+        filters,
+        `Top pitcher matchups from **${String(result.source ?? 'unknown').toUpperCase()}** for **${result.resolvedDate ?? 'unknown slate'}**.`
+      )
+    );
+
+  if (result.warning) {
+    embed.addFields({ name: 'Source Note', value: truncate(result.warning, 256), inline: false });
+  }
+
+  if (!result.rows?.length) {
+    return embed.addFields({ name: 'Board', value: 'No pitcher matchup rows were available for that filter set.' });
+  }
+
+  embed.addFields(
+    result.rows.map((row, index) => ({
+      name: `${index + 1}. ${row.pitcher_name ?? 'Unknown Pitcher'}${row.team ? ` (${row.team})` : ''}`,
+      value: [
+        `Pitch Score: ${formatMetricNumber(row.pitcher_score)} | Strikeout: ${formatMetricNumber(row.strikeout_score)} | Matchup Adj: ${formatMetricNumber(row.pitcher_matchup_adjustment)}`,
+        `xwOBA: ${formatMetricDecimal(row.xwoba)} | CSW%: ${formatMetricPercent(row.csw_pct)} | SwStr%: ${formatMetricPercent(row.swstr_pct)}`,
+        `Opponent: ${row.opponent_team ?? 'N/A'} | Lineup Quality: ${formatMetricNumber(row.opponent_lineup_quality)} | Lineup Count: ${formatMetricNumber(row.lineup_hitter_count, 0)}`,
+      ].join('\n'),
+      inline: false,
+    }))
+  );
+
+  return embed;
+}
+
+export function buildBestMatchupsEmbed(result, filters = {}) {
+  const embed = new EmbedBuilder()
+    .setColor(PALETTE.accent)
+    .setTitle('Best Matchups')
+    .setDescription(
+      buildFilterBanner(
+        filters,
+        `Compact hitter board from **${String(result.source ?? 'unknown').toUpperCase()}** for **${result.resolvedDate ?? 'unknown slate'}**.`
+      )
+    );
+
+  if (!result.rows?.length) {
+    return embed.addFields({ name: 'Board', value: 'No matchup hitters were available for that slate.' });
+  }
+
+  embed.addFields(
+    {
+      name: 'Top Board',
+      value: result.rows.map((row, index) => (
+        `${index + 1}. **${row.hitter_name ?? 'Unknown'}**${row.team ? ` (${row.team})` : ''} | `
+        + `Matchup ${formatMetricNumber(row.matchup_score)} | `
+        + `Ceiling ${formatMetricNumber(row.ceiling_score)} | `
+        + `xwOBA ${formatMetricDecimal(row.xwoba)}`
+      )).join('\n'),
+      inline: false,
+    }
+  );
+
+  if (result.warning) {
+    embed.addFields({ name: 'Source Note', value: truncate(result.warning, 256), inline: false });
+  }
+
+  return embed;
+}
+
+export function buildPlayerContextEmbed(result) {
+  const baseDescription = [
+    `Source: **${String(result.source ?? 'unknown').toUpperCase()}**`,
+    `Slate: **${result.resolvedDate ?? 'unknown'}**`,
+    result.team ? `Team: **${result.team}**` : null,
+    result.opponentTeam ? `Opponent: **${result.opponentTeam}**` : null,
+  ].filter(Boolean).join(' | ');
+
+  const embed = new EmbedBuilder()
+    .setColor(result.playerType === 'pitcher' ? PALETTE.secondary : PALETTE.primary)
+    .setTitle(`${result.name ?? 'Player Context'}${result.playerType ? ` - ${capitalize(result.playerType)}` : ''}`)
+    .setDescription(baseDescription);
+
+  if (result.metrics?.length) {
+    embed.addFields({
+      name: 'Overview',
+      value: result.metrics
+        .map((metric) => `${metric.label}: ${formatMetricAuto(metric.value, metric.label)}`)
+        .join(' | '),
+      inline: false,
+    });
+  }
+
+  if (result.playerType === 'hitter') {
+    embed.addFields({
+      name: 'Today',
+      value: [
+        result.opposingPitcherName ? `Opposing Pitcher: ${result.opposingPitcherName}` : null,
+        result.hand ? `Pitcher Hand: ${result.hand}` : null,
+      ].filter(Boolean).join(' | ') || 'No same-day opponent context was available.',
+      inline: false,
+    });
+  }
+
+  if (result.rolling?.length) {
+    embed.addFields({
+      name: 'Rolling',
+      value: result.rolling
+        .map((row) => `${row.label}: ${formatMetricDecimal(row.value)}`)
+        .join('\n'),
+      inline: false,
+    });
+  }
+
+  if (result.zones?.length) {
+    embed.addFields({
+      name: result.playerType === 'pitcher' ? 'Zones To Watch' : 'Best Zones',
+      value: result.zones
+        .map((row) => `${row.label}: ${formatMetricAuto(row.value, row.metricKey)}${row.sample !== null ? ` | Sample ${formatMetricNumber(row.sample, 0)}` : ''}`)
+        .join('\n'),
+      inline: false,
+    });
+  }
+
+  if (result.arsenal?.length) {
+    embed.addFields({
+      name: 'Arsenal',
+      value: result.arsenal
+        .map((row) => `${row.pitchType}: Usage ${formatMetricPercent(row.usagePct)}${row.velocity !== null ? ` | Velo ${formatMetricNumber(row.velocity)}` : ''}${row.whiffRate !== null ? ` | Whiff ${formatMetricPercent(row.whiffRate)}` : ''}`)
+        .join('\n'),
+      inline: false,
+    });
+  }
+
+  if (result.countUsage?.length) {
+    embed.addFields({
+      name: 'Count Usage',
+      value: result.countUsage
+        .map((row) => `${row.countBucket} ${String(row.batterSide).toUpperCase()}: ${row.pitchType} ${formatMetricPercent(row.usagePct)}`)
+        .join('\n'),
+      inline: false,
+    });
+  }
+
+  return embed;
+}
+
+export function buildMatchupHealthEmbed(result) {
+  return new EmbedBuilder()
+    .setColor(PALETTE.info)
+    .setTitle('Matchup Health')
+    .addFields(
+      {
+        name: 'Hosted Artifacts',
+        value: [
+          `Configured: ${result.hosted?.configured ? 'Yes' : 'No'}`,
+          `Latest Date: ${result.hosted?.latestDate ?? 'Unavailable'}`,
+          `Cache Entries: ${result.hosted?.cacheEntries ?? 0}`,
+          `Cache TTL: ${formatMetricNumber((result.hosted?.cacheTtlMs ?? 0) / 1000, 0)}s`,
+          result.hosted?.error ? `Error: ${truncate(result.hosted.error, 180)}` : null,
+        ].filter(Boolean).join('\n'),
+        inline: false,
+      },
+      {
+        name: 'Cockroach Fallback',
+        value: [
+          `Configured: ${result.fallback?.configured ? 'Yes' : 'No'}`,
+          `Latest Date: ${result.fallback?.latestDate ?? 'Unavailable'}`,
+          result.fallback?.error ? `Error: ${truncate(result.fallback.error, 180)}` : null,
+        ].filter(Boolean).join('\n'),
+        inline: false,
+      }
+    );
+}
+
 function escapeCsv(value) {
   const stringValue = String(value);
   if (stringValue.includes(',') || stringValue.includes('"') || stringValue.includes('\n')) {
@@ -1023,6 +1231,45 @@ function formatUnits(value) {
   return `${(value ?? 0).toFixed(2)}u`;
 }
 
+function formatMetricNumber(value, digits = 1) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) {
+    return 'N/A';
+  }
+  return numeric.toFixed(digits);
+}
+
+function formatMetricDecimal(value) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) {
+    return 'N/A';
+  }
+  return numeric.toFixed(3);
+}
+
+function formatMetricPercent(value) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) {
+    return 'N/A';
+  }
+  return `${numeric.toFixed(1)}%`;
+}
+
+function formatMetricAuto(value, labelOrKey) {
+  const key = String(labelOrKey ?? '').toLowerCase();
+  if (key.includes('%') || key.endsWith('_pct') || key.includes('usage') || key.includes('whiff') || key.includes('strike')) {
+    return formatMetricPercent(value);
+  }
+  if (key.includes('xwoba')) {
+    return formatMetricDecimal(value);
+  }
+  return formatMetricNumber(value);
+}
+
+function capitalize(value) {
+  return value ? `${value[0].toUpperCase()}${value.slice(1)}` : '';
+}
+
 function formatSelection(side, lineValue) {
   const normalizedSide = String(side ?? '').trim().toLowerCase();
   const sideLabel = {

src/index.js

@@ -26,6 +26,7 @@ import {
   buildAlertsButtonRows,
   buildAlertsEmbed,
   buildBankrollEmbed,
+  buildBestMatchupsEmbed,
   buildBetSavedEmbed,
   buildBetsEmbed,
   buildBetsPaginationRow,
@@ -54,7 +55,11 @@ import {
   buildEditBetEmbed,
   buildErrorEmbed,
   buildExportAttachment,
+  buildMatchupHealthEmbed,
+  buildMatchupHittersEmbed,
+  buildMatchupPitchersEmbed,
   buildMarketTopEmbed,
+  buildPlayerContextEmbed,
   buildResolveAllEmbed,
   buildResolveEmbed,
   buildRoiEmbed,
@@ -70,6 +75,7 @@ import {
 import { parseBulkAddInput } from './bulk-add.js';
 import { parseBetIdList } from './resolve-bulk.js';
 import { MarketScanner } from './market-scanner.js';
+import { MatchupService } from './matchups.js';
 
 const BET_MODAL_PREFIX = 'bet-entry-modal';
 const BULK_ADD_MODAL_PREFIX = 'bulk-add-modal';
@@ -94,6 +100,9 @@ async function main() {
   const client = new Client({
     intents: [GatewayIntentBits.Guilds],
   });
+  const matchupService = new MatchupService(config.matchups, {
+    logger: console,
+  });
   const scanner = new MarketScanner({
     client,
     store,
@@ -114,6 +123,7 @@ async function main() {
     logger: console,
   });
   client.__marketScanner = scanner;
+  client.__matchupService = matchupService;
 
   const healthServer = http.createServer((request, response) => {
     response.writeHead(200, { 'Content-Type': 'application/json' });
@@ -196,6 +206,7 @@ async function main() {
     console.log('Shutting down...');
     healthServer.close();
     await scanner.stop();
+    await matchupService.close();
     client.destroy();
     await store.close();
     process.exit(0);
@@ -432,6 +443,31 @@ async function handleChatInput(interaction, store, config) {
     return;
   }
 
+  if (commandName === 'matchuphitters') {
+    await handleMatchupCommand(interaction, config, 'matchuphitters');
+    return;
+  }
+
+  if (commandName === 'matchuppitchers') {
+    await handleMatchupCommand(interaction, config, 'matchuppitchers');
+    return;
+  }
+
+  if (commandName === 'playercontext') {
+    await handleMatchupCommand(interaction, config, 'playercontext');
+    return;
+  }
+
+  if (commandName === 'bestmatchups') {
+    await handleMatchupCommand(interaction, config, 'bestmatchups');
+    return;
+  }
+
+  if (commandName === 'matchuphealth') {
+    await handleMatchupHealth(interaction, config);
+    return;
+  }
+
   if (commandName === 'alerts') {
     await handleAlerts(interaction);
     return;
@@ -463,6 +499,16 @@ function getMarketIntelligenceFilters(interaction) {
   };
 }
 
+function getMatchupFilters(interaction) {
+  return {
+    team: interaction.options.getString('team') ?? undefined,
+    player: interaction.options.getString('player') ?? undefined,
+    playerType: interaction.options.getString('player_type') ?? undefined,
+    date: interaction.options.getString('date') ?? undefined,
+    limit: interaction.options.getInteger('limit') ?? undefined,
+  };
+}
+
 async function showBetModal(interaction) {
   const selectedBook = interaction.options.getString('book', true);
   const selectedSport = interaction.options.getString('sport', true);
@@ -1272,6 +1318,83 @@ async function handleSharpBoard(interaction, config, commandName) {
   }
 }
 
+async function handleMatchupCommand(interaction, config, commandName) {
+  await interaction.deferReply();
+
+  const matchupService = interaction.client.__matchupService;
+  if (!config.matchups.enabled || !matchupService) {
+    await interaction.editReply({
+      embeds: [buildErrorEmbed('Matchups unavailable', 'Configure MLB_HOSTED_BASE_URL or Cockroach access before using matchup commands.')],
+    });
+    return;
+  }
+
+  const filters = getMatchupFilters(interaction);
+
+  try {
+    if (commandName === 'matchuphitters') {
+      const result = await matchupService.getTopHitters(filters);
+      await interaction.editReply({ embeds: [buildMatchupHittersEmbed(result, filters)] });
+      return;
+    }
+
+    if (commandName === 'matchuppitchers') {
+      const result = await matchupService.getTopPitchers(filters);
+      await interaction.editReply({ embeds: [buildMatchupPitchersEmbed(result, filters)] });
+      return;
+    }
+
+    if (commandName === 'bestmatchups') {
+      const result = await matchupService.getBestMatchups(filters);
+      await interaction.editReply({ embeds: [buildBestMatchupsEmbed(result, filters)] });
+      return;
+    }
+
+    if (commandName === 'playercontext') {
+      const result = await matchupService.getPlayerContext(filters);
+      await interaction.editReply({ embeds: [buildPlayerContextEmbed(result, filters)] });
+      return;
+    }
+
+    await interaction.editReply({
+      embeds: [buildErrorEmbed('Command unavailable', 'That matchup command is not wired up yet.')],
+    });
+  } catch (error) {
+    await interaction.editReply({
+      embeds: [buildErrorEmbed('Matchup data unavailable', error.message || 'The matchup lookup hit an unexpected error.')],
+    });
+  }
+}
+
+async function handleMatchupHealth(interaction, config) {
+  const isAdmin = await memberHasRoleName(interaction, config.adminRoleName);
+  if (!isAdmin) {
+    await denyAdminOnly(interaction, config.adminRoleName);
+    return;
+  }
+
+  const matchupService = interaction.client.__matchupService;
+  if (!config.matchups.enabled || !matchupService) {
+    await interaction.reply({
+      embeds: [buildErrorEmbed('Matchups unavailable', 'Configure MLB_HOSTED_BASE_URL or Cockroach access before using matchup commands.')],
+      flags: MessageFlags.Ephemeral,
+    });
+    return;
+  }
+
+  await interaction.deferReply({ flags: MessageFlags.Ephemeral });
+  try {
+    const result = await matchupService.getHealth(getMatchupFilters(interaction));
+    await interaction.editReply({
+      embeds: [buildMatchupHealthEmbed(result)],
+    });
+  } catch (error) {
+    await interaction.editReply({
+      embeds: [buildErrorEmbed('Matchup health unavailable', error.message || 'The matchup health lookup hit an unexpected error.')],
+    });
+  }
+}
+
 async function handleButton(interaction, store) {
   const alertRoleName = parseAlertRoleButtonId(interaction.customId);
   if (alertRoleName) {

src/matchups.js

@@ -0,0 +1,1005 @@
+import { Pool } from 'pg';
+import { asyncBufferFromUrl, parquetReadObjects } from 'hyparquet';
+
+const DEFAULT_MATCHUP_LIMIT = 10;
+const DEFAULT_RECENT_WINDOW = 'season';
+const DEFAULT_SPLIT_KEY = 'overall';
+const DEFAULT_WEIGHTED_MODE = 'weighted';
+const DEFAULT_FALLBACK_DAYS = 7;
+const COCKROACH_RETRY_CODES = new Set(['40001']);
+const PROFILE_CANDIDATE_LIMIT = 5;
+
+const HITTER_COLUMNS = [
+  'game_pk',
+  'team',
+  'opponent_team',
+  'opposing_pitcher_name',
+  'opposing_pitcher_hand',
+  'batter',
+  'player_id',
+  'hitter_name',
+  'split_key',
+  'recent_window',
+  'weighted_mode',
+  'matchup_score',
+  'ceiling_score',
+  'zone_fit_score',
+  'likely_starter_score',
+  'xwoba',
+  'pulled_barrel_pct',
+  'sweet_spot_pct',
+  'barrel_bip_pct',
+  'hard_hit_pct',
+];
+
+const PITCHER_COLUMNS = [
+  'game_pk',
+  'team',
+  'opponent_team',
+  'pitcher_id',
+  'player_id',
+  'pitcher_name',
+  'p_throws',
+  'split_key',
+  'recent_window',
+  'weighted_mode',
+  'pitcher_score',
+  'strikeout_score',
+  'raw_pitcher_score',
+  'raw_strikeout_score',
+  'pitcher_matchup_adjustment',
+  'strikeout_matchup_adjustment',
+  'opponent_lineup_quality',
+  'opponent_contact_threat',
+  'opponent_whiff_tendency',
+  'opponent_family_fit_allowed',
+  'lineup_source',
+  'lineup_hitter_count',
+  'xwoba',
+  'csw_pct',
+  'swstr_pct',
+  'putaway_pct',
+  'ball_pct',
+  'siera',
+  'gb_pct',
+  'gb_fb_ratio',
+  'barrel_bip_pct',
+  'hard_hit_pct',
+];
+
+const SLATE_COLUMNS = [
+  'game_pk',
+  'away_team',
+  'home_team',
+  'away_probable_pitcher',
+  'home_probable_pitcher',
+  'away_probable_hand',
+  'home_probable_hand',
+];
+
+const ROSTER_COLUMNS = ['team', 'player_id', 'player_name'];
+const EXCLUSION_COLUMNS = ['player_id', 'exclude_from_hitter_tables'];
+
+const REUSABLE_HITTER_COLUMNS = [
+  'team',
+  'batter',
+  'player_id',
+  'hitter_name',
+  'split_key',
+  'recent_window',
+  'weighted_mode',
+  'matchup_score',
+  'ceiling_score',
+  'zone_fit_score',
+  'likely_starter_score',
+  'xwoba',
+  'pulled_barrel_pct',
+  'sweet_spot_pct',
+  'barrel_bip_pct',
+  'hard_hit_pct',
+];
+
+const REUSABLE_PITCHER_COLUMNS = [
+  'team',
+  'pitcher_id',
+  'player_id',
+  'pitcher_name',
+  'p_throws',
+  'split_key',
+  'recent_window',
+  'weighted_mode',
+  'pitcher_score',
+  'strikeout_score',
+  'raw_pitcher_score',
+  'raw_strikeout_score',
+  'pitcher_matchup_adjustment',
+  'strikeout_matchup_adjustment',
+  'xwoba',
+  'csw_pct',
+  'swstr_pct',
+  'putaway_pct',
+  'ball_pct',
+  'siera',
+  'gb_pct',
+  'gb_fb_ratio',
+  'barrel_bip_pct',
+  'hard_hit_pct',
+];
+
+const HITTER_ROLLING_COLUMNS = [
+  'batter',
+  'player_id',
+  'hitter_name',
+  'window_label',
+  'window_size',
+  'xwoba',
+  'hard_hit_pct',
+  'barrel_bip_pct',
+  'sweet_spot_pct',
+];
+
+const PITCHER_ROLLING_COLUMNS = [
+  'pitcher_id',
+  'player_id',
+  'pitcher_name',
+  'window_label',
+  'window_size',
+  'xwoba',
+  'csw_pct',
+  'swstr_pct',
+  'putaway_pct',
+  'ball_pct',
+];
+
+const BATTER_ZONE_COLUMNS = [
+  'batter',
+  'player_id',
+  'hitter_name',
+  'zone_label',
+  'zone',
+  'xwoba',
+  'hard_hit_pct',
+  'barrel_bip_pct',
+  'sample_size',
+  'bip',
+];
+
+const PITCHER_ZONE_COLUMNS = [
+  'pitcher_id',
+  'player_id',
+  'pitcher_name',
+  'zone_label',
+  'zone',
+  'xwoba_allowed',
+  'hard_hit_pct_allowed',
+  'barrel_bip_pct_allowed',
+  'sample_size',
+  'bip',
+];
+
+const ARSENAL_COLUMNS = [
+  'pitcher_id',
+  'player_id',
+  'pitcher_name',
+  'pitch_type',
+  'usage_pct',
+  'avg_velocity',
+  'avg_spin_rate',
+  'whiff_rate',
+  'called_strike_rate',
+  'putaway_rate',
+];
+
+const COUNT_USAGE_COLUMNS = [
+  'pitcher_id',
+  'player_id',
+  'pitcher_name',
+  'count_bucket',
+  'batter_side_key',
+  'pitch_type',
+  'usage_pct',
+];
+
+function addDays(value, delta) {
+  const next = new Date(`${value}T12:00:00Z`);
+  next.setUTCDate(next.getUTCDate() + delta);
+  return next.toISOString().slice(0, 10);
+}
+
+function parseDateOrToday(value) {
+  if (!value) {
+    return new Date().toISOString().slice(0, 10);
+  }
+
+  if (/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    return value;
+  }
+
+  throw new Error('Dates must use YYYY-MM-DD format.');
+}
+
+function limitOrDefault(value, max = 15) {
+  const numeric = Number(value ?? DEFAULT_MATCHUP_LIMIT);
+  if (!Number.isFinite(numeric) || numeric <= 0) {
+    return DEFAULT_MATCHUP_LIMIT;
+  }
+  return Math.min(max, Math.max(1, Math.floor(numeric)));
+}
+
+function normalizeText(value) {
+  return String(value ?? '').trim().toLowerCase();
+}
+
+function normalizeTeam(value) {
+  return String(value ?? '').trim().toUpperCase();
+}
+
+function numberOrNull(value) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : null;
+}
+
+function compareNullableDescending(left, right) {
+  const leftValue = numberOrNull(left);
+  const rightValue = numberOrNull(right);
+  if (leftValue === null && rightValue === null) {
+    return 0;
+  }
+  if (leftValue === null) {
+    return 1;
+  }
+  if (rightValue === null) {
+    return -1;
+  }
+  return rightValue - leftValue;
+}
+
+function sortHitters(rows) {
+  return [...rows].sort((left, right) =>
+    compareNullableDescending(left.matchup_score, right.matchup_score)
+    || compareNullableDescending(left.ceiling_score, right.ceiling_score)
+    || compareNullableDescending(left.likely_starter_score, right.likely_starter_score)
+    || compareNullableDescending(left.xwoba, right.xwoba)
+    || String(left.hitter_name ?? '').localeCompare(String(right.hitter_name ?? ''))
+  );
+}
+
+function sortPitchers(rows) {
+  return [...rows].sort((left, right) =>
+    compareNullableDescending(left.pitcher_score, right.pitcher_score)
+    || compareNullableDescending(left.strikeout_score, right.strikeout_score)
+    || compareNullableDescending(left.pitcher_matchup_adjustment, right.pitcher_matchup_adjustment)
+    || compareNullableDescending(left.xwoba, right.xwoba)
+    || String(left.pitcher_name ?? '').localeCompare(String(right.pitcher_name ?? ''))
+  );
+}
+
+function keepRowForDefaults(row) {
+  const splitKey = String(row.split_key ?? DEFAULT_SPLIT_KEY);
+  const recentWindow = String(row.recent_window ?? DEFAULT_RECENT_WINDOW);
+  const weightedMode = String(row.weighted_mode ?? DEFAULT_WEIGHTED_MODE);
+  return splitKey === DEFAULT_SPLIT_KEY
+    && recentWindow === DEFAULT_RECENT_WINDOW
+    && weightedMode === DEFAULT_WEIGHTED_MODE;
+}
+
+function mapSlateTeams(slateRows) {
+  const lookup = new Map();
+  for (const row of slateRows) {
+    const awayTeam = String(row.away_team ?? '').trim();
+    const homeTeam = String(row.home_team ?? '').trim();
+    if (!awayTeam || !homeTeam) {
+      continue;
+    }
+
+    lookup.set(awayTeam, {
+      gamePk: row.game_pk ?? null,
+      opponentTeam: homeTeam,
+      opposingPitcherName: row.home_probable_pitcher ?? null,
+      opposingPitcherHand: row.home_probable_hand ?? null,
+    });
+    lookup.set(homeTeam, {
+      gamePk: row.game_pk ?? null,
+      opponentTeam: awayTeam,
+      opposingPitcherName: row.away_probable_pitcher ?? null,
+      opposingPitcherHand: row.away_probable_hand ?? null,
+    });
+  }
+  return lookup;
+}
+
+function buildExclusionSet(rows) {
+  const values = new Set();
+  for (const row of rows) {
+    const playerId = row.player_id;
+    if (playerId === null || playerId === undefined || playerId === '') {
+      continue;
+    }
+    const shouldExclude = row.exclude_from_hitter_tables === true
+      || String(row.exclude_from_hitter_tables ?? '').toLowerCase() === 'true'
+      || String(row.exclude_from_hitter_tables ?? '') === '1';
+    if (shouldExclude) {
+      values.add(String(playerId));
+    }
+  }
+  return values;
+}
+
+function withDefaults(row, slateLookup) {
+  const team = String(row.team ?? '').trim();
+  const slate = slateLookup.get(team) ?? {};
+  return {
+    ...row,
+    team,
+    game_pk: row.game_pk ?? slate.gamePk ?? null,
+    opponent_team: row.opponent_team ?? slate.opponentTeam ?? null,
+    opposing_pitcher_name: row.opposing_pitcher_name ?? slate.opposingPitcherName ?? null,
+    opposing_pitcher_hand: row.opposing_pitcher_hand ?? slate.opposingPitcherHand ?? null,
+  };
+}
+
+function pickMetrics(row, metricKeys) {
+  return metricKeys
+    .map(([label, key]) => ({ label, key, value: numberOrNull(row[key]) }))
+    .filter((item) => item.value !== null);
+}
+
+function buildRollingSummary(rows, metricKey, valueKey) {
+  return rows
+    .map((row) => ({
+      label: row[metricKey] ?? (row.window_size ? `Rolling ${row.window_size}` : null),
+      value: numberOrNull(row[valueKey]),
+    }))
+    .filter((row) => row.label && row.value !== null)
+    .slice(0, 3);
+}
+
+function buildZoneSummary(rows, nameKey, valueKeys) {
+  return [...rows]
+    .map((row) => {
+      const label = row.zone_label ?? row.zone ?? null;
+      const metric = valueKeys
+        .map((key) => ({ key, value: numberOrNull(row[key]) }))
+        .find((item) => item.value !== null);
+      return {
+        label,
+        metricKey: metric?.key ?? null,
+        value: metric?.value ?? null,
+        sample: numberOrNull(row.sample_size ?? row.bip),
+        playerName: row[nameKey] ?? null,
+      };
+    })
+    .filter((row) => row.label && row.value !== null)
+    .sort((left, right) => compareNullableDescending(left.value, right.value))
+    .slice(0, 3);
+}
+
+function buildArsenalSummary(rows) {
+  return [...rows]
+    .map((row) => ({
+      pitchType: row.pitch_type ?? null,
+      usagePct: numberOrNull(row.usage_pct),
+      velocity: numberOrNull(row.avg_velocity),
+      whiffRate: numberOrNull(row.whiff_rate),
+      calledStrikeRate: numberOrNull(row.called_strike_rate),
+    }))
+    .filter((row) => row.pitchType && row.usagePct !== null)
+    .sort((left, right) => compareNullableDescending(left.usagePct, right.usagePct))
+    .slice(0, 4);
+}
+
+function buildCountUsageSummary(rows) {
+  return [...rows]
+    .map((row) => ({
+      countBucket: row.count_bucket ?? null,
+      batterSide: row.batter_side_key ?? 'all',
+      pitchType: row.pitch_type ?? null,
+      usagePct: numberOrNull(row.usage_pct),
+    }))
+    .filter((row) => row.countBucket && row.pitchType && row.usagePct !== null)
+    .sort((left, right) => compareNullableDescending(left.usagePct, right.usagePct))
+    .slice(0, 4);
+}
+
+function findBestPlayerMatch(rows, key, playerName) {
+  const normalizedNeedle = normalizeText(playerName);
+  const exact = rows.find((row) => normalizeText(row[key]) === normalizedNeedle);
+  if (exact) {
+    return exact;
+  }
+  return rows.find((row) => normalizeText(row[key]).includes(normalizedNeedle)) ?? null;
+}
+
+async function sleep(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export class HostedArtifactSource {
+  constructor(config = {}, options = {}) {
+    this.baseUrl = String(config.baseUrl ?? '').trim().replace(/\/$/, '');
+    this.cacheTtlMs = Number(config.cacheTtlMs ?? 5 * 60 * 1000);
+    this.fallbackDays = Number(config.fallbackDays ?? DEFAULT_FALLBACK_DAYS);
+    this.logger = options.logger ?? console;
+    this.readParquetImpl = options.readParquetImpl ?? readParquetFromUrl;
+    this.cache = new Map();
+  }
+
+  isConfigured() {
+    return Boolean(this.baseUrl);
+  }
+
+  async getLatestAvailableDate(targetDate) {
+    if (!this.isConfigured()) {
+      return null;
+    }
+
+    const safeTargetDate = parseDateOrToday(targetDate);
+    for (let offset = 0; offset <= this.fallbackDays; offset += 1) {
+      const candidate = addDays(safeTargetDate, -offset);
+      try {
+        await this.readDailyFile(candidate, 'slate.parquet', SLATE_COLUMNS);
+        return candidate;
+      } catch (error) {
+        this.logger?.debug?.('Hosted slate check failed', { candidate, error: error.message });
+      }
+    }
+
+    return null;
+  }
+
+  async readDailyFile(targetDate, filename, columns) {
+    const safeDate = parseDateOrToday(targetDate);
+    const url = `${this.baseUrl}/daily/${safeDate}/${filename}`;
+    return this.readCached(url, columns);
+  }
+
+  async readReusableFile(filename, columns) {
+    const url = `${this.baseUrl}/reusable/${filename}`;
+    return this.readCached(url, columns);
+  }
+
+  async readCached(url, columns) {
+    const cacheKey = `${url}|${(columns ?? []).join(',')}`;
+    const now = Date.now();
+    const cached = this.cache.get(cacheKey);
+    if (cached && cached.expiresAt > now) {
+      return cached.rows;
+    }
+
+    const rows = await this.readParquetImpl(url, columns);
+    this.cache.set(cacheKey, {
+      expiresAt: now + this.cacheTtlMs,
+      rows,
+    });
+    return rows;
+  }
+
+  async getTopHitters(options = {}) {
+    const targetDate = parseDateOrToday(options.date);
+    const resolvedDate = await this.getLatestAvailableDate(targetDate);
+    if (!resolvedDate) {
+      throw new Error('No hosted matchup slate was available in the fallback window.');
+    }
+
+    const [slateRows, hitterRows, exclusionRows] = await Promise.all([
+      this.readDailyFile(resolvedDate, 'slate.parquet', SLATE_COLUMNS),
+      this.readDailyFile(resolvedDate, 'daily_hitter_metrics.parquet', HITTER_COLUMNS),
+      this.readDailyFile(resolvedDate, 'hitter_pitcher_exclusions.parquet', EXCLUSION_COLUMNS)
+        .catch(() => []),
+    ]);
+
+    const exclusionSet = buildExclusionSet(exclusionRows);
+    const slateLookup = mapSlateTeams(slateRows);
+    const filteredRows = hitterRows
+      .filter(keepRowForDefaults)
+      .map((row) => withDefaults(row, slateLookup))
+      .filter((row) => !options.team || normalizeTeam(row.team) === normalizeTeam(options.team))
+      .filter((row) => {
+        const playerId = row.batter ?? row.player_id;
+        return !exclusionSet.has(String(playerId ?? ''));
+      });
+
+    return {
+      source: 'hosted',
+      resolvedDate,
+      rows: sortHitters(filteredRows).slice(0, limitOrDefault(options.limit)),
+    };
+  }
+
+  async getTopPitchers(options = {}) {
+    const targetDate = parseDateOrToday(options.date);
+    const resolvedDate = await this.getLatestAvailableDate(targetDate);
+    if (!resolvedDate) {
+      throw new Error('No hosted pitcher slate was available in the fallback window.');
+    }
+
+    const [slateRows, pitcherRows] = await Promise.all([
+      this.readDailyFile(resolvedDate, 'slate.parquet', SLATE_COLUMNS),
+      this.readDailyFile(resolvedDate, 'daily_pitcher_metrics.parquet', PITCHER_COLUMNS),
+    ]);
+
+    const slateLookup = mapSlateTeams(slateRows);
+    const filteredRows = pitcherRows
+      .filter(keepRowForDefaults)
+      .map((row) => withDefaults(row, slateLookup))
+      .filter((row) => !options.team || normalizeTeam(row.team) === normalizeTeam(options.team));
+
+    return {
+      source: 'hosted',
+      resolvedDate,
+      rows: sortPitchers(filteredRows).slice(0, limitOrDefault(options.limit)),
+    };
+  }
+
+  async getBestMatchups(options = {}) {
+    const result = await this.getTopHitters({
+      ...options,
+      limit: limitOrDefault(options.limit, 12),
+    });
+    return {
+      ...result,
+      rows: result.rows,
+    };
+  }
+
+  async getPlayerContext(options = {}) {
+    const targetDate = parseDateOrToday(options.date);
+    const resolvedDate = await this.getLatestAvailableDate(targetDate);
+    if (!resolvedDate) {
+      throw new Error('No hosted player context was available in the fallback window.');
+    }
+
+    const [slateRows, dailyHitterRows, dailyPitcherRows, reusableHitters, reusablePitchers, hitterRollingRows, pitcherRollingRows, batterZoneRows, pitcherZoneRows, arsenalRows, countUsageRows] = await Promise.all([
+      this.readDailyFile(resolvedDate, 'slate.parquet', SLATE_COLUMNS),
+      this.readDailyFile(resolvedDate, 'daily_hitter_metrics.parquet', HITTER_COLUMNS),
+      this.readDailyFile(resolvedDate, 'daily_pitcher_metrics.parquet', PITCHER_COLUMNS),
+      this.readReusableFile('hitter_metrics.parquet', REUSABLE_HITTER_COLUMNS),
+      this.readReusableFile('pitcher_metrics.parquet', REUSABLE_PITCHER_COLUMNS),
+      this.readReusableFile('hitter_rolling.parquet', HITTER_ROLLING_COLUMNS).catch(() => []),
+      this.readReusableFile('pitcher_rolling.parquet', PITCHER_ROLLING_COLUMNS).catch(() => []),
+      this.readReusableFile('batter_zone_profiles.parquet', BATTER_ZONE_COLUMNS).catch(() => []),
+      this.readReusableFile('pitcher_zone_profiles.parquet', PITCHER_ZONE_COLUMNS).catch(() => []),
+      this.readReusableFile('pitcher_arsenal.parquet', ARSENAL_COLUMNS).catch(() => []),
+      this.readReusableFile('pitcher_usage_by_count.parquet', COUNT_USAGE_COLUMNS).catch(() => []),
+    ]);
+
+    const slateLookup = mapSlateTeams(slateRows);
+    const normalizedType = normalizeText(options.playerType || 'auto');
+
+    const dailyHitters = dailyHitterRows.filter(keepRowForDefaults).map((row) => withDefaults(row, slateLookup));
+    const dailyPitchers = dailyPitcherRows.filter(keepRowForDefaults).map((row) => withDefaults(row, slateLookup));
+    const baseHitters = reusableHitters.filter(keepRowForDefaults);
+    const basePitchers = reusablePitchers.filter(keepRowForDefaults);
+
+    const hitterMatch = normalizedType === 'pitcher' ? null : findBestPlayerMatch(dailyHitters, 'hitter_name', options.player)
+      ?? findBestPlayerMatch(baseHitters, 'hitter_name', options.player);
+    const pitcherMatch = normalizedType === 'hitter' ? null : findBestPlayerMatch(dailyPitchers, 'pitcher_name', options.player)
+      ?? findBestPlayerMatch(basePitchers, 'pitcher_name', options.player);
+
+    if (hitterMatch) {
+      const playerId = String(hitterMatch.batter ?? hitterMatch.player_id ?? '');
+      return {
+        source: 'hosted',
+        resolvedDate,
+        playerType: 'hitter',
+        name: hitterMatch.hitter_name,
+        team: hitterMatch.team ?? null,
+        opponentTeam: hitterMatch.opponent_team ?? null,
+        opposingPitcherName: hitterMatch.opposing_pitcher_name ?? null,
+        hand: hitterMatch.opposing_pitcher_hand ?? null,
+        overview: hitterMatch,
+        metrics: pickMetrics(hitterMatch, [
+          ['Matchup', 'matchup_score'],
+          ['Ceiling', 'ceiling_score'],
+          ['Zone Fit', 'zone_fit_score'],
+          ['Likely', 'likely_starter_score'],
+          ['xwOBA', 'xwoba'],
+          ['HH%', 'hard_hit_pct'],
+          ['Brl/BIP%', 'barrel_bip_pct'],
+        ]),
+        rolling: buildRollingSummary(
+          hitterRollingRows.filter((row) => String(row.batter ?? row.player_id ?? '') === playerId),
+          'window_label',
+          'xwoba'
+        ),
+        zones: buildZoneSummary(
+          batterZoneRows.filter((row) => String(row.batter ?? row.player_id ?? '') === playerId),
+          'hitter_name',
+          ['xwoba', 'hard_hit_pct', 'barrel_bip_pct']
+        ),
+        arsenal: [],
+        countUsage: [],
+      };
+    }
+
+    if (pitcherMatch) {
+      const playerId = String(pitcherMatch.pitcher_id ?? pitcherMatch.player_id ?? '');
+      return {
+        source: 'hosted',
+        resolvedDate,
+        playerType: 'pitcher',
+        name: pitcherMatch.pitcher_name,
+        team: pitcherMatch.team ?? null,
+        opponentTeam: pitcherMatch.opponent_team ?? null,
+        hand: pitcherMatch.p_throws ?? null,
+        overview: pitcherMatch,
+        metrics: pickMetrics(pitcherMatch, [
+          ['Pitch Score', 'pitcher_score'],
+          ['Strikeout', 'strikeout_score'],
+          ['Matchup Adj', 'pitcher_matchup_adjustment'],
+          ['K Adj', 'strikeout_matchup_adjustment'],
+          ['xwOBA', 'xwoba'],
+          ['CSW%', 'csw_pct'],
+          ['SwStr%', 'swstr_pct'],
+        ]),
+        rolling: buildRollingSummary(
+          pitcherRollingRows.filter((row) => String(row.pitcher_id ?? row.player_id ?? '') === playerId),
+          'window_label',
+          'xwoba'
+        ),
+        zones: buildZoneSummary(
+          pitcherZoneRows.filter((row) => String(row.pitcher_id ?? row.player_id ?? '') === playerId),
+          'pitcher_name',
+          ['xwoba_allowed', 'hard_hit_pct_allowed', 'barrel_bip_pct_allowed']
+        ),
+        arsenal: buildArsenalSummary(
+          arsenalRows.filter((row) => String(row.pitcher_id ?? row.player_id ?? '') === playerId)
+        ),
+        countUsage: buildCountUsageSummary(
+          countUsageRows.filter((row) => String(row.pitcher_id ?? row.player_id ?? '') === playerId)
+        ),
+      };
+    }
+
+    throw new Error(`No hosted matchup profile matched "${options.player}".`);
+  }
+
+  async getHealth(options = {}) {
+    const targetDate = parseDateOrToday(options.date);
+    const latestDate = await this.getLatestAvailableDate(targetDate);
+    return {
+      configured: this.isConfigured(),
+      baseUrl: this.baseUrl || null,
+      latestDate,
+      cacheEntries: this.cache.size,
+      cacheTtlMs: this.cacheTtlMs,
+    };
+  }
+}
+
+export class CockroachMatchupSource {
+  constructor(databaseUrl, options = {}) {
+    const usesSsl = /sslmode=(require|verify-ca|verify-full)/i.test(databaseUrl);
+    this.pool = options.pool ?? new Pool({
+      connectionString: databaseUrl,
+      ssl: usesSsl ? { rejectUnauthorized: false } : undefined,
+    });
+    this.logger = options.logger ?? console;
+    this.retryLimit = Number(options.retryLimit ?? 3);
+  }
+
+  async close() {
+    await this.pool.end();
+  }
+
+  async query(text, values = [], attempt = 1) {
+    try {
+      return await this.pool.query(text, values);
+    } catch (error) {
+      if (COCKROACH_RETRY_CODES.has(error?.code) && attempt < this.retryLimit) {
+        await sleep(50 * attempt);
+        return this.query(text, values, attempt + 1);
+      }
+      throw error;
+    }
+  }
+
+  async getLatestSnapshotDate() {
+    const { rows } = await this.query(
+      `
+        SELECT GREATEST(
+          COALESCE((SELECT MAX(slate_date)::date FROM public.hitter_model_snapshots), DATE '1970-01-01'),
+          COALESCE((SELECT MAX(slate_date)::date FROM public.pitcher_model_snapshots), DATE '1970-01-01')
+        ) AS latest_slate_date
+      `
+    );
+    return rows[0]?.latest_slate_date ?? null;
+  }
+
+  async getTopHitters(options = {}) {
+    const limit = limitOrDefault(options.limit);
+    const values = [options.date ?? null, options.team ?? null, limit];
+    const { rows } = await this.query(
+      `
+        WITH target_date AS (
+          SELECT COALESCE($1::date, (SELECT MAX(slate_date)::date FROM public.hitter_model_snapshots)) AS slate_date
+        )
+        SELECT
+          slate_date::date AS slate_date,
+          team,
+          hitter_name,
+          matchup_score,
+          ceiling_score,
+          zone_fit_score,
+          likely_starter_score,
+          xwoba
+        FROM public.hitter_model_snapshots
+        WHERE slate_date::date = (SELECT slate_date FROM target_date)
+          AND split_key = $4
+          AND recent_window = $5
+          AND weighted_mode = $6
+          AND ($2::text IS NULL OR team = $2::text)
+        ORDER BY matchup_score DESC NULLS LAST, ceiling_score DESC NULLS LAST, likely_starter_score DESC NULLS LAST, xwoba DESC NULLS LAST
+        LIMIT $3
+      `,
+      [...values, DEFAULT_SPLIT_KEY, DEFAULT_RECENT_WINDOW, DEFAULT_WEIGHTED_MODE]
+    );
+
+    return {
+      source: 'cockroach',
+      resolvedDate: rows[0]?.slate_date ?? null,
+      rows,
+    };
+  }
+
+  async getTopPitchers(options = {}) {
+    const limit = limitOrDefault(options.limit);
+    const values = [options.date ?? null, options.team ?? null, limit];
+    const { rows } = await this.query(
+      `
+        WITH target_date AS (
+          SELECT COALESCE($1::date, (SELECT MAX(slate_date)::date FROM public.pitcher_model_snapshots)) AS slate_date
+        )
+        SELECT
+          slate_date::date AS slate_date,
+          team,
+          pitcher_name,
+          p_throws,
+          pitcher_score,
+          strikeout_score,
+          raw_pitcher_score,
+          raw_strikeout_score,
+          pitcher_matchup_adjustment,
+          strikeout_matchup_adjustment,
+          opponent_lineup_quality,
+          opponent_contact_threat,
+          opponent_whiff_tendency,
+          lineup_source,
+          lineup_hitter_count,
+          xwoba,
+          csw_pct,
+          swstr_pct,
+          putaway_pct,
+          ball_pct,
+          siera,
+          gb_pct,
+          gb_fb_ratio,
+          barrel_bip_pct,
+          hard_hit_pct
+        FROM public.pitcher_model_snapshots
+        WHERE slate_date::date = (SELECT slate_date FROM target_date)
+          AND split_key = $4
+          AND recent_window = $5
+          AND weighted_mode = $6
+          AND ($2::text IS NULL OR team = $2::text)
+        ORDER BY pitcher_score DESC NULLS LAST, strikeout_score DESC NULLS LAST, pitcher_matchup_adjustment DESC NULLS LAST, xwoba ASC NULLS LAST
+        LIMIT $3
+      `,
+      [...values, DEFAULT_SPLIT_KEY, DEFAULT_RECENT_WINDOW, DEFAULT_WEIGHTED_MODE]
+    );
+
+    return {
+      source: 'cockroach',
+      resolvedDate: rows[0]?.slate_date ?? null,
+      rows,
+    };
+  }
+
+  async getBestMatchups(options = {}) {
+    return this.getTopHitters({
+      ...options,
+      limit: limitOrDefault(options.limit, 12),
+    });
+  }
+
+  async getPlayerContext(options = {}) {
+    const hitterResult = normalizeText(options.playerType) === 'pitcher'
+      ? { rows: [] }
+      : await this.query(
+        `
+          SELECT
+            slate_date::date AS slate_date,
+            team,
+            hitter_name,
+            matchup_score,
+            ceiling_score,
+            zone_fit_score,
+            likely_starter_score,
+            xwoba,
+            hard_hit_pct,
+            barrel_bip_pct
+          FROM public.hitter_model_snapshots
+          WHERE slate_date::date = COALESCE($2::date, (SELECT MAX(slate_date)::date FROM public.hitter_model_snapshots))
+            AND split_key = $3
+            AND recent_window = $4
+            AND weighted_mode = $5
+            AND LOWER(hitter_name) LIKE LOWER($1)
+          ORDER BY CASE WHEN LOWER(hitter_name) = LOWER($6) THEN 0 ELSE 1 END, matchup_score DESC NULLS LAST
+          LIMIT $7
+        `,
+        [`%${options.player}%`, options.date ?? null, DEFAULT_SPLIT_KEY, DEFAULT_RECENT_WINDOW, DEFAULT_WEIGHTED_MODE, options.player, PROFILE_CANDIDATE_LIMIT]
+      );
+
+    const pitcherResult = normalizeText(options.playerType) === 'hitter'
+      ? { rows: [] }
+      : await this.query(
+        `
+          SELECT
+            slate_date::date AS slate_date,
+            team,
+            pitcher_name,
+            p_throws,
+            pitcher_score,
+            strikeout_score,
+            pitcher_matchup_adjustment,
+            strikeout_matchup_adjustment,
+            xwoba,
+            csw_pct,
+            swstr_pct
+          FROM public.pitcher_model_snapshots
+          WHERE slate_date::date = COALESCE($2::date, (SELECT MAX(slate_date)::date FROM public.pitcher_model_snapshots))
+            AND split_key = $3
+            AND recent_window = $4
+            AND weighted_mode = $5
+            AND LOWER(pitcher_name) LIKE LOWER($1)
+          ORDER BY CASE WHEN LOWER(pitcher_name) = LOWER($6) THEN 0 ELSE 1 END, pitcher_score DESC NULLS LAST
+          LIMIT $7
+        `,
+        [`%${options.player}%`, options.date ?? null, DEFAULT_SPLIT_KEY, DEFAULT_RECENT_WINDOW, DEFAULT_WEIGHTED_MODE, options.player, PROFILE_CANDIDATE_LIMIT]
+      );
+
+    const hitter = hitterResult.rows[0] ?? null;
+    const pitcher = pitcherResult.rows[0] ?? null;
+
+    if (hitter) {
+      return {
+        source: 'cockroach',
+        resolvedDate: hitter.slate_date ?? null,
+        playerType: 'hitter',
+        name: hitter.hitter_name,
+        team: hitter.team ?? null,
+        opponentTeam: null,
+        opposingPitcherName: null,
+        hand: null,
+        overview: hitter,
+        metrics: pickMetrics(hitter, [
+          ['Matchup', 'matchup_score'],
+          ['Ceiling', 'ceiling_score'],
+          ['Zone Fit', 'zone_fit_score'],
+          ['Likely', 'likely_starter_score'],
+          ['xwOBA', 'xwoba'],
+          ['HH%', 'hard_hit_pct'],
+          ['Brl/BIP%', 'barrel_bip_pct'],
+        ]),
+        rolling: [],
+        zones: [],
+        arsenal: [],
+        countUsage: [],
+      };
+    }
+
+    if (pitcher) {
+      return {
+        source: 'cockroach',
+        resolvedDate: pitcher.slate_date ?? null,
+        playerType: 'pitcher',
+        name: pitcher.pitcher_name,
+        team: pitcher.team ?? null,
+        opponentTeam: null,
+        hand: pitcher.p_throws ?? null,
+        overview: pitcher,
+        metrics: pickMetrics(pitcher, [
+          ['Pitch Score', 'pitcher_score'],
+          ['Strikeout', 'strikeout_score'],
+          ['Matchup Adj', 'pitcher_matchup_adjustment'],
+          ['K Adj', 'strikeout_matchup_adjustment'],
+          ['xwOBA', 'xwoba'],
+          ['CSW%', 'csw_pct'],
+          ['SwStr%', 'swstr_pct'],
+        ]),
+        rolling: [],
+        zones: [],
+        arsenal: [],
+        countUsage: [],
+      };
+    }
+
+    throw new Error(`No Cockroach matchup profile matched "${options.player}".`);
+  }
+
+  async getHealth(options = {}) {
+    const latestDate = await this.getLatestSnapshotDate();
+    return {
+      configured: true,
+      latestDate: latestDate ?? null,
+      requestedDate: options.date ?? null,
+    };
+  }
+}
+
+export class MatchupService {
+  constructor(config = {}, options = {}) {
+    this.logger = options.logger ?? console;
+    this.hosted = options.hosted ?? new HostedArtifactSource(config.hosted ?? {}, { logger: this.logger });
+    this.fallback = options.fallback ?? new CockroachMatchupSource(config.databaseUrl, { logger: this.logger });
+  }
+
+  async close() {
+    await this.fallback?.close?.();
+  }
+
+  async runHostedFirst(methodName, options = {}) {
+    let hostedError = null;
+    if (this.hosted?.isConfigured?.()) {
+      try {
+        return await this.hosted[methodName](options);
+      } catch (error) {
+        hostedError = error;
+        this.logger?.warn?.(`Hosted matchup source failed for ${methodName}`, {
+          error: error.message,
+          options,
+        });
+      }
+    }
+
+    const result = await this.fallback[methodName](options);
+    if (hostedError) {
+      result.warning = hostedError.message;
+    }
+    return result;
+  }
+
+  async getTopHitters(options = {}) {
+    return this.runHostedFirst('getTopHitters', options);
+  }
+
+  async getTopPitchers(options = {}) {
+    return this.runHostedFirst('getTopPitchers', options);
+  }
+
+  async getBestMatchups(options = {}) {
+    return this.runHostedFirst('getBestMatchups', options);
+  }
+
+  async getPlayerContext(options = {}) {
+    return this.runHostedFirst('getPlayerContext', options);
+  }
+
+  async getHealth(options = {}) {
+    const [hosted, fallback] = await Promise.all([
+      this.hosted.getHealth(options).catch((error) => ({
+        configured: this.hosted?.isConfigured?.() ?? false,
+        latestDate: null,
+        error: error.message,
+      })),
+      this.fallback.getHealth(options).catch((error) => ({
+        configured: true,
+        latestDate: null,
+        error: error.message,
+      })),
+    ]);
+
+    return {
+      hosted,
+      fallback,
+    };
+  }
+}
+
+export async function readParquetFromUrl(url, columns) {
+  const file = await asyncBufferFromUrl({ url });
+  return parquetReadObjects({
+    file,
+    columns,
+  });
+}

test/matchups.test.js

@@ -0,0 +1,152 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { commands } from '../src/commands.js';
+import { buildMatchupHittersEmbed, buildPlayerContextEmbed } from '../src/embeds.js';
+import { HostedArtifactSource, MatchupService } from '../src/matchups.js';
+
+test('hosted artifact source resolves latest available daily slate and caches parquet reads', async () => {
+  const responses = new Map([
+    ['https://example.test/daily/2026-04-06/slate.parquet', [
+      {
+        game_pk: 10,
+        away_team: 'CHC',
+        home_team: 'MIL',
+        away_probable_pitcher: 'Shota Imanaga',
+        home_probable_pitcher: 'Freddy Peralta',
+        away_probable_hand: 'L',
+        home_probable_hand: 'R',
+      },
+    ]],
+    ['https://example.test/daily/2026-04-06/daily_hitter_metrics.parquet', [
+      {
+        team: 'CHC',
+        hitter_name: 'Seiya Suzuki',
+        batter: 100,
+        split_key: 'overall',
+        recent_window: 'season',
+        weighted_mode: 'weighted',
+        matchup_score: 82.4,
+        ceiling_score: 79.5,
+        zone_fit_score: 70.1,
+        likely_starter_score: 98.2,
+        xwoba: 0.398,
+        hard_hit_pct: 48.2,
+      },
+    ]],
+    ['https://example.test/daily/2026-04-06/hitter_pitcher_exclusions.parquet', []],
+  ]);
+  const calls = [];
+  const source = new HostedArtifactSource(
+    {
+      baseUrl: 'https://example.test',
+      cacheTtlMs: 60_000,
+      fallbackDays: 2,
+    },
+    {
+      readParquetImpl: async (url) => {
+        calls.push(url);
+        if (!responses.has(url)) {
+          throw new Error(`Missing ${url}`);
+        }
+        return responses.get(url);
+      },
+      logger: { debug() {}, warn() {} },
+    }
+  );
+
+  const first = await source.getTopHitters({ date: '2026-04-07' });
+  const second = await source.getTopHitters({ date: '2026-04-07' });
+
+  assert.equal(first.resolvedDate, '2026-04-06');
+  assert.equal(first.rows[0].hitter_name, 'Seiya Suzuki');
+  assert.equal(first.rows[0].opponent_team, 'MIL');
+  assert.equal(second.rows[0].opposing_pitcher_name, 'Freddy Peralta');
+  assert.equal(calls.filter((url) => url.includes('2026-04-06/slate.parquet')).length, 1);
+  assert.equal(calls.filter((url) => url.includes('daily_hitter_metrics.parquet')).length, 1);
+});
+
+test('matchup service falls back to Cockroach when hosted source fails', async () => {
+  const service = new MatchupService(
+    { databaseUrl: 'postgresql://test', hosted: { baseUrl: 'https://example.test' } },
+    {
+      hosted: {
+        isConfigured: () => true,
+        async getTopPitchers() {
+          throw new Error('hosted down');
+        },
+        async getHealth() {
+          return { configured: true, latestDate: null };
+        },
+      },
+      fallback: {
+        async getTopPitchers() {
+          return {
+            source: 'cockroach',
+            resolvedDate: '2026-04-06',
+            rows: [{ pitcher_name: 'Tarik Skubal', pitcher_score: 91.2, strikeout_score: 88.1 }],
+          };
+        },
+        async getHealth() {
+          return { configured: true, latestDate: '2026-04-06' };
+        },
+        async close() {},
+      },
+      logger: { warn() {} },
+    }
+  );
+
+  const result = await service.getTopPitchers({ date: '2026-04-07' });
+
+  assert.equal(result.source, 'cockroach');
+  assert.equal(result.rows[0].pitcher_name, 'Tarik Skubal');
+  assert.match(result.warning, /hosted down/i);
+});
+
+test('commands include new matchup commands', () => {
+  const names = commands.map((command) => command.name);
+  assert.ok(names.includes('matchuphitters'));
+  assert.ok(names.includes('matchuppitchers'));
+  assert.ok(names.includes('playercontext'));
+  assert.ok(names.includes('bestmatchups'));
+  assert.ok(names.includes('matchuphealth'));
+});
+
+test('matchup embeds render core matchup data clearly', () => {
+  const hittersEmbed = buildMatchupHittersEmbed({
+    source: 'hosted',
+    resolvedDate: '2026-04-06',
+    rows: [{
+      hitter_name: 'Aaron Judge',
+      team: 'NYY',
+      matchup_score: 85.1,
+      ceiling_score: 90.2,
+      zone_fit_score: 78.4,
+      likely_starter_score: 99.0,
+      xwoba: 0.455,
+      hard_hit_pct: 57.2,
+      opponent_team: 'BOS',
+      opposing_pitcher_name: 'Tanner Houck',
+      opposing_pitcher_hand: 'R',
+    }],
+  });
+  const playerEmbed = buildPlayerContextEmbed({
+    source: 'hosted',
+    resolvedDate: '2026-04-06',
+    playerType: 'pitcher',
+    name: 'Paul Skenes',
+    team: 'PIT',
+    metrics: [
+      { label: 'Pitch Score', value: 92.2 },
+      { label: 'Strikeout', value: 89.5 },
+    ],
+    rolling: [{ label: 'Rolling 5', value: 0.245 }],
+    zones: [{ label: 'Up-In', metricKey: 'xwoba_allowed', value: 0.198, sample: 22 }],
+    arsenal: [{ pitchType: 'Four-Seam', usagePct: 41.2, velocity: 99.1, whiffRate: 31.4 }],
+    countUsage: [{ countBucket: 'Putaway', batterSide: 'R', pitchType: 'Slider', usagePct: 38.2 }],
+  });
+
+  assert.equal(hittersEmbed.data.title, 'Matchup Hitters');
+  assert.match(hittersEmbed.data.fields[0].name, /Aaron Judge/);
+  assert.equal(playerEmbed.data.title, 'Paul Skenes - Pitcher');
+  assert.ok(playerEmbed.data.fields.some((field) => field.name === 'Arsenal'));
+});