hathor library

The TypeScript SDK over Hathor's HTTP APIs (libs/hathor/client/src), a tsup-built package. HathorClient (client.ts) composes three API resources — WorldResource, NarrativeResource, SimulationResource (under src/api/) — over a pluggable HttpTransport with a typed error hierarchy (HathorError, NetworkError, TimeoutError, NotFoundError, ValidationError, RateLimitError, …). Beyond raw API calls it ships helpers/ with real client-side logic: world-state snapshots and relationship maps, quest generation from templates (QUEST_TEMPLATES, generateQuestChain), and lore validation (validateWorldLore). It also carries contract tests (contracts/hathor-openapi.contract.spec.ts, hathor-cross-service.contract.spec.ts) that keep the client aligned with the service's OpenAPI surface.

The persistence layer (libs/hathor/database/src + a prisma/ schema). It exports a Prisma-client wrapper (getHathorClient, createHathorClient, connect/disconnect, transaction, executeRaw, queryRaw, isConnected) plus a set of hand-mirrored string-literal union types (WorldStatus, WorldGenre, EntityType, QuestStatus, SimulationType, ValidationSeverity, etc.) so consumers can type against the schema before running prisma:generate. The fuller generated model exports are present in index.ts but commented out, gated on code generation — an honest "available after generation" seam rather than a fake export.

A CGI character-definition export facade (libs/hathor/characters/src/index.ts). Despite the "import facade" label it is a real builder: createHathorCharactersCgiPacket maps @hathor/domain-models Character records (and @hathor/pre-production CharacterReferences) into a flat HathorCharactersCgiPacket — flattening appearance (height/age/hair/eyes/skin), costume designs, and visual references — and validateHathorCharactersCgiPacket checks for missing characters, appearance, costumes, visual references, and export metadata, emitting blocking vs. warning issues. It defaults the export target to ['maya','unreal','blender'] under schema hathor-characters-cgi/v1.

The engine-agnostic type spine for the whole area (libs/hathor/domain-models/src). Its index.ts re-exports eight worldbuilding sub-domains — faction, economy, law, culture, geography, timeline, character, location — plus a common base layer and a V2 fighting-game narrative-record module, each with its own types.ts, constants.ts, factories.ts, utils.ts, and validators.ts. It also ships shared helpers (e.g. sortEventsChronologically, calendarDateToSortKey, formatCalendarDate) that the timeline and validation libraries build on. Nearly every other @hathor/* library imports its types, so it is the foundational node of the domain.

The pre-writing surface (libs/hathor/ideation/src/index.ts): where an idea lives before it is canon. It owns capture and triage (a status machine from captured through developing/shortlisted/selected to promoted, with append-only revisions and cycle-checked lineage links), the development ladder (logline → synopsis → treatment → beat outline, where editing means appending a version rather than overwriting one), and generators split by tier: deterministic ones (SCAMPER operators, phonotactic naming, premise combinatorics, MAP-Elites quality-diversity selection) and model-tier ones that fail loud when no provider is wired rather than fabricating a draft.

Selection is quantitative. Option sets are compared with pairwise tournaments fitted by Bradley–Terry (plus Elo for live scheduling), judge disagreement is measured rather than eyeballed, and every kill or promotion writes an immutable DecisionRecord — rejected siblings, scores as they stood, stated reason, decider — so a later re-scoring can never rewrite why a past call was made.

Four cross-cutting guards wrap that surface, each enforced at a seam rather than at call sites:

• Content safety. withContentSafetyScreening wraps the storage provider so model-generated ideas pass Yemaya's ContentFilterManager before they persist; blocked content becomes a redacted tombstone carrying the category result and a digest of the refused text, never a silent drop. withPromptInjectionScreening wraps the model provider so user text is screened before it reaches a prompt.
• Canon guardrails. The same contradiction/causality validators run at both ends of an idea's life with opposite consequences: advisory at capture (an idea that contradicts canon is often the point), blocking at promotion, where an override requires a named decider and a stated reason and writes an override DecisionRecord.
• Attribution. The AI-vs-human split is computed from the revision trail — the longest common subsequence between the model's origin draft and the current text — so the disclosure describes the idea as it is now, not as it was generated. Records go through Yemaya's EthicsManager, which also holds the likeness consent that a real-person character concept needs before it can be promoted.
• Access. idea:read, idea:create/idea:update, idea:judge, and idea:promote are distinct permissions in the shared @yemaya/rbac registry: a reviewer judges what they cannot rewrite, and an editor drafts but cannot commit to canon.

Promotion hands the finished idea to its owning system (character, culture, world entity, quest) through @hathor/narrative and @hathor/domain-models, recording an append-only promotion ledger whose rows survive deletion of the target — marked, never removed, so the idea's history always explains what it became.

An LLM-powered NPC "brain" system (libs/hathor/llm-npc/src; note the source header still reads @yemaya/llm-npc, but the project name is @hathor/llm-npc). It composes a brain (personality manager with Big-Five traits, emotional-state manager, short/long-term memory, world awareness), a dialogue module (DialogueGenerator plus a SafetyFilter), a behavior module (BehaviorController, NPC-to-NPC conversation), a platforms layer with clients for NVIDIA ACE, Inworld, Convai, and a generic LLM client, a ProviderChain fallback system with circuit breaking, and an advanced SOTA tier (Enneagram + BDI personality, GOAP/HTN behaviour planning, attention-weighted memory consolidation, dialogue-act and manipulation detection). Substantial and genuinely implemented, with per-module spec files.

The outbound compiler (libs/hathor/lore-compiler/src) that turns narrative content into engine-ready and film-ready artifacts. engine/quest-compiler.ts compiles quests for game engines (Unreal, Unity, Godot, Blender) into typed CompiledQuest artifacts; film/screenplay-compiler.ts compiles stories into screenplays exportable as Fountain/FDX/PDF; bellona/package-builder.ts builds engine-interchange packages for the Bellona pipeline; and v2/v2-package-compiler.ts emits the V2 fighting-game contract. The index.ts exposes factory functions (createQuestCompiler, createScreenplayCompiler, createPackageBuilder).

The interactive-narrative engine (libs/hathor/narrative/src): a quest system (quest/quest-engine.ts), a dialogue engine (dialogue/dialogue-engine.ts), a story-graph traverser with effect execution (story-graph/traversal.ts, exporting StoryGraphTraverser and EffectExecutor), a journal/codex system, branching utilities, and an export subsystem that serialises stories to Ink, Yarn, and JSON (export/ink-exporter.ts, yarn-exporter.ts, json-exporter.ts behind an exporter-factory). The index.ts re-exports the story-graph surface selectively to avoid name collisions with the quest module's ConditionEvaluator/GameStateContext. Its Quest and StoryArc types are the inputs the @hathor/quests facade captures.

LLM narrative-generation pipelines (libs/hathor/narrative-generation/src). The design is planner→writer: Neith's deterministic tension/motif machinery plans the structure, then a governed LLM writes inside it via an injected LLMProviderInterface from @oshun/ai (NarrativeGenerationService in generators.ts). Around that core it adds prompt builders, a QuestBatchGenerator, a QualityGatedQuestBatchGenerator, a runStagedVolume staged generator that measures per-stage quality and corpus diversity and STOPs on regression (staged-volume.ts, reusing corpusDiversity from @oshun/content-quality-judge), a LoreConsistencyChecker, and a review workflow. The model boundary is fail-loud: with no provider wired the writer throws NarrativeGenerationError rather than fabricating output.

The largest library in the area (libs/hathor/pre-production/src, ~258 non-test implementation files), covering three concerns. scriptwriting/ is a "Chronicle" document parser plus narrative-structure analyzer with built-in templates (Epic Journey, Chronicle, Rise-and-Fall) and a Fountain-style exporter. storyboard/ is a visual-planning system (StoryboardManager, frames, sequences, style guides, export). planning/ is project management plus an unusually deep drone-cinematography production-planning subsystem: dozens of plan/sample/assess/export systems for flight-path design, choreography, speed ramps, obstacle avoidance, fleet/formation control, photogrammetry / NeRF / Gaussian-splatting / LiDAR capture, scan-to-CGI pipelines, and regulatory compliance (geofencing, NOTAM airspace deconfliction, pre-flight regulatory packets). Each system ships typed plans, fixtures, and assessment functions.

A quest scene-dependency capture facade (libs/hathor/quests/src/index.ts). createHathorQuestSceneDependencyPacket takes Quest and StoryArc records from @hathor/narrative plus author-supplied scene requirements, cross-indexes which scenes satisfy which quests/arcs, and produces a HathorQuestSceneDependencyPacket. validateHathorQuestSceneDependencyPacket performs real dependency checking — missing scenes/quests/arcs/objectives, dangling scene and quest dependencies, and missing capture requirements — under schema hathor-quests-scene-dependencies/v1.

The world-simulation engine bundle (libs/hathor/simulation/src). It carries five distinct subsystems, each with a manager + provider/storage seam: economy (markets, trade routes, guilds, a SeededRandom, a PriceCalculatorProvider.calculatePrice supply/demand model, event generation), politics (factions, leaders, alliances, conflicts, treaties, elections), culture (trait diffusion, cultural contact/exchange, drift and resilience analysis), scenario (scenario generation and world-state advancement), plus a physics engine (physics/engine.ts — a real fixed-step PhysicsEngine with rigid bodies, colliders, constraints, force fields, broad-phase, and Earth/Moon/ zero-G presets), an npc behaviour-tree library (SequenceNode, SelectorNode, decorators, a BehaviorTreeBuilder, and pattern factories), and a state persistence layer with in-memory, Postgres, and Redis backends. All storage is behind injectable providers (in-memory implementations shipped by default).

The bridge between Hathor's world model and Sophia's knowledge services (libs/hathor/sophia-integration/src). Three services compose into a unified HathorSophiaIntegration client: CitationService links world lore to research sources, LoreValidationService fact-checks lore against research, and ResearchGroundingService generates grounded world content from a topic. The unified client is fail-honest by construction — research grounding is only instantiated when both a graph client and an ingestion client are supplied, and the ground() helper throws if those are absent rather than returning fabricated results. All Sophia clients are injected interfaces (SophiaSearchClient, SophiaGraphClientForGrounding, SophiaIngestionClientForGrounding).

Game-design and storytelling theory tooling (libs/hathor/theory/src), in three managed subsystems. mda/ implements the Mechanics-Dynamics-Aesthetics framework (MDAManager, a dynamics simulator, aesthetics analyzer, feedback-loop visualizer, plus MDA_AESTHETICS and mechanic templates). narrative/ provides story-structure analysis (NarrativeManager, fabula/syuzhet mapping, dramatic irony, pacing analysis, beat-sheet generation, and structure templates). cinematography/ covers shot design, composition, lighting, and colour theory (CinematographyManager with composition/lighting/colour-theory references and a continuity checker). Each subsystem follows the same types.ts / constants.ts / manager.ts shape with default in-memory storage and reference-data providers.

A narrative scene-order facade (libs/hathor/timeline/src/index.ts). It reconciles story order against shoot order: createHathorTimelineSceneOrderPacket sorts HistoricalEvents chronologically (via sortEventsChronologically / calendarDateToSortKey from @hathor/domain-models), assigns each linked scene a derived storyOrder, and captures world-state tags. validateHathorTimelineSceneOrderPacket detects story-order conflicts and causal-dependency violations (a scene appearing before its causal prerequisite), plus missing scenes/events/world-state and export metadata, under schema hathor-timeline-scene-order/v1. The most algorithmically interesting of the four facades.

Phase 85–86 flywheel producer for the NPC/world domain (libs/hathor/training-data/src): HathorTrainingDataPipeline turns eleven HathorTrainingKind signals — npc-dialogue, npc-emotion, npc-memory-relevance, economy-simulation, political-simulation, cultural-evolution, narrative-quality, and peers — into governance-gated (governanceGrantId), anonymized HathorTrainingRecords delivered to a pluggable HathorTrainingSink.

Lore-consistency validation (libs/hathor/validation/src). Four focused validators — timeline/ (chronological order, era boundaries, lifespans), causality/ (temporal consistency, cycle detection, causal-chain analysis), taxonomy/ (type and hierarchy checking), and contradiction/ (temporal, spatial, attribute, relationship, and state contradictions across characters and locations) — are composed by a top-level LoreValidator (index.ts) that runs the configured set, supports failFast, caps issues per category, and returns a merged LoreValidationResult with error/warning/info counts. Inputs are the @hathor/domain-models event/era/character/location types.

A CGI scene-definition export facade (libs/hathor/world/src/index.ts). createHathorWorldCgiSceneDefinition flattens Location, Region, Era, and Culture domain models — including buildings, rooms, points of interest, architectural styles, terrain, climate, and a coordinate system (origin / up-axis / scale) — into a HathorWorldCgiSceneDefinition under schema hathor-world-cgi-scene/v1, and validateHathorWorldCgiSceneDefinition enforces that required locations, primary time period, cultures, architecture styles, and coordinate/export metadata are all present. Like the other facades it is a real mapper-plus-validator, not a stub.

Hathor's inbound cross-domain event subscriptions (libs/hathor/event-handlers/src). setupHathorEventHandlers wires the HATHOR_SUBSCRIPTIONS map — sophia.document.ingested, isis.asset.generated, yemaya.project.created, yemaya.character.created — onto an @oshun/event-bus IEventBus, builds a per-event HathorHandlerContext (world graph, world/suggestion/character/asset/ relationship repositories, a job queue, logger), and returns a handle with stop(), isRunning(), and getStats(). The four handlers live under src/handlers/ and grow/maintain the world graph from sibling-domain activity; getHandlerRegistrations() exposes per-event concurrency for custom setups.

Hathor's outbound event surface (libs/hathor/event-publisher/src). The HathorEventPublisher class (hathor-event-publisher.ts) lazily initialises an @oshun/event-bus connection and exposes type-safe publish methods for the domain's lifecycle events — world created/published/validated, element added, narrative generated, simulation started/completed — keyed off HathorEventTypes from @oshun/contracts. It honours an enabled flag (logging "disabled" and skipping the bus when off) and is exposed as a singleton via getHathorEventPublisher / createHathorEventPublisher / resetHathorEventPublisher.