import { getMunicipalityFederalBaseline, type MunicipalityFederalBaseline, } from '@/lib/bahiaElectionAggregates' import { ELECTION_YEAR_2014, ELECTION_YEAR_2018, ELECTION_YEAR_2022, HISTORICAL_SERIES_YEARS, } from '@/lib/electionResults' import { municipalityCatalog } from '@/lib/municipalityCatalog' import type { BahiaIdentityTerritory } from '@/lib/bahiaTerritories' import type { CampaignGoal } from '@/payload-types' /** * E8 "conta da cadeira" — derived electoral potential per municipality, built * entirely from the committed `bahia-federal-baseline.json` artifact (no DB * reads: pure functions over `getMunicipalityFederalBaseline`). Every * projection here is a documented, fixed formula — never a fitted model (see * the E8 plan's "rabbit holes vigiados": projection turning into a model). */ /** * Projected 2026 valid votes: weighted average of 2014/2018/2022 federal T1 * valid votes, weighting 2022 double (closer election, more predictive of * turnout composition). Documented as a fixed formula, not a forecast: * `(v2014 + v2018 + 2×v2022) / 4`. */ export const projectedValidVotes = (baseline: MunicipalityFederalBaseline): number => { const v2014 = baseline.validVotesByYear[String(ELECTION_YEAR_2014)] ?? 0 const v2018 = baseline.validVotesByYear[String(ELECTION_YEAR_2018)] ?? 0 const v2022 = baseline.validVotesByYear[String(ELECTION_YEAR_2022)] ?? 0 return (v2014 + v2018 + 2 * v2022) / 4 } /** * "Teto do campo" (field ceiling): 2022 T1 votes for the presidential * candidate of the field (#13) — a majoritarian race attracts far more of * the field's total vote than the fragmented federal-deputy quotient race, * so it stands in for "how many votes could the field plausibly get here". * Primary reading only (governador is a secondary cross-check surfaced by the * artifact, not blended in — assumption flagged for product validation in * the E8 plan). 2022-only by design — see `bahiaElectionAggregates.ts` for * why the committed artifact doesn't cut 2014/2018 majoritária too. */ export const fieldCeiling = (baseline: MunicipalityFederalBaseline): number => baseline.majoritarian2022?.president.votes ?? 0 /** * `fieldCeiling` scaled by the same turnout-growth factor used for * `projectedValidVotes` (projected ÷ observed 2022 valid votes), since the * ceiling itself has only one observed data point (2022). Falls back to the * unscaled ceiling when 2022 valid votes are unknown (avoids a divide-by-zero * blow-up rather than silently zeroing the projection). */ export const projectedFieldCeiling = (baseline: MunicipalityFederalBaseline): number => { const ceiling2022 = fieldCeiling(baseline) const validVotes2022 = baseline.validVotesByYear[String(ELECTION_YEAR_2022)] ?? 0 if (validVotes2022 <= 0) return ceiling2022 return ceiling2022 * (projectedValidVotes(baseline) / validVotes2022) } /** * Capture rate (diagnostic only, not a decomposition input): share of the * 2022 field ceiling that Solla's own candidacy actually captured. `null` * when the ceiling is unknown/zero rather than a misleading 0. */ export const captureRate = (baseline: MunicipalityFederalBaseline): number | null => { const ceiling = fieldCeiling(baseline) if (ceiling <= 0) return null const votes2022 = baseline.votesByYear[String(ELECTION_YEAR_2022)] ?? 0 return votes2022 / ceiling } /** * Intra-field share (diagnostic only): of the curated field's federal-deputy * nominal votes (`campoFederalVotesByYear`, `campoParties.ts`) in a given * year, what share went to Solla specifically. Available for all three * historical years (unlike `fieldCeiling`, which is majoritarian and * 2022-only). `null` when the field polled zero that year. */ export const intraFieldShare = (baseline: MunicipalityFederalBaseline, year: number): number | null => { const campo = baseline.campoFederalVotesByYear[String(year)] ?? 0 if (campo <= 0) return null const votes = baseline.votesByYear[String(year)] ?? 0 return votes / campo } export type RollOff = { /** (brancos+nulos DF) − (brancos+nulos majoritária), in votes. */ votes: number /** `votes` as a share of the federal-deputy T1 turnout, or null if turnout is unknown. */ percentOfTurnout: number | null } /** * Roll-off (diagnostic only): the DF race always shows more blank/null votes * than the majoritarian race in the same turnout — this is the gap, in votes * and as a share of comparecimento. 2022-only, same artifact limitation as * `fieldCeiling` above; `null` when either tally is missing for the slug. */ export const rollOff = (baseline: MunicipalityFederalBaseline): RollOff | null => { const majoritarian = baseline.majoritarian2022?.president const federalTally = baseline.federalTallyByYear[String(ELECTION_YEAR_2022)] if (!majoritarian || !federalTally) return null const dfBlankNull = federalTally.votosBranco + federalTally.votosNulo const majoritarianBlankNull = majoritarian.votosBranco + majoritarian.votosNulo const votes = dfBlankNull - majoritarianBlankNull const percentOfTurnout = federalTally.comparecimento > 0 ? votes / federalTally.comparecimento : null return { votes, percentOfTurnout } } export type MunicipalityPotential = { slug: string projectedValidVotes: number fieldCeiling2022: number projectedFieldCeiling: number captureRate2022: number | null intraFieldShareByYear: Record rollOff2022: RollOff | null } /** Assembles every derived metric above for one catalog municipality slug. */ export const computeMunicipalityPotential = (slug: string): MunicipalityPotential => { const baseline = getMunicipalityFederalBaseline(slug) const intraFieldShareByYear: Record = {} for (const year of HISTORICAL_SERIES_YEARS) { intraFieldShareByYear[year] = intraFieldShare(baseline, year) } return { slug, projectedValidVotes: projectedValidVotes(baseline), fieldCeiling2022: fieldCeiling(baseline), projectedFieldCeiling: projectedFieldCeiling(baseline), captureRate2022: captureRate(baseline), intraFieldShareByYear, rollOff2022: rollOff(baseline), } } /** `computeMunicipalityPotential` for every catalog municipality (435 slugs). */ export const computeAllMunicipalityPotentials = (): MunicipalityPotential[] => municipalityCatalog.map((entry) => computeMunicipalityPotential(entry.slug)) /** * Decomposes the state goal proportionally to each municipality's projected * field ceiling — `suggestedGoal_i = stateGoal × projectedFieldCeiling_i / Σ * projectedFieldCeiling` — NOT a composite formula folding in capture rate or * intra-field share (those stay diagnostic columns; see the E8 plan's * "rabbit holes vigiados"). `margin` on the `campaignGoals` global is * informational for the table (a safety reading for the coordination), it * does not change the decomposed value. * * Falls back to an even split when every ceiling is zero/unknown (e.g. an * empty potentials list slice) rather than producing `NaN` suggested goals. */ export const decomposeStateGoal = ( potentials: ReadonlyArray>, goals: Pick, ): Map => { const stateGoal = goals.stateGoal const totalCeiling = potentials.reduce((sum, entry) => sum + entry.projectedFieldCeiling, 0) const suggestedGoalBySlug = new Map() if (totalCeiling <= 0) { const even = potentials.length > 0 ? stateGoal / potentials.length : 0 for (const entry of potentials) suggestedGoalBySlug.set(entry.slug, even) return suggestedGoalBySlug } for (const entry of potentials) { suggestedGoalBySlug.set(entry.slug, stateGoal * (entry.projectedFieldCeiling / totalCeiling)) } return suggestedGoalBySlug } export type TerritorySanityWarning = { region: BahiaIdentityTerritory suggestedGoalTotal: number projectedValidVotesTotal: number /** suggestedGoalTotal / projectedValidVotesTotal — > 1 means the decomposed goal exceeds the projected electorate. */ ratio: number } /** * Sanity check (never blocking, per the plan): flags identity territories * (TI) where the decomposed suggested goals, summed, exceed the projected * valid-vote electorate of that territory — a signal that the decomposition * needs a human look (state goal too high, or ceilings skewed), never a * thrown error. Callers surface `warnAboveRatio` as an `CampaignInfoHint`, * not a validation failure. */ export const sanityCheckSuggestedGoalsByTerritory = ( entries: ReadonlyArray<{ region: BahiaIdentityTerritory suggestedGoal: number projectedValidVotes: number }>, { warnAboveRatio = 1 }: { warnAboveRatio?: number } = {}, ): TerritorySanityWarning[] => { const totalsByRegion = new Map< BahiaIdentityTerritory, { suggestedGoalTotal: number; projectedValidVotesTotal: number } >() for (const entry of entries) { const current = totalsByRegion.get(entry.region) ?? { suggestedGoalTotal: 0, projectedValidVotesTotal: 0, } current.suggestedGoalTotal += entry.suggestedGoal current.projectedValidVotesTotal += entry.projectedValidVotes totalsByRegion.set(entry.region, current) } const warnings: TerritorySanityWarning[] = [] for (const [region, totals] of totalsByRegion) { if (totals.projectedValidVotesTotal <= 0) continue const ratio = totals.suggestedGoalTotal / totals.projectedValidVotesTotal if (ratio > warnAboveRatio) { warnings.push({ region, ...totals, ratio }) } } return warnings } /** * Convenience end-to-end: computes every municipality's potential and * decomposes the state goal — the single entry point the dashboard/list/ * detail loaders need (`municipalityGoalAccount.ts`), keyed by slug for O(1) * per-municipality lookup instead of a linear scan. * * Deliberately does NOT run `sanityCheckSuggestedGoalsByTerritory` here: no * caller surfaces `TerritorySanityWarning`s yet (deferred to E12's TI layer * — see the E8 plan), so computing them on every dashboard/list/detail * request would be pure wasted work. Callers that need the check once E12 * lands can build the same `{ region, suggestedGoal, projectedValidVotes }` * entries from `potentialBySlug` + `municipalityCatalog` and call it * directly — it stays exported and unit-tested for that. */ export const computeStatewideGoalDecomposition = ( goals: Pick, ): { potentialBySlug: Map suggestedGoalBySlug: Map } => { const potentials = computeAllMunicipalityPotentials() const suggestedGoalBySlug = decomposeStateGoal(potentials, goals) const potentialBySlug = new Map(potentials.map((potential) => [potential.slug, potential])) return { potentialBySlug, suggestedGoalBySlug } }