sagaphone/spec/event-system.md

# Event System

See [Data Model](data-model.md) for the `Event`, `EventEntry`, `Stage` types
this section builds on.

## Death Probability per Stage

Before every event, a roll decides whether the person dies. A minimum number
of events per stage must happen before death is even possible. Past that
minimum, the probability rises with a `magic_factor`.

```
death_probability = death_at_stage[stage]
Generate events until the person dies.
minimum_events = events_per_stage[stage]
if current_event_count > events_per_stage[stage]:
    death_probability += (current_event_count - events_per_stage[stage]) * magic_factor
```

**Starting values (to be tuned via playtesting):**

| Stage       | Min. Events | Base Death % |
|-------------|-------------|--------------|
| Child       | 2           | 30%          |
| Teen        | 3           | 10%          |
| Young Adult | 3           | 25%          |
| Adult       | 3           | 35%          |
| Senior      | 3           | 60%          |

Person 1 (the ancestor / `is_ancestor = True`) is guaranteed to survive every
stage — no early death for them.

## Event Categories

1. **Death** — events leading to death (only rolled if death was decided).
2. **Partnership** — love, marriage, engagement, political engagement,
   childhood promise.
3. **Offspring** — birth, complications (mother dies giving birth),
   twins/triplets.
4. **Daily Life** — daily routine, family interactions, temporary characters.
5. **Travel** — the person travels, experiences things, temp characters
   possible.
6. **Learning** — formative learning, training, profession.
7. **Conflict/Fight** — not fatal for the active person.
8. **Discovery** — object, spell, natural wonder etc. (boosted probability
   after travel).
9. **Local Conflict** — rebellion, crisis, natural disaster, and how the
   person handles it.
10. **Intrigue** — political intrigue, social conflict.
11. **Illness/Injury** — not fatal, but formative.

## Event Tables

Concrete fantasy events per category, used during simulation (Phase 1). Each
entry represents a possible `result`/`context` payload for a given `Event`
type. The LLM receives these as narrative input during Phase 2.

### Category 1 — Death

| Event Type | Description | Notes |
|---|---|---|
| DEATH_ILLNESS | Succumbs to a long illness | Can follow ILLNESS_CHRONIC |
| DEATH_ACCIDENT | Fatal accident (e.g. fall, fire, drowning) | Higher chance in CHILD stage |
| DEATH_COMBAT | Killed in a fight or battle | Can follow CONFLICT_FIGHT or LOCAL_REBELLION |
| DEATH_OLD_AGE | Dies peacefully of old age | Senior stage only |
| DEATH_CHILDBIRTH | Mother dies giving birth | Triggers active node switch to newborn if mother was the active node |

### Category 2 — Partnership

| Event Type | Description | Notes |
|---|---|---|
| PARTNER_MARRIAGE | Formal marriage ceremony | From TEEN stage onwards |
| PARTNER_AFFAIR | Secret or open love affair | May produce illegitimate children |
| PARTNER_ENGAGEMENT | Formal betrothal, not yet married | Can be broken off by later event |
| PARTNER_POLITICAL | Arranged marriage for political gain | Often initiated by parent |
| PARTNER_CHILDHOOD_PROMISE | Two children swear to marry one day | Can be fulfilled or broken later |

### Category 3 — Offspring

| Event Type | Description | Notes |
|---|---|---|
| CHILD_BORN | A healthy child is born | Sets child's birth_year |
| CHILD_TWINS | Twin birth | Two new Person objects created |
| CHILD_TRIPLETS | Triplet birth | Three new Person objects created |
| CHILD_STILLBORN | Child is born dead | No new Person object; affects parents narratively |
| CHILD_ADOPT | Person adopts a child | Only path to offspring for NONBINARY; possible for all genders at reduced weight. From YOUNG_ADULT onwards. |

### Category 4 — Daily Life

| Event Type | Description | Notes |
|---|---|---|
| DAILY_FRIENDSHIP | Forms a meaningful friendship | New person added to acquaintances |
| DAILY_FAMILY | Notable interaction with a family member | Uses existing person from tree |
| DAILY_TEMP_CHAR | Encounter with a temporary character | New person added to person_pool |

### Category 5 — Travel

| Event Type | Description | Notes |
|---|---|---|
| TRAVEL_NEAR | Journey to a nearby village or town | location_is_temp = True |
| TRAVEL_FAR | Long journey to a distant land | Increases follow_bonus for DISCOVER_* |
| TRAVEL_PILGRIMAGE | Religious or spiritual journey | May trigger LEARN_SELF or DISCOVER_WONDER |

### Category 6 — Learning

| Event Type | Description | Notes |
|---|---|---|
| LEARN_APPRENTICESHIP | Begins formal training under a master | Sets profession |
| LEARN_MENTOR | Gains wisdom from an older figure | May use existing acquaintance as mentor |
| LEARN_SELF | Self-taught skill or insight | Often follows TRAVEL or DISCOVER |

### Category 7 — Personal Conflict

| Event Type | Description | Notes |
|---|---|---|
| CONFLICT_PERSONAL | Serious argument or falling out | Can involve family or acquaintance |
| CONFLICT_FIGHT | Physical altercation, non-fatal | May leave injury (INJURY_COMBAT follow) |
| CONFLICT_FEUD | Long-running grudge with a person or family | Can span multiple stages |

### Category 8 — Discovery

| Event Type | Description | Notes |
|---|---|---|
| DISCOVER_OBJECT | Finds a curious or valuable object | Object stored in result.item |
| DISCOVER_SPELL | Stumbles upon a magical formula or ritual | Higher chance if LEARN_SELF preceded |
| DISCOVER_WONDER | Witnesses a natural or supernatural wonder | Often follows TRAVEL_FAR |
| DISCOVER_KNOWLEDGE | Uncovers a secret, history, or forbidden lore | May trigger INTRIGUE follow events |

### Category 9 — Local Conflict

| Event Type | Description | Notes |
|---|---|---|
| LOCAL_REBELLION | A local uprising disrupts daily life | Person may flee, fight, or hide |
| LOCAL_PLAGUE | Disease sweeps through the region | Increases death probability for all |
| LOCAL_DISASTER | Natural disaster (flood, fire, earthquake) | May destroy home or kill acquaintances |
| LOCAL_CRISIS | Economic or political crisis in the region | Affects profession and home stability |

### Category 10 — Intrigue

| Event Type | Description | Notes |
|---|---|---|
| INTRIGUE_POLITICAL | Person becomes entangled in a power struggle | Higher chance for persons with political partners |
| INTRIGUE_EXILE | Person is banished from home or community | Changes person.home |
| INTRIGUE_CONSPIRACY | Person is targeted by a secret group | May follow DISCOVER_KNOWLEDGE |

### Category 11 — Illness & Injury

| Event Type | Description | Notes |
|---|---|---|
| ILLNESS_WEAK | Mild illness, recovers quickly | Minimal long-term effect |
| ILLNESS_SEVERE | Serious illness, leaves a mark | May set a permanent trait in appearance |
| ILLNESS_CHRONIC | Ongoing condition affecting daily life | Stored as permanent result flag |
| INJURY_ACCIDENT | Hurt in an accident | Higher chance after TRAVEL or LOCAL_DISASTER |
| INJURY_COMBAT | Wounded in a fight | Follows CONFLICT_FIGHT or LOCAL_REBELLION |

## Follow Bonus Map

Some events make certain follow-up events more likely, stored in
`EventEntry.follow_bonus`.

| Trigger Event | follow_bonus |
|---|---|
| TRAVEL_FAR | DISCOVER_OBJECT, DISCOVER_WONDER |
| TRAVEL_PILGRIMAGE | DISCOVER_WONDER, LEARN_SELF |
| CONFLICT_FIGHT | INJURY_COMBAT |
| LOCAL_REBELLION | DEATH_COMBAT, INJURY_COMBAT, INTRIGUE_EXILE |
| LOCAL_PLAGUE | DEATH_ILLNESS, ILLNESS_SEVERE |
| LOCAL_DISASTER | INJURY_ACCIDENT, INTRIGUE_EXILE |
| DISCOVER_KNOWLEDGE | INTRIGUE_CONSPIRACY, INTRIGUE_POLITICAL |
| PARTNER_POLITICAL | INTRIGUE_POLITICAL |
| LEARN_APPRENTICESHIP | LEARN_MENTOR |
| ILLNESS_CHRONIC, ILLNESS_SEVERE | DEATH_ILLNESS |
| INJURY_COMBAT | ILLNESS_SEVERE, DEATH_COMBAT |

See [Implementation Notes](implementation-notes.md) for the concrete weight
calculation (`get_effective_chance`) and stage-lock rules that gate which
events are even eligible.