Eve library

Hathor Ideation — Domain Proposal

Guide

Revision 1

On this page

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).

text
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.