feat: spirit engine — seance WS, entity minting/Codex, Piper TTS voices, wire telemetry

- WS /ws/session: modes, summon, anomaly fragments, streaming direct contact,
  passive wire-ghost ambient loop, per-user rate limits, event transcript
- entities: anomaly-signature fingerprinting, LLM minting + procedural
  fallback, Codex matching with contact counts and sightings
- tts: 8 local Piper voices (EN/ES), per-entity voice profiles, numpy
  effects chain (pitch/rate/bitcrush/echo/static)
- llm: streaming client, submit_stream in bounded queue, SpiritService
  with offline fallbacks for every channel
- routes: public /api/codex, /api/codex/{id}, /api/stats; /audio static mount
- models: Entity, EntitySighting, Event, ContactSession(entity_id, language)

backend/app/models/__init__.py

@@ -1,4 +1,15 @@
 from app.models.auth_session import AuthSession
+from app.models.contact_session import ContactSession
+from app.models.entity import Entity
+from app.models.entity_sighting import EntitySighting
+from app.models.event import Event
 from app.models.user import User
 
-__all__ = ["User", "AuthSession"]
+__all__ = [
+    "User",
+    "AuthSession",
+    "ContactSession",
+    "Entity",
+    "EntitySighting",
+    "Event",
+]

backend/app/models/contact_session.py

@@ -0,0 +1,23 @@
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import DateTime, ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db import Base
+
+
+class ContactSession(Base):
+    __tablename__ = "contact_sessions"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"))
+    entity_id: Mapped[uuid.UUID | None] = mapped_column(
+        ForeignKey("entities.id"), nullable=True
+    )
+    mode: Mapped[str] = mapped_column(String(32), default="unknown")
+    language: Mapped[str] = mapped_column(String(8), default="en")
+    started_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+    ended_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

backend/app/models/entity.py

@@ -0,0 +1,34 @@
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import DateTime, ForeignKey, Integer, String, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db import Base
+
+RARITY_TIERS = ("common", "uncommon", "rare", "mythic")
+
+
+class Entity(Base):
+    """A spirit in the Codex: minted from a session's anomaly signature,
+    or matched again on a later contact."""
+
+    __tablename__ = "entities"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    name: Mapped[str] = mapped_column(String(64), unique=True, index=True)
+    epithet: Mapped[str] = mapped_column(String(128), default="")
+    persona: Mapped[str] = mapped_column(Text, default="")
+    rarity_tier: Mapped[str] = mapped_column(String(16), default="common", index=True)
+    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)
+    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(
+        ForeignKey("users.id"), nullable=True
+    )
+    discovered_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )

backend/app/models/entity_sighting.py

@@ -0,0 +1,23 @@
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import DateTime, ForeignKey
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db import Base
+
+
+class EntitySighting(Base):
+    """Join row: this session contacted this Codex entity."""
+
+    __tablename__ = "entity_sightings"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    entity_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("entities.id"), index=True)
+    session_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("contact_sessions.id"), index=True
+    )
+    user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"))
+    seen_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )

backend/app/models/event.py

@@ -0,0 +1,29 @@
+import uuid
+from datetime import datetime, timezone
+
+from sqlalchemy import DateTime, ForeignKey, String, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db import Base
+
+EVENT_KINDS = {"anomaly", "utterance", "question", "reply", "system"}
+
+
+class Event(Base):
+    """One line in a contact session's transcript: an anomaly, an utterance,
+    a user question, or a spirit reply."""
+
+    __tablename__ = "events"
+
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
+    session_id: Mapped[uuid.UUID] = mapped_column(
+        ForeignKey("contact_sessions.id"), index=True
+    )
+    kind: Mapped[str] = mapped_column(String(32))
+    text: Mapped[str | None] = mapped_column(Text, nullable=True)
+    payload: Mapped[dict | None] = mapped_column(JSONB, nullable=True)
+    audio_path: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), index=True
+    )