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

package/CHANGELOG.md

@@ -10,6 +10,37 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.8] — 2026-03-24
+
+  ### Added
+
+  - **CE-7 · Spatial Partitioning API for WebWorker Support** (`src/parallel.ts`)
+    - Add partitionWorld / mergePartitions / detectBoundaryPairs /
+      assignEntitiesToPartitions / canonicaliseBoundaryPairs.  Boundary pairs
+      are sorted in canonical (min-id first) order to preserve determinism
+      across partitions.
+    - Export via src/index.ts
+
+---
+
+## [0.1.7] — 2026-03-23
+
+  ### Added
+
+  - **CE-9 · World-state Diffing and Incremental Snapshots** (`src/sim/cover.ts`)
+    - diffWorldState(prev, next): top-level-field diff per entity; world
+      scalar/subsystem diffs; added/removed entity tracking
+    - applyDiff(base, diff): reconstruct next state (non-mutating, copy-on-write)
+    - packDiff(diff): custom binary encoding — magic "ANKD", tagged-value
+      format (null/bool/uint8/int32/float64/string/array/object); zero
+      external dependencies, implemented with DataView/Uint8Array
+    - unpackDiff(bytes): full round-trip with magic and version validation
+    - isDiffEmpty(), diffStats() — helpers for logging and network budgeting
+    - 30 tests; verified binary size < full JSON for single-entity changes
+    - Export via src/index.ts
+
+---
+
 ## [0.1.6] — 2026-03-23
 
   ### Added

package/dist/src/index.d.ts

@@ -20,3 +20,6 @@ export * from "./scenario.js";
 export * from "./catalog.js";
 export * from "./sim/formation-combat.js";
 export * from "./sim/cover.js";
+export * from "./sim/ai/behavior-trees.js";
+export * from "./snapshot.js";
+export * from "./parallel.js";

package/dist/src/index.js

@@ -29,3 +29,6 @@ export * from "./scenario.js"; // loadScenario(), validateScenario(), AnankeScen
 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()
+export * from "./sim/ai/behavior-trees.js"; // CE-10: BehaviorNode, FlankTarget, RetreatTo, ProtectAlly, GuardPosition, HealTarget, Sequence, Fallback
+export * from "./snapshot.js"; // CE-9: diffWorldState(), applyDiff(), packDiff(), unpackDiff(), WorldStateDiff
+export * from "./parallel.js"; // CE-7: partitionWorld(), mergePartitions(), detectBoundaryPairs(), assignEntitiesToPartitions()

package/dist/src/parallel.d.ts

@@ -0,0 +1,161 @@
+/**
+ * CE-7 — Multi-threading / WebWorker Support
+ *
+ * Spatial partitioning utilities for running `stepWorld` in parallel Workers.
+ *
+ * ## Threading Model
+ *
+ * ```
+ * Host thread
+ *   1.  partitionWorld(world, specs) → N WorldState slices
+ *   2.  postMessage(slice_i, commandSubset_i) to Worker i
+ *
+ * Worker i
+ *   3.  stepWorld(slice_i, commands_i, ctx) → stepped WorldState
+ *   4.  postMessage(steppedSlice_i) back to host
+ *
+ * Host thread
+ *   5.  mergePartitions([steppedSlice_0, …, steppedSlice_N-1], boundaryPairs)
+ *         → merged WorldState
+ *   6.  (optional) run a cross-partition boundary-pair resolution pass using
+ *         the sorted boundary pairs returned by canonicaliseBoundaryPairs()
+ * ```
+ *
+ * ## Determinism guarantee
+ *
+ * Each partition is fully deterministic in isolation: same seed + same commands
+ * always produces the same output. Cross-partition boundary pairs **must** be
+ * resolved in canonical order (lower entity id first) after merging to avoid
+ * seed divergence. Use `canonicaliseBoundaryPairs()` before any boundary
+ * resolution step.
+ *
+ * ## Partition sizing guidelines
+ *
+ * | Entity count | Suggested partitions |
+ * |-------------|---------------------|
+ * | < 200       | 1 (no benefit)      |
+ * | 200–500     | 2                   |
+ * | 500–2 000   | 4                   |
+ * | > 2 000     | 8                   |
+ *
+ * Keep each partition roughly equal in entity count for best load balance.
+ * Avoid partitions with < 25 entities (thread-overhead exceeds compute savings).
+ */
+import type { WorldState } from "./sim/world.js";
+/**
+ * Specification for a single spatial partition.
+ *
+ * `regionIds` are arbitrary string labels used to identify the geographic
+ * region(s) this partition covers (e.g. `["north-west", "north-centre"]`).
+ * They are metadata only — they do not affect computation.
+ *
+ * `entities` lists the entity ids that belong to this partition.
+ * An entity id must appear in **at most one** partition; duplicate ids across
+ * partitions cause undefined behaviour in `mergePartitions`.
+ */
+export interface PartitionSpec {
+    /** Human-readable region labels (metadata only). */
+    regionIds: string[];
+    /** Entity ids assigned to this partition. */
+    entities: number[];
+}
+/**
+ * Result summary returned by `mergePartitions`.
+ * The merged `WorldState` is the primary payload; `unresolvedBoundaryPairs` are
+ * the boundary pairs sorted in canonical order and ready for an optional
+ * post-merge resolution pass (e.g. cross-partition push/repulsion).
+ */
+export interface MergeResult {
+    /** Merged world state with all entities from all partitions. */
+    world: WorldState;
+    /**
+     * Boundary pairs sorted in canonical order (a < b) for post-merge
+     * cross-partition resolution.  Pass these to your boundary-resolution step
+     * to preserve determinism.
+     */
+    sortedBoundaryPairs: [number, number][];
+}
+/**
+ * Split a `WorldState` into N independent partition slices.
+ *
+ * Each partition slice contains:
+ * - All world-level scalar / subsystem fields (shared, copy-on-write).
+ * - Only the entities whose ids appear in `spec.entities`.
+ *
+ * Entity ids not referenced in any spec are silently dropped from all slices.
+ * If you need unassigned entities preserved, include them in one of the specs.
+ *
+ * @param world  The current world state to partition.
+ * @param specs  One spec per desired partition.  Must have at least one entry.
+ * @returns      Array of `WorldState` slices, one per spec, in the same order.
+ */
+export declare function partitionWorld(world: WorldState, specs: PartitionSpec[]): WorldState[];
+/**
+ * Merge N independently-stepped partition slices back into a single
+ * `WorldState`, and return the boundary pairs sorted in canonical order.
+ *
+ * **Entity ownership rule:** If an entity id appears in multiple partition
+ * results (which can happen if a host intentionally duplicated a boundary
+ * entity as a read-only context ghost), the entity state from the
+ * **last partition** in the array wins.  To avoid ambiguity, ensure each
+ * entity id appears in at most one partition before stepping.
+ *
+ * World-level fields (`tick`, `seed`, subsystems) are taken from the first
+ * non-empty partition.  All partitions should have been stepped with the same
+ * seed and world-level state; mixing partitions stepped at different ticks
+ * produces undefined behaviour.
+ *
+ * @param partitions     Stepped WorldState slices, one per worker.
+ * @param boundaryPairs  Pairs of entity ids that span partition boundaries.
+ *                       Order within each pair does not matter — they are
+ *                       normalised to `[min, max]` internally.
+ * @returns              Merged world state + canonically sorted boundary pairs.
+ */
+export declare function mergePartitions(partitions: WorldState[], boundaryPairs: [number, number][]): MergeResult;
+/**
+ * Normalise and sort an array of entity-id pairs into canonical form.
+ *
+ * Each pair is normalised to `[min(a, b), max(a, b)]` and the array is sorted
+ * lexicographically by `[a, b]`.  Duplicate pairs are preserved (callers may
+ * de-duplicate if needed).
+ *
+ * Use this before any cross-partition resolution step to guarantee the same
+ * pair-processing order regardless of how the host partitioned the world.
+ *
+ * @param pairs  Boundary pairs in any order.
+ * @returns      New sorted array with each pair normalised.
+ */
+export declare function canonicaliseBoundaryPairs(pairs: [number, number][]): [number, number][];
+/**
+ * Automatically detect cross-partition entity pairs within a given range.
+ *
+ * Scans all entity pairs `(e_i from partition_A, e_j from partition_B)` where
+ * `A ≠ B`, and returns any pair whose entities are within `range_m` of each
+ * other (using 2-D Euclidean distance).  Results are canonically sorted.
+ *
+ * Useful for building the `boundaryPairs` argument to `mergePartitions` without
+ * manually specifying which pairs cross boundaries.
+ *
+ * Complexity: O(E²) — only suitable for boundary detection (not the hot path).
+ * For large entity counts, build boundary pairs from the spatial index instead.
+ *
+ * @param partitions  Post-step (or pre-step) partition slices.
+ * @param range_m     Maximum inter-entity distance to consider a boundary pair
+ *                    (in fixed-point metres, same scale as `entity.position_m`).
+ * @returns           Canonically sorted cross-partition boundary pairs.
+ */
+export declare function detectBoundaryPairs(partitions: WorldState[], range_m: number): [number, number][];
+/**
+ * Simple spatial partitioning helper — assigns entities to N partitions based
+ * on their X position (vertical strip partitioning).
+ *
+ * Entities are sorted by ascending `position_m.x` and divided into `n` roughly
+ * equal buckets.  This is suitable for combat scenarios where combatants are
+ * spread along the X axis.  For 2-D grid layouts, call this function twice
+ * (once per axis) and intersect the results.
+ *
+ * @param world     World state whose entities should be partitioned.
+ * @param n         Number of partitions (≥ 1).
+ * @returns         `PartitionSpec` array ready for `partitionWorld`.
+ */
+export declare function assignEntitiesToPartitions(world: WorldState, n: number): PartitionSpec[];

package/dist/src/parallel.js

@@ -0,0 +1,235 @@
+/**
+ * CE-7 — Multi-threading / WebWorker Support
+ *
+ * Spatial partitioning utilities for running `stepWorld` in parallel Workers.
+ *
+ * ## Threading Model
+ *
+ * ```
+ * Host thread
+ *   1.  partitionWorld(world, specs) → N WorldState slices
+ *   2.  postMessage(slice_i, commandSubset_i) to Worker i
+ *
+ * Worker i
+ *   3.  stepWorld(slice_i, commands_i, ctx) → stepped WorldState
+ *   4.  postMessage(steppedSlice_i) back to host
+ *
+ * Host thread
+ *   5.  mergePartitions([steppedSlice_0, …, steppedSlice_N-1], boundaryPairs)
+ *         → merged WorldState
+ *   6.  (optional) run a cross-partition boundary-pair resolution pass using
+ *         the sorted boundary pairs returned by canonicaliseBoundaryPairs()
+ * ```
+ *
+ * ## Determinism guarantee
+ *
+ * Each partition is fully deterministic in isolation: same seed + same commands
+ * always produces the same output. Cross-partition boundary pairs **must** be
+ * resolved in canonical order (lower entity id first) after merging to avoid
+ * seed divergence. Use `canonicaliseBoundaryPairs()` before any boundary
+ * resolution step.
+ *
+ * ## Partition sizing guidelines
+ *
+ * | Entity count | Suggested partitions |
+ * |-------------|---------------------|
+ * | < 200       | 1 (no benefit)      |
+ * | 200–500     | 2                   |
+ * | 500–2 000   | 4                   |
+ * | > 2 000     | 8                   |
+ *
+ * Keep each partition roughly equal in entity count for best load balance.
+ * Avoid partitions with < 25 entities (thread-overhead exceeds compute savings).
+ */
+// ── partitionWorld ─────────────────────────────────────────────────────────────
+/**
+ * Split a `WorldState` into N independent partition slices.
+ *
+ * Each partition slice contains:
+ * - All world-level scalar / subsystem fields (shared, copy-on-write).
+ * - Only the entities whose ids appear in `spec.entities`.
+ *
+ * Entity ids not referenced in any spec are silently dropped from all slices.
+ * If you need unassigned entities preserved, include them in one of the specs.
+ *
+ * @param world  The current world state to partition.
+ * @param specs  One spec per desired partition.  Must have at least one entry.
+ * @returns      Array of `WorldState` slices, one per spec, in the same order.
+ */
+export function partitionWorld(world, specs) {
+    if (specs.length === 0) {
+        throw new RangeError("parallel: partitionWorld requires at least one PartitionSpec");
+    }
+    // Build O(1) entity lookup
+    const entityMap = new Map(world.entities.map(e => [e.id, e]));
+    return specs.map(spec => {
+        // Collect entities for this partition; skip unknown ids
+        const entities = [];
+        for (const id of spec.entities) {
+            const e = entityMap.get(id);
+            if (e !== undefined)
+                entities.push(e);
+        }
+        // Maintain canonical ascending-id sort within partition
+        entities.sort((a, b) => a.id - b.id);
+        return {
+            ...world,
+            entities,
+        };
+    });
+}
+// ── mergePartitions ────────────────────────────────────────────────────────────
+/**
+ * Merge N independently-stepped partition slices back into a single
+ * `WorldState`, and return the boundary pairs sorted in canonical order.
+ *
+ * **Entity ownership rule:** If an entity id appears in multiple partition
+ * results (which can happen if a host intentionally duplicated a boundary
+ * entity as a read-only context ghost), the entity state from the
+ * **last partition** in the array wins.  To avoid ambiguity, ensure each
+ * entity id appears in at most one partition before stepping.
+ *
+ * World-level fields (`tick`, `seed`, subsystems) are taken from the first
+ * non-empty partition.  All partitions should have been stepped with the same
+ * seed and world-level state; mixing partitions stepped at different ticks
+ * produces undefined behaviour.
+ *
+ * @param partitions     Stepped WorldState slices, one per worker.
+ * @param boundaryPairs  Pairs of entity ids that span partition boundaries.
+ *                       Order within each pair does not matter — they are
+ *                       normalised to `[min, max]` internally.
+ * @returns              Merged world state + canonically sorted boundary pairs.
+ */
+export function mergePartitions(partitions, boundaryPairs) {
+    if (partitions.length === 0) {
+        throw new RangeError("parallel: mergePartitions requires at least one partition");
+    }
+    // Merge entities — last-partition-wins for duplicates
+    const entityMap = new Map();
+    for (const partition of partitions) {
+        for (const e of partition.entities) {
+            entityMap.set(e.id, e);
+        }
+    }
+    // Restore canonical ascending-id sort
+    const entities = [...entityMap.values()].sort((a, b) => a.id - b.id);
+    // World-level fields from first partition (tick, seed, subsystems)
+    const base = partitions[0];
+    const world = {
+        ...base,
+        entities,
+    };
+    // Canonical boundary pairs: normalise order + sort
+    const sortedBoundaryPairs = canonicaliseBoundaryPairs(boundaryPairs);
+    return { world, sortedBoundaryPairs };
+}
+// ── canonicaliseBoundaryPairs ─────────────────────────────────────────────────
+/**
+ * Normalise and sort an array of entity-id pairs into canonical form.
+ *
+ * Each pair is normalised to `[min(a, b), max(a, b)]` and the array is sorted
+ * lexicographically by `[a, b]`.  Duplicate pairs are preserved (callers may
+ * de-duplicate if needed).
+ *
+ * Use this before any cross-partition resolution step to guarantee the same
+ * pair-processing order regardless of how the host partitioned the world.
+ *
+ * @param pairs  Boundary pairs in any order.
+ * @returns      New sorted array with each pair normalised.
+ */
+export function canonicaliseBoundaryPairs(pairs) {
+    return pairs
+        .map(([a, b]) => a <= b ? [a, b] : [b, a])
+        .sort(([a1, b1], [a2, b2]) => (a1 - a2) || (b1 - b2));
+}
+// ── detectBoundaryPairs ────────────────────────────────────────────────────────
+/**
+ * Automatically detect cross-partition entity pairs within a given range.
+ *
+ * Scans all entity pairs `(e_i from partition_A, e_j from partition_B)` where
+ * `A ≠ B`, and returns any pair whose entities are within `range_m` of each
+ * other (using 2-D Euclidean distance).  Results are canonically sorted.
+ *
+ * Useful for building the `boundaryPairs` argument to `mergePartitions` without
+ * manually specifying which pairs cross boundaries.
+ *
+ * Complexity: O(E²) — only suitable for boundary detection (not the hot path).
+ * For large entity counts, build boundary pairs from the spatial index instead.
+ *
+ * @param partitions  Post-step (or pre-step) partition slices.
+ * @param range_m     Maximum inter-entity distance to consider a boundary pair
+ *                    (in fixed-point metres, same scale as `entity.position_m`).
+ * @returns           Canonically sorted cross-partition boundary pairs.
+ */
+export function detectBoundaryPairs(partitions, range_m) {
+    const range2 = range_m * range_m;
+    // Build (entityId → partitionIndex) map
+    const ownerMap = new Map();
+    for (let pi = 0; pi < partitions.length; pi++) {
+        for (const e of partitions[pi].entities) {
+            ownerMap.set(e.id, pi);
+        }
+    }
+    // Flat entity list for pair scanning
+    const all = partitions.flatMap(p => p.entities);
+    const pairs = [];
+    for (let i = 0; i < all.length; i++) {
+        const ei = all[i];
+        if (ei.injury.dead)
+            continue;
+        const piOwner = ownerMap.get(ei.id);
+        for (let j = i + 1; j < all.length; j++) {
+            const ej = all[j];
+            if (ej.injury.dead)
+                continue;
+            if (ownerMap.get(ej.id) === piOwner)
+                continue; // same partition — skip
+            const dx = ei.position_m.x - ej.position_m.x;
+            const dy = ei.position_m.y - ej.position_m.y;
+            const dist2 = dx * dx + dy * dy;
+            if (dist2 <= range2) {
+                const a = Math.min(ei.id, ej.id);
+                const b = Math.max(ei.id, ej.id);
+                pairs.push([a, b]);
+            }
+        }
+    }
+    return canonicaliseBoundaryPairs(pairs);
+}
+// ── assignEntitiesToPartitions ────────────────────────────────────────────────
+/**
+ * Simple spatial partitioning helper — assigns entities to N partitions based
+ * on their X position (vertical strip partitioning).
+ *
+ * Entities are sorted by ascending `position_m.x` and divided into `n` roughly
+ * equal buckets.  This is suitable for combat scenarios where combatants are
+ * spread along the X axis.  For 2-D grid layouts, call this function twice
+ * (once per axis) and intersect the results.
+ *
+ * @param world     World state whose entities should be partitioned.
+ * @param n         Number of partitions (≥ 1).
+ * @returns         `PartitionSpec` array ready for `partitionWorld`.
+ */
+export function assignEntitiesToPartitions(world, n) {
+    if (n < 1)
+        throw new RangeError("parallel: partition count must be ≥ 1");
+    const live = world.entities
+        .filter(e => !e.injury.dead)
+        .sort((a, b) => a.position_m.x - b.position_m.x);
+    const specs = Array.from({ length: n }, (_, i) => ({
+        regionIds: [`strip-${i}`],
+        entities: [],
+    }));
+    // Assign dead entities to first partition so they're not dropped
+    const dead = world.entities.filter(e => e.injury.dead);
+    for (const e of dead) {
+        specs[0].entities.push(e.id);
+    }
+    // Round-robin striped assignment for live entities
+    const bucketSize = Math.ceil(live.length / n);
+    for (let i = 0; i < live.length; i++) {
+        const bucket = Math.min(Math.trunc(i / bucketSize), n - 1);
+        specs[bucket].entities.push(live[i].id);
+    }
+    return specs;
+}

package/dist/src/sim/ai/behavior-trees.d.ts

@@ -0,0 +1,166 @@
+/**
+ * CE-10 — Pre-built AI Behavior Tree Library
+ *
+ * A thin, composable layer over the existing AI decision system.  Each
+ * `BehaviorNode` receives the ticking entity, the current world state, and
+ * kernel context, and either returns a `Command` (success) or `null` (failure /
+ * not applicable).
+ *
+ * ## Semantics
+ * - `null`  — node failed / condition not met
+ * - Command — node succeeded; caller should use this command
+ *
+ * ## Composite nodes
+ * - `Sequence`  — run children left-to-right; return first **non-null** result
+ *                 (priority / fallback selector pattern)
+ * - `Fallback`  — identical semantics to Sequence for this usage:
+ *                 try children in order, first non-null wins
+ *
+ * Note: The ROADMAP spec uses "first success wins" for both Sequence and
+ * Fallback (i.e. both are priority-selectors).  A traditional BT Sequence
+ * would return the *last* child result; here all composites return the first
+ * non-null command for practical game-AI use.
+ *
+ * ## Determinism constraint
+ * All nodes are deterministic.  Any tie-breaking or random sampling uses
+ * `eventSeed(world.seed, world.tick, entity.id, salt)` — never `Math.random()`.
+ */
+import type { Entity } from "../entity.js";
+import type { WorldState } from "../world.js";
+import type { KernelContext } from "../context.js";
+import type { Command } from "../commands.js";
+import { type Q } from "../../units.js";
+/**
+ * A single node in a behavior tree.
+ *
+ * `tick` is called once per AI frame (typically once per `stepWorld` tick).
+ * Returns a `Command` if this node produces an action, or `null` if the node's
+ * condition is not satisfied (pass control to the next node in a composite).
+ */
+export interface BehaviorNode {
+    tick(entity: Entity, world: WorldState, ctx: KernelContext): Command | null;
+}
+/**
+ * Move toward a target entity and attack when in range.
+ *
+ * If the target is dead or missing, returns null.
+ * Flanks by approaching from the target's perpendicular when `flankOffset > 0`.
+ *
+ * @param targetId     Id of the entity to flank/attack.
+ * @param flankOffset  Lateral offset in SCALE.m units (0 = direct approach).
+ */
+export declare function FlankTarget(targetId: number, flankOffset?: number): BehaviorNode;
+/**
+ * Move to a fixed world position and stop when within `arrivalRadius_m` metres.
+ *
+ * Returns null when already at the destination (no command needed).
+ *
+ * @param x_m           Destination x [SCALE.m].
+ * @param y_m           Destination y [SCALE.m].
+ * @param arrivalRadius_m  Stop radius [SCALE.m]. Default 5 000 (0.5 m).
+ */
+export declare function RetreatTo(x_m: number, y_m: number, arrivalRadius_m?: number): BehaviorNode;
+/**
+ * Move toward an allied entity and interpose between it and the nearest threat.
+ *
+ * - If ally is missing or dead, returns null.
+ * - If no threats (other entities) are present, returns null.
+ * - Otherwise moves toward the ally.
+ *
+ * @param allyId   Id of the entity to protect.
+ */
+export declare function ProtectAlly(allyId: number): BehaviorNode;
+/**
+ * Hold a position: move toward the guard point if outside `radius_m`, defend
+ * if inside.  Returns null when the entity is already inside the radius and
+ * there are no threats to defend against.
+ *
+ * @param x_m       Guard point x [SCALE.m].
+ * @param y_m       Guard point y [SCALE.m].
+ * @param radius_m  Patrol radius [SCALE.m].
+ */
+export declare function GuardPosition(x_m: number, y_m: number, radius_m: number): BehaviorNode;
+/**
+ * Move toward a target entity and issue a Treat command when in range.
+ *
+ * - Returns null if target is missing, already dead, or has no injuries.
+ * - Healing uses the first injured region found (deterministic iteration order).
+ *
+ * @param targetId   Id of the entity to heal.
+ */
+export declare function HealTarget(targetId: number): BehaviorNode;
+/**
+ * Priority selector: tries each child node in order and returns the first
+ * non-null command.  If all children return null, returns null.
+ *
+ * This is the most commonly used composite.  Place higher-priority behaviours
+ * earlier in the list.
+ *
+ * @param nodes  Child nodes to evaluate in order.
+ */
+export declare function Sequence(...nodes: BehaviorNode[]): BehaviorNode;
+/**
+ * Fallback: identical to `Sequence` — tries children in order, returns first
+ * non-null result.  Provided as a semantic alias for callers who prefer the
+ * standard BT naming convention (Sequence = AND-chain; Fallback = OR-chain).
+ *
+ * @param nodes  Child nodes to evaluate in order.
+ */
+export declare function Fallback(...nodes: BehaviorNode[]): BehaviorNode;
+/**
+ * Gate: return `inner.tick()` only if the entity's shock is below `maxShockQ`.
+ * When the entity is in severe shock it cannot act — returns null instead.
+ *
+ * Useful for wrapping aggressive nodes: "attack only if not badly shocked."
+ *
+ * @param maxShockQ  Q threshold; entity.injury.shock must be below this.
+ * @param inner      Wrapped node.
+ */
+export declare function IfNotShocked(maxShockQ: Q, inner: BehaviorNode): BehaviorNode;
+/**
+ * Gate: return `inner.tick()` only when `entity.energy.fatigue` is below
+ * `maxFatigueQ`.  Prevents exhausted entities from taking high-intensity actions.
+ *
+ * @param maxFatigueQ  Q threshold; fatigue must be below this.
+ * @param inner        Wrapped node.
+ */
+export declare function IfNotExhausted(maxFatigueQ: Q, inner: BehaviorNode): BehaviorNode;
+/**
+ * Probabilistic gate: run `inner` only when
+ * `eventSeed(world.seed, world.tick, entity.id, salt) % SCALE.Q < probability_Q`.
+ *
+ * Allows stochastic variation without `Math.random()`.
+ *
+ * @param probability_Q  Q probability [0..SCALE.Q]; q(1.0) = always, q(0) = never.
+ * @param salt           Arbitrary integer to distinguish independent rolls on the
+ *                       same entity+tick (default 0).
+ * @param inner          Wrapped node.
+ */
+export declare function WithProbability(probability_Q: Q, inner: BehaviorNode, salt?: number): BehaviorNode;
+/**
+ * Standard aggressive attacker: attack `targetId` at full intensity.
+ * Falls back to retreat if badly shocked (shock ≥ q(0.70)).
+ *
+ * @param targetId   Primary attack target.
+ * @param retreatX   Fallback retreat x [SCALE.m].
+ * @param retreatY   Fallback retreat y [SCALE.m].
+ */
+export declare function aggressorTree(targetId: number, retreatX: number, retreatY: number): BehaviorNode;
+/**
+ * Standard defender: hold position, heal allies when in range, defend otherwise.
+ *
+ * @param guardX     Guard point x [SCALE.m].
+ * @param guardY     Guard point y [SCALE.m].
+ * @param radius_m   Guard radius [SCALE.m].
+ * @param allyIds    Ally ids to heal (checked in order; first injured ally wins).
+ */
+export declare function defenderTree(guardX: number, guardY: number, radius_m: number, allyIds: number[]): BehaviorNode;
+/**
+ * Medic tree: prioritise healing each ally in the given list (first injured wins),
+ * then retreat to a safe point if badly shocked.
+ *
+ * @param allyIds    Allies to heal in priority order.
+ * @param safeX      Retreat x [SCALE.m].
+ * @param safeY      Retreat y [SCALE.m].
+ */
+export declare function medicTree(allyIds: number[], safeX: number, safeY: number): BehaviorNode;