@its-not-rocket-science/ananke 0.1.42 → 0.1.44

package/CHANGELOG.md

@@ -6,6 +6,54 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.44] — 2026-03-27
+
+### Added
+
+- **Phase 99 · Mercenaries & Hired Forces** (`src/mercenaries.ts`)
+  - `MercenaryBand { bandId, name, size, quality_Q, dailyWagePerSoldier_cu }` — immutable descriptor.
+  - `MercenaryContract { contractId, polityId, bandId, daysActive, loyalty_Q, arrears_cu }` — mutable live state stored externally.
+  - `MercenaryStepResult { wagePaid_cu, arrearsAdded_cu, loyaltyDelta, deserted }` — step outcome.
+  - `DESERT_LOYALTY_THRESHOLD_Q = q(0.25)` — below this, desertion roll fires.
+  - `LOYALTY_DECAY_PER_DAY_UNPAID = 80` — loyalty drops 0.8%/day when wages owed.
+  - `LOYALTY_GROWTH_PER_DAY_PAID = 20` — loyalty grows 0.2%/day when fully paid.
+  - `MAX_MERC_STRENGTH_BONUS_Q = q(0.30)` — caps advisory strength contribution.
+  - `computeMercenaryWage(band, elapsedDays)` — `size × dailyWage × days`.
+  - `computeMercenaryStrengthContribution(band, contract)` → Q — `size × quality × loyalty / SCALE.Q²`; capped at q(0.30); add to Phase-93 battle strength.
+  - `stepMercenaryContract(contract, band, polity, elapsedDays, worldSeed, tick)` — pays wages from treasury, accrues arrears, grows/decays loyalty, rolls desertion via `eventSeed` (deterministic).
+  - `applyVictoryLoyaltyBonus(contract)` — q(0.10) boost after campaign victory.
+  - `hireMercenaries(contractId, polityId, band, initialLoyalty_Q?)` — factory; default loyalty q(0.70).
+  - `isMercenaryReliable(contract)` / `hasMercenaryArrears(contract)` — predicates.
+  - Three sample bands: `BAND_LIGHT_CAVALRY` (400 soldiers, q(0.65), 3 cu/day), `BAND_HEAVY_INFANTRY` (600, q(0.85), 5 cu/day), `BAND_SIEGE_ENGINEERS` (200, q(0.75), 8 cu/day).
+  - Added `./mercenaries` subpath export to `package.json`.
+  - 44 new tests; 5,173 total. Coverage: 100% statements/branches/functions/lines on `mercenaries.ts`.
+
+---
+
+## [0.1.43] — 2026-03-26
+
+### Added
+
+- **Phase 98 · Plague Containment & Quarantine** (`src/containment.ts`)
+  - `QuarantinePolicy`: `"none" | "voluntary" | "enforced" | "total_lockdown"`.
+  - `ContainmentState { polityId, policy, daysActive, complianceDecay_Q }` — per-polity mutable tracker stored externally.
+  - Compliance decay models population resistance to prolonged enforcement: voluntary decays 2/day, enforced 8/day, total_lockdown 18/day (out of SCALE.Q=10000). `changeQuarantinePolicy` resets decay.
+  - `QUARANTINE_TRANSMISSION_REDUCTION_Q`: voluntary q(0.20) → enforced q(0.55) → total_lockdown q(0.85) — base transmission cut fed to Phase-88 `spreadEpidemic`.
+  - `QUARANTINE_HEALTH_BONUS_Q`: voluntary q(0.05) → total_lockdown q(0.25) — stacks with Phase-88 `deriveHealthCapacity` as additive `healthCapacity_Q` bonus.
+  - `QUARANTINE_UNREST_Q`: q(0.02) → q(0.28); grows further as compliance decays.
+  - `QUARANTINE_DAILY_COST_PER_1000`: 1 → 5 → 15 cu/1000 pop/day.
+  - `computeEffectiveTransmissionReduction(state)` — base reduction × compliance factor.
+  - `computeContainmentHealthBonus(state)` — health bonus scaled by compliance.
+  - `computeContainmentUnrest(state)` — base unrest + decay-driven bonus.
+  - `computeContainmentCost_cu(polity, state, elapsedDays)` — treasury drain.
+  - `stepContainment(state, elapsedDays)` — increments daysActive; accrues complianceDecay_Q.
+  - `applyQuarantineToContact(contactIntensity_Q, state)` — scales Phase-88 contact parameter by effective reduction; returns reduced value for `computeSpreadToPolity`.
+  - `isQuarantineActive(state)` / `isTotalLockdown(state)` — convenience predicates.
+  - Added `./containment` subpath export to `package.json`.
+  - 47 new tests; 5,129 total. Coverage: 100% statements/branches/functions/lines on `containment.ts`.
+
+---
+
 ## [0.1.42] — 2026-03-26
 
 ### Added

package/dist/src/containment.d.ts

@@ -0,0 +1,103 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/** Polity-level quarantine policy tier. */
+export type QuarantinePolicy = "none" | "voluntary" | "enforced" | "total_lockdown";
+/**
+ * Per-polity containment tracking state.
+ * Attach one per polity; store externally (e.g. `Map<string, ContainmentState>`).
+ */
+export interface ContainmentState {
+    polityId: string;
+    policy: QuarantinePolicy;
+    /** Days the current policy has been continuously active. */
+    daysActive: number;
+    /**
+     * Accumulated non-compliance [0, SCALE.Q].
+     * Rises each day a strict policy is maintained; resets when policy changes.
+     * Reduces effective transmission reduction as populations resist enforcement.
+     */
+    complianceDecay_Q: Q;
+}
+/**
+ * Base transmission reduction fraction per policy tier [0, SCALE.Q].
+ * Applied to `contactIntensity_Q` in Phase-88 spread calculations.
+ * Actual effect is scaled down by `(SCALE.Q − complianceDecay_Q) / SCALE.Q`.
+ */
+export declare const QUARANTINE_TRANSMISSION_REDUCTION_Q: Record<QuarantinePolicy, Q>;
+/**
+ * Health capacity bonus per policy tier [0, SCALE.Q].
+ * Stack with Phase-88 `deriveHealthCapacity` as additive bonus to `healthCapacity_Q`.
+ * Reflects improved isolation, triage, and care coordination.
+ */
+export declare const QUARANTINE_HEALTH_BONUS_Q: Record<QuarantinePolicy, Q>;
+/** Unrest pressure per policy tier [0, SCALE.Q]. Pass to Phase-90 `computeUnrestLevel`. */
+export declare const QUARANTINE_UNREST_Q: Record<QuarantinePolicy, Q>;
+/**
+ * Daily treasury cost per 1,000 population by policy tier [cu].
+ * Scale: `computeContainmentCost_cu = cost × population / 1000 × elapsedDays`.
+ */
+export declare const QUARANTINE_DAILY_COST_PER_1000: Record<QuarantinePolicy, number>;
+/**
+ * Compliance decay accrued per day by policy tier [out of SCALE.Q].
+ * Voluntary: minimal decay (people accept guidance).
+ * Total lockdown: fast erosion (coercion breeds resistance).
+ */
+export declare const COMPLIANCE_DECAY_PER_DAY: Record<QuarantinePolicy, number>;
+/** Create a `ContainmentState` with no active quarantine policy. */
+export declare function createContainmentState(polityId: string): ContainmentState;
+/**
+ * Change the active quarantine policy.
+ *
+ * Resets `daysActive` and `complianceDecay_Q` — a policy change resets the
+ * population's compliance posture (initial goodwill or fear of the new measure).
+ */
+export declare function changeQuarantinePolicy(state: ContainmentState, newPolicy: QuarantinePolicy): void;
+/**
+ * Compute the effective transmission reduction fraction [0, SCALE.Q],
+ * factoring in accumulated compliance decay.
+ *
+ * `effective = baseReduction × (SCALE.Q − complianceDecay_Q) / SCALE.Q`
+ */
+export declare function computeEffectiveTransmissionReduction(state: ContainmentState): Q;
+/**
+ * Compute the health capacity bonus from active quarantine [0, SCALE.Q].
+ * Add to the output of Phase-88 `deriveHealthCapacity(polity)`.
+ * The bonus also decays with compliance.
+ */
+export declare function computeContainmentHealthBonus(state: ContainmentState): Q;
+/**
+ * Compute the unrest pressure from the current quarantine policy [0, SCALE.Q].
+ *
+ * Unrest grows as compliance erodes — a partially-enforced lockdown is more
+ * resented than a fresh voluntary advisory.
+ * `unrest = baseUnrest + decayFraction × baseUnrest / SCALE.Q`
+ */
+export declare function computeContainmentUnrest(state: ContainmentState): Q;
+/**
+ * Compute the daily treasury cost of the active quarantine policy.
+ *
+ * `cost = DAILY_COST_PER_1000 × population / 1000 × elapsedDays`
+ */
+export declare function computeContainmentCost_cu(polity: Polity, state: ContainmentState, elapsedDays: number): number;
+/**
+ * Advance containment state by `elapsedDays`.
+ *
+ * - Increments `daysActive`.
+ * - Accrues `complianceDecay_Q` at `COMPLIANCE_DECAY_PER_DAY[policy]`; clamped to SCALE.Q.
+ *   Policy "none" does not decay (nothing to comply with).
+ */
+export declare function stepContainment(state: ContainmentState, elapsedDays: number): void;
+/**
+ * Scale down a Phase-88 `contactIntensity_Q` by the effective quarantine reduction.
+ *
+ * Pass the returned value to `spreadEpidemic` or `computeSpreadToPolity`:
+ * ```ts
+ * const adjContact = applyQuarantineToContact(tradeIntensity_Q, containmentState);
+ * computeSpreadToPolity(source, profile, adjContact);
+ * ```
+ */
+export declare function applyQuarantineToContact(contactIntensity_Q: Q, state: ContainmentState): Q;
+/** Return `true` when any active containment policy is in effect. */
+export declare function isQuarantineActive(state: ContainmentState): boolean;
+/** Return `true` when the current policy is the most restrictive tier. */
+export declare function isTotalLockdown(state: ContainmentState): boolean;

package/dist/src/containment.js

@@ -0,0 +1,180 @@
+// src/containment.ts — Phase 98: Plague Containment & Quarantine
+//
+// Active polity-level response to epidemic outbreaks.  Sits above Phase-88
+// (Epidemic) as the policy layer, just as Phase-97 (Famine) sits above Phase-87.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `ContainmentState` tracks active policy, days enforced, and compliance decay.
+//     Store one per polity externally (e.g. `Map<string, ContainmentState>`).
+//   - `computeEffectiveTransmissionReduction` factors in compliance decay — strict
+//     lockdowns erode over time as populations resist enforcement.
+//   - `applyQuarantineToContact` scales the `contactIntensity_Q` parameter passed
+//     to Phase-88 `spreadEpidemic` / `computeSpreadToPolity`.
+//   - `computeContainmentHealthBonus` stacks with Phase-88 `deriveHealthCapacity`
+//     as the `healthCapacity_Q` bonus passed to `stepEpidemic`.
+//   - Cost, unrest, and health bonus are all advisory; callers apply them.
+//
+// Integration:
+//   Phase 88 (Epidemic):   applyQuarantineToContact → contactIntensity_Q;
+//                          computeContainmentHealthBonus → healthCapacity_Q bonus.
+//   Phase 90 (Unrest):     computeContainmentUnrest → unrestPressure_Q.
+//   Phase 92 (Taxation):   computeContainmentCost_cu → daily treasury drain.
+//   Phase 97 (Famine):     simultaneous famine+plague compounds; host stacks pressures.
+//   Phase 96 (Climate):    plague_season epidemicGrowthBonus may prompt policy change.
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Base transmission reduction fraction per policy tier [0, SCALE.Q].
+ * Applied to `contactIntensity_Q` in Phase-88 spread calculations.
+ * Actual effect is scaled down by `(SCALE.Q − complianceDecay_Q) / SCALE.Q`.
+ */
+export const QUARANTINE_TRANSMISSION_REDUCTION_Q = {
+    none: 0,
+    voluntary: q(0.20),
+    enforced: q(0.55),
+    total_lockdown: q(0.85),
+};
+/**
+ * Health capacity bonus per policy tier [0, SCALE.Q].
+ * Stack with Phase-88 `deriveHealthCapacity` as additive bonus to `healthCapacity_Q`.
+ * Reflects improved isolation, triage, and care coordination.
+ */
+export const QUARANTINE_HEALTH_BONUS_Q = {
+    none: 0,
+    voluntary: q(0.05),
+    enforced: q(0.15),
+    total_lockdown: q(0.25),
+};
+/** Unrest pressure per policy tier [0, SCALE.Q]. Pass to Phase-90 `computeUnrestLevel`. */
+export const QUARANTINE_UNREST_Q = {
+    none: 0,
+    voluntary: q(0.02),
+    enforced: q(0.12),
+    total_lockdown: q(0.28),
+};
+/**
+ * Daily treasury cost per 1,000 population by policy tier [cu].
+ * Scale: `computeContainmentCost_cu = cost × population / 1000 × elapsedDays`.
+ */
+export const QUARANTINE_DAILY_COST_PER_1000 = {
+    none: 0,
+    voluntary: 1, // public messaging, basic clinics
+    enforced: 5, // enforcement personnel, field hospitals
+    total_lockdown: 15, // military deployment, supply distribution
+};
+/**
+ * Compliance decay accrued per day by policy tier [out of SCALE.Q].
+ * Voluntary: minimal decay (people accept guidance).
+ * Total lockdown: fast erosion (coercion breeds resistance).
+ */
+export const COMPLIANCE_DECAY_PER_DAY = {
+    none: 0,
+    voluntary: 2,
+    enforced: 8,
+    total_lockdown: 18,
+};
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Create a `ContainmentState` with no active quarantine policy. */
+export function createContainmentState(polityId) {
+    return {
+        polityId,
+        policy: "none",
+        daysActive: 0,
+        complianceDecay_Q: 0,
+    };
+}
+// ── Policy management ─────────────────────────────────────────────────────────
+/**
+ * Change the active quarantine policy.
+ *
+ * Resets `daysActive` and `complianceDecay_Q` — a policy change resets the
+ * population's compliance posture (initial goodwill or fear of the new measure).
+ */
+export function changeQuarantinePolicy(state, newPolicy) {
+    state.policy = newPolicy;
+    state.daysActive = 0;
+    state.complianceDecay_Q = 0;
+}
+// ── Effectiveness computation ─────────────────────────────────────────────────
+/**
+ * Compute the effective transmission reduction fraction [0, SCALE.Q],
+ * factoring in accumulated compliance decay.
+ *
+ * `effective = baseReduction × (SCALE.Q − complianceDecay_Q) / SCALE.Q`
+ */
+export function computeEffectiveTransmissionReduction(state) {
+    const base = QUARANTINE_TRANSMISSION_REDUCTION_Q[state.policy];
+    const compliance = SCALE.Q - state.complianceDecay_Q;
+    return clampQ(mulDiv(base, compliance, SCALE.Q), 0, SCALE.Q);
+}
+/**
+ * Compute the health capacity bonus from active quarantine [0, SCALE.Q].
+ * Add to the output of Phase-88 `deriveHealthCapacity(polity)`.
+ * The bonus also decays with compliance.
+ */
+export function computeContainmentHealthBonus(state) {
+    const base = QUARANTINE_HEALTH_BONUS_Q[state.policy];
+    const compliance = SCALE.Q - state.complianceDecay_Q;
+    return clampQ(mulDiv(base, compliance, SCALE.Q), 0, SCALE.Q);
+}
+/**
+ * Compute the unrest pressure from the current quarantine policy [0, SCALE.Q].
+ *
+ * Unrest grows as compliance erodes — a partially-enforced lockdown is more
+ * resented than a fresh voluntary advisory.
+ * `unrest = baseUnrest + decayFraction × baseUnrest / SCALE.Q`
+ */
+export function computeContainmentUnrest(state) {
+    const base = QUARANTINE_UNREST_Q[state.policy];
+    if (base === 0)
+        return 0;
+    const decayBonus = mulDiv(base, state.complianceDecay_Q, SCALE.Q);
+    return clampQ(base + decayBonus, 0, SCALE.Q);
+}
+/**
+ * Compute the daily treasury cost of the active quarantine policy.
+ *
+ * `cost = DAILY_COST_PER_1000 × population / 1000 × elapsedDays`
+ */
+export function computeContainmentCost_cu(polity, state, elapsedDays) {
+    const costPer1k = QUARANTINE_DAILY_COST_PER_1000[state.policy];
+    return Math.round(costPer1k * polity.population / 1000 * elapsedDays);
+}
+// ── State step ────────────────────────────────────────────────────────────────
+/**
+ * Advance containment state by `elapsedDays`.
+ *
+ * - Increments `daysActive`.
+ * - Accrues `complianceDecay_Q` at `COMPLIANCE_DECAY_PER_DAY[policy]`; clamped to SCALE.Q.
+ *   Policy "none" does not decay (nothing to comply with).
+ */
+export function stepContainment(state, elapsedDays) {
+    state.daysActive += elapsedDays;
+    const decay = COMPLIANCE_DECAY_PER_DAY[state.policy] * elapsedDays;
+    state.complianceDecay_Q = clampQ(state.complianceDecay_Q + decay, 0, SCALE.Q);
+}
+// ── Integration helpers ───────────────────────────────────────────────────────
+/**
+ * Scale down a Phase-88 `contactIntensity_Q` by the effective quarantine reduction.
+ *
+ * Pass the returned value to `spreadEpidemic` or `computeSpreadToPolity`:
+ * ```ts
+ * const adjContact = applyQuarantineToContact(tradeIntensity_Q, containmentState);
+ * computeSpreadToPolity(source, profile, adjContact);
+ * ```
+ */
+export function applyQuarantineToContact(contactIntensity_Q, state) {
+    const reduction = computeEffectiveTransmissionReduction(state);
+    const reduced = mulDiv(contactIntensity_Q, reduction, SCALE.Q);
+    return clampQ(contactIntensity_Q - reduced, 0, SCALE.Q);
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+/** Return `true` when any active containment policy is in effect. */
+export function isQuarantineActive(state) {
+    return state.policy !== "none";
+}
+/** Return `true` when the current policy is the most restrictive tier. */
+export function isTotalLockdown(state) {
+    return state.policy === "total_lockdown";
+}

package/dist/src/mercenaries.d.ts

@@ -0,0 +1,131 @@
+import type { Q } from "./units.js";
+import type { Polity } from "./polity.js";
+/**
+ * Immutable descriptor for a mercenary band.
+ * Create via `createMercenaryBand`; share across multiple contracts if needed.
+ */
+export interface MercenaryBand {
+    bandId: string;
+    name: string;
+    /** Number of soldiers in the band. */
+    size: number;
+    /** Combat effectiveness [0, SCALE.Q].  q(0.50) = average militia; q(0.90) = elite. */
+    quality_Q: Q;
+    /** Base daily wage per soldier in cost-units. */
+    dailyWagePerSoldier_cu: number;
+}
+/**
+ * Live contract state for one hired band.
+ * Store externally (e.g. `Map<string, MercenaryContract>`); pass to step each tick.
+ */
+export interface MercenaryContract {
+    contractId: string;
+    polityId: string;
+    bandId: string;
+    /** Days the contract has been active. */
+    daysActive: number;
+    /**
+     * Current loyalty of the band to this polity [0, SCALE.Q].
+     * Grows when paid; decays when in arrears; below DESERT_THRESHOLD → desertion risk.
+     */
+    loyalty_Q: Q;
+    /**
+     * Unpaid wages accumulated [cu].
+     * Grows when treasury is insufficient; cleared when back-paid.
+     */
+    arrears_cu: number;
+}
+/** Outcome of a single `stepMercenaryContract` call. */
+export interface MercenaryStepResult {
+    /** Amount actually paid from treasury this step. */
+    wagePaid_cu: number;
+    /** Arrears added this step (0 if fully paid). */
+    arrearsAdded_cu: number;
+    /** Loyalty change this step (negative = decay, positive = growth). */
+    loyaltyDelta: number;
+    /** Whether the band deserted this step. */
+    deserted: boolean;
+}
+/** Loyalty below this → desertion roll fires. */
+export declare const DESERT_LOYALTY_THRESHOLD_Q: Q;
+/** Loyalty decay per day when wages are in arrears [out of SCALE.Q]. */
+export declare const LOYALTY_DECAY_PER_DAY_UNPAID: number;
+/** Loyalty growth per day when wages are paid in full [out of SCALE.Q]. */
+export declare const LOYALTY_GROWTH_PER_DAY_PAID: number;
+/**
+ * Loyalty bonus on campaign victory — reward for shared triumph.
+ * Caller applies via `applyVictoryLoyaltyBonus`.
+ */
+export declare const LOYALTY_VICTORY_BONUS_Q: Q;
+/**
+ * Maximum military strength contribution from any single mercenary contract [Q].
+ * Prevents a single large band from trivially dominating a polity's army.
+ */
+export declare const MAX_MERC_STRENGTH_BONUS_Q: Q;
+/**
+ * Daily desertion probability roll threshold when loyalty is at zero [out of SCALE.Q].
+ * At loyalty = DESERT_THRESHOLD: ~25% chance/day; scales linearly to 0 at threshold.
+ */
+export declare const DESERT_ROLL_MAX: number;
+/** Create a `MercenaryBand` descriptor. */
+export declare function createMercenaryBand(bandId: string, name: string, size: number, quality_Q: Q, dailyWagePerSoldier_cu: number): MercenaryBand;
+/**
+ * Hire a mercenary band, creating a contract with initial loyalty.
+ *
+ * Does NOT deduct an advance payment — caller may pay via `computeMercenaryWage`
+ * before the first step if an upfront retainer is desired.
+ *
+ * @param initialLoyalty_Q  Starting loyalty. Defaults to q(0.70) (neutral-positive hire).
+ */
+export declare function hireMercenaries(contractId: string, polityId: string, band: MercenaryBand, initialLoyalty_Q?: Q): MercenaryContract;
+/**
+ * Compute total wages due for `elapsedDays` days.
+ *
+ * `wage = band.size × band.dailyWagePerSoldier_cu × elapsedDays`
+ */
+export declare function computeMercenaryWage(band: MercenaryBand, elapsedDays: number): number;
+/**
+ * Compute the military strength contribution of a hired band [0, SCALE.Q].
+ *
+ * Formula: `round(size × quality_Q × loyalty_Q / SCALE.Q²)`, clamped to
+ * `MAX_MERC_STRENGTH_BONUS_Q`.
+ *
+ * Add the result to Phase-93 `computeBattleStrength` output.
+ * At full quality and full loyalty: ~q(0.05) per 500 soldiers; caps at q(0.30).
+ */
+export declare function computeMercenaryStrengthContribution(band: MercenaryBand, contract: MercenaryContract): Q;
+/**
+ * Apply a loyalty bonus after a campaign victory.
+ * Clamps result to SCALE.Q.
+ */
+export declare function applyVictoryLoyaltyBonus(contract: MercenaryContract): void;
+/**
+ * Advance a mercenary contract by `elapsedDays`.
+ *
+ * Each step:
+ * 1. Compute wages due = `computeMercenaryWage(band, elapsedDays)`.
+ * 2. Pay as much as `polity.treasury_cu` allows; add remainder to `arrears_cu`.
+ * 3. If fully paid: grow loyalty, clear any arrears previously owed.
+ *    If in arrears: decay loyalty by `LOYALTY_DECAY_PER_DAY_UNPAID × elapsedDays`.
+ * 4. If `loyalty_Q < DESERT_LOYALTY_THRESHOLD_Q`: roll for desertion via `eventSeed`.
+ *    Desertion probability scales linearly from `DESERT_ROLL_MAX` at loyalty 0
+ *    to 0 at `DESERT_LOYALTY_THRESHOLD_Q`.
+ * 5. If deserted: set `loyalty_Q = 0` (signal to caller to remove contract).
+ *
+ * Mutates `polity.treasury_cu`, `contract.loyalty_Q`, `contract.arrears_cu`,
+ * and `contract.daysActive`.
+ *
+ * @param worldSeed  World-level seed for deterministic desertion roll.
+ * @param tick       Current simulation tick (day).
+ */
+export declare function stepMercenaryContract(contract: MercenaryContract, band: MercenaryBand, polity: Polity, elapsedDays: number, worldSeed: number, tick: number): MercenaryStepResult;
+/** Return `true` when the band is loyal enough to remain in service reliably. */
+export declare function isMercenaryReliable(contract: MercenaryContract): boolean;
+/** Return `true` when the contract has active arrears. */
+export declare function hasMercenaryArrears(contract: MercenaryContract): boolean;
+/** A typical 400-man light cavalry band — mobile, moderate quality. */
+export declare const BAND_LIGHT_CAVALRY: MercenaryBand;
+/** A 600-man heavy infantry cohort — expensive, high quality. */
+export declare const BAND_HEAVY_INFANTRY: MercenaryBand;
+/** A 200-man specialist siege engineers unit. */
+export declare const BAND_SIEGE_ENGINEERS: MercenaryBand;

package/dist/src/mercenaries.js

@@ -0,0 +1,187 @@
+// src/mercenaries.ts — Phase 99: Mercenaries & Hired Forces
+//
+// Professional soldiers hired from the treasury.  Mercenaries augment polity
+// armies with high-quality fighters but demand regular wages; unpaid bands
+// lose loyalty and eventually desert.
+//
+// Design:
+//   - Pure data layer — no Entity fields, no kernel changes.
+//   - `MercenaryBand` is an immutable descriptor (could represent an NPC faction
+//     or a persistent world actor).
+//   - `MercenaryContract` is the mutable live state; host stores one per hired band.
+//   - Loyalty drives both effectiveness and desertion risk.
+//   - `stepMercenaryContract` pays wages, accrues arrears, decays/grows loyalty,
+//     and rolls desertion via `eventSeed` for full determinism.
+//   - `computeMercenaryStrengthContribution` returns an advisory [0, SCALE.Q]
+//     bonus stacked on top of Phase-93 `computeBattleStrength`.
+//
+// Integration:
+//   Phase 92 (Taxation):        daily wage drains `polity.treasury_cu`.
+//   Phase 93 (Military Campaign): strength contribution stacks with battle strength.
+//   Phase 90 (Unrest):          deserted band may leave unrest pressure (caller-driven).
+//   Phase 61 (Polity):          polity.treasury_cu mutated by wage payment.
+import { eventSeed } from "./sim/seeds.js";
+import { q, SCALE, clampQ, mulDiv } from "./units.js";
+// ── Constants ─────────────────────────────────────────────────────────────────
+/** Loyalty below this → desertion roll fires. */
+export const DESERT_LOYALTY_THRESHOLD_Q = q(0.25);
+/** Loyalty decay per day when wages are in arrears [out of SCALE.Q]. */
+export const LOYALTY_DECAY_PER_DAY_UNPAID = 80; // q(0.008)/day
+/** Loyalty growth per day when wages are paid in full [out of SCALE.Q]. */
+export const LOYALTY_GROWTH_PER_DAY_PAID = 20; // q(0.002)/day
+/**
+ * Loyalty bonus on campaign victory — reward for shared triumph.
+ * Caller applies via `applyVictoryLoyaltyBonus`.
+ */
+export const LOYALTY_VICTORY_BONUS_Q = q(0.10);
+/**
+ * Maximum military strength contribution from any single mercenary contract [Q].
+ * Prevents a single large band from trivially dominating a polity's army.
+ */
+export const MAX_MERC_STRENGTH_BONUS_Q = q(0.30);
+/**
+ * Daily desertion probability roll threshold when loyalty is at zero [out of SCALE.Q].
+ * At loyalty = DESERT_THRESHOLD: ~25% chance/day; scales linearly to 0 at threshold.
+ */
+export const DESERT_ROLL_MAX = 2500; // 2500/10000 = 25% when loyalty = 0
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Create a `MercenaryBand` descriptor. */
+export function createMercenaryBand(bandId, name, size, quality_Q, dailyWagePerSoldier_cu) {
+    return {
+        bandId,
+        name,
+        size: Math.max(1, size),
+        quality_Q: clampQ(quality_Q, 0, SCALE.Q),
+        dailyWagePerSoldier_cu: Math.max(0, dailyWagePerSoldier_cu),
+    };
+}
+/**
+ * Hire a mercenary band, creating a contract with initial loyalty.
+ *
+ * Does NOT deduct an advance payment — caller may pay via `computeMercenaryWage`
+ * before the first step if an upfront retainer is desired.
+ *
+ * @param initialLoyalty_Q  Starting loyalty. Defaults to q(0.70) (neutral-positive hire).
+ */
+export function hireMercenaries(contractId, polityId, band, initialLoyalty_Q = q(0.70)) {
+    return {
+        contractId,
+        polityId,
+        bandId: band.bandId,
+        daysActive: 0,
+        loyalty_Q: clampQ(initialLoyalty_Q, 0, SCALE.Q),
+        arrears_cu: 0,
+    };
+}
+// ── Cost computation ──────────────────────────────────────────────────────────
+/**
+ * Compute total wages due for `elapsedDays` days.
+ *
+ * `wage = band.size × band.dailyWagePerSoldier_cu × elapsedDays`
+ */
+export function computeMercenaryWage(band, elapsedDays) {
+    return band.size * band.dailyWagePerSoldier_cu * elapsedDays;
+}
+// ── Strength contribution ─────────────────────────────────────────────────────
+/**
+ * Compute the military strength contribution of a hired band [0, SCALE.Q].
+ *
+ * Formula: `round(size × quality_Q × loyalty_Q / SCALE.Q²)`, clamped to
+ * `MAX_MERC_STRENGTH_BONUS_Q`.
+ *
+ * Add the result to Phase-93 `computeBattleStrength` output.
+ * At full quality and full loyalty: ~q(0.05) per 500 soldiers; caps at q(0.30).
+ */
+export function computeMercenaryStrengthContribution(band, contract) {
+    const step1 = mulDiv(band.size, band.quality_Q, SCALE.Q); // size × quality / SCALE
+    const step2 = mulDiv(step1, contract.loyalty_Q, SCALE.Q); // × loyalty / SCALE
+    return clampQ(step2, 0, MAX_MERC_STRENGTH_BONUS_Q);
+}
+// ── Loyalty management ────────────────────────────────────────────────────────
+/**
+ * Apply a loyalty bonus after a campaign victory.
+ * Clamps result to SCALE.Q.
+ */
+export function applyVictoryLoyaltyBonus(contract) {
+    contract.loyalty_Q = clampQ(contract.loyalty_Q + LOYALTY_VICTORY_BONUS_Q, 0, SCALE.Q);
+}
+// ── Contract step ─────────────────────────────────────────────────────────────
+/**
+ * Advance a mercenary contract by `elapsedDays`.
+ *
+ * Each step:
+ * 1. Compute wages due = `computeMercenaryWage(band, elapsedDays)`.
+ * 2. Pay as much as `polity.treasury_cu` allows; add remainder to `arrears_cu`.
+ * 3. If fully paid: grow loyalty, clear any arrears previously owed.
+ *    If in arrears: decay loyalty by `LOYALTY_DECAY_PER_DAY_UNPAID × elapsedDays`.
+ * 4. If `loyalty_Q < DESERT_LOYALTY_THRESHOLD_Q`: roll for desertion via `eventSeed`.
+ *    Desertion probability scales linearly from `DESERT_ROLL_MAX` at loyalty 0
+ *    to 0 at `DESERT_LOYALTY_THRESHOLD_Q`.
+ * 5. If deserted: set `loyalty_Q = 0` (signal to caller to remove contract).
+ *
+ * Mutates `polity.treasury_cu`, `contract.loyalty_Q`, `contract.arrears_cu`,
+ * and `contract.daysActive`.
+ *
+ * @param worldSeed  World-level seed for deterministic desertion roll.
+ * @param tick       Current simulation tick (day).
+ */
+export function stepMercenaryContract(contract, band, polity, elapsedDays, worldSeed, tick) {
+    contract.daysActive += elapsedDays;
+    // ── 1. Wages due ──────────────────────────────────────────────────────────
+    const wageDue = computeMercenaryWage(band, elapsedDays);
+    // ── 2. Payment ────────────────────────────────────────────────────────────
+    const totalOwed = wageDue + contract.arrears_cu;
+    const paid = Math.min(totalOwed, polity.treasury_cu);
+    polity.treasury_cu -= paid;
+    const remaining = totalOwed - paid;
+    const wagePaid_cu = Math.min(wageDue, paid);
+    const arrearsAdded = wageDue - wagePaid_cu;
+    contract.arrears_cu = remaining;
+    // ── 3. Loyalty update ─────────────────────────────────────────────────────
+    let loyaltyDelta;
+    if (remaining === 0) {
+        // Fully paid — loyalty grows
+        loyaltyDelta = LOYALTY_GROWTH_PER_DAY_PAID * elapsedDays;
+    }
+    else {
+        // In arrears — loyalty decays
+        loyaltyDelta = -(LOYALTY_DECAY_PER_DAY_UNPAID * elapsedDays);
+    }
+    contract.loyalty_Q = clampQ(contract.loyalty_Q + loyaltyDelta, 0, SCALE.Q);
+    // ── 4. Desertion check ────────────────────────────────────────────────────
+    let deserted = false;
+    if (contract.loyalty_Q < DESERT_LOYALTY_THRESHOLD_Q) {
+        // Probability scales: 0 at threshold, DESERT_ROLL_MAX at loyalty=0
+        const loyaltyFrac = contract.loyalty_Q; // 0 = worst, DESERT_THRESHOLD = boundary
+        const deserProbScale = SCALE.Q - Math.round(loyaltyFrac * SCALE.Q / DESERT_LOYALTY_THRESHOLD_Q);
+        const deserProb = Math.round(deserProbScale * DESERT_ROLL_MAX / SCALE.Q);
+        const seed = eventSeed(worldSeed, tick, 0, 0, contract.contractId.length + band.size);
+        const roll = seed % SCALE.Q;
+        if (roll < deserProb) {
+            deserted = true;
+            contract.loyalty_Q = 0;
+        }
+    }
+    return {
+        wagePaid_cu,
+        arrearsAdded_cu: arrearsAdded,
+        loyaltyDelta,
+        deserted,
+    };
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+/** Return `true` when the band is loyal enough to remain in service reliably. */
+export function isMercenaryReliable(contract) {
+    return contract.loyalty_Q >= DESERT_LOYALTY_THRESHOLD_Q;
+}
+/** Return `true` when the contract has active arrears. */
+export function hasMercenaryArrears(contract) {
+    return contract.arrears_cu > 0;
+}
+// ── Sample bands ─────────────────────────────────────────────────────────────
+/** A typical 400-man light cavalry band — mobile, moderate quality. */
+export const BAND_LIGHT_CAVALRY = createMercenaryBand("light_cavalry", "Free Riders", 400, q(0.65), 3);
+/** A 600-man heavy infantry cohort — expensive, high quality. */
+export const BAND_HEAVY_INFANTRY = createMercenaryBand("heavy_infantry", "Iron Shields", 600, q(0.85), 5);
+/** A 200-man specialist siege engineers unit. */
+export const BAND_SIEGE_ENGINEERS = createMercenaryBand("siege_engineers", "The Sappers", 200, q(0.75), 8);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -154,6 +154,14 @@
     "./famine": {
       "import": "./dist/src/famine.js",
       "types": "./dist/src/famine.d.ts"
+    },
+    "./containment": {
+      "import": "./dist/src/containment.js",
+      "types": "./dist/src/containment.d.ts"
+    },
+    "./mercenaries": {
+      "import": "./dist/src/mercenaries.js",
+      "types": "./dist/src/mercenaries.d.ts"
     }
   },
   "files": [