feat: add hidden entity traits (Workstream A) + idempotent migration

Entity.traits (alignment/power/volatility/deceptiveness, 0.0-1.0 each) is
rolled once at mint time in entities.py, seeded from the entity's
signature via random.Random(f"traits:{signature}") — a separate rng
namespace from normalize_profile's existing "norm:" rng, and never fed
into mint_prompt, so persona text stays fully decoupled from ground
truth. normalize_profile now includes "traits" in its returned dict;
fallback_profile inherits it for free since it already delegates to
normalize_profile.

Adds the new JSONB column to the Entity model (default {}) and the
idempotent `ALTER TABLE entities ADD COLUMN IF NOT EXISTS traits ...`
migration line to main.py's lifespan, per the live-Postgres migration
convention this spec introduces (no Alembic in this repo).

Tests cover trait value ranges, signature-determinism, and
persona/trait independence (same persona template pairs with a wide
spread of alignment rolls across signatures), plus a regression check
that mint_prompt's signature never grows a traits parameter.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

backend/app/entities.py

@@ -96,6 +96,23 @@ def parse_mint_response(text: str) -> dict | None:
     return profile
 
 
+def roll_traits(signature: str) -> dict:
+    """Roll the four hidden truth-traits for an entity, seeded from its
+    signature. These are never derived from — or fed into — the LLM persona
+    prompt (see `mint_prompt`, which never sees this function's output):
+    persona text must stay fully decoupled from ground truth, so a
+    convincing "sweet old lady" persona can pair with any alignment roll.
+    A separate `random.Random` namespace (`"traits:"` vs. `normalize_profile`'s
+    `"norm:"`) keeps this roll independent of the cosmetic-defaults rng."""
+    rng = random.Random(f"traits:{signature}")
+    return {
+        "alignment": rng.uniform(0.0, 1.0),
+        "power": rng.uniform(0.0, 1.0),
+        "volatility": rng.uniform(0.0, 1.0),
+        "deceptiveness": rng.uniform(0.0, 1.0),
+    }
+
+
 def normalize_profile(profile: dict, signature: str) -> dict:
     """Coerce an LLM (or fallback) profile into the exact shape the DB and
     frontend expect, filling gaps with signature-deterministic defaults."""
@@ -138,6 +155,7 @@ def normalize_profile(profile: dict, signature: str) -> dict:
         },
         "quotes": [str(q)[:200] for q in quotes[:4] if isinstance(q, str)]
         or rng.sample(_QUOTE_BANK, 2),
+        "traits": roll_traits(signature),
     }
 
 

backend/app/main.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from fastapi import FastAPI, HTTPException
 from fastapi.responses import FileResponse
 from fastapi.staticfiles import StaticFiles
+from sqlalchemy import text
 
 import app.models  # noqa: F401 — registers models on Base.metadata before create_all
 from app.config import settings
@@ -45,6 +46,12 @@ async def lifespan(app: FastAPI):
     AUDIO_DIR.mkdir(parents=True, exist_ok=True)
     async with engine.begin() as conn:
         await conn.run_sync(Base.metadata.create_all)
+        # No Alembic in this repo — `create_all` never alters existing
+        # tables, so columns added to live models need a manual, idempotent
+        # migration here. Safe to run on every startup.
+        await conn.execute(text(
+            "ALTER TABLE entities ADD COLUMN IF NOT EXISTS traits JSONB NOT NULL DEFAULT '{}'::jsonb"
+        ))
     cleanup_task = asyncio.create_task(_session_cleanup_loop())
     try:
         yield

backend/app/models/entity.py

@@ -24,6 +24,7 @@ class Entity(Base):
     signature: Mapped[str] = mapped_column(String(64), unique=True, index=True)
     voice_profile: Mapped[dict] = mapped_column(JSONB, default=dict)
     visual_profile: Mapped[dict] = mapped_column(JSONB, default=dict)
+    traits: Mapped[dict] = mapped_column(JSONB, default=dict)
     sample_quotes: Mapped[list] = mapped_column(JSONB, default=list)
     contact_count: Mapped[int] = mapped_column(Integer, default=0)
     discovered_by: Mapped[uuid.UUID | None] = mapped_column(