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

package/CHANGELOG.md

@@ -8,6 +8,80 @@ 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

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/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.8",
+  "version": "0.1.9",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -81,6 +81,7 @@
     "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",