@its-not-rocket-science/ananke 0.1.34 → 0.1.36

package/CHANGELOG.md

@@ -6,6 +6,40 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.36] — 2026-03-26
+
+### Added
+
+- **Phase 91 · Technology Research** (`src/research.ts`)
+  - `ResearchState { polityId, progress }` — per-polity accumulator stored externally by the host.
+  - `RESEARCH_POINTS_REQUIRED: Record<number, number>` — numeric TechEra keys; Prehistoric 2 k → FarFuture 5 M; DeepSpace absent (no advancement).
+  - `computeDailyResearchPoints(polity, bonusPoints?)` → integer points/day: `baseUnits = max(1, floor(pop / RESEARCH_POP_DIVISOR=5000))`; `stabilityFactor ∈ [5000, 10000]`; `max(1, round(baseUnits × stabilityFactor / SCALE.Q)) + bonusPoints`.
+  - `stepResearch(polity, state, elapsedDays, bonusPoints?)` → `ResearchStepResult`: accumulates `daily × elapsedDays`; on threshold: increments `polity.techEra`, calls `deriveMilitaryStrength`, carries surplus; no-op at DeepSpace.
+  - `investInResearch(polity, state, amount)` — drains treasury at `RESEARCH_COST_PER_POINT = 10` cu/point; capped at available treasury; returns points added.
+  - `computeKnowledgeDiffusion(sourcePolity, targetPolity, contactIntensity_Q)` → bonus points/day: fires when `source.techEra > target.techEra`; `sourceDaily × eraDiff × KNOWLEDGE_DIFFUSION_RATE_Q(q(0.10)) × contactIntensity / SCALE.Q²`.
+  - `computeResearchProgress_Q(polity, state)` → Q [0, SCALE.Q]: fraction toward next era; SCALE.Q at DeepSpace.
+  - `estimateDaysToNextEra(polity, state, bonusPoints?)` → ceiling days; Infinity at DeepSpace or zero rate.
+  - Added `./research` subpath export to `package.json`.
+  - 57 new tests; 4,779 total. Coverage maintained above all thresholds.
+
+---
+
+## [0.1.35] — 2026-03-26
+
+### Added
+
+- **Phase 90 · Civil Unrest & Rebellion** (`src/unrest.ts`)
+  - `UnrestFactors { faminePressure_Q?, epidemicPressure_Q?, heresyRisk_Q?, weakestBond_Q? }` — optional pressure inputs from Phases 85/87/88/79.
+  - `computeUnrestLevel(polity, factors?)` → Q: weighted composite of morale deficit (×q(0.30)), stability deficit (×q(0.25)), famine (×q(0.20)), epidemic (×q(0.10)), heresy (×q(0.10)), feudal bond deficit (×q(0.05)).
+  - `UNREST_ACTION_THRESHOLD_Q = q(0.30)` — excess above this drains morale/stability.
+  - `REBELLION_THRESHOLD_Q = q(0.65)` — above this `rebellionRisk` flag is set.
+  - `stepUnrest(polity, unrestLevel_Q, elapsedDays)` → `UnrestStepResult`: drains morale at `excess × UNREST_MORALE_DRAIN_Q = q(0.005)` per day, stability at `q(0.003)` per day; mutates polity in place; floor at 0.
+  - `resolveRebellion(polity, worldSeed, tick)` → `RebellionResult`: deterministic via `eventSeed`; outcomes `"quelled" | "uprising" | "civil_war"` weighted by polity `militaryStrength_Q` vs. unrest roll; each outcome applies morale/stability penalties and treasury raid (`REBELLION_TREASURY_RAID_Q = q(0.15)`; civil war = 2×).
+  - Added `./unrest` subpath export to `package.json`.
+  - 35 new tests; 4,722 total. Coverage maintained above all thresholds.
+
+---
+
 ## [0.1.34] — 2026-03-26
 
 ### Added

package/dist/src/research.d.ts

@@ -0,0 +1,103 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/** Per-polity research progress. Store one externally per polity. */
+export interface ResearchState {
+    polityId: string;
+    /** Accumulated research points toward the next era. */
+    progress: number;
+}
+/** Result returned by `stepResearch`. */
+export interface ResearchStepResult {
+    /** Raw points added this step. */
+    pointsGained: number;
+    /** Whether the polity advanced to a new era this step. */
+    advanced: boolean;
+    /** New era if `advanced === true`, otherwise `undefined`. */
+    newEra?: number;
+}
+/**
+ * Population divisor for base daily research units.
+ * `baseUnits = floor(population / RESEARCH_POP_DIVISOR)` — minimum 1.
+ */
+export declare const RESEARCH_POP_DIVISOR = 5000;
+/**
+ * Research points required to advance FROM each TechEra to the next.
+ * Keyed by numeric TechEra value.  `Infinity` (absent) = max era, no advancement.
+ */
+export declare const RESEARCH_POINTS_REQUIRED: Record<number, number>;
+/**
+ * Treasury cost per research point when using `investInResearch`.
+ * 10 cost-units = 1 research point.
+ */
+export declare const RESEARCH_COST_PER_POINT = 10;
+/**
+ * Fraction of the source polity's daily research rate that diffuses to a
+ * less-advanced trade partner per era of difference.
+ */
+export declare const KNOWLEDGE_DIFFUSION_RATE_Q: Q;
+/** Create a fresh `ResearchState` with zero progress. */
+export declare function createResearchState(polityId: string): ResearchState;
+/**
+ * Points required to advance from the polity's current era.
+ * Returns `Infinity` at max era (no advancement possible).
+ */
+export declare function pointsRequiredForNextEra(polity: Polity): number;
+/**
+ * Compute the daily research rate for a polity [integer points/day].
+ *
+ * Formula:
+ *   baseUnits = max(1, floor(population / RESEARCH_POP_DIVISOR))
+ *   stabilityFactor = SCALE.Q/2 + mulDiv(SCALE.Q/2, stabilityQ, SCALE.Q)
+ *                   ∈ [q(0.50), q(1.00)] = [5000, 10000]
+ *   dailyPoints = max(1, round(baseUnits × stabilityFactor / SCALE.Q))
+ *
+ * @param bonusPoints  Additional flat bonus points per day (e.g., from
+ *                     knowledge diffusion or Phase-89 infrastructure).
+ */
+export declare function computeDailyResearchPoints(polity: Polity, bonusPoints?: number): number;
+/**
+ * Advance research for `elapsedDays` days.
+ *
+ * Adds `computeDailyResearchPoints(polity) × elapsedDays` to `state.progress`.
+ * When progress meets or exceeds `pointsRequiredForNextEra`:
+ * - Excess progress carries over.
+ * - `polity.techEra` is incremented.
+ * - `deriveMilitaryStrength` is refreshed.
+ *
+ * Only one era advancement occurs per call regardless of elapsed days.
+ * At DeepSpace (max era) the call is a no-op.
+ *
+ * @param bonusPoints  Flat daily bonus from knowledge diffusion or infrastructure.
+ */
+export declare function stepResearch(polity: Polity, state: ResearchState, elapsedDays: number, bonusPoints?: number): ResearchStepResult;
+/**
+ * Invest treasury into research, immediately adding points.
+ *
+ * Rate: `RESEARCH_COST_PER_POINT` cost-units = 1 point.
+ * Drains `min(amount, polity.treasury_cu)`.  No-ops if treasury is empty.
+ *
+ * Returns the actual number of research points added.
+ */
+export declare function investInResearch(polity: Polity, state: ResearchState, amount: number): number;
+/**
+ * Compute daily knowledge diffusion bonus that a source polity grants to a
+ * less-advanced target polity through trade or diplomatic contact.
+ *
+ * Diffusion fires only when `sourcePolity.techEra > targetPolity.techEra`.
+ *
+ * Formula: `round(sourceDaily × eraDiff × DIFFUSION_RATE × contactIntensity / SCALE.Q²)`
+ *
+ * @param contactIntensity_Q  Trade or diplomatic contact [0, SCALE.Q].
+ *                            Derive from Phase-83 route efficiency or Phase-80 treaty strength.
+ */
+export declare function computeKnowledgeDiffusion(sourcePolity: Polity, targetPolity: Polity, contactIntensity_Q: Q): number;
+/**
+ * Return current research progress as a Q fraction [0, SCALE.Q] toward the next era.
+ * Returns `SCALE.Q` at max era (DeepSpace).
+ */
+export declare function computeResearchProgress_Q(polity: Polity, state: ResearchState): Q;
+/**
+ * Estimate days until the next era advance at the current daily research rate.
+ * Returns `Infinity` at max era or when rate is zero.
+ */
+export declare function estimateDaysToNextEra(polity: Polity, state: ResearchState, bonusPoints?: number): number;

package/dist/src/research.js

@@ -0,0 +1,175 @@
+// src/research.ts — Phase 91: Technology Research
+//
+// Polities accumulate research points from their population and stability.
+// When accumulated points reach the era threshold the polity advances to the
+// next TechEra; treasury investment buys additional progress; contact with a
+// more advanced polity (via Phase-83 trade routes) grants knowledge diffusion.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `ResearchState` is separate from Polity; host stores one per polity.
+//   - Uses numeric TechEra values (0–8) from Phase-11 tech.ts.
+//   - `stepResearch` mutates both `state.progress` and `polity.techEra`.
+//   - All arithmetic is integer fixed-point; no floating-point accumulation.
+//
+// Integration:
+//   Phase 11 (Tech):     TechEra numeric enum — advancement increments polity.techEra.
+//   Phase 61 (Polity):   population, stabilityQ, treasury_cu are read/mutated.
+//   Phase 83 (Trade):    contactIntensity_Q drives knowledge diffusion.
+//   Phase 89 (Infra):    hosts may add infrastructure bonuses to daily rate.
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+import { deriveMilitaryStrength } from "./polity.js";
+import { TechEra } from "./sim/tech.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Population divisor for base daily research units.
+ * `baseUnits = floor(population / RESEARCH_POP_DIVISOR)` — minimum 1.
+ */
+export const RESEARCH_POP_DIVISOR = 5_000;
+/**
+ * Research points required to advance FROM each TechEra to the next.
+ * Keyed by numeric TechEra value.  `Infinity` (absent) = max era, no advancement.
+ */
+export const RESEARCH_POINTS_REQUIRED = {
+    [TechEra.Prehistoric]: 2_000,
+    [TechEra.Ancient]: 8_000,
+    [TechEra.Medieval]: 30_000,
+    [TechEra.EarlyModern]: 80_000,
+    [TechEra.Industrial]: 200_000,
+    [TechEra.Modern]: 500_000,
+    [TechEra.NearFuture]: 1_500_000,
+    [TechEra.FarFuture]: 5_000_000,
+    // TechEra.DeepSpace (8): no entry → no advancement
+};
+/**
+ * Treasury cost per research point when using `investInResearch`.
+ * 10 cost-units = 1 research point.
+ */
+export const RESEARCH_COST_PER_POINT = 10;
+/**
+ * Fraction of the source polity's daily research rate that diffuses to a
+ * less-advanced trade partner per era of difference.
+ */
+export const KNOWLEDGE_DIFFUSION_RATE_Q = q(0.10);
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Create a fresh `ResearchState` with zero progress. */
+export function createResearchState(polityId) {
+    return { polityId, progress: 0 };
+}
+// ── Rate computation ──────────────────────────────────────────────────────────
+/**
+ * Points required to advance from the polity's current era.
+ * Returns `Infinity` at max era (no advancement possible).
+ */
+export function pointsRequiredForNextEra(polity) {
+    return RESEARCH_POINTS_REQUIRED[polity.techEra] ?? Infinity;
+}
+/**
+ * Compute the daily research rate for a polity [integer points/day].
+ *
+ * Formula:
+ *   baseUnits = max(1, floor(population / RESEARCH_POP_DIVISOR))
+ *   stabilityFactor = SCALE.Q/2 + mulDiv(SCALE.Q/2, stabilityQ, SCALE.Q)
+ *                   ∈ [q(0.50), q(1.00)] = [5000, 10000]
+ *   dailyPoints = max(1, round(baseUnits × stabilityFactor / SCALE.Q))
+ *
+ * @param bonusPoints  Additional flat bonus points per day (e.g., from
+ *                     knowledge diffusion or Phase-89 infrastructure).
+ */
+export function computeDailyResearchPoints(polity, bonusPoints = 0) {
+    const baseUnits = Math.max(1, Math.floor(polity.population / RESEARCH_POP_DIVISOR));
+    const stabilityFactor = SCALE.Q / 2 + mulDiv(SCALE.Q / 2, polity.stabilityQ, SCALE.Q);
+    const base = Math.max(1, Math.round(baseUnits * stabilityFactor / SCALE.Q));
+    return base + bonusPoints;
+}
+// ── Research step ─────────────────────────────────────────────────────────────
+/**
+ * Advance research for `elapsedDays` days.
+ *
+ * Adds `computeDailyResearchPoints(polity) × elapsedDays` to `state.progress`.
+ * When progress meets or exceeds `pointsRequiredForNextEra`:
+ * - Excess progress carries over.
+ * - `polity.techEra` is incremented.
+ * - `deriveMilitaryStrength` is refreshed.
+ *
+ * Only one era advancement occurs per call regardless of elapsed days.
+ * At DeepSpace (max era) the call is a no-op.
+ *
+ * @param bonusPoints  Flat daily bonus from knowledge diffusion or infrastructure.
+ */
+export function stepResearch(polity, state, elapsedDays, bonusPoints = 0) {
+    const daily = computeDailyResearchPoints(polity, bonusPoints);
+    const gained = daily * elapsedDays;
+    state.progress += gained;
+    const required = pointsRequiredForNextEra(polity);
+    const maxEra = TechEra.DeepSpace;
+    const canAdvance = polity.techEra < maxEra && isFinite(required) && state.progress >= required;
+    if (canAdvance) {
+        state.progress -= required; // carry over surplus
+        polity.techEra = (polity.techEra + 1);
+        deriveMilitaryStrength(polity);
+        return { pointsGained: gained, advanced: true, newEra: polity.techEra };
+    }
+    return { pointsGained: gained, advanced: false };
+}
+// ── Treasury investment ───────────────────────────────────────────────────────
+/**
+ * Invest treasury into research, immediately adding points.
+ *
+ * Rate: `RESEARCH_COST_PER_POINT` cost-units = 1 point.
+ * Drains `min(amount, polity.treasury_cu)`.  No-ops if treasury is empty.
+ *
+ * Returns the actual number of research points added.
+ */
+export function investInResearch(polity, state, amount) {
+    const actual = Math.min(amount, polity.treasury_cu);
+    const points = Math.floor(actual / RESEARCH_COST_PER_POINT);
+    polity.treasury_cu -= actual;
+    state.progress += points;
+    return points;
+}
+// ── Knowledge diffusion ───────────────────────────────────────────────────────
+/**
+ * Compute daily knowledge diffusion bonus that a source polity grants to a
+ * less-advanced target polity through trade or diplomatic contact.
+ *
+ * Diffusion fires only when `sourcePolity.techEra > targetPolity.techEra`.
+ *
+ * Formula: `round(sourceDaily × eraDiff × DIFFUSION_RATE × contactIntensity / SCALE.Q²)`
+ *
+ * @param contactIntensity_Q  Trade or diplomatic contact [0, SCALE.Q].
+ *                            Derive from Phase-83 route efficiency or Phase-80 treaty strength.
+ */
+export function computeKnowledgeDiffusion(sourcePolity, targetPolity, contactIntensity_Q) {
+    if (sourcePolity.techEra <= targetPolity.techEra)
+        return 0;
+    const eraDiff = sourcePolity.techEra - targetPolity.techEra;
+    const sourceRate = computeDailyResearchPoints(sourcePolity);
+    const step1 = mulDiv(sourceRate * eraDiff, KNOWLEDGE_DIFFUSION_RATE_Q, SCALE.Q);
+    return Math.max(0, Math.round(step1 * contactIntensity_Q / SCALE.Q));
+}
+// ── Progress reporting ────────────────────────────────────────────────────────
+/**
+ * Return current research progress as a Q fraction [0, SCALE.Q] toward the next era.
+ * Returns `SCALE.Q` at max era (DeepSpace).
+ */
+export function computeResearchProgress_Q(polity, state) {
+    const required = pointsRequiredForNextEra(polity);
+    if (!isFinite(required))
+        return SCALE.Q;
+    return clampQ(Math.round(state.progress * SCALE.Q / required), 0, SCALE.Q);
+}
+/**
+ * Estimate days until the next era advance at the current daily research rate.
+ * Returns `Infinity` at max era or when rate is zero.
+ */
+export function estimateDaysToNextEra(polity, state, bonusPoints = 0) {
+    const required = pointsRequiredForNextEra(polity);
+    if (!isFinite(required))
+        return Infinity;
+    const remaining = Math.max(0, required - state.progress);
+    const daily = computeDailyResearchPoints(polity, bonusPoints);
+    if (daily <= 0)
+        return Infinity;
+    return Math.ceil(remaining / daily);
+}

package/dist/src/unrest.d.ts

@@ -0,0 +1,99 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/**
+ * Pressure signals fed into `computeUnrestLevel`.
+ * All fields are Q fractions [0, SCALE.Q]; omit any that are not applicable.
+ */
+export interface UnrestFactors {
+    /** Phase-87 famine push pressure. */
+    faminePressure_Q?: Q;
+    /** Phase-88 epidemic flight pressure. */
+    epidemicPressure_Q?: Q;
+    /** Phase-85 heresy risk. */
+    heresyRisk_Q?: Q;
+    /**
+     * Weakest feudal bond strength [0, SCALE.Q] from Phase-79.
+     * Low value → high feudal unrest contribution.
+     */
+    weakestBond_Q?: Q;
+}
+/** Possible outcomes of a rebellion resolution. */
+export type RebellionOutcome = "quelled" | "uprising" | "civil_war";
+/** Result returned by `resolveRebellion`. */
+export interface RebellionResult {
+    outcome: RebellionOutcome;
+    /** Morale penalty applied to the polity (always ≤ 0). */
+    moraleHit_Q: number;
+    /** Stability penalty applied to the polity (always ≤ 0). */
+    stabilityHit_Q: number;
+    /** Treasury plundered by rebels [cost units]. */
+    treasuryLoss: number;
+}
+/** Outcome of `stepUnrest` — the changes applied this step. */
+export interface UnrestStepResult {
+    unrestLevel_Q: Q;
+    moraleDecay_Q: number;
+    stabilityDecay_Q: number;
+    /** Whether rebellion threshold was crossed (host should call resolveRebellion). */
+    rebellionRisk: boolean;
+}
+/** Weights applied to each pressure source in `computeUnrestLevel`. */
+export declare const UNREST_MORALE_WEIGHT_Q: Q;
+export declare const UNREST_STABILITY_WEIGHT_Q: Q;
+export declare const UNREST_FAMINE_WEIGHT_Q: Q;
+export declare const UNREST_EPIDEMIC_WEIGHT_Q: Q;
+export declare const UNREST_HERESY_WEIGHT_Q: Q;
+export declare const UNREST_FEUDAL_WEIGHT_Q: Q;
+/** Unrest above this threshold → morale and stability begin draining. */
+export declare const UNREST_ACTION_THRESHOLD_Q: Q;
+/** Unrest above this threshold → rebellion risk flag raised. */
+export declare const REBELLION_THRESHOLD_Q: Q;
+/** Maximum daily morale drain from sustained unrest [Q/day]. */
+export declare const UNREST_MORALE_DRAIN_Q: Q;
+/** Maximum daily stability drain from sustained unrest [Q/day]. */
+export declare const UNREST_STABILITY_DRAIN_Q: Q;
+/** Fraction of treasury rebels plunder during an uprising or civil war. */
+export declare const REBELLION_TREASURY_RAID_Q: Q;
+/**
+ * Compute the composite unrest level [0, SCALE.Q] for a polity.
+ *
+ * Unrest is the weighted sum of:
+ * - Low morale   (`(SCALE.Q - moraleQ)    × MORALE_WEIGHT`)
+ * - Low stability (`(SCALE.Q - stabilityQ) × STABILITY_WEIGHT`)
+ * - Famine pressure  × FAMINE_WEIGHT
+ * - Epidemic pressure × EPIDEMIC_WEIGHT
+ * - Heresy risk      × HERESY_WEIGHT
+ * - Feudal deficit   × FEUDAL_WEIGHT  (`SCALE.Q − weakestBond_Q`)
+ *
+ * All inputs are optional; omitted factors contribute zero.
+ */
+export declare function computeUnrestLevel(polity: Polity, factors?: UnrestFactors): Q;
+/**
+ * Apply unrest consequences to a polity for `elapsedDays` days.
+ *
+ * When `unrestLevel_Q > UNREST_ACTION_THRESHOLD_Q`:
+ * - Drains morale at rate `(unrest − threshold) × MORALE_DRAIN_Q / SCALE.Q` per day.
+ * - Drains stability at a lower rate.
+ *
+ * Mutates `polity.moraleQ` and `polity.stabilityQ` in place.
+ * Returns the step result for host inspection.
+ */
+export declare function stepUnrest(polity: Polity, unrestLevel_Q: Q, elapsedDays: number): UnrestStepResult;
+/**
+ * Resolve a rebellion event deterministically.
+ *
+ * Outcomes:
+ * - `"quelled"`:   rebels dispersed — morale/treasury hit only.
+ * - `"uprising"`:  significant unrest — larger morale/stability hit + treasury raid.
+ * - `"civil_war"`: polity fractures — severe penalties across all stats.
+ *
+ * Outcome probability is weighted by unrest level vs. military strength:
+ * - High military strength + moderate unrest → likely `"quelled"`
+ * - Low military + high unrest → risk of `"civil_war"`
+ *
+ * Mutates polity morale, stability, and treasury.
+ *
+ * @param worldSeed  World seed for deterministic resolution.
+ * @param tick       Current simulation tick.
+ */
+export declare function resolveRebellion(polity: Polity, worldSeed: number, tick: number): RebellionResult;

package/dist/src/unrest.js

@@ -0,0 +1,147 @@
+// src/unrest.ts — Phase 90: Civil Unrest & Rebellion
+//
+// Aggregates pressure signals from existing systems into a composite unrest
+// level, drains polity morale and stability under sustained pressure, and
+// resolves rebellion events deterministically.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `computeUnrestLevel` is a pure aggregator: callers pass pre-computed
+//     pressure values from Phase-85 (heresy), Phase-87 (famine), Phase-88
+//     (epidemic), Phase-79 (weakest feudal bond), etc.
+//   - `stepUnrest` mutates polity.moraleQ and polity.stabilityQ when unrest
+//     exceeds thresholds.
+//   - `resolveRebellion` uses eventSeed for full determinism and replay safety.
+//
+// Integration:
+//   Phase 61 (Polity):     mutates moraleQ / stabilityQ; reads militaryStrength_Q.
+//   Phase 79 (Feudal):     weakestBond_Q input.
+//   Phase 85 (Faith):      heresyRisk_Q input.
+//   Phase 87 (Granary):    faminePressure_Q input from computeFamineMigrationPush.
+//   Phase 88 (Epidemic):   epidemicPressure_Q input from computeEpidemicMigrationPush.
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+import { eventSeed, hashString } from "./sim/seeds.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Weights applied to each pressure source in `computeUnrestLevel`. */
+export const UNREST_MORALE_WEIGHT_Q = q(0.30);
+export const UNREST_STABILITY_WEIGHT_Q = q(0.25);
+export const UNREST_FAMINE_WEIGHT_Q = q(0.20);
+export const UNREST_EPIDEMIC_WEIGHT_Q = q(0.10);
+export const UNREST_HERESY_WEIGHT_Q = q(0.10);
+export const UNREST_FEUDAL_WEIGHT_Q = q(0.05);
+/** Unrest above this threshold → morale and stability begin draining. */
+export const UNREST_ACTION_THRESHOLD_Q = q(0.30);
+/** Unrest above this threshold → rebellion risk flag raised. */
+export const REBELLION_THRESHOLD_Q = q(0.65);
+/** Maximum daily morale drain from sustained unrest [Q/day]. */
+export const UNREST_MORALE_DRAIN_Q = q(0.005);
+/** Maximum daily stability drain from sustained unrest [Q/day]. */
+export const UNREST_STABILITY_DRAIN_Q = q(0.003);
+/** Fraction of treasury rebels plunder during an uprising or civil war. */
+export const REBELLION_TREASURY_RAID_Q = q(0.15);
+// ── Unrest computation ────────────────────────────────────────────────────────
+/**
+ * Compute the composite unrest level [0, SCALE.Q] for a polity.
+ *
+ * Unrest is the weighted sum of:
+ * - Low morale   (`(SCALE.Q - moraleQ)    × MORALE_WEIGHT`)
+ * - Low stability (`(SCALE.Q - stabilityQ) × STABILITY_WEIGHT`)
+ * - Famine pressure  × FAMINE_WEIGHT
+ * - Epidemic pressure × EPIDEMIC_WEIGHT
+ * - Heresy risk      × HERESY_WEIGHT
+ * - Feudal deficit   × FEUDAL_WEIGHT  (`SCALE.Q − weakestBond_Q`)
+ *
+ * All inputs are optional; omitted factors contribute zero.
+ */
+export function computeUnrestLevel(polity, factors = {}) {
+    const moraleContrib = mulDiv(SCALE.Q - polity.moraleQ, UNREST_MORALE_WEIGHT_Q, SCALE.Q);
+    const stabilityContrib = mulDiv(SCALE.Q - polity.stabilityQ, UNREST_STABILITY_WEIGHT_Q, SCALE.Q);
+    const famineContrib = mulDiv(factors.faminePressure_Q ?? 0, UNREST_FAMINE_WEIGHT_Q, SCALE.Q);
+    const epidemicContrib = mulDiv(factors.epidemicPressure_Q ?? 0, UNREST_EPIDEMIC_WEIGHT_Q, SCALE.Q);
+    const heresyContrib = mulDiv(factors.heresyRisk_Q ?? 0, UNREST_HERESY_WEIGHT_Q, SCALE.Q);
+    const feudalDeficit = factors.weakestBond_Q != null
+        ? clampQ(SCALE.Q - factors.weakestBond_Q, 0, SCALE.Q)
+        : 0;
+    const feudalContrib = mulDiv(feudalDeficit, UNREST_FEUDAL_WEIGHT_Q, SCALE.Q);
+    const total = moraleContrib + stabilityContrib + famineContrib +
+        epidemicContrib + heresyContrib + feudalContrib;
+    return clampQ(total, 0, SCALE.Q);
+}
+// ── Unrest step ───────────────────────────────────────────────────────────────
+/**
+ * Apply unrest consequences to a polity for `elapsedDays` days.
+ *
+ * When `unrestLevel_Q > UNREST_ACTION_THRESHOLD_Q`:
+ * - Drains morale at rate `(unrest − threshold) × MORALE_DRAIN_Q / SCALE.Q` per day.
+ * - Drains stability at a lower rate.
+ *
+ * Mutates `polity.moraleQ` and `polity.stabilityQ` in place.
+ * Returns the step result for host inspection.
+ */
+export function stepUnrest(polity, unrestLevel_Q, elapsedDays) {
+    const excess = clampQ(unrestLevel_Q - UNREST_ACTION_THRESHOLD_Q, 0, SCALE.Q);
+    const moraleDecayPerDay = mulDiv(excess, UNREST_MORALE_DRAIN_Q, SCALE.Q);
+    const stabilityDecayPerDay = mulDiv(excess, UNREST_STABILITY_DRAIN_Q, SCALE.Q);
+    const totalMoraleDecay = Math.round(moraleDecayPerDay * elapsedDays);
+    const totalStabilityDecay = Math.round(stabilityDecayPerDay * elapsedDays);
+    polity.moraleQ = clampQ(polity.moraleQ - totalMoraleDecay, 0, SCALE.Q);
+    polity.stabilityQ = clampQ(polity.stabilityQ - totalStabilityDecay, 0, SCALE.Q);
+    return {
+        unrestLevel_Q,
+        moraleDecay_Q: totalMoraleDecay,
+        stabilityDecay_Q: totalStabilityDecay,
+        rebellionRisk: unrestLevel_Q > REBELLION_THRESHOLD_Q,
+    };
+}
+// ── Rebellion resolution ──────────────────────────────────────────────────────
+/**
+ * Resolve a rebellion event deterministically.
+ *
+ * Outcomes:
+ * - `"quelled"`:   rebels dispersed — morale/treasury hit only.
+ * - `"uprising"`:  significant unrest — larger morale/stability hit + treasury raid.
+ * - `"civil_war"`: polity fractures — severe penalties across all stats.
+ *
+ * Outcome probability is weighted by unrest level vs. military strength:
+ * - High military strength + moderate unrest → likely `"quelled"`
+ * - Low military + high unrest → risk of `"civil_war"`
+ *
+ * Mutates polity morale, stability, and treasury.
+ *
+ * @param worldSeed  World seed for deterministic resolution.
+ * @param tick       Current simulation tick.
+ */
+export function resolveRebellion(polity, worldSeed, tick) {
+    const polityHash = hashString(polity.id);
+    const seed = eventSeed(worldSeed, tick, polityHash, 0, 9001); // salt: rebellion
+    const roll = seed % SCALE.Q; // [0, SCALE.Q)
+    // Suppression capacity = military strength
+    const suppressCap = polity.militaryStrength_Q;
+    // Civil war threshold = low suppression + any roll in top quarter
+    const civilWarThresh = clampQ(SCALE.Q - suppressCap, 0, SCALE.Q);
+    const uprisingThresh = Math.round(civilWarThresh * 0.6);
+    let outcome;
+    if (roll >= civilWarThresh) {
+        outcome = "quelled";
+    }
+    else if (roll >= uprisingThresh) {
+        outcome = "uprising";
+    }
+    else {
+        outcome = "civil_war";
+    }
+    const moraleHit = outcome === "quelled" ? -q(0.05)
+        : outcome === "uprising" ? -q(0.15)
+            : -q(0.30);
+    const stabilityHit = outcome === "quelled" ? -q(0.03)
+        : outcome === "uprising" ? -q(0.10)
+            : -q(0.25);
+    const treasuryRaid = outcome === "quelled"
+        ? 0
+        : Math.floor(mulDiv(polity.treasury_cu, REBELLION_TREASURY_RAID_Q, SCALE.Q)
+            * (outcome === "civil_war" ? 2 : 1));
+    polity.moraleQ = clampQ(polity.moraleQ + moraleHit, 0, SCALE.Q);
+    polity.stabilityQ = clampQ(polity.stabilityQ + stabilityHit, 0, SCALE.Q);
+    polity.treasury_cu = Math.max(0, polity.treasury_cu - treasuryRaid);
+    return { outcome, moraleHit_Q: moraleHit, stabilityHit_Q: stabilityHit, treasuryLoss: treasuryRaid };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -122,6 +122,14 @@
     "./infrastructure": {
       "import": "./dist/src/infrastructure.js",
       "types": "./dist/src/infrastructure.d.ts"
+    },
+    "./unrest": {
+      "import": "./dist/src/unrest.js",
+      "types": "./dist/src/unrest.d.ts"
+    },
+    "./research": {
+      "import": "./dist/src/research.js",
+      "types": "./dist/src/research.d.ts"
     }
   },
   "files": [