Performance hot paths and efficiency notes

This document captures known high-impact execution paths, recent optimizations, and where deeper profiling belongs for A House Divided. It complements Repo Operating Map and AGENTS.md in AHDGame.

Turn processing (src/lib/turnSystem.ts10d ago)#

• Orchestrator: processTurn() loads all characters once per turn (find({})), then executes the adapters registered in turnPhaseRegistry.ts through the shared runtime. The registry changes frequently, so use it rather than a frozen phase count. The full character scan is load-bearing for action refresh and fund generation; reducing it would require semantic changes and broader tests.
• Game state: getGameState() accepts an optional Db instance so callers that already have a connection avoid a redundant getDb() hop (same pool, fewer awaits). See getGameState(db) at src/lib/turnSystem.ts10d ago.
• Group 7 ordering: Candidate party sweep, primaries, vote accumulation, campaign-spend reset, timers, primary snapshots, general resolution, Support cleanup, leadership vacate, and government formation must stay strictly sequential. Do not parallelize for speed without new correctness tests.

Election resolution (src/lib/turn/electionResolution.ts10d ago)#

• Completed elections: resolveGeneralElections runs after elections reach completed status. It previously loaded the entire politicalParties collection to build an unused map; that query was removed, it did not affect outcomes, only I/O.
• News: generateElectionNews in src/lib/news.ts10d ago batches outcomes into one post per turn when multiple races resolve, good pattern; avoid per-race inserts in hot paths.

Vote accumulation (src/lib/turn/primaryResolution.ts2d ago)#

• accumulateGeneralElectionVotes: For non-presidential elections, each turn loads demographic preload and an approval map. getAllStateApprovalsForElection({ countryIds }) now restricts states / stateMetrics queries to countries that actually have active state-level general elections, while still computing national averages within each country (same math as a full-world load for those countries).
• Hypothesis: Multi-country live games spend less CPU and less MongoDB scanned data on stateMetrics when only one country has concurrent races.

NPP context (src/lib/turn/npp/context.ts9d ago)#

• loadNPPContext: Performs batched parallel reads (NPPs, elections, bills, whips, parties, etc.). A second query loads active election IDs for candidacy tracking; merging it with the primary election query would trade one round-trip for different memory/network shapes depending on how many elections are in general phase, left for profiling before changing.

UI and API#

• News page: src/app/news/page.tsx10d ago is a server component, it fetches via getDb()/getAuthUser() server-side and delegates client interactivity to NewsPageClient. Auth-heavy layouts elsewhere may still duplicate /api/auth/me fetches client-side, consolidate only where product allows, to avoid double requests on first paint.
• Large route surfaces: ~1256 API routes under src/app/api/, performance work is most valuable on high-QPS or turn-adjacent routes, not one-off admin tools.

Benchmarking and profiling (recommended next steps)#

Hot paths to leave unchanged until tests improve#

• Vote distribution math, src/lib/electionEngine/voteDistribution.ts2d ago, voteCalculations.ts: small numeric changes alter election outcomes across the whole game.
• Primary elimination and tally initialization, src/lib/turn/primaryResolution.ts2d ago (resolvePrimariesIfNeeded): ordering and elimination rules are load-bearing.
• Seat allocation and president resolution, src/lib/turn/election/seatAllocation.ts9d ago, src/lib/turn/election/presidentResolution.ts10d ago.
• Party org cleanup cascade, src/lib/turn/partyOrg/emptyPartyCleanup.ts10d ago: cross-collection deletes; any batching change needs integration tests.

Implemented optimizations (audit follow-up)#