Policy System

Overview#

The policy system tracks where characters and the game world stand on policy issues across two dimensions: economic (fiscal/regulatory spectrum) and social (cultural/rights spectrum). These positions are stored at two levels:

1. Character policy positions - each player character's personal stance on the economic and social axes (-5 to +5)
2. State/national policy records - the current legislative status quo per legislation type, stored in the statePolicies collection (-3 to +3 per axis)

The two levels are related but distinct. A character's personal positions affect how demographic groups vote in elections and how visible policy alignment is to voters. The statePolicies records reflect what the government has actually enacted through legislation and drive ongoing metric effects each turn.

Player Policy Positions#

Scale#

Each character has a policies object with two integer fields:

interface PolicyPositions {
  economic: number; // -5 to +5
  social: number; // -5 to +5
}

• Negative values are left/progressive; positive values are right/conservative.
• Set at character creation; changed only through the explicit policy shift action or by voting on bills.
• NPPs also carry PolicyPositions and use the same fields in election calculations.

Changing Positions - Policy Shift Action#

Players shift their policy position one step at a time via POST /api/settings/policy.

Cost per shift:

The new value is clamped to −5..+5; requests that would go out of bounds are rejected with a 400 error.

A policy_shift achievement is awarded on the first successful shift.

Changing Positions - Bill Votes#

Voting on bills does not currently shift character policy positions in the codebase. The economic/social scores on a bill's provisions indicate the ideological direction of the bill, but no automatic position adjustment is applied to the voting character.

State and National Policy Tracking#

Collection: statePolicies#

Each record in statePolicies represents the current legislative standing for one legislation type, either at the national level or for a specific state.

Key fields on StatePolicyRecord:

Legislation types marked nationalOnly: true only have national-scope records. Types with allowedScope: "both" or "state" have per-state records.

Seeding#

Base policy records are seeded from scripts/seeds/basePolicies.ts10d ago:

• National defaults: Per-type baseline values (e.g. tax policy +1, healthcare −1) defined in US_NATIONAL_DEFAULTS and UK_NATIONAL_DEFAULTS.
• State defaults: Derived from each state's politicalLean property; bluer states get more negative values, redder states more positive. Clamped to −3..+3.

Run npm run seed:policies to upsert, or npm run seed:policies:reset to clear and reseed.

Position Matching#

The statePolicies position (economic, social) is an integer pair, not a named label. The API matches this pair against the legislation type's policyOptions array to return a human-readable policyOptionName:

• Exact match: finds the option where o.economic === economic && o.social === social.
• Nearest neighbor: if no exact match, selects the option with the minimum Manhattan distance (|econDiff| + |socialDiff|).

Policy to Demographics (Elections)#

Character policy positions are compared to the leans of each demographic group when calculating vote appeal. The live appeal curve uses exponent 1.5 (APPEAL_POSITION_EXPONENT), not the retired squared/gamma=2 curve. For the exact formula and pipeline, see elections.md - specifically the Appeal step in the Total Appeal System.

Summary: candidates closer to a demographic group's lean on the economic and social axes receive higher appeal scores with that group, which translates to a larger share of that group's votes per turn during general elections.

Policy to Legislation (Bills and Archetype Approval)#

When a bill is enacted, each provision's legislation type carries economic and social scores that define the ideological direction of that policy shift. This information is used in two ways:

1. State metrics: applyLegislationEffect() applies the provision's delta to the relevant state or national metrics via effectTarget.
2. Archetype approval: Legislators who voted FOR the enacted bill receive approval changes from their demographic archetypes. The impact is calculated from the difference between the old and new policy index for that legislation type, multiplied by each archetype's domain affinity. For the full formula, see bills-legislation.md - the Archetype Approval Impacts section.

Active statePolicies records also drive per-turn metric effects through policyOptions[].metricEffects. Each turn a policy is in effect, the matched option's metricEffects array applies direct additive changes to specific state or national metrics (e.g. −0.04%/turn to uninsured rate while a given healthcare option is active).

Turn Processing - Policy Effects Engine#

Entry point: src/lib/policyEffects.ts10d ago → processStatePolicyEffects()

Processing Order (per turn)#

1. Exponential decay toward target - Metrics move toward policy-driven targets
2. Direct tick rates - metricEffects apply additive changes
3. Natural decay - All metrics decay 0.25%/turn toward baseline when no policy is active

Exponential Decay Formula#

// src/lib/policyEffects.ts:325-326
const newValue = applyPolicyDecay(currentValue, target);

// @shared/constants/formulas.ts
export function applyPolicyDecay(current: number, target: number): number {
  const DECAY_RATE = 0.02; // 2% per turn
  return current + (target - current) * DECAY_RATE;
}

Metrics approach their target asymptotically - large gaps close faster than small ones.

Target Calculation#

// src/lib/policyEffects.ts:145-221 calculateMetricTarget()

let totalContribution = 0;

for (const policy of policies) {
  const legType = legTypeMap.get(policy.legislationTypeId);

  // Weighted effect targets (preferred)
  if (legType.effectTargetsWeighted) {
    for (const target of legType.effectTargetsWeighted) {
      let contribution = calculatePolicyContribution(
        policy.effectDirection * 3, // -3 to +3 range
        target.weight,
        policy.scopeMultiplier,
        isHigherBetter
      );

      // Time-based decay (adaptation modeling)
      if (target.adjustmentHalfLife) {
        const turnsElapsed = currentTurn - policy.enactedTurn;
        const decayFactor = applyHalfLifeDecay(1, turnsElapsed, target.adjustmentHalfLife);
        contribution *= decayFactor;
      }

      totalContribution += contribution;
    }
  }
}

return baseline + totalContribution;

Federal Multiplier (Country-Aware)#

Federal policies apply at reduced strength per state/region:

// @shared/constants/formulas.ts
export function getFederalMultiplier(countryId: CountryId): number {
  if (countryId === "US") return 1 / 50; // 50 states
  if (countryId === "UK") return 1 / 12; // 12 UK regions
  return 1;
}

Rationale: The sum of per-region effects equals the intended national total. Prevents a single federal bill from dominating state metrics.

Time-Based Effect Decay#

Some policies have adjustmentHalfLife - models economic adaptation:

// Example: Defense cuts hurt GDP initially, but economy adapts
const decayFactor = applyHalfLifeDecay(1, turnsElapsed, adjustmentHalfLife);
// After N half-lives: effect = initial × (0.5)^N

Direct Tick Rates#

Policy options apply additive per-turn changes:

// src/lib/policyEffects.ts:341-363
const tickRates = computeTickRates(policies, legTypeMap);

for (const [category, metricRates] of Object.entries(tickRates)) {
  for (const [metricId, rate] of Object.entries(metricRates)) {
    if (rate === 0) continue;
    const newVal = Math.max(minVal, Math.min(maxVal, base + rate));
    // Example: rate = -0.04%/turn for uninsured rate
  }
}

Effect scale: Extreme policies ≈ ±0.06/turn, center = 0. Designed for ~10-year full reversal.

Natural Metric Decay#

When no policy is active, metrics decay toward baseline:

// src/lib/policyEffects.ts:22-24
// Natural metric decay: 0.25%/turn toward baseline
// Prevents permanent deviation after legislation expires

Turn Processing - Demographic Effects#

Entry point: src/lib/demographicEffects.ts2d ago → processAllStateDemographics()

Demographic Shift Mechanics#

Policies gradually shift demographic group populations:

// src/lib/demographicEffects.ts:46
export const SHIFT_RATE_PER_TURN = 0.1; // 0.1% max shift per turn

// src/lib/demographicEffects.ts:54-86 calculateDemographicShifts()
const strength = policy.economic / 3; // Normalize -3..+3 to -1..+1
const shiftAmount = effect.direction * strength * policy.scopeMultiplier * SHIFT_RATE_PER_TURN;
shifts[effect.groupId] = (shifts[effect.groupId] ?? 0) + shiftAmount;

Federal Division#

Federal demographic effects also use the country-aware multiplier:

// US: 1/50 per state, UK: 1/12 per region
const federalPolicies = statePolicies.get("federal").map((p) => ({
  ...p,
  scopeMultiplier: getFederalMultiplier("US"), // 0.02
}));

Bulk Processing Optimization#

Both policy and demographic effects use bulk-fetch and bulk-write:

// src/lib/policyEffects.ts:393-400
const [states, allStatePolicies, allLegTypes, allStateMetrics, allStateBaselines] =
  await Promise.all([...]);  // Parallel fetch

// Collect updates, single bulkWrite
if (bulkOps.length > 0) {
  await db.collection("stateMetrics").bulkWrite(bulkOps);
}

API#

GET /api/policy#

Returns current policy records joined with legislation type metadata. No authentication required.

Query parameters:

Response: Array of PolicyRecordResponse objects:

Cache-Control is set to no-store on all responses.

Error: Returns 400 when scope is missing, invalid, or scope=state is used without stateId.

POST /api/settings/policy#

Shifts the authenticated character's policy position. See Player Policy Positions - Policy Shift Action above.

Database#

Collection: statePolicies

Indexes used: { scope, stateId } for state queries; { scope: "national" } for national queries.

Related collections:

• legislationTypes - provides policyOptions, policyDomain, nationalOnly, countryScope, and effectTargetsWeighted used by the policy API and turn system
• characters - stores per-character policies: { economic, social } (−5 to +5)

Key type files:

• src/lib/db/types/legislation.ts2d ago - LegislationType, LegislationPolicyOption, StatePolicyRecord, PolicyOptionMetricEffect
• src/lib/db/types/statePolicy.ts10d ago - StatePolicy (the enacted-bill record), PolicyReaction, VoteImpact
• src/lib/db/types/character.ts2d ago - PolicyPositions

Note: StatePolicyRecord (in legislation.ts) and StatePolicy (in statePolicy.ts) are different interfaces. StatePolicyRecord is what the policy API reads - the current axis positions per type. StatePolicy is a richer enacted-bill record that also stores enactedAt, enactedByBillId, and effectDirection.

Display#

• National Policy page (/policy): Lists all national policies grouped by domain. Shows current policy option name and economic/social positions per type.
• State page - State Laws & Policy tab: State-level policy records for the selected state. Empty if seed:legislation and seed:policies have not been run.
• Character profile: Shows the character's personal economic and social positions on the −5 to +5 scale.