@its-not-rocket-science/ananke 0.1.5 → 0.1.7

package/dist/src/sim/formation-combat.js

@@ -0,0 +1,255 @@
+/**
+ * Phase 69 — Macro-Scale Formation Combat
+ *
+ * A tactical abstraction layer between individual entity simulation (20 Hz) and
+ * polity-level conflict (1 tick/day).  Squads and companies resolve combat as
+ * cohesive units via Lanchester's square law, adjusted for terrain and morale.
+ *
+ * When a named entity (id < NAMED_ENTITY_THRESHOLD, or in a caller-supplied set)
+ * participates in the engagement, the resolver marks them in `namedEntityIds` so the
+ * host can run a full per-entity micro-simulation frame at the decisive tick.
+ *
+ * Lanchester's Square Law:
+ *   Attrition per tick ∝ opponent_strength² / own_strength
+ *   δA = k × B²          δB = k × A²
+ *
+ * where k is derived from aggregated combat effectiveness (force_N × endurance × morale).
+ */
+import { q, SCALE, clampQ, qMul, mulDiv } from "../units.js";
+import { HUMAN_BASE } from "../archetypes.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Entity ids strictly below this value are treated as "named" and trigger
+ * micro-simulation delegation.  Hosts may override via `FormationUnit.namedEntityIds`.
+ */
+export const NAMED_ENTITY_THRESHOLD = 1000;
+/**
+ * Morale Q threshold below which a unit routs.
+ * Matches Phase 32D formation morale `BASE_DECAY` model.
+ */
+export const ROUT_THRESHOLD = q(0.20);
+/**
+ * Base morale decay per tactical tick due to casualties (Q per tick per 1% casualty rate).
+ * A unit sustaining 10% casualties/tick loses ~q(0.10) morale/tick.
+ */
+export const MORALE_CASUALTY_DECAY_PER_PCT = q(0.010);
+/**
+ * Lanchester attrition rate (fraction of effective opponent strength killed per tick).
+ *
+ * Lanchester's Square Law differential form:
+ *   dA/dt = -rate × B_eff     (attacker casualties ∝ effective defender count)
+ *   dB/dt = -rate × A_eff     (defender casualties ∝ effective attacker count)
+ *
+ * The "square law" refers to the conservation integral (A²-B²=const), not squared
+ * differentials.  rate=0.01 gives ~100-tick engagements for equal 100-person units.
+ */
+export const LANCHESTER_RATE = 0.10;
+/**
+ * Reference combat power of a single standard human soldier at q(1.0) morale.
+ * Used to convert aggregated sidePower() to "effective fighter count" for attrition.
+ * Units: same as aggregatedForce_N × conversionEfficiency / SCALE.Q (SCALE.N units).
+ */
+export const REFERENCE_POWER_PER_SOLDIER = Math.round((HUMAN_BASE.peakForce_N * HUMAN_BASE.conversionEfficiency) / SCALE.Q);
+// ── Terrain multipliers ───────────────────────────────────────────────────────
+/**
+ * Defender effectiveness multiplier per terrain type.
+ * Applied to the defender's combat power (force × endurance × morale).
+ * Attackers always use multiplier q(1.0).
+ */
+export const TERRAIN_DEFENDER_MUL = {
+    open: q(1.00), // no terrain advantage
+    difficult: q(1.30), // broken ground, forest, river — 30% defender bonus
+    fortified: q(2.00), // walls, prepared positions — 2× defender effectiveness
+};
+// ── Internal helpers ──────────────────────────────────────────────────────────
+/**
+ * Aggregate combat power for a side (Q-scaled, relative units).
+ * power = sum(force_N × endurance × morale / SCALE.Q²)
+ * Returns an integer in SCALE.N × Q units (before the /SCALE.Q² normalisation).
+ */
+function sidePower(units, terrainMul) {
+    let total = 0;
+    for (const u of units) {
+        if (u.strength <= 0 || u.moraleQ <= 0)
+            continue;
+        // effective = force_N × (endurance / SCALE.Q) × (morale / SCALE.Q) × (terrain / SCALE.Q)
+        const effForce = mulDiv(u.aggregatedForce_N, u.aggregatedEndurance, SCALE.Q);
+        const withMorale = mulDiv(effForce, u.moraleQ, SCALE.Q);
+        total += mulDiv(withMorale, terrainMul, SCALE.Q);
+    }
+    return Math.max(0, total);
+}
+/** Total headcount across all units on a side. */
+function sideStrength(units) {
+    return units.reduce((s, u) => s + Math.max(0, u.strength), 0);
+}
+/**
+ * Distribute `casualties` proportionally across units by current strength.
+ * Mutates unit.strength in-place.  Returns actual casualties applied.
+ */
+function distributeCasualties(units, casualties) {
+    const total = sideStrength(units);
+    if (total <= 0 || casualties <= 0)
+        return 0;
+    let applied = 0;
+    for (const u of units) {
+        if (u.strength <= 0)
+            continue;
+        const share = Math.round((casualties * u.strength) / total);
+        const actual = Math.min(share, u.strength);
+        u.strength -= actual;
+        applied += actual;
+    }
+    return applied;
+}
+/**
+ * Apply morale pressure to all units on a side.
+ * Pressure = casualty rate × MORALE_CASUALTY_DECAY_PER_PCT.
+ */
+function applyMoralePressure(units, casualtiesThisTick) {
+    const total = sideStrength(units) + casualtiesThisTick;
+    if (total <= 0)
+        return;
+    const pct = Math.round((casualtiesThisTick * SCALE.Q) / total);
+    const decay = qMul(MORALE_CASUALTY_DECAY_PER_PCT, pct);
+    for (const u of units) {
+        u.moraleQ = clampQ((u.moraleQ - decay), 0, SCALE.Q);
+    }
+}
+/** Collect named entity ids from all units across both sides. */
+function collectNamedIds(attackers, defenders) {
+    const ids = new Set();
+    for (const u of [...attackers, ...defenders]) {
+        // Explicit named ids
+        if (u.namedEntityIds) {
+            for (const id of u.namedEntityIds)
+                ids.add(id);
+        }
+    }
+    return [...ids];
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Build a `FormationUnit` from headcount and archetype.
+ *
+ * @param id        Unique unit identifier.
+ * @param factionId Faction / polity identifier.
+ * @param strength  Number of combatants.
+ * @param archetype Representative archetype (used for force and endurance derivation).
+ * @param moraleQ   Initial morale (defaults to q(0.70)).
+ */
+export function createFormationUnit(id, factionId, strength, archetype, moraleQ = q(0.70)) {
+    return {
+        id,
+        factionId,
+        strength: Math.max(0, strength),
+        aggregatedForce_N: Math.round(archetype.peakForce_N * strength),
+        aggregatedEndurance: archetype.conversionEfficiency,
+        moraleQ,
+        archetype,
+    };
+}
+/**
+ * Resolve a tactical engagement over `durationTicks` using Lanchester's square law.
+ *
+ * The engagement proceeds tick-by-tick:
+ *  1. Compute combat power for each side (aggregated force × endurance × morale × terrain).
+ *  2. Apply Lanchester attrition: δA = k × B²/A, δB = k × A²/B.
+ *  3. Apply morale pressure proportional to casualty rate.
+ *  4. Check rout conditions — any unit below ROUT_THRESHOLD is considered routed.
+ *  5. Stop early if all units on one side are routed or wiped out.
+ *
+ * **Note:** This mutates `strength` and `moraleQ` on the supplied `FormationUnit` objects.
+ * Clone them before calling if you need to preserve original state.
+ *
+ * @param engagement - The engagement parameters.
+ * @returns `TacticalResult` with per-side outcomes, routed factions, and named entity ids.
+ */
+export function resolveTacticalEngagement(engagement) {
+    const { attackers, defenders, terrain, durationTicks } = engagement;
+    const terrainMul = TERRAIN_DEFENDER_MUL[terrain];
+    const namedEntityIds = collectNamedIds(attackers, defenders);
+    let totalAttackerCasualties = 0;
+    let totalDefenderCasualties = 0;
+    const routedFactions = new Set();
+    let decisiveTick = durationTicks;
+    for (let tick = 0; tick < durationTicks; tick++) {
+        const aStrength = sideStrength(attackers);
+        const dStrength = sideStrength(defenders);
+        // Stop if one side is wiped out
+        if (aStrength <= 0 || dStrength <= 0) {
+            decisiveTick = tick;
+            break;
+        }
+        // Combat power for each side
+        const aPower = sidePower(attackers, SCALE.Q); // attackers: no terrain bonus
+        const dPower = sidePower(defenders, terrainMul); // defenders: terrain multiplier
+        // Lanchester's Square Law — linear differential form:
+        //   δA = rate × dEff    (attacker casualties ∝ effective defender count)
+        //   δB = rate × aEff    (defender casualties ∝ effective attacker count)
+        //
+        // Convert aggregated power to "effective fighter count" by dividing by the
+        // reference combat power of one standard soldier.
+        const ref = Math.max(1, REFERENCE_POWER_PER_SOLDIER);
+        const aEff = Math.max(1, Math.round(aPower / ref));
+        const dEff = Math.max(1, Math.round(dPower / ref));
+        const aCas = Math.max(0, Math.round(LANCHESTER_RATE * dEff));
+        const dCas = Math.max(0, Math.round(LANCHESTER_RATE * aEff));
+        // Distribute casualties
+        totalAttackerCasualties += distributeCasualties(attackers, aCas);
+        totalDefenderCasualties += distributeCasualties(defenders, dCas);
+        // Morale pressure
+        applyMoralePressure(attackers, aCas);
+        applyMoralePressure(defenders, dCas);
+        // Rout check
+        for (const u of attackers) {
+            if (u.moraleQ < ROUT_THRESHOLD || u.strength <= 0)
+                routedFactions.add(u.factionId);
+        }
+        for (const u of defenders) {
+            if (u.moraleQ < ROUT_THRESHOLD || u.strength <= 0)
+                routedFactions.add(u.factionId);
+        }
+        // Early stop: all attacker or all defender factions routed
+        const aAllRouted = attackers.every(u => routedFactions.has(u.factionId) || u.strength <= 0);
+        const dAllRouted = defenders.every(u => routedFactions.has(u.factionId) || u.strength <= 0);
+        if (aAllRouted || dAllRouted) {
+            decisiveTick = tick + 1;
+            break;
+        }
+    }
+    const attackerResult = {
+        casualties: totalAttackerCasualties,
+        survivingStrength: sideStrength(attackers),
+        finalMoraleQ: Math.round(attackers.reduce((s, u) => s + u.moraleQ, 0) / Math.max(1, attackers.length)),
+        routed: attackers.every(u => routedFactions.has(u.factionId) || u.strength <= 0),
+    };
+    const defenderResult = {
+        casualties: totalDefenderCasualties,
+        survivingStrength: sideStrength(defenders),
+        finalMoraleQ: Math.round(defenders.reduce((s, u) => s + u.moraleQ, 0) / Math.max(1, defenders.length)),
+        routed: defenders.every(u => routedFactions.has(u.factionId) || u.strength <= 0),
+    };
+    return {
+        attackerResult,
+        defenderResult,
+        routedFactions: [...routedFactions],
+        namedEntityIds,
+        decisiveTick,
+    };
+}
+/**
+ * Apply the tactical result back to polity military strength (Q).
+ *
+ * @param currentStrength_Q - Current `polity.militaryStrength_Q`.
+ * @param initialStrength   - Headcount at engagement start.
+ * @param result            - Side result from `resolveTacticalEngagement`.
+ * @returns Updated `militaryStrength_Q`.
+ */
+export function applyTacticalResultToPolity(currentStrength_Q, initialStrength, result) {
+    if (initialStrength <= 0)
+        return currentStrength_Q;
+    const survivorFrac = Math.round((result.survivingStrength * SCALE.Q) / initialStrength);
+    const moraleAdj = qMul(survivorFrac, result.finalMoraleQ);
+    return clampQ(Math.round((currentStrength_Q * moraleAdj) / SCALE.Q), 0, SCALE.Q);
+}

package/dist/src/snapshot.d.ts

@@ -0,0 +1,117 @@
+/**
+ * CE-9 — World-State Diffing + Incremental Snapshots
+ *
+ * Reduces long-run storage from O(ticks × fullState) to O(initialState + Σ deltas).
+ *
+ * ## Diff model
+ * `WorldStateDiff` captures:
+ * - World-level scalar changes (`tick`, `seed`, optional subsystem fields).
+ * - Entity-level changes at **top-level-field granularity**: each field that
+ *   differs from the previous snapshot is stored in full; unchanged fields are
+ *   omitted.  This avoids deep-diffing complex nested types.
+ * - Newly added entities (stored in full).
+ * - Removed entity ids.
+ *
+ * ## Binary wire format (`packDiff` / `unpackDiff`)
+ * A compact, dependency-free binary encoding using a simple tag-value scheme.
+ * Zero external dependencies — implemented entirely with `DataView` / `Uint8Array`.
+ *
+ * Layout:
+ *   [4 bytes magic "ANKD"] [1 byte version=1] [tag-value payload...]
+ *
+ * Tag bytes:
+ *   0x01 null | 0x02 true | 0x03 false
+ *   0x04 uint8  (1 byte) | 0x05 int32 LE (4 bytes) | 0x06 float64 LE (8 bytes)
+ *   0x07 string (uint16 LE length + UTF-8 bytes)
+ *   0x08 array  (uint32 LE count + items)
+ *   0x09 object (uint32 LE count + key-value pairs, keys as 0x07 strings)
+ *   0x0A undefined/absent (skipped in round-trip)
+ */
+import type { WorldState } from "./sim/world.js";
+import type { Entity } from "./sim/entity.js";
+/** A patch for a single entity — only changed top-level fields are included. */
+export interface EntityPatch {
+    /** Entity id. */
+    id: number;
+    /** Changed top-level fields (field name → new value). */
+    changes: Record<string, unknown>;
+}
+/**
+ * Delta between two consecutive `WorldState` snapshots.
+ *
+ * Applying a `WorldStateDiff` to the `prev` snapshot must yield a state
+ * indistinguishable (JSON-round-trip-equal) from `next`.
+ */
+export interface WorldStateDiff {
+    /** `next.tick` — always present for sequencing. */
+    tick: number;
+    /** Changed world-level scalar/subsystem fields (excluding `entities`). */
+    worldChanges: Record<string, unknown>;
+    /** Entities present in `next` but not in `prev` — stored in full. */
+    added: Entity[];
+    /** Entity ids present in `prev` but not in `next`. */
+    removed: number[];
+    /** Top-level-field patches for entities present in both states. */
+    modified: EntityPatch[];
+}
+/**
+ * Compute the diff between two `WorldState` snapshots.
+ *
+ * The diff is guaranteed to be **idempotent**: `applyDiff(prev, diffWorldState(prev, next))`
+ * produces a state that is JSON-round-trip-equal to `next`.
+ *
+ * Complexity: O(E × F) where E = entity count and F = top-level field count per entity.
+ *
+ * @param prev  Base snapshot.
+ * @param next  New snapshot (must have the same `seed`; `tick` may differ).
+ * @returns     `WorldStateDiff` — empty diff if states are identical.
+ */
+export declare function diffWorldState(prev: WorldState, next: WorldState): WorldStateDiff;
+/**
+ * Apply a `WorldStateDiff` to a base `WorldState`, producing the `next` state.
+ *
+ * **Does not mutate `base`** — returns a new `WorldState` object.
+ * The returned state may share sub-object references with `base` for unchanged
+ * entities (copy-on-write semantics).
+ *
+ * @param base   The `prev` snapshot that was passed to `diffWorldState`.
+ * @param diff   The diff produced by `diffWorldState`.
+ * @returns      Reconstructed `next` state.
+ */
+export declare function applyDiff(base: WorldState, diff: WorldStateDiff): WorldState;
+/**
+ * Returns `true` when the diff contains no changes — states were identical.
+ */
+export declare function isDiffEmpty(diff: WorldStateDiff): boolean;
+/**
+ * Summary statistics for a diff (useful for logging / network budget monitoring).
+ */
+export interface DiffStats {
+    /** Number of world-level changed fields. */
+    worldChangedFields: number;
+    addedEntities: number;
+    removedEntities: number;
+    modifiedEntities: number;
+    /** Total changed fields across all modified entities. */
+    totalEntityChanges: number;
+}
+export declare function diffStats(diff: WorldStateDiff): DiffStats;
+/**
+ * Encode a `WorldStateDiff` as a compact binary `Uint8Array`.
+ *
+ * The binary format is self-describing (no schema required for decoding).
+ * `unpackDiff(packDiff(diff))` is guaranteed to produce a diff that when
+ * applied gives the same result as the original.
+ *
+ * @param diff  Diff to encode.
+ * @returns     Binary representation.
+ */
+export declare function packDiff(diff: WorldStateDiff): Uint8Array;
+/**
+ * Decode a `WorldStateDiff` previously encoded by `packDiff`.
+ *
+ * @param bytes  Binary data produced by `packDiff`.
+ * @returns      Decoded `WorldStateDiff`.
+ * @throws       If the magic bytes or version do not match.
+ */
+export declare function unpackDiff(bytes: Uint8Array): WorldStateDiff;