@its-not-rocket-science/ananke 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -10,6 +10,45 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+- **Phase 71 · Cultural Generation & Evolution Framework** (`src/culture.ts`)
+  - Reverse WOAC method: derives culture bottom-up from five forces (`environment`,
+    `power`, `exchange`, `legacy`, `belief`) scored from simulation state.
+  - `generateCulture(polity, registry, myths, vassals?, biome?)` → `CultureProfile`
+    with 10 possible `CulturalValue` types, `CulturalContradiction` pairs, and
+    `CulturalCycle` practices (CYCLES audit).
+  - `stepCultureYear(profile, techPressure_Q, militaryOutcome_Q, myths, worldSeed, tick)`
+    → `CultureYearResult { profile, schism? }`: tech diffusion pulls exchange force
+    upward; military outcomes shift power; new myths update legacy/belief; conservative
+    cultures with high tension fire deterministic `SchismEvent` (reform_movement,
+    heresy, or civil_unrest).
+  - `describeCulture(profile)` → `{ summary, values, contradictions, cycles }`:
+    human-readable output for writers and game designers.
+  - Query helpers: `getCulturalValue`, `getDominantValues`, `getSignificantContradictions`.
+  - Integrates with Phase 70 (vassal count → power force), Phase 66 (myths → legacy/belief),
+    Phase 68 (BiomeContext → environment harshness), Phase 23 dialogue and Phase 24
+    faction standing via exported profile queries.
+  - 45 tests in `test/culture.test.ts`; exported via `ananke/campaign` subpath.
+
+- **Phase 70 · Stratified Political Simulation ("Vassal Web" Layer)** (`src/polity-vassals.ts`)
+  - `VassalNode` — intermediate layer between Entity and Polity with `territory_Q`,
+    `military_Q`, `treasury_cu`, and a `VassalLoyalty` block.
+  - Seven `LoyaltyType` variants with distinct `stepVassalLoyalty` dynamics:
+    `ideological` (slow, conviction-driven), `transactional` (treasury comparison),
+    `terrified` (instant collapse if liege appears weak), `honor_bound` (oath + grievance
+    spike), `opportunistic` (tracks liege/rival morale ratio), `kin_bound` (stable family
+    ties), `ideological_rival` (constant decay, cannot recover).
+  - `applyGrievanceEvent` — immutable grievance accumulation (host applies broken-promise,
+    tax-hike, kin-death events).
+  - `computeVassalContribution` — loyalty-scaled troop and treasury output; zero below
+    `CONTRIBUTION_FLOOR_Q` (q(0.20)), full above `CONTRIBUTION_FULL_Q` (q(0.50)).
+  - `computeEffectiveMilitary` — sums contributions for command-chain filtering before
+    passing force ratio to Phase 69 `resolveTacticalEngagement`.
+  - `detectRebellionRisk` — Q score (70% low-loyalty + 30% high-grievance) for AI queries.
+  - `resolveSuccessionCrisis` — deterministic heir-support rolls weighted by `military_Q`;
+    winners gain +q(0.05) loyalty, losers −q(0.08); `SuccessionResult` with `supportQ`
+    and per-vassal `loyaltyDeltas`.
+  - 40 tests in `test/polity-vassals.test.ts`; exported via `ananke/campaign` subpath.
+
 - **Option B · Tier 2 subpath exports** — eight new named import subpaths for all
   Tier 2 module groupings; deep imports remain supported as a fallback:
   - `ananke/character` → aging, sleep, disease, wound-aging, thermoregulation, nutrition,

package/dist/src/campaign-layer.d.ts

@@ -20,3 +20,5 @@ export * from "./world-generation.js";
 export * from "./inheritance.js";
 export * from "./economy.js";
 export * from "./polity.js";
+export * from "./polity-vassals.js";
+export * from "./culture.js";

package/dist/src/campaign-layer.js

@@ -20,3 +20,5 @@ export * from "./world-generation.js";
 export * from "./inheritance.js";
 export * from "./economy.js";
 export * from "./polity.js";
+export * from "./polity-vassals.js";
+export * from "./culture.js";

package/dist/src/culture.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Phase 71 — Cultural Generation & Evolution Framework
+ *
+ * Derives culture bottom-up from five environmental forces (Environment, Power,
+ * Exchange, Legacy, Belief) using the Reverse WOAC method.  Given a Polity and
+ * its world context, `generateCulture` produces a `CultureProfile` of values,
+ * internal contradictions, and recurring practices (CYCLES).  `stepCultureYear`
+ * evolves the profile over simulated time.  `describeCulture` renders it as
+ * human-readable prose for writers and game designers.
+ *
+ * No kernel import — pure data-management module, fixed-point arithmetic only.
+ */
+import type { Q } from "./units.js";
+import type { Polity, PolityRegistry } from "./polity.js";
+import type { Myth } from "./mythology.js";
+import type { BiomeContext } from "./sim/biome.js";
+import type { VassalNode } from "./polity-vassals.js";
+/** The five environmental forces that drive culture generation. */
+export type CultureForce = "environment" | "power" | "exchange" | "legacy" | "belief";
+/**
+ * CYCLES audit: the six recurring cultural practice categories.
+ * (Celebration, Yes-or-no rules, Conflict resolution, Lifecycle rites,
+ *  Exchange norms, Status markers)
+ */
+export type CycleType = "celebration" | "taboo" | "conflict_resolution" | "lifecycle" | "exchange_norm" | "status_marker";
+/** Named cultural values a society may hold. */
+export type ValueId = "honour" | "martial_virtue" | "commerce" | "fatalism" | "hospitality" | "hierarchy" | "spiritual_devotion" | "innovation" | "kin_loyalty" | "craft_mastery";
+/** Type of cultural schism that can emerge from unresolved contradictions. */
+export type SchismType = "reform_movement" | "heresy" | "civil_unrest";
+export interface CulturalValue {
+    id: ValueId;
+    /** Strength of this value in the culture [0, SCALE.Q]. */
+    strength_Q: Q;
+}
+export interface CulturalContradiction {
+    valueA: ValueId;
+    valueB: ValueId;
+    /**
+     * Tension level [0, SCALE.Q].
+     * High tension → more likely to produce internal conflict events.
+     */
+    tension_Q: Q;
+}
+export interface CulturalCycle {
+    type: CycleType;
+    name: string;
+    description: string;
+}
+export interface CultureProfile {
+    /** Unique id, typically `"culture_${polityId}"`. */
+    id: string;
+    polityId: string;
+    /** Strength of each driving force [0, SCALE.Q]. */
+    forces: Record<CultureForce, Q>;
+    /** Derived value list, sorted descending by strength. */
+    values: CulturalValue[];
+    /** Value pairs in tension; only pairs with tension > CONTRADICTION_THRESHOLD included. */
+    contradictions: CulturalContradiction[];
+    /** Recurring cultural practices that resolve the dominant tensions. */
+    cycles: CulturalCycle[];
+    /**
+     * Openness to cultural change [0, SCALE.Q].
+     * Low = conservative; high = receptive to drift.
+     */
+    driftTendency_Q: Q;
+}
+export interface CultureDescription {
+    /** One-paragraph cultural summary. */
+    summary: string;
+    /** Plain-English description of each significant value. */
+    values: string[];
+    /** What conflicts each contradiction tends to generate. */
+    contradictions: string[];
+    /** Narrative descriptions of key recurring practices. */
+    cycles: string[];
+}
+export interface SchismEvent {
+    polityId: string;
+    triggeringContradiction: CulturalContradiction;
+    type: SchismType;
+    /** How disruptive the schism is [0, SCALE.Q]. */
+    severity_Q: Q;
+}
+export interface CultureYearResult {
+    profile: CultureProfile;
+    /** Populated if a contradiction triggered a schism this year. */
+    schism?: SchismEvent;
+}
+/** Minimum value strength to be included in the profile. */
+export declare const VALUE_THRESHOLD_Q: Q;
+/** Minimum tension to qualify as a significant contradiction. */
+export declare const CONTRADICTION_THRESHOLD_Q: Q;
+/** Maximum number of values retained in a profile. */
+export declare const MAX_VALUES = 6;
+/** Maximum number of contradictions tracked. */
+export declare const MAX_CONTRADICTIONS = 4;
+/** Maximum number of CYCLES retained. */
+export declare const MAX_CYCLES = 3;
+/** Annual drift step magnitude for force evolution. */
+export declare const DRIFT_STEP_Q: Q;
+/** Annual tech pressure on the exchange force per tech-era gap. */
+export declare const TECH_DIFFUSION_PULL_Q: Q;
+/** eventSeed salt for schism rolls. */
+export declare const SCHISM_SALT: number;
+/**
+ * Generate a `CultureProfile` for a polity from its current simulation state.
+ *
+ * All five forces are derived automatically:
+ * - `environment` from `biome` physics overrides
+ * - `power` from `polity.techEra` + vassal count
+ * - `exchange` from treasury per capita
+ * - `legacy` + `belief` from myth registry
+ *
+ * @param polity    The polity to generate culture for.
+ * @param _registry PolityRegistry (reserved for future neighbour-context use).
+ * @param myths     Active myths that the polity's factions believe.
+ * @param vassals   Current vassal roster (Phase 70; pass `[]` if not available).
+ * @param biome     Optional BiomeContext affecting the environment force.
+ */
+export declare function generateCulture(polity: Polity, _registry: PolityRegistry, myths: readonly Myth[], vassals?: readonly VassalNode[], biome?: BiomeContext): CultureProfile;
+/**
+ * Evolve a culture profile by one simulated year.
+ *
+ * Three pressures are applied:
+ * 1. **Tech diffusion** (`techPressure_Q`): pulls exchange force upward when
+ *    neighbouring polities have a higher tech era (Phase 67).  Pass q(0) if
+ *    the polity is technologically isolated.
+ * 2. **Military outcome** (`militaryOutcome_Q`): q(0) = crushing defeat,
+ *    q(0.50) = neutral, q(1.0) = great victory.  Shifts martial_virtue in the
+ *    dominant values and the power force.
+ * 3. **New myths** (`myths`): re-derives the legacy and belief forces from the
+ *    current myth state.
+ *
+ * If any contradiction exceeds the schism threshold, a `SchismEvent` is
+ * returned alongside the updated profile.  The schism reduces the tension of
+ * the triggering contradiction by damping both values slightly.
+ *
+ * @param profile           Current culture profile.
+ * @param techPressure_Q    Exchange-force pull from tech-advanced neighbours.
+ * @param militaryOutcome_Q Season military result [0, SCALE.Q].
+ * @param myths             Current myth registry entries.
+ * @param worldSeed
+ * @param tick              Current campaign tick (used for schism roll).
+ */
+export declare function stepCultureYear(profile: CultureProfile, techPressure_Q: Q, militaryOutcome_Q: Q, myths: readonly Myth[], worldSeed: number, tick: number): CultureYearResult;
+/**
+ * Return the strength of a named value in the culture, or q(0) if absent.
+ */
+export declare function getCulturalValue(profile: CultureProfile, id: ValueId): Q;
+/**
+ * Return the top N values by strength (default 3).
+ */
+export declare function getDominantValues(profile: CultureProfile, n?: number): CulturalValue[];
+/**
+ * Return only contradictions above CONTRADICTION_THRESHOLD_Q,
+ * sorted by tension descending.
+ */
+export declare function getSignificantContradictions(profile: CultureProfile): CulturalContradiction[];
+/**
+ * Render a `CultureProfile` as human-readable prose and bullet lists.
+ *
+ * Suitable for game designers, writers, and procedural quest/dialogue generation.
+ */
+export declare function describeCulture(profile: CultureProfile): CultureDescription;

package/dist/src/culture.js

@@ -0,0 +1,412 @@
+/**
+ * Phase 71 — Cultural Generation & Evolution Framework
+ *
+ * Derives culture bottom-up from five environmental forces (Environment, Power,
+ * Exchange, Legacy, Belief) using the Reverse WOAC method.  Given a Polity and
+ * its world context, `generateCulture` produces a `CultureProfile` of values,
+ * internal contradictions, and recurring practices (CYCLES).  `stepCultureYear`
+ * evolves the profile over simulated time.  `describeCulture` renders it as
+ * human-readable prose for writers and game designers.
+ *
+ * No kernel import — pure data-management module, fixed-point arithmetic only.
+ */
+import { SCALE, q, clampQ, mulDiv } from "./units.js";
+import { eventSeed, hashString } from "./sim/seeds.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Minimum value strength to be included in the profile. */
+export const VALUE_THRESHOLD_Q = q(0.10);
+/** Minimum tension to qualify as a significant contradiction. */
+export const CONTRADICTION_THRESHOLD_Q = q(0.30);
+/** Maximum number of values retained in a profile. */
+export const MAX_VALUES = 6;
+/** Maximum number of contradictions tracked. */
+export const MAX_CONTRADICTIONS = 4;
+/** Maximum number of CYCLES retained. */
+export const MAX_CYCLES = 3;
+/** Annual drift step magnitude for force evolution. */
+export const DRIFT_STEP_Q = q(0.02);
+/** Annual tech pressure on the exchange force per tech-era gap. */
+export const TECH_DIFFUSION_PULL_Q = q(0.03);
+/** eventSeed salt for schism rolls. */
+export const SCHISM_SALT = 0xC17E;
+// ── Internal lookup tables ────────────────────────────────────────────────────
+/** Baseline power force (authority centralisation) by tech era. */
+const TECH_POWER = {
+    prehistoric: q(0.20),
+    ancient: q(0.40),
+    medieval: q(0.70),
+    early_modern: q(0.55),
+    industrial: q(0.45),
+    contemporary: q(0.35),
+};
+/**
+ * Known-tension pairs: [valueA, valueB, base tension when both are at SCALE.Q].
+ * Actual tension is scaled by min(strengthA, strengthB).
+ */
+const TENSION_PAIRS = [
+    ["honour", "commerce", q(0.80)], // reputation vs bargaining
+    ["hierarchy", "innovation", q(0.70)], // authority vs change
+    ["fatalism", "commerce", q(0.60)], // why strive vs strive
+    ["spiritual_devotion", "innovation", q(0.65)], // sacred vs secular
+    ["martial_virtue", "hospitality", q(0.55)], // warrior vs peace-weaver
+    ["kin_loyalty", "hierarchy", q(0.50)], // family vs state
+];
+/**
+ * Cycle assigned to each contradiction to resolve the tension.
+ * Ordered to match TENSION_PAIRS.
+ */
+const RESOLUTION_CYCLES = [
+    { type: "exchange_norm", name: "Gift Exchange Ceremony", description: "Formal gift rituals preserve social honour while enabling commerce — trade dressed as generosity." },
+    { type: "conflict_resolution", name: "Trial by Tradition", description: "New ideas must survive an ordeal judged by elders; innovation that earns approval gains legitimacy." },
+    { type: "celebration", name: "Harvest Gratitude Feast", description: "Communities celebrate what was achieved and accept loss without shame, reconciling effort with fate." },
+    { type: "taboo", name: "Sacred Knowledge Seal", description: "Certain fields of inquiry are quarantined as 'holy mystery', allowing other innovation to proceed freely." },
+    { type: "lifecycle", name: "Warrior's Hospitality", description: "Feasting enemies before and after battle transforms potential atrocity into ritual; violence is bounded by courtesy." },
+    { type: "status_marker", name: "Adoption Ceremony", description: "Political allies are formally adopted into the family, converting external obligation into kin loyalty." },
+];
+/** Cycles for dominant single values (no contradiction needed). */
+const VALUE_CYCLES = [
+    ["martial_virtue", { type: "lifecycle", name: "Warrior's Rite", description: "Coming-of-age trials test martial ability; those who pass gain full social standing." }],
+    ["spiritual_devotion", { type: "celebration", name: "Propitiation Festival", description: "Seasonal ceremonies appease the supernatural and reinforce communal bonds." }],
+    ["kin_loyalty", { type: "celebration", name: "Ancestor Feast", description: "Regular remembrance of forebears reaffirms family lineage as the core social unit." }],
+    ["commerce", { type: "exchange_norm", name: "Market Day", description: "Scheduled communal markets with enforced rules create safe space for strangers to trade." }],
+    ["hierarchy", { type: "status_marker", name: "Tribute Ceremony", description: "Regular displays of wealth offered upward reinforce the legitimacy of the ruling rank." }],
+    ["craft_mastery", { type: "lifecycle", name: "Masterwork Presentation", description: "Artisans publicly present their finest work to earn the title of master and social respect." }],
+];
+// ── Force derivation ──────────────────────────────────────────────────────────
+function deriveEnvironmentForce(biome) {
+    if (!biome)
+        return q(0.50);
+    // Vacuum/no-sound environment: most extreme
+    if (biome.soundPropagation === 0)
+        return q(0.85);
+    // High-drag (underwater): physically demanding
+    if (biome.dragMul !== undefined && biome.dragMul < q(0.50))
+        return q(0.75);
+    // Some non-default biome is set: treat as unusual environment
+    return q(0.60);
+}
+function derivePowerForce(polity, vassals) {
+    const base = TECH_POWER[polity.techEra] ?? q(0.50);
+    // Many vassals reinforce feudal hierarchy → raise power force slightly
+    const vassalBonus = Math.min(vassals.length * q(0.01), q(0.15));
+    return clampQ(base + vassalBonus, 0, SCALE.Q);
+}
+function deriveExchangeForce(polity) {
+    if (polity.population <= 0)
+        return q(0.30);
+    const wealthPerCapita = polity.treasury_cu / polity.population;
+    // 0 cu/person → q(0.20); 5 cu/person → q(0.70); normalised linearly
+    const NORM = 5;
+    return clampQ(q(0.20) + Math.round(Math.min(wealthPerCapita, NORM) * q(0.50) / NORM), 0, SCALE.Q);
+}
+function deriveLegacyForce(myths) {
+    if (myths.length === 0)
+        return { legacy_Q: q(0.10), positivity_Q: q(0.50) };
+    const sumBelief = myths.reduce((s, m) => s + m.belief_Q, 0);
+    const avgBelief = Math.round(sumBelief / myths.length);
+    const posCount = myths.filter(m => m.archetype === "hero" || m.archetype === "golden_age").length;
+    const positivity = Math.round(posCount * SCALE.Q / myths.length);
+    return {
+        legacy_Q: clampQ(avgBelief, 0, SCALE.Q),
+        positivity_Q: clampQ(positivity, 0, SCALE.Q),
+    };
+}
+function deriveBeliefForce(myths) {
+    if (myths.length === 0)
+        return q(0.30);
+    const supernaturalCount = myths.filter(m => m.archetype === "great_plague" ||
+        m.archetype === "divine_wrath").length;
+    // Each supernatural myth adds belief pressure
+    return clampQ(q(0.30) + Math.round(supernaturalCount * q(0.15)), 0, SCALE.Q);
+}
+// ── Value derivation ──────────────────────────────────────────────────────────
+function deriveValues(forces, positivity_Q) {
+    const { environment, power, exchange, legacy, belief } = forces;
+    const antiEnv = (SCALE.Q - environment);
+    const antiPower = (SCALE.Q - power);
+    const antiExchange = (SCALE.Q - exchange);
+    const antiPositive = (SCALE.Q - positivity_Q);
+    const raw = [
+        ["honour", mulDiv(power, q(0.50), SCALE.Q) + mulDiv(legacy, q(0.30), SCALE.Q)],
+        ["martial_virtue", mulDiv(environment, q(0.40), SCALE.Q) + mulDiv(power, q(0.30), SCALE.Q)],
+        ["commerce", mulDiv(exchange, q(0.60), SCALE.Q) + mulDiv(antiEnv, q(0.15), SCALE.Q)],
+        ["fatalism", mulDiv(environment, q(0.30), SCALE.Q) + mulDiv(antiPositive, q(0.40), SCALE.Q)],
+        ["hospitality", mulDiv(exchange, q(0.30), SCALE.Q) + mulDiv(antiPower, q(0.25), SCALE.Q)],
+        ["hierarchy", mulDiv(power, q(0.65), SCALE.Q)],
+        ["spiritual_devotion", mulDiv(belief, q(0.60), SCALE.Q) + mulDiv(environment, q(0.20), SCALE.Q)],
+        ["innovation", mulDiv(exchange, q(0.25), SCALE.Q) + mulDiv(antiPower, q(0.20), SCALE.Q)],
+        ["kin_loyalty", mulDiv(antiExchange, q(0.30), SCALE.Q) + mulDiv(environment, q(0.20), SCALE.Q)],
+        ["craft_mastery", mulDiv(exchange, q(0.20), SCALE.Q) + mulDiv(power, q(0.15), SCALE.Q)],
+    ];
+    return raw
+        .map(([id, strength]) => ({ id, strength_Q: clampQ(strength, 0, SCALE.Q) }))
+        .filter(v => v.strength_Q >= VALUE_THRESHOLD_Q)
+        .sort((a, b) => b.strength_Q - a.strength_Q)
+        .slice(0, MAX_VALUES);
+}
+// ── Contradiction detection ───────────────────────────────────────────────────
+function deriveContradictions(values) {
+    const strengthMap = new Map(values.map(v => [v.id, v.strength_Q]));
+    const result = [];
+    for (const [a, b, baseTension] of TENSION_PAIRS) {
+        const sa = strengthMap.get(a) ?? q(0.0);
+        const sb = strengthMap.get(b) ?? q(0.0);
+        if (sa < VALUE_THRESHOLD_Q || sb < VALUE_THRESHOLD_Q)
+            continue;
+        // Tension scales with the weaker of the two values and the base tension rate.
+        const minStrength = Math.min(sa, sb);
+        const tension = clampQ(mulDiv(minStrength, baseTension, SCALE.Q), 0, SCALE.Q);
+        if (tension >= CONTRADICTION_THRESHOLD_Q) {
+            result.push({ valueA: a, valueB: b, tension_Q: tension });
+        }
+    }
+    return result
+        .sort((a, b) => b.tension_Q - a.tension_Q)
+        .slice(0, MAX_CONTRADICTIONS);
+}
+// ── CYCLES derivation ─────────────────────────────────────────────────────────
+function deriveCycles(values, contradictions) {
+    const cycles = [];
+    const seen = new Set();
+    // First: one cycle per contradiction (tension-resolving practice)
+    for (const c of contradictions) {
+        const idx = TENSION_PAIRS.findIndex(([a, b]) => a === c.valueA && b === c.valueB);
+        if (idx >= 0 && idx < RESOLUTION_CYCLES.length) {
+            const cycle = RESOLUTION_CYCLES[idx];
+            if (!seen.has(cycle.name)) {
+                cycles.push(cycle);
+                seen.add(cycle.name);
+            }
+        }
+    }
+    // Then: dominant-value cycles to fill remaining slots
+    const dominantIds = new Set(values.slice(0, 3).map(v => v.id));
+    for (const [vid, cycle] of VALUE_CYCLES) {
+        if (cycles.length >= MAX_CYCLES)
+            break;
+        if (dominantIds.has(vid) && !seen.has(cycle.name)) {
+            cycles.push(cycle);
+            seen.add(cycle.name);
+        }
+    }
+    return cycles.slice(0, MAX_CYCLES);
+}
+// ── Drift tendency ────────────────────────────────────────────────────────────
+function deriveDriftTendency(forces) {
+    // High exchange + high innovation → open; high power + high belief → conservative.
+    const openness = mulDiv(forces.exchange, q(0.40), SCALE.Q)
+        + mulDiv(SCALE.Q - forces.power, q(0.30), SCALE.Q)
+        + mulDiv(SCALE.Q - forces.belief, q(0.20), SCALE.Q);
+    return clampQ(openness, q(0.10), q(0.90));
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Generate a `CultureProfile` for a polity from its current simulation state.
+ *
+ * All five forces are derived automatically:
+ * - `environment` from `biome` physics overrides
+ * - `power` from `polity.techEra` + vassal count
+ * - `exchange` from treasury per capita
+ * - `legacy` + `belief` from myth registry
+ *
+ * @param polity    The polity to generate culture for.
+ * @param _registry PolityRegistry (reserved for future neighbour-context use).
+ * @param myths     Active myths that the polity's factions believe.
+ * @param vassals   Current vassal roster (Phase 70; pass `[]` if not available).
+ * @param biome     Optional BiomeContext affecting the environment force.
+ */
+export function generateCulture(polity, _registry, myths, vassals = [], biome) {
+    const envForce = deriveEnvironmentForce(biome);
+    const powForce = derivePowerForce(polity, vassals);
+    const exchForce = deriveExchangeForce(polity);
+    const { legacy_Q, positivity_Q } = deriveLegacyForce(myths);
+    const beliefForce = deriveBeliefForce(myths);
+    const forces = {
+        environment: envForce,
+        power: powForce,
+        exchange: exchForce,
+        legacy: legacy_Q,
+        belief: beliefForce,
+    };
+    const values = deriveValues(forces, positivity_Q);
+    const contradictions = deriveContradictions(values);
+    const cycles = deriveCycles(values, contradictions);
+    const driftTendency = deriveDriftTendency(forces);
+    return {
+        id: `culture_${polity.id}`,
+        polityId: polity.id,
+        forces,
+        values,
+        contradictions,
+        cycles,
+        driftTendency_Q: driftTendency,
+    };
+}
+/**
+ * Evolve a culture profile by one simulated year.
+ *
+ * Three pressures are applied:
+ * 1. **Tech diffusion** (`techPressure_Q`): pulls exchange force upward when
+ *    neighbouring polities have a higher tech era (Phase 67).  Pass q(0) if
+ *    the polity is technologically isolated.
+ * 2. **Military outcome** (`militaryOutcome_Q`): q(0) = crushing defeat,
+ *    q(0.50) = neutral, q(1.0) = great victory.  Shifts martial_virtue in the
+ *    dominant values and the power force.
+ * 3. **New myths** (`myths`): re-derives the legacy and belief forces from the
+ *    current myth state.
+ *
+ * If any contradiction exceeds the schism threshold, a `SchismEvent` is
+ * returned alongside the updated profile.  The schism reduces the tension of
+ * the triggering contradiction by damping both values slightly.
+ *
+ * @param profile           Current culture profile.
+ * @param techPressure_Q    Exchange-force pull from tech-advanced neighbours.
+ * @param militaryOutcome_Q Season military result [0, SCALE.Q].
+ * @param myths             Current myth registry entries.
+ * @param worldSeed
+ * @param tick              Current campaign tick (used for schism roll).
+ */
+export function stepCultureYear(profile, techPressure_Q, militaryOutcome_Q, myths, worldSeed, tick) {
+    const polityHash = hashString(profile.polityId);
+    // ── 1. Drift forces ────────────────────────────────────────────────────────
+    const { legacy_Q, positivity_Q } = deriveLegacyForce(myths);
+    const beliefForce = deriveBeliefForce(myths);
+    // Exchange: tech-diffusion pulls upward; drift tendency amplifies openness
+    const exchDrift = mulDiv(techPressure_Q, profile.driftTendency_Q, SCALE.Q);
+    const newExchange = clampQ(profile.forces.exchange + Math.max(0, exchDrift), 0, SCALE.Q);
+    // Power: military victory reinforces authority; defeat weakens it
+    const militaryDelta = mulDiv(militaryOutcome_Q - q(0.50), DRIFT_STEP_Q * 2, SCALE.Q);
+    const newPower = clampQ(profile.forces.power + militaryDelta, 0, SCALE.Q);
+    const newForces = {
+        environment: profile.forces.environment, // geography doesn't change year-to-year
+        power: newPower,
+        exchange: newExchange,
+        legacy: legacy_Q,
+        belief: beliefForce,
+    };
+    // ── 2. Re-derive values and contradictions ─────────────────────────────────
+    let newValues = deriveValues(newForces, positivity_Q);
+    let newContradictions = deriveContradictions(newValues);
+    const newCycles = deriveCycles(newValues, newContradictions);
+    const newDrift = deriveDriftTendency(newForces);
+    // ── 3. Check for schism ────────────────────────────────────────────────────
+    let schism;
+    const topContradiction = newContradictions[0];
+    if (topContradiction !== undefined) {
+        const tensionHash = hashString(topContradiction.valueA + topContradiction.valueB);
+        const seed = eventSeed(worldSeed, tick, polityHash, tensionHash, SCHISM_SALT);
+        const roll = seed % (SCALE.Q + 1);
+        // Schism probability = tension × (1 - driftTendency) [conservative cultures crack harder]
+        const probability = mulDiv(topContradiction.tension_Q, SCALE.Q - profile.driftTendency_Q, SCALE.Q);
+        if (roll < probability) {
+            const severity = clampQ(mulDiv(topContradiction.tension_Q, SCALE.Q - profile.driftTendency_Q, SCALE.Q), 0, SCALE.Q);
+            const schismType = topContradiction.tension_Q >= q(0.75) ? "civil_unrest" :
+                topContradiction.tension_Q >= q(0.55) ? "heresy" :
+                    "reform_movement";
+            schism = {
+                polityId: profile.polityId,
+                triggeringContradiction: topContradiction,
+                type: schismType,
+                severity_Q: severity,
+            };
+            // Schism partially resolves the tension: damp both values slightly
+            const dampFactor = q(0.90);
+            newValues = newValues.map(v => v.id === topContradiction.valueA || v.id === topContradiction.valueB
+                ? { ...v, strength_Q: mulDiv(v.strength_Q, dampFactor, SCALE.Q) }
+                : v);
+            newContradictions = deriveContradictions(newValues);
+        }
+    }
+    const updatedProfile = {
+        ...profile,
+        forces: newForces,
+        values: newValues,
+        contradictions: newContradictions,
+        cycles: newCycles,
+        driftTendency_Q: newDrift,
+    };
+    return { profile: updatedProfile, ...(schism ? { schism } : {}) };
+}
+// ── Query helpers ─────────────────────────────────────────────────────────────
+/**
+ * Return the strength of a named value in the culture, or q(0) if absent.
+ */
+export function getCulturalValue(profile, id) {
+    return profile.values.find(v => v.id === id)?.strength_Q ?? q(0.0);
+}
+/**
+ * Return the top N values by strength (default 3).
+ */
+export function getDominantValues(profile, n = 3) {
+    return profile.values.slice(0, n);
+}
+/**
+ * Return only contradictions above CONTRADICTION_THRESHOLD_Q,
+ * sorted by tension descending.
+ */
+export function getSignificantContradictions(profile) {
+    return profile.contradictions.filter(c => c.tension_Q >= CONTRADICTION_THRESHOLD_Q);
+}
+// ── Human-readable description ────────────────────────────────────────────────
+const VALUE_PROSE = {
+    honour: "Social reputation and oath-keeping are central; broken promises carry severe consequences.",
+    martial_virtue: "Courage and prowess in battle are prized above most other qualities.",
+    commerce: "Trade and wealth accumulation are respected pursuits; markets thrive.",
+    fatalism: "Hardship is accepted with stoicism; fate is not resisted but endured.",
+    hospitality: "Generosity to strangers is a moral obligation and source of social prestige.",
+    hierarchy: "Rank and authority are respected; social order is seen as natural and necessary.",
+    spiritual_devotion: "Supernatural forces are central to daily life; ritual and propitiation are constant.",
+    innovation: "New ideas and methods are embraced; tradition is weighed against pragmatism.",
+    kin_loyalty: "Family obligations supersede external duties; lineage is the core identity.",
+    craft_mastery: "Skilled artisans are highly respected; excellence in craft carries social status.",
+};
+const CONTRADICTION_PROSE = {
+    "honour+commerce": "Tension between maintaining dignity and striking profitable deals; bargaining can feel like a loss of face.",
+    "hierarchy+innovation": "Authority structures resist change; new ideas must be framed as tradition to gain acceptance.",
+    "fatalism+commerce": "The belief that outcomes are preordained clashes with the drive to accumulate and improve; some see striving as futile.",
+    "spiritual_devotion+innovation": "New discoveries threaten sacred explanations; the boundary between sacred knowledge and secular inquiry is contested.",
+    "martial_virtue+hospitality": "Warrior culture and the duty to welcome strangers create awkward social choreography around guests who may become enemies.",
+    "kin_loyalty+hierarchy": "Obligation to family can conflict with loyalty to lord or state; both claim the same person's ultimate allegiance.",
+};
+/**
+ * Render a `CultureProfile` as human-readable prose and bullet lists.
+ *
+ * Suitable for game designers, writers, and procedural quest/dialogue generation.
+ */
+export function describeCulture(profile) {
+    const dominant = getDominantValues(profile, 3);
+    const topTwo = dominant.slice(0, 2).map(v => v.id.replace(/_/g, " "));
+    // Build one-paragraph summary
+    const opening = topTwo.length >= 2
+        ? `This culture places strong emphasis on ${topTwo[0]} and ${topTwo[1]}.`
+        : topTwo.length === 1
+            ? `This culture places strong emphasis on ${topTwo[0]}.`
+            : "This culture has no dominant values yet established.";
+    const envNote = profile.forces.environment >= q(0.70)
+        ? " Shaped by harsh conditions, survival demands constant collective effort."
+        : "";
+    const exchNote = profile.forces.exchange >= q(0.65)
+        ? " Trade and exchange are woven into everyday social life."
+        : profile.forces.exchange <= q(0.30)
+            ? " Material exchange is subordinate to gift-giving and reciprocal obligation."
+            : "";
+    const beliefNote = profile.forces.belief >= q(0.60)
+        ? " The supernatural is not distant — it is present in every significant decision."
+        : "";
+    const topContra = profile.contradictions[0];
+    const contradNote = topContra !== undefined
+        ? ` The culture harbours a live internal tension between ${topContra.valueA.replace(/_/g, " ")} and ${topContra.valueB.replace(/_/g, " ")}.`
+        : "";
+    const summary = opening + envNote + exchNote + beliefNote + contradNote;
+    // Value bullet list
+    const values = dominant.map(v => `${v.id.replace(/_/g, " ").replace(/\b\w/g, c => c.toUpperCase())}: ${VALUE_PROSE[v.id]}`);
+    // Contradiction descriptions
+    const contradictions = getSignificantContradictions(profile).map(c => {
+        const key = `${c.valueA}+${c.valueB}`;
+        const prose = CONTRADICTION_PROSE[key] ?? `Tension between ${c.valueA.replace(/_/g, " ")} and ${c.valueB.replace(/_/g, " ")}.`;
+        return prose;
+    });
+    // Cycle descriptions
+    const cycles = profile.cycles.map(c => `${c.name} (${c.type.replace(/_/g, " ")}): ${c.description}`);
+    return { summary, values, contradictions, cycles };
+}

package/dist/src/polity-vassals.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Phase 70 — Stratified Political Simulation ("Vassal Web" Layer)
+ *
+ * Introduces a `VassalNode` between the individual Entity and the Polity.
+ * Seven loyalty types with distinct step dynamics allow political crises
+ * (rebellions, succession disputes, noble defections) to emerge from
+ * simulation state rather than scripted events.
+ *
+ * No kernel import — pure data-management module, fixed-point arithmetic only.
+ */
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/**
+ * The basis of a vassal's loyalty to their liege.
+ *
+ * Determines how `stepVassalLoyalty` updates `loyaltyQ` each campaign tick
+ * and what events cause loyalty to spike or collapse.
+ */
+export type LoyaltyType = "ideological" | "transactional" | "terrified" | "honor_bound" | "opportunistic" | "kin_bound" | "ideological_rival";
+export interface VassalLoyalty {
+    type: LoyaltyType;
+    /** Current loyalty level [0, SCALE.Q].  q(0) = open rebellion; q(1) = unconditional. */
+    loyaltyQ: Q;
+    /**
+     * Accumulated grievances [0, SCALE.Q].
+     * Drains loyalty each tick; applied by `applyGrievanceEvent` or set directly by the host.
+     */
+    grievance_Q: Q;
+}
+export interface VassalNode {
+    /** Unique identifier, e.g. "house_harlow", "guild_weavers". */
+    id: string;
+    /** The liege polity this vassal owes service to. */
+    polityId: string;
+    /** Fractional share of polity territory controlled [0, SCALE.Q]. */
+    territory_Q: Q;
+    /**
+     * Fractional share of polity military strength contracted from this vassal
+     * when loyalty is full [0, SCALE.Q].
+     */
+    military_Q: Q;
+    /** Vassal's own treasury reserves in cost-units (independent of polity). */
+    treasury_cu: number;
+    loyalty: VassalLoyalty;
+}
+export interface VassalContribution {
+    /** Actual troop fraction provided this tick (after loyalty scaling). */
+    troops_Q: Q;
+    /** Actual treasury contribution in cost-units this tick (after loyalty scaling). */
+    treasury_cu: number;
+}
+export interface SuccessionResult {
+    /** The heir identifier that was evaluated. */
+    heirId: string;
+    /** True if the heir secured majority military support; false = contested succession. */
+    successful: boolean;
+    /** Weighted military support fraction for the heir [0, SCALE.Q]. */
+    supportQ: Q;
+    /**
+     * Loyalty delta for each vassal this tick (id → delta Q, can be negative).
+     * Supporters of the winning side gain loyalty; supporters of the losing side lose it.
+     */
+    loyaltyDeltas: Map<string, Q>;
+}
+/** Natural grievance decay per tick for most loyalty types. */
+export declare const GRIEVANCE_DECAY_Q: Q;
+/** Slower natural decay for honor_bound — oaths and grudges linger. */
+export declare const GRIEVANCE_DECAY_HONOR_Q: Q;
+/** Hard loyalty ceiling for terrified vassals (fear ≠ devotion). */
+export declare const TERRIFIED_MAX_LOYALTY_Q: Q;
+/** Loyalty target kin_bound vassals gravitate toward in the absence of grievance. */
+export declare const KIN_BOUND_BASE_Q: Q;
+/** Constant loyalty decay per tick for ideological_rival — undermining is ceaseless. */
+export declare const RIVAL_DECAY_Q: Q;
+/** Below this loyalty Q, contribution drops to zero (passive defiance). */
+export declare const CONTRIBUTION_FLOOR_Q: Q;
+/** At or above this loyalty Q, full contribution is provided. */
+export declare const CONTRIBUTION_FULL_Q: Q;
+/**
+ * Treasury difference (in cost-units) that shifts transactional loyalty by q(0.40).
+ * A liege with 50 000 cu more than the richest rival earns maximum loyalty advantage.
+ */
+export declare const TRANSACTIONAL_TREASURY_NORM = 50000;
+/** eventSeed salt for succession crisis rolls. */
+export declare const SUCCESSION_SALT: number;
+/**
+ * Apply a grievance event to a vassal and return the updated node.
+ * Typical events: broken promise, tax hike, kin killed in service, territory seized.
+ *
+ * @param delta_Q  Grievance increment [0, SCALE.Q]; positive = more aggrieved.
+ */
+export declare function applyGrievanceEvent(node: VassalNode, delta_Q: Q): VassalNode;
+/**
+ * Advance a vassal's loyalty state by one campaign tick.
+ *
+ * Loyalty dynamics are determined entirely by the vassal's `LoyaltyType`.
+ * Returns a new `VassalNode` — the input is never mutated.
+ *
+ * @param node      Current vassal state.
+ * @param liege     The liege polity.
+ * @param rivals    All other polities the vassal might consider as alternatives.
+ * @param worldSeed Deterministic RNG seed (unused directly — reserved for future variance).
+ * @param tick      Current campaign tick.
+ */
+export declare function stepVassalLoyalty(node: VassalNode, liege: Polity, rivals: readonly Polity[], _worldSeed: number, _tick: number): VassalNode;
+/**
+ * Compute the actual troop and treasury contribution a vassal provides this tick.
+ *
+ * - `loyaltyQ >= CONTRIBUTION_FULL_Q` (q(0.50)): full contracted contribution.
+ * - `loyaltyQ <= CONTRIBUTION_FLOOR_Q` (q(0.20)): zero (passive defiance).
+ * - Between floor and full: linear interpolation.
+ */
+export declare function computeVassalContribution(node: VassalNode): VassalContribution;
+/**
+ * Aggregate the effective military strength a polity can actually field,
+ * accounting for disloyal vassals.
+ *
+ * Pass this value as the force multiplier to `resolveTacticalEngagement` (Phase 69)
+ * instead of the polity's nominal `militaryStrength_Q`.
+ *
+ * ```typescript
+ * const effective = computeEffectiveMilitary(vassals);
+ * // scale polity's military by effective fraction
+ * const scaledForce = mulDiv(polity.militaryStrength_Q, effective, SCALE.Q);
+ * ```
+ */
+export declare function computeEffectiveMilitary(vassals: readonly VassalNode[]): Q;
+/**
+ * Compute the rebellion risk for a vassal [0, SCALE.Q].
+ *
+ * Risk = 70 % from low loyalty + 30 % from high grievance.
+ * Use as an AI query or host-side event trigger threshold.
+ */
+export declare function detectRebellionRisk(node: VassalNode): Q;
+/**
+ * Resolve a succession crisis: determine whether the intended heir secures
+ * enough vassal support to rule unchallenged.
+ *
+ * Each vassal "votes" based on their loyalty type, current loyalty level,
+ * and a deterministic roll from `eventSeed`.  The vote is weighted by
+ * `military_Q` so powerful nobles matter more.
+ *
+ * On success:  supporters gain +q(0.05) loyalty; opponents lose −q(0.08).
+ * On failure:  deltas are inverted (the pretender's faction benefits).
+ *
+ * @param polity    The polity undergoing succession.
+ * @param vassals   Current vassal roster.
+ * @param heirId    Identifier of the intended heir.
+ * @param worldSeed
+ * @param tick
+ */
+export declare function resolveSuccessionCrisis(polity: Polity, vassals: readonly VassalNode[], heirId: string, worldSeed: number, tick: number): SuccessionResult;

package/dist/src/polity-vassals.js

@@ -0,0 +1,289 @@
+/**
+ * Phase 70 — Stratified Political Simulation ("Vassal Web" Layer)
+ *
+ * Introduces a `VassalNode` between the individual Entity and the Polity.
+ * Seven loyalty types with distinct step dynamics allow political crises
+ * (rebellions, succession disputes, noble defections) to emerge from
+ * simulation state rather than scripted events.
+ *
+ * No kernel import — pure data-management module, fixed-point arithmetic only.
+ */
+import { SCALE, q, clampQ, mulDiv } from "./units.js";
+import { eventSeed, hashString } from "./sim/seeds.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Natural grievance decay per tick for most loyalty types. */
+export const GRIEVANCE_DECAY_Q = q(0.010);
+/** Slower natural decay for honor_bound — oaths and grudges linger. */
+export const GRIEVANCE_DECAY_HONOR_Q = q(0.004);
+/** Hard loyalty ceiling for terrified vassals (fear ≠ devotion). */
+export const TERRIFIED_MAX_LOYALTY_Q = q(0.70);
+/** Loyalty target kin_bound vassals gravitate toward in the absence of grievance. */
+export const KIN_BOUND_BASE_Q = q(0.85);
+/** Constant loyalty decay per tick for ideological_rival — undermining is ceaseless. */
+export const RIVAL_DECAY_Q = q(0.005);
+/** Below this loyalty Q, contribution drops to zero (passive defiance). */
+export const CONTRIBUTION_FLOOR_Q = q(0.20);
+/** At or above this loyalty Q, full contribution is provided. */
+export const CONTRIBUTION_FULL_Q = q(0.50);
+/**
+ * Treasury difference (in cost-units) that shifts transactional loyalty by q(0.40).
+ * A liege with 50 000 cu more than the richest rival earns maximum loyalty advantage.
+ */
+export const TRANSACTIONAL_TREASURY_NORM = 50_000;
+/** eventSeed salt for succession crisis rolls. */
+export const SUCCESSION_SALT = 0x5ECC;
+// ── Grievance events ──────────────────────────────────────────────────────────
+/**
+ * Apply a grievance event to a vassal and return the updated node.
+ * Typical events: broken promise, tax hike, kin killed in service, territory seized.
+ *
+ * @param delta_Q  Grievance increment [0, SCALE.Q]; positive = more aggrieved.
+ */
+export function applyGrievanceEvent(node, delta_Q) {
+    return {
+        ...node,
+        loyalty: {
+            ...node.loyalty,
+            grievance_Q: clampQ(node.loyalty.grievance_Q + delta_Q, 0, SCALE.Q),
+        },
+    };
+}
+// ── Loyalty step ──────────────────────────────────────────────────────────────
+/**
+ * Advance a vassal's loyalty state by one campaign tick.
+ *
+ * Loyalty dynamics are determined entirely by the vassal's `LoyaltyType`.
+ * Returns a new `VassalNode` — the input is never mutated.
+ *
+ * @param node      Current vassal state.
+ * @param liege     The liege polity.
+ * @param rivals    All other polities the vassal might consider as alternatives.
+ * @param worldSeed Deterministic RNG seed (unused directly — reserved for future variance).
+ * @param tick      Current campaign tick.
+ */
+export function stepVassalLoyalty(node, liege, rivals, _worldSeed, _tick) {
+    const { loyalty } = node;
+    const { type, loyaltyQ, grievance_Q } = loyalty;
+    // ── Step 1: decay grievance naturally ─────────────────────────────────────
+    const decayRate = type === "honor_bound" ? GRIEVANCE_DECAY_HONOR_Q : GRIEVANCE_DECAY_Q;
+    const newGrievance = clampQ(grievance_Q - decayRate, 0, SCALE.Q);
+    // ── Step 2: compute loyalty delta by type ─────────────────────────────────
+    let deltaNum = 0;
+    switch (type) {
+        case "ideological": {
+            // Slow ideological drift: grievance has minimal effect; passive recovery when content.
+            if (newGrievance > q(0.30)) {
+                deltaNum = -mulDiv(newGrievance, q(0.08), SCALE.Q);
+            }
+            else {
+                // Gentle recovery toward conviction
+                deltaNum = loyaltyQ < SCALE.Q ? q(0.003) : 0;
+            }
+            break;
+        }
+        case "transactional": {
+            // Target loyalty tracks how much richer the liege is than the best-paying rival.
+            const maxRivalTreasury = rivals.reduce((best, r) => Math.max(best, r.treasury_cu), 0);
+            const diff = Math.max(-TRANSACTIONAL_TREASURY_NORM, Math.min(TRANSACTIONAL_TREASURY_NORM, liege.treasury_cu - maxRivalTreasury));
+            const targetQ = clampQ(q(0.50) + Math.round(diff * q(0.40) / TRANSACTIONAL_TREASURY_NORM), 0, SCALE.Q);
+            // Move 5 %/tick toward target; grievance also bleeds loyalty.
+            deltaNum = mulDiv(targetQ - loyaltyQ, q(0.05), SCALE.Q);
+            deltaNum -= mulDiv(newGrievance, q(0.20), SCALE.Q);
+            break;
+        }
+        case "terrified": {
+            // Instant collapse if the liege is no stronger than the vassal.
+            if (liege.militaryStrength_Q <= node.military_Q) {
+                return {
+                    ...node,
+                    loyalty: { type, loyaltyQ: q(0.0), grievance_Q: newGrievance },
+                };
+            }
+            // Slow recovery toward the terrified ceiling; grievance undermines it.
+            deltaNum = mulDiv(TERRIFIED_MAX_LOYALTY_Q - loyaltyQ, q(0.03), SCALE.Q);
+            deltaNum -= mulDiv(newGrievance, q(0.25), SCALE.Q);
+            break;
+        }
+        case "honor_bound": {
+            // Heavy grievance causes sharp loyalty drain; without it, loyalty recovers.
+            if (grievance_Q > q(0.40)) {
+                deltaNum = -mulDiv(grievance_Q, q(0.30), SCALE.Q);
+            }
+            else {
+                deltaNum = loyaltyQ < q(0.90) ? q(0.008) : 0;
+                deltaNum -= mulDiv(newGrievance, q(0.10), SCALE.Q);
+            }
+            break;
+        }
+        case "opportunistic": {
+            // Target loyalty = liege.moraleQ: stays loyal when the liege is thriving,
+            // drifts away when the liege looks weak compared to rivals.
+            // Rivals pull target down proportionally if any of them out-morale the liege.
+            let maxRivalMorale = 0;
+            for (const r of rivals)
+                if (r.moraleQ > maxRivalMorale)
+                    maxRivalMorale = r.moraleQ;
+            // If a rival outperforms the liege, drag the target below liege.moraleQ.
+            const relativeQ = maxRivalMorale > liege.moraleQ
+                ? clampQ(mulDiv(liege.moraleQ, SCALE.Q, maxRivalMorale), 0, SCALE.Q)
+                : liege.moraleQ;
+            deltaNum = mulDiv(relativeQ - loyaltyQ, q(0.08), SCALE.Q);
+            deltaNum -= mulDiv(newGrievance, q(0.15), SCALE.Q);
+            break;
+        }
+        case "kin_bound": {
+            // Very stable; slow recovery; grievance has half the normal weight.
+            deltaNum = loyaltyQ < KIN_BOUND_BASE_Q ? q(0.01) : 0;
+            deltaNum -= mulDiv(newGrievance, q(0.10), SCALE.Q);
+            break;
+        }
+        case "ideological_rival": {
+            // Constant, inexorable decay — no incentive can reverse it.
+            deltaNum = -RIVAL_DECAY_Q;
+            break;
+        }
+    }
+    const rawLoyalty = clampQ(loyaltyQ + deltaNum, 0, SCALE.Q);
+    const newLoyalty = type === "terrified"
+        ? clampQ(rawLoyalty, 0, TERRIFIED_MAX_LOYALTY_Q)
+        : rawLoyalty;
+    return {
+        ...node,
+        loyalty: { type, loyaltyQ: newLoyalty, grievance_Q: newGrievance },
+    };
+}
+// ── Contribution ──────────────────────────────────────────────────────────────
+/**
+ * Compute the actual troop and treasury contribution a vassal provides this tick.
+ *
+ * - `loyaltyQ >= CONTRIBUTION_FULL_Q` (q(0.50)): full contracted contribution.
+ * - `loyaltyQ <= CONTRIBUTION_FLOOR_Q` (q(0.20)): zero (passive defiance).
+ * - Between floor and full: linear interpolation.
+ */
+export function computeVassalContribution(node) {
+    const { loyaltyQ } = node.loyalty;
+    const range = CONTRIBUTION_FULL_Q - CONTRIBUTION_FLOOR_Q; // q(0.30)
+    let factor;
+    if (loyaltyQ >= CONTRIBUTION_FULL_Q) {
+        factor = SCALE.Q;
+    }
+    else if (loyaltyQ <= CONTRIBUTION_FLOOR_Q) {
+        factor = 0;
+    }
+    else {
+        factor = Math.round((loyaltyQ - CONTRIBUTION_FLOOR_Q) * SCALE.Q / range);
+    }
+    return {
+        troops_Q: mulDiv(node.military_Q, factor, SCALE.Q),
+        treasury_cu: Math.round(node.treasury_cu * factor / SCALE.Q),
+    };
+}
+/**
+ * Aggregate the effective military strength a polity can actually field,
+ * accounting for disloyal vassals.
+ *
+ * Pass this value as the force multiplier to `resolveTacticalEngagement` (Phase 69)
+ * instead of the polity's nominal `militaryStrength_Q`.
+ *
+ * ```typescript
+ * const effective = computeEffectiveMilitary(vassals);
+ * // scale polity's military by effective fraction
+ * const scaledForce = mulDiv(polity.militaryStrength_Q, effective, SCALE.Q);
+ * ```
+ */
+export function computeEffectiveMilitary(vassals) {
+    return clampQ(vassals.reduce((sum, v) => sum + computeVassalContribution(v).troops_Q, 0), 0, SCALE.Q);
+}
+// ── Rebellion risk ────────────────────────────────────────────────────────────
+/**
+ * Compute the rebellion risk for a vassal [0, SCALE.Q].
+ *
+ * Risk = 70 % from low loyalty + 30 % from high grievance.
+ * Use as an AI query or host-side event trigger threshold.
+ */
+export function detectRebellionRisk(node) {
+    const { loyaltyQ, grievance_Q } = node.loyalty;
+    const loyaltyContrib = mulDiv(SCALE.Q - loyaltyQ, q(0.70), SCALE.Q);
+    const grievanceContrib = mulDiv(grievance_Q, q(0.30), SCALE.Q);
+    return clampQ(loyaltyContrib + grievanceContrib, 0, SCALE.Q);
+}
+// ── Succession crisis ─────────────────────────────────────────────────────────
+/**
+ * Resolve a succession crisis: determine whether the intended heir secures
+ * enough vassal support to rule unchallenged.
+ *
+ * Each vassal "votes" based on their loyalty type, current loyalty level,
+ * and a deterministic roll from `eventSeed`.  The vote is weighted by
+ * `military_Q` so powerful nobles matter more.
+ *
+ * On success:  supporters gain +q(0.05) loyalty; opponents lose −q(0.08).
+ * On failure:  deltas are inverted (the pretender's faction benefits).
+ *
+ * @param polity    The polity undergoing succession.
+ * @param vassals   Current vassal roster.
+ * @param heirId    Identifier of the intended heir.
+ * @param worldSeed
+ * @param tick
+ */
+export function resolveSuccessionCrisis(polity, vassals, heirId, worldSeed, tick) {
+    const polityHash = hashString(polity.id);
+    const heirHash = hashString(heirId);
+    let supportMilitary = 0;
+    let totalMilitary = 0;
+    const supportsHeir = new Map();
+    for (const vassal of vassals) {
+        const vassalHash = hashString(vassal.id);
+        const seed = eventSeed(worldSeed, tick, vassalHash, heirHash, (polityHash + SUCCESSION_SALT) & 0x7fff);
+        const roll = seed % (SCALE.Q + 1); // 0 .. SCALE.Q
+        // Support threshold: vassal supports heir if roll < threshold
+        let threshold;
+        switch (vassal.loyalty.type) {
+            case "ideological":
+                // Ideologically committed to the current regime → likely backs the heir.
+                threshold = q(0.70);
+                break;
+            case "transactional":
+                // Support proportional to current loyalty (loyalty ≈ economic satisfaction).
+                threshold = vassal.loyalty.loyaltyQ;
+                break;
+            case "terrified":
+                // Terrified vassals back whoever they think will win; proxy: loyalty.
+                threshold = vassal.loyalty.loyaltyQ;
+                break;
+            case "honor_bound":
+                // Oath-bound: strong support unless grievance has eroded trust.
+                threshold = vassal.loyalty.grievance_Q > q(0.60) ? q(0.25) : q(0.80);
+                break;
+            case "opportunistic":
+                // Genuinely uncertain — 50/50 until the outcome is clear.
+                threshold = q(0.50);
+                break;
+            case "kin_bound":
+                // Family ties: strongly backs the heir.
+                threshold = clampQ(vassal.loyalty.loyaltyQ + q(0.10), 0, SCALE.Q);
+                break;
+            case "ideological_rival":
+                // Almost never supports the heir — opposition is their purpose.
+                threshold = q(0.10);
+                break;
+        }
+        const backs = roll < threshold;
+        supportsHeir.set(vassal.id, backs);
+        totalMilitary += vassal.military_Q;
+        if (backs)
+            supportMilitary += vassal.military_Q;
+    }
+    const supportQ = totalMilitary > 0
+        ? clampQ(Math.round(supportMilitary * SCALE.Q / totalMilitary), 0, SCALE.Q)
+        : q(0.0);
+    const successful = supportQ > q(0.50);
+    const loyaltyDeltas = new Map();
+    for (const vassal of vassals) {
+        const backed = supportsHeir.get(vassal.id) ?? false;
+        // Winners gain loyalty; losers lose it (winning/losing is relative to outcome).
+        const backedHeir = backed;
+        const onWinningSide = successful ? backedHeir : !backedHeir;
+        loyaltyDeltas.set(vassal.id, (onWinningSide ? q(0.05) : -q(0.08)));
+    }
+    return { heirId, successful, supportQ, loyaltyDeltas };
+}

package/package.json

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