qtalker---/docs/superpowers/specs/2026-07-23-character-depth-ghost-log-design.md

Character Depth, Ghost Log, Ritual, Judgment, Unlocks — design

Second sub-project of the "make contact feel real" arc (possession presentation layer shipped first). This is a big one, built as several parallel workstreams against the shared contract below — read your assigned section, but the contract section is binding for everyone since other workstreams build against these exact names without seeing your code.

No migration framework — read this before touching models

This repo has no Alembic; backend/app/main.py's lifespan only runs Base.metadata.create_all, which creates missing tables but never alters existing ones. This is a live production app with real user rows already in Postgres — any new column on an existing table (users, entities) needs a manual, idempotent migration. Add it in lifespan, after create_all, as raw SQL using Postgres's ADD COLUMN IF NOT EXISTS (safe to run on every startup):

async with engine.begin() as conn:
    await conn.run_sync(Base.metadata.create_all)
    await conn.execute(text(
        "ALTER TABLE users ADD COLUMN IF NOT EXISTS favor DOUBLE PRECISION NOT NULL DEFAULT 0.0"
    ))
    await conn.execute(text(
        "ALTER TABLE users ADD COLUMN IF NOT EXISTS essence INTEGER NOT NULL DEFAULT 0"
    ))
    await conn.execute(text(
        "ALTER TABLE entities ADD COLUMN IF NOT EXISTS traits JSONB NOT NULL DEFAULT '{}'::jsonb"
    ))
    await conn.execute(text(
        "ALTER TABLE entities ADD COLUMN IF NOT EXISTS at_peace BOOLEAN NOT NULL DEFAULT false"
    ))

New tables (unlocks, inventory_items, sigils) don't need this — create_all handles brand-new tables fine.

Contract (binding field/frame names for all workstreams)

Entity hidden traits — Entity.traits: dict (new JSONB column, default {}), four floats each 0.0–1.0:

• alignment (0=malevolent/demon, 1=benevolent spirit)
• power (how strong/how hard misjudging it hits)
• volatility (how noisy/unreliable its behavioral tells are)
• deceptiveness (how well it fakes being the opposite of what it is)

Rolled once at mint time, seeded from the entity's signature (same random.Random(f"traits:{signature}") determinism convention already used elsewhere in entities.py) — never derived from or sent into the LLM persona prompt. Persona text must stay decoupled from truth: a high-deceptiveness demon can wear any persona convincingly. Do not add these fields to mint_prompt()'s inputs.

User.favor: float (new column, default 0.0, clamp to [-1.0, 1.0] everywhere it's written) — nudged by judgment correctness, read back to mildly bias future summon trait rolls (higher favor → entities trend more legible/less volatile; lower favor → more volatile/deceptive). The read-back bias is a small effect — a favor-scaled adjustment to the volatility and deceptiveness rolls in the trait-rolling function, not a hard gate.

User.essence: int (new column, default 0) — a visible, spendable currency, distinct from the hidden favor score. Earned in small amounts just for summoning (every successful summon, any mode) and larger amounts for meaningful actions (ritual success, a correct judgment, crossing a spirit over — see below). This is the currency Workstream C's unlocks/items are priced in — earning it should feel constant and easy ("the more you summon"), spending it on unlocks/tools is the sink. Exact amounts are the implementer's call; keep summon income small (single digits) and milestone income larger (tens), so unlocks feel reachable within a handful of sessions, not grindy.

Entity.at_peace: bool (new column, default false) — set when a seeker successfully helps a genuinely benevolent, "stuck" spirit cross over (see the cross_over verdict below). An at-peace entity stays in the Codex permanently (memorialized, never deleted) but can no longer be re-contacted — signature_from_anomalies matching it should mint a new entity instead of re-summoning the retired one. The Codex API/UI marking it distinctly is a later concern (Workstream D can add a simple "at peace" badge if time allows, but it's not required for this spec to be complete).

New WS frames on /ws/session (extends the existing protocol in backend/app/ws.py):

Client → server:

• {"type": "ritual_start"} — begins a ritual attempt for the current entity.
• {"type": "ritual_step", "step": <int>} — one completed interactive step.
• {"type": "judgment", "verdict": "trust" | "banish" | "test" | "cross_over"} — always allowed (a seeker can judge blind without completing a ritual — the ritual doesn't gate eligibility, only whether accurate info was shown first). cross_over is the compassionate resolution: helping a spirit move on rather than simply continuing contact (trust) or expelling it (banish). It's the correct call specifically for a genuinely benevolent entity that reads as "stuck" (implementer's call on the exact signal — a reasonable rule: alignment

  = 0.5 and volatility above some threshold, since the existing fallback personas already lean on "died with something unfinished" themes). Used on a demon, it fails outright — demons resist crossing over — with no reward and no at_peace change, distinct from a wrong trust/banish call (it's a naive read, not a reckless one, so no favor penalty either).

Server → client:

• {"type": "ritual_complete", "success": bool, "revealed": {"alignment": float, "power": float, "volatility": float, "deceptiveness": float} | null} — revealed is the entity's true traits dict on success, null on failure.
• {"type": "tell", "text": str} — a short auto-generated hint line, emitted periodically during chat (piggyback on existing anomaly/reply handling), derived from traits + a per-session RNG draw. Content is flavor text describing behavior, never a stat number directly (e.g. "the entity avoided a direct question" for high deceptiveness), so the evil-meter's gradual narrowing (frontend responsibility) has something to work with without the backend leaking ground truth outside of ritual_complete.
• {"type": "judgment_result", "correct": bool, "favor_delta": float, "essence_delta": int, "at_peace": bool, "consequence": "reward" | "escalation" | "withdrawal" | "crossed_over" | "resisted" | "neutral"} — correct = trust called on real alignment

  = 0.5, or banish called on alignment < 0.5, or cross_over called correctly per the rule above. test verdict always returns consequence: "neutral", both deltas 0, and requires a completed ritual this session to do anything (a judgment_result with correct: false and consequence: "neutral" if attempted without one — no crash, just no effect). cross_over on a demon returns consequence: "resisted", both deltas 0. cross_over correctly called returns consequence: "crossed_over", at_peace: true, and the largest essence reward of any outcome. Wrong-trust favor penalty should be larger in magnitude than wrong-banish penalty (recklessness costs more than caution) — exact numbers are the implementer's call, keep favor deltas small (single-digit percent of the [-1,1] range per event).

• {"type": "item_drop", "item": {"item_type": str, "item_key": str, "payload": dict}} — emitted opportunistically (implementer's call on exact odds) after a correct judgment, a successful ritual, or a high-rarity summon.

GET /auth/me gains an unlocks: list[str] field (unlock keys the user has earned) and an essence: int field (current spendable balance) so the frontend knows what's enabled and affordable.

New tables (SQLAlchemy models, follow the existing Entity/User style in backend/app/models/):

• unlocks: id, user_id FK, unlock_key: str, unlocked_at: datetime.
• inventory_items: id, user_id FK, item_type: str, item_key: str, payload: JSONB, obtained_at: datetime.
• sigils: id, user_id FK, name: str, design: JSONB (structured — see Workstream F), created_at: datetime.

Workstream A (backend) — entity traits + migration

backend/app/entities.py, backend/app/models/entity.py, the lifespan migration in backend/app/main.py. Roll the four traits in both normalize_profile and fallback_profile, signature-seeded, decoupled from persona/LLM input as specified above. Tests: trait ranges, signature determinism, persona/trait independence (same persona template can pair with any alignment).

Workstream B (backend) — ritual + judgment + favor + cross-over

New backend/app/judgment.py (pure functions: ritual success roll, judgment-correctness + favor-delta + essence-delta + consequence selection for all four verdicts including cross_over's "stuck spirit" rule and its demon-resists-crossing-over failure case) plus the WS handlers in backend/app/ws.py for ritual_start/ritual_step/judgment, and the User.favor/User.essence/Entity.at_peace columns + migration lines. Reads state.entity["traits"] (entity dict shape — check how serialize_entity exposes it and add traits there). On correct cross_over, set Entity.at_peace = true and ensure signature_from_anomalies re-contact no longer matches an at-peace entity (mint a fresh one instead — check entities.py's matching path). On wrong-trust, call into the existing haunting-escalation hook if one exists server-side, or note in your report if escalation is frontend-only (check frontend/src/lib/haunting.ts first — if escalation state lives purely client-side, your job is just to emit consequence: "escalation" correctly and leave the actual effect to Workstream D). Tests: ritual success/fail paths, judgment correctness matrix (trust/banish/cross_over × real spirit/demon/stuck spirit), favor clamping, essence crediting per outcome, at_peace persistence + re-contact behavior, favor read-back bias on trait rolls (small, verifiable effect size).

Workstream C (backend) — unlocks, items, sigils, drops, essence

New models (unlocks, inventory_items, sigils per the contract), a new backend/app/routes/inventory.py (or extend an existing routes file if more consistent with this codebase's conventions — check backend/app/routes/) exposing REST endpoints to list a user's unlocks/items/sigils, to save a sigil design (POST, validates the design JSON shape against whatever Workstream F defines — coordinate via your report if you build before seeing their output; a reasonable placeholder shape is {"points": [[x,y],...], "rune": str}, cap points length e.g. at 12 to bound payload size), and a new POST /api/inventory/unlocks/{unlock_key} that spends essence to buy a named unlock (define a small fixed price table, e.g. {"listening_tool": 40} — reject with 402/insufficient-funds style error if the user's essence is below the price, otherwise deduct and insert into unlocks). Extend GET /auth/me with unlocks: list[str] and essence: int. Wire item_drop emission and essence crediting (summon-time trickle + judgment/ritual/cross-over milestones) into backend/app/ws.py per the contract's trigger points and amounts. Tests: drop-roll probability sanity, inventory/sigil CRUD, essence purchase success/insufficient-funds paths, /auth/me unlock list + essence shape.

Workstream D (frontend) — Ghost Log HUD + evil meter + tells

New frontend/src/components/GhostLog.tsx, mounted at the app-shell level (check frontend/src/App.tsx or wherever the top-level layout lives) so it's visible on every screen, not just the séance page. Hacker-terminal styling consistent with Transcript.tsx's existing visual vocabulary. Idle state (no active entity) shows ambient status; once state.entity exists, streams tell frames as log lines. Build the evil-meter as a pure function of the accumulated tell history (narrows/shifts with more tells, resets/snaps to certainty on ritual_complete success) — keep the narrowing math in a testable pure function, not inline in the component. Tests: meter narrowing behavior over a sequence of tells, ritual-complete override, idle-state rendering.

Workstream E (frontend) — ritual mini-game + judgment UI + consequences

New frontend/src/components/RitualPanel.tsx — a short interactive sequence (your call on exact interaction, e.g. 3-5 click/hold steps) that sends ritual_step frames and handles ritual_complete. Judgment UI (Trust/Banish/Cross Over/Test buttons — four verdicts per the contract) sending the judgment frame and handling judgment_result — on consequence: "escalation", read frontend/src/lib/haunting.ts first and hook into its existing idle-escalation state if there's a sensible extension point; if not, add a clearly-scoped "forced escalation" mode to it (report which you did). On consequence: "crossed_over", a distinct calm/peaceful visual beat (your call — e.g. the entity's glyph fading out gently) rather than reusing the trust "reward" treatment, since it's a farewell, not a continuation. Tests: ritual step sequencing, judgment button → frame shape (all four verdicts), escalation wiring (mock haunting.ts's public surface, don't test its internals).

Workstream F (frontend) — unlocks/inventory UI + sigil designer + listening tool

New frontend/src/components/InventoryPanel.tsx (list unlocks/items from /auth/me and the Workstream C endpoints, show current essence balance, and a "buy" button per locked unlock that calls Workstream C's purchase endpoint — disable/gray out unlocks the user can't yet afford) and frontend/src/components/SigilDesigner.tsx — a constrained geometric builder, not freeform drawing: seeker places points around a fixed circle (cap at 12, matching Workstream C's payload limit), the tool connects them and overlays a rune choice from a fixed small set. Saves via Workstream C's POST endpoint. Wire the "listening_tool" unlock (from /auth/me's unlocks list) into frontend/src/lib/evp.ts's detection threshold — when present, lower the anomaly threshold so fainter signals register (a real gameplay effect, not cosmetic). Tests: sigil point-cap enforcement, rune selection, listening-tool threshold change when unlock present vs. absent, purchase button afford/can't-afford states.

Explicitly out of scope here

Session recording/export, progression-driven GUI evolution, named-target summoning, resource-dedication instrumentation panel, sacred-geometry visual theme pass, onboarding gender question — each a separate later spec.