Add Character Depth, Ghost Log, Ritual, Judgment, Unlocks design spec
Second sub-project of the "make contact feel real" arc. Defines the shared contract (entity traits, favor, WS frames, new tables) that 6 parallel workstreams build against: entity traits + migration, ritual/judgment/favor, unlocks/items/sigils, Ghost Log HUD, ritual+judgment UI, inventory/sigil designer + listening tool.
This commit is contained in:
Indiana
@@ -0,0 +1,193 @@
|
|||||||
|
# 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):
|
||||||
|
|
||||||
|
```python
|
||||||
|
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 entities ADD COLUMN IF NOT EXISTS traits JSONB NOT NULL DEFAULT '{}'::jsonb"
|
||||||
|
))
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
**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"}` — always
|
||||||
|
allowed (a seeker can judge blind without completing a ritual — the
|
||||||
|
ritual doesn't gate eligibility, only whether accurate info was shown
|
||||||
|
first).
|
||||||
|
|
||||||
|
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,
|
||||||
|
"consequence": "reward" | "escalation" | "withdrawal" | "neutral"}` —
|
||||||
|
`correct` = trust called on real alignment >= 0.5, or banish called on
|
||||||
|
alignment < 0.5. `test` verdict always returns `consequence: "neutral"`,
|
||||||
|
`favor_delta: 0.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). 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 them 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) so the frontend knows what's enabled — e.g. `"listening_tool"`.
|
||||||
|
|
||||||
|
**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
|
||||||
|
|
||||||
|
New `backend/app/judgment.py` (pure functions: ritual success roll,
|
||||||
|
judgment-correctness + favor-delta + consequence selection) plus the WS
|
||||||
|
handlers in `backend/app/ws.py` for `ritual_start`/`ritual_step`/`judgment`,
|
||||||
|
and the `User.favor` column + migration line. Reads `state.entity["traits"]`
|
||||||
|
(entity dict shape — check how `serialize_entity` exposes it and add
|
||||||
|
`traits` there). 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 × real spirit/demon), favor clamping, favor read-back
|
||||||
|
bias on trait rolls (small, verifiable effect size).
|
||||||
|
|
||||||
|
## Workstream C (backend) — unlocks, items, sigils, drops
|
||||||
|
|
||||||
|
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 and 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). Extend `GET /auth/me` with `unlocks: list[str]`. Wire
|
||||||
|
`item_drop` emission into `backend/app/ws.py` per the contract's trigger
|
||||||
|
points. Tests: drop-roll probability sanity, inventory/sigil CRUD, `/auth/me`
|
||||||
|
unlock list 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/Test buttons) 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).
|
||||||
|
Tests: ritual step sequencing, judgment button → frame shape, 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) 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.
|
||||||
|
|
||||||
|
## 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.
|
||||||
Reference in New Issue
Block a user