@funpixel/tools 0.0.0-stage → 0.1.1

package/dist/sim/judge.js

@@ -0,0 +1,240 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const TAUGHT_WINS = 0.5;
+export const NOVICE_FLOOR = 0.8;
+export const CEILING_SHARE = 0.9;
+export const CEILING_TIME = 1.25;
+export const IDLE_SHARE = 0.5;
+export const byRole = (cohorts, role) => cohorts.find((c) => c.role === role && !c.human) ?? cohorts.find((c) => c.role === role);
+const pct = (a, b) => (b > 0 ? Math.round((100 * a) / b) : 0);
+const rate = (c) => (c.seeds > 0 ? c.won / c.seeds : 0);
+export function invalid(out) {
+    const o = out;
+    if (!o || typeof o !== 'object')
+        return 'the probe printed no JSON object';
+    if (o.probes !== 1)
+        return 'the JSON is not a probe run ({ "probes": 1, "cohorts": [...] })';
+    if (!Array.isArray(o.cohorts))
+        return 'the probe run has no cohorts';
+    for (const c of o.cohorts)
+        if (!c || typeof c.policy !== 'string' || typeof c.seeds !== 'number' || !c.progress)
+            return `a cohort is malformed (${JSON.stringify(c).slice(0, 80)})`;
+    return null;
+}
+export const STALLED_SHARE = 1.25;
+export function stalledBot(cohorts) {
+    const skilled = byRole(cohorts, 'skilled');
+    if (!skilled)
+        return null;
+    const next = 'fix the sharp policy first (replay a seed and watch where it stops: a target it cannot reach, an input the rules ignore, a timer that never fires); the ceiling, length and moments read the bot until then';
+    if (skilled.progress.max <= 0 && skilled.won === 0)
+        return { id: 'bot', state: 'warn', says: `bot broken: the sharp bot (${skilled.says}) made no progress on any of ${skilled.seeds} seeds in ${skilled.seconds} s`, next };
+    const better = cohorts.filter((c) => c.role !== 'skilled' && !c.human && c.progress.mean > STALLED_SHARE * skilled.progress.mean && c.won >= skilled.won)
+        .sort((a, b) => b.progress.mean - a.progress.mean)[0];
+    if (better)
+        return { id: 'bot', state: 'warn', says: `bot broken: the ${better.role} player gets ${pct(better.progress.mean, skilled.progress.mean)}% as far as the sharp bot (progress ${better.progress.mean} vs ${skilled.progress.mean}), so the sharp bot stalls`, next };
+    return null;
+}
+export function judgeCohorts(cohorts, noviceFloor = NOVICE_FLOOR) {
+    const by = (r) => byRole(cohorts, r);
+    const idle = by('idle'), naive = by('naive'), taught = by('taught'), skilled = by('skilled'), novice = by('novice');
+    const out = [];
+    const stalled = stalledBot(cohorts);
+    if (stalled)
+        out.push(stalled);
+    if (!idle)
+        out.push({ id: 'idle', state: 'not measured', says: 'no idle policy: whether standing still wins was never played' });
+    else if (idle.won > 0)
+        out.push({ id: 'idle', state: 'warn', says: `standing still wins ${idle.won}/${idle.seeds} seeds`, next: 'let a threat or the clock end an idle run; a phone player idles while reading the screen and should not win for it' });
+    else if (skilled && skilled.progress.mean > 0 && idle.progress.mean >= IDLE_SHARE * skilled.progress.mean)
+        out.push({ id: 'idle', state: 'warn', says: `standing still gets ${pct(idle.progress.mean, skilled.progress.mean)}% as far as the sharp bot (progress ${idle.progress.mean} vs ${skilled.progress.mean})`, next: 'waves that clear themselves or points that accrue untouched: make progress come from the verb' });
+    else
+        out.push({ id: 'idle', state: 'ok', says: `standing still does not win (${idle.lost} lost, ${idle.open} unfinished of ${idle.seeds}; progress ${idle.progress.mean})` });
+    if (!naive || !skilled)
+        out.push({ id: 'skill-ceiling', state: 'not measured', says: `no ${!naive ? 'naive' : 'skilled'} policy: the gap between steering at the target and playing well was never measured` });
+    else if (stalled)
+        out.push({ id: 'skill-ceiling', state: 'not measured', says: 'the sharp bot is broken, so the gap between steering at the target and playing well was not measured' });
+    else {
+        const own = 'on purpose (a toy, a relaxed game, a race against the clock)? say so in the design note; else give the verb something to master: a risk that pays, a line to read, a combo';
+        const slower = skilled.meanSeconds > 0 ? naive.meanSeconds / skilled.meanSeconds : 1;
+        if (rate(naive) >= CEILING_SHARE && rate(skilled) >= CEILING_SHARE) {
+            out.push(slower < CEILING_TIME
+                ? { id: 'skill-ceiling', state: 'note', says: `no skill ceiling: the naive player (${naive.says}) wins ${naive.won}/${naive.seeds} as fast as the sharp one (${naive.meanSeconds} s vs ${skilled.meanSeconds} s)`, next: own }
+                : { id: 'skill-ceiling', state: 'note', says: `the win holds no challenge: the naive player (${naive.says}) wins ${naive.won}/${naive.seeds}; skill shows only as time (${naive.meanSeconds} s vs ${skilled.meanSeconds} s)`, next: own });
+        }
+        else if (skilled.progress.mean > 0 && naive.progress.mean >= CEILING_SHARE * skilled.progress.mean && Math.abs(rate(naive) - rate(skilled)) <= 0.1) {
+            out.push({ id: 'skill-ceiling', state: 'note', says: `no skill ceiling: the naive player gets ${pct(naive.progress.mean, skilled.progress.mean)}% as far as the sharp one (progress ${naive.progress.mean} vs ${skilled.progress.mean})`, next: own });
+        }
+        else
+            out.push({ id: 'skill-ceiling', state: 'ok', says: `playing well goes further: progress ${skilled.progress.mean} vs ${naive.progress.mean}, wins ${skilled.won} vs ${naive.won} of ${skilled.seeds}` });
+    }
+    const base = naive ?? idle;
+    if (!taught)
+        out.push({ id: 'taught', state: 'not measured', says: 'no taught policy: whether doing what the game teaches pays was never played' });
+    else if (base && (rate(taught) < rate(base) - 0.1 || taught.progress.mean < CEILING_SHARE * base.progress.mean)) {
+        out.push({ id: 'taught', state: 'warn', says: `doing what the game teaches (${taught.says}) does worse than the ${base.role} player: progress ${taught.progress.mean} vs ${base.progress.mean}, wins ${taught.won} vs ${base.won}`, next: 'the tutorial teaches a losing line, or the mechanic hurts the player who uses it: check the reward reaches them and they are safe from their own move' });
+    }
+    else if (skilled && skilled.won > 0 && rate(taught) < TAUGHT_WINS) {
+        out.push({ id: 'taught', state: 'warn', says: `doing what the game teaches (${taught.policy}: ${taught.says}) wins only ${taught.won}/${taught.seeds} where the sharp policy wins ${skilled.won}/${skilled.seeds} (progress ${taught.progress.mean} vs ${skilled.progress.mean})`, next: 'the lesson alone does not get a player through: teach what the winning player does, give the taught line more room (longer tells, a wider window), or ease the defaults' });
+    }
+    else
+        out.push({ id: 'taught', state: 'ok', says: `doing what the game teaches pays: progress ${taught.progress.mean}, wins ${taught.won}/${taught.seeds}` });
+    if (skilled && skilled.won === 0 && skilled.lost > 0)
+        out.push({ id: 'winnable', state: 'note', says: `the sharp bot never wins in ${skilled.seconds} s (${skilled.lost} lost): a win may be out of reach, or the bot is weak` });
+    else if (skilled && skilled.won > 0)
+        out.push({ id: 'winnable', state: 'ok', says: `the sharp bot wins ${skilled.won}/${skilled.seeds}` });
+    if (!novice)
+        out.push({ id: 'novice', state: 'not measured', says: 'no novice policy: the first-success floor was never played' });
+    else if (novice.firstSuccess === null)
+        out.push({ id: 'novice', state: 'not measured', says: 'the game names no first success (ProbeGame.firstSuccess)' });
+    else {
+        const ok = novice.firstSuccess >= noviceFloor * novice.seeds;
+        out.push({ id: 'novice', state: ok ? 'ok' : 'warn', says: `the novice (${novice.says}) reaches the first success on ${novice.firstSuccess}/${novice.seeds} seeds (the skill's floor: ${Math.round(noviceFloor * 100)}%)`, ...(ok ? {} : { next: 'fix controls, safe introductions and warning time before lowering every enemy\'s health; freeze the novice before tuning' }) });
+    }
+    const checked = cohorts.filter((c) => c.broken !== undefined);
+    const broke = checked.find((c) => c.broken);
+    if (broke?.broken)
+        out.push({ id: 'broken', state: 'warn', says: `${broke.broken.what}: ${broke.policy} policy, seed ${broke.broken.seed}, at ${broke.broken.at} s`, next: 'replay that seed; the worst case matters, not the average' });
+    else if (checked.length)
+        out.push({ id: 'broken', state: 'ok', says: `the game's never-happens check held for ${checked.map((c) => c.policy).join(', ')}` });
+    else
+        out.push({ id: 'broken', state: 'not measured', says: 'no broken() check (NaN, off the map, inside a wall)' });
+    return out;
+}
+export function judgeMoments(moments = []) {
+    return moments.map((m) => {
+        const [best, next] = m.candidates ?? [];
+        if (!best || best.score <= 0)
+            return { id: `moment:${m.name}`, state: 'note', says: `no seed staged a ${m.name} moment in the search`, next: 'widen the seeds or start times, or check the score counts the payoff event' };
+        return {
+            id: `moment:${m.name}`, state: 'ok',
+            says: `best ${m.name}${m.says ? ` (${m.says})` : ''}: seed ${best.seed} at ${best.at} s, score ${best.score}${next ? `; next ${next.score}` : ''}`,
+            next: `the moment view's enter() can replay it: replayTo(game, policy, ${best.seed}, ${best.at}), so capture shoots a real payoff`,
+        };
+    });
+}
+export function correlation(a, b) {
+    const n = Math.min(a.length, b.length);
+    if (n < 3)
+        return null;
+    const ma = a.slice(0, n).reduce((s, x) => s + x, 0) / n, mb = b.slice(0, n).reduce((s, x) => s + x, 0) / n;
+    let ab = 0, aa = 0, bb = 0;
+    for (let i = 0; i < n; i++) {
+        ab += (a[i] - ma) * (b[i] - mb);
+        aa += (a[i] - ma) ** 2;
+        bb += (b[i] - mb) ** 2;
+    }
+    return aa < 1e-9 || bb < 1e-9 ? null : Math.round((ab / Math.sqrt(aa * bb)) * 100) / 100;
+}
+export function judgeTimelines(timelines = []) {
+    const out = [];
+    for (const tl of timelines)
+        for (const f of tl.follow ?? []) {
+            const id = `music:${tl.name}:${f.layer}`;
+            const layer = tl.rows.map((r) => r[f.layer]).filter((v) => typeof v === 'number');
+            const driver = tl.rows.map((r) => r[f.driver]).filter((v) => typeof v === 'number');
+            const span = (xs) => (xs.length ? Math.max(...xs) - Math.min(...xs) : 0);
+            const secs = tl.rows.at(-1)?.t ?? 0;
+            if (layer.length < 4 || driver.length < 4) {
+                out.push({ id, state: 'not measured', says: `${tl.name}: too few samples of ${f.layer} and ${f.driver}` });
+                continue;
+            }
+            if (span(layer) < 0.05) {
+                out.push({ id, state: 'warn', says: `${tl.name}: the ${f.layer} layer never moved in ${secs} s of play`, next: 'the mix does not follow play: raise the layer with what it names, or drop the claim' });
+                continue;
+            }
+            const r = correlation(layer, driver);
+            if (r === null)
+                out.push({ id, state: 'not measured', says: `${tl.name}: ${f.driver} never changed, so nothing to follow` });
+            else if (r < 0.3)
+                out.push({ id, state: 'note', says: `${tl.name}: ${f.layer} moves but not with ${f.driver} (r = ${r} over ${layer.length} samples)`, next: 'check what drives the layer: a mix on a timer reads as a playlist' });
+            else
+                out.push({ id, state: 'ok', says: `${tl.name}: ${f.layer} follows ${f.driver} (r = ${r} over ${layer.length} samples)` });
+        }
+    return out;
+}
+export const SHORT_RUN_SECONDS = 60;
+export function perMinute(c) {
+    const total = Object.values(c.events ?? {}).reduce((a, b) => a + b, 0);
+    return c.meanSeconds > 0 ? Math.round((total / c.meanSeconds) * 600) / 10 : 0;
+}
+const mmss = (secs) => { const s = Math.round(secs); return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`; };
+export function judgeDepth(cohorts) {
+    const out = [];
+    for (const role of ['skilled', 'novice']) {
+        const c = byRole(cohorts, role);
+        if (!c || !(c.meanSeconds > 0))
+            continue;
+        const kinds = Object.entries(c.events ?? {}).sort((a, b) => b[1] - a[1]).slice(0, 4)
+            .map(([k, v]) => `${k} ${Math.round((v / c.meanSeconds) * 600) / 10}`).join(', ');
+        const says = `${role}: a run lasts ${mmss(c.meanSeconds)} and ${perMinute(c)} events a minute${kinds ? ` (${kinds})` : ''}`;
+        if (c.lost >= c.seeds / 2 && c.meanSeconds < SHORT_RUN_SECONDS) {
+            out.push({ id: `depth:${role}`, state: 'note', says: `${says}; ${c.lost}/${c.seeds} runs end lost in under a minute`, next: 'a run under a minute is a demo in most genres (depth.md run length): warning time, a safer start or a slower ramp, before cutting the threat' });
+        }
+        else
+            out.push({ id: `depth:${role}`, state: 'ok', says, ...(kinds ? {} : { next: 'the policy steps return no events: count eats, pickups and decisions to measure density' }) });
+    }
+    return out;
+}
+export const PLAY_FLOOR = 900;
+export const DEFAULT_FLOOR = { seconds: PLAY_FLOOR, where: 'a complete game' };
+export function playFloor(root) {
+    try {
+        const n = Number(JSON.parse(readFileSync(join(root, 'funpixel.json'), 'utf8'))?.play_min_minutes);
+        if (Number.isFinite(n) && n > 0)
+            return { seconds: Math.round(n * 60), where: 'this game (funpixel.json play_min_minutes)' };
+    }
+    catch { }
+    return DEFAULT_FLOOR;
+}
+const ON_PURPOSE = /\bon purpose\b|\bby design\b|\bdeliberate(?:ly)?\b/i;
+export function statedLength(text, where = 'the design doc') {
+    const m = /play[ -]length\W{0,8}(?:about |~|≈)?(\d+(?:\.\d+)?)(?::(\d\d))?(?:\s*[–-]\s*\d+(?:\.\d+)?)?\s*(min(?:ute)?s?\b|m\b|s\b|sec(?:ond)?s?\b)?/i.exec(text);
+    if (!m) {
+        const body = /^#{1,4}\s*play[ -]length\b[^\n]*\n([\s\S]{0,400})/im.exec(text)?.[1] ?? '';
+        const n = /(\d+(?:\.\d+)?)(?:\s*(?:to|–|-)\s*\d+(?:\.\d+)?)?\s*(min(?:ute)?s?\b|s\b|sec(?:ond)?s?\b)/i.exec(body);
+        return n ? { seconds: /^s/i.test(n[2]) ? Number(n[1]) : Number(n[1]) * 60, where, ...(ON_PURPOSE.test(body) ? { onPurpose: true } : {}) } : null;
+    }
+    const seconds = m[2] !== undefined ? Number(m[1]) * 60 + Number(m[2]) : m[3] && /^s/i.test(m[3]) ? Number(m[1]) : m[3] ? Number(m[1]) * 60 : 0;
+    const at = m.index + m[0].length - 1, eol = text.indexOf('\n', at);
+    const line = text.slice(text.lastIndexOf('\n', at) + 1, eol < 0 ? text.length : eol);
+    return seconds > 0 ? { seconds, where, ...(ON_PURPOSE.test(line) ? { onPurpose: true } : {}) } : null;
+}
+export function judgeLength(cohorts, stated = null, floor = DEFAULT_FLOOR) {
+    const skilled = byRole(cohorts, 'skilled');
+    if (!skilled || !(skilled.meanSeconds > 0))
+        return { id: 'length', state: 'not measured', says: 'no skilled policy: how long a good run lasts was never played' };
+    const levels = (skilled.levels?.length ?? 0) > 1;
+    const chosen = !!stated?.onPurpose && stated.seconds < floor.seconds;
+    const need = chosen ? stated.seconds : Math.max(floor.seconds, stated?.seconds ?? 0);
+    const spread = skilled.spread ? ` (${mmss(skilled.spread.min)}–${mmss(skilled.spread.max)} over ${skilled.seeds} seeds)` : '';
+    const split = levels ? `; levels reached at ${skilled.levels.map((l) => `${l.level} ${mmss(l.meanAt)}`).join(', ')}` : '';
+    const ending = skilled.ended === undefined ? '' : skilled.ended > 0
+        ? `; the ending reached on ${skilled.ended}/${skilled.seeds} seeds${skilled.endedAt ? ` at ${mmss(skilled.endedAt)}` : ''}` : '';
+    const says = `a skilled run lasts ${mmss(skilled.meanSeconds)}${spread}${split}${ending}`;
+    const bar = `${mmss(floor.seconds)} for ${floor.where}${stated ? `, ${stated.where} says ${mmss(stated.seconds)}${stated.onPurpose ? ' on purpose' : ''}` : ''}`;
+    if (skilled.open >= skilled.seeds / 2 && skilled.seconds < need) {
+        return { id: 'length', state: 'not measured', says: `${says}, but the probe stops each run at ${skilled.seconds} s, under the bar (${bar})`, next: `raise the seconds in test/probes.ts to ${need} or more so a run can reach its ending` };
+    }
+    if (skilled.ended === 0) {
+        const looped = skilled.open >= skilled.seeds / 2;
+        const what = looped ? `no ending reached in ${skilled.seconds} s` : `no ending reached in ${skilled.seconds} s: every skilled run ends lost first (${skilled.lost}/${skilled.seeds})`;
+        if (stated?.onPurpose && looped)
+            return { id: 'length', state: 'note', says: `${says}; ${what}, as ${stated.where} chooses (endless on purpose)`, next: 'an endless game carries its minutes in what brings a player back (a best, a daily seed, a score attack)' };
+        return { id: 'length', state: 'warn', says: `${says}; ${what}`, next: looped
+                ? 'play never runs out and never ends: a game reaches an ending worth reaching (a last level, a final boss, an end screen); name it in ProbeGame.ended(run) so sim times it (skill funpixel-game-logic, references/probes.md)'
+                : 'a good player never sees the end: ease the last stretch or check the sharp bot reaches it; a run that must end in a loss says so on the play-length line "on purpose"' };
+    }
+    if (chosen && skilled.meanSeconds + 0.5 >= stated.seconds) {
+        return { id: 'length', state: 'note', says: `${says}: shorter than the ${mmss(floor.seconds)} floor for ${floor.where}, as ${stated.where} chooses on purpose (${mmss(stated.seconds)})`, next: 'a round that short is a choice; what brings a player back for the next one (a best, a daily seed, a score attack) carries the minutes' };
+    }
+    if (skilled.meanSeconds + 0.5 < need) {
+        return { id: 'length', state: 'warn', says: `${says}: under the bar (${bar})`, next: stated && stated.seconds >= floor.seconds
+                ? `play ends before the length ${stated.where} states: content that play reaches (a new idea per stage, a twist, an ending worth reaching), or state the length it has`
+                : `real play of ${mmss(floor.seconds)} or more for a first-time player: escalation, variety, a twist, an ending worth reaching (skill funpixel-game-logic, references/depth.md); a smaller scope is a choice: say "on purpose" on the play-length line of the design doc, or set funpixel.json play_min_minutes` };
+    }
+    return { id: 'length', state: 'ok', says: `${says}, at or over the bar (${bar})${skilled.ended === undefined ? '; the probe kit reports no ending (src/probe-kit.ts predates endedAt: `funtools upgrade`)' : ''}` };
+}
+export function judge(out, noviceFloor = NOVICE_FLOOR, stated = null, floor = DEFAULT_FLOOR) {
+    return [...judgeCohorts(out.cohorts, noviceFloor), judgeLength(out.cohorts, stated, floor), ...judgeDepth(out.cohorts), ...judgeMoments(out.moments), ...judgeTimelines(out.timelines)];
+}

package/dist/sim/skeleton.js

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const RULES_FILES = ['src/rules.ts', 'src/sim/rules.ts', 'src/sim/index.ts', 'src/logic/rules.ts', 'src/logic/index.ts', 'src/rules/index.ts'];
+export function rulesModule(dir) {
+    const rel = RULES_FILES.find((f) => existsSync(join(dir, f)));
+    if (!rel)
+        return null;
+    const text = readFileSync(join(dir, rel), 'utf8');
+    const names = new Set();
+    for (const m of text.matchAll(/^export\s+(?:async\s+)?(?:function\*?|const|let|class|enum)\s+([A-Za-z_$][\w$]*)/gm))
+        names.add(m[1]);
+    for (const m of text.matchAll(/^export\s*\{([^}]+)\}/gm))
+        for (const n of m[1].split(',')) {
+            const x = n.trim().split(/\s+as\s+/).pop().trim();
+            if (/^[A-Za-z_$][\w$]*$/.test(x))
+                names.add(x);
+        }
+    return { rel, exports: [...names] };
+}
+export const UNWIRED = 'is not wired yet';
+export function probeSkeleton(dir) {
+    return probeSkeletonFor(rulesModule(dir), 'funtools upgrade');
+}
+export function probeSkeletonFor(mod, writer) {
+    const from = mod ? `../${mod.rel}` : '../src/rules.ts';
+    const listed = mod?.exports.length ? mod.exports.join(', ') : '(none found: export the rules first)';
+    const imports = mod
+        ? `import * as rules from '${from}';\n`
+        : `// TODO: your rules, engine-free beside the game (skill funpixel-game-logic), then:\n// import * as rules from '${from}';\n`;
+    return `// test/probes.ts — the rules played by five policies over 100 seeds, for \`npx @funpixel/tools sim\`.
+// Written by ${writer} for this game: ${mod ? `${mod.rel} exports ${listed}` : 'no rules module yet (src/rules.ts is yours to write)'}.
+// Fill the five marked places (TODO 1–5) with your own rules; each policy sees only what a player could see.
+// Until they are filled, \`sim\` fails: the bots never played the rules (a naive bot that loses and a
+// skilled one that wins some is the core test's gate). When the rules change, change this file in the
+// same step: sim reads it every round (play length, standing still wins, the skill ceiling). Shape and
+// worked examples: skill funpixel-game-logic, references/probes.md. Run: node test/probes.ts
+
+${imports}import { cohort, type Policy, type ProbeGame } from '../src/probe-kit.ts';
+
+type Run = any; // TODO 1. the run's state type from your rules (e.g. ReturnType<typeof rules.newRun>)
+type Input = number; // TODO 2. what a player presses each step (a direction, a tap at x, nothing)
+const todo = (what: string): never => { throw new Error(\`test/probes.ts ${UNWIRED}: \${what} (skill funpixel-game-logic, references/probes.md)\`); };
+${mod ? 'void rules;\n' : ''}
+const game: ProbeGame<Run, Input> = {
+  dt: 1 / 60,
+  newRun: (seed) => todo(\`newRun(\${seed}): start a seeded run from your rules\`), // TODO 3. start, advance, end
+  step: () => todo('step(run, input): advance one dt with the input, return events as { type }'),
+  outcome: () => todo("outcome(run): 'won' | 'lost' | null"),
+  progress: () => todo('progress(run): how far it got (score, level, waves)'),
+  // level: (run) => run.level, // TODO 4. with levels, stages or waves: sim splits play length by level
+};
+
+// TODO 5. the players: idle never presses; naive steers straight at the goal (it must LOSE some runs);
+// skilled plays as the how-to teaches (at a human pace it must WIN some); then taught, novice, middle.
+const policies: Policy<Run, Input>[] = [
+  { name: 'idle', role: 'idle', says: 'never presses', make: () => () => 0 },
+  { name: 'naive', role: 'naive', says: 'steers straight at the goal, never reads a threat', make: () => () => todo('the naive policy: press toward the goal every step') },
+  { name: 'skilled', role: 'skilled', says: 'plays as the how-to teaches', make: () => () => todo('the skilled policy: read what the player sees, answer it') },
+];
+
+const seeds = Array.from({ length: 100 }, (_, i) => i + 1);
+// Seconds per run: past the length the game means to have (sim's floor is 15 min and an ending: ProbeGame.ended).
+console.log(JSON.stringify({ probes: 1, cohorts: policies.map((p) => cohort(game, p, seeds, 960)) }));
+`;
+}

package/dist/simulator/lease.js

@@ -0,0 +1,159 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { alive } from "../machine/procs.js";
+import { guarded, isUdid, LEASE_PREFIX, parseDevices, parseDeviceTypes, parseRuntimes, pickDeviceType, pickRuntime } from "./simctl.js";
+export const DEFAULT_DEVICE = 'iPhone 17 Pro';
+const file = (root, udid) => join(root, `${udid.toUpperCase()}.json`);
+export async function readLeases(root) {
+    let names = [];
+    try {
+        names = await readdir(root);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const n of names.filter((x) => x.endsWith('.json'))) {
+        try {
+            out.push(JSON.parse(await readFile(join(root, n), 'utf8')));
+        }
+        catch { }
+    }
+    return out.sort((a, b) => a.created.localeCompare(b.created));
+}
+export async function readLease(root, udid) {
+    try {
+        return JSON.parse(await readFile(file(root, udid), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeLease(root, l) {
+    await mkdir(root, { recursive: true });
+    const f = file(root, l.udid);
+    const tmp = `${f}.${randomBytes(3).toString('hex')}.tmp`;
+    await writeFile(tmp, JSON.stringify(l, null, 2) + '\n');
+    await rename(tmp, f);
+}
+const ours = (leases, devices) => (udid) => {
+    const u = udid.toUpperCase();
+    return leases.some((l) => l.udid.toUpperCase() === u) && devices.some((d) => d.udid.toUpperCase() === u && d.name.startsWith(LEASE_PREFIX));
+};
+async function devices(run) {
+    return parseDevices(await run(['list', 'devices', '-j'], 30_000));
+}
+export async function lease(o, d) {
+    const types = parseDeviceTypes(await d.simctl(['list', 'devicetypes', '-j'], 30_000));
+    const type = pickDeviceType(types, o.device ?? DEFAULT_DEVICE);
+    if (!type)
+        return { ok: false, message: `no simulator device type "${o.device ?? DEFAULT_DEVICE}" — \`xcrun simctl list devicetypes\` lists them` };
+    const rt = pickRuntime(parseRuntimes(await d.simctl(['list', 'runtimes', '-j'], 30_000)), type, o.runtime);
+    if (!rt)
+        return { ok: false, message: o.runtime ? `no available runtime "${o.runtime}" for ${type.name} — \`xcrun simctl list runtimes\` lists them` : `no available iOS runtime for ${type.name} (Xcode → Settings → Components installs one)` };
+    const name = `${LEASE_PREFIX}${randomBytes(4).toString('hex')}`;
+    const udid = (await d.simctl(['create', name, type.identifier, rt.identifier], 120_000)).trim().split('\n').pop().trim();
+    if (!isUdid(udid))
+        return { ok: false, message: `simctl create answered "${udid}", not a udid` };
+    const procs = await d.procs();
+    const l = {
+        udid, name, device: type.name, runtime: rt.name, owner_pid: d.ownerPid,
+        owner: procs.find((p) => p.pid === d.ownerPid)?.args.slice(0, 120) ?? '?', session: d.session, cwd: d.cwd, created: new Date(d.now()).toISOString(),
+    };
+    await writeLease(d.root, l);
+    if (!o.boot)
+        return { ok: true, lease: l, booted: false };
+    const run = guarded(d.simctl, ours([l], [{ udid, name, state: 'Shutdown', runtime: rt.identifier }]));
+    try {
+        await run(['boot', udid], 240_000);
+        await run(['bootstatus', udid, '-b'], 240_000);
+    }
+    catch (e) {
+        await run(['shutdown', udid], 120_000).catch(() => '');
+        await run(['delete', udid], 120_000).catch(() => '');
+        await rm(file(d.root, udid), { force: true });
+        return { ok: false, message: `${name} would not boot (deleted again): ${e.message}` };
+    }
+    return { ok: true, lease: l, booted: true };
+}
+export async function release(udid, o, d) {
+    if (!isUdid(udid))
+        return { ok: false, message: `${udid} is not a udid (funtools sim list shows the leases)` };
+    const l = await readLease(d.root, udid);
+    if (!l)
+        return { ok: false, message: `${udid} is not a funtools lease — funtools only releases simulators it created (funtools sim list)` };
+    const devs = await devices(d.simctl);
+    const dev = devs.find((x) => x.udid.toUpperCase() === udid.toUpperCase());
+    if (!dev) {
+        await rm(file(d.root, udid), { force: true });
+        return { ok: true, lease: l, note: 'the device was already gone; its record is removed' };
+    }
+    if (!dev.name.startsWith(LEASE_PREFIX))
+        return { ok: false, message: `${udid} is named "${dev.name}", not ${LEASE_PREFIX}…: a record names it but funtools did not create it, so it is left alone` };
+    const procs = await d.procs();
+    if (!o.force && l.owner_pid !== d.ownerPid && alive(procs, l.owner_pid)) {
+        return { ok: false, message: `${l.name} belongs to session ${l.session} (pid ${l.owner_pid}, still running) — releasing it would end that agent's run; pass --force only if it is yours` };
+    }
+    const run = guarded(d.simctl, ours([l], devs));
+    if (dev.state !== 'Shutdown')
+        await run(['shutdown', udid], 120_000).catch((e) => { if (!/current state: Shutdown/i.test(e.message))
+            throw e; return ''; });
+    await run(['delete', udid], 120_000);
+    await rm(file(d.root, udid), { force: true });
+    return { ok: true, lease: l };
+}
+export async function list(d) {
+    const leases = await readLeases(d.root);
+    const devs = await devices(d.simctl);
+    const procs = await d.procs();
+    const rows = leases.map((l) => ({ lease: l, device: devs.find((x) => x.udid.toUpperCase() === l.udid.toUpperCase()) ?? null, owner_alive: alive(procs, l.owner_pid), orphan: false }));
+    for (const dev of devs)
+        if (dev.name.startsWith(LEASE_PREFIX) && !leases.some((l) => l.udid.toUpperCase() === dev.udid.toUpperCase()))
+            rows.push({ lease: null, device: dev, owner_alive: false, orphan: true });
+    return rows;
+}
+export async function gc(o, d) {
+    const rows = await list(d);
+    const out = { released: [], deleted_orphans: [], kept: [], dry_run: o.dryRun };
+    const leases = rows.flatMap((r) => (r.lease ? [r.lease] : []));
+    const devs = await devices(d.simctl);
+    const orphanIds = new Set(rows.filter((r) => r.orphan && r.device?.state === 'Shutdown').map((r) => r.device.udid.toUpperCase()));
+    const run = guarded(d.simctl, (u) => ours(leases, devs)(u) || (orphanIds.has(u.toUpperCase()) && devs.some((x) => x.udid.toUpperCase() === u.toUpperCase() && x.name.startsWith(LEASE_PREFIX))));
+    for (const r of rows) {
+        if (r.lease && r.owner_alive) {
+            out.kept.push({ name: r.lease.name, why: `owner pid ${r.lease.owner_pid} is running` });
+            continue;
+        }
+        if (r.lease && !r.device) {
+            if (!o.dryRun)
+                await rm(file(d.root, r.lease.udid), { force: true });
+            out.released.push(r.lease);
+            continue;
+        }
+        if (r.lease && r.device) {
+            if (!r.device.name.startsWith(LEASE_PREFIX)) {
+                out.kept.push({ name: r.device.name, why: 'recorded, but not an ft-lease-* device: left alone' });
+                continue;
+            }
+            if (!o.dryRun) {
+                if (r.device.state !== 'Shutdown')
+                    await run(['shutdown', r.device.udid], 120_000).catch(() => '');
+                await run(['delete', r.device.udid], 120_000);
+                await rm(file(d.root, r.lease.udid), { force: true });
+            }
+            out.released.push(r.lease);
+            continue;
+        }
+        if (r.orphan && r.device) {
+            if (r.device.state !== 'Shutdown') {
+                out.kept.push({ name: r.device.name, why: `no record and ${r.device.state}: it may be in use, so it is left running; the next gc deletes it once it is shut down` });
+                continue;
+            }
+            if (!o.dryRun)
+                await run(['delete', r.device.udid], 120_000);
+            out.deleted_orphans.push(r.device);
+        }
+    }
+    return out;
+}

package/dist/simulator/orient.js

@@ -0,0 +1,57 @@
+export const ORIENTATIONS = ['portrait', 'portrait-upside-down', 'landscape', 'landscape-left', 'landscape-right'];
+export function orientationOf(word) {
+    const w = word.toLowerCase();
+    if (w === 'landscape')
+        return 'landscape-left';
+    return ['portrait', 'portrait-upside-down', 'landscape-left', 'landscape-right'].find((o) => o === w) ?? null;
+}
+export function rotation(o) {
+    return o === 'landscape-left' ? 90 : o === 'landscape-right' ? 270 : o === 'portrait-upside-down' ? 180 : 0;
+}
+export function uprightSize(o, w, h) {
+    return o === 'landscape-left' || o === 'landscape-right' ? { width: h, height: w } : { width: w, height: h };
+}
+export function toDevice(o, x, y, w, h) {
+    switch (o) {
+        case 'landscape-left': return { x: y, y: h - x };
+        case 'landscape-right': return { x: w - y, y: x };
+        case 'portrait-upside-down': return { x: w - x, y: h - y };
+        default: return { x, y };
+    }
+}
+export function toUpright(o, x, y, w, h) {
+    switch (o) {
+        case 'landscape-left': return { x: h - y, y: x };
+        case 'landscape-right': return { x: y, y: w - x };
+        case 'portrait-upside-down': return { x: w - x, y: h - y };
+        default: return { x, y };
+    }
+}
+const PLIST = {
+    UIInterfaceOrientationPortrait: 'portrait',
+    UIInterfaceOrientationPortraitUpsideDown: 'portrait-upside-down',
+    UIInterfaceOrientationLandscapeLeft: 'landscape-left',
+    UIInterfaceOrientationLandscapeRight: 'landscape-right',
+};
+export function appOrientation(plist, family = 'iphone') {
+    const list = (plist[`UISupportedInterfaceOrientations~${family}`] ?? plist.UISupportedInterfaceOrientations);
+    const supported = Array.isArray(list) ? list.map(String).filter((s) => s in PLIST) : [];
+    const initial = typeof plist.UIInterfaceOrientation === 'string' && plist.UIInterfaceOrientation in PLIST ? plist.UIInterfaceOrientation : null;
+    if (supported.includes('UIInterfaceOrientationPortrait'))
+        return { orientation: 'portrait', from: 'supports portrait' };
+    if (initial && (!supported.length || supported.includes(initial)))
+        return { orientation: PLIST[initial], from: `UIInterfaceOrientation ${initial}` };
+    const land = supported.find((s) => /Landscape/.test(s));
+    if (land)
+        return { orientation: PLIST[land], from: `UISupportedInterfaceOrientations ${land}` };
+    if (supported.length)
+        return { orientation: PLIST[supported[0]], from: `UISupportedInterfaceOrientations ${supported[0]}` };
+    return null;
+}
+export function runningApps(launchctl) {
+    const out = new Set();
+    for (const m of launchctl.matchAll(/UIKitApplication:([A-Za-z0-9._-]+)\[/g))
+        if (!m[1].startsWith('com.apple.'))
+            out.add(m[1]);
+    return [...out];
+}

package/dist/simulator/screen.js

@@ -0,0 +1,113 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { findBaguette, INSTALL as BAGUETTE_INSTALL } from "../phone/baguette.js";
+import { appOrientation, orientationOf, rotation, runningApps, toDevice, uprightSize } from "./orient.js";
+import { parseDevices, parseDeviceTypes } from "./simctl.js";
+export const IDB_INSTALL = 'brew install facebook/fb/idb-companion && pipx install fb-idb';
+export const readPlist = (f) => new Promise((ok) => {
+    execFile('plutil', ['-convert', 'json', '-o', '-', f], { timeout: 15_000, maxBuffer: 16 * 1024 * 1024 }, (err, stdout) => {
+        if (err)
+            return ok(null);
+        try {
+            ok(JSON.parse(String(stdout)));
+        }
+        catch {
+            ok(null);
+        }
+    });
+});
+export const sipsRotate = (f, deg) => new Promise((ok, fail) => {
+    if (!deg)
+        return ok();
+    execFile('sips', ['-r', String(deg), f], { timeout: 30_000 }, (err, _o, stderr) => (err ? fail(new Error(`sips: ${String(stderr || err.message).trim()}`)) : ok()));
+});
+export async function geometry(dev, simctl, plist) {
+    const t = parseDeviceTypes(await simctl(['list', 'devicetypes', '-j'], 30_000)).find((x) => x.identifier === dev.deviceTypeIdentifier || x.name === dev.name);
+    if (!t?.bundlePath)
+        return null;
+    const p = await plist(join(t.bundlePath, 'Contents', 'Resources', 'profile.plist'));
+    const w = Number(p?.mainScreenWidth), h = Number(p?.mainScreenHeight), s = Number(p?.mainScreenScale);
+    return w > 0 && h > 0 && s > 0 ? { width: Math.min(w, h), height: Math.max(w, h), scale: s } : null;
+}
+export async function device(udid, simctl) {
+    return parseDevices(await simctl(['list', 'devices', '-j'], 30_000)).find((d) => d.udid.toUpperCase() === udid.toUpperCase()) ?? null;
+}
+export async function stand(udid, o, simctl, plist) {
+    const asked = o.orientation ? orientationOf(o.orientation) : null;
+    if (o.orientation && !asked)
+        return { error: `--orientation ${o.orientation}: portrait, landscape, landscape-left, landscape-right or portrait-upside-down` };
+    if (asked && o.orientation !== 'landscape')
+        return { orientation: asked, from: `--orientation ${o.orientation}` };
+    let app = o.app;
+    if (!app) {
+        const apps = runningApps(await simctl(['spawn', udid, 'launchctl', 'list'], 30_000).catch(() => ''));
+        if (apps.length === 1)
+            app = apps[0];
+    }
+    if (app) {
+        const path = (await simctl(['get_app_container', udid, app, 'app'], 30_000).catch(() => '')).trim();
+        const info = path ? await plist(join(path, 'Info.plist')) : null;
+        const got = info ? appOrientation(info) : null;
+        if (got && (!asked || got.orientation.startsWith('landscape')))
+            return { orientation: got.orientation, from: `${app} Info.plist (${got.from})`, app };
+        if (o.app && !path)
+            return { error: `${o.app} is not installed on ${udid}` };
+    }
+    if (asked)
+        return { orientation: asked, from: '--orientation landscape (landscape-left; pass landscape-right if the picture comes back upside down)' };
+    if (o.remembered)
+        return { orientation: o.remembered, from: 'the orientation this lease last used' };
+    return { orientation: 'portrait', from: 'no app orientation found: portrait (pass --orientation or --app)' };
+}
+export async function shot(udid, out, st, d) {
+    await d.simctl(['io', udid, 'screenshot', '--type=png', out], 60_000);
+    const deg = rotation(st.orientation);
+    await d.rotate(out, deg);
+    const dev = await device(udid, d.simctl);
+    const g = dev ? await geometry(dev, d.simctl, d.plist) : null;
+    return { file: out, orientation: st.orientation, from: st.from, rotated: deg, size: g ? uprightSize(st.orientation, g.width, g.height) : null };
+}
+export const runTool = (bin, args) => new Promise((ok, fail) => {
+    execFile(bin, args, { timeout: 30_000 }, (err, _o, stderr) => (err ? fail(new Error(`${bin.split('/').pop()} ${args[0]}: ${String(stderr || err.message).trim().split('\n').slice(-2).join(' ')}`)) : ok()));
+});
+export function findTapTool(env = process.env, prefer) {
+    const b = findBaguette(env);
+    let i = null;
+    for (const d of [...(env.PATH ?? '').split(':'), join(homedir(), '.local', 'bin'), '/opt/homebrew/bin'].filter(Boolean))
+        if (existsSync(join(d, 'idb'))) {
+            i = join(d, 'idb');
+            break;
+        }
+    if (prefer === 'idb')
+        return i ? { kind: 'idb', bin: i } : null;
+    if (prefer === 'baguette')
+        return b ? { kind: 'baguette', bin: b } : null;
+    return b ? { kind: 'baguette', bin: b } : i ? { kind: 'idb', bin: i } : null;
+}
+export const NO_TAP_TOOL = `simctl cannot tap a simulator, and neither baguette nor idb is installed: ${BAGUETTE_INSTALL} (what funtools phone uses), or ${IDB_INSTALL}`;
+export async function tap(udid, x, y, o, d) {
+    if (!d.tool)
+        return { error: NO_TAP_TOOL };
+    const dev = await device(udid, d.simctl);
+    if (!dev)
+        return { error: `no simulator ${udid}` };
+    if (dev.state !== 'Booted')
+        return { error: `${dev.name} is ${dev.state}, not booted` };
+    const g = await geometry(dev, d.simctl, d.plist);
+    if (!g)
+        return { error: `the screen size of ${dev.name} is unknown (no profile.plist for its device type)` };
+    const w = g.width / g.scale, h = g.height / g.scale;
+    const px = o.points ? x : x / g.scale, py = o.points ? y : y / g.scale;
+    const up = uprightSize(o.stand.orientation, w, h);
+    if (px < 0 || py < 0 || px > up.width || py > up.height)
+        return { error: `(${x}, ${y}) is off the ${o.stand.orientation} screen (${Math.round(up.width * (o.points ? 1 : g.scale))}x${Math.round(up.height * (o.points ? 1 : g.scale))} ${o.points ? 'points' : 'pixels'})` };
+    const p = toDevice(o.stand.orientation, px, py, w, h);
+    const pt = { x: Math.round(p.x * 10) / 10, y: Math.round(p.y * 10) / 10 };
+    if (d.tool.kind === 'baguette')
+        await d.run(d.tool.bin, ['tap', '--udid', udid, '--x', String(pt.x), '--y', String(pt.y), '--width', String(w), '--height', String(h)]);
+    else
+        await d.run(d.tool.bin, ['ui', 'tap', String(Math.round(pt.x)), String(Math.round(pt.y)), '--udid', udid]);
+    return { tool: d.tool.kind, game: { x, y }, device_points: pt, orientation: o.stand.orientation, from: o.stand.from };
+}