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

package/CHANGELOG.md

@@ -10,6 +10,23 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.6] — 2026-03-23
+
+  ### Added
+
+  - **CE-15 · Dynamic Terrain Cover System** (`src/sim/cover.ts`)
+    - CoverSegment type: axis-aligned obstacle with material, height, burn state
+    - isLineOfSightBlocked(): pure integer segment-intersection test (no sqrt)
+    - computeCoverProtection(): multiplicative absorption across stacked cover
+    - arcClearsCover(): indirect/lob fire height check
+    - applyExplosionToTerrain(): proximity-scaled crater + wood ignition
+    - stepCoverDecay(): wood burn-out and crater erosion over real time
+    - 4 sample presets: stone wall, sandbag barricade, wooden palisade, dirt berm
+    - 60 tests
+    - Export via src/index.ts
+
+---
+
 ## [0.1.5] — 2026-03-21
 
   ### Added

package/dist/src/index.d.ts

@@ -18,3 +18,5 @@ export * from "./bridge/index.js";
 export * from "./world-factory.js";
 export * from "./scenario.js";
 export * from "./catalog.js";
+export * from "./sim/formation-combat.js";
+export * from "./sim/cover.js";

package/dist/src/index.js

@@ -27,3 +27,5 @@ export * from "./bridge/index.js"; // BridgeEngine, InterpolatedState, BridgeCon
 export * from "./world-factory.js"; // createWorld(), EntitySpec, ARCHETYPE_MAP, ITEM_MAP
 export * from "./scenario.js"; // loadScenario(), validateScenario(), AnankeScenario
 export * from "./catalog.js"; // CE-12: registerArchetype(), registerWeapon(), registerArmour(), getCatalogEntry()
+export * from "./sim/formation-combat.js"; // Phase 69: FormationUnit, TacticalEngagement, resolveTacticalEngagement()
+export * from "./sim/cover.js"; // CE-15: CoverSegment, computeCoverProtection(), isLineOfSightBlocked(), applyExplosionToTerrain()

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;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",