# Hathor Ideation — Domain Proposal

Status: ACCEPTED (2026-07-17). Companion checklist:
`HATHOR_YEMAYA_IDEATION_SOTA_TODOS_2026-07-17.md` (repo root; the checklist's
checkboxes are the execution ledger; this document records the decisions the
checklist builds on).

## 1. Goals

Build the blank-page-to-canon pipeline the 2026-07-17 audit found missing: a
first-class surface that owns **capture → divergent generation → convergent
selection → development → promotion into canon**, for AAA games, film, and
series work, on top of the real engines hathor/yemaya already have (world
versioning + merge, culture/economy/politics simulation, lore validators, Sophia
grounding, the yemaya QA analyzer battery, presentation-compiler, TTS).

Product stance:

- Ideas are **first-class entities** with lineage, revisions, and decision
  records — not notes in a doc.
- Every generator produces **option sets**, never a single answer, and every
  selection step records why the winner won and the losers lost.
- Speculation never dirties canon: promotion lands on **world branches**;
  merging is the act of canonization.
- Deterministic tier before model tier, everywhere (rationale §6).

## 2. Non-goals

- Not a general note-taking or docs product (Notion/Neith territory). Only
  idea-shaped artifacts with the ideation lifecycle.
- Not a screenwriting editor. We ladder up to beat outlines / treatments and
  interop via Fountain/FDX (P16.7); full script drafting stays in
  `libs/hathor/pre-production` scriptwriting and external tools.
- Not legal clearance. Title/premise-similarity search is advisory and labeled
  as such (P15.4).
- Not likeness synthesis. Casting sheets and voice reads reference real people
  descriptively only; anything likeness-bearing routes through the existing
  consent machinery (P10.3, P14.6, P14.8).
- No autonomous canon mutation. Every gate that changes canon or advances a
  stage has a human sign-off (HITL, P15.3).

## 3. Glossary

| Term                | Meaning                                                                                                                                                                                |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Spark**           | Any captured idea fragment, pre-triage (inbox state `captured`).                                                                                                                       |
| **Idea**            | The core entity; one of 13 kinds (premise, logline, what_if, character_concept, culture_seed, world_seed, location_seed, faction_seed, quest_seed, theme, title, image_ref, fragment). |
| **Option set**      | N ≥ 3 sibling ideas produced by one generator invocation, compared as a unit.                                                                                                          |
| **Board**           | A curated working collection of ideas (kanban/canvas view).                                                                                                                            |
| **Tournament**      | A pairwise-judgment session producing Bradley-Terry/Elo ratings over an option set or board.                                                                                           |
| **Rubric**          | Weighted multi-criteria scoring configuration applied to options.                                                                                                                      |
| **Decision record** | Immutable record of a selection/kill/gate decision: winner, rejected siblings, scores at decision time, stated reason, decider.                                                        |
| **Ladder**          | The development sequence logline → synopsis → treatment → beat outline (each rung a versioned artifact).                                                                               |
| **Promotion**       | Converting an idea/ladder artifact into a draft canonical entity (character, culture, world entity on a branch, quest).                                                                |
| **Gate**            | A stage boundary (concept → develop → greenlight) requiring artifacts + human sign-off.                                                                                                |
| **Graveyard**       | Killed ideas, queryable and revivable with lineage intact.                                                                                                                             |

## 4. Namespace decision (task 0.2)

**Decision: `libs/hathor/ideation` (new library) + routes added to
`apps/hathor/narrative-api`.** UI lands in `apps/hathor/workbench` (pages) with
studio back-parity per P6.7.

Considered:

| Option                                 | Verdict  | Reasoning                                                                                                                                                                                                                                                                                                         |
| -------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New `apps/hathor/ideation-api` service | Rejected | Service sprawl: a fourth hathor service for a surface whose consumers (workbench, studio) already speak to narrative-api; nothing in the ideation workload (low QPS, no long jobs — simulation previews delegate to simulation-worker) justifies an isolated deployable.                                          |
| Extend `world-api`                     | Rejected | world-api's contract is canonical world state + versioning/merge; ideation is pre-canon by definition. Mixing lifecycles (speculative vs. canonical) in one service blurs the promotion boundary we want sharp.                                                                                                   |
| Extend `narrative-api` (chosen)        | Accepted | It already owns authoring-adjacent, pre-runtime surfaces (quests, dialogues, story-graphs, validation routes). Ideation routes (`/ideation/*`) sit beside them; blast radius is one service redeploy; the promotion flows call world-api/narrative-api internals the same way validation already does.            |
| Yemaya-side lib                        | Rejected | Ideation's grounding objects are hathor's (worlds, cultures, canon validators). Yemaya assets (QA analyzers, presentation-compiler, TTS, collaboration) are consumed through their public packages — dependency direction hathor→yemaya packages is already established (e.g. workbench uses yemaya UI patterns). |

Library shape: TypeScript, Vitest, tsup, path-mapped in `tsconfig.base.json`,
`scope:hathor` tag — identical scaffold conventions to `libs/hathor/validation`.

## 5. Storage design (task 0.3)

Prisma models in `libs/hathor/database/prisma/schema.prisma` (the `hathor`
schema/DB), one migration. Entity summary (authoritative DDL in the schema
file):

- **Idea** — id (cuid), kind (enum, 13 values), status (enum: CAPTURED,
  DEVELOPING, SHORTLISTED, SELECTED, PROMOTED, KILLED, ARCHIVED), title, body
  (text), structured payload (Json — premise slots etc.), tags (String[]),
  boardId?, worldId? (grounding anchor), embedding metadata (Json?; vectors live
  behind the provider seam, not in this table), createdBy, timestamps. Indexed
  on (status, boardId), (kind), (worldId).
- **IdeaRevision** — ideaId FK, seq (int, unique per idea), author, diffSummary,
  snapshot (Json), createdAt. Append-only.
- **IdeaLink** — fromId, toId, linkType (enum: DERIVED_FROM, MERGED_FROM,
  INSPIRED_BY, CONTRADICTS, PROMOTED_TO), note?, createdAt. Unique on (fromId,
  toId, linkType). DAG enforced in the domain layer (cycle check on insert), not
  in SQL.
- **IdeaBoard** — id, name, purpose?, layout (Json — canvas positions), archived
  flag.
- **OptionSet** — id, generatorId, generatorParamsHash, prompt metadata (Json),
  createdAt; **OptionSetMember** — optionSetId, ideaId, ordinal.
- **Tournament** — id, optionSetId? | boardId?, method (enum: ELO,
  BRADLEY_TERRY), status, config (Json: K, scheduling), createdAt; **Judgment**
  — tournamentId, judgeId, aId, bId, winner (A|B|TIE), createdAt. Ratings are
  **derived** (recomputed from judgments — the fit is deterministic), cached in
  Tournament.resultCache (Json) with the judgment count it was computed at;
  never hand-written.
- **RubricScore** — ideaId, rubricId, criterionKey, score, weightAtTime, source
  (enum: HUMAN, CRITIC_AGENT, ANALYZER), sourceDetail, createdAt.
- **DecisionRecord** — id, subjectIdeaId, decision (enum: SELECTED, KILLED,
  REVIVED, GATE_ADVANCED, GATE_HELD, OVERRIDE), rejectedIdeaIds (String[]),
  scoresSnapshot (Json), reason (text, required), decidedBy, gate? (enum),
  createdAt. Append-only, no updates.
- **PromotionRecord** — ideaId, targetType (enum: CHARACTER, CULTURE,
  WORLD_ENTITY, QUEST, PROTOTYPE_BRIEF, BIBLE), targetId, worldBranchId?,
  validationFindings (Json — the lore-validator output at promotion), createdAt.
- **IdeationNote** (P14.7) — subjectType+subjectId, body, severity, author,
  state (enum: OPEN, ADDRESSED, REBUTTED, DEFERRED), resolutionLink?,
  createdAt/resolvedAt.

Conventions carried from the existing hathor schema: cuid ids, soft delete only
via status (KILLED/ARCHIVED), Json for polymorphic payloads with Zod validation
at the boundary, no cross-schema FKs (world/quest references are ids validated
at the service layer, same as the rest of hathor).

## 6. LLM seam (task 0.4)

One interface, defined in `libs/hathor/ideation/src/provider.ts`, consumed by
every generator/critic; no other module talks to a model.

```ts
export interface IdeationModelProvider {
  /** Freeform generation under a fenced, structured prompt. */
  generate(request: {
    task: IdeationTask; // discriminated union per generator
    fencedContext: FencedBlock[]; // user text, canon excerpts, sources — always fenced
    options: { n: number; maxTokens: number; temperature?: number };
  }): Promise<IdeationGenerateResult>; // n candidates + usage + modelId

  /** Structured critique of one artifact (writers-room, critic pass). */
  critique(request: {
    persona: CriticPersona; // data-defined, not code forks
    artifact: FencedBlock;
    focus: string[];
  }): Promise<IdeationCritiqueResult>;

  /** Embedding for dedupe/clustering/semantic search. */
  embed(texts: string[]): Promise<number[][]>;
}
```

Wiring rules (the V2/SAFETY-001 lessons, made structural):

1. **Fencing** — every non-system string (user idea text, canon excerpts, Sophia
   passages) enters prompts inside delimited fenced blocks with an
   injection-resistant preamble; nothing user-controlled is ever spliced into
   instruction text. Reuse the fencing helpers from `libs/hathor/llm-npc` rather
   than new ones.
2. **Safety filter invoked, always** — provider outputs pass through
   `libs/yemaya/safety` `ContentFilterManager.checkContent` before persistence
   (P10.1); the call is in the ideation service layer so no generator can skip
   it.
3. **Fail-loud absence** — no provider configured ⇒ `generate`/`critique` throw
   `IdeationError('not_configured', …)`; `embed` unavailability degrades
   features to their labeled lexical fallback (dedupe via the credited
   feature-hashing fallback) or honest "unavailable", never fake vectors.
4. **Provider chain reuse** — the default implementation adapts
   `libs/hathor/llm-npc/provider-chain` (health tracking, circuit breaker,
   fallback order) rather than a new chain.
5. **Attribution** — every generate/critique result stores modelId, paramsHash,
   and prompt hash on the produced options (P12.3) and flows into AI-attribution
   records (P10.3).

## 7. Threat & safety review (task 0.5)

**Prompt injection.** User-supplied idea text and imported web content (2.5b)
are attacker-controlled; both are fenced (rule 1 above) and the content filter's
injection detector screens text that will be routed into prompts (P10.1). Sophia
passages are treated as untrusted quotes, fenced and cited, never as
instructions. **Generated-content risk.** All model output is filtered
pre-persist; blocked output is stored as a redacted tombstone with the category
result — auditable, not silently dropped. **Likeness/consent.** Character
concepts resembling real people, cloned voices for table reads, and casting
references are gated on `EthicsManager` consent records before promotion or
synthesis; stock synthetic voices are exempt but labeled. **Canon integrity.**
Ideation writes never touch canonical tables; promotion targets world
**branches** and runs the lore validators, with conflicts blocking-with-override
and every override captured in a DecisionRecord. **Access control.** Distinct
`ideation.read/write/judge/promote` permissions via `libs/yemaya/rbac`; promote
additionally requires the gate's HITL sign-off. **Data retention.** Killed ideas
persist (graveyard) — deletion requests route through the existing organizations
data-lifecycle surfaces rather than a bespoke purge.

## 8. UX skeleton (task 0.6)

Five core surfaces, workbench-first (`apps/hathor/workbench`), studio
back-parity per P6.7. Layout language follows the existing workbench (left nav,
list+detail, modal editors).

```
INBOX (P2.3)                              BOARD (P6.5)
┌──────────┬───────────────────────┐      ┌────────────────────────────────┐
│ nav      │ [spark] title         │      │ board: "S2 villains"  [+ gen ▾]│
│          │  raw text…            │      │ ┌────┐ ┌────┐ ┌────┐ ┌────┐    │
│ Inbox(12)│  similar: 3 ideas ⚠   │      │ │card│ │card│ │card│ │card│    │
│ Boards   │  ┌─────────────────┐  │      │ └────┘ └────┘ └────┘ └────┘    │
│ Tourn.   │  │keep→kind+board  │  │      │ columns: captured│dev│short    │
│ Ladder   │  │merge→picker     │  │      │ [tournament] [rubric] [board▾] │
│ Graveyard│  │kill→reason      │  │      └────────────────────────────────┘
│          │  └─────────────────┘  │
│          │  keys: j/k/enter      │
└──────────┴───────────────────────┘

GENERATOR CONSOLE (P6.5)                  TOURNAMENT (P4.2c)
┌────────────────────────────────┐        ┌────────────────────────────────┐
│ engine: [premise ▾]            │        │ pair 7/21          judge: ama   │
│ seed world: [Veilborn ▾]       │        │ ┌───── A ─────┐ ┌───── B ─────┐│
│ grounding docs: [+]            │        │ │ logline…    │ │ logline…    ││
│ tier: ◉ deterministic ○ model  │        │ │ premise slots│ │ premise slots││
│        (model not configured)  │        │ └─────────────┘ └─────────────┘│
│ [generate 5 options]           │        │   [← A wins]  [tie]  [B wins →]│
│ → OptionSet grid, per-option:  │        │ leaderboard (live BT ratings)  │
│   [develop] [critique] [kill]  │        └────────────────────────────────┘
└────────────────────────────────┘

DEVELOP LADDER (P5)
┌──────────────────────────────────────────────┐
│ logline ── synopsis ── treatment ── beats    │
│   v3         v1          —          —        │
│ [framework: Save the Cat ▾]  [corkboard ⇄]   │
│ diagnostics: tension ▂▄▆▄█  pacing ok        │
│ notes(2 open) │ critics(1 refuted) │ promote │
└──────────────────────────────────────────────┘
```

Interaction commitments: keyboard-first triage (j/k/enter), every destructive
action requires a reason (feeds DecisionRecords), every model-tier control shows
honest availability (disabled + tooltip when `not_configured`), canvas surfaces
get keyboard equivalents (a11y, P11.4).

## 9. SOTA benchmark dispositions (task 0.1)

Disposition of every row in the checklist's benchmark table. COVERED = planned
as mapped; no row is rejected outright; two are explicitly descoped in part,
noted below.

| #   | Capability row                                        | Disposition                                                                                                                                                        |
| --- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1   | Frictionless capture                                  | COVERED — P2 (hotkey modal, inbox, zero-form path).                                                                                                                |
| 2   | Mood boards & reference libraries                     | COVERED — P8.1 via `maya/inspirations` bridge (2.5a); no duplicate library.                                                                                        |
| 3   | Premise/logline formulas                              | COVERED — P3.1 (deterministic slot grammar + lints + model tier).                                                                                                  |
| 4   | Hierarchical story generation                         | COVERED — P5.1/5.2 ladder; scene-level generation DESCOPED (non-goal §2: script drafting stays in pre-production/external tools; ladder stops at beats/treatment). |
| 5   | What-if over canon                                    | COVERED — P3.2 (structural mutation operators + simulator-backed consequences + tree UI).                                                                          |
| 6   | Creativity operators                                  | COVERED — P3.3 (SCAMPER as typed transforms, Zwicky box, stimulus deck, hats).                                                                                     |
| 7   | Diversity-guaranteed generation                       | COVERED — P3.4 (MAP-Elites grid over genre/tone/scope/era/conflict descriptors).                                                                                   |
| 8   | Multi-agent writers' room                             | COVERED — P3.5 (genre-agnostic generalization of case-writers-room; Canon-Keeper calls real validators).                                                           |
| 9   | Research-grounded ideation                            | COVERED — P3.6 (Sophia citations; fail-loud without client).                                                                                                       |
| 10  | Culture-aware onomastics                              | COVERED — P3.7 (phonotactic profiles on culture entities; seeded RNG).                                                                                             |
| 11  | Pairwise/tournament selection                         | COVERED — P4.2 (BT/Elo, information-maximizing scheduling).                                                                                                        |
| 12  | Multi-criteria scoring                                | COVERED — P4.3 (weighted rubric + sensitivity solve).                                                                                                              |
| 13  | Diversity-aware shortlisting                          | COVERED — P4.4 (MMR; DPP considered and rejected — MMR is sufficient, simpler, and testable; revisit only if shortlists degenerate in practice).                   |
| 14  | Adversarial critic panels                             | COVERED — P4.5 (sequential refuting critics; human-only mode when unconfigured).                                                                                   |
| 15  | Decision records                                      | COVERED — P4.6 (immutable, graveyard revival keeps lineage).                                                                                                       |
| 16  | Development ladder                                    | COVERED — P5.1.                                                                                                                                                    |
| 17  | Multiple narrative frameworks                         | COVERED — P5.2 (six frameworks, single source of truth shared with theory lib).                                                                                    |
| 18  | Promotion with provenance                             | COVERED — P5.4 (drafts on world branches; validators at the gate).                                                                                                 |
| 19  | Real-time collaborative boards                        | COVERED — P7.1 (Yjs via yemaya/collaboration).                                                                                                                     |
| 20  | Idea versioning & lineage                             | COVERED — P1.3/1.4.                                                                                                                                                |
| 21  | Canon guardrails during ideation                      | COVERED — P10.2 (advisory at capture, blocking-with-override at promotion).                                                                                        |
| 22  | AI attribution & consent                              | COVERED — P10.3 (EthicsManager labeling + consent gating).                                                                                                         |
| 23  | Funnel analytics & win-rates                          | COVERED — P12.                                                                                                                                                     |
| 24  | Pillars & core loops (MDA)                            | COVERED — P13.1/13.2 (real theory-lib engine).                                                                                                                     |
| 25  | Comps & positioning                                   | COVERED — P13.3 (+ P15.4 for clearance-flavored search).                                                                                                           |
| 26  | Mechanic/systems concepting w/ sim preview            | COVERED — P13.4 (honest labels; unsimulated sketches stay labeled drafts).                                                                                         |
| 27  | Level/biome/encounter briefs                          | COVERED — P13.5/13.6.                                                                                                                                              |
| 28  | Prototype briefs w/ kill criteria                     | COVERED — P13.7.                                                                                                                                                   |
| 29  | Scope & branching-cost estimation                     | COVERED — P13.8 (existing estimators; labeled estimates).                                                                                                          |
| 30  | Series bible / season arc / episode grid              | COVERED — P14.2–14.4.                                                                                                                                              |
| 31  | Corkboard beat board                                  | COVERED — P6.8 (+P14.4 specialization).                                                                                                                            |
| 32  | Character arc design                                  | COVERED — P5.7 (existing arc validator wired).                                                                                                                     |
| 33  | Ensemble balance                                      | COVERED — P6.9 (real Gini/representation analyzers).                                                                                                               |
| 34  | Voiced table reads                                    | COVERED — P14.6 (tts-integration; consent-gated; fail-loud).                                                                                                       |
| 35  | Pitch decks/one-pagers/lookbooks                      | COVERED — P14.5 (presentation-compiler; assembled from real artifacts only).                                                                                       |
| 36  | Notes workflow                                        | COVERED — P14.7 (blocking gates on unresolved blocking notes).                                                                                                     |
| 37  | Title/logline A/B testing                             | COVERED — P4.7 (existing ab-variant machinery).                                                                                                                    |
| 38  | Craft critic battery                                  | COVERED — P4.8/P5.6 (adapters over the existing yemaya analyzers; reuse-first rule).                                                                               |
| 39  | Franchise routing & slate balance                     | COVERED — P15.1/15.2.                                                                                                                                              |
| 40  | Stage-gate greenlight w/ HITL                         | COVERED — P15.3 (gates never auto-advance).                                                                                                                        |
| 41  | Title clearance & similarity                          | COVERED (advisory-only, labeled) — P15.4; legal clearance is a non-goal (§2).                                                                                      |
| 42  | Cultural sensitivity & representation                 | COVERED — P15.5 (existing validators; evidence-carrying findings).                                                                                                 |
| 43  | Locale-aware naming                                   | COVERED — P15.6 (honest scope: only locales with lexicons, listed).                                                                                                |
| 44  | Fountain/FDX interop                                  | COVERED — P16.7 (import extends existing parser; FDX export new).                                                                                                  |
| 45  | Command palette / search / templates / mobile capture | COVERED — P16.1–16.5.                                                                                                                                              |

Partial descopes on record: row 4 (scene-level drafting → pre-production/
external, by non-goal) and row 13 (DPP → MMR, simplicity + testability).
Everything else lands as mapped or the checklist row gets re-opened.

## 10. Sequencing

As in the checklist's "Sequencing & dependency notes" — P0→P1→P2 strictly
sequential; P3 engines independent after P2 (3.1 first); P6.0a/6.0b before any
parity page; P10/P11 apply from the first line of code.
