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

package/dist/src/sim/cover.d.ts

@@ -0,0 +1,186 @@
+/**
+ * CE-15 — Dynamic Terrain + Cover System
+ *
+ * Structural cover segments that reduce incoming damage and deform under explosions.
+ * Complements Phase 60 (Environmental Hazard Zones), which handles area-effect
+ * environmental damage; this module handles solid cover and line-of-sight blocking.
+ *
+ * ## Cover model
+ * Each `CoverSegment` is an axis-aligned horizontal obstacle (wall/barricade).
+ * LOS and protection are computed in 2-D (x/y world plane); `height_Sm` is used
+ * for above-cover arc checks (grenade lobs, indirect fire).
+ *
+ * All coordinates are in SCALE.m units (1 unit = 0.1 mm; 10 000 units = 1 m).
+ *
+ * ## Deformation model
+ * Explosions reduce `height_Sm` and may ignite wood segments.
+ * `stepCoverDecay` advances burn-out and crater erosion over real-time seconds.
+ *
+ * Integration with Phase 60: callers may convert an ignited segment into a
+ * `HazardZone` of type "fire" centred on the segment midpoint.
+ */
+import { type Q } from "../units.js";
+/** Cover material — determines energy absorption and deformation behaviour. */
+export type CoverMaterial = "dirt" | "stone" | "wood" | "sandbag";
+/**
+ * Energy absorption fraction per material [Q].
+ * Applied to incoming projectile / blast energy before it reaches the target.
+ */
+export declare const MATERIAL_ABSORPTION: Record<CoverMaterial, Q>;
+/**
+ * Explosion energy threshold [J] above which wood ignites.
+ * A grenade at close range (~30 J) reliably sets wood alight.
+ */
+export declare const WOOD_IGNITION_THRESHOLD_J = 30;
+/**
+ * Height lost per joule of explosion energy at the segment [SCALE.m / J].
+ * Calibrated so a 1 000 J blast (artillery shell) craters 1 m of height
+ * (10 000 SCALE.m) — i.e. rate = 10 SCALE.m / J.
+ */
+export declare const CRATER_RATE_Sm_PER_J = 10;
+/**
+ * Natural crater erosion rate [SCALE.m / s].
+ * Rain and loose earth refill a small crater in hours.
+ * At 1 SCALE.m/s a 1 m (10 000 Sm) crater refills in ~10 000 s (~2.8 h).
+ */
+export declare const CRATER_EROSION_RATE_Sm_PER_S = 1;
+/**
+ * Wood burn-out rate [SCALE.m of height consumed per second while burning].
+ * A 2 m tall (20 000 Sm) wooden wall burns down in ~200 s (~3 min).
+ */
+export declare const WOOD_BURN_RATE_Sm_PER_S = 100;
+/**
+ * An axis-aligned rectangular cover segment in world-space (2-D top-down view).
+ *
+ * The segment occupies the line from `(x_Sm, y_Sm)` to `(x_Sm + length_Sm, y_Sm)`.
+ * For LOS purposes it is treated as an infinitely thin vertical wall of the given
+ * length; `height_Sm` is used only for above-cover arc checks.
+ */
+export interface CoverSegment {
+    id: string;
+    /** Left end x-coordinate [SCALE.m]. */
+    x_Sm: number;
+    /** Left end y-coordinate (constant along the segment) [SCALE.m]. */
+    y_Sm: number;
+    /** Segment length along the x-axis [SCALE.m]. */
+    length_Sm: number;
+    /** Current cover height [SCALE.m]. Reduced by explosions. */
+    height_Sm: number;
+    /** Original (undamaged) height [SCALE.m]. Used as crater refill ceiling. */
+    originalHeight_Sm: number;
+    material: CoverMaterial;
+    /** True when the segment is actively on fire (wood only). */
+    burning: boolean;
+}
+/** Point in the 2-D world plane used for LOS / protection queries. */
+export interface WorldPoint2D {
+    x_Sm: number;
+    y_Sm: number;
+}
+/** Result of `applyExplosionToTerrain`. */
+export interface CoverExplosionResult {
+    /** Ids of segments that lost height (craters formed). */
+    cratered: string[];
+    /** Ids of segments that ignited (wood only). */
+    ignited: string[];
+}
+/**
+ * Create a `CoverSegment` with `originalHeight_Sm` initialised from `height_Sm`.
+ */
+export declare function createCoverSegment(id: string, x_Sm: number, y_Sm: number, length_Sm: number, height_Sm: number, material: CoverMaterial): CoverSegment;
+/** 3 m stone wall (30 000 Sm long, 1.5 m tall). */
+export declare const COVER_STONE_WALL: CoverSegment;
+/** 2 m sandbag barricade (20 000 Sm long, 1.0 m tall). */
+export declare const COVER_SANDBAG_BARRICADE: CoverSegment;
+/** 4 m wooden palisade (40 000 Sm long, 2.0 m tall). */
+export declare const COVER_WOODEN_PALISADE: CoverSegment;
+/** 5 m dirt berm (50 000 Sm long, 1.2 m tall). */
+export declare const COVER_DIRT_BERM: CoverSegment;
+/**
+ * Test whether at least one non-destroyed cover segment crosses the LOS
+ * line from `from` to `to`.
+ *
+ * Segments with `height_Sm ≤ 0` are considered destroyed and ignored.
+ *
+ * Pure integer arithmetic — no `Math.sqrt`.
+ *
+ * @param from     Attacker position.
+ * @param to       Target position.
+ * @param segments Cover segments to test.
+ * @returns `true` if LOS is blocked by at least one segment.
+ */
+export declare function isLineOfSightBlocked(from: WorldPoint2D, to: WorldPoint2D, segments: readonly CoverSegment[]): boolean;
+/**
+ * Compute the aggregate cover protection factor [Q] for a shot from `attacker`
+ * to `target`.
+ *
+ * For each cover segment that:
+ *   1. Intersects the LOS line.
+ *   2. Has `height_Sm > 0`.
+ *
+ * the material absorption fraction is composed multiplicatively:
+ *
+ *   passthrough = ∏ (1 − absorptionᵢ)
+ *   protection  = 1 − passthrough
+ *
+ * Returns Q ∈ [0, SCALE.Q]:
+ *   0        = no cover (clear LOS)
+ *   SCALE.Q  = complete protection (unreachable for finite stacked cover)
+ */
+export declare function computeCoverProtection(attacker: WorldPoint2D, target: WorldPoint2D, segments: readonly CoverSegment[]): Q;
+/**
+ * Test whether arc fire (lob / indirect trajectory) at `elevation_Sm` clears all
+ * cover segments on the LOS from `attacker` to `target`.
+ *
+ * A segment blocks the arc only if `elevation_Sm < seg.height_Sm`.  Destroyed
+ * segments (height ≤ 0) are ignored.
+ *
+ * @param attacker     Attacker position.
+ * @param target       Target position.
+ * @param elevation_Sm Arc peak height above ground [SCALE.m].
+ * @param segments     Segments to test.
+ * @returns `true` if the arc passes over all cover.
+ */
+export declare function arcClearsCover(attacker: WorldPoint2D, target: WorldPoint2D, elevation_Sm: number, segments: readonly CoverSegment[]): boolean;
+/**
+ * Apply a point-source explosion to nearby cover segments.
+ *
+ * For each segment whose midpoint falls within `blastRadius_Sm` of `(cx, cy)`:
+ * - Height is reduced proportional to proximity and energy.
+ * - Wood segments above `WOOD_IGNITION_THRESHOLD_J` (scaled energy) ignite.
+ *
+ * Proximity scaling uses a squared falloff approximation
+ * `proximityQ ≈ 1 − distSq / radiusSq` (integer, no sqrt).
+ *
+ * Mutates `segments` in-place.
+ *
+ * @param cx             Blast centre x [SCALE.m].
+ * @param cy             Blast centre y [SCALE.m].
+ * @param energy_J       Total explosion energy [J].
+ * @param blastRadius_Sm Blast radius [SCALE.m].
+ * @param segments       Segments to affect (mutated).
+ * @returns Summary of craters and ignitions.
+ */
+export declare function applyExplosionToTerrain(cx: number, cy: number, energy_J: number, blastRadius_Sm: number, segments: CoverSegment[]): CoverExplosionResult;
+/**
+ * Advance cover decay over `elapsedSeconds`:
+ *
+ * - **Burning wood**: height decreases at `WOOD_BURN_RATE_Sm_PER_S` per second.
+ *   Burning stops when height reaches 0.
+ * - **Craters (non-burning)**: height erodes toward `originalHeight_Sm`
+ *   at `CRATER_EROSION_RATE_Sm_PER_S` per second.
+ *
+ * Mutates `segments` in-place.
+ *
+ * @param segments        Segments to advance.
+ * @param elapsedSeconds  Elapsed real time in seconds.
+ */
+export declare function stepCoverDecay(segments: CoverSegment[], elapsedSeconds: number): void;
+/**
+ * Return the 2-D midpoint of a cover segment.
+ */
+export declare function coverSegmentCentre(seg: CoverSegment): WorldPoint2D;
+/**
+ * Return `true` if the segment has been completely destroyed (height reduced to 0).
+ */
+export declare function isCoverDestroyed(seg: CoverSegment): boolean;

package/dist/src/sim/cover.js

@@ -0,0 +1,290 @@
+/**
+ * CE-15 — Dynamic Terrain + Cover System
+ *
+ * Structural cover segments that reduce incoming damage and deform under explosions.
+ * Complements Phase 60 (Environmental Hazard Zones), which handles area-effect
+ * environmental damage; this module handles solid cover and line-of-sight blocking.
+ *
+ * ## Cover model
+ * Each `CoverSegment` is an axis-aligned horizontal obstacle (wall/barricade).
+ * LOS and protection are computed in 2-D (x/y world plane); `height_Sm` is used
+ * for above-cover arc checks (grenade lobs, indirect fire).
+ *
+ * All coordinates are in SCALE.m units (1 unit = 0.1 mm; 10 000 units = 1 m).
+ *
+ * ## Deformation model
+ * Explosions reduce `height_Sm` and may ignite wood segments.
+ * `stepCoverDecay` advances burn-out and crater erosion over real-time seconds.
+ *
+ * Integration with Phase 60: callers may convert an ignited segment into a
+ * `HazardZone` of type "fire" centred on the segment midpoint.
+ */
+import { q, SCALE, clampQ, mulDiv } from "../units.js";
+/**
+ * Energy absorption fraction per material [Q].
+ * Applied to incoming projectile / blast energy before it reaches the target.
+ */
+export const MATERIAL_ABSORPTION = {
+    stone: q(0.70), // dense masonry — absorbs 70% of incoming energy
+    sandbag: q(0.60), // packed granular — 60%
+    dirt: q(0.50), // loose earth — 50%
+    wood: q(0.35), // timber — 35% (burns easily)
+};
+/**
+ * Explosion energy threshold [J] above which wood ignites.
+ * A grenade at close range (~30 J) reliably sets wood alight.
+ */
+export const WOOD_IGNITION_THRESHOLD_J = 30;
+/**
+ * Height lost per joule of explosion energy at the segment [SCALE.m / J].
+ * Calibrated so a 1 000 J blast (artillery shell) craters 1 m of height
+ * (10 000 SCALE.m) — i.e. rate = 10 SCALE.m / J.
+ */
+export const CRATER_RATE_Sm_PER_J = 10;
+/**
+ * Natural crater erosion rate [SCALE.m / s].
+ * Rain and loose earth refill a small crater in hours.
+ * At 1 SCALE.m/s a 1 m (10 000 Sm) crater refills in ~10 000 s (~2.8 h).
+ */
+export const CRATER_EROSION_RATE_Sm_PER_S = 1;
+/**
+ * Wood burn-out rate [SCALE.m of height consumed per second while burning].
+ * A 2 m tall (20 000 Sm) wooden wall burns down in ~200 s (~3 min).
+ */
+export const WOOD_BURN_RATE_Sm_PER_S = 100;
+// ── Construction helpers ──────────────────────────────────────────────────────
+/**
+ * Create a `CoverSegment` with `originalHeight_Sm` initialised from `height_Sm`.
+ */
+export function createCoverSegment(id, x_Sm, y_Sm, length_Sm, height_Sm, material) {
+    return {
+        id,
+        x_Sm,
+        y_Sm,
+        length_Sm: Math.max(1, length_Sm),
+        height_Sm: Math.max(0, height_Sm),
+        originalHeight_Sm: Math.max(0, height_Sm),
+        material,
+        burning: false,
+    };
+}
+// ── Sample segments ───────────────────────────────────────────────────────────
+/** 3 m stone wall (30 000 Sm long, 1.5 m tall). */
+export const COVER_STONE_WALL = createCoverSegment("stone_wall", 0, 50_000, 30_000, 15_000, "stone");
+/** 2 m sandbag barricade (20 000 Sm long, 1.0 m tall). */
+export const COVER_SANDBAG_BARRICADE = createCoverSegment("sandbag_barricade", 0, 30_000, 20_000, 10_000, "sandbag");
+/** 4 m wooden palisade (40 000 Sm long, 2.0 m tall). */
+export const COVER_WOODEN_PALISADE = createCoverSegment("wooden_palisade", 0, 20_000, 40_000, 20_000, "wood");
+/** 5 m dirt berm (50 000 Sm long, 1.2 m tall). */
+export const COVER_DIRT_BERM = createCoverSegment("dirt_berm", 0, 40_000, 50_000, 12_000, "dirt");
+// ── Geometry helpers (integer arithmetic only) ────────────────────────────────
+/** Squared Euclidean distance between two points [SCALE.m²]. */
+function distSq(ax, ay, bx, by) {
+    const dx = bx - ax;
+    const dy = by - ay;
+    return dx * dx + dy * dy;
+}
+/**
+ * Cross product of vectors (AB × AC) — positive = C is left of AB.
+ */
+function cross2D(ax, ay, bx, by, cx, cy) {
+    return (bx - ax) * (cy - ay) - (by - ay) * (cx - ax);
+}
+/** Check whether point (px, py) lies on segment (ax, ay)→(bx, by). */
+function onSegment2D(ax, ay, bx, by, px, py) {
+    return (Math.min(ax, bx) <= px && px <= Math.max(ax, bx) &&
+        Math.min(ay, by) <= py && py <= Math.max(ay, by));
+}
+/**
+ * Test whether line segment P1→P2 intersects segment P3→P4.
+ * Pure integer arithmetic — no division, no float.
+ */
+function segmentsIntersect(p1x, p1y, p2x, p2y, p3x, p3y, p4x, p4y) {
+    const d1 = cross2D(p3x, p3y, p4x, p4y, p1x, p1y);
+    const d2 = cross2D(p3x, p3y, p4x, p4y, p2x, p2y);
+    const d3 = cross2D(p1x, p1y, p2x, p2y, p3x, p3y);
+    const d4 = cross2D(p1x, p1y, p2x, p2y, p4x, p4y);
+    if (((d1 > 0 && d2 < 0) || (d1 < 0 && d2 > 0)) &&
+        ((d3 > 0 && d4 < 0) || (d3 < 0 && d4 > 0))) {
+        return true;
+    }
+    if (d1 === 0 && onSegment2D(p3x, p3y, p4x, p4y, p1x, p1y))
+        return true;
+    if (d2 === 0 && onSegment2D(p3x, p3y, p4x, p4y, p2x, p2y))
+        return true;
+    if (d3 === 0 && onSegment2D(p1x, p1y, p2x, p2y, p3x, p3y))
+        return true;
+    if (d4 === 0 && onSegment2D(p1x, p1y, p2x, p2y, p4x, p4y))
+        return true;
+    return false;
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Test whether at least one non-destroyed cover segment crosses the LOS
+ * line from `from` to `to`.
+ *
+ * Segments with `height_Sm ≤ 0` are considered destroyed and ignored.
+ *
+ * Pure integer arithmetic — no `Math.sqrt`.
+ *
+ * @param from     Attacker position.
+ * @param to       Target position.
+ * @param segments Cover segments to test.
+ * @returns `true` if LOS is blocked by at least one segment.
+ */
+export function isLineOfSightBlocked(from, to, segments) {
+    for (const seg of segments) {
+        if (seg.height_Sm <= 0)
+            continue;
+        if (segmentsIntersect(from.x_Sm, from.y_Sm, to.x_Sm, to.y_Sm, seg.x_Sm, seg.y_Sm, seg.x_Sm + seg.length_Sm, seg.y_Sm)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Compute the aggregate cover protection factor [Q] for a shot from `attacker`
+ * to `target`.
+ *
+ * For each cover segment that:
+ *   1. Intersects the LOS line.
+ *   2. Has `height_Sm > 0`.
+ *
+ * the material absorption fraction is composed multiplicatively:
+ *
+ *   passthrough = ∏ (1 − absorptionᵢ)
+ *   protection  = 1 − passthrough
+ *
+ * Returns Q ∈ [0, SCALE.Q]:
+ *   0        = no cover (clear LOS)
+ *   SCALE.Q  = complete protection (unreachable for finite stacked cover)
+ */
+export function computeCoverProtection(attacker, target, segments) {
+    let passthrough = SCALE.Q; // q(1.0) — all energy passes through initially
+    for (const seg of segments) {
+        if (seg.height_Sm <= 0)
+            continue;
+        if (segmentsIntersect(attacker.x_Sm, attacker.y_Sm, target.x_Sm, target.y_Sm, seg.x_Sm, seg.y_Sm, seg.x_Sm + seg.length_Sm, seg.y_Sm)) {
+            const absorption = MATERIAL_ABSORPTION[seg.material];
+            passthrough = mulDiv(passthrough, SCALE.Q - absorption, SCALE.Q);
+        }
+    }
+    return clampQ((SCALE.Q - passthrough), 0, SCALE.Q);
+}
+/**
+ * Test whether arc fire (lob / indirect trajectory) at `elevation_Sm` clears all
+ * cover segments on the LOS from `attacker` to `target`.
+ *
+ * A segment blocks the arc only if `elevation_Sm < seg.height_Sm`.  Destroyed
+ * segments (height ≤ 0) are ignored.
+ *
+ * @param attacker     Attacker position.
+ * @param target       Target position.
+ * @param elevation_Sm Arc peak height above ground [SCALE.m].
+ * @param segments     Segments to test.
+ * @returns `true` if the arc passes over all cover.
+ */
+export function arcClearsCover(attacker, target, elevation_Sm, segments) {
+    for (const seg of segments) {
+        if (seg.height_Sm <= 0)
+            continue;
+        if (segmentsIntersect(attacker.x_Sm, attacker.y_Sm, target.x_Sm, target.y_Sm, seg.x_Sm, seg.y_Sm, seg.x_Sm + seg.length_Sm, seg.y_Sm)) {
+            if (elevation_Sm < seg.height_Sm)
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Apply a point-source explosion to nearby cover segments.
+ *
+ * For each segment whose midpoint falls within `blastRadius_Sm` of `(cx, cy)`:
+ * - Height is reduced proportional to proximity and energy.
+ * - Wood segments above `WOOD_IGNITION_THRESHOLD_J` (scaled energy) ignite.
+ *
+ * Proximity scaling uses a squared falloff approximation
+ * `proximityQ ≈ 1 − distSq / radiusSq` (integer, no sqrt).
+ *
+ * Mutates `segments` in-place.
+ *
+ * @param cx             Blast centre x [SCALE.m].
+ * @param cy             Blast centre y [SCALE.m].
+ * @param energy_J       Total explosion energy [J].
+ * @param blastRadius_Sm Blast radius [SCALE.m].
+ * @param segments       Segments to affect (mutated).
+ * @returns Summary of craters and ignitions.
+ */
+export function applyExplosionToTerrain(cx, cy, energy_J, blastRadius_Sm, segments) {
+    const cratered = [];
+    const ignited = [];
+    const radiusSq = blastRadius_Sm * blastRadius_Sm;
+    for (const seg of segments) {
+        const midX = seg.x_Sm + Math.trunc(seg.length_Sm / 2);
+        const midY = seg.y_Sm;
+        const dSq = distSq(cx, cy, midX, midY);
+        if (dSq > radiusSq)
+            continue;
+        // proximityQ: q(1.0) at centre, q(0) at edge — squared distance falloff
+        const proximityQ = Math.max(0, Math.round(SCALE.Q - Math.round((dSq * SCALE.Q) / Math.max(1, radiusSq))));
+        const localEnergy_J = Math.round((energy_J * proximityQ) / SCALE.Q);
+        if (localEnergy_J <= 0)
+            continue;
+        // Crater: reduce height, min 0
+        const heightLoss = Math.min(seg.height_Sm, localEnergy_J * CRATER_RATE_Sm_PER_J);
+        if (heightLoss > 0) {
+            seg.height_Sm = Math.max(0, seg.height_Sm - heightLoss);
+            cratered.push(seg.id);
+        }
+        // Ignition: wood above threshold
+        if (seg.material === "wood" && !seg.burning && localEnergy_J >= WOOD_IGNITION_THRESHOLD_J) {
+            seg.burning = true;
+            ignited.push(seg.id);
+        }
+    }
+    return { cratered, ignited };
+}
+/**
+ * Advance cover decay over `elapsedSeconds`:
+ *
+ * - **Burning wood**: height decreases at `WOOD_BURN_RATE_Sm_PER_S` per second.
+ *   Burning stops when height reaches 0.
+ * - **Craters (non-burning)**: height erodes toward `originalHeight_Sm`
+ *   at `CRATER_EROSION_RATE_Sm_PER_S` per second.
+ *
+ * Mutates `segments` in-place.
+ *
+ * @param segments        Segments to advance.
+ * @param elapsedSeconds  Elapsed real time in seconds.
+ */
+export function stepCoverDecay(segments, elapsedSeconds) {
+    if (elapsedSeconds <= 0)
+        return;
+    for (const seg of segments) {
+        if (seg.burning) {
+            const burnLoss = Math.round(WOOD_BURN_RATE_Sm_PER_S * elapsedSeconds);
+            seg.height_Sm = Math.max(0, seg.height_Sm - burnLoss);
+            if (seg.height_Sm === 0) {
+                seg.burning = false; // nothing left to burn
+            }
+        }
+        else if (seg.height_Sm < seg.originalHeight_Sm) {
+            const erosion = Math.round(CRATER_EROSION_RATE_Sm_PER_S * elapsedSeconds);
+            seg.height_Sm = Math.min(seg.originalHeight_Sm, seg.height_Sm + erosion);
+        }
+    }
+}
+/**
+ * Return the 2-D midpoint of a cover segment.
+ */
+export function coverSegmentCentre(seg) {
+    return {
+        x_Sm: seg.x_Sm + Math.trunc(seg.length_Sm / 2),
+        y_Sm: seg.y_Sm,
+    };
+}
+/**
+ * Return `true` if the segment has been completely destroyed (height reduced to 0).
+ */
+export function isCoverDestroyed(seg) {
+    return seg.height_Sm <= 0;
+}

package/dist/src/sim/formation-combat.d.ts

@@ -0,0 +1,170 @@
+/**
+ * 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 { type Q, type I32 } from "../units.js";
+import type { Archetype } from "../archetypes.js";
+/**
+ * A squad- or company-level unit in a formation engagement.
+ * All numeric fields that represent ratios use Q; headcounts are plain integers.
+ */
+export interface FormationUnit {
+    /** Unique identifier within the engagement. */
+    id: string;
+    /** Polity / faction identifier. Units with the same factionId fight together. */
+    factionId: string;
+    /** Current headcount (soldiers present and capable of fighting). */
+    strength: number;
+    /** Sum of `peakForce_N` across all members (SCALE.N units). */
+    aggregatedForce_N: I32;
+    /**
+     * Average continuous endurance as a Q fraction [0..SCALE.Q].
+     * Derived from avg(continuousPower_W) / HUMAN_CONT_W_REFERENCE.
+     */
+    aggregatedEndurance: Q;
+    /** Formation morale Q [0..SCALE.Q]. Collapse below `breakThreshold` triggers rout. */
+    moraleQ: Q;
+    /**
+     * Representative archetype for the unit.  Used by the host to spawn micro-simulation
+     * entities at the decisive tick when named characters are present.
+     */
+    archetype: Archetype;
+    /**
+     * Optional list of named entity ids (from the micro-simulation) embedded in this unit.
+     * Any id below NAMED_ENTITY_THRESHOLD is treated as named automatically.
+     */
+    namedEntityIds?: readonly number[];
+}
+/** Terrain type affects defender effectiveness multiplier. */
+export type TacticalTerrain = "open" | "difficult" | "fortified";
+/**
+ * An engagement between two (or more) sides.
+ * `attackers` and `defenders` are lists of `FormationUnit`.
+ * All units sharing a `factionId` within a side fight cohesively.
+ */
+export interface TacticalEngagement {
+    attackers: FormationUnit[];
+    defenders: FormationUnit[];
+    /** Terrain favours the defender. */
+    terrain: TacticalTerrain;
+    /**
+     * How many tactical ticks to resolve (1 tactical tick ≈ 1 real second at this scale).
+     * Typical engagement: 30–600 ticks.
+     */
+    durationTicks: number;
+    /**
+     * World seed — used for deterministic morale collapse rolls.
+     * If omitted, morale collapse is deterministic via threshold comparison only (no randomness).
+     */
+    seed?: number;
+}
+/** Per-side outcome summary from `resolveTacticalEngagement`. */
+export interface TacticalSideResult {
+    casualties: number;
+    survivingStrength: number;
+    finalMoraleQ: Q;
+    routed: boolean;
+}
+export interface TacticalResult {
+    attackerResult: TacticalSideResult;
+    defenderResult: TacticalSideResult;
+    /** Faction ids that routed (morale collapsed below `breakThreshold`). */
+    routedFactions: string[];
+    /**
+     * Named entity ids present in the engagement that require micro-simulation resolution.
+     * The host should run `stepWorld` for these entities at the decisive tick.
+     */
+    namedEntityIds: number[];
+    /**
+     * The tick number (0-based) at which the decisive moment occurred.
+     * If no side routed or was wiped out, equals `durationTicks`.
+     */
+    decisiveTick: number;
+}
+/**
+ * Entity ids strictly below this value are treated as "named" and trigger
+ * micro-simulation delegation.  Hosts may override via `FormationUnit.namedEntityIds`.
+ */
+export declare const NAMED_ENTITY_THRESHOLD = 1000;
+/**
+ * Morale Q threshold below which a unit routs.
+ * Matches Phase 32D formation morale `BASE_DECAY` model.
+ */
+export declare const ROUT_THRESHOLD: Q;
+/**
+ * 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 declare const MORALE_CASUALTY_DECAY_PER_PCT: Q;
+/**
+ * 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 declare const LANCHESTER_RATE = 0.1;
+/**
+ * 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 declare const REFERENCE_POWER_PER_SOLDIER: number;
+/**
+ * Defender effectiveness multiplier per terrain type.
+ * Applied to the defender's combat power (force × endurance × morale).
+ * Attackers always use multiplier q(1.0).
+ */
+export declare const TERRAIN_DEFENDER_MUL: Record<TacticalTerrain, Q>;
+/**
+ * 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 declare function createFormationUnit(id: string, factionId: string, strength: number, archetype: Archetype, moraleQ?: Q): FormationUnit;
+/**
+ * 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 declare function resolveTacticalEngagement(engagement: TacticalEngagement): TacticalResult;
+/**
+ * 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 declare function applyTacticalResultToPolity(currentStrength_Q: Q, initialStrength: number, result: TacticalSideResult): Q;