Move DIFFICULTY_OPTIONS into engine/aiDifficulty.js, add state.ai.difficulty

Scaffold for tiered difficulty economics: the Easy/Medium/Hard table now
lives in engine/ (mirroring how aiStrategy.js already holds STRATEGIES)
with a difficultyFor(state) resolver alongside it, and every state.ai now
carries the picked difficulty as a plain string, threaded through boot.js's
skirmish/Odyssey paths and galaxy.js's per-planet seeding, with save/load
round-trip support. setup.js re-exports DIFFICULTY_OPTIONS so boot.js and
existing tests are unaffected. No economic field is added to any difficulty
tier yet — every new/updated test proves this lands as a pure no-op.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01G73oK4p3bnreizCcMUHVEy

boot.js

@@ -108,7 +108,8 @@ export function startGame(planetId) {
   // (aiArchetypes.js), so the opponent's identity is part of the world's character.
   const aiFaction = archetypeFor(planetId).faction || "neutral";
   const fresh = createGameState({ planetId, seed, rng: mulberry32(seed),
-    aiApm: diff.aiApm, aiMicro: diff.aiMicro, aiStrategy: setup.aiStrategy, sizeMult: setup.sizeMult, resourceMult: setup.resourceMult,
+    aiApm: diff.aiApm, aiMicro: diff.aiMicro, aiStrategy: setup.aiStrategy, difficulty: setup.difficulty,
+    sizeMult: setup.sizeMult, resourceMult: setup.resourceMult,
     playerFaction: setup.faction, aiFaction });
   bootState(fresh, { intro: true });
 }

engine/aiDifficulty.js

@@ -0,0 +1,36 @@
+/* ============================================================
+   AI DIFFICULTY — the Easy/Medium/Hard pick from the splash screen, orthogonal to
+   both the archetype (engine/aiArchetypes.js — which planet/temperament) and the
+   player-picked strategy (engine/aiStrategy.js — whether/when it voluntarily
+   attacks). Bundles the two original dials — how FAST the opponent acts (aiApm)
+   and whether it MICROS its army (aiMicro) — plus the picker's own label/note.
+   This is the ONE list of valid difficulty keys: it drives the Easy/Medium/Hard
+   buttons in setup.js AND (via boot.js's difficultyDials, which looks a key up in
+   this same array) the AI dials a match actually runs with — so a key can never
+   exist in one place and not the other, which used to let a mismatched difficulty
+   silently downgrade to Medium instead of erroring.
+
+   Economic dials land here as more fields on an entry, read through
+   difficultyFor(state) the same defensive way engine/aiStrategy.js's
+   strategyFor(state) already reads STRATEGIES — a multiplier field with `|| 1`
+   at its use site, a flag read falsy — so an absent field or a legacy/unknown key
+   composes as a no-op. This file adds no such field yet: state.ai.difficulty and
+   this resolver are pure scaffold, unread by anything but their own test until a
+   dial is added on top.
+   ============================================================ */
+
+"use strict";
+
+export const DIFFICULTY_OPTIONS = [
+  { label: "Easy", mult: "easy", note: "slow · no micro", aiApm: 20, aiMicro: false },
+  { label: "Medium", mult: "medium", note: "a fair fight", aiApm: 65, aiMicro: false },
+  { label: "Hard", mult: "hard", note: "fast · focus-fire · kite", aiApm: 140, aiMicro: true },
+];
+
+/** The active difficulty entry for this match — DIFFICULTY_OPTIONS' medium entry when
+ * state.ai.difficulty is unset or names a key that isn't in the list, the same fallback
+ * boot.js's difficultyDials already applies before a match even starts. */
+export function difficultyFor(state) {
+  return DIFFICULTY_OPTIONS.find(o => o.mult === state.ai.difficulty)
+      || DIFFICULTY_OPTIONS.find(o => o.mult === "medium");
+}

engine/galaxy.js

@@ -132,7 +132,8 @@ export function addPlanet(galaxy, planetId, { unsettled = false } = {}) {
   const aiFaction = archetypeFor(planetId).faction || "neutral";
   const state = createGameState({
     planetId, seed, rng: mulberry32(seed),
-    aiApm: s.aiApm, aiMicro: s.aiMicro, aiStrategy: s.aiStrategy, sizeMult: s.sizeMult, resourceMult: s.resourceMult,
+    aiApm: s.aiApm, aiMicro: s.aiMicro, aiStrategy: s.aiStrategy, difficulty: s.difficulty,
+    sizeMult: s.sizeMult, resourceMult: s.resourceMult,
     playerFaction: s.playerFaction, aiFaction, endless: true,
   });
   if (unsettled) {

engine/persist.js

@@ -404,6 +404,10 @@ function serPlanet(state) {
       // way aiApm/aiMicro already are (not re-derived like the archetype, since it's not a function of
       // planetId), so an old save without the field defaults to "default" (byte-identical to today).
       aiStrategy: state.ai.strategy || "default",
+      // The splash-screen Easy/Medium/Hard pick (engine/aiDifficulty.js) — persisted the same
+      // redundant-per-planet way aiApm/aiMicro/aiStrategy already are, so an old save without the
+      // field defaults to "medium" (the same fallback difficultyFor(state) itself applies).
+      aiDifficulty: state.ai.difficulty || "medium",
       // Sim-time of the last seen threat near home (drives Economic's war-footing window,
       // engine/ai.js). Additive + nullish-defaulted, so an old save without it loads as "no recent
       // threat" — the safe, conservative default (a freshly reloaded game reads as being at peace).
@@ -557,6 +561,7 @@ function rehydratePlanet(P) {
       scoutId: P.ai.aiScoutId, think: P.ai.aiThink,
       apm: P.ai.aiApm, micro: P.ai.aiMicro,
       strategy: P.ai.aiStrategy || "default",
+      difficulty: P.ai.aiDifficulty || "medium",
       lastThreatAt: P.ai.aiLastThreatAt ?? null,
       actionBudget: P.ai.aiActionBudget,
       attackForce: P.ai.aiAttackForce, attackDesperate: P.ai.aiAttackDesperate,

engine/state.js

@@ -80,7 +80,7 @@ export function makeBuilding(type, owner, x, y, opts = {}) {
  * regenerates deterministically from the seed, so two same-option runs are identical.
  * @param {{ planetId?: string, rng?: () => number, seed?: number, sizeMult?: number,
  *   resourceMult?: number, endless?: boolean, aiApm?: number, aiMicro?: boolean,
- *   aiStrategy?: string, playerFaction?: string, aiFaction?: string }} [opts]
+ *   aiStrategy?: string, difficulty?: string, playerFaction?: string, aiFaction?: string }} [opts]
  * @returns {State}
  */
 export function createGameState(opts = {}) {
@@ -156,6 +156,7 @@ export function createGameState(opts = {}) {
       apm: opts.aiApm ?? null,      // AI actions-per-minute cap from the splash screen; null = unthrottled (default/tests)
       micro: opts.aiMicro ?? false, // Tactical AI: unit-level micro (focus-fire, kiting). Off by default (and in tests).
       strategy: opts.aiStrategy || "default",   // player-picked AI strategy (engine/aiStrategy.js) — "default" ⇒ byte-identical to today
+      difficulty: opts.difficulty || "medium",  // splash-screen Easy/Medium/Hard pick (engine/aiDifficulty.js) — read via difficultyFor(state)
       lastThreatAt: null,     // sim-time of the last seen threat near home — drives the Economic strategy's war-footing window (engine/ai.js)
       actionBudget: 0,        // accumulated action credits (see engine/ai.js's accrueActionBudget)
       attackForce: 0,         // size of the current committed attack at its peak — drives the retreat check (ai.js)

engine/types.js

@@ -218,6 +218,7 @@
  * @property {{x:number, y:number}|null} colonyTarget
  * @property {number|null} apm
  * @property {boolean} micro
+ * @property {string} difficulty   splash-screen Easy/Medium/Hard pick (engine/aiDifficulty.js), read via difficultyFor(state)
  * @property {number} actionBudget
  * @property {number} attackForce
  * @property {boolean} attackDesperate

setup.js

@@ -13,6 +13,8 @@ import { PLANETS } from "./data.js";
 import { PLANET_MODIFIERS } from "./engine/map.js";
 import { archetypeFor, PLANET_ARCHETYPE } from "./engine/aiArchetypes.js";
 import { STRATEGIES } from "./engine/aiStrategy.js";
+import { DIFFICULTY_OPTIONS } from "./engine/aiDifficulty.js";
+export { DIFFICULTY_OPTIONS };   // re-exported: boot.js and a few tests still import it from here
 import { FACTIONS, PLAYABLE_FACTIONS } from "./engine/factions.js";
 import { hasSave, loadGame, hasOdysseySave, loadOdyssey } from "./saveload.js";
 import { APP_VERSION } from "./version.js";
@@ -37,18 +39,6 @@ const RESOURCE_OPTIONS = [
   { label: "Normal", mult: 1.0, note: "balanced" },
   { label: "Abundant", mult: 1.5, note: "rich deposits" },
 ];
-// Difficulty bundles the two dials — how FAST the opponent acts (aiApm) and
-// whether it MICROS its army (aiMicro) — into one Easy/Medium/Hard pick, plus
-// the picker's own label/note. This is the ONE list of valid difficulty keys:
-// it drives the Easy/Medium/Hard buttons here AND (via boot.js's difficultyDials,
-// which looks a key up in this same array) the AI dials a match actually runs
-// with — so a key can never exist in one place and not the other, which used to
-// let a mismatched difficulty silently downgrade to Medium instead of erroring.
-export const DIFFICULTY_OPTIONS = [
-  { label: "Easy", mult: "easy", note: "slow · no micro", aiApm: 20, aiMicro: false },
-  { label: "Medium", mult: "medium", note: "a fair fight", aiApm: 65, aiMicro: false },
-  { label: "Hard", mult: "hard", note: "fast · focus-fire · kite", aiApm: 140, aiMicro: true },
-];
 // Playable factions for the setup picker — a passive-trait identity for your side
 // (engine/factions.js). Each option's `mult` is the faction id, its note the short
 // tagline of its edge. The AI's faction comes from the world's archetype instead.

test/aiDifficulty.test.js

@@ -0,0 +1,78 @@
+/* ============================================================
+   AI DIFFICULTY (engine/aiDifficulty.js): the Easy/Medium/Hard pick from the splash
+   screen, orthogonal to the archetype and the player-picked strategy — see the
+   module header for the full design. This is Tier 0 of the section-08 economic-
+   dial proposal: pure scaffold, so every test here proves a NO-OP — the same
+   dials as before, now resolvable off a live state the same way strategyFor already
+   resolves engine/aiStrategy.js's STRATEGIES. Round-trip coverage lives here too
+   (engine/persist.js's serPlanet/rehydratePlanet), since nothing else exercises it.
+   ============================================================ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createGameState } from "../engine/state.js";
+import { createGalaxy, activeState } from "../engine/galaxy.js";
+import { serializeGame, deserializeGame } from "../engine/persist.js";
+import { DIFFICULTY_OPTIONS, difficultyFor } from "../engine/aiDifficulty.js";
+
+test("DIFFICULTY_OPTIONS carries no economic fields yet — a genuine no-op scaffold", () => {
+  for (const opt of DIFFICULTY_OPTIONS) {
+    for (const field of ["workerTargetMult", "graceMult", "grievanceMult", "economicEdge",
+                          "researchPaceMult", "marketAccess"]) {
+      assert.equal(opt[field], undefined, `${opt.mult}.${field} should be unset — Tier 0 adds no dial yet`);
+    }
+  }
+});
+
+test("every difficulty option still names its two original dials (aiApm, aiMicro) and its key", () => {
+  for (const key of ["easy", "medium", "hard"]) {
+    const opt = DIFFICULTY_OPTIONS.find(o => o.mult === key);
+    assert.ok(opt, `expected a "${key}" entry`);
+    assert.equal(typeof opt.aiApm, "number");
+    assert.equal(typeof opt.aiMicro, "boolean");
+  }
+});
+
+test("difficultyFor resolves each real key to its matching DIFFICULTY_OPTIONS entry", () => {
+  for (const key of ["easy", "medium", "hard"]) {
+    const s = createGameState({ planetId: "ferros", difficulty: key });
+    assert.equal(difficultyFor(s), DIFFICULTY_OPTIONS.find(o => o.mult === key));
+  }
+});
+
+test("difficultyFor falls back to medium for an unset or unrecognised state.ai.difficulty", () => {
+  const s = createGameState({ planetId: "ferros" });
+  assert.equal(s.ai.difficulty, "medium", "createGameState's own default, unprompted");
+  assert.equal(difficultyFor(s), DIFFICULTY_OPTIONS.find(o => o.mult === "medium"));
+  s.ai.difficulty = "not-a-real-difficulty";
+  assert.equal(difficultyFor(s), DIFFICULTY_OPTIONS.find(o => o.mult === "medium"), "unrecognised ⇒ medium, never throws");
+});
+
+test("createGameState wires opts.difficulty onto state.ai.difficulty", () => {
+  const s = createGameState({ planetId: "ferros", difficulty: "hard" });
+  assert.equal(s.ai.difficulty, "hard");
+  assert.equal(difficultyFor(s), DIFFICULTY_OPTIONS.find(o => o.mult === "hard"));
+});
+
+test("createGalaxy threads settings.difficulty down into every planet's state.ai.difficulty, not just the active one", () => {
+  const g = createGalaxy({ seed: 11, difficulty: "hard" });
+  assert.equal(g.settings.difficulty, "hard");
+  for (const state of g.planets.values()) {
+    assert.equal(state.ai.difficulty, "hard", `world ${state.planetId} should inherit the galaxy's difficulty`);
+  }
+  assert.equal(activeState(g).ai.difficulty, "hard");
+});
+
+test("a saved game round-trips state.ai.difficulty through JSON", () => {
+  const a = createGameState({ planetId: "ferros", difficulty: "hard" });
+  const b = deserializeGame(JSON.parse(JSON.stringify(serializeGame(a))));
+  assert.equal(b.ai.difficulty, "hard");
+});
+
+test("an old save with no aiDifficulty field loads as medium — the same defaulting every other additive ai.* field already gets", () => {
+  const a = createGameState({ planetId: "ferros", difficulty: "hard" });
+  const save = serializeGame(a);
+  delete save.ai.aiDifficulty;   // simulate a save written before this field existed
+  const b = deserializeGame(JSON.parse(JSON.stringify(save)));
+  assert.equal(b.ai.difficulty, "medium");
+});

test/static-integrity.test.js

@@ -98,17 +98,19 @@ test("data.js's lore-flavor faction data has its own name — no duplicate FACTI
 });
 
 // Regression guard: boot.js used to keep its own hand-maintained easy/medium/hard -> {aiApm,
-// aiMicro} map, entirely separate from setup.js's DIFFICULTY_OPTIONS (which drives the
-// Easy/Medium/Hard picker). If the two ever drifted — a difficulty key added to one list but
-// not the other — `DIFFICULTY[setup.difficulty] || DIFFICULTY.medium` silently downgraded an
-// unrecognised difficulty to Medium instead of erroring. setup.js's DIFFICULTY_OPTIONS is now
-// the one list carrying the AI dials too, and boot.js derives from it.
-test("setup.js's DIFFICULTY_OPTIONS is the single source of every difficulty's AI dials; boot.js derives from it", () => {
+// aiMicro} map, entirely separate from the list driving the Easy/Medium/Hard picker. If the two
+// ever drifted — a difficulty key added to one list but not the other —
+// `DIFFICULTY[setup.difficulty] || DIFFICULTY.medium` silently downgraded an unrecognised
+// difficulty to Medium instead of erroring. engine/aiDifficulty.js's DIFFICULTY_OPTIONS is the
+// one list carrying the AI dials (and, going forward, any economic difficulty fields) — setup.js
+// imports it for the picker rather than keeping its own copy, and boot.js derives from it too.
+test("engine/aiDifficulty.js's DIFFICULTY_OPTIONS is the single source of every difficulty's AI dials; setup.js and boot.js derive from it", () => {
+  const difficultySrc = readFileSync(join(root, "engine", "aiDifficulty.js"), "utf8");
   const setupSrc = readFileSync(join(root, "setup.js"), "utf8");
   const bootSrc = readFileSync(join(root, "boot.js"), "utf8");
 
-  const optionsBlock = setupSrc.match(/export const DIFFICULTY_OPTIONS\s*=\s*\[([\s\S]*?)\n\];/);
-  assert.ok(optionsBlock, "setup.js must export DIFFICULTY_OPTIONS");
+  const optionsBlock = difficultySrc.match(/export const DIFFICULTY_OPTIONS\s*=\s*\[([\s\S]*?)\n\];/);
+  assert.ok(optionsBlock, "engine/aiDifficulty.js must export DIFFICULTY_OPTIONS");
   const entries = [...optionsBlock[1].matchAll(/\{([^}]*)\}/g)].map(m => m[1]);
   assert.ok(entries.length >= 3, "expected at least the three Easy/Medium/Hard entries");
   for (const entry of entries) {
@@ -117,6 +119,10 @@ test("setup.js's DIFFICULTY_OPTIONS is the single source of every difficulty's A
     assert.match(entry, /aiMicro:\s*(true|false)/, `difficulty option missing its aiMicro dial (must live in the canonical list): ${entry}`);
   }
 
+  assert.doesNotMatch(setupSrc, /export const DIFFICULTY_OPTIONS\s*=\s*\[/,
+    "setup.js must not keep its own copy of DIFFICULTY_OPTIONS — that duplication is exactly the drift this guards against");
+  assert.match(setupSrc, /import\s*\{[^}]*\bDIFFICULTY_OPTIONS\b[^}]*\}\s*from\s*["']\.\/engine\/aiDifficulty\.js["']/,
+    "setup.js should import DIFFICULTY_OPTIONS from engine/aiDifficulty.js");
   assert.match(bootSrc, /import\s*\{[^}]*\bDIFFICULTY_OPTIONS\b[^}]*\}\s*from\s*["']\.\/setup\.js["']/,
     "boot.js should import DIFFICULTY_OPTIONS from setup.js rather than hardcoding its own difficulty list");
   assert.doesNotMatch(bootSrc, /easy:\s*\{\s*aiApm/,