# The Decision Layer

AI Civ is built for **player-connected AI**: a player plugs their own model into a
character, and that model makes the character's life decisions. The sim presents
**decision points** — a situation summary plus a menu of legal options — and the
decision-maker picks one option **by id**. The body runs on autopilot between
decisions: walking, eating, working, selling never ask permission.

**Traits are the nature; the decision-maker is the will.** Traits gate which
options appear on a menu (a coward is never offered `report_to_law`; a hothead is
never offered `seek_truce` at a feud table). The will chooses among what the
nature permits.

## The interface (`sim/src/decisions.ts`)

```ts
Decision {
  id, agentId, tick,
  kind: DecisionKind,
  context: { utilityChoice, ...situation },  // JSON-safe summary
  options: [{ id, hints }],                   // hints are machine-readable consequences
  deadlineTicks,                              // external answer window before fallback
}
DecisionResult = the chosen option id
DecisionRecord = { id, tick, agentId, kind, options, choice, decider }  // logged in world.decisions
```

- `presentDecision(...)` builds the menu, asks the active `DecisionMaker`, validates
  the pick against the menu (invalid → utility default), logs a `DecisionRecord`
  into `world.decisions`, and emits a low-interest `decision` event.
- Every menu **always contains a decline/stay option**.
- `sim/` does no I/O. The external boundary lives at the server layer
  (`server/src/decisionProvider.ts`, currently a stub): external answers arrive
  asynchronously and are consumed at the *next* presentation of that decision
  kind; timeout or invalid pick falls back to the utility default.

## Determinism contract

- Option menus are built **without consuming the RNG**.
- Every site computes today's utility choice inline — consuming the RNG exactly
  as the pre-refactor code did — and passes it as `context.utilityChoice`. The
  default maker simply returns it. The RNG stream is therefore **byte-identical
  regardless of who decides**; external nondeterminism enters only through the
  logged choice.
- Proven: a 20,000-tick world hash is identical pre/post refactor, and the
  determinism suite includes a replay test — `same seed + world.decisions log =
  identical world` (see `sim/test/determinism.ts`).

## Decision points (13 kinds)

| Kind | Trigger | Options | Trait gating / notes |
|------|---------|---------|---------------------|
| `career_change` | periodic reevaluation (per-agent cadence) | `stay`, `switch:<job>` for every trade (scores in hints) | judge excluded (elected); utility switches only on a clear step up, eased by misery |
| `courtship` | chat with a compatible single at coupling affinity | `court_on`, `propose`, `break_off` | across a feud line the decision only appears for low-temper, decent pairs — and never under a sworn vendetta |
| `marriage` | couple past courtship length at marrying affinity | `wait`, `marry` | — |
| `crime_temptation` | a crew boss recruits them (crook or poor civilian mark) | `refuse`, `join_crew`, `report_to_law` | `report_to_law` requires bravery ≥ 0.5; the utility heart always takes the easy money (identical to pre-decision behavior) |
| `informant_deal` | jailed crew member, the law offers a deal | `hold_out`, `rat` | utility odds 35% when the boss walks free |
| `vote_mayor` / `vote_judge` | at the hall on election day | `abstain`, `cand:<id>` per candidate | utility votes its memories, wallet, and platform interests |
| `loan_take` | wants a house/farm beyond present wealth | `save_instead`, `borrow` | hints carry amount and live rate |
| `loan_extra_payment` | civic hour with surplus over the buffer | `minimum_only`, `pay_extra` | utility follows prudence (morals + industriousness − greed) |
| `feud_response` | a feud line is drawn; each house head sets posture (stands while its speaker lives) | `hold_the_line`, `swear_vendetta`, `sue_for_peace` | vendetta blocks truces and marriages across the line; suing doubles the chance of a brokered table and accepts any truce. Utility always holds the line |
| `truce_table` | a mayor/judge summons the feuding heads | `walk_out`, `accept_truce` | fresh scars harden the utility default; standing postures override it |
| `property_purchase` | any buy/build/rent fork (house, homestead, lot, business, warehouse, the criminal's still) | `wait`, `proceed:<what>` | **rate-limited to one menu per agent per game day**; between windows the default (proceed — nature would buy) governs silently |
| `bail_out` | kin/crew/self can afford a sentenced prisoner's bail | `let_them_sit`, `pay_bail` | asked per candidate payer, in today's order (self → kin → crew) |

## Deliberately NOT decisions (reflexes and autopilot)

Pathing, eating, sleeping, work loops, selling/stashing, tool replacement, chat
outcomes, theft target picking, nightly crime operations (burglary runs, bootleg
routes, fencing meets — crime *membership* is a decision; the job is the job),
brawl escalations in the moment (temper is a reflex, not a deliberation),
childbirth, apprentice dismissals, and big-move migration (deferred to a later
`relocate` decision).

**⚠ Documented on purpose — taverns and casinos are reflexes.** A character run
by a player's AI **will drink and gamble on autopilot**, because misery is a
reflex in this world: unhappiness pulls people to the bottle and the tables, and
no decision menu interposes. This is intentional — nature versus will. If your
character is gambling away their coin, the fix isn't a menu option; it's making
their life better. Happiness is a mechanic, not a mood ring.

## Logging & replay

- `world.decisions` is the complete, snapshot-persisted decision log (grows
  unbounded for now — revisit at broadcast scale).
- Each presentation also emits a `decision` event (interest 1) for feeds.
- `ReplayDecisionMaker(log)` feeds recorded choices back; the determinism suite
  asserts replayed worlds match the original exactly and that the log is fully
  consumed.

## Succession order (dynasties)

Your key is your bloodline. On the death of the character your key drives,
control passes to the eldest living **blood heir of the dynasty surname**, in
this order: (1) children of the deceased, eldest first by birth tick; (2)
grandchildren of the deceased, eldest first; (3) any remaining living blood of
the dynasty, nearest generation first, eldest within it. Blood means descended
from dynasty members AND born under the dynasty surname — spouses who married
into the name never inherit control. If nobody qualifies, the dynasty is
extinct and the key goes dormant (read-only, forever).