burnrate 0.1.0

package/dist/db/turso-database.js

@@ -0,0 +1,1586 @@
+/**
+ * BURNRATE Database Layer (Turso/LibSQL)
+ * Multiplayer-ready persistence using Turso distributed SQLite
+ */
+import { createClient } from '@libsql/client';
+import { v4 as uuid } from 'uuid';
+import { emptyInventory, getIntelFreshness, getDecayedSignalQuality, applyIntelDecay } from '../core/types.js';
+export class TursoDatabase {
+    client;
+    constructor(url, authToken) {
+        // Use environment variables or fall back to local file for dev
+        this.client = createClient({
+            url: url || process.env.TURSO_DATABASE_URL || 'file:local.db',
+            authToken: authToken || process.env.TURSO_AUTH_TOKEN,
+        });
+    }
+    async initialize() {
+        await this.initSchema();
+    }
+    // ============================================================================
+    // TRANSACTION SUPPORT
+    // ============================================================================
+    /**
+     * Execute multiple statements in a single transaction.
+     * All statements succeed or all fail.
+     */
+    async transaction(fn) {
+        const statements = [];
+        const ctx = new TransactionContext(statements);
+        // Collect all statements
+        const result = await fn(ctx);
+        // Execute as batch with write mode (transaction)
+        if (statements.length > 0) {
+            await this.client.batch(statements, 'write');
+        }
+        return result;
+    }
+    /**
+     * Execute a batch of independent statements efficiently.
+     * Not a transaction - some may succeed while others fail.
+     */
+    async batch(statements) {
+        if (statements.length > 0) {
+            await this.client.batch(statements);
+        }
+    }
+    async initSchema() {
+        const statements = [
+            // World state
+            `CREATE TABLE IF NOT EXISTS world (
+        id INTEGER PRIMARY KEY CHECK (id = 1),
+        current_tick INTEGER NOT NULL DEFAULT 0,
+        season_number INTEGER NOT NULL DEFAULT 1,
+        season_week INTEGER NOT NULL DEFAULT 1
+      )`,
+            // Zones
+            `CREATE TABLE IF NOT EXISTS zones (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        type TEXT NOT NULL,
+        owner_id TEXT,
+        supply_level REAL NOT NULL DEFAULT 100,
+        burn_rate INTEGER NOT NULL,
+        compliance_streak INTEGER NOT NULL DEFAULT 0,
+        su_stockpile INTEGER NOT NULL DEFAULT 0,
+        inventory TEXT NOT NULL DEFAULT '{}',
+        production_capacity INTEGER NOT NULL DEFAULT 0,
+        garrison_level INTEGER NOT NULL DEFAULT 0,
+        market_depth REAL NOT NULL DEFAULT 1.0,
+        medkit_stockpile INTEGER NOT NULL DEFAULT 0,
+        comms_stockpile INTEGER NOT NULL DEFAULT 0
+      )`,
+            // Routes
+            `CREATE TABLE IF NOT EXISTS routes (
+        id TEXT PRIMARY KEY,
+        from_zone_id TEXT NOT NULL,
+        to_zone_id TEXT NOT NULL,
+        distance INTEGER NOT NULL,
+        capacity INTEGER NOT NULL,
+        base_risk REAL NOT NULL,
+        chokepoint_rating REAL NOT NULL DEFAULT 1.0,
+        FOREIGN KEY (from_zone_id) REFERENCES zones(id),
+        FOREIGN KEY (to_zone_id) REFERENCES zones(id)
+      )`,
+            // Players
+            `CREATE TABLE IF NOT EXISTS players (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL UNIQUE,
+        api_key TEXT UNIQUE,
+        tier TEXT NOT NULL DEFAULT 'freelance',
+        inventory TEXT NOT NULL DEFAULT '{}',
+        location_id TEXT NOT NULL,
+        faction_id TEXT,
+        reputation INTEGER NOT NULL DEFAULT 0,
+        actions_today INTEGER NOT NULL DEFAULT 0,
+        last_action_tick INTEGER NOT NULL DEFAULT 0,
+        licenses TEXT NOT NULL DEFAULT '{"courier":true,"freight":false,"convoy":false}',
+        tutorial_step INTEGER NOT NULL DEFAULT 0,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (location_id) REFERENCES zones(id),
+        FOREIGN KEY (faction_id) REFERENCES factions(id)
+      )`,
+            // Factions
+            `CREATE TABLE IF NOT EXISTS factions (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL UNIQUE,
+        tag TEXT NOT NULL UNIQUE,
+        founder_id TEXT NOT NULL,
+        treasury TEXT NOT NULL DEFAULT '{}',
+        officer_withdraw_limit INTEGER NOT NULL DEFAULT 1000,
+        doctrine_hash TEXT,
+        upgrades TEXT NOT NULL DEFAULT '{}',
+        relations TEXT NOT NULL DEFAULT '{}',
+        FOREIGN KEY (founder_id) REFERENCES players(id)
+      )`,
+            // Faction members
+            `CREATE TABLE IF NOT EXISTS faction_members (
+        faction_id TEXT NOT NULL,
+        player_id TEXT NOT NULL,
+        rank TEXT NOT NULL DEFAULT 'member',
+        joined_at INTEGER NOT NULL,
+        PRIMARY KEY (faction_id, player_id),
+        FOREIGN KEY (faction_id) REFERENCES factions(id),
+        FOREIGN KEY (player_id) REFERENCES players(id)
+      )`,
+            // Shipments
+            `CREATE TABLE IF NOT EXISTS shipments (
+        id TEXT PRIMARY KEY,
+        player_id TEXT NOT NULL,
+        type TEXT NOT NULL,
+        path TEXT NOT NULL,
+        current_position INTEGER NOT NULL DEFAULT 0,
+        ticks_to_next_zone INTEGER NOT NULL,
+        cargo TEXT NOT NULL DEFAULT '{}',
+        escort_ids TEXT NOT NULL DEFAULT '[]',
+        created_at INTEGER NOT NULL,
+        status TEXT NOT NULL DEFAULT 'in_transit',
+        FOREIGN KEY (player_id) REFERENCES players(id)
+      )`,
+            // Units
+            `CREATE TABLE IF NOT EXISTS units (
+        id TEXT PRIMARY KEY,
+        player_id TEXT NOT NULL,
+        type TEXT NOT NULL,
+        location_id TEXT NOT NULL,
+        strength INTEGER NOT NULL,
+        speed INTEGER NOT NULL,
+        maintenance INTEGER NOT NULL,
+        assignment_id TEXT,
+        for_sale_price INTEGER,
+        FOREIGN KEY (player_id) REFERENCES players(id),
+        FOREIGN KEY (location_id) REFERENCES zones(id)
+      )`,
+            // Market orders
+            `CREATE TABLE IF NOT EXISTS market_orders (
+        id TEXT PRIMARY KEY,
+        player_id TEXT NOT NULL,
+        zone_id TEXT NOT NULL,
+        resource TEXT NOT NULL,
+        side TEXT NOT NULL,
+        price INTEGER NOT NULL,
+        quantity INTEGER NOT NULL,
+        original_quantity INTEGER NOT NULL,
+        created_at INTEGER NOT NULL,
+        FOREIGN KEY (player_id) REFERENCES players(id),
+        FOREIGN KEY (zone_id) REFERENCES zones(id)
+      )`,
+            // Trades
+            `CREATE TABLE IF NOT EXISTS trades (
+        id TEXT PRIMARY KEY,
+        zone_id TEXT NOT NULL,
+        resource TEXT NOT NULL,
+        buyer_id TEXT NOT NULL,
+        seller_id TEXT NOT NULL,
+        price INTEGER NOT NULL,
+        quantity INTEGER NOT NULL,
+        executed_at INTEGER NOT NULL,
+        FOREIGN KEY (zone_id) REFERENCES zones(id)
+      )`,
+            // Contracts
+            `CREATE TABLE IF NOT EXISTS contracts (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL,
+        poster_id TEXT NOT NULL,
+        poster_type TEXT NOT NULL,
+        accepted_by TEXT,
+        details TEXT NOT NULL DEFAULT '{}',
+        deadline INTEGER NOT NULL,
+        reward TEXT NOT NULL DEFAULT '{}',
+        bonus TEXT,
+        status TEXT NOT NULL DEFAULT 'open',
+        created_at INTEGER NOT NULL
+      )`,
+            // Intel reports
+            `CREATE TABLE IF NOT EXISTS intel (
+        id TEXT PRIMARY KEY,
+        player_id TEXT NOT NULL,
+        faction_id TEXT,
+        target_type TEXT NOT NULL,
+        target_id TEXT NOT NULL,
+        gathered_at INTEGER NOT NULL,
+        data TEXT NOT NULL DEFAULT '{}',
+        signal_quality INTEGER NOT NULL,
+        FOREIGN KEY (player_id) REFERENCES players(id),
+        FOREIGN KEY (faction_id) REFERENCES factions(id)
+      )`,
+            // Game events
+            `CREATE TABLE IF NOT EXISTS events (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL,
+        tick INTEGER NOT NULL,
+        timestamp TEXT NOT NULL,
+        actor_id TEXT,
+        actor_type TEXT NOT NULL,
+        data TEXT NOT NULL DEFAULT '{}',
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      )`,
+            // Season scores
+            `CREATE TABLE IF NOT EXISTS season_scores (
+        id TEXT PRIMARY KEY,
+        season_number INTEGER NOT NULL,
+        entity_id TEXT NOT NULL,
+        entity_type TEXT NOT NULL,
+        entity_name TEXT NOT NULL,
+        zones_controlled INTEGER NOT NULL DEFAULT 0,
+        supply_delivered INTEGER NOT NULL DEFAULT 0,
+        shipments_completed INTEGER NOT NULL DEFAULT 0,
+        contracts_completed INTEGER NOT NULL DEFAULT 0,
+        reputation_gained INTEGER NOT NULL DEFAULT 0,
+        combat_victories INTEGER NOT NULL DEFAULT 0,
+        total_score INTEGER NOT NULL DEFAULT 0,
+        UNIQUE(season_number, entity_id)
+      )`,
+            // Doctrines (Phase 5)
+            `CREATE TABLE IF NOT EXISTS doctrines (
+        id TEXT PRIMARY KEY,
+        faction_id TEXT NOT NULL,
+        title TEXT NOT NULL,
+        content TEXT NOT NULL,
+        version INTEGER NOT NULL DEFAULT 1,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        created_by TEXT NOT NULL,
+        FOREIGN KEY (faction_id) REFERENCES factions(id),
+        FOREIGN KEY (created_by) REFERENCES players(id)
+      )`,
+            // Webhooks (Phase 6)
+            `CREATE TABLE IF NOT EXISTS webhooks (
+        id TEXT PRIMARY KEY,
+        player_id TEXT NOT NULL,
+        url TEXT NOT NULL,
+        events TEXT NOT NULL DEFAULT '[]',
+        active INTEGER NOT NULL DEFAULT 1,
+        created_at INTEGER NOT NULL,
+        last_triggered_at INTEGER,
+        fail_count INTEGER NOT NULL DEFAULT 0,
+        FOREIGN KEY (player_id) REFERENCES players(id)
+      )`,
+            // Conditional orders (Phase 5)
+            `CREATE TABLE IF NOT EXISTS conditional_orders (
+        id TEXT PRIMARY KEY,
+        player_id TEXT NOT NULL,
+        zone_id TEXT NOT NULL,
+        resource TEXT NOT NULL,
+        side TEXT NOT NULL,
+        trigger_price INTEGER NOT NULL,
+        quantity INTEGER NOT NULL,
+        condition TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'active',
+        created_at INTEGER NOT NULL,
+        FOREIGN KEY (player_id) REFERENCES players(id),
+        FOREIGN KEY (zone_id) REFERENCES zones(id)
+      )`,
+            // Time-weighted orders (Phase 5)
+            `CREATE TABLE IF NOT EXISTS time_weighted_orders (
+        id TEXT PRIMARY KEY,
+        player_id TEXT NOT NULL,
+        zone_id TEXT NOT NULL,
+        resource TEXT NOT NULL,
+        side TEXT NOT NULL,
+        price INTEGER NOT NULL,
+        total_quantity INTEGER NOT NULL,
+        remaining_quantity INTEGER NOT NULL,
+        quantity_per_tick INTEGER NOT NULL,
+        status TEXT NOT NULL DEFAULT 'active',
+        created_at INTEGER NOT NULL,
+        FOREIGN KEY (player_id) REFERENCES players(id),
+        FOREIGN KEY (zone_id) REFERENCES zones(id)
+      )`,
+            // Audit logs (Phase 7)
+            `CREATE TABLE IF NOT EXISTS audit_logs (
+        id TEXT PRIMARY KEY,
+        faction_id TEXT NOT NULL,
+        player_id TEXT NOT NULL,
+        action TEXT NOT NULL,
+        details TEXT NOT NULL DEFAULT '{}',
+        tick INTEGER NOT NULL,
+        timestamp TEXT NOT NULL,
+        FOREIGN KEY (faction_id) REFERENCES factions(id),
+        FOREIGN KEY (player_id) REFERENCES players(id)
+      )`,
+            // Indexes
+            `CREATE INDEX IF NOT EXISTS idx_events_tick ON events(tick)`,
+            `CREATE INDEX IF NOT EXISTS idx_events_type ON events(type)`,
+            `CREATE INDEX IF NOT EXISTS idx_events_actor ON events(actor_id)`,
+            `CREATE INDEX IF NOT EXISTS idx_intel_faction ON intel(faction_id)`,
+            `CREATE INDEX IF NOT EXISTS idx_players_api_key ON players(api_key)`,
+            `CREATE INDEX IF NOT EXISTS idx_season_scores_season ON season_scores(season_number)`,
+            `CREATE INDEX IF NOT EXISTS idx_season_scores_total ON season_scores(total_score DESC)`,
+            `CREATE INDEX IF NOT EXISTS idx_doctrines_faction ON doctrines(faction_id)`,
+            `CREATE INDEX IF NOT EXISTS idx_webhooks_player ON webhooks(player_id)`,
+            `CREATE INDEX IF NOT EXISTS idx_conditional_orders_status ON conditional_orders(status)`,
+            `CREATE INDEX IF NOT EXISTS idx_time_weighted_orders_status ON time_weighted_orders(status)`,
+            `CREATE INDEX IF NOT EXISTS idx_audit_logs_faction ON audit_logs(faction_id)`,
+            `CREATE INDEX IF NOT EXISTS idx_audit_logs_tick ON audit_logs(tick)`,
+            // Initialize world state
+            `INSERT OR IGNORE INTO world (id, current_tick, season_number, season_week) VALUES (1, 0, 1, 1)`,
+        ];
+        for (const sql of statements) {
+            await this.client.execute(sql);
+        }
+    }
+    // ============================================================================
+    // WORLD STATE
+    // ============================================================================
+    async getCurrentTick() {
+        const result = await this.client.execute('SELECT current_tick FROM world WHERE id = 1');
+        return result.rows[0]?.current_tick || 0;
+    }
+    async incrementTick() {
+        await this.client.execute('UPDATE world SET current_tick = current_tick + 1 WHERE id = 1');
+        return this.getCurrentTick();
+    }
+    async getSeasonInfo() {
+        const result = await this.client.execute('SELECT season_number, season_week FROM world WHERE id = 1');
+        const row = result.rows[0];
+        return {
+            seasonNumber: row?.season_number || 1,
+            seasonWeek: row?.season_week || 1
+        };
+    }
+    // ============================================================================
+    // ZONES
+    // ============================================================================
+    async createZone(zone) {
+        const id = uuid();
+        await this.client.execute({
+            sql: `INSERT INTO zones (id, name, type, owner_id, supply_level, burn_rate, compliance_streak,
+                               su_stockpile, inventory, production_capacity, garrison_level, market_depth,
+                               medkit_stockpile, comms_stockpile)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+            args: [id, zone.name, zone.type, zone.ownerId, zone.supplyLevel, zone.burnRate,
+                zone.complianceStreak, zone.suStockpile, JSON.stringify(zone.inventory),
+                zone.productionCapacity, zone.garrisonLevel, zone.marketDepth,
+                zone.medkitStockpile, zone.commsStockpile]
+        });
+        return { id, ...zone };
+    }
+    async getZone(id) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM zones WHERE id = ?',
+            args: [id]
+        });
+        if (result.rows.length === 0)
+            return null;
+        return this.rowToZone(result.rows[0]);
+    }
+    async getAllZones() {
+        const result = await this.client.execute('SELECT * FROM zones');
+        return result.rows.map(row => this.rowToZone(row));
+    }
+    async updateZone(id, updates) {
+        const sets = [];
+        const values = [];
+        if (updates.ownerId !== undefined) {
+            sets.push('owner_id = ?');
+            values.push(updates.ownerId);
+        }
+        if (updates.supplyLevel !== undefined) {
+            sets.push('supply_level = ?');
+            values.push(updates.supplyLevel);
+        }
+        if (updates.complianceStreak !== undefined) {
+            sets.push('compliance_streak = ?');
+            values.push(updates.complianceStreak);
+        }
+        if (updates.suStockpile !== undefined) {
+            sets.push('su_stockpile = ?');
+            values.push(updates.suStockpile);
+        }
+        if (updates.inventory !== undefined) {
+            sets.push('inventory = ?');
+            values.push(JSON.stringify(updates.inventory));
+        }
+        if (updates.garrisonLevel !== undefined) {
+            sets.push('garrison_level = ?');
+            values.push(updates.garrisonLevel);
+        }
+        if (updates.medkitStockpile !== undefined) {
+            sets.push('medkit_stockpile = ?');
+            values.push(updates.medkitStockpile);
+        }
+        if (updates.commsStockpile !== undefined) {
+            sets.push('comms_stockpile = ?');
+            values.push(updates.commsStockpile);
+        }
+        if (sets.length === 0)
+            return;
+        values.push(id);
+        await this.client.execute({
+            sql: `UPDATE zones SET ${sets.join(', ')} WHERE id = ?`,
+            args: values
+        });
+    }
+    rowToZone(row) {
+        return {
+            id: row.id,
+            name: row.name,
+            type: row.type,
+            ownerId: row.owner_id,
+            supplyLevel: row.supply_level,
+            burnRate: row.burn_rate,
+            complianceStreak: row.compliance_streak,
+            suStockpile: row.su_stockpile,
+            inventory: JSON.parse(row.inventory),
+            productionCapacity: row.production_capacity,
+            garrisonLevel: row.garrison_level,
+            marketDepth: row.market_depth,
+            medkitStockpile: row.medkit_stockpile || 0,
+            commsStockpile: row.comms_stockpile || 0
+        };
+    }
+    // ============================================================================
+    // ROUTES
+    // ============================================================================
+    async createRoute(route) {
+        const id = uuid();
+        await this.client.execute({
+            sql: `INSERT INTO routes (id, from_zone_id, to_zone_id, distance, capacity, base_risk, chokepoint_rating)
+            VALUES (?, ?, ?, ?, ?, ?, ?)`,
+            args: [id, route.fromZoneId, route.toZoneId, route.distance, route.capacity, route.baseRisk, route.chokepointRating]
+        });
+        return { id, ...route };
+    }
+    async getRoute(id) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM routes WHERE id = ?',
+            args: [id]
+        });
+        if (result.rows.length === 0)
+            return null;
+        return this.rowToRoute(result.rows[0]);
+    }
+    async getRoutesBetween(fromZoneId, toZoneId) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM routes WHERE from_zone_id = ? AND to_zone_id = ?',
+            args: [fromZoneId, toZoneId]
+        });
+        return result.rows.map(row => this.rowToRoute(row));
+    }
+    async getRoutesFromZone(zoneId) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM routes WHERE from_zone_id = ?',
+            args: [zoneId]
+        });
+        return result.rows.map(row => this.rowToRoute(row));
+    }
+    async getAllRoutes() {
+        const result = await this.client.execute('SELECT * FROM routes');
+        return result.rows.map(row => this.rowToRoute(row));
+    }
+    rowToRoute(row) {
+        return {
+            id: row.id,
+            fromZoneId: row.from_zone_id,
+            toZoneId: row.to_zone_id,
+            distance: row.distance,
+            capacity: row.capacity,
+            baseRisk: row.base_risk,
+            chokepointRating: row.chokepoint_rating
+        };
+    }
+    // ============================================================================
+    // PLAYERS
+    // ============================================================================
+    async createPlayer(name, startingZoneId) {
+        const id = uuid();
+        const apiKey = `br_${uuid().replace(/-/g, '')}`;
+        const inventory = { ...emptyInventory(), credits: 500 };
+        const licenses = { courier: true, freight: false, convoy: false };
+        await this.client.execute({
+            sql: `INSERT INTO players (id, name, api_key, tier, inventory, location_id, reputation, licenses)
+            VALUES (?, ?, ?, 'freelance', ?, ?, 0, ?)`,
+            args: [id, name, apiKey, JSON.stringify(inventory), startingZoneId, JSON.stringify(licenses)]
+        });
+        return {
+            id, name, tier: 'freelance', inventory, locationId: startingZoneId,
+            factionId: null, reputation: 0, actionsToday: 0, lastActionTick: 0, licenses,
+            tutorialStep: 0,
+            apiKey
+        };
+    }
+    async getPlayer(id) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM players WHERE id = ?',
+            args: [id]
+        });
+        if (result.rows.length === 0)
+            return null;
+        return this.rowToPlayer(result.rows[0]);
+    }
+    async getPlayerByApiKey(apiKey) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM players WHERE api_key = ?',
+            args: [apiKey]
+        });
+        if (result.rows.length === 0)
+            return null;
+        return this.rowToPlayer(result.rows[0]);
+    }
+    async getPlayerByName(name) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM players WHERE name = ?',
+            args: [name]
+        });
+        if (result.rows.length === 0)
+            return null;
+        return this.rowToPlayer(result.rows[0]);
+    }
+    async getAllPlayers() {
+        const result = await this.client.execute('SELECT * FROM players');
+        return result.rows.map(row => this.rowToPlayer(row));
+    }
+    async updatePlayer(id, updates) {
+        const sets = [];
+        const values = [];
+        if (updates.inventory !== undefined) {
+            sets.push('inventory = ?');
+            values.push(JSON.stringify(updates.inventory));
+        }
+        if (updates.locationId !== undefined) {
+            sets.push('location_id = ?');
+            values.push(updates.locationId);
+        }
+        if (updates.factionId !== undefined) {
+            sets.push('faction_id = ?');
+            values.push(updates.factionId);
+        }
+        if (updates.reputation !== undefined) {
+            sets.push('reputation = ?');
+            values.push(updates.reputation);
+        }
+        if (updates.actionsToday !== undefined) {
+            sets.push('actions_today = ?');
+            values.push(updates.actionsToday);
+        }
+        if (updates.lastActionTick !== undefined) {
+            sets.push('last_action_tick = ?');
+            values.push(updates.lastActionTick);
+        }
+        if (updates.tier !== undefined) {
+            sets.push('tier = ?');
+            values.push(updates.tier);
+        }
+        if (updates.licenses !== undefined) {
+            sets.push('licenses = ?');
+            values.push(JSON.stringify(updates.licenses));
+        }
+        if (updates.tutorialStep !== undefined) {
+            sets.push('tutorial_step = ?');
+            values.push(updates.tutorialStep);
+        }
+        if (sets.length === 0)
+            return;
+        values.push(id);
+        await this.client.execute({
+            sql: `UPDATE players SET ${sets.join(', ')} WHERE id = ?`,
+            args: values
+        });
+    }
+    rowToPlayer(row) {
+        return {
+            id: row.id,
+            name: row.name,
+            tier: row.tier,
+            inventory: JSON.parse(row.inventory),
+            locationId: row.location_id,
+            factionId: row.faction_id,
+            reputation: row.reputation,
+            actionsToday: row.actions_today,
+            lastActionTick: row.last_action_tick,
+            licenses: JSON.parse(row.licenses),
+            tutorialStep: row.tutorial_step || 0
+        };
+    }
+    // ============================================================================
+    // FACTIONS
+    // ============================================================================
+    async createFaction(name, tag, founderId) {
+        const id = uuid();
+        const treasury = emptyInventory();
+        const upgrades = {
+            relayNetwork: 0,
+            routeFortification: 0,
+            productionBonus: 0,
+            garrisonStrength: 0,
+            marketDepth: 0
+        };
+        const tick = await this.getCurrentTick();
+        await this.client.execute({
+            sql: `INSERT INTO factions (id, name, tag, founder_id, treasury, upgrades, relations)
+            VALUES (?, ?, ?, ?, ?, ?, '{}')`,
+            args: [id, name, tag, founderId, JSON.stringify(treasury), JSON.stringify(upgrades)]
+        });
+        await this.client.execute({
+            sql: `INSERT INTO faction_members (faction_id, player_id, rank, joined_at) VALUES (?, ?, 'founder', ?)`,
+            args: [id, founderId, tick]
+        });
+        await this.updatePlayer(founderId, { factionId: id });
+        return {
+            id, name, tag, founderId, treasury,
+            officerWithdrawLimit: 1000,
+            members: [{ playerId: founderId, rank: 'founder', joinedAt: tick }],
+            controlledZones: [],
+            doctrineHash: null,
+            upgrades,
+            relations: {}
+        };
+    }
+    async getFaction(id) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM factions WHERE id = ?',
+            args: [id]
+        });
+        if (result.rows.length === 0)
+            return null;
+        return this.rowToFaction(result.rows[0]);
+    }
+    async getAllFactions() {
+        const result = await this.client.execute('SELECT * FROM factions');
+        const factions = [];
+        for (const row of result.rows) {
+            factions.push(await this.rowToFaction(row));
+        }
+        return factions;
+    }
+    async rowToFaction(row) {
+        const membersResult = await this.client.execute({
+            sql: 'SELECT player_id, rank, joined_at FROM faction_members WHERE faction_id = ?',
+            args: [row.id]
+        });
+        const zonesResult = await this.client.execute({
+            sql: 'SELECT id FROM zones WHERE owner_id = ?',
+            args: [row.id]
+        });
+        return {
+            id: row.id,
+            name: row.name,
+            tag: row.tag,
+            founderId: row.founder_id,
+            treasury: JSON.parse(row.treasury),
+            officerWithdrawLimit: row.officer_withdraw_limit,
+            members: membersResult.rows.map(m => ({
+                playerId: m.player_id,
+                rank: m.rank,
+                joinedAt: m.joined_at
+            })),
+            controlledZones: zonesResult.rows.map(z => z.id),
+            doctrineHash: row.doctrine_hash,
+            upgrades: JSON.parse(row.upgrades),
+            relations: JSON.parse(row.relations)
+        };
+    }
+    async addFactionMember(factionId, playerId, rank = 'member') {
+        const tick = await this.getCurrentTick();
+        await this.client.execute({
+            sql: `INSERT INTO faction_members (faction_id, player_id, rank, joined_at) VALUES (?, ?, ?, ?)`,
+            args: [factionId, playerId, rank, tick]
+        });
+        await this.updatePlayer(playerId, { factionId });
+    }
+    async removeFactionMember(factionId, playerId) {
+        await this.client.execute({
+            sql: 'DELETE FROM faction_members WHERE faction_id = ? AND player_id = ?',
+            args: [factionId, playerId]
+        });
+        await this.updatePlayer(playerId, { factionId: null });
+    }
+    // ============================================================================
+    // SHIPMENTS
+    // ============================================================================
+    async createShipment(shipment) {
+        const id = uuid();
+        await this.client.execute({
+            sql: `INSERT INTO shipments (id, player_id, type, path, current_position, ticks_to_next_zone,
+                                   cargo, escort_ids, created_at, status)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+            args: [id, shipment.playerId, shipment.type, JSON.stringify(shipment.path),
+                shipment.currentPosition, shipment.ticksToNextZone, JSON.stringify(shipment.cargo),
+                JSON.stringify(shipment.escortIds), shipment.createdAt, shipment.status]
+        });
+        return { id, ...shipment };
+    }
+    async getShipment(id) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM shipments WHERE id = ?',
+            args: [id]
+        });
+        if (result.rows.length === 0)
+            return null;
+        return this.rowToShipment(result.rows[0]);
+    }
+    async getActiveShipments() {
+        const result = await this.client.execute("SELECT * FROM shipments WHERE status = 'in_transit'");
+        return result.rows.map(row => this.rowToShipment(row));
+    }
+    async getPlayerShipments(playerId) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM shipments WHERE player_id = ?',
+            args: [playerId]
+        });
+        return result.rows.map(row => this.rowToShipment(row));
+    }
+    async updateShipment(id, updates) {
+        const sets = [];
+        const values = [];
+        if (updates.currentPosition !== undefined) {
+            sets.push('current_position = ?');
+            values.push(updates.currentPosition);
+        }
+        if (updates.ticksToNextZone !== undefined) {
+            sets.push('ticks_to_next_zone = ?');
+            values.push(updates.ticksToNextZone);
+        }
+        if (updates.status !== undefined) {
+            sets.push('status = ?');
+            values.push(updates.status);
+        }
+        if (updates.escortIds !== undefined) {
+            sets.push('escort_ids = ?');
+            values.push(JSON.stringify(updates.escortIds));
+        }
+        if (sets.length === 0)
+            return;
+        values.push(id);
+        await this.client.execute({
+            sql: `UPDATE shipments SET ${sets.join(', ')} WHERE id = ?`,
+            args: values
+        });
+    }
+    rowToShipment(row) {
+        return {
+            id: row.id,
+            playerId: row.player_id,
+            type: row.type,
+            path: JSON.parse(row.path),
+            currentPosition: row.current_position,
+            ticksToNextZone: row.ticks_to_next_zone,
+            cargo: JSON.parse(row.cargo),
+            escortIds: JSON.parse(row.escort_ids),
+            createdAt: row.created_at,
+            status: row.status
+        };
+    }
+    // ============================================================================
+    // UNITS
+    // ============================================================================
+    async createUnit(unit) {
+        const id = uuid();
+        await this.client.execute({
+            sql: `INSERT INTO units (id, player_id, type, location_id, strength, speed, maintenance, assignment_id, for_sale_price)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+            args: [id, unit.playerId, unit.type, unit.locationId, unit.strength, unit.speed, unit.maintenance, unit.assignmentId, unit.forSalePrice]
+        });
+        return { id, ...unit };
+    }
+    async getUnit(id) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM units WHERE id = ?',
+            args: [id]
+        });
+        if (result.rows.length === 0)
+            return null;
+        return this.rowToUnit(result.rows[0]);
+    }
+    async getPlayerUnits(playerId) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM units WHERE player_id = ?',
+            args: [playerId]
+        });
+        return result.rows.map(row => this.rowToUnit(row));
+    }
+    async getUnitsForSaleAtZone(zoneId) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM units WHERE location_id = ? AND for_sale_price IS NOT NULL',
+            args: [zoneId]
+        });
+        return result.rows.map(row => this.rowToUnit(row));
+    }
+    async updateUnit(id, updates) {
+        const sets = [];
+        const values = [];
+        if (updates.locationId !== undefined) {
+            sets.push('location_id = ?');
+            values.push(updates.locationId);
+        }
+        if (updates.assignmentId !== undefined) {
+            sets.push('assignment_id = ?');
+            values.push(updates.assignmentId);
+        }
+        if (updates.playerId !== undefined) {
+            sets.push('player_id = ?');
+            values.push(updates.playerId);
+        }
+        if (updates.forSalePrice !== undefined) {
+            sets.push('for_sale_price = ?');
+            values.push(updates.forSalePrice);
+        }
+        if (sets.length === 0)
+            return;
+        values.push(id);
+        await this.client.execute({
+            sql: `UPDATE units SET ${sets.join(', ')} WHERE id = ?`,
+            args: values
+        });
+    }
+    async deleteUnit(id) {
+        await this.client.execute({
+            sql: 'DELETE FROM units WHERE id = ?',
+            args: [id]
+        });
+    }
+    rowToUnit(row) {
+        return {
+            id: row.id,
+            playerId: row.player_id,
+            type: row.type,
+            locationId: row.location_id,
+            strength: row.strength,
+            speed: row.speed,
+            maintenance: row.maintenance,
+            assignmentId: row.assignment_id,
+            forSalePrice: row.for_sale_price
+        };
+    }
+    // ============================================================================
+    // MARKET ORDERS
+    // ============================================================================
+    async createOrder(order) {
+        const id = uuid();
+        await this.client.execute({
+            sql: `INSERT INTO market_orders (id, player_id, zone_id, resource, side, price, quantity, original_quantity, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+            args: [id, order.playerId, order.zoneId, order.resource, order.side, order.price, order.quantity, order.originalQuantity, order.createdAt]
+        });
+        return { id, ...order };
+    }
+    async getOrdersForZone(zoneId, resource) {
+        let sql = 'SELECT * FROM market_orders WHERE zone_id = ? AND quantity > 0';
+        const args = [zoneId];
+        if (resource) {
+            sql += ' AND resource = ?';
+            args.push(resource);
+        }
+        sql += ' ORDER BY side, price';
+        const result = await this.client.execute({ sql, args });
+        return result.rows.map(row => this.rowToOrder(row));
+    }
+    async updateOrder(id, quantity) {
+        await this.client.execute({
+            sql: 'UPDATE market_orders SET quantity = ? WHERE id = ?',
+            args: [quantity, id]
+        });
+    }
+    rowToOrder(row) {
+        return {
+            id: row.id,
+            playerId: row.player_id,
+            zoneId: row.zone_id,
+            resource: row.resource,
+            side: row.side,
+            price: row.price,
+            quantity: row.quantity,
+            originalQuantity: row.original_quantity,
+            createdAt: row.created_at
+        };
+    }
+    // ============================================================================
+    // CONTRACTS
+    // ============================================================================
+    async createContract(contract) {
+        const id = uuid();
+        await this.client.execute({
+            sql: `INSERT INTO contracts (id, type, poster_id, poster_type, accepted_by, details, deadline, reward, bonus, status, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+            args: [id, contract.type, contract.posterId, contract.posterType, contract.acceptedBy,
+                JSON.stringify(contract.details), contract.deadline, JSON.stringify(contract.reward),
+                contract.bonus ? JSON.stringify(contract.bonus) : null, contract.status, contract.createdAt]
+        });
+        return { id, ...contract };
+    }
+    async getOpenContracts() {
+        const result = await this.client.execute("SELECT * FROM contracts WHERE status = 'open' ORDER BY created_at DESC");
+        return result.rows.map(row => this.rowToContract(row));
+    }
+    async updateContract(id, updates) {
+        const sets = [];
+        const values = [];
+        if (updates.status) {
+            sets.push('status = ?');
+            values.push(updates.status);
+        }
+        if (updates.acceptedBy) {
+            sets.push('accepted_by = ?');
+            values.push(updates.acceptedBy);
+        }
+        if (sets.length === 0)
+            return;
+        values.push(id);
+        await this.client.execute({
+            sql: `UPDATE contracts SET ${sets.join(', ')} WHERE id = ?`,
+            args: values
+        });
+    }
+    rowToContract(row) {
+        return {
+            id: row.id,
+            type: row.type,
+            posterId: row.poster_id,
+            posterType: row.poster_type,
+            acceptedBy: row.accepted_by,
+            details: JSON.parse(row.details),
+            deadline: row.deadline,
+            reward: JSON.parse(row.reward),
+            bonus: row.bonus ? JSON.parse(row.bonus) : undefined,
+            status: row.status,
+            createdAt: row.created_at
+        };
+    }
+    // ============================================================================
+    // INTEL
+    // ============================================================================
+    async createIntel(intel) {
+        const id = uuid();
+        await this.client.execute({
+            sql: `INSERT INTO intel (id, player_id, faction_id, target_type, target_id, gathered_at, data, signal_quality)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+            args: [id, intel.playerId, intel.factionId, intel.targetType, intel.targetId, intel.gatheredAt, JSON.stringify(intel.data), intel.signalQuality]
+        });
+        return { id, ...intel };
+    }
+    async getFactionIntel(factionId, limit = 100) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM intel WHERE faction_id = ? ORDER BY gathered_at DESC LIMIT ?',
+            args: [factionId, limit]
+        });
+        return result.rows.map(row => this.rowToIntel(row));
+    }
+    rowToIntel(row) {
+        return {
+            id: row.id,
+            playerId: row.player_id,
+            factionId: row.faction_id,
+            targetType: row.target_type,
+            targetId: row.target_id,
+            gatheredAt: row.gathered_at,
+            data: JSON.parse(row.data),
+            signalQuality: row.signal_quality
+        };
+    }
+    // ============================================================================
+    // EVENTS
+    // ============================================================================
+    async recordEvent(event) {
+        const id = uuid();
+        await this.client.execute({
+            sql: `INSERT INTO events (id, type, tick, timestamp, actor_id, actor_type, data)
+            VALUES (?, ?, ?, ?, ?, ?, ?)`,
+            args: [id, event.type, event.tick, event.timestamp.toISOString(), event.actorId, event.actorType, JSON.stringify(event.data)]
+        });
+        return { id, ...event };
+    }
+    async getEvents(options = {}) {
+        let sql = 'SELECT * FROM events WHERE 1=1';
+        const args = [];
+        if (options.type) {
+            sql += ' AND type = ?';
+            args.push(options.type);
+        }
+        if (options.actorId) {
+            sql += ' AND actor_id = ?';
+            args.push(options.actorId);
+        }
+        sql += ' ORDER BY tick DESC, created_at DESC';
+        if (options.limit) {
+            sql += ' LIMIT ?';
+            args.push(options.limit);
+        }
+        const result = await this.client.execute({ sql, args });
+        return result.rows.map(row => ({
+            id: row.id,
+            type: row.type,
+            tick: row.tick,
+            timestamp: new Date(row.timestamp),
+            actorId: row.actor_id,
+            actorType: row.actor_type,
+            data: JSON.parse(row.data)
+        }));
+    }
+    // ============================================================================
+    // PLAYER INTEL (with freshness)
+    // ============================================================================
+    async getPlayerIntel(playerId, limit = 100) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM intel WHERE player_id = ? ORDER BY gathered_at DESC LIMIT ?',
+            args: [playerId, limit]
+        });
+        return result.rows.map(row => this.rowToIntel(row));
+    }
+    /**
+     * Get player intel with freshness calculation and data decay applied.
+     * This is the recommended method for retrieving intel for display.
+     */
+    async getPlayerIntelWithFreshness(playerId, limit = 100) {
+        const currentTick = await this.getCurrentTick();
+        const rawIntel = await this.getPlayerIntel(playerId, limit);
+        return rawIntel.map(intel => this.applyFreshnessToIntel(intel, currentTick));
+    }
+    /**
+     * Get faction intel with freshness calculation and data decay applied.
+     */
+    async getFactionIntelWithFreshness(factionId, limit = 100) {
+        const currentTick = await this.getCurrentTick();
+        const rawIntel = await this.getFactionIntel(factionId, limit);
+        return rawIntel.map(intel => this.applyFreshnessToIntel(intel, currentTick));
+    }
+    /**
+     * Get the most recent intel on a specific target (zone or route).
+     * Returns intel with freshness applied.
+     */
+    async getTargetIntel(playerId, factionId, targetType, targetId) {
+        const currentTick = await this.getCurrentTick();
+        // First try player's own intel
+        let result = await this.client.execute({
+            sql: `SELECT * FROM intel
+            WHERE player_id = ? AND target_type = ? AND target_id = ?
+            ORDER BY gathered_at DESC LIMIT 1`,
+            args: [playerId, targetType, targetId]
+        });
+        // If not found and player has a faction, try faction intel
+        if (result.rows.length === 0 && factionId) {
+            result = await this.client.execute({
+                sql: `SELECT * FROM intel
+              WHERE faction_id = ? AND target_type = ? AND target_id = ?
+              ORDER BY gathered_at DESC LIMIT 1`,
+                args: [factionId, targetType, targetId]
+            });
+        }
+        if (result.rows.length === 0)
+            return null;
+        return this.applyFreshnessToIntel(this.rowToIntel(result.rows[0]), currentTick);
+    }
+    /**
+     * Delete expired intel older than a threshold to keep database clean.
+     * Called periodically during tick processing.
+     */
+    async cleanupExpiredIntel(maxAgeTicks = 200) {
+        const currentTick = await this.getCurrentTick();
+        const threshold = currentTick - maxAgeTicks;
+        const result = await this.client.execute({
+            sql: 'DELETE FROM intel WHERE gathered_at < ?',
+            args: [threshold]
+        });
+        return result.rowsAffected;
+    }
+    /**
+     * Apply freshness calculation to raw intel data
+     */
+    applyFreshnessToIntel(intel, currentTick) {
+        const ageInTicks = currentTick - intel.gatheredAt;
+        const freshness = getIntelFreshness(intel.gatheredAt, currentTick);
+        const effectiveSignalQuality = getDecayedSignalQuality(intel.signalQuality, intel.gatheredAt, currentTick);
+        const decayedData = applyIntelDecay(intel.data, freshness);
+        return {
+            ...intel,
+            data: decayedData,
+            freshness,
+            effectiveSignalQuality,
+            ageInTicks
+        };
+    }
+    // ============================================================================
+    // CONTRACT QUERIES
+    // ============================================================================
+    async getContract(id) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM contracts WHERE id = ?',
+            args: [id]
+        });
+        if (result.rows.length === 0)
+            return null;
+        return this.rowToContract(result.rows[0]);
+    }
+    async getContractsAtZone(zoneId) {
+        const result = await this.client.execute({
+            sql: `SELECT * FROM contracts
+            WHERE status = 'open'
+            AND (json_extract(details, '$.fromZoneId') = ? OR json_extract(details, '$.toZoneId') = ?)
+            ORDER BY created_at DESC`,
+            args: [zoneId, zoneId]
+        });
+        return result.rows.map(row => this.rowToContract(row));
+    }
+    async getPlayerContracts(playerId) {
+        const result = await this.client.execute({
+            sql: `SELECT * FROM contracts WHERE poster_id = ? OR accepted_by = ? ORDER BY created_at DESC`,
+            args: [playerId, playerId]
+        });
+        return result.rows.map(row => this.rowToContract(row));
+    }
+    // ============================================================================
+    // FACTION MEMBER RANK
+    // ============================================================================
+    async getFactionMemberRank(factionId, playerId) {
+        const result = await this.client.execute({
+            sql: 'SELECT rank FROM faction_members WHERE faction_id = ? AND player_id = ?',
+            args: [factionId, playerId]
+        });
+        if (result.rows.length === 0)
+            return null;
+        return result.rows[0].rank;
+    }
+    async updateFactionMemberRank(factionId, playerId, rank) {
+        await this.client.execute({
+            sql: 'UPDATE faction_members SET rank = ? WHERE faction_id = ? AND player_id = ?',
+            args: [rank, factionId, playerId]
+        });
+    }
+    // ============================================================================
+    // FACTION UPDATES
+    // ============================================================================
+    async updateFaction(id, updates) {
+        const sets = [];
+        const values = [];
+        if (updates.founderId !== undefined) {
+            sets.push('founder_id = ?');
+            values.push(updates.founderId);
+        }
+        if (updates.treasury !== undefined) {
+            sets.push('treasury = ?');
+            values.push(JSON.stringify(updates.treasury));
+        }
+        if (updates.officerWithdrawLimit !== undefined) {
+            sets.push('officer_withdraw_limit = ?');
+            values.push(updates.officerWithdrawLimit);
+        }
+        if (updates.doctrineHash !== undefined) {
+            sets.push('doctrine_hash = ?');
+            values.push(updates.doctrineHash);
+        }
+        if (updates.upgrades !== undefined) {
+            sets.push('upgrades = ?');
+            values.push(JSON.stringify(updates.upgrades));
+        }
+        if (updates.relations !== undefined) {
+            sets.push('relations = ?');
+            values.push(JSON.stringify(updates.relations));
+        }
+        if (sets.length === 0)
+            return;
+        values.push(id);
+        await this.client.execute({
+            sql: `UPDATE factions SET ${sets.join(', ')} WHERE id = ?`,
+            args: values
+        });
+    }
+    // ============================================================================
+    // SEASON SCORES
+    // ============================================================================
+    async getOrCreateSeasonScore(seasonNumber, entityId, entityType, entityName) {
+        // Try to get existing
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM season_scores WHERE season_number = ? AND entity_id = ?',
+            args: [seasonNumber, entityId]
+        });
+        if (result.rows.length > 0) {
+            return this.rowToSeasonScore(result.rows[0]);
+        }
+        // Create new
+        const id = uuid();
+        await this.client.execute({
+            sql: `INSERT INTO season_scores (id, season_number, entity_id, entity_type, entity_name,
+            zones_controlled, supply_delivered, shipments_completed, contracts_completed,
+            reputation_gained, combat_victories, total_score)
+            VALUES (?, ?, ?, ?, ?, 0, 0, 0, 0, 0, 0, 0)`,
+            args: [id, seasonNumber, entityId, entityType, entityName]
+        });
+        return {
+            id,
+            seasonNumber,
+            entityId,
+            entityType,
+            entityName,
+            zonesControlled: 0,
+            supplyDelivered: 0,
+            shipmentsCompleted: 0,
+            contractsCompleted: 0,
+            reputationGained: 0,
+            combatVictories: 0,
+            totalScore: 0
+        };
+    }
+    async incrementSeasonScore(seasonNumber, entityId, entityType, entityName, field, amount) {
+        // Ensure record exists
+        await this.getOrCreateSeasonScore(seasonNumber, entityId, entityType, entityName);
+        const fieldMap = {
+            supplyDelivered: 'supply_delivered',
+            shipmentsCompleted: 'shipments_completed',
+            contractsCompleted: 'contracts_completed',
+            reputationGained: 'reputation_gained',
+            combatVictories: 'combat_victories'
+        };
+        const dbField = fieldMap[field];
+        // Increment the field and recalculate total
+        await this.client.execute({
+            sql: `UPDATE season_scores
+            SET ${dbField} = ${dbField} + ?,
+                total_score = (zones_controlled * 100 + supply_delivered * 1 + shipments_completed * 10 +
+                              contracts_completed * 25 + reputation_gained * 2 + combat_victories * 50)
+            WHERE season_number = ? AND entity_id = ?`,
+            args: [amount, seasonNumber, entityId]
+        });
+    }
+    async updateSeasonZoneScores(seasonNumber) {
+        // Get all factions and their controlled zone counts
+        const factions = await this.getAllFactions();
+        for (const faction of factions) {
+            const zoneCount = faction.controlledZones.length;
+            // Update or create score record
+            await this.getOrCreateSeasonScore(seasonNumber, faction.id, 'faction', faction.name);
+            await this.client.execute({
+                sql: `UPDATE season_scores
+              SET zones_controlled = ?,
+                  total_score = (? * 100 + supply_delivered * 1 + shipments_completed * 10 +
+                                contracts_completed * 25 + reputation_gained * 2 + combat_victories * 50)
+              WHERE season_number = ? AND entity_id = ?`,
+                args: [zoneCount, zoneCount, seasonNumber, faction.id]
+            });
+        }
+    }
+    async getSeasonLeaderboard(seasonNumber, entityType, limit = 50) {
+        let sql = 'SELECT * FROM season_scores WHERE season_number = ?';
+        const args = [seasonNumber];
+        if (entityType) {
+            sql += ' AND entity_type = ?';
+            args.push(entityType);
+        }
+        sql += ' ORDER BY total_score DESC LIMIT ?';
+        args.push(limit);
+        const result = await this.client.execute({ sql, args });
+        return result.rows.map((row, index) => ({
+            ...this.rowToSeasonScore(row),
+            rank: index + 1
+        }));
+    }
+    async getEntitySeasonScore(seasonNumber, entityId) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM season_scores WHERE season_number = ? AND entity_id = ?',
+            args: [seasonNumber, entityId]
+        });
+        if (result.rows.length === 0)
+            return null;
+        return this.rowToSeasonScore(result.rows[0]);
+    }
+    async advanceSeason() {
+        const season = await this.getSeasonInfo();
+        const newSeason = season.seasonNumber + 1;
+        await this.client.execute({
+            sql: 'UPDATE world SET season_number = ?, season_week = 1 WHERE id = 1',
+            args: [newSeason]
+        });
+        return { newSeason, newWeek: 1 };
+    }
+    async advanceWeek() {
+        const season = await this.getSeasonInfo();
+        const newWeek = season.seasonWeek + 1;
+        await this.client.execute({
+            sql: 'UPDATE world SET season_week = ? WHERE id = 1',
+            args: [newWeek]
+        });
+        return { seasonNumber: season.seasonNumber, newWeek };
+    }
+    /**
+     * Reset the game world for a new season.
+     * Archives scores, resets zones/inventories, preserves accounts/licenses/factions.
+     */
+    // ============================================================================
+    // DOCTRINES (Phase 5)
+    // ============================================================================
+    async createDoctrine(factionId, title, content, createdBy) {
+        const id = uuid();
+        const tick = await this.getCurrentTick();
+        await this.client.execute({
+            sql: `INSERT INTO doctrines (id, faction_id, title, content, version, created_at, updated_at, created_by)
+            VALUES (?, ?, ?, ?, 1, ?, ?, ?)`,
+            args: [id, factionId, title, content, tick, tick, createdBy]
+        });
+        return { id, factionId, title, content, version: 1, createdAt: tick, updatedAt: tick, createdBy };
+    }
+    async getFactionDoctrines(factionId) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM doctrines WHERE faction_id = ? ORDER BY updated_at DESC',
+            args: [factionId]
+        });
+        return result.rows.map(row => ({
+            id: row.id,
+            factionId: row.faction_id,
+            title: row.title,
+            content: row.content,
+            version: row.version,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+            createdBy: row.created_by
+        }));
+    }
+    async getDoctrine(id) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM doctrines WHERE id = ?',
+            args: [id]
+        });
+        if (result.rows.length === 0)
+            return null;
+        const row = result.rows[0];
+        return {
+            id: row.id,
+            factionId: row.faction_id,
+            title: row.title,
+            content: row.content,
+            version: row.version,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+            createdBy: row.created_by
+        };
+    }
+    async updateDoctrine(id, content) {
+        const tick = await this.getCurrentTick();
+        await this.client.execute({
+            sql: 'UPDATE doctrines SET content = ?, version = version + 1, updated_at = ? WHERE id = ?',
+            args: [content, tick, id]
+        });
+    }
+    async deleteDoctrine(id) {
+        await this.client.execute({
+            sql: 'DELETE FROM doctrines WHERE id = ?',
+            args: [id]
+        });
+    }
+    // ============================================================================
+    // WEBHOOKS (Phase 6)
+    // ============================================================================
+    async createWebhook(playerId, url, events) {
+        const id = uuid();
+        const tick = await this.getCurrentTick();
+        await this.client.execute({
+            sql: `INSERT INTO webhooks (id, player_id, url, events, active, created_at, fail_count)
+            VALUES (?, ?, ?, ?, 1, ?, 0)`,
+            args: [id, playerId, url, JSON.stringify(events), tick]
+        });
+        return { id, playerId, url, events: events, active: true, createdAt: tick, lastTriggeredAt: null, failCount: 0 };
+    }
+    async getPlayerWebhooks(playerId) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM webhooks WHERE player_id = ?',
+            args: [playerId]
+        });
+        return result.rows.map(row => ({
+            id: row.id,
+            playerId: row.player_id,
+            url: row.url,
+            events: JSON.parse(row.events),
+            active: !!row.active,
+            createdAt: row.created_at,
+            lastTriggeredAt: row.last_triggered_at,
+            failCount: row.fail_count
+        }));
+    }
+    async deleteWebhook(id, playerId) {
+        const result = await this.client.execute({
+            sql: 'DELETE FROM webhooks WHERE id = ? AND player_id = ?',
+            args: [id, playerId]
+        });
+        return result.rowsAffected > 0;
+    }
+    async getWebhooksForEvent(eventType) {
+        const result = await this.client.execute({
+            sql: `SELECT * FROM webhooks WHERE active = 1 AND events LIKE ?`,
+            args: [`%${eventType}%`]
+        });
+        return result.rows.map(row => ({
+            id: row.id,
+            playerId: row.player_id,
+            url: row.url,
+            events: JSON.parse(row.events),
+            active: true,
+            createdAt: row.created_at,
+            lastTriggeredAt: row.last_triggered_at,
+            failCount: row.fail_count
+        }));
+    }
+    async updateWebhookStatus(id, lastTriggered, failCount) {
+        await this.client.execute({
+            sql: 'UPDATE webhooks SET last_triggered_at = ?, fail_count = ?, active = ? WHERE id = ?',
+            args: [lastTriggered, failCount, failCount < 5 ? 1 : 0, id]
+        });
+    }
+    // ============================================================================
+    // CONDITIONAL ORDERS (Phase 5)
+    // ============================================================================
+    async createConditionalOrder(order) {
+        const id = uuid();
+        await this.client.execute({
+            sql: `INSERT INTO conditional_orders (id, player_id, zone_id, resource, side, trigger_price, quantity, condition, status, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'active', ?)`,
+            args: [id, order.playerId, order.zoneId, order.resource, order.side, order.triggerPrice, order.quantity, order.condition, order.createdAt]
+        });
+        return { id, ...order, status: 'active' };
+    }
+    async getActiveConditionalOrders() {
+        const result = await this.client.execute("SELECT * FROM conditional_orders WHERE status = 'active'");
+        return result.rows.map(row => ({
+            id: row.id,
+            playerId: row.player_id,
+            zoneId: row.zone_id,
+            resource: row.resource,
+            side: row.side,
+            triggerPrice: row.trigger_price,
+            quantity: row.quantity,
+            condition: row.condition,
+            status: row.status,
+            createdAt: row.created_at
+        }));
+    }
+    async updateConditionalOrderStatus(id, status) {
+        await this.client.execute({
+            sql: 'UPDATE conditional_orders SET status = ? WHERE id = ?',
+            args: [status, id]
+        });
+    }
+    // ============================================================================
+    // TIME-WEIGHTED ORDERS (Phase 5)
+    // ============================================================================
+    async createTimeWeightedOrder(order) {
+        const id = uuid();
+        await this.client.execute({
+            sql: `INSERT INTO time_weighted_orders (id, player_id, zone_id, resource, side, price, total_quantity, remaining_quantity, quantity_per_tick, status, created_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?)`,
+            args: [id, order.playerId, order.zoneId, order.resource, order.side, order.price, order.totalQuantity, order.remainingQuantity, order.quantityPerTick, order.createdAt]
+        });
+        return { id, ...order, status: 'active' };
+    }
+    async getActiveTimeWeightedOrders() {
+        const result = await this.client.execute("SELECT * FROM time_weighted_orders WHERE status = 'active'");
+        return result.rows.map(row => ({
+            id: row.id,
+            playerId: row.player_id,
+            zoneId: row.zone_id,
+            resource: row.resource,
+            side: row.side,
+            price: row.price,
+            totalQuantity: row.total_quantity,
+            remainingQuantity: row.remaining_quantity,
+            quantityPerTick: row.quantity_per_tick,
+            status: row.status,
+            createdAt: row.created_at
+        }));
+    }
+    async updateTimeWeightedOrder(id, remainingQuantity) {
+        const status = remainingQuantity <= 0 ? 'completed' : 'active';
+        await this.client.execute({
+            sql: 'UPDATE time_weighted_orders SET remaining_quantity = ?, status = ? WHERE id = ?',
+            args: [remainingQuantity, status, id]
+        });
+    }
+    // ============================================================================
+    // AUDIT LOGS (Phase 7)
+    // ============================================================================
+    async createAuditLog(factionId, playerId, action, details) {
+        const id = uuid();
+        const tick = await this.getCurrentTick();
+        await this.client.execute({
+            sql: `INSERT INTO audit_logs (id, faction_id, player_id, action, details, tick, timestamp)
+            VALUES (?, ?, ?, ?, ?, ?, ?)`,
+            args: [id, factionId, playerId, action, JSON.stringify(details), tick, new Date().toISOString()]
+        });
+    }
+    async getFactionAuditLogs(factionId, limit = 100) {
+        const result = await this.client.execute({
+            sql: 'SELECT * FROM audit_logs WHERE faction_id = ? ORDER BY tick DESC LIMIT ?',
+            args: [factionId, limit]
+        });
+        return result.rows.map(row => ({
+            id: row.id,
+            factionId: row.faction_id,
+            playerId: row.player_id,
+            action: row.action,
+            details: JSON.parse(row.details),
+            tick: row.tick,
+            timestamp: new Date(row.timestamp)
+        }));
+    }
+    async seasonReset(newSeasonNumber) {
+        // Reset all zones to neutral defaults
+        await this.client.execute(`UPDATE zones SET owner_id = NULL, supply_level = 100, compliance_streak = 0,
+       su_stockpile = 0, inventory = '{}', garrison_level = 0,
+       medkit_stockpile = 0, comms_stockpile = 0`);
+        // Reset player inventories/credits, preserve accounts/licenses/factions
+        const startingInventory = JSON.stringify({ ...emptyInventory(), credits: 500 });
+        await this.client.execute({
+            sql: `UPDATE players SET inventory = ?, actions_today = 0, last_action_tick = 0,
+            reputation = CAST(reputation * 0.5 AS INTEGER)`,
+            args: [startingInventory]
+        });
+        // Clear all active shipments
+        await this.client.execute(`DELETE FROM shipments`);
+        // Clear all units
+        await this.client.execute(`DELETE FROM units`);
+        // Clear all market orders
+        await this.client.execute(`DELETE FROM market_orders`);
+        // Clear all active contracts
+        await this.client.execute(`DELETE FROM contracts WHERE status IN ('open', 'accepted')`);
+        // Clear all intel
+        await this.client.execute(`DELETE FROM intel`);
+        // Reset faction treasuries
+        const emptyTreasury = JSON.stringify(emptyInventory());
+        await this.client.execute({
+            sql: `UPDATE factions SET treasury = ?`,
+            args: [emptyTreasury]
+        });
+        // Advance to new season
+        await this.client.execute({
+            sql: 'UPDATE world SET season_number = ?, season_week = 1 WHERE id = 1',
+            args: [newSeasonNumber]
+        });
+    }
+    rowToSeasonScore(row) {
+        return {
+            id: row.id,
+            seasonNumber: row.season_number,
+            entityId: row.entity_id,
+            entityType: row.entity_type,
+            entityName: row.entity_name,
+            zonesControlled: row.zones_controlled,
+            supplyDelivered: row.supply_delivered,
+            shipmentsCompleted: row.shipments_completed,
+            contractsCompleted: row.contracts_completed,
+            reputationGained: row.reputation_gained,
+            combatVictories: row.combat_victories,
+            totalScore: row.total_score
+        };
+    }
+}
+// ============================================================================
+// TRANSACTION CONTEXT
+// ============================================================================
+/**
+ * Collects statements to be executed in a transaction.
+ * Call add() to queue statements, they execute when transaction() completes.
+ */
+export class TransactionContext {
+    statements;
+    constructor(statements) {
+        this.statements = statements;
+    }
+    /**
+     * Add a statement to the transaction
+     */
+    add(sql, args = []) {
+        this.statements.push({ sql, args });
+    }
+    /**
+     * Generate a UUID for use in the transaction
+     */
+    uuid() {
+        return uuid();
+    }
+}