# Hathor Domain - Developer Guide

Hathor is the Worldbuilding & Narrative domain. It provides tools for creating,
simulating, and managing fictional worlds, including narrative systems (story
graphs, dialogues, quests), world simulation (economy, politics, culture), and
pre-production tools. Hathor generates living worlds with emergent behavior.

---

## Prerequisites

### Required Software

| Software   | Minimum Version | Purpose                              |
| ---------- | --------------- | ------------------------------------ |
| Node.js    | >= 20.0.0       | Runtime for all Hathor services      |
| pnpm       | >= 9.0.0        | Package manager (monorepo workspace) |
| Docker     | >= 24.0         | Infrastructure (PostgreSQL, Redis)   |
| TypeScript | ^6.0.3          | Type checking and compilation        |

### Optional

| Software | Purpose                                    |
| -------- | ------------------------------------------ |
| Neo4j    | Knowledge graph for world entity relations |
| Redis    | Job queues for simulation workers          |

---

## Project Structure

```
apps/hathor/
  world-api/           # World state management, versioning, queries, merge operations
  narrative-api/       # Story graphs, dialogues, quests, validation
  simulation-worker/   # Background simulation workers (economy, politics, culture)
  workbench/           # React web UI for world management and visualization

libs/hathor/
  client/              # TypeScript SDK (@hathor/client)
  database/            # Prisma schema and generated client (@hathor/database)
  domain-models/       # Core domain model types
  event-handlers/      # Cross-domain event handler setup
  event-publisher/     # Cross-domain event publisher
  llm-npc/             # LLM-powered NPC dialogue and behavior
  lore-compiler/       # Lore consistency validation and compilation
  narrative/           # Narrative export formats (Yarn, Ink, JSON)
  pre-production/      # Pre-production planning tools
  simulation/          # Simulation engine and models
  sophia-integration/  # Sophia domain integration for research
  theory/              # Narrative theory, cinematography, MDA framework
  validation/          # World data validation rules
```

### Simulation Workers

The simulation worker runs specialized sub-workers:

| Worker          | File                 | Purpose                         |
| --------------- | -------------------- | ------------------------------- |
| Economy Worker  | `economy-worker.ts`  | Trade, markets, resource flow   |
| Politics Worker | `politics-worker.ts` | Factions, diplomacy, governance |
| Culture Worker  | `culture-worker.ts`  | Traditions, art, language drift |
| Scenario Worker | `scenario-worker.ts` | What-if scenario simulations    |

All workers extend `BaseWorker` which provides the simulation loop, heartbeat,
health monitoring, and job processing lifecycle.

---

## Local Development Setup

### 1. Start Infrastructure

```bash
# Core services (PostgreSQL + Redis)
docker compose -f docker/docker-compose.dev.yml up -d

# Optional: Neo4j for world entity graphs
docker compose -f docker/docker-compose.dev.yml --profile graph up -d
```

### 2. Set Environment Variables

| Variable              | Default                  | Used By           |
| --------------------- | ------------------------ | ----------------- |
| `HATHOR_DATABASE_URL` | (from root `.env`)       | database lib      |
| `REDIS_URL`           | `redis://localhost:6379` | event bus, queues |
| `PORT`                | `3000`                   | world-api         |
| `HOST`                | `localhost`              | world-api         |
| `NEO4J_URL`           | `bolt://localhost:7687`  | knowledge graph   |

### 3. Database Setup (Prisma)

Hathor has a full Prisma migration setup with an initial migration:

```bash
cd libs/hathor/database

# Generate the Prisma client
npx prisma generate

# Run migrations (applies existing migrations)
npx prisma migrate dev

# Or push schema directly for rapid iteration
npx prisma db push
```

The migration history is at:

```
libs/hathor/database/prisma/migrations/
  20260111231616_init/migration.sql
  migration_lock.toml
```

### 4. Install Dependencies

```bash
pnpm install
```

### 5. Seed the Database

```bash
cd libs/hathor/database
npx tsx prisma/seed.ts       # Standard world data
npx tsx prisma/seed-test.ts  # Test fixtures
```

---

## Running Services

### World API

The central API for world state management. Built with Hono and Zod OpenAPI.
Supports world creation, versioning, graph queries, and merge operations.

```bash
# Development (hot reload)
cd apps/hathor/world-api
pnpm dev   # tsx watch src/index.ts

# Via Nx
pnpm nx serve @hathor/world-api
```

**API routes:**

- `/worlds` - World CRUD operations
- `/versions` - World version management (branching, tagging)
- `/query` - Semantic queries against world state
- `/merge` - Merge world branches with conflict resolution

**Key services:**

- `world.service.ts` - World CRUD and state management
- `version.service.ts` - Version control for worlds
- `query.service.ts` - World state queries
- `world-graph.service.ts` - Graph-based world relationships
- `merge.service.ts` - Branch merging with conflict detection

Rate limiting is enabled via `middleware/rate-limit.ts`.

### Narrative API

Manages story graphs, dialogues, quests, and narrative validation.

```bash
pnpm nx serve @hathor/narrative-api
```

**API routes:**

- `/story-graphs` - Story graph CRUD and traversal
- `/dialogues` - Dialogue tree management
- `/quests` - Quest definition and state tracking
- `/validation` - Lore consistency validation

**Key services:**

- `story-graph.service.ts` - Branching narrative graphs
- `dialogue.service.ts` - Dialogue trees with conditions/effects
- `quest.service.ts` - Quest definitions with objectives
- `validation.service.ts` - Cross-reference validation

### Simulation Worker

Processes simulation jobs that advance world state over time ticks.

```bash
pnpm nx serve @hathor/simulation-worker
```

The worker provides:

- A **job queue** (`queue/job-queue.ts`) for managing simulation jobs
- A **worker pool** (`api/worker-pool.ts`) for running multiple workers
- An **API** (`api/routes.ts`) for submitting and monitoring jobs

**Simulation types:** economy, politics, culture, scenario, integrated

Each worker type extends `BaseWorker` and implements:

- `initialize()` - Load domain-specific models
- `executeTick(job, tickNumber, currentDate, signal)` - Process one time step
- `takeSnapshot(job, tickNumber)` - Capture world state at a point in time
- `compileOutput(job, ticks, snapshots, events, duration)` - Compile results
- `cleanup(job)` - Release resources

**Tick intervals:** hour, day, week, month, year

### Workbench (React Web UI)

A React SPA for world visualization and management.

```bash
pnpm nx serve @hathor/workbench
```

The workbench includes:

- Vite dev server with Tailwind CSS
- Pages: Dashboard, Worlds, Characters, Locations, Factions, Timeline
- API service layer in `src/api/services/`

---

## Building

### Build All Hathor Projects

```bash
pnpm nx run-many --target=build --projects=tag:scope:hathor
```

### Build Individual Projects

```bash
# World API (tsc via @nx/js:tsc)
pnpm nx build @hathor/world-api

# Narrative API (tsc via @nx/js:tsc)
pnpm nx build @hathor/narrative-api

# Simulation Worker (tsc via @nx/js:tsc)
pnpm nx build @hathor/simulation-worker

# Workbench (Vite build)
pnpm nx build @hathor/workbench

# Client SDK (tsup)
pnpm nx build @hathor/client
```

---

## Testing

### Test Runner Configuration

Hathor uses a mix of Vitest and Jest:

| Project           | Runner | Executor        |
| ----------------- | ------ | --------------- |
| world-api         | Vitest | `@nx/vite:test` |
| narrative-api     | Jest   | `@nx/jest:jest` |
| simulation-worker | Vitest | `@nx/vite:test` |
| workbench         | Vitest | `@nx/vite:test` |
| database lib      | Vitest | `@nx/vite:test` |
| client lib        | Vitest | (tsup project)  |
| theory lib        | Vitest | `@nx/vite:test` |

### Running Tests

```bash
# All Hathor projects
pnpm nx run-many --target=test --projects=tag:scope:hathor

# Individual projects
pnpm nx test @hathor/world-api
pnpm nx test @hathor/narrative-api
pnpm nx test @hathor/simulation-worker
pnpm nx test @hathor/workbench
pnpm nx test @hathor/database
pnpm nx test @hathor/theory
```

### Testing Simulation Workers

The simulation workers use `AbortController` for cancellation. Test workers by
providing a mock `JobQueue`:

```typescript
import { JobQueue } from '../queue/job-queue.js';

const queue = new JobQueue();
queue.enqueue({
  type: 'economy',
  worldId: 'test-world',
  input: {
    startDate: '2024-01-01',
    endDate: '2024-12-31',
    tickInterval: 'month',
    snapshotInterval: 3,
  },
  // ... other required fields
});

const worker = new EconomyWorker({ type: 'economy' });
await worker.start(queue);
```

### Linting

```bash
pnpm nx run-many --target=lint --projects=tag:scope:hathor
```

---

## Database Schema

The Hathor database (`libs/hathor/database/prisma/schema.prisma`) uses
PostgreSQL with Prisma ORM. The database URL is `HATHOR_DATABASE_URL`.

Key model areas:

- **Worlds** - World definitions, metadata, settings
- **Entities** - Characters, locations, factions, items, events
- **Relations** - Typed relationships between world entities
- **Versions** - World version control (branches, tags, commits)
- **Simulations** - Simulation run records, snapshots, events
- **Narratives** - Story graphs, dialogue trees, quest definitions

### Prisma Workflow

```bash
# After schema changes
cd libs/hathor/database

# Generate client
npx prisma generate

# Create migration
npx prisma migrate dev --name describe_your_change

# Apply in production
npx prisma migrate deploy

# Reset (destructive)
npx prisma migrate reset
```

---

## Common Development Tasks

### Creating a New World Template

World templates provide starting configurations for new worlds.

1. Define the template data structure with world settings, initial entities, and
   simulation parameters.

2. Add the template to the seed script (`libs/hathor/database/prisma/seed.ts`).

3. Create a template endpoint in the world-api if templates should be selectable
   via the API.

4. Add validation rules in `libs/hathor/validation/` for any template-specific
   constraints.

5. If the template includes pre-built lore, integrate with the lore compiler
   (`libs/hathor/lore-compiler/`) for consistency validation.

### Adding a New Simulation Type

1. Create a new worker in `apps/hathor/simulation-worker/src/workers/`:

   ```typescript
   import { BaseWorker, type BaseWorkerConfig } from './base-worker.js';

   export class ReligionWorker extends BaseWorker {
     protected async initialize(): Promise<void> {
       // Load religion simulation models
     }

     protected async executeTick(
       job: SimulationJob,
       tickNumber: number,
       currentDate: Date,
       signal: AbortSignal
     ): Promise<{ events: Event[]; metrics: Record<string, unknown> }> {
       // Simulate one time step of religious dynamics
       return { events: [], metrics: {} };
     }

     protected async takeSnapshot(
       job: SimulationJob,
       tickNumber: number
     ): Promise<string> {
       // Capture state snapshot, return snapshot ID
       return `snapshot-${tickNumber}`;
     }

     protected async compileOutput(
       job,
       ticks,
       snapshots,
       events,
       duration
     ): Promise<SimulationOutput> {
       // Compile final simulation report
       return {
         /* ... */
       };
     }

     protected async cleanup(job: SimulationJob): Promise<void> {
       // Release resources
     }
   }
   ```

2. Add the simulation type to the `SimulationType` type definition in
   `apps/hathor/simulation-worker/src/types/index.ts`.

3. Register the worker in `apps/hathor/simulation-worker/src/workers/index.ts`.

4. Add the worker to the worker pool in `api/worker-pool.ts`.

5. Update the simulation library (`libs/hathor/simulation/`) with domain models
   for the new simulation type.

### Adding a New Narrative Export Format

The narrative library (`libs/hathor/narrative/`) supports exporting to multiple
formats.

1. Create an exporter in `libs/hathor/narrative/src/export/`:

   ```typescript
   import type {
     NarrativeExporter,
     ExportOptions,
     ExportResult,
   } from './types.js';

   export class TwineExporter implements NarrativeExporter {
     export(storyGraph: StoryGraph, options: ExportOptions): ExportResult {
       // Convert story graph to Twine format
     }
   }
   ```

2. Register the exporter in `exporter-factory.ts`.

3. Existing exporters for reference:
   - `yarn-exporter.ts` - Yarn Spinner format
   - `ink-exporter.ts` - Inkle's Ink format
   - `json-exporter.ts` - Generic JSON format

### Integrating LLM NPCs

The `libs/hathor/llm-npc/` library provides LLM-powered NPC dialogue.

1. Define NPC personality, knowledge, and behavior in the NPC configuration.
2. The LLM NPC system uses the NPC's world context (from the world-api) and
   narrative state (from the narrative-api) to generate contextual dialogue.
3. Integration with the Sophia domain (via `libs/hathor/sophia-integration/`)
   provides research knowledge to NPC responses.

---

## Debugging Tips

### World API Not Starting

- Check that PostgreSQL is running and `HATHOR_DATABASE_URL` is correct
- Verify Prisma client is generated: `npx prisma generate`
- The world-api uses Hono with `@hono/zod-openapi`; validation errors appear in
  response bodies
- Check that `@oshun/event-bus` can connect to Redis

### Narrative Validation Failures

- The validation service checks lore consistency across story graphs
- Cross-reference errors indicate conflicting world facts
- Check the story graph for orphaned nodes (unreachable from root)
- Dialogue trees must have valid condition expressions

### Simulation Worker Issues

- Workers process jobs from the `JobQueue` in a polling loop (1-second interval)
- Jobs are matched to workers by `SimulationType`
- Workers report health via `getHealth()` (memory usage, uptime, job counts)
- Cancellation uses `AbortController`; check `signal.aborted` in tick loops
- The tick interval must match the job's `tickInterval` setting
- Snapshot frequency is controlled by `snapshotInterval` (every N ticks)

### Database Migration Issues

- Migrations are in `libs/hathor/database/prisma/migrations/`
- If migrations are out of sync: `npx prisma migrate reset` (destructive)
- For schema drift: `npx prisma db push --accept-data-loss` (development only)
- Check the `migration_lock.toml` for provider consistency

### Workbench Build Issues

- The workbench uses Vite with Tailwind CSS
- Test setup is in `src/test/setup.ts`
- API mock data is available in `src/api/mock-data.ts` for offline development
- The workbench includes API services for all domain resources: `worlds`,
  `characters`, `factions`, `locations`, `timeline`, `dashboard`

### Performance Considerations

- Simulation ticks yield control every 100 iterations (`await sleep(0)`)
- Snapshot intervals should be tuned for memory usage vs. granularity
- The world-api includes rate limiting middleware
- Version branching creates copies of world state; monitor database size
- The merge service handles conflict detection; review merge conflicts before
  accepting
