@its-not-rocket-science/ananke 0.1.0

package/dist/src/replay.d.ts

@@ -0,0 +1,47 @@
+import type { WorldState } from "./sim/world.js";
+import type { CommandMap, Command } from "./sim/commands.js";
+import type { KernelContext } from "./sim/context.js";
+/** One recorded tick: the tick number and the commands dispatched that tick. */
+export interface ReplayFrame {
+    tick: number;
+    commands: ReadonlyArray<readonly [entityId: number, cmds: ReadonlyArray<Command>]>;
+}
+/**
+ * A complete replay: the initial world snapshot plus one frame per recorded tick.
+ * Replaying from `initialState` and re-applying `frames` in order deterministically
+ * reproduces the original simulation.
+ */
+export interface Replay {
+    /** Deep clone of the WorldState before the first stepWorld call. */
+    initialState: WorldState;
+    frames: readonly ReplayFrame[];
+}
+/**
+ * Records commands applied each tick so the simulation can be replayed later.
+ *
+ * Usage:
+ *   const recorder = new ReplayRecorder(world);        // snapshot before first step
+ *   recorder.record(world.tick, cmds);                 // call once per tick
+ *   stepWorld(world, cmds, ctx);
+ *   const replay = recorder.toReplay();
+ */
+export declare class ReplayRecorder {
+    private readonly _initialState;
+    private readonly _frames;
+    constructor(world: WorldState);
+    /** Record the commands dispatched for one tick. Call once per tick, before or after stepWorld. */
+    record(tick: number, commands: CommandMap): void;
+    toReplay(): Replay;
+}
+/**
+ * Replay a recorded simulation up to (and including) `targetTick`.
+ * Returns the reconstructed WorldState at that tick.
+ * Does NOT mutate the Replay.
+ *
+ * Pass `ctx.trace` to collect all replayed events for analysis.
+ */
+export declare function replayTo(replay: Replay, targetTick: number, ctx: KernelContext): WorldState;
+/** Serialize a Replay to a JSON string (handles Maps). */
+export declare function serializeReplay(replay: Replay): string;
+/** Deserialize a JSON string produced by `serializeReplay` back into a Replay. */
+export declare function deserializeReplay(json: string): Replay;

package/dist/src/replay.js

@@ -0,0 +1,82 @@
+// src/replay.ts — Phase 13: deterministic replay system
+//
+// Deterministic replays work because stepWorld is a pure function of:
+//   (WorldState, CommandMap, KernelContext)
+//
+// Recording: snapshot the initial WorldState, then log commands per tick.
+// Replaying: restore the snapshot, apply logged commands in order.
+import { stepWorld } from "./sim/kernel.js";
+/**
+ * Records commands applied each tick so the simulation can be replayed later.
+ *
+ * Usage:
+ *   const recorder = new ReplayRecorder(world);        // snapshot before first step
+ *   recorder.record(world.tick, cmds);                 // call once per tick
+ *   stepWorld(world, cmds, ctx);
+ *   const replay = recorder.toReplay();
+ */
+export class ReplayRecorder {
+    _initialState;
+    _frames = [];
+    constructor(world) {
+        // structuredClone handles Maps (armourState, capabilityCooldowns) correctly.
+        this._initialState = structuredClone(world);
+    }
+    /** Record the commands dispatched for one tick. Call once per tick, before or after stepWorld. */
+    record(tick, commands) {
+        this._frames.push({
+            tick,
+            commands: [...commands.entries()].map(([id, cmds]) => [id, [...cmds]]),
+        });
+    }
+    toReplay() {
+        return {
+            initialState: structuredClone(this._initialState),
+            frames: this._frames.map(f => ({ ...f })),
+        };
+    }
+}
+/**
+ * Replay a recorded simulation up to (and including) `targetTick`.
+ * Returns the reconstructed WorldState at that tick.
+ * Does NOT mutate the Replay.
+ *
+ * Pass `ctx.trace` to collect all replayed events for analysis.
+ */
+export function replayTo(replay, targetTick, ctx) {
+    const world = structuredClone(replay.initialState);
+    for (const frame of replay.frames) {
+        if (frame.tick > targetTick)
+            break;
+        const cmds = new Map(frame.commands.map(([id, cmds]) => [id, cmds]));
+        stepWorld(world, cmds, ctx);
+    }
+    return world;
+}
+// ── JSON serialisation ────────────────────────────────────────────────────────
+//
+// WorldState contains Map fields (entity.armourState, action.capabilityCooldowns).
+// Standard JSON.stringify drops Map entries. We use a marker-based replacer/reviver.
+const MAP_MARKER = "__ananke_map__";
+function mapAwareReplacer(_key, value) {
+    if (value instanceof Map) {
+        return { [MAP_MARKER]: true, entries: [...value.entries()] };
+    }
+    return value;
+}
+function mapAwareReviver(_key, value) {
+    if (value !== null &&
+        typeof value === "object" &&
+        value[MAP_MARKER] === true) {
+        return new Map(value.entries);
+    }
+    return value;
+}
+/** Serialize a Replay to a JSON string (handles Maps). */
+export function serializeReplay(replay) {
+    return JSON.stringify(replay, mapAwareReplacer);
+}
+/** Deserialize a JSON string produced by `serializeReplay` back into a Replay. */
+export function deserializeReplay(json) {
+    return JSON.parse(json, mapAwareReviver);
+}

package/dist/src/rng.d.ts

@@ -0,0 +1,9 @@
+export type U32 = number;
+export declare function splitmix32(seed: U32): () => U32;
+export declare function sfc32(a: U32, b: U32, c: U32, d: U32): {
+    nextU32: () => number;
+};
+export declare function makeRng(seed: U32, scaleQ: number): {
+    u32: () => number;
+    q01: () => number;
+};

package/dist/src/rng.js

@@ -0,0 +1,37 @@
+const u32 = (x) => (x >>> 0);
+export function splitmix32(seed) {
+    let x = u32(seed);
+    return () => {
+        x = u32(x + 0x9E3779B9);
+        let z = x;
+        z = u32((z ^ (z >>> 16)) * 0x85EBCA6B);
+        z = u32((z ^ (z >>> 13)) * 0xC2B2AE35);
+        z = u32(z ^ (z >>> 16));
+        return z;
+    };
+}
+export function sfc32(a, b, c, d) {
+    let A = u32(a), B = u32(b), C = u32(c), D = u32(d);
+    const nextU32 = () => {
+        const t = u32(A + B);
+        A = u32(B ^ (B >>> 9));
+        B = u32(C + (C << 3));
+        C = u32((C << 21) | (C >>> 11));
+        D = u32(D + 1);
+        const out = u32(t + D);
+        C = u32(C + out);
+        return out;
+    };
+    return { nextU32 };
+}
+export function makeRng(seed, scaleQ) {
+    const sm = splitmix32(seed);
+    const r = sfc32(sm(), sm(), sm(), sm());
+    return {
+        u32: r.nextU32,
+        q01: () => {
+            const x = r.nextU32();
+            return Math.min(scaleQ - 1, Math.trunc((x / 0x1_0000_0000) * scaleQ));
+        },
+    };
+}

package/dist/src/settlement-services.d.ts

@@ -0,0 +1,67 @@
+import type { Q } from "./units.js";
+import type { Settlement } from "./settlement.js";
+export interface ServicePricing {
+    baseCost: number;
+    currency: string;
+    settlementMultiplier: number;
+    availability: boolean;
+}
+/** Get repair service pricing for a settlement. */
+export declare function getRepairPricing(settlement: Settlement, itemValue: number, damageLevel: Q): {
+    cost: number;
+    canRepair: boolean;
+    qualityBonus_Q: Q;
+};
+/** Get medical service pricing. */
+export declare function getMedicalPricing(settlement: Settlement, careLevel: "treatment" | "surgery" | "recovery"): {
+    cost: number;
+    available: boolean;
+    careQuality: number;
+};
+/** Get training service pricing. */
+export declare function getTrainingPricing(settlement: Settlement, hours: number): {
+    cost: number;
+    available: boolean;
+    xpBonus_Q: Q;
+};
+export interface SettlementQuestNeed {
+    type: string;
+    priority: number;
+    description: string;
+    suggestedReward: number;
+}
+/** Generate settlement needs that can become quests. */
+export declare function generateSettlementNeeds(settlement: Settlement): SettlementQuestNeed[];
+/** Select the highest priority need and convert to quest template. */
+export declare function selectQuestNeed(settlement: Settlement, needs?: SettlementQuestNeed[]): SettlementQuestNeed | undefined;
+export interface ServiceDescription {
+    name: string;
+    description: string;
+    available: boolean;
+    quality: string;
+    costEstimate: string;
+}
+/** Get descriptions of all available services for UI/display. */
+export declare function getServiceDescriptions(settlement: Settlement): ServiceDescription[];
+export interface SettlementInfo {
+    id: string;
+    name: string;
+    tier: string;
+    population: number;
+    populationCap: number;
+    faction?: string | undefined;
+    services: string[];
+    activeProjects: number;
+    hasQuests: boolean;
+}
+/** Get summary info for settlement listing. */
+export declare function getSettlementInfo(settlement: Settlement): SettlementInfo;
+/** Check if entity can use a service at a settlement. */
+export declare function canUseService(settlement: Settlement, entityId: number, serviceType: "repair" | "medical" | "training" | "market"): {
+    allowed: boolean;
+    reason?: string;
+};
+/** Calculate total investment in a settlement (sum of all facility levels). */
+export declare function calculateSettlementInvestment(settlement: Settlement): number;
+/** Get settlement attractiveness score for immigration. */
+export declare function getSettlementAttractiveness(settlement: Settlement): number;

package/dist/src/settlement-services.js

@@ -0,0 +1,267 @@
+// src/settlement-services.ts — Phase 44: Settlement Services Integration
+//
+// Service availability, pricing, and quest generation for settlements.
+// Integrates with economy (Phase 25), quests (Phase 41), and competence (Phase 40).
+import { q, SCALE } from "./units.js";
+import { getAvailableServices, SETTLEMENT_TIER_NAMES } from "./settlement.js";
+/** Get repair service pricing for a settlement. */
+export function getRepairPricing(settlement, itemValue, damageLevel) {
+    const services = getAvailableServices(settlement);
+    if (!services.repair) {
+        return { cost: 0, canRepair: false, qualityBonus_Q: q(0) };
+    }
+    // Base cost scales with item value and damage
+    const baseCost = Math.round(itemValue * 0.1 * (damageLevel / SCALE.Q));
+    // Apply market discount
+    const discountMul = SCALE.Q - services.marketDiscount_Q;
+    const cost = Math.round((baseCost * discountMul) / SCALE.Q);
+    return {
+        cost: Math.max(1, cost),
+        canRepair: true,
+        qualityBonus_Q: services.repairQualityBonus_Q,
+    };
+}
+/** Get medical service pricing. */
+export function getMedicalPricing(settlement, careLevel) {
+    const services = getAvailableServices(settlement);
+    if (services.medicalCare === "none") {
+        return { cost: 0, available: false, careQuality: 0 };
+    }
+    const careQualityMap = {
+        none: 0,
+        basic: 1,
+        skilled: 2,
+        expert: 3,
+        master: 4,
+    };
+    const baseCosts = {
+        treatment: 50,
+        surgery: 200,
+        recovery: 20,
+    };
+    const careQuality = careQualityMap[services.medicalCare] ?? 0;
+    const costMultiplier = careLevel === "surgery" ? careQuality * 0.5 + 1 : 1;
+    return {
+        cost: Math.round(baseCosts[careLevel] * costMultiplier),
+        available: true,
+        careQuality: careQuality,
+    };
+}
+/** Get training service pricing. */
+export function getTrainingPricing(settlement, hours) {
+    const services = getAvailableServices(settlement);
+    if (!services.training) {
+        return { cost: 0, available: false, xpBonus_Q: q(0) };
+    }
+    const hourlyRate = 10; // Currency per hour
+    const discountMul = SCALE.Q - services.marketDiscount_Q;
+    const cost = Math.round((hourlyRate * hours * discountMul) / SCALE.Q);
+    return {
+        cost: Math.max(1, cost),
+        available: true,
+        xpBonus_Q: services.trainingBonus_Q,
+    };
+}
+/** Generate settlement needs that can become quests. */
+export function generateSettlementNeeds(settlement) {
+    const needs = [];
+    // Check for low facilities that need upgrading
+    const facilities = settlement.facilities;
+    const facilityNames = ["forge", "medical", "market", "barracks", "temple"];
+    for (const facility of facilityNames) {
+        const level = facilities[facility];
+        if (level < 2 && settlement.tier >= 2) {
+            needs.push({
+                type: "construction",
+                priority: 5 + (2 - level) * 2,
+                description: `Upgrade ${facility} to support growing population`,
+                suggestedReward: 100 * (level + 1),
+            });
+        }
+    }
+    // Food shortage
+    if (settlement.foodSurplus_Q < q(0.3)) {
+        needs.push({
+            type: "supply",
+            priority: 9,
+            description: "Food shortage threatening population",
+            suggestedReward: 200,
+        });
+    }
+    // Recent raid → defense need
+    if (settlement.safetyStatus.ticksSinceLastRaid < 100) {
+        needs.push({
+            type: "defense",
+            priority: 8,
+            description: "Recent raid requires improved defenses",
+            suggestedReward: 300,
+        });
+    }
+    // Medical need if high population, low medical facility
+    if (settlement.population > 100 && facilities.medical < 2) {
+        needs.push({
+            type: "medical",
+            priority: 6,
+            description: "Population needs better medical facilities",
+            suggestedReward: 150,
+        });
+    }
+    // Generic settlement needs based on tier
+    if (settlement.tier >= 1) {
+        needs.push({
+            type: "patrol",
+            priority: 4,
+            description: `Patrol roads near ${settlement.name}`,
+            suggestedReward: 100,
+        });
+        needs.push({
+            type: "delivery",
+            priority: 3,
+            description: "Deliver goods to nearby settlement",
+            suggestedReward: 75,
+        });
+    }
+    return needs.sort((a, b) => b.priority - a.priority);
+}
+/** Select the highest priority need and convert to quest template. */
+export function selectQuestNeed(settlement, needs) {
+    const settlementNeeds = needs ?? generateSettlementNeeds(settlement);
+    if (settlementNeeds.length === 0)
+        return undefined;
+    // Return highest priority need
+    return settlementNeeds[0];
+}
+/** Get descriptions of all available services for UI/display. */
+export function getServiceDescriptions(settlement) {
+    const services = getAvailableServices(settlement);
+    const descriptions = [];
+    // Repair
+    if (services.repair) {
+        descriptions.push({
+            name: "Repair Services",
+            description: "Weapon and armour repair",
+            available: true,
+            quality: getQualityLabel(services.repairQualityBonus_Q),
+            costEstimate: "10% of item value",
+        });
+    }
+    // Medical
+    if (services.medicalCare !== "none") {
+        descriptions.push({
+            name: "Medical Care",
+            description: "Wound treatment and surgery",
+            available: true,
+            quality: services.medicalCare,
+            costEstimate: services.medicalCare === "basic" ? "50-200" : "100-500",
+        });
+    }
+    // Training
+    if (services.training) {
+        descriptions.push({
+            name: "Training Grounds",
+            description: "Combat skill training",
+            available: true,
+            quality: getQualityLabel(services.trainingBonus_Q),
+            costEstimate: "10 per hour",
+        });
+    }
+    // Market
+    if (services.market) {
+        const discount = Math.round((services.marketDiscount_Q / SCALE.Q) * 100);
+        descriptions.push({
+            name: "Market",
+            description: "Buy and sell goods",
+            available: true,
+            quality: `${discount}% discount`,
+            costEstimate: "Variable",
+        });
+    }
+    return descriptions;
+}
+function getQualityLabel(bonus_Q) {
+    const percent = Math.round((bonus_Q / SCALE.Q) * 100);
+    if (percent >= 15)
+        return "Excellent (+" + percent + "%)";
+    if (percent >= 10)
+        return "Good (+" + percent + "%)";
+    if (percent >= 5)
+        return "Fair (+" + percent + "%)";
+    return "Basic";
+}
+/** Get summary info for settlement listing. */
+export function getSettlementInfo(settlement) {
+    const services = getAvailableServices(settlement);
+    const availableServices = [];
+    if (services.repair)
+        availableServices.push("Repair");
+    if (services.medicalCare !== "none")
+        availableServices.push("Medical");
+    if (services.training)
+        availableServices.push("Training");
+    if (services.market)
+        availableServices.push("Market");
+    return {
+        id: settlement.settlementId,
+        name: settlement.name,
+        tier: SETTLEMENT_TIER_NAMES[settlement.tier],
+        population: settlement.population,
+        populationCap: settlement.populationCap,
+        faction: settlement.factionId?.toString(),
+        services: availableServices,
+        activeProjects: settlement.activeProjects.length,
+        hasQuests: services.questGeneration,
+    };
+}
+// ── Integration Helpers ────────────────────────────────────────────────────────
+/** Check if entity can use a service at a settlement. */
+export function canUseService(settlement, entityId, serviceType) {
+    // Check if service exists
+    const services = getAvailableServices(settlement);
+    switch (serviceType) {
+        case "repair":
+            if (!services.repair)
+                return { allowed: false, reason: "no_forge" };
+            break;
+        case "medical":
+            if (services.medicalCare === "none")
+                return { allowed: false, reason: "no_medical" };
+            break;
+        case "training":
+            if (!services.training)
+                return { allowed: false, reason: "no_barracks" };
+            break;
+        case "market":
+            if (!services.market)
+                return { allowed: false, reason: "no_market" };
+            break;
+    }
+    // Entity can use service
+    return { allowed: true };
+}
+/** Calculate total investment in a settlement (sum of all facility levels). */
+export function calculateSettlementInvestment(settlement) {
+    return Object.values(settlement.facilities).reduce((sum, level) => sum + level, 0);
+}
+/** Get settlement attractiveness score for immigration. */
+export function getSettlementAttractiveness(settlement) {
+    let score = settlement.tier * 10;
+    // Facilities add attractiveness
+    score += calculateSettlementInvestment(settlement) * 2;
+    // Safety penalty
+    if (settlement.safetyStatus.ticksSinceLastRaid < 500) {
+        score -= 10;
+    }
+    // Food bonus
+    if (settlement.foodSurplus_Q > q(0.5)) {
+        score += 5;
+    }
+    // Population pressure (less attractive if overcrowded)
+    const occupancy = settlement.population / settlement.populationCap;
+    if (occupancy > 0.9) {
+        score -= 15;
+    }
+    else if (occupancy < 0.5) {
+        score += 5; // Room to grow
+    }
+    return Math.max(0, score);
+}

package/dist/src/settlement.d.ts

@@ -0,0 +1,143 @@
+import type { Q } from "./units.js";
+import type { Inventory } from "./inventory.js";
+/** Facility tier levels. */
+export type FacilityLevel = 0 | 1 | 2 | 3 | 4;
+/** Settlement tiers from smallest to largest. */
+export type SettlementTier = 0 | 1 | 2 | 3 | 4;
+export declare const SETTLEMENT_TIER_NAMES: Record<SettlementTier, string>;
+/** Settlement definition. */
+export interface Settlement {
+    settlementId: string;
+    name: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    tier: SettlementTier;
+    /** Facilities determine available services. */
+    facilities: {
+        forge: FacilityLevel;
+        medical: FacilityLevel;
+        market: FacilityLevel;
+        barracks: FacilityLevel;
+        temple: FacilityLevel;
+    };
+    population: number;
+    populationCap: number;
+    factionId?: number | undefined;
+    /** Shared storage for guild/faction. */
+    sharedStorage?: Inventory | undefined;
+    /** Active construction projects. */
+    activeProjects: ConstructionProject[];
+    /** Settlement history for chronicle generation. */
+    history: SettlementEvent[];
+    /** Safety status (affects population growth). */
+    safetyStatus: SafetyStatus;
+    /** Food surplus metric (affects population growth). */
+    foodSurplus_Q: Q;
+    /** Tick when settlement was founded. */
+    foundedAtTick: number;
+    /** Last time settlement was updated. */
+    lastUpdateTick: number;
+}
+/** Safety status affecting population growth. */
+export interface SafetyStatus {
+    /** Number of ticks since last raid/attack. */
+    ticksSinceLastRaid: number;
+    /** Whether settlement has defensive structures. */
+    hasDefenses: boolean;
+    /** Recent casualties from raids. */
+    recentCasualties: number;
+}
+/** Construction project for upgrading facilities. */
+export interface ConstructionProject {
+    projectId: string;
+    targetFacility: keyof Settlement["facilities"];
+    targetLevel: FacilityLevel;
+    requiredResources: Record<string, number>;
+    progress_Q: Q;
+    contributors: number[];
+    startedAtTick: number;
+    estimatedCompletionTick?: number | undefined;
+}
+/** Settlement event for history/chronicle. */
+export interface SettlementEvent {
+    tick: number;
+    type: SettlementEventType;
+    description: string;
+    entityIds?: number[] | undefined;
+    data?: Record<string, unknown> | undefined;
+}
+export type SettlementEventType = "founded" | "tier_upgraded" | "facility_upgraded" | "project_started" | "project_completed" | "population_changed" | "raid" | "siege_started" | "siege_ended" | "faction_changed" | "quest_generated";
+/** Settlement registry for world management. */
+export interface SettlementRegistry {
+    settlements: Map<string, Settlement>;
+    byPosition: Map<string, string>;
+    byFaction: Map<number, Set<string>>;
+}
+/** Create a new settlement. */
+export declare function createSettlement(settlementId: string, name: string, position: {
+    x: number;
+    y: number;
+}, tick: number, tier?: SettlementTier, factionId?: number): Settlement;
+/** Calculate population cap based on tier and facilities. */
+export declare function calculatePopulationCap(tier: SettlementTier, facilities: Settlement["facilities"]): number;
+/** Create a new settlement registry. */
+export declare function createSettlementRegistry(): SettlementRegistry;
+/** Register a settlement in the registry. */
+export declare function registerSettlement(registry: SettlementRegistry, settlement: Settlement): void;
+/** Remove a settlement from the registry. */
+export declare function unregisterSettlement(registry: SettlementRegistry, settlementId: string): boolean;
+/** Get settlement by position. */
+export declare function getSettlementAtPosition(registry: SettlementRegistry, x: number, y: number): Settlement | undefined;
+/** Get all settlements for a faction. */
+export declare function getFactionSettlements(registry: SettlementRegistry, factionId: number): Settlement[];
+/** Find nearest settlement to a position. */
+export declare function findNearestSettlement(registry: SettlementRegistry, x: number, y: number): {
+    settlement: Settlement;
+    distance: number;
+} | undefined;
+/** Facility upgrade costs and requirements. */
+export declare const FACILITY_UPGRADE_COSTS: Record<keyof Settlement["facilities"], Record<FacilityLevel, {
+    materials: Record<string, number>;
+    laborHours: number;
+}>>;
+/** Start a construction project. */
+export declare function startConstructionProject(settlement: Settlement, facility: keyof Settlement["facilities"], targetLevel: FacilityLevel, tick: number): {
+    success: boolean;
+    reason?: string;
+    project?: ConstructionProject;
+};
+/** Contribute work to a construction project. */
+export declare function contributeToProject(settlement: Settlement, projectId: string, entityId: number, competenceQuality_Q: Q, // From Phase 40 competence system
+hoursWorked: number, tick: number): {
+    success: boolean;
+    reason?: string;
+    completed?: boolean;
+};
+/** Update settlement population based on conditions. */
+export declare function updateSettlementPopulation(settlement: Settlement, tick: number): {
+    growth: number;
+    reason: string;
+};
+/** Services available based on facility levels. */
+export interface AvailableServices {
+    repair: boolean;
+    repairQualityBonus_Q: Q;
+    medicalCare: "none" | "basic" | "skilled" | "expert" | "master";
+    training: boolean;
+    trainingBonus_Q: Q;
+    market: boolean;
+    marketDiscount_Q: Q;
+    questGeneration: boolean;
+}
+/** Get available services for a settlement. */
+export declare function getAvailableServices(settlement: Settlement): AvailableServices;
+/** Record a raid/siege on a settlement. */
+export declare function recordRaid(settlement: Settlement, attackerFactionId: number, casualties: number, tick: number): void;
+/** Update settlement defenses. */
+export declare function updateDefenses(settlement: Settlement, hasDefenses: boolean): void;
+/** Serialize settlement to JSON-friendly format. */
+export declare function serializeSettlement(settlement: Settlement): unknown;
+/** Deserialize settlement. */
+export declare function deserializeSettlement(data: unknown): Settlement;