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

package/CHANGELOG.md

@@ -8,6 +8,93 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Added
+
+- **CE-14 · Socio-Economic Campaign Layer → Stable Promotion**
+  - Promote `stepPolityDay`, `declareWar`, `makePeace`, `areAtWar`,
+    `createPolity`, `createPolityRegistry`, `Polity`, `PolityRegistry`,
+    `PolityPair` (`src/polity.ts`), `stepTechDiffusion`, `computeDiffusionPressure`,
+    `totalInboundPressure`, `techEraName` (`src/tech-diffusion.ts`), and
+    `applyEmotionalContagion`, `stepEmotionalWaves`, `computeEmotionalSpread`,
+    `triggerMilitaryRout`, `triggerVictoryRally`, `netEmotionalPressure`,
+    `EmotionalWave` (`src/emotional-contagion.ts`) from Tier 2 (Experimental)
+    to Tier 1 (Stable) in `STABLE_API.md`.
+  - Add `export *` re-exports to `src/polity.ts` so the `ananke/polity` subpath
+    delivers the complete Socio-Economic Campaign Layer in one import.
+  - Freeze `Polity`, `PolityRegistry`, `PolityPair` and `EmotionalWave` interfaces
+    with `@stable CE-14` JSDoc annotations — no required-field additions without a
+    minor bump, no renames without a major bump.
+
+### Migration guide — v0.1.x → v0.2.0
+
+This is a **non-breaking promotion**.  No existing code needs to change.
+
+#### What is new
+
+The Socio-Economic Campaign Layer (`polity`, `tech-diffusion`, `emotional-contagion`)
+is now Tier 1 (Stable).  You can depend on it without fear of silent API churn.
+
+#### Import change (optional)
+
+Instead of importing from the package root:
+
+```typescript
+import { stepPolityDay }       from "@its-not-rocket-science/ananke";
+import { stepTechDiffusion }   from "@its-not-rocket-science/ananke";
+import { applyEmotionalContagion } from "@its-not-rocket-science/ananke";
+```
+
+You may now import from the dedicated subpath (recommended for tree-shaking):
+
+```typescript
+import {
+  stepPolityDay,
+  stepTechDiffusion,
+  applyEmotionalContagion,
+  EmotionalWave,
+} from "@its-not-rocket-science/ananke/polity";
+```
+
+Both forms remain supported indefinitely.
+
+#### Interface freeze guarantees (from v0.2.0)
+
+| Interface | Guarantee |
+|-----------|-----------|
+| `Polity` | Existing fields never renamed/removed without major bump |
+| `PolityRegistry` | `polities`, `activeWars`, `alliances` fields frozen |
+| `PolityPair` | `polityAId`, `polityBId`, `sharedLocations`, `routeQuality_Q` frozen |
+| `EmotionalWave` | `profileId`, `sourcePolityId`, `intensity_Q`, `daysActive` frozen |
+
+Adding new **optional** fields to these interfaces is never a breaking change.
+
+---
+
+## [0.1.9] — 2026-03-24
+
+  ### Added
+
+  - **CE-14 · Promote Socio-economic Campaign Layer to Tier 1 Stable** (`src/parallel.ts`)
+    - Freeze Polity, PolityRegistry, PolityPair, EmotionalWave interfaces.
+    - Promote stepPolityDay, stepTechDiffusion, applyEmotionalContagion,
+      declareWar, makePeace to Tier 1 in STABLE_API.md.
+    - Re-export tech-diffusion and emotional-contagion from src/polity.ts so
+      ananke/polity is a single-import campaign layer entry point.
+    - Add v0.1.x -> v0.2.0 migration guide to CHANGELOG.md.
+
+---
+
+## [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
@@ -28,8 +115,6 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
----
-
 ## [0.1.6] — 2026-03-23
 
   ### Added

package/STABLE_API.md

@@ -112,6 +112,48 @@ including `AnimationHints`, `GrapplePoseConstraint`, and `InterpolatedState`.
 | `formatOneLine(desc)` | One-line summary |
 | `CharacterDescription`, `AttributeRating` | Types |
 
+### Socio-Economic Campaign Layer (`ananke/polity` subpath — CE-14)
+
+All of the following are available via `import { … } from "ananke/polity"` as a single
+entry point.  The frozen interfaces (`Polity`, `PolityRegistry`, `PolityPair`,
+`EmotionalWave`) will not gain required fields or lose existing fields without a minor
+version bump; renames require a major bump and migration guide.
+
+#### Polity system (`src/polity.ts`)
+
+| Export | Description |
+|--------|-------------|
+| `Polity` _(frozen)_ | Geopolitical entity: city, nation, or empire |
+| `PolityRegistry` _(frozen)_ | Container for all polities and active wars/alliances |
+| `PolityPair` _(frozen)_ | Trade/proximity link between two polities |
+| `createPolity(spec)` | Construct a `Polity` with sensible defaults |
+| `createPolityRegistry(polities)` | Construct an empty registry |
+| `stepPolityDay(registry, pairs, worldSeed, tick)` | Advance all polities by one simulated day |
+| `declareWar(registry, aId, bId)` | Record a war between two polities |
+| `makePeace(registry, aId, bId)` | End a war between two polities |
+| `areAtWar(registry, aId, bId)` | Query war status |
+
+#### Technology diffusion (`src/tech-diffusion.ts`)
+
+| Export | Description |
+|--------|-------------|
+| `stepTechDiffusion(registry, pairs, worldSeed, tick)` | Spread technology between polities for one day |
+| `computeDiffusionPressure(source, target, pair)` | Per-pair pressure score |
+| `totalInboundPressure(registry, pairs, targetId)` | Sum of all inbound pressure toward a polity |
+| `techEraName(era)` | Human-readable era label |
+
+#### Emotional contagion (`src/emotional-contagion.ts`)
+
+| Export | Description |
+|--------|-------------|
+| `EmotionalWave` _(frozen)_ | Active emotional event propagating across polities |
+| `applyEmotionalContagion(registry, waves, worldSeed, tick)` | Apply all active waves to polity morale |
+| `stepEmotionalWaves(waves, worldSeed, tick)` | Advance wave intensities by one day |
+| `computeEmotionalSpread(source, target, wave, profile)` | Spread probability for one polity pair |
+| `triggerMilitaryRout(sourcePolityId)` | Emit a fear wave from a battlefield loss |
+| `triggerVictoryRally(sourcePolityId, leaderId?)` | Emit a hope wave from a victory |
+| `netEmotionalPressure(registry, waves, polityId)` | Net morale pressure on a polity |
+
 ---
 
 ## Tier 2 — Experimental extension API
@@ -121,9 +163,6 @@ A `CHANGELOG.md` entry will document any breaking change.
 
 | Module | Key exports |
 |--------|------------|
-| `src/polity.ts` | `createPolity`, `createPolityRegistry`, `stepPolityDay`, `declareWar`, `areAtWar`, `Polity`, `PolityRegistry`, `PolityPair` |
-| `src/tech-diffusion.ts` | `computeDiffusionPressure`, `stepTechDiffusion`, `totalInboundPressure`, `techEraName` |
-| `src/emotional-contagion.ts` | `applyEmotionalContagion`, `stepEmotionalWaves`, `computeEmotionalSpread`, `triggerMilitaryRout`, `triggerVictoryRally`, `netEmotionalPressure` |
 | `src/mythology.ts` | `compressMythsFromHistory`, `stepMythologyYear`, `aggregateFactionMythEffect`, `scaledMythEffect` |
 | `src/narrative-stress.ts` | `runNarrativeStressTest`, `scoreNarrativePush` |
 | `src/campaign.ts` | `Campaign`, `stepCampaignDay`, `advanceCampaignClock`, `serializeCampaign`, `deserializeCampaign` |

package/dist/src/emotional-contagion.d.ts

@@ -36,6 +36,9 @@ export interface EmotionalContagionProfile {
 /**
  * An active emotional event originating from one polity.
  * Decays each day; removed when intensity_Q reaches 0.
+ *
+ * @stable CE-14 — frozen from v0.2.0.  Also exported as the nominal
+ * `ContagionWave` type referenced in the Campaign Layer documentation.
  */
 export interface EmotionalWave {
     profileId: string;

package/dist/src/index.d.ts

@@ -22,3 +22,4 @@ 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

@@ -31,3 +31,4 @@ export * from "./sim/formation-combat.js"; // Phase 69: FormationUnit, TacticalE
 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/polity.d.ts

@@ -7,6 +7,9 @@ import type { FactionRegistry } from "./faction.js";
  *
  * Operates at 1 tick per simulated day.  All Q fields are fixed-point
  * fractions in [0, SCALE.Q] unless documented otherwise.
+ *
+ * @stable CE-14 — fields are frozen from v0.2.0.  New fields require a minor
+ * version bump; removals or renames require a major bump and migration guide.
  */
 export interface Polity {
     id: string;
@@ -31,7 +34,11 @@ export interface Polity {
     /** Population morale [0, SCALE.Q]. Low morale → weak military and stability decay. */
     moraleQ: Q;
 }
-/** Registry of all active polities and their geopolitical relationships. */
+/**
+ * Registry of all active polities and their geopolitical relationships.
+ *
+ * @stable CE-14 — frozen from v0.2.0.
+ */
 export interface PolityRegistry {
     polities: Map<string, Polity>;
     /**
@@ -42,7 +49,11 @@ export interface PolityRegistry {
     /** Diplomatic alliances: polityId → Set of allied polityIds. */
     alliances: Map<string, Set<string>>;
 }
-/** A trade/proximity link between two polities in the Campaign graph. */
+/**
+ * A trade/proximity link between two polities in the Campaign graph.
+ *
+ * @stable CE-14 — frozen from v0.2.0.
+ */
 export interface PolityPair {
     polityAId: string;
     polityBId: string;
@@ -260,3 +271,5 @@ export declare function areAtWar(registry: PolityRegistry, polityAId: string, po
  * Use this as `currentStanding_Q` for `resolveDiplomacy`.
  */
 export declare function polityFactionStanding(factionRegistry: FactionRegistry, polityA: Polity, polityB: Polity): Q;
+export * from "./tech-diffusion.js";
+export * from "./emotional-contagion.js";

package/dist/src/polity.js

@@ -396,3 +396,14 @@ export function polityFactionStanding(factionRegistry, polityA, polityB) {
     return factionRegistry.globalStanding
         .get(polityA.factionId)?.get(polityB.factionId) ?? STANDING_NEUTRAL;
 }
+// ── Campaign Layer barrel (CE-14) ──────────────────────────────────────────────
+//
+// The `ananke/polity` subpath re-exports the full Socio-Economic Campaign Layer
+// so that a host can import everything from one entry point:
+//
+//   import { stepPolityDay, stepTechDiffusion, applyEmotionalContagion }
+//     from "ananke/polity";
+//
+// Both modules are Tier 1 (Stable) from v0.2.0.
+export * from "./tech-diffusion.js";
+export * from "./emotional-contagion.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -81,10 +81,12 @@
     "generate-zoo": "node dist/tools/generate-zoo.js",
     "generate-map": "node dist/tools/generate-map.js",
     "world-server": "node dist/tools/world-server.js",
+    "replication-server": "node dist/tools/replication-server.js",
     "benchmark-check": "node dist/tools/benchmark-check.js",
     "benchmark-check:strict": "node dist/tools/benchmark-check.js --threshold=0.10",
     "benchmark-check:update": "node dist/tools/benchmark-check.js --update-baseline",
-    "benchmark:guide": "node dist/tools/benchmark-guide.js"
+    "benchmark:guide": "node dist/tools/benchmark-guide.js",
+    "benchmark:parallel": "node dist/tools/benchmark-parallel.js"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.3",