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

package/dist/src/battle-bridge.js

@@ -0,0 +1,126 @@
+// src/battle-bridge.ts — Campaign ↔ Combat bridge for the Persistent World Server.
+//
+// Pure functions that translate between polity-scale state and tactical combat
+// configuration, and back.  No I/O, no timers, no side effects.
+//
+// Flow:
+//   1. Polity layer detects a war (activeWars contains pair key).
+//   2. Caller invokes battleConfigFromPolities() to get a BattleConfig.
+//   3. Caller runs a tactical combat instance until one team is wiped out.
+//   4. Caller invokes polityImpactFromBattle() to get PolityImpact[] to apply.
+import { SCALE, q, clampQ } from "./units.js";
+import { TechEra } from "./sim/tech.js";
+// ── Constants ──────────────────────────────────────────────────────────────────
+/** Minimum and maximum combatants per side. */
+export const MIN_TEAM_SIZE = 2;
+export const MAX_TEAM_SIZE = 16;
+/** Battle ends after this many ticks regardless of outcome (prevents infinite loops). */
+export const DEFAULT_MAX_TICKS = 6000; // 5 min at 20 Hz
+/** Morale bonus for winning a battle (Q units). */
+export const WIN_MORALE_BONUS = q(0.08);
+/** Morale penalty for losing a battle (Q units). */
+export const LOSS_MORALE_PENALTY = q(0.12);
+/** Stability penalty per 10% casualties above 20% casualty rate. */
+export const CASUALTY_STABILITY_RATE = q(0.02);
+/** Population lost per combatant casualty (polity headcount, not Q). */
+export const POP_PER_CASUALTY = 50;
+// ── Era → Loadout mapping ──────────────────────────────────────────────────────
+/**
+ * Returns the best available weapon and armour for a given tech era.
+ * Prehistoric → club + none; Ancient → knife + leather; Medieval+ → longsword + mail/plate.
+ */
+export function techEraToLoadout(era) {
+    switch (era) {
+        case TechEra.Prehistoric:
+            return { archetype: "HUMAN_BASE", weaponId: "wpn_club", armourId: "arm_leather" };
+        case TechEra.Ancient:
+            return { archetype: "HUMAN_BASE", weaponId: "wpn_knife", armourId: "arm_leather" };
+        case TechEra.Medieval:
+            return { archetype: "HUMAN_BASE", weaponId: "wpn_longsword", armourId: "arm_mail" };
+        case TechEra.EarlyModern:
+            return { archetype: "HUMAN_BASE", weaponId: "wpn_longsword", armourId: "arm_plate" };
+        default:
+            return { archetype: "HUMAN_BASE", weaponId: "wpn_longsword", armourId: "arm_plate" };
+    }
+}
+// ── Military strength → team size ─────────────────────────────────────────────
+/**
+ * Converts a polity's military strength (Q) to a team size.
+ * q(0) → MIN_TEAM_SIZE; q(1.0) → MAX_TEAM_SIZE.  Linear interpolation.
+ */
+export function militaryStrengthToTeamSize(militaryStrength_Q) {
+    const frac = Math.max(0, Math.min(SCALE.Q, militaryStrength_Q)) / SCALE.Q;
+    const size = Math.round(MIN_TEAM_SIZE + frac * (MAX_TEAM_SIZE - MIN_TEAM_SIZE));
+    return Math.max(MIN_TEAM_SIZE, Math.min(MAX_TEAM_SIZE, size));
+}
+// ── Deterministic seed ─────────────────────────────────────────────────────────
+/**
+ * Produces a deterministic battle seed from the world seed, day, and polity ids.
+ * Ensures each polity pair on each day gets a unique, reproducible seed.
+ */
+export function battleSeed(worldSeed, day, polityAId, polityBId) {
+    const idSalt = [...(polityAId + polityBId)].reduce((acc, c) => acc + c.charCodeAt(0), 0);
+    return ((worldSeed * 1000003 + day * 6151 + idSalt) >>> 0);
+}
+// ── BattleConfig factory ───────────────────────────────────────────────────────
+/**
+ * Builds a BattleConfig for a war between two polities.
+ * Team sizes scale with militaryStrength_Q; loadouts reflect each side's tech era.
+ */
+export function battleConfigFromPolities(polityA, polityB, worldSeed, day, maxTicks = DEFAULT_MAX_TICKS) {
+    return {
+        seed: battleSeed(worldSeed, day, polityA.id, polityB.id),
+        polityAId: polityA.id,
+        polityBId: polityB.id,
+        teamASize: militaryStrengthToTeamSize(polityA.militaryStrength_Q),
+        teamBSize: militaryStrengthToTeamSize(polityB.militaryStrength_Q),
+        loadoutA: techEraToLoadout(polityA.techEra),
+        loadoutB: techEraToLoadout(polityB.techEra),
+        maxTicks,
+    };
+}
+// ── PolityImpact derivation ────────────────────────────────────────────────────
+/**
+ * Derives the per-polity state changes to apply after a battle.
+ *
+ * Win:  +WIN_MORALE_BONUS morale.
+ * Loss: −LOSS_MORALE_PENALTY morale.
+ * Draw: no morale change.
+ * Both sides: stability penalty proportional to casualties above 20%.
+ * Population: POP_PER_CASUALTY headcount lost per casualty.
+ */
+export function polityImpactFromBattle(outcome, config) {
+    const results = [];
+    const sides = [
+        { id: config.polityAId, casualties: outcome.teamACasualties, teamSize: config.teamASize, isWinner: outcome.winner === 1 },
+        { id: config.polityBId, casualties: outcome.teamBCasualties, teamSize: config.teamBSize, isWinner: outcome.winner === 2 },
+    ];
+    for (const side of sides) {
+        const isLoser = outcome.winner !== 0 && !side.isWinner;
+        const moraleDelta_Q = side.isWinner
+            ? WIN_MORALE_BONUS
+            : isLoser
+                ? -LOSS_MORALE_PENALTY
+                : 0;
+        // Stability penalty for casualty rates above 20%
+        const casualtyRate = side.teamSize > 0 ? side.casualties / side.teamSize : 0;
+        const excessCasualties = Math.max(0, casualtyRate - 0.20);
+        const stabilityDelta_Q = -Math.round(excessCasualties * 10 * CASUALTY_STABILITY_RATE);
+        results.push({
+            polityId: side.id,
+            moraleDelta_Q,
+            stabilityDelta_Q,
+            populationLost: side.casualties * POP_PER_CASUALTY,
+        });
+    }
+    return results;
+}
+/**
+ * Apply a PolityImpact to a polity in-place.
+ * Clamps morale and stability to [0, SCALE.Q].
+ */
+export function applyPolityImpact(polity, impact) {
+    polity.moraleQ = clampQ(polity.moraleQ + impact.moraleDelta_Q, 0, SCALE.Q);
+    polity.stabilityQ = clampQ(polity.stabilityQ + impact.stabilityDelta_Q, 0, SCALE.Q);
+    polity.population = Math.max(0, polity.population - impact.populationLost);
+}

package/dist/src/wasm-kernel.d.ts

@@ -0,0 +1,58 @@
+import type { WorldState } from "./sim/world.js";
+interface PushExports {
+    MAX_ENTITIES: WebAssembly.Global;
+    writeEntity: (slot: number, posX: number, posY: number, alive: number) => void;
+    readDvX: (slot: number) => number;
+    readDvY: (slot: number) => number;
+    stepRepulsionPairs: (n: number, radius_m: number, repelAccel_mps2: number) => void;
+}
+interface InjuryExports {
+    MAX_ENTITIES: WebAssembly.Global;
+    writeVitals: (slot: number, fluidLoss: number, shock: number, consciousness: number, dead: number, fatigue: number, suffocation: number) => void;
+    writeRegion: (slot: number, r: number, bleedingRate: number, structuralDamage: number, internalDamage: number, surfaceDamage: number) => void;
+    readFluidLoss: (slot: number) => number;
+    readShock: (slot: number) => number;
+    readConsciousness: (slot: number) => number;
+    readDead: (slot: number) => number;
+    stepBleedAndShock: (n: number) => void;
+}
+export interface WasmEntityReport {
+    entityId: number;
+    /** Repulsion velocity delta computed by WASM push kernel (SCALE.mps units). */
+    pushDvX: number;
+    pushDvY: number;
+    /** Projected injury state after one WASM injury tick. */
+    projFluidLoss: number;
+    projShock: number;
+    projConsciousness: number;
+    projDead: boolean;
+}
+export interface WasmStepReport {
+    tick: number;
+    entities: WasmEntityReport[];
+    /** True if WASM is available and ran successfully. */
+    ok: boolean;
+    summary: string;
+}
+export declare class WasmKernel {
+    private readonly push;
+    private readonly injury;
+    private static readonly PUSH_RADIUS_M;
+    private static readonly PUSH_REPEL_MPS2;
+    constructor(push: PushExports, injury: InjuryExports);
+    /**
+     * Run WASM push + injury steps on the current world state (shadow mode — does not
+     * mutate world).  Returns a per-entity report and a one-line summary string.
+     *
+     * Call this after stepWorld() each tick for validation / diagnostics.
+     */
+    shadowStep(world: WorldState, tick: number): WasmStepReport;
+}
+/**
+ * Load push.wasm and injury.wasm from dist/as/ (co-located with this compiled module)
+ * and return a WasmKernel ready for use.
+ *
+ * Throws if the WASM files are not found (e.g. npm run build:wasm:all not yet run).
+ */
+export declare function loadWasmKernel(): Promise<WasmKernel>;
+export {};

package/dist/src/wasm-kernel.js

@@ -0,0 +1,96 @@
+// src/wasm-kernel.ts — Node.js loader and host bridge for the AssemblyScript WASM modules.
+//
+// Provides a shadow-mode step that runs as/push.wasm + as/injury.wasm alongside the
+// TypeScript kernel.  In shadow mode the WASM outputs are NOT applied to world state;
+// they are returned for the caller to log or validate.
+//
+// Usage:
+//   const kernel = await loadWasmKernel();       // once at startup
+//   const report = kernel.shadowStep(world);     // after stepWorld() each tick
+//   console.log(report.summary);
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { SCALE } from "./units.js";
+// ── Region order shared with as/injury.ts ─────────────────────────────────────
+const REGION_ORDER = ["head", "torso", "leftArm", "rightArm", "leftLeg", "rightLeg"];
+// ── Kernel class ──────────────────────────────────────────────────────────────
+export class WasmKernel {
+    push;
+    injury;
+    // Canonical kernel push tuning (mirrors src/sim/kernel.ts)
+    static PUSH_RADIUS_M = Math.trunc(0.45 * SCALE.m); // 4500
+    static PUSH_REPEL_MPS2 = Math.trunc(1.5 * SCALE.mps2); // 15000
+    constructor(push, injury) {
+        this.push = push;
+        this.injury = injury;
+    }
+    /**
+     * Run WASM push + injury steps on the current world state (shadow mode — does not
+     * mutate world).  Returns a per-entity report and a one-line summary string.
+     *
+     * Call this after stepWorld() each tick for validation / diagnostics.
+     */
+    shadowStep(world, tick) {
+        const entities = world.entities;
+        const pushMax = this.push.MAX_ENTITIES.value;
+        const injMax = this.injury.MAX_ENTITIES.value;
+        const n = Math.min(entities.length, pushMax, injMax);
+        // ── Push pass (position-based repulsion) ──────────────────────────────────
+        for (let i = 0; i < n; i++) {
+            const e = entities[i];
+            this.push.writeEntity(i, e.position_m.x, e.position_m.y, e.injury.dead ? 0 : 1);
+        }
+        this.push.stepRepulsionPairs(n, WasmKernel.PUSH_RADIUS_M, WasmKernel.PUSH_REPEL_MPS2);
+        // ── Injury pass (clotting / bleed / shock / consciousness) ────────────────
+        for (let i = 0; i < n; i++) {
+            const e = entities[i];
+            const suff = e.condition["suffocation"] ?? 0;
+            this.injury.writeVitals(i, e.injury.fluidLoss, e.injury.shock, e.injury.consciousness, e.injury.dead ? 1 : 0, e.energy.fatigue, suff);
+            for (let r = 0; r < REGION_ORDER.length; r++) {
+                const reg = e.injury.byRegion[REGION_ORDER[r]];
+                this.injury.writeRegion(i, r, reg?.bleedingRate ?? 0, reg?.structuralDamage ?? 0, reg?.internalDamage ?? 0, reg?.["surfaceDamage"] ?? 0);
+            }
+        }
+        this.injury.stepBleedAndShock(n);
+        // ── Build report ──────────────────────────────────────────────────────────
+        const reports = [];
+        for (let i = 0; i < n; i++) {
+            const e = entities[i];
+            reports.push({
+                entityId: e.id,
+                pushDvX: this.push.readDvX(i),
+                pushDvY: this.push.readDvY(i),
+                projFluidLoss: this.injury.readFluidLoss(i),
+                projShock: this.injury.readShock(i),
+                projConsciousness: this.injury.readConsciousness(i),
+                projDead: this.injury.readDead(i) === 1,
+            });
+        }
+        const summary = reports
+            .map(r => `e${r.entityId} dv=(${r.pushDvX},${r.pushDvY}) ` +
+            `fl=${(r.projFluidLoss / SCALE.Q).toFixed(3)} ` +
+            `sh=${(r.projShock / SCALE.Q).toFixed(3)} ` +
+            `co=${(r.projConsciousness / SCALE.Q).toFixed(3)}` +
+            (r.projDead ? " DEAD" : ""))
+            .join(" | ");
+        return { tick, entities: reports, ok: true, summary: `[wasm] tick ${tick}: ${summary}` };
+    }
+}
+// ── Factory ───────────────────────────────────────────────────────────────────
+/**
+ * Load push.wasm and injury.wasm from dist/as/ (co-located with this compiled module)
+ * and return a WasmKernel ready for use.
+ *
+ * Throws if the WASM files are not found (e.g. npm run build:wasm:all not yet run).
+ */
+export async function loadWasmKernel() {
+    // Compiled to dist/src/wasm-kernel.js → WASM files are at ../as/*.wasm
+    const base = new URL("../as/", import.meta.url);
+    const pushBuf = readFileSync(fileURLToPath(new URL("push.wasm", base)));
+    const injuryBuf = readFileSync(fileURLToPath(new URL("injury.wasm", base)));
+    const [pushResult, injuryResult] = await Promise.all([
+        WebAssembly.instantiate(pushBuf),
+        WebAssembly.instantiate(injuryBuf),
+    ]);
+    return new WasmKernel(pushResult.instance.exports, injuryResult.instance.exports);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",
@@ -54,10 +54,15 @@
     "./competence": {
       "import": "./dist/src/competence/index.js",
       "types": "./dist/src/competence/index.d.ts"
+    },
+    "./wasm-kernel": {
+      "import": "./dist/src/wasm-kernel.js",
+      "types": "./dist/src/wasm-kernel.d.ts"
     }
   },
   "files": [
     "dist/src",
+    "dist/as",
     "docs/project-overview.md",
     "docs/host-contract.md",
     "docs/integration-primer.md",
@@ -113,17 +118,25 @@
     "generate-zoo": "node dist/tools/generate-zoo.js",
     "generate-map": "node dist/tools/generate-map.js",
     "world-server": "node dist/tools/world-server.js",
+    "persistent-world": "node dist/tools/persistent-world.js",
     "replication-server": "node dist/tools/replication-server.js",
     "benchmark-check": "node dist/tools/benchmark-check.js",
     "benchmark-check:strict": "node dist/tools/benchmark-check.js --threshold=0.10",
     "benchmark-check:update": "node dist/tools/benchmark-check.js --update-baseline",
     "benchmark:guide": "node dist/tools/benchmark-guide.js",
-    "benchmark:parallel": "node dist/tools/benchmark-parallel.js"
+    "benchmark:parallel": "node dist/tools/benchmark-parallel.js",
+    "run:renderer-bridge": "node dist/tools/renderer-bridge.js",
+    "build:wasm": "asc as/units.ts --outFile dist/as/units.wasm --textFile dist/as/units.wat --runtime stub --optimize",
+    "build:wasm:push": "asc as/push.ts --outFile dist/as/push.wasm --textFile dist/as/push.wat --runtime stub --optimize --initialMemory 1",
+    "build:wasm:injury": "asc as/injury.ts --outFile dist/as/injury.wasm --textFile dist/as/injury.wat --runtime stub --optimize --initialMemory 1",
+    "build:wasm:all": "npm run build:wasm && npm run build:wasm:push && npm run build:wasm:injury",
+    "test:wasm": "npm run build:wasm:all && vitest run test/as/"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.3",
     "@types/node": "^20.0.0",
     "@vitest/coverage-v8": "^2.1.8",
+    "assemblyscript": "^0.27.37",
     "eslint": "^9.39.3",
     "fast-check": "^4.6.0",
     "typescript": "^5.5.4",