# Veilborn Chronicles Migration to Hathor

## Executive Summary

This document outlines the migration plan for Lilith's Veilborn game services
(veilborn-core and veilborn-strategy) to Hathor's world simulation platform. The
migration preserves all game mechanics while leveraging Hathor's versioning,
narrative, and simulation capabilities.

**Total Codebase**: ~76K LOC

- veilborn-core: 40,849 LOC
- veilborn-strategy: 35,346 LOC

**Estimated Effort**: 10-12 weeks

---

## 1. Source Systems Overview

### veilborn-core

Core game mechanics including:

- **Character System**: 12 Paths, 5 Resonance types, Thread abilities,
  Awakenings
- **Combat System**: Hex-grid, Tide initiative, action economy, dice pools
- **World Systems**: Tri-planar territory control, ley lines, supply routes
- **Narrative (Weave)**: Graph-based story threads, nodes, connections
- **Game State**: Phase/turn management, undo/redo, snapshots

### veilborn-strategy

Five interconnected strategy game modes:

- **Veil War**: Tri-planar territory control (foundation)
- **Resonance Wars**: Poker-like simultaneous action combat
- **Eternal Game**: Go-like influence projection
- **Echoes of Fate**: Temporal reasoning with prophecies
- **Weave Conspiracy**: Social deduction with hidden agendas

Plus sophisticated AI systems:

- 5 difficulty tiers (Novice → Grandmaster)
- 5 personality types (Aggressive, Defensive, etc.)
- Balance testing framework with tournaments

---

## 2. Migration Mapping

### Entity Mapping

| Veilborn     | Hathor                    |
| ------------ | ------------------------- |
| Character    | Entity (type: character)  |
| Faction      | Entity (type: faction)    |
| Territory    | Entity (type: location)   |
| Weave Thread | Story Arc                 |
| Weave Node   | Story Beat / Event Entity |
| Game Session | World Version             |
| Campaign     | World                     |

### System Mapping

| Veilborn System   | Hathor Integration           |
| ----------------- | ---------------------------- |
| Combat            | Scenario Simulation Worker   |
| Territory Control | Politics Simulation Worker   |
| Weave Graph       | Narrative API (Story Graphs) |
| AI Opponents      | Simulation Parameters        |
| Balance Testing   | Batch Job Processing         |

---

## 3. Phased Migration Plan

### Phase 1: Data Foundation (Weeks 1-2)

- [ ] Create Hathor entity schemas for Veilborn data
- [ ] Build character → entity migration scripts
- [ ] Build faction → entity migration scripts
- [ ] Build territory → location migration scripts
- [ ] Implement resonance system as entity properties
- [ ] Create database migration tools with rollback

### Phase 2: Narrative System (Weeks 2-3)

- [ ] Map Weave threads to Hathor story arcs
- [ ] Map Weave nodes to story beats/events
- [ ] Implement quest objective mapping
- [ ] Create dialogue tree integration
- [ ] Build trigger/effect system for beats

### Phase 3: Simulation Workers (Weeks 3-5)

- [ ] Create VeilWarScenarioWorker
- [ ] Create ResonanceWarsWorker
- [ ] Create EternalGameWorker
- [ ] Create EchoesOfFateWorker (temporal)
- [ ] Create WeaveConspiracyWorker
- [ ] Implement difficulty parameter system
- [ ] Add simulation output processors

### Phase 4: AI System (Weeks 4-5)

- [ ] Port difficulty tiers to simulation parameters
- [ ] Migrate personality system
- [ ] Implement AI decision logging
- [ ] Build AI tournament system as batch jobs
- [ ] Create pattern tracking on aggregated results

### Phase 5: Testing & Validation (Week 6)

- [ ] Data integrity validation
- [ ] Replay recorded game sessions
- [ ] AI behavior consistency tests
- [ ] Performance benchmarking
- [ ] Migration rollback testing

---

## 4. Technical Details

### Character Entity Schema

```typescript
// Hathor Entity for Veilborn Character
{
  type: 'character',
  name: string,
  properties: {
    path: PathName,
    resonance: {
      clarity: number,
      flow: number,
      presence: number,
      root: number,
      void: number
    },
    stats: {
      vitality: number,
      will: number,
      presence: number,
      instinct: number,
      attunement: number,
      cognition: number
    },
    veilPoints: number,
    level: number,
    experience: number
  }
}
```

### Territory as Location Entity

```typescript
{
  type: 'location',
  name: string,
  properties: {
    territoryType: 'heartland' | 'borderland' | 'wasteland' | 'sacred_site' | 'nexus',
    position: { x: number, y: number },
    control: {
      material: { faction: string, strength: number },
      resonance: { faction: string, strength: number },
      void: { faction: string, strength: number }
    },
    supplyStatus: 'supplied' | 'foraging' | 'starving',
    leyLineType?: 'minor' | 'major' | 'primal' | 'confluence'
  }
}
```

### Veil War Simulation Job

```typescript
{
  type: 'scenario',
  subtype: 'veil_war',
  input: {
    territories: Territory[],
    armies: Army[],
    supplyRoutes: SupplyRoute[],
    aiParams: {
      evaluationDepth: number,
      randomnessFactor: number,
      mistakeChance: number,
      planningHorizon: number
    }
  },
  tickInterval: 'day',
  snapshotInterval: 1
}
```

---

## 5. Risk Mitigation

| Risk                    | Mitigation                            |
| ----------------------- | ------------------------------------- |
| State explosion         | Snapshot intervals, worker limits     |
| AI consistency          | Deterministic RNG with seeds          |
| Performance degradation | Spatial indexing, incremental updates |
| Weave complexity        | Arc/beat hierarchy, lazy loading      |
| Migration failures      | Dual-write validation, rollback       |

---

## 6. Success Criteria

### Must-Have

- All character data migrated with stat integrity
- All faction/territory data accessible via Hathor APIs
- Weave system functional in story graphs
- Simulation workers process game mode logic
- AI personality system preserved

### Should-Have

- Balance testing pipeline automated
- Real-time multiplayer via Hathor
- Performance matching original
- Complete audit trail

### Nice-to-Have

- Enhanced territory visualization
- Expanded balance metrics
- Advanced AI analytics

---

## 7. Dependencies

### Required Before Migration

- Hathor Database Schema complete ✓
- Hathor Client SDK complete ✓
- Hathor Sophia Integration complete ✓
- Simulation Worker infrastructure ✓

### External Dependencies

- PostgreSQL database provisioned
- Worker queue (Redis/Bull) configured
- Monitoring/alerting in place

---

## Conclusion

The Veilborn game engine represents a substantial codebase (76K LOC) with
sophisticated mechanics that map well to Hathor's architecture. The migration
will:

1. Preserve all game mechanics and data
2. Enable version-controlled world states
3. Provide scalable simulation infrastructure
4. Support AI-driven automated balance testing
5. Integrate with Hathor's narrative system

Estimated timeline: 10-12 weeks with dedicated development effort.
