Import verified AzerothAI snapshot from GitHub

Source branch: feature/ai-brain-router
Source commit: c2a09e0460465201a58aaab56c71424e9a96405e

docs/LIVING_WORLD.md

@@ -0,0 +1,158 @@
+# Living World, Housing, Population Direction, and Zaku Plot Armor
+
+## Principle
+
+Residents should experience Azeroth as their world, not as a simulation session.
+
+AzerothAI therefore separates two layers:
+
+- **Diegetic character context:** home, possessions, relationships, routines, goals, memories, danger, travel, work, social life.
+- **Operator/runtime context:** simulation bands, capacity budgets, connector state, plot armor, scheduling, infrastructure.
+
+Runtime-only facts must not be included in prompts or memories given to residents.
+
+## Housing
+
+Every seeded resident has a persistent home record.
+
+A home includes:
+
+- type: house, inn, barracks, guild housing, camp, or homeless
+- zone
+- capacity
+- residents
+- owners
+- storage capacity
+- safety rating
+- description
+
+A resident stores a `homeId` and routine. Moving home produces a normal in-world memory such as "I moved to..." rather than an infrastructure message.
+
+Zaku begins with a rented room in Brill.
+
+## World Population Director
+
+The population director implements the whiteboard flow:
+
+```
+EVENT TRIGGER
+  zone change / interaction / time / manual
+        |
+        v
+CAPACITY CHECK
+  zone max
+  server max
+  foreground AI budget
+  background AI budget
+        |
+        v
+VALIDITY / BELIEVABILITY
+  already in zone?
+  home in zone?
+  preferred zone?
+  personality fit?
+  alive / active identity?
+        |
+        v
+ACTIVATE OR ROUTE EXISTING RESIDENTS
+```
+
+The director does **not** create disposable people to fill a zone.
+
+If a zone wants six active residents but only three believable existing residents are available, it activates three and records the shortfall. New identities must be created through explicit population growth systems later.
+
+## Simulation bands
+
+Residents can exist at three simulation detail levels:
+
+- **foreground** — near the human player or in an important active scene; detailed decisions and conversations.
+- **background** — alive elsewhere in the world; lower-frequency decisions.
+- **dormant** — sleeping, inactive, or safely abstracted; life state persists without constant model inference.
+
+This lets a large persistent population exist on modest hardware without running an LLM for every resident every second.
+
+## Zaku plot armor
+
+Zaku is the one explicit exception to the normal Hardcore mortality mechanic.
+
+His runtime identity contains:
+
+```json
+{
+  "id": "hero-zaku",
+  "plotArmorHpFloor": 1
+}
+```
+
+This field is **runtime-only**. Do not place it in Zaku's LLM prompt, memory, dialogue context, biography, or observable world state.
+
+Zaku should believe the same thing other residents believe: death is possible and danger matters.
+
+### Required AzerothCore behavior
+
+The live worldserver/bridge must enforce the floor at the combat mechanics layer. AzerothAI cannot reliably prevent lethal damage after the fact.
+
+Conceptually:
+
+```text
+if character.plotArmorHpFloor > 0:
+    resolvedHp = max(character.plotArmorHpFloor, resolvedHp)
+    suppressDeathTransition()
+```
+
+For Zaku, any damage event that would normally produce 0 or negative HP must leave him at exactly 1 HP.
+
+The character can still:
+
+- lose a fight
+- flee
+- be crowd-controlled
+- run out of mana
+- suffer durability loss if normal mechanics produce it
+- remember near-death experiences
+- become more risk-averse
+
+He simply cannot enter the dead state.
+
+### Defense in depth
+
+AzerothAI also blocks death at the control-plane layer.
+
+If an operator attempts to record Zaku as permanently dead, the action is rejected.
+
+If the AzerothCore bridge reports Zaku as dead, AzerothAI treats it as a **plot armor breach**, records an error, preserves the identity, and refuses to write a death record.
+
+This protects Zaku from a bridge bug, but the live worldserver still needs the HP clamp so players never visually see him die.
+
+## AzerothCore lifecycle payload
+
+The bridge receives the runtime rule when a resident is spawned or managed:
+
+```json
+{
+  "identity": {
+    "id": "hero-zaku",
+    "name": "Zaku",
+    "race": "Undead",
+    "role": "Warlock",
+    "tier": "hero",
+    "mortal": true,
+    "plotArmorHpFloor": 1
+  }
+}
+```
+
+Normal residents use `plotArmorHpFloor: 0`.
+
+## Future work
+
+Next useful steps are:
+
+1. authoritative player-zone events from AzerothCore into `worldTrigger`
+2. interaction/hearing-radius triggers
+3. world-time scheduler that wakes residents and routes them home
+4. home storage and possessions
+5. travel-time-aware routing rather than immediate simulation relocation
+6. jobs, rent, households, inheritance, and estates
+7. capacity telemetry based on the actual mini-PC load
+8. near-death memories and risk psychology, especially for Zaku