fix(openworlds): persist house + biography in engine snapshot (Closes #383)

[100yenadmin]

TL;DR

Loop-10 follow-up to #277. PR #369 wired house + biography from the Creation wizard's inputs into the bindHero spec, but the engine seating path silently dropped both fields at FIVE sites: the Character model, create_character's signature, the Character() constructor call, play.sh's spec-to-create_character bridge, and the /character-surface projection. A player who authored House = "Three Bells" + Biography = "..." in the wizard saw both vanish the moment they hit Bind.

This PR threads both fields end-to-end + adds the UI rendering + the regression test the parent issue's AC5 asked for.

Closes

• fix(openworlds): persist house + biography in engine snapshot (Loop 10 follow-up to #277) #383 — Loop-10 follow-up: persist house + biography in engine snapshot

The five sites threaded

#	File	What
1	servers/engine/models.py	Character model gains house: str = "" and biography: str = "" in the identity block. _StrictModel rejects extra fields — adding them at the model is what makes accepting these kwargs possible.
2	servers/engine/server.py	create_character signature accepts both kwargs (positional callers stay working) + the Character(...) constructor call threads them inside campaign_lock.
3	scripts/play.sh	The embedded Python that translates the bindHero spec into create_character kwargs now reads both fields from the spec dict with "" coalesce. This is the single place where the wizard's prose crosses the process boundary into the engine.
4	viewer/server.py	_character_sheet projects "house" and "biography" to the /character-surface read-model via _text() for string safety.
5	viewer/openworlds/screen-character.jsx	(a) Hero header card renders subtle italic "of House {hero.house}" line under the name when set. (b) LineagePanel renders a "Biography" section with eyebrow label + whiteSpace: pre-wrap paragraph when set. Both honest-empty otherwise.

Tests

New: servers/engine/tests/test_house_biography_persistence.py — 4 tests

Test	Asserts
test_create_character_accepts_house_and_biography_kwargs	Sanity: no TypeError on call
test_house_and_biography_persist_on_the_character_model	Both fields survive the save_campaign round-trip inside create_character (asserted via get_state)
test_house_and_biography_default_to_empty_when_omitted	Existing call sites (NPC spawn without new kwargs) keep working; defaults are "" not None
test_house_and_biography_round_trip_through_get_state	End-to-end: explicit values → snapshot dict → fields intact + pre-existing identity (race, background) still works alongside

Tests follow the canonical pattern from test_action_economy.py + test_adversarial_release.py (server.create_campaign(name)["id"]).

Verification

Check	Result
ast.parse on all 5 modified .py + new test	✅
Brace + paren balance screen-character.jsx	✅ 652/652, 540/540
Snapshot round-trip via existing _StrictModel ser/de	✅ (no custom dump/load needed; plain str = "")
Local pytest	NOT RUN (per CLAUDE.md: ClawDnD-val is not on the test-execution allowlist; GitHub CI is the verification path)

Acceptance criteria (per #383)

• ☑ Pydantic field added (house, biography)
• ☑ create_character signature accepts both kwargs
• ☑ play.sh threads both from spec to create_character
• ☑ /character-surface projects both
• ☑ screen-character.jsx renders both
• ☑ Pytest asserts the contract end-to-end (4 tests: kwargs accept, persistence, defaults, round-trip)

Out of scope (intentionally)

• BACKSTORY MERGE: the issue body called out that fix(openworlds): persist house + biography in engine snapshot (Loop 10 follow-up to #277) #383 should NOT rename personality/backstory or merge biography into them. These remain DISTINCT fields with distinct sources. Lineage prose from engine-side flavor stays in lineageNote; player-authored biography stays in biography.
• Player-rename mid-play: this PR seeds house+bio at character creation time. No update_character path here — out of scope until a "rename / edit your hero" affordance lands.
• Companion / NPC house + biography: the model now CARRIES the fields for all characters, but only the player wizard authors them today. Companions/NPCs default "".

Collision audit

File	Last touched on main	Overlap with this PR
servers/engine/models.py	#355 (max_hp)	Zero — different field section
servers/engine/server.py	#355 (max_hp)	Zero — different signature region
scripts/play.sh	#360 (DM resolver fallback)	Zero — different Python block
viewer/server.py	#370 (#286 feats fix)	Zero — different sheet section
viewer/openworlds/screen-character.jsx	#364 (#308 #288)	Zero — conditionally-rendered nodes only appear when fields are set
Main agent's open #388	—	DM/cold-open territory; zero overlap

DO NOT MERGE yet

Per owner direction. CI will verify pytest correctness. Ready for review.

Refs

• Closes fix(openworlds): persist house + biography in engine snapshot (Loop 10 follow-up to #277) #383 (Loop-10 follow-up)
• Parent [openworlds-audit] Creation: Family/House field and Biography textarea are not passed to bindHero #277 (Creation wizard wires the fields; PR fix(openworlds): create — #277 #281 #315 #369 closed the viewer half)
• Completes the engine half of the chain PR fix(openworlds): create — #277 #281 #315 #369 started

Summary by CodeRabbit

Release Notes

• New Features
  • Players can now add a house affiliation and personal biography to their characters.
  • The character's house displays as a subtitle beneath their name on the character sheet.
  • A dedicated Biography section in the Lineage panel displays the player-authored biography text.
  • Both fields are optional and remain empty by default.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds two new optional player-authored identity fields to the character system: house and biography. The fields are added to the Character model, accepted as parameters in the create_character API, tested for proper persistence and round-trip serialization, projected through the viewer endpoint, and rendered conditionally in the character screen UI with appropriate formatting.

Changes

House and Biography Character Fields

Layer / File(s)	Summary
Character model schema servers/engine/models.py	Character model adds two new optional text fields (house and biography) with empty-string defaults for backward compatibility.
Engine create_character API servers/engine/server.py	create_character function signature and implementation accept two new optional parameters (house and biography) and pass them to the Character instance during construction.
Persistence verification tests servers/engine/tests/test_house_biography_persistence.py	New test module with a campaign helper and four end-to-end tests verify that fields are accepted by the API, persist through snapshots, default to empty strings when omitted, and round-trip correctly through get_character while preserving existing fields.
Viewer character sheet projection viewer/server.py	Viewer server's character sheet output now includes house and biography fields sourced from character snapshots, returning empty strings when unset.
Character screen rendering viewer/openworlds/screen-character.jsx	Character screen conditionally renders house as an italic subtitle (only when set) beneath the hero name, and biography as a separate paragraph in the lineage panel with pre-wrap formatting (only when non-empty).
Play script integration scripts/play.sh	Play script extracts house and biography from the authored hero spec and passes them as arguments to the create_character engine call.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• electricsheephq/WorldOS#383: Implements the exact requirements—adding house and biography fields to Character model, threading them through the create_character API, play script, viewer projection, and character screen UI rendering.

Possibly related PRs

• electricsheephq/WorldOS#369: Adds hero.house and hero.biography to the New Hero wizard spec sent to startProviderSession, which this PR then persists and renders.
• electricsheephq/WorldOS#364: Modifies the same viewer/openworlds/screen-character.jsx LineagePanel rendering logic for hero/lineage visibility changes.

Poem

A rabbit hops through fields so grand,
Where heroes claim their house and land,
Their tales now writ in biography's page,
Each character finds their rightful stage. 🐰✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 77.78% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main change: persisting house and biography fields in the engine snapshot, with issue reference.
Description check	✅ Passed	The description follows the template with comprehensive Summary, Licensing/CLA checklist, and Validation sections covering all five modified sites, tests, and acceptance criteria verification.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

viewer/openworlds/screen-character.jsx (1)

771-773: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Biography is skipped when race/note are empty due to early return.

Line 771 short-circuits before the new biography block, so a hero with only biography set still shows “No lineage recorded” and never renders biography.

Suggested fix

-  if (!race && !note) {
+  const biography = (hero.biography || "").trim();
+  if (!race && !note && !biography) {
     return <p className="body muted" style={{ marginTop: 0, fontSize: 14 }}>No lineage recorded for this hero.</p>;
   }
@@
-      {(hero.biography || "").trim() && (
+      {biography && (
         <div style={{ marginTop: (note || race) ? 12 : 0 }}>
           <div className="eyebrow" style={{ fontSize: 11, letterSpacing: "0.14em", color: "var(--ink-600)", marginBottom: 4 }}>Biography</div>
           <p className="body" style={{ margin: 0, fontSize: 14, color: "var(--ink-700)", whiteSpace: "pre-wrap" }}>
-            {hero.biography}
+            {hero.biography}
           </p>
         </div>
       )}

Also applies to: 801-808

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@viewer/openworlds/screen-character.jsx` around lines 771 - 773, The early
return checks only race and note causing biography to be skipped; update the
condition that returns the "No lineage recorded" paragraph to also check
biography (i.e., change the if (!race && !note) to if (!race && !note &&
!biography>) or alternatively move the biography rendering above that return so
a non-empty biography is rendered; apply the same fix to the similar block
around the code handling lines 801-808 to ensure biography is considered there
too.

🧹 Nitpick comments (1)

servers/engine/tests/test_house_biography_persistence.py (1)

76-77: ⚡ Quick win

Strengthen round-trip assertions to exact equality.

For persistence regressions, startswith/substring checks can pass even with truncation or unexpected mutation. Prefer asserting full string equality for house and biography in these checks.

Suggested assertion tightening

-    assert pc["biography"].startswith("Three winters in the Iron Shield")
+    assert pc["biography"] == "Three winters in the Iron Shield; one summer at the Spear Gate."
...
-    assert "Ember" in pc["house"]
-    assert "Hellfire" in pc["biography"]
+    assert pc["house"] == "Ember (foundling — no kin recorded)"
+    assert pc["biography"] == (
+        "Born into the Avernus engine-shops with the Hellfire still in her chest. "
+        "The infernal contract was cut; the heart is hers again. The forge owes her a name."
+    )

Also applies to: 121-122

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@servers/engine/tests/test_house_biography_persistence.py` around lines 76 -
77, The assertions use startswith which allows truncation; change both checks to
strict equality: replace the assertion on pc["house"] and pc["biography"] to
assert pc["house"] == "Anvilforge" and assert pc["biography"] == "Three winters
in the Iron Shield..." (use the full expected biography string present in the
test), and make the same exact-equality replacements for the corresponding
assertions around lines 121-122 so the round-trip persistence test validates
exact matches for pc["house"] and pc["biography"].

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@viewer/openworlds/screen-character.jsx`:
- Around line 771-773: The early return checks only race and note causing
biography to be skipped; update the condition that returns the "No lineage
recorded" paragraph to also check biography (i.e., change the if (!race &&
!note) to if (!race && !note && !biography>) or alternatively move the biography
rendering above that return so a non-empty biography is rendered; apply the same
fix to the similar block around the code handling lines 801-808 to ensure
biography is considered there too.

---

Nitpick comments:
In `@servers/engine/tests/test_house_biography_persistence.py`:
- Around line 76-77: The assertions use startswith which allows truncation;
change both checks to strict equality: replace the assertion on pc["house"] and
pc["biography"] to assert pc["house"] == "Anvilforge" and assert pc["biography"]
== "Three winters in the Iron Shield..." (use the full expected biography string
present in the test), and make the same exact-equality replacements for the
corresponding assertions around lines 121-122 so the round-trip persistence test
validates exact matches for pc["house"] and pc["biography"].

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 54f2b378-58db-4fa4-aa55-ed24539ee02f

📥 Commits

Reviewing files that changed from the base of the PR and between bb1870d and 7c48f63.

📒 Files selected for processing (6)

• scripts/play.sh
• servers/engine/models.py
• servers/engine/server.py
• servers/engine/tests/test_house_biography_persistence.py
• viewer/openworlds/screen-character.jsx
• viewer/server.py

[100yenadmin]

Superseded by #656 (merged) — a fresh re-implementation off current main with a 4-test regression guard. Closing the stale branch.