valuationWorkflow.ts

import type {
  LeanPlayer,
  NormalizedValuationInput,
  ValuationResponse,
} from "../types/brain";
import { attachValuationExplainability } from "../lib/valuationExplainability";
import { logger } from "../lib/logger";
import { validateValuationResponse } from "../lib/valuationQuality";
import { DEFAULT_INFLATION_MODEL } from "../lib/valuationDefaults";
import { positionOverridesFromRequest } from "../lib/fantasyRosterSlots";
import {
  listUnsupportedScoringCategories,
  scoringCategorySupportWarnings,
} from "../lib/scoringCategorySupport";
import { calculateInflation } from "./inflationEngine";
import { DEFAULT_STAGE3B_CALIBRATION } from "./stage3bPitcherCalibration";
import { applyInjuryOverridesToPool } from "../lib/valuationInjuryOverrides";
import { scoringAwareBaselinePlayers } from "./baselineValueEngine";
import { filterValuationUniverse } from "../lib/valuationPlayerPool";
import { computeRemainingLeagueRosterSlots } from "../lib/remainingLeagueRosterSlots";
import { buildRosteredPlayersForSlotEngine } from "../lib/rosteredPlayersForSlots";
import {
  buildValuationContextMetrics,
  buildValuationContextWarnings,
} from "../lib/valuationContextGuards";
import {
  addTimingMs,
  nowMs,
  setCount,
} from "../lib/valuationRequestTiming";
import type { ValuationRequestDiagnostics } from "../lib/valuationRequestTiming";
import { isBaselineOutputCollapsed } from "../lib/catalogProjectionHealth";

const BASELINE_COLLAPSE_WARNING =
  "Baseline valuations are uniform across the eligible pool — upstream `projection.batting/pitching` data is likely empty for this catalog snapshot, so auction_value will not differentiate players. Re-run `pnpm sync-players` and restart the API process (catalog cache is in-process).";

/**
 * Valuation pipeline (course UML activity diagram — first pass mapping)
 *
 * 1. **Read league settings & draft state** — Done upstream: `NormalizedValuationInput`
 *    from Draft/fixtures (roster_slots, scoring_categories, budgets, drafted_players, …).
 * 2. **Read eligible player data** — `LeanPlayer[]` from Mongo (`Player`); long-term this
 *    should carry 3-year stats, age, role, injury signals populated by your analytics/sync
 *    pipeline (not an external valuation API). Optional **`injury_overrides`** on the request
 *    replace catalog `injurySeverity` per `player_id` before baseline (`applyInjuryOverridesToPool`).
 * 3. **Valuation universe** — `filterValuationUniverse` (`league_scope`, optional
 *    `eligible_player_ids` / `excluded_player_ids`) before baseline z-scores and inflation.
 *    **Filter drafted** — inside `calculateInflation` (drafted ids, minors/taxi, etc.).
 *    Optional `player_ids` only limits **returned rows**; inflation basis follows **`inflation_model`**
 *    (`global_v1`, `surplus_slots_v1`, or `replacement_slots_v2`; default **`replacement_slots_v2`**; see `docs/valuation-inflation-semantics.md`).
 * 4. **Choose scoring system** — Branch on `scoring_format`: `points` vs category-style
 *    (`5x5` / `6x6` / default). Baseline dollars are projection- and category-driven; Mongo
 *    `value` is a weak prior via `catalogValuePrior`.
 * 5. **Per-player projection & surplus** — Projections + scoring categories set list baselines;
 *    inflation pass scales to remaining auction dollars (market condition).
 * 6. **Convert to auction dollars** — `calculateInflation` → `adjusted_value`.
 * 7. **Validate reasonableness** — `validateValuationResponse` (finite, non-negative $, enums).
 *    UML “retry / adjust parameters” loop: extend here (recompute with caps) when you add
 *    tunable model parameters.
 */
export type ScoringMode = "points" | "rotisserie_categories";

export function resolveScoringMode(
  input: NormalizedValuationInput
): ScoringMode {
  if (input.scoring_format === "points") {
    return "points";
  }
  return "rotisserie_categories";
}

export type ValuationWorkflowResult =
  | { ok: true; response: ValuationResponse }
  | { ok: false; issues: string[] };

type ExtraDraftContext = {
  additionalSpent: number;
  additionalDraftedIds: string[];
};

function extractDraftedIdsAndSpend(input: NormalizedValuationInput): ExtraDraftContext {
  const ids = new Set<string>();
  let spent = 0;

  const collectUnknownRows = (rows: unknown[] | undefined) => {
    for (const row of rows ?? []) {
      if (typeof row !== "object" || row == null) continue;
      const rec = row as Record<string, unknown>;
      const pid = rec.player_id;
      if (typeof pid === "string" && pid.length > 0) ids.add(pid);
      const keeperCost = rec.keeper_cost;
      const paid = rec.paid;
      if (typeof keeperCost === "number" && Number.isFinite(keeperCost)) {
        spent += keeperCost;
      } else if (typeof paid === "number" && Number.isFinite(paid)) {
        spent += paid;
      }
    }
  };

  const collectBuckets = (
    buckets: NormalizedValuationInput["minors"] | NormalizedValuationInput["taxi"]
  ) => {
    if (!buckets) return;
    if (Array.isArray(buckets)) {
      for (const bucket of buckets) {
        collectUnknownRows(bucket.players as unknown[]);
      }
      return;
    }
    for (const v of Object.values(buckets)) {
      if (Array.isArray(v)) collectUnknownRows(v);
    }
  };

  if (input.pre_draft_rosters) {
    for (const rows of Object.values(input.pre_draft_rosters)) {
      collectUnknownRows(Array.isArray(rows) ? rows : []);
    }
  }
  collectBuckets(input.minors);
  collectBuckets(input.taxi);
  return { additionalSpent: spent, additionalDraftedIds: [...ids] };
}

/**
 * Runs inflation + steal/reach on the current pool. Scoring mode is resolved for logging
 * and future per-format baseline math; today both paths use the same `calculateInflation`.
 *
 * Post-calculation sanity checks use **fail-closed** semantics: invalid output returns
 * `ok: false` so the HTTP layer can respond with **422** and no price payload.
 */
export function executeValuationWorkflow(
  allPlayers: LeanPlayer[],
  input: NormalizedValuationInput,
  scope: { playerId?: string; position?: string } = {},
  options: { debugSignals?: boolean; diagnostics?: ValuationRequestDiagnostics } = {}
): ValuationWorkflowResult {
  const diag = options.diagnostics;

  const tFilter0 = diag ? nowMs() : 0;
  const valuationPool = filterValuationUniverse(allPlayers, {
    leagueScope: input.league_scope,
    eligiblePlayerIds: input.eligible_player_ids,
    excludedPlayerIds: input.excluded_player_ids,
  });
  if (diag) {
    addTimingMs(diag, "workflow_filter_universe_ms", tFilter0);
    setCount(diag, "valuation_eligible_count", valuationPool.length);
  }

  const positionOverrides = positionOverridesFromRequest(input.position_overrides);
  const unsupportedCats = listUnsupportedScoringCategories(input.scoring_categories);
  if (input.strict_scoring_categories && unsupportedCats.length > 0) {
    const names = unsupportedCats.map((c) => `${c.name} (${c.type})`).join(", ");
    return {
      ok: false,
      issues: [
        `Unsupported scoring categories for v1 baselines: ${names}. Remove them, set strict_scoring_categories to false to receive warnings instead, or extend engine stat wiring.`,
      ],
    };
  }
  const scoringCategoryWarnings =
    unsupportedCats.length > 0 ? scoringCategorySupportWarnings(unsupportedCats) : [];

  const tInj0 = diag ? nowMs() : 0;
  const poolWithInjury = applyInjuryOverridesToPool(
    valuationPool,
    input.injury_overrides
  );
  if (diag) addTimingMs(diag, "workflow_injury_overrides_ms", tInj0);

  const tBase0 = diag ? nowMs() : 0;
  const basePlayers = scoringAwareBaselinePlayers(
    poolWithInjury,
    input.scoring_format,
    input.scoring_categories,
    input.roster_slots,
    positionOverrides
  );
  if (diag) addTimingMs(diag, "workflow_scoring_aware_baseline_ms", tBase0);

  /*
   * Detect the "every player at $10" failure mode (production 2026-05-13). When the projection
   * blob upstream of `scoringAwareBaselinePlayers` is empty/uniform for the whole catalog, every
   * player gets the same baseline `value` and downstream inflation collapses to a degenerate
   * "everybody at the same price" response. We log the failure and pass it along as a context
   * warning instead of failing closed, so Draftroom keeps responding while operators see the
   * alert in App Runner logs.
   */
  const baselineCollapsed = isBaselineOutputCollapsed(basePlayers);
  if (baselineCollapsed) {
    logger.warn(
      {
        component: "valuationWorkflow",
        baseline_pool_size: basePlayers.length,
        baseline_collapsed: true,
      },
      "baseline valuations collapsed — projection inputs likely empty"
    );
    if (diag) setCount(diag, "baseline_pool_collapsed", 1);
  }

  const tSlot0 = diag ? nowMs() : 0;
  const extra = extractDraftedIdsAndSpend(input);
  const rosteredPlayersForSlots = buildRosteredPlayersForSlotEngine(input);
  const remainingLeagueSlots = computeRemainingLeagueRosterSlots(
    input.roster_slots,
    input.num_teams,
    input.drafted_players,
    extra.additionalDraftedIds
  );
  if (diag) addTimingMs(diag, "workflow_slot_context_ms", tSlot0);

  const retryPlan = [
    { inflationCap: 3.0, inflationFloor: 0.25 },
    { inflationCap: 3.0, inflationFloor: 0.35 },
    { inflationCap: 2.5, inflationFloor: 0.5 },
  ];
  let lastIssues: string[] = [];

  for (let i = 0; i < retryPlan.length; i++) {
    const pass = retryPlan[i];
    const tInfl0 = diag ? nowMs() : 0;
    const response = calculateInflation(
      basePlayers,
      input.drafted_players,
      input.total_budget,
      input.num_teams,
      input.roster_slots,
      input.league_scope,
      {
        deterministic: input.deterministic,
        seed: input.seed,
        playerIdsFilter: input.player_ids,
        budgetByTeamId: input.budget_by_team_id,
        userTeamId: input.user_team_id,
        additionalSpent: extra.additionalSpent,
        additionalDraftedIds: extra.additionalDraftedIds,
        inflationCap: pass.inflationCap,
        inflationFloor: pass.inflationFloor,
        inflationModel: input.inflation_model ?? DEFAULT_INFLATION_MODEL,
        auctionCurveModel: input.auction_curve_model,
        remainingLeagueSlots,
        rosteredPlayersForSlots,
        debugSignals: options.debugSignals,
        explainValuationRows: input.explain_valuation_rows === true,
        recommendedBidSoftCapRatio: input.recommended_bid_soft_cap_ratio,
        positionOverrides,
        hybridSurplusCalibration: input.hybrid_surplus_calibration,
        stage3bCalibration:
          input.stage3b_calibration ?? DEFAULT_STAGE3B_CALIBRATION,
        openingBoardCalibration: input.opening_board_calibration,
        inflationPhaseTimings: diag?.timings_ms,
      }
    );
    if (diag) addTimingMs(diag, "workflow_calculate_inflation_ms", tInfl0);

    const quality = validateValuationResponse(response);
    if (quality.ok) {
      if (diag) setCount(diag, "inflation_retry_pass_index", i + 1);
      if (i > 0) {
        logger.warn(
          { pass: i + 1, component: "valuationWorkflow" },
          "valuation recovered after bounded recompute"
        );
      }
      const rosterDemandSlots = response.remaining_slots ?? 0;
      const valuation_context = buildValuationContextMetrics({
        eligiblePoolSize: valuationPool.length,
        rosterDemandSlots,
      });
      const ctxWarnList = buildValuationContextWarnings({
        eligiblePoolSize: valuationPool.length,
        rosterDemandSlots,
        customEligibleUniverse: (input.eligible_player_ids?.length ?? 0) > 0,
        rosteredPlayers: rosteredPlayersForSlots,
      });
      if (baselineCollapsed) {
        ctxWarnList.push(BASELINE_COLLAPSE_WARNING);
      }
      const responseWithContext: ValuationResponse = {
        ...response,
        valuation_context,
        ...(ctxWarnList.length > 0
          ? { valuation_context_warnings: ctxWarnList }
          : {}),
      };
      const tEx0 = diag ? nowMs() : 0;
      const explained = attachValuationExplainability(
        responseWithContext,
        input,
        basePlayers,
        scope,
        {
          inflationOptions: {
            deterministic: input.deterministic,
            seed: input.seed,
            budgetByTeamId: input.budget_by_team_id,
            additionalSpent: extra.additionalSpent,
            additionalDraftedIds: extra.additionalDraftedIds,
            inflationCap: pass.inflationCap,
            inflationFloor: pass.inflationFloor,
            auctionCurveModel: input.auction_curve_model,
            rosteredPlayersForSlots,
            positionOverrides,
          },
        }
      );
      if (diag) addTimingMs(diag, "workflow_attach_explain_ms", tEx0);
      let merged: ValuationResponse = {
        ...explained,
        ...(scoringCategoryWarnings.length > 0
          ? { scoring_category_warnings: scoringCategoryWarnings }
          : {}),
      };
      if (input.explain_valuation_rows) {
        const ratio = valuation_context.pool_to_slot_ratio;
        merged = {
          ...merged,
          valuations: merged.valuations.map((v) => {
            if (!v.valuation_explain) return v;
            return {
              ...v,
              valuation_explain: {
                ...v.valuation_explain,
                pool_size: valuationPool.length,
                roster_demand_slots: rosterDemandSlots,
                pool_to_slot_ratio: ratio,
                ...(scoringCategoryWarnings.length > 0
                  ? { scoring_category_warnings: scoringCategoryWarnings }
                  : {}),
                ...(ctxWarnList.length > 0
                  ? { valuation_context_warnings: ctxWarnList }
                  : {}),
              },
            };
          }),
        };
      }
      if (diag) {
        setCount(diag, "response_valuation_rows", merged.valuations.length);
      }
      return {
        ok: true,
        response: merged,
      };
    }
    lastIssues = quality.issues;
  }

  logger.warn(
    { issues: lastIssues, component: "valuationWorkflow" },
    "valuation output validation failed (422)"
  );
  return { ok: false, issues: lastIssues };
}