@semanticintent/semantic-chirp-intelligence-mcp 3.0.0 → 4.0.0

package/build/analyses/StreamingAnalysis.js

@@ -6,87 +6,37 @@
  */
 import { AnalysisTemplate } from '../template/AnalysisTemplate.js';
 import { ChirpIntelligence } from '../services/ChirpIntelligence.js';
+import { NHL_SCHEDULE, NhlScheduleService } from '../services/NhlScheduleService.js';
+import { LEAGUE_DATA, LeagueDataService } from '../services/LeagueDataService.js';
+import { NHL_STATS } from '../services/NhlStatsService.js';
 export class StreamingAnalysis extends AnalysisTemplate {
-    apiClient;
-    leagueId;
-    teamId;
-    constructor(apiClient, leagueId, teamId) {
+    constructor() {
         super("get_streaming_recommendations", "streaming_strategy");
-        this.apiClient = apiClient;
-        this.leagueId = leagueId;
-        this.teamId = teamId;
     }
     /**
      * Hook 1: Fetch raw data from Yahoo API
      */
     async fetchData(args) {
-        try {
-            // Fetch trending players (hot pickups)
-            // Note: apiClient.request() already includes /fantasy/v2 base
-            const cleanLeagueId = this.leagueId.replace(/^nhl\.l\./, '');
-            const trendingData = await this.apiClient.request(`/league/nhl.l.${cleanLeagueId}/players;status=A;sort=AR`);
-            // Fetch your current roster to avoid recommending owned players
-            const rosterData = await this.apiClient.getTeamRoster(this.leagueId, this.teamId);
-            // Fetch league scoreboard for schedule data
-            const scoreboardData = await this.apiClient.getLeagueScoreboard(this.leagueId);
-            return {
-                trending: trendingData,
-                roster: rosterData,
-                scoreboard: scoreboardData
-            };
-        }
-        catch (error) {
-            throw new Error(`Failed to fetch streaming data: ${error}`);
-        }
+        // v4: no waiver wire exists without league-private ownership data, so the
+        // pool is "NHL players not on the rosters you gave me", ranked by
+        // production. The caveat travels with the results.
+        await Promise.all([NHL_STATS.load(), NHL_SCHEDULE.load()]);
+        return {
+            pool: LEAGUE_DATA.getPlayerPool({ limit: 120 }),
+            roster: LEAGUE_DATA.getRoster(),
+            pool_caveat: LeagueDataService.POOL_CAVEAT
+        };
     }
     /**
      * Hook 2: Prepare data into FantasyData structure
      */
     async prepareData(rawData, args) {
-        const { trending, roster, scoreboard } = rawData;
-        // Parse current roster to filter out owned players
-        const ownedPlayerIds = new Set();
-        const rosterPlayers = roster.fantasy_content?.team?.[1]?.roster?.['0']?.players?.['0']?.player || [];
-        for (const playerData of rosterPlayers) {
-            const player = playerData.player?.[0] || playerData;
-            ownedPlayerIds.add(player.player_id);
-        }
-        // Parse available trending players
-        const availablePlayers = [];
-        const trendingPlayers = trending.fantasy_content?.league?.[1]?.players?.['0']?.player || [];
-        for (const playerData of trendingPlayers) {
-            const player = playerData.player?.[0] || playerData;
-            const playerId = player.player_id;
-            // Skip if already owned
-            if (ownedPlayerIds.has(playerId)) {
-                continue;
-            }
-            // Apply position filter if specified
-            const position = player.display_position || player.primary_positions?.[0] || 'Unknown';
-            if (args.position_filter && args.position_filter.length > 0) {
-                if (!args.position_filter.includes(position)) {
-                    continue;
-                }
-            }
-            availablePlayers.push({
-                player_id: playerId,
-                name: player.name?.full || 'Unknown',
-                position: position,
-                team: player.editorial_team_abbr || '',
-                selected_position: ['FA'], // Free agent
-                status: player.status,
-                percent_owned: parseFloat(player.percent_owned?.value || '0'),
-                stats: this.parsePlayerStats(player)
-            });
-            // Limit to top available players
-            if (availablePlayers.length >= (args.max_recommendations || 10) * 2) {
-                break;
-            }
-        }
+        // The pool is already resolved NHL players; there is no platform payload
+        // left to traverse.
         return {
-            availablePlayers,
-            roster: this.parseRoster(roster),
-            scoreboard: scoreboard
+            availablePlayers: rawData.pool ?? [],
+            roster: rawData.roster ?? undefined,
+            poolCaveat: rawData.pool_caveat
         };
     }
     /**
@@ -98,8 +48,8 @@ export class StreamingAnalysis extends AnalysisTemplate {
         const streamingRecommendations = [];
         // Analyze each available player
         for (const player of data.availablePlayers || []) {
-            // Calculate games this week (simplified - would use actual schedule in production)
-            const gamesThisWeek = this.estimateGamesThisWeek(player, lookAheadDays);
+            // Real games in the look-ahead window for this player's actual club
+            const gamesThisWeek = this.countGamesThisWeek(player, lookAheadDays);
             // Determine pickup priority based on games and ownership
             let pickupPriority;
             let reasoning;
@@ -156,6 +106,10 @@ export class StreamingAnalysis extends AnalysisTemplate {
             reasoning: analysis.reasoning
         }));
         const analysisInsights = {
+            pool_caveat: data.poolCaveat,
+            schedule_source: this.scheduleAvailable()
+                ? `NHL public API (season ${NHL_SCHEDULE.getSeason()})`
+                : `UNAVAILABLE - ${NHL_SCHEDULE.getUnavailableReason()}; game counts shown as 0`,
             streaming_summary: {
                 total_recommendations: streamingData.length,
                 high_priority_count: streamingData.filter(s => s.pickup_priority === 'HIGH' || s.pickup_priority === 'CRITICAL').length,
@@ -216,13 +170,23 @@ export class StreamingAnalysis extends AnalysisTemplate {
         };
     }
     /**
-     * Helper: Estimate games this week for a player
+     * Helper: Count this player's real club games in the look-ahead window.
+     *
+     * Every player used to return the same number here, which made the
+     * "4 games this week, low ownership" branch unreachable in practice.
+     * Returns 0 when the schedule is unavailable so no player is promoted on
+     * imaginary volume; `scheduleAvailable()` reports why.
      */
-    estimateGamesThisWeek(player, lookAheadDays) {
-        // Simplified calculation - in production would use actual NHL schedule
-        // Average NHL team plays 3-4 games per week
-        const gamesPerWeek = 3.5;
-        return Math.round((lookAheadDays / 7) * gamesPerWeek);
+    countGamesThisWeek(player, lookAheadDays) {
+        if (!NHL_SCHEDULE.isAvailable())
+            return 0;
+        const start = NhlScheduleService.today();
+        const end = NhlScheduleService.addDays(start, Math.max(0, lookAheadDays - 1));
+        return NHL_SCHEDULE.countGamesInRange(player.team, start, end);
+    }
+    /** Whether recommendations in this run were backed by the real schedule. */
+    scheduleAvailable() {
+        return NHL_SCHEDULE.isAvailable();
     }
     /**
      * Helper: Describe recent performance

package/build/analyses/WeekendStreamAnalysis.js

@@ -20,15 +20,12 @@
  */
 import { AnalysisTemplate } from '../template/AnalysisTemplate.js';
 import { ChirpIntelligence } from '../services/ChirpIntelligence.js';
+import { NHL_SCHEDULE, NhlScheduleService } from '../services/NhlScheduleService.js';
+import { LEAGUE_DATA, LeagueDataService } from '../services/LeagueDataService.js';
+import { NHL_STATS } from '../services/NhlStatsService.js';
 export class WeekendStreamAnalysis extends AnalysisTemplate {
-    yahooClient;
-    leagueId;
-    teamId;
-    constructor(yahooClient, leagueId, teamId) {
+    constructor() {
         super('analyze_weekend_streams', 'streaming_recommendations');
-        this.yahooClient = yahooClient;
-        this.leagueId = leagueId;
-        this.teamId = teamId;
     }
     /**
      * Semantic Identity for this analysis
@@ -75,28 +72,27 @@ CHIRP STYLE: desperate_or_legit
      * - Trending players
      */
     async fetchData(args) {
-        const ownershipMax = args.ownership_max || 50;
         const positions = args.position_filter || ['C', 'LW', 'RW', 'D', 'G'];
-        // Fetch free agents across requested positions
-        const freeAgentPromises = positions.map(pos => this.yahooClient.searchPlayers(pos, 50, this.leagueId));
-        const [freeAgentResults, roster, trendingAdds] = await Promise.all([
-            Promise.all(freeAgentPromises),
-            this.yahooClient.getTeamRoster(this.leagueId, this.teamId),
-            this.yahooClient.getTrendingPlayers('add', 25, this.leagueId)
-        ]);
-        // Combine and deduplicate free agents
-        const allFreeAgents = [];
-        for (const result of freeAgentResults) {
-            if (result.players) {
-                allFreeAgents.push(...result.players);
+        await Promise.all([NHL_STATS.load(), NHL_SCHEDULE.load(), NHL_SCHEDULE.loadStandings()]);
+        // One pool per requested position, deduplicated — replaces the Yahoo
+        // free-agent search. Ownership is league-private, so these are candidates
+        // to check rather than confirmed adds.
+        const seen = new Set();
+        const freeAgents = [];
+        for (const pos of positions) {
+            for (const p of LEAGUE_DATA.getPlayerPool({ position: pos, limit: 40 })) {
+                if (seen.has(p.player_id))
+                    continue;
+                seen.add(p.player_id);
+                freeAgents.push(p);
             }
         }
-        const uniqueFreeAgents = Array.from(new Map(allFreeAgents.map(p => [p.player_id, p])).values()).filter(p => (p.percent_owned || 0) <= ownershipMax);
         return {
-            freeAgents: uniqueFreeAgents,
-            roster,
-            trendingAdds: trendingAdds.players || [],
-            dateRange: args.date_range
+            freeAgents,
+            roster: LEAGUE_DATA.getRoster(),
+            trendingAdds: [],
+            dateRange: args.date_range,
+            pool_caveat: LeagueDataService.POOL_CAVEAT
         };
     }
     /**
@@ -108,16 +104,16 @@ CHIRP STYLE: desperate_or_legit
     async prepareData(rawData, args) {
         // Identify roster gaps
         const rosterGaps = this.identifyRosterGaps(rawData.roster, args);
-        // Get weekend schedules for each free agent
-        // (In real implementation, would fetch NHL schedule API)
-        const weekendSchedules = this.mockWeekendSchedules(rawData.freeAgents, rawData.dateRange);
+        // Real weekend schedules from the NHL public API
+        const weekendSchedules = this.buildWeekendSchedules(rawData.freeAgents, rawData.dateRange);
         // Return with custom properties attached
         const result = {
             availablePlayers: rawData.freeAgents,
             roster: rawData.roster,
             trendingPlayers: rawData.trendingAdds,
             rosterGaps: rosterGaps,
-            weekendSchedules: weekendSchedules
+            weekendSchedules: weekendSchedules,
+            poolCaveat: rawData.pool_caveat
         };
         return result;
     }
@@ -163,27 +159,25 @@ CHIRP STYLE: desperate_or_legit
         };
     }
     /**
-     * Layer 3: Mock weekend schedules
-     * (In production, integrate with NHL Schedule API)
+     * Layer 3: Real weekend schedules from the NHL public API.
+     *
+     * Each candidate gets the games their actual club actually plays in the
+     * requested window — including whether those games are back-to-back, which
+     * is a real signal for goalies rather than a coin flip.
      */
-    mockWeekendSchedules(players, dateRange) {
+    buildWeekendSchedules(players, dateRange) {
         const schedules = new Map();
+        const start = dateRange?.start ?? NhlScheduleService.today();
+        const end = dateRange?.end ?? NhlScheduleService.addDays(start, 2);
         for (const player of players) {
-            // Mock 1-3 weekend games
-            const gameCount = Math.floor(Math.random() * 3) + 1;
-            const games = [];
-            for (let i = 0; i < gameCount; i++) {
-                games.push({
-                    date: dateRange.start,
-                    opponent: this.getRandomOpponent(player.team),
-                    home: Math.random() > 0.5
-                });
-            }
+            const games = NHL_SCHEDULE.isAvailable()
+                ? NHL_SCHEDULE.getGamesInRange(player.team, start, end)
+                : [];
             schedules.set(player.player_id, {
                 player_id: player.player_id,
-                games,
-                game_count: gameCount,
-                has_back_to_back: gameCount >= 2 && Math.random() > 0.7
+                games: games.map(g => ({ date: g.date, opponent: g.opponent, home: g.home })),
+                game_count: games.length,
+                has_back_to_back: NHL_SCHEDULE.isAvailable() && NHL_SCHEDULE.countBackToBacks(player.team, start, end) > 0
             });
         }
         return schedules;
@@ -305,31 +299,86 @@ CHIRP STYLE: desperate_or_legit
         return 'monitor';
     }
     /**
-     * Layer 3: Evaluate player metrics
+     * Layer 3: Evaluate player metrics from Yahoo's real stats.
+     *
+     * Season stats give the baseline, last-month stats give the current form,
+     * and the projection weights recent form 60/40 over the season line. Where a
+     * player has no stats at all (a true unknown), `has_stats` is false and the
+     * caller can see the score rests on schedule and role signals only —
+     * previously this method returned `Math.random()` and nothing said so.
      */
     async evaluateMetrics(player, data) {
-        // Mock metrics - in production, fetch real stats
+        const dataAny = data;
         const isTrending = data.trendingPlayers?.some((t) => t.player_id === player.player_id);
-        const basePerformance = Math.random() * 0.8 + 0.2; // 0.2 - 1.0 PPG
-        const recent_ppg = basePerformance;
-        const projected_fpg = isTrending ? basePerformance * 1.15 : basePerformance;
-        // TOI estimate (higher for better players)
-        const ownership = player.percent_owned || 0;
-        const opportunity_toi = 10 + (ownership / 100) * 10 + Math.random() * 5; // 10-25 min
+        // v4: NHL season statistics ride on the player. There is no public source
+        // of recent-form splits, so form weighting is not applied — the season
+        // line is the projection basis, and `games_sampled` says so.
+        const season = player.stats ?? null;
+        const seasonPoints = (season?.goals ?? 0) + (season?.assists ?? 0);
+        const recentPoints = seasonPoints;
+        const seasonGames = season?.games_played ?? 0;
+        const recentGames = 0;
+        const hasStats = seasonGames > 0 || recentGames > 0;
+        const seasonPpg = seasonGames > 0 ? seasonPoints / seasonGames : 0;
+        const recentPpg = recentGames > 0 ? recentPoints / recentGames : seasonPpg;
+        // Weight current form over the season baseline, but only when there is
+        // enough recent sample to mean anything.
+        const formWeight = recentGames >= 3 ? 0.6 : 0;
+        const projectedBase = (formWeight * recentPpg) + ((1 - formWeight) * seasonPpg);
+        const projected_fpg = isTrending ? projectedBase * 1.15 : projectedBase;
         return {
-            recent_ppg,
-            projected_fpg,
-            opportunity_toi,
-            pp_role: opportunity_toi > 18 ? 'PP1' : opportunity_toi > 15 ? 'PP2' : 'None',
-            line_position: opportunity_toi > 16 ? 'Top-6' : 'Bottom-6'
+            has_stats: hasStats,
+            recent_ppg: Number(recentPpg.toFixed(3)),
+            season_ppg: Number(seasonPpg.toFixed(3)),
+            games_sampled: { season: seasonGames, recent: recentGames },
+            projected_fpg: Number(projected_fpg.toFixed(3)),
+            opportunity_toi: this.estimateOpportunity(player, season, null),
+            pp_role: this.derivePowerPlayRole(season, null, seasonGames, recentGames),
+            line_position: projectedBase >= 0.5 ? 'Top-6' : 'Bottom-6'
         };
     }
+    /**
+     * Fantasy points proxy from a labelled stat line.
+     * Uses Yahoo's own points category when the league reports it, otherwise
+     * reconstructs it from goals and assists.
+     */
+    /**
+     * Opportunity signal on the 0-25 scale the upside formula expects.
+     *
+     * Yahoo does not expose time on ice in standard league stat lines, so this
+     * derives opportunity from observable production volume (shots per game) and
+     * power-play involvement rather than inventing a minutes figure.
+     */
+    estimateOpportunity(player, season, _recent) {
+        const games = season?.games_played ?? 0;
+        if (games === 0)
+            return 0;
+        const shotsPerGame = (season?.shots ?? 0) / games;
+        const ppPointsPerGame = (season?.power_play_goals ?? 0) / games;
+        // Shot volume scaled to ~0-15, power-play involvement worth up to ~10.
+        const shotComponent = Math.min(15, shotsPerGame * 5);
+        const ppComponent = Math.min(10, ppPointsPerGame * 40);
+        return Number((shotComponent + ppComponent).toFixed(1));
+    }
+    /** Power-play role inferred from actual power-play production. */
+    derivePowerPlayRole(season, _recent, seasonGames, recentGames) {
+        const games = seasonGames || recentGames;
+        if (games === 0)
+            return 'Unknown';
+        const ppp = season?.power_play_goals ?? 0;
+        const perGame = ppp / games;
+        if (perGame >= 0.35)
+            return 'PP1';
+        if (perGame >= 0.12)
+            return 'PP2';
+        return 'None';
+    }
     /**
      * Layer 1: Analyze schedule ease
      */
     analyzeScheduleEase(schedule, player) {
         if (schedule.game_count === 0) {
-            return { ease_score: 0, matchup_quality: 'average' };
+            return { ease_score: 0, matchup_quality: 'unknown' };
         }
         // Base score on game count
         let easeScore = schedule.game_count * 30;
@@ -339,8 +388,16 @@ CHIRP STYLE: desperate_or_legit
         // Penalty for back-to-back
         if (schedule.has_back_to_back)
             easeScore -= 10;
-        // Opponent strength (mock - in production use team rankings)
-        const opponentStrength = Math.random() * 100;
+        // Opponent strength from real NHL standings (goals allowed per game, ranked).
+        // 0 = softest defence to face, 100 = stingiest.
+        const opponentStrength = this.averageOpponentDifficulty(schedule);
+        if (opponentStrength === null) {
+            // No standings data - rate on schedule volume alone rather than guessing.
+            return {
+                ease_score: Math.max(0, Math.min(100, easeScore)),
+                matchup_quality: 'unknown'
+            };
+        }
         if (opponentStrength < 30) {
             easeScore += 20; // Weak opponent
         }
@@ -479,12 +536,19 @@ CHIRP STYLE: desperate_or_legit
         };
     }
     /**
-     * Generate random opponent (mock)
+     * Mean defensive difficulty of the opponents on this weekend slate.
+     * Returns null when standings are unavailable, so the caller can decline to
+     * rate the matchup rather than invent a rating.
      */
-    getRandomOpponent(excludeTeam) {
-        const teams = ['BOS', 'CAR', 'COL', 'DAL', 'EDM', 'FLA', 'NYR', 'TOR', 'VGK', 'WPG'];
-        const filtered = teams.filter(t => t !== excludeTeam);
-        return filtered[Math.floor(Math.random() * filtered.length)];
+    averageOpponentDifficulty(schedule) {
+        if (!NHL_SCHEDULE.hasStandings() || schedule.games.length === 0)
+            return null;
+        const ratings = schedule.games
+            .map(game => NHL_SCHEDULE.getTeamStrength(game.opponent)?.difficulty)
+            .filter((d) => typeof d === 'number');
+        if (ratings.length === 0)
+            return null;
+        return ratings.reduce((sum, d) => sum + d, 0) / ratings.length;
     }
     /**
      * Generate chirp intelligence

package/build/config/tool-metadata.js

@@ -109,5 +109,73 @@ export const TOOL_METADATA = {
         intent_category: "market_intelligence",
         hockey_context: "waiver_trends",
         chirp_potential: "trend_opportunities"
+    },
+    chirp_opponent: {
+        chirp_style: "savage_trash_talk",
+        discovery_tags: ["opponent", "chirp", "trash_talk", "weaknesses", "rivalry"],
+        intent_category: "psychological_warfare",
+        hockey_context: "head_to_head_dominance",
+        chirp_potential: "opponent_destruction"
+    },
+    set_roster: {
+        chirp_style: "analytical_assessment",
+        discovery_tags: ["roster", "paste", "setup", "players", "import"],
+        intent_category: "league_state_capture",
+        hockey_context: "roster_definition",
+        chirp_potential: "roster_reality"
+    },
+    set_opponent_roster: {
+        chirp_style: "matchup_assessment",
+        discovery_tags: ["opponent", "paste", "matchup", "scouting", "import"],
+        intent_category: "league_state_capture",
+        hockey_context: "head_to_head_battle",
+        chirp_potential: "opponent_weaknesses"
+    },
+    set_standings: {
+        chirp_style: "competitive_reality",
+        discovery_tags: ["standings", "paste", "league", "rankings", "import"],
+        intent_category: "league_state_capture",
+        hockey_context: "competitive_landscape",
+        chirp_potential: "standings_truth"
+    },
+    show_stored_data: {
+        chirp_style: "analytical_assessment",
+        discovery_tags: ["state", "stored", "roster", "debug", "inspect"],
+        intent_category: "league_state_capture",
+        hockey_context: "roster_analysis",
+        chirp_potential: "state_visibility"
+    },
+    schedule_value: {
+        chirp_style: "strategic_advantage",
+        discovery_tags: ["draft", "schedule", "playoff_weeks", "games_per_week", "tiebreaker"],
+        intent_category: "draft_intelligence",
+        hockey_context: "schedule_warfare",
+        chirp_potential: "schedule_domination",
+        // 🆕 Template Pattern Metadata
+        uses_template_pattern: true,
+        analysis_class: "ScheduleValueAnalysis",
+        template_version: "1.0.0",
+        analysis_type: "schedule_advantage"
+    },
+    chirp_draft_pick: {
+        chirp_style: "ice_cold_truth",
+        discovery_tags: ["draft", "pick", "ADP", "value", "roster_build"],
+        intent_category: "draft_intelligence",
+        hockey_context: "draft_day_decisions",
+        chirp_potential: "draft_reality",
+        is_ice_engine: true,
+        tool_semantic_identity: "ICE - Intent Chirp Engine (Draft)",
+        // 🆕 Template Pattern Metadata
+        uses_template_pattern: true,
+        analysis_class: "DraftPickAnalysis",
+        template_version: "1.0.0",
+        analysis_type: "draft_pick"
+    },
+    analyze_trade: {
+        chirp_style: "trade_verdict",
+        discovery_tags: ["trade", "analysis", "value", "categories", "decision"],
+        intent_category: "trade_intelligence",
+        hockey_context: "roster_maneuvering",
+        chirp_potential: "trade_reality"
     }
 };

package/build/domain/nhl-teams.js

@@ -0,0 +1,67 @@
+/**
+ * 🏒 NHL Team Identity — Yahoo ↔ NHL abbreviation mapping
+ *
+ * 🏛️ Rule 3 (Observable Anchoring): a team's identity is anchored to its NHL
+ * tricode, which is the only abbreviation the NHL public API answers to.
+ * Yahoo publishes a *different* set of abbreviations for the same 32 clubs
+ * (`LA` vs `LAK`, `NJ` vs `NJD`, `SJ` vs `SJS`, `TB` vs `TBL`, `StL` vs `STL`).
+ *
+ * Comparing Yahoo's abbreviation directly against an NHL tricode silently fails
+ * for those five clubs — the player simply looks like they never play. Every
+ * crossing of that boundary must go through `toNhlTricode`.
+ */
+/** The 32 NHL tricodes as the public API spells them. */
+export const NHL_TRICODES = [
+    'ANA', 'BOS', 'BUF', 'CAR', 'CBJ', 'CGY', 'CHI', 'COL',
+    'DAL', 'DET', 'EDM', 'FLA', 'LAK', 'MIN', 'MTL', 'NJD',
+    'NSH', 'NYI', 'NYR', 'OTT', 'PHI', 'PIT', 'SEA', 'SJS',
+    'STL', 'TBL', 'TOR', 'UTA', 'VAN', 'VGK', 'WPG', 'WSH'
+];
+const TRICODE_SET = new Set(NHL_TRICODES);
+/**
+ * Yahoo `editorial_team_abbr` values that differ from the NHL tricode,
+ * plus a few historical/alternate spellings seen in the wild.
+ * Keys are compared upper-cased.
+ */
+const ALIAS_TO_TRICODE = {
+    // Yahoo's short forms — the five that silently break naive comparison
+    LA: 'LAK',
+    NJ: 'NJD',
+    SJ: 'SJS',
+    TB: 'TBL',
+    STL: 'STL', // StL upper-cases cleanly, listed for intent
+    // Alternate spellings / other providers
+    LV: 'VGK',
+    VEG: 'VGK',
+    WAS: 'WSH',
+    WSH: 'WSH',
+    CLS: 'CBJ',
+    CLB: 'CBJ',
+    MON: 'MTL',
+    NAS: 'NSH',
+    CAL: 'CGY',
+    TBL: 'TBL',
+    ARI: 'UTA', // Arizona relocated to Utah
+    PHX: 'UTA',
+    UTA: 'UTA',
+    UTAH: 'UTA'
+};
+/**
+ * Normalize any provider's team abbreviation to an NHL tricode.
+ * Returns `null` for unknown or missing input rather than guessing — callers
+ * must decide what an unmappable team means for their analysis.
+ */
+export function toNhlTricode(abbr) {
+    if (!abbr)
+        return null;
+    const upper = String(abbr).trim().toUpperCase();
+    if (!upper)
+        return null;
+    if (TRICODE_SET.has(upper))
+        return upper;
+    return ALIAS_TO_TRICODE[upper] ?? null;
+}
+/** True when the abbreviation resolves to a real NHL club. */
+export function isKnownTeam(abbr) {
+    return toNhlTricode(abbr) !== null;
+}