refactor(contract)!: class_id -> calling_id, and the log gains race_id

class_id is the rulebook's word; the world has callings — that was the whole §17
reconcile. The contract the Narrator reads should say what the world says. There
are no saves (M9) and no deployed clients, so this is as cheap as it will ever be
and strictly more expensive every milestone after.

race_id reaches the log because the AI must be able to describe the player:
api/app/prompts.py rendered 'a sellsword' and now renders 'a beastfolk cutpurse'.
It humanizes the id (the model must never read 'hedge_mage') and picks the right
article ('an elf', not 'a elf').

LogPlayer's hardcoded CLASSES const is deleted — the roster is Callings.IDS. A
parity test reads the JSON Schema from the client and asserts its enum equals the
code, so the two sides of the HTTP boundary cannot drift.

The deserter allowed three callings that no longer exist. He now allows all seven;
a thematic gate is a content decision for the Greywater authoring.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QYa9u7Kdxv5gX4AnwWexy8

api/app/prompts.py

@@ -12,6 +12,23 @@ from pathlib import Path
 _PROMPT_DIR = Path(__file__).resolve().parent.parent / "prompts"
 
 
+def _humanize(id_: str) -> str:
+    """Ids are snake_case; the model should read prose. hedge_mage -> hedge-mage."""
+    return id_.replace("_", "-")
+
+
+def _article(word: str) -> str:
+    return "an" if word[:1].lower() in "aeiou" else "a"
+
+
+def _describe_player(player: dict) -> str:
+    """'Aldric, a beastfolk cutpurse' — what the AI narrates the player as."""
+    race = _humanize(player.get("race_id", ""))
+    calling = _humanize(player.get("calling_id", ""))
+    name = player.get("name", "")
+    return f"{name}, {_article(race)} {race} {calling}".strip()
+
+
 @lru_cache(maxsize=None)
 def system_prompt(role: str) -> str:
     text = (_PROMPT_DIR / f"{role}.md").read_text(encoding="utf-8")
@@ -50,7 +67,7 @@ def render_digest(canon_log: dict) -> str:
     descriptor = player.get("luck_descriptor")
     if descriptor:
         lines.append(f"Fortune: {descriptor}")
-    lines.append(f"Player: {player.get('name', '')}, a {player.get('class_id', '')}")
+    lines.append(f"Player: {_describe_player(player)}")
 
     lines.append("")
     lines.append("Describe the scene as it is now.")
@@ -104,7 +121,7 @@ def render_npc_digest(
             lines.append(f"Active quest: {quest.get('name', '')} — {quest.get('objective', '')}")
 
     player = canon_log.get("player", {})
-    lines.append(f"The player is {player.get('name', '')}, a {player.get('class_id', '')}.")
+    lines.append(f"The player is {_describe_player(player)}.")
 
     lines.append("")
     lines.append(f'The player says to you: "{utterance}"')

api/tests/fixtures/canon_log_valid.json

@@ -2,7 +2,8 @@
   "schema_version": 1,
   "player": {
     "name": "Aldric",
-    "class_id": "sellsword",
+    "race_id": "human",
+    "calling_id": "sellsword",
     "luck_descriptor": "Fortune spits on you"
   },
   "location": { "id": "greywater_docks", "name": "the Greywater docks" },

api/tests/test_live_smoke.py

@@ -30,7 +30,8 @@ def test_live_npc_speak_fenn():
     log = {
         "player": {
             "name": "Aldric",
-            "class_id": "sellsword",
+            "race_id": "human",
+            "calling_id": "sellsword",
             "luck_descriptor": "the dice are kind",
         },
         "location": {"id": "greywater_docks", "name": "Greywater Docks"},

api/tests/test_npc.py

@@ -4,7 +4,7 @@ import app.npc as npc
 from app.ollama_client import ModelError
 
 LOG = {
-    "player": {"name": "Aldric", "class_id": "sellsword", "luck_descriptor": "kind"},
+    "player": {"name": "Aldric", "race_id": "human", "calling_id": "sellsword", "luck_descriptor": "kind"},
     "location": {"id": "greywater_docks", "name": "Greywater Docks"},
     "party": [], "recent_events": [], "established_facts": [],
     "active_quests": [], "humiliations": [],

api/tests/test_origin_schema.py

@@ -14,7 +14,7 @@ VALID_ORIGIN = {
     "inventory_grants": [{"item_id": "worn_shortsword", "qty": 1}],
     "start_quest_id": "find_the_ledger",
     "build_constraints": {
-        "allowed_classes": ["sellsword", "assassin", "priest"],
+        "allowed_callings": ["sellsword", "cutpurse", "bonesetter"],
         "luck_modifier": 0,
     },
 }
@@ -32,7 +32,7 @@ def test_null_start_quest_is_allowed():
 
 def test_unknown_class_is_rejected():
     doc = copy.deepcopy(VALID_ORIGIN)
-    doc["build_constraints"]["allowed_classes"] = ["bard"]
+    doc["build_constraints"]["allowed_callings"] = ["bard"]
     assert validate_origin(doc) != []
 
 

api/tests/test_prompts.py

@@ -22,7 +22,7 @@ def test_digest_has_the_narrative_context():
     assert "Companions present: Brannoc Thane, Cadwyn Vell" in d
     assert "Active quest: The Missing Ledger — Find who took Fenn's ledger" in d
     assert "Fortune: Fortune spits on you" in d
-    assert "Player: Aldric, a sellsword" in d
+    assert "Player: Aldric, a human sellsword" in d
     assert d.rstrip().endswith("Describe the scene as it is now.")
 
 
@@ -42,10 +42,32 @@ def test_narrator_body_is_authored():
     assert "second person" in body    # the core task is present
 
 
+def _with_player(**player) -> dict:
+    log = json.loads(json.dumps(VALID))   # deep copy — VALID is module-level and shared
+    log["player"] = {"luck_descriptor": "the dice are kind", **player}
+    return log
+
+
+def test_digest_names_the_race_and_the_calling():
+    out = render_digest(_with_player(name="Aldric", race_id="beastfolk", calling_id="cutpurse"))
+    assert "Aldric, a beastfolk cutpurse" in out
+
+
+def test_digest_says_an_elf_not_a_elf():
+    out = render_digest(_with_player(name="Aldric", race_id="elf", calling_id="sellsword"))
+    assert "an elf sellsword" in out
+
+
+def test_digest_does_not_leak_a_snake_case_id():
+    out = render_digest(_with_player(name="Aldric", race_id="human", calling_id="hedge_mage"))
+    assert "hedge_mage" not in out, "the model must never read a raw snake_case id"
+    assert "hedge-mage" in out
+
+
 def test_render_npc_digest_includes_all_sections():
     from app import prompts
     log = {
-        "player": {"name": "Aldric", "class_id": "sellsword", "luck_descriptor": "the dice are kind"},
+        "player": {"name": "Aldric", "race_id": "human", "calling_id": "sellsword", "luck_descriptor": "the dice are kind"},
         "location": {"id": "greywater_docks", "name": "Greywater Docks"},
         "party": [], "recent_events": ["a gull screamed"],
         "established_facts": ["the eastern bridge is out"],