feat: balance checks and README - v1 complete

tests/balance.test.js

@@ -0,0 +1,31 @@
+import { describe, it, expect } from 'vitest';
+import { createWorld, advance } from '../src/sim/world.js';
+import { priceOf, advancePlanet } from '../src/sim/economy.js';
+import { GOODS, BASE_PRICE } from '../src/sim/constants.js';
+
+describe('balance', () => {
+  it('the NPC economy stays alive over a long horizon', () => {
+    const w = createWorld('balance-1');
+    advance(w, 120);
+    const alive = w.npcs.filter((n) => n.alive);
+    expect(alive.length).toBeGreaterThan(w.npcs.length * 0.5);
+    expect(w.stats.trades).toBeGreaterThan(w.npcs.length * 3);
+  });
+
+  it('price gradients survive NPC arbitrage (the player can still profit)', () => {
+    const w = createWorld('balance-1');
+    advance(w, 60);
+    let bestSpread = 0;
+    for (const good of GOODS) {
+      let lo = Infinity, hi = 0;
+      for (const planet of w.galaxy.planets) {
+        advancePlanet(planet, w.t);
+        const price = priceOf(good, planet.stock[good]);
+        lo = Math.min(lo, price);
+        hi = Math.max(hi, price);
+      }
+      bestSpread = Math.max(bestSpread, (hi - lo) / BASE_PRICE[good]);
+    }
+    expect(bestSpread).toBeGreaterThan(0.5); // at least one good still has a fat margin somewhere
+  });
+});