Novolis Docs
novolis-geopolitics / layering.md

Layering (Economy-aligned academic split)

Full-world geopolitics engines

dotnetgeopoliticssimulationnovolis

novolis-geopolitics follows the same layering discipline as `Novolis.Economy`: a pure kernel that settles stocks from policy, a set of independent engine packages that each own one causal domain, and a composition root that wires them together into a day/month tick.

┌───────────────────────────────────────────────────────────────────────┐
│  novolis-apps/src/GeoPolity  — UI / headless (presentation)           │
└──────────────────────────────────▲────────────────────────────────────┘
                                    │ observes WorldState + WorldSimulation.Telemetry
┌──────────────────────────────────┴────────────────────────────────────┐
│  Novolis.Geopolitics.Simulation  — composition root                   │
│  Day tick → month: Trade → CivicPipeline → TreatyEffects → PolicyAgent │
└──────┬───────────┬───────────┬───────────┬───────────┬────────────────┘
       │            │           │           │           │
       ▼            ▼           ▼           ▼           ▼
┌───────────┐ ┌───────────┐ ┌────────┐ ┌────────────┐ ┌───────────┐
│ Conflict  │ │ Diplomacy │ │ Trade  │ │PolicyAgents│ │ Scenarios │
│ (battles) │ │(treaties, │ │(clear- │ │(heuristic  │ │(procedural│
│           │ │ orgs, war)│ │  ing)  │ │ policy)    │ │ world, seed)│
└─────┬─────┘ └─────┬─────┘ └───┬────┘ └──────┬─────┘ └─────┬─────┘
      │             │           │             │             │ (also → Diplomacy)
      └─────────────┴───────────┴─────────────┴─────────────┘
                                 │ calls pure settlement
                    ┌────────────┴────────────┐
                    │  Novolis.Geopolitics.Core │
                    │  Polity + StateFiscalPolicy + CivicState │
                    │  CivicEngine.ApplyMonth (the only settlement) │
                    │  GovernmentRules, WorldState, WorldTelemetry, │
                    │  Provinces, relations, treaties, wars (records) │
                    └───────────────────────────┘

Why five engine packages instead of one

Each engine package owns exactly one causal domain and depends on nothing but Core (PolicyAgents also depends on Diplomacy, to propose treaties and wars):

PackageCausal domainDepends on
Novolis.Geopolitics.ConflictDaily battle resolution over war frontsCore
Novolis.Geopolitics.DiplomacyTreaty/org lifecycle, acceptance rules, monthly treaty effectsCore
Novolis.Geopolitics.TradeDomestic production, common-market and world-market clearingCore
Novolis.Geopolitics.PolicyAgentsHeuristic fiscal-policy adjustment and diplomacy proposalsCore, Diplomacy
Novolis.Geopolitics.ScenariosProcedural world generation, seed schema, institution seedingCore, Diplomacy

None of these packages depends on Simulation. Simulation depends on all of them and on Core, and its only original logic is CivicPipeline (context-building for CivicEngine) plus the day tick that decides when each engine runs.

This means any engine package can be unit-tested, versioned, or replaced independently, exactly as Novolis.Economy.Production or Novolis.Economy.Logistics can be tested independently of Novolis.Economy.Simulation.

Economy relationships (mapped)

Economy CoreGeoPolity Core
State + StatePolicy (tax / transfer)Polity + StateFiscalPolicy
Period fiscal settlementCivicEngine.ApplyMonth
Household welfare / capacityTransfers → approval; infrastructure → HumanDevelopment
Solvency / liquidity stressTreasury < 0 → legitimacy/stability penalty
Resource holdings / shortagesResourceVector Balance → approval and growth drag
Out of Core: production ops, logistics, marketsOut of Core: conflict, diplomacy, trade, policy agendas

Civics kinship (novolis-civics)

CivicEngine.ApplyMonth delegates nation stock–flow to `Novolis.Civics.Core` and applies force-domain growth from ForceCapabilityDemand. Cash conservation remains Economy; territory/war remain Geopolitics.

Month order (why)

  1. Trade (TradeClearing.RunMonth) — domestic + common-market + world-market write Balance

so shortages are visible before civic settlement.

  1. Civic (CivicPipeline.RunMonth → CivicEngine.ApplyMonth) — tax collection capacity,

transfers, spend, civic stocks, GDP growth.

  1. Treaty effects (TreatyEffects.RunMonth) — economic-partnership GDP, research catch-up,

aid transfers, alliance relation floor. These nudge civic stocks lightly but do not replace settlement.

  1. Policy agents (HeuristicPolicyAgent.RunMonth) — adjusts StateFiscalPolicy and proposes

diplomacy for next period; does not recompute this period's legitimacy.

Daily (not monthly): treaty expiry, bilateral-relation drift, and one ConflictResolver battle attempt per active war.

Non-goals in Core

  • UI meters that bypass stock–flow settlement
  • Diplomatic acceptance heuristics or war-declaration chain reactions
  • Combat resolution
  • Resource-market clearing
  • Policy heuristics or interactive control
  • Procedural generation or seed data

Each of these lives in exactly one package above Core, and only one.