Design — Rival AI (the Elder controller)

High-level design for rival-dynasty AI: how an opposing house decides what to do as a whole. The headline is that there is no separate rival-AI subsystem — a rival is just a dynasty whose topmost controller (the Elder) is running on Auto. This builds directly on the control model (../GAME_DESIGN.md §2, the player↔AI symmetry) and the controller layer (controllers.md, positions as domain-owning agents). It reacts to the world through the memory substrate (memory.md). Design doc — the model and its rules, not an implementation plan.

This is the last design pillar. It is deliberately small, because the heavy lifting was already done: if every position is a swappable brain behind a uniform socket (controllers.md §7), then a rival is the same machine with the top socket filled by a rule instead of a player.

The whole pillar in one sentence: rival AI is the Elder controller — the always-filled top of the controller stack — which sets the dynasty’s Agenda (a standing bias, not a task) from the seated character’s traits and the house’s memories, and issues the big orders that bias motivates. Player vs. rival is one Auto toggle on that seat.

1. Rival AI is the Elder controller, not a subsystem

There is no “enemy AI.” A rival dynasty is a dynasty exactly like yours, whose Elder seat is being driven by a rule instead of by you.

The control model already commits to symmetry: rivals are “not special-cased opponents with bespoke AI … it is literally the same machinery” (../GAME_DESIGN.md §2). Rival AI honours that by being one more controller — the highest one:

The Elder is the topmost controller, sitting above the cabinet (Treasurer, Trademaster, Marshal…) and the per-shop managers (controllers.md §1). Where a manager owns one shop’s profit, the Elder owns the whole house’s direction.
The Elder seat is always filled. Succession auto-passes it to the oldest living member; the only way to lack an Elder is to have no members at all, which is the hard loss (../GAME_DESIGN.md §6, dynasty.md §4). So every dynasty always has a top brain — which is why a house behaves as one coherent agent instead of a bag of independent shops.

Player vs. rival is a single Auto toggle

The Elder controller carries the same Auto switch as a building manager (controllers.md §2), one tier up:

Mode	Who sets the dynasty’s direction
Elder-Auto off (your dynasty, default)	you — you are the Elder’s brain
Elder-Auto on (every rival; optional for you)	the Elder controller runs the whole house

Flipping your own Elder to Auto hands the entire dynasty to the AI — the CK3 move of switching off the top of your own brain and watching the house run itself. Rivals simply ship with it on. There is no second code path: player and rival run the identical Elder controller, differing only in whose hand is on the toggle — exactly the symmetry §2 demands, now extended to the very top of the stack.

2. The Agenda — a standing bias, not a task

What does the Elder actually produce? Not commands. A bias.

The Agenda is a standing posture — a set of priority dials and grudge attitudes — that tints every other controller’s judgment. It is not a task: it never completes, is addressed to no one, and is never claimed. It is the dial the Elder sets; the house leans the way it points.

This is the one genuinely new concept the pillar adds, and it is the judgments-not-facts mechanism (controllers.md §5) lifted to the dynasty level. Concretely the Agenda holds two kinds of thing:

Priority dials — how much the house leans toward each pursuit: expansion (buy plots / open shops), politics (chase council & guild seats), military (raise troops, settle scores), wealth (hoard a war chest).
Attitudes — signed standing toward specific other dynasties (the grudges and alliances), sourced from the dynasty memory bank (memory.md §5).

The sub-controllers read the Agenda when they form judgments — and per the ECS rules a read needs no Enqueue. A manager weighing “switch this shop to swords?” reads high militaryBias + an enemy attitude and leans yes; the Treasurer reading a high expansionBias favours the buying budget over the war chest. The Agenda never does anything itself; it reweights everyone.

Goals are biases; the moves they motivate are orders

The distinction that makes this tractable:

	What it is	Mechanism
Agenda (goal)	a standing bias — “we’re a smithing house,” “we hate House Vane,” “hoard gold”	new — this doc
Order (move)	a discrete act the bias motivates — “buy that plot,” “muster against Vane,” “place a kin on the council”	existing — the order tier, `controllers.md` §3

So the Elder’s job is: set the Agenda (the new bias layer), and issue the big board-changing orders that Agenda motivates — not to re-do the sub-controllers’ work. A vengeful Agenda doesn’t attack anyone by itself; it raises militaryBias and the Vane attitude, and then the Elder issues a “muster against Vane” order to the Marshal — who, his own judgment already agreeing, accepts it without hesitation and spawns the labour. The grudge flows from a memory, through a bias, into the existing order + labour tiers. No new task machinery.

3. Who authors the Agenda — the Elder brain or the player

The Agenda is one component on the dynasty entity with two possible authors — the exact Auto-toggle symmetry of a shop manager, at the top of the stack:

Elder-Auto on (rivals): the Elder controller writes the Agenda, choosing the dials from the seated character’s traits (§4). This recompute is the rival AI.
Elder-Auto off (you, default): you write the Agenda. Which means the Agenda literally is your dynasty-strategy screen — those dials and target-attitudes are the UI you set to steer the house at a high level, while still running shops by hand if you like.

Same component, same readers, same effect on the machine — only the hand on the sliders differs. This keeps the player and the AI provably symmetric at the strategy layer, not just the task layer.

4. Personality, reaction, and succession come for free

The Elder picks its Agenda from two inputs, and both already exist as designed systems — so rival “personality” needs no bespoke AI:

The seated character’s traits (characters.md) set the baseline dials. A greedy/ambitious Elder runs the house toward wealth and politics; a cautious one hoards and consolidates. The Agenda is the office’s posture tinted by its occupant — the same hat-to-hat rule as every other controller.
The dynasty’s memories (memory.md) make it react to the world. A fresh WasBeaten against House Vane pushes militaryBias up and the Vane attitude down; the slight fades on its own, so postures cool unless renewed. The Elder is not running a fixed script — it answers to what has actually happened to the house.

Succession is a personality reroll

When the Elder dies, the seat passes to a member with different traits, so the recompute yields a different Agenda — the whole dynasty can pivot. And because facts persist in the dynasty memory bank while disposition rerolls with the new Elder’s traits (memory.md §2), you get the rich case for free: the family remembers the grudge, but the new heir decides whether to act on it. A forgiving successor sits on a feud his vengeful father would have prosecuted.

Recompute cadence

The Elder controller re-derives the Agenda on a slow tick (a daily or weekly pass — exact rate is balancing), reading traits + recent dynasty memories and resetting the dials. It is just another low-frequency system on TimeUpdateFrequency::Tick. That recompute is the rival AI’s heartbeat — between ticks the posture holds steady and the sub-controllers run against it.

5. No difficulty setting — the AI just does its best

There is deliberately no difficulty mode, and the reasoning is a genre stance:

This is a sandbox with no win condition (../GAME_DESIGN.md §1, §6) — Dwarf Fortress, not a scored campaign. In such a game “difficulty” can only mean handicapping the player, because the AI can’t realistically be made to out-think a human, and a cheating AI breaks the symmetry the whole design rests on.
So the Elder controller simply does its best with the dummy-then-fancy brain behind the same socket (controllers.md §7) — no secret bonuses, no rigged information.
If friction is ever wanted, it arrives as modifiers through the existing modifier system — e.g. an overload-style penalty, or an “everyone who dislikes you taxes your dealings” debuff sourced from opinion (memory.md §5) — never as a smarter or cheating brain. This is the CK3 / EU4 stance, and it costs nothing now because the modifier pipeline already exists.

Parked, not built: difficulty is a future modifier pack, not a mode toggle.

6. ⚠ Tensions with current code

No player/rival distinction exists at all. There is no PlayerComponent, no “this dynasty is mine” flag, no AI/human marker anywhere in the code. Dynasties are undifferentiated DynastyComponent entities (created only via a debug ImGui panel), and every dynasty-owned workshop is driven by the same hardwired WorkshopSystem brain. So today the game already runs N dynasties on one dumb shared policy — and none of them is the player. The Elder-controller + Auto-flag model is what introduces the distinction.
No Elder controller, no Agenda. The Elder office is sketched (../GAME_DESIGN.md §2, dynasty.md) but no controller, no dial-and-grudge AgendaComponent on the dynasty entity, and no recompute pass exist. This sits on top of the (also-greenfield) controller and position layers (controllers.md §8) — rival AI cannot be built before the Elder seat and the order tier it issues into exist.
Depends on the memory substrate. “React to the world” reads the dynasty memory bank, which does not exist yet (memory.md §7). The dummy Agenda (traits → dials by a constant) works without memory; the reactive Agenda does not.
The player-side Agenda is a new UI surface. Elder-Auto-off makes the Agenda the player’s dynasty-strategy screen (§3) — a panel that does not exist; today’s only dynasty UI is the debug creation panel.

7. Open questions & held notes (next pass)

The authoritative Agenda dial set (§2). The exact priority axes (expansion / politics / military / wealth here are illustrative) and how attitudes are keyed are a build/balancing decision, reconciled with the position roster (controllers.md §9).
Goal → order translation (§2). Which concrete orders a given Agenda emits, and how strongly, is the meat of the Elder brain — trivial for the dummy (“high expansion → occasionally order a plot purchase”), richer later. Same dummy-then-fancy socket as every controller.
Trait → dial mapping (§4). How specific traits set baseline dials is balancing; the dummy is “trait value × constant.”
Player Agenda UI (§3). The dynasty-strategy panel (dials + per-rival attitudes) is a real UI design, deferred with the rest of the player-facing controller UI (controllers.md §9, per-shop automation levels).
Difficulty as a modifier pack (§5). If ever wanted, designed then as modifiers, not now.
Inter-dynasty diplomacy. relationships.md confirms the base: attitudes stay memory-sourced (the Agenda reads them as-is), and marriage kinship is a relationship modifier the Agenda already responds to (no new input needed). Formal treaties/pacts beyond that are explicitly parked (relationships.md §6) as a future diplomacy layer — not built in 1.0.