Files
ekcSchianoandClaude Opus 5.5 e10312ab02
CI / test (pull_request) Successful in 2m3s
Known answers for the bot: the guide's encounter answers and the bot's own results, by choice text (#35)
analysis/known/build_known.py writes data/public/known_answers.json from pdf_encounters.json and tree.json;
solver.js knownAnswer(known, offered, { target, sceneColour }) matches a screen's choices against it (the guide's
paraphrases by their words, the bot's texts exactly) and returns a pick when one choice is clearly on the guide's
recommended path to the target, plus the evidence for every choice to hand to Clef. Rebuilt daily, checked in CI,
and sent to the bot with the route model.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UCzTd31GphpMXDhQqWrCMQ
2026-11-19 13:32:09 +00:00

520 lines
33 KiB
JavaScript

/*
* solver.js: the route advisor for the site and the DragonKind bot.
*
* The route model is built in Python (core/atlas/solver.py) from the game in core/spec/game.yaml and published as
* data/policy.json. Each sample in it carries the game itself (model.game) and the count tables behind every roll
* (model.tables, model.alphas). This file reads both and re-solves the game from any point in a run, including
* points off the recommended route, so a rider (or the bot) always gets the best next choice. It is the same
* interpreter as the Python one, kept small: a walk of the game's steps, posterior-mean odds with hierarchical
* back-off, backward induction, and Dinkelbach iteration for the "eventually" goal.
* tests/core/advisor.test.js checks it gives exactly the Python model's values.
*
* Public API (unchanged for the bot): advisor(sample, colour, objective, { only }), recommendOption(adv, h, texts),
* solverHistory(formVars, seen), makeParams(tables, { alphas, game }), ENCOUNTERS (set from the first sample).
* Since November 2026: advisor options `attempt` (the account's attempt number: a first attempt has its own
* shadow odds), `fix` (hold some decisions to given options: an experiment arm) and sampling "uniform" (mapping);
* assign(plan, { accountSeq, attempt }) reads the experiment plan (experiments.json) and says what an attempt is for;
* screenPick(tree, sceneId, offered, { mode }) picks from the screen tree (tree.json): least-tried, or Thompson.
* knownAnswer(known, offered, { target, sceneColour }) looks a screen's choices up in known_answers.json (the guide's
* encounter answers and the bot's own results) for screens nothing else covers: a pick when the evidence is clear,
* and the evidence for every choice either way, to hand to Clef (issue #35).
* UMD: window.ThreshSolver in the browser, module.exports in Node. No dependencies.
*/
(function (root, factory) {
if (typeof module === "object" && module.exports) module.exports = factory();
else root.ThreshSolver = factory();
})(typeof self !== "undefined" ? self : this, function () {
"use strict";
const ALPHA = 20;
const ZERO = { x: 0, o: 0, r: 0 }, REACHED = { x: 0, o: 0, r: 1 };
const canon = (s) => JSON.stringify(Object.keys(s).sort().map((k) => [k, s[k]]));
const encColour = (ctx) => (ctx === "tree-Greens" ? "Green" : ctx.split("-")[1]);
const api = {};
/* ---------- posterior draws, for Thompson sampling ---------- */
function rng(seed) {
let x = (seed >>> 0) || 0x9e3779b9;
return () => { x ^= x << 13; x >>>= 0; x ^= x >>> 17; x ^= x << 5; x >>>= 0; return (x + 0.5) / 4294967296; };
}
function normal(rand) { return Math.sqrt(-2 * Math.log(rand())) * Math.cos(2 * Math.PI * rand()); }
function gamma(k, rand) { // Marsaglia and Tsang
if (k < 1) return gamma(k + 1, rand) * Math.pow(rand(), 1 / k);
const d = k - 1 / 3, c = 1 / Math.sqrt(9 * d);
for (;;) {
let x, v;
do { x = normal(rand); v = 1 + c * x; } while (v <= 0);
v = v * v * v;
const u = rand();
if (u < 1 - 0.0331 * x ** 4 || Math.log(u) < 0.5 * x * x + d * (1 - v + Math.log(v))) return d * v;
}
}
function dirichlet(a, rand) {
const g = a.map((x) => Math.max(gamma(x, rand), 1e-300));
let s = 0; for (const x of g) s += x;
return g.map((x) => x / s);
}
/* ---------- the odds: posterior means (or, with rand, one posterior draw) with hierarchical back-off ---------- */
/** The givens of a run (game.yaml `givens`): the defaults, with `attempt` set from an attempt number or name. */
function givenFor(game, { attempt = null, given = null } = {}) {
const g = Object.fromEntries(Object.entries(game.givens || {}).map(([k, v]) => [k, v.default]));
if (attempt != null && game.givens && game.givens.attempt) g.attempt = attempt === 1 || attempt === "1" || attempt === "First attempt" ? "First attempt" : "Later attempt";
return { ...g, ...(given || {}) };
}
// given: the run's givens; memo: pass the same Map to get the same posterior draw for another given
function makeParams(T, { alphas = {}, game, rand = null, given = null, memo = new Map() }) {
const normalise = (a) => { let sum = 0; for (const x of a) sum += x; return a.map((x) => x / sum); };
const estimate = rand ? (a) => dirichlet(a, rand) : normalise;
const known = given || givenFor(game);
const ctxKey = (s, names) => names.map((k) => (s[k] == null ? "?" : s[k])).join("|");
function chance(node, walked) {
const sp = game.chance[node], cats = sp.outcomes;
// a closed gate (game.yaml `requires`): the roll always comes out as `otherwise`
if (sp.requires && Object.entries(sp.requires).some(([k, v]) => walked[k] !== v)) return Object.fromEntries(cats.map((k) => [k, k === sp.otherwise ? 1 : 0]));
const state = { ...known, ...walked };
let p = null;
for (let L = 0; L <= sp.context.length; L++) {
const names = sp.context.slice(0, L);
if (names.some((k) => state[k] == null)) break;
const key = L + ":" + ctxKey(state, names), mk = node + "#" + key;
if (memo.has(mk)) { p = memo.get(mk); continue; }
// a level that is not pooled (game.yaml `distinct`) keeps a token prior of one run
const c = T[node][key] || {}, al = L <= (sp.distinct || 0) ? 1 : alphas[node] || ALPHA;
const a = cats.map((k, i) => (c[k] || 0) + (p ? al * p[i] : 0.5));
p = estimate(a);
memo.set(mk, p);
}
return Object.fromEntries(cats.map((k, i) => [k, p[i]]));
}
function encounter(ctx) {
const mk = "enc#" + ctx;
if (!memo.has(mk)) {
const e = T.encounter[ctx] || { outcomes: {}, seen: {} };
const cats = game.encounter_outcomes.filter((k) => k === "burn" || e.seen[k] || (e.outcomes[k] || 0) > 0 || k === encColour(ctx));
const a = estimate(cats.map((k) => (e.outcomes[k] || 0) + 0.5));
memo.set(mk, Object.fromEntries(cats.map((k, i) => [k, a[i]])));
}
return memo.get(mk);
}
return { chance, encounter };
}
/* ---------- one walk of the game, used to solve (as Walker in core/atlas/solver.py) ---------- */
function apply(then, state, value) {
const s = then.keep ? Object.fromEntries(then.keep.filter((k) => k in state).map((k) => [k, state[k]])) : { ...state };
for (const k of then.drop || []) delete s[k];
for (const [k, v] of Object.entries(then.set || {})) s[k] = v === "$" ? value : v;
return s;
}
function walker(game, support, only, hooks) {
const options = (name, state) => {
const by = game.decisions[name].support_by;
return by ? support[`${name}:${state[by]}`] || game.decisions[name].options : support[name];
};
function follow(then, value, state) {
const t = then[value] || then.default;
if (t.end) return hooks.end(t.end);
const s = apply(t, state, value);
if (t.encounter) {
const ctx = t.encounter.replace("$", value);
const opts = only && !only.includes(ctx) ? ["Die on purpose"] : support.encounter;
return hooks.decision("encounter", { ...s, enc: ctx }, opts, (o) => (o === "Die on purpose" ? hooks.dieOnPurpose() : hooks.attempt(ctx)));
}
return run(t.go, s);
}
function run(id, state) {
const st = game.steps[id];
if (st.decision) return hooks.decision(st.decision, state, options(st.decision, state), (o) => follow(st.then, o, state));
return hooks.chance(st.chance, state, (k) => follow(st.then, k, state));
}
return { root: () => run(game.start, {}) };
}
/** Backward induction for colour X: score = (1 - lam) P(X) - lam P(other), ties to the higher P(X). */
function solve(params, game, support, X, lam = 0, only = null) {
const memo = new Map(), choices = new Map(), optVals = new Map();
const score = (v) => (1 - lam) * v.x - lam * v.o + 1e-9 * v.x - 1e-12 * v.o;
const w = walker(game, support, only, {
decision(name, state, opts, cont) {
const key = name + "@" + canon(state);
if (memo.has(key)) return memo.get(key);
let top = null, arg = null;
const vals = {};
for (const o of opts) {
const v = cont(o);
vals[o] = v;
if (!top || score(v) > score(top)) { top = v; arg = o; }
}
memo.set(key, top); choices.set(key, arg); optVals.set(key, vals);
return top;
},
chance(node, state, cont) {
let acc = ZERO;
for (const [k, p] of Object.entries(params.chance(node, state))) {
if (!p) continue;
const v = cont(k);
acc = { x: acc.x + p * v.x, o: acc.o + p * v.o, r: acc.r + p * v.r };
}
return acc;
},
end: () => ZERO,
dieOnPurpose: () => REACHED,
attempt(ctx) {
let x = 0, o = 0;
for (const [k, p] of Object.entries(params.encounter(ctx))) if (k !== "burn") { if (k === X) x += p; else o += p; }
return { x, o, r: 1 };
},
});
return { value: w.root(), choices, optVals };
}
function solveRatio(params, game, support, X, only) {
let lam = 0, s = solve(params, game, support, X, 0, only);
for (let i = 0; i < 30; i++) {
const v = s.value, r = v.x + v.o > 0 ? v.x / (v.x + v.o) : 0;
if (Math.abs(r - lam) < 1e-10) break;
lam = r;
s = solve(params, game, support, X, lam, only);
}
return { ...s, lam };
}
/* ---------- the advisor ---------- */
/**
* advisor(sample, X, objective, { only }): sample is policy.samples.all (or .lowBias); X a colour; objective
* "eventually" (default) or "thisAttempt"; only: bond only at these encounters, die on purpose elsewhere.
* Returns { value, step(h), next(h), attempts(ctx), params, game }.
*
* h is a run so far, keyed by the game's step names: decisions (company, leave, direction, react, scream,
* clearing, fight, dagger, fate, wounded, post, hour, descend, red, valley, encounter) and rolls (fs, shadow,
* shadowColour, meadow). A rider asking for advice survived every deadly roll so far; step() reports the risk of
* the deadly roll just passed on the step after it. When h already has a later step but skips an earlier
* decision (an older form record, say), the recommended option is assumed for the skipped one.
*/
function advisor(sample, X, objective = "eventually", { only = null, sampling = "best", seed = 1, draws = 40, attempt = null, given = null, fix = null } = {}) {
const m = sample.model, game = m.game;
api.game = game; api.ENCOUNTERS = game.by_colour;
// attempt: the account's attempt number (or "First attempt" / "Later attempt"). A first attempt has its own odds
// for the rolls that depend on it (the shadow); without it, a later attempt is assumed.
const defaults = givenFor(game), known = givenFor(game, { attempt, given });
const special = Object.keys(known).some((k) => known[k] !== defaults[k]);
// "uniform" (mapping) may take any option the game has, so it is solved without the minimum-support rule
const all = Object.fromEntries(Object.entries(game.decisions).map(([k, d]) => [k, d.options]));
const base = sampling === "uniform" ? { ...all, encounter: m.support.encounter } : m.support;
// fix: { decision: option } holds those decisions to one option (an experiment arm); the rest is solved around it
let support = base;
if (fix) {
support = { ...base };
for (const [k, o] of Object.entries(fix)) {
if (!game.decisions[k] || !game.decisions[k].options.includes(o)) throw new Error(`fix: ${k} has no option "${o}"`);
support[k] = [o];
if (game.decisions[k].support_by) for (const key of Object.keys(support)) if (key.startsWith(k + ":")) support[key] = [o];
}
}
// One world (the posterior means, or one draw): the odds for this run's givens, solved for the objective.
// "Eventually" on a first attempt: every later attempt is an ordinary one, worth its own ratio (lam), so the
// best play now maximises P(X now) + P(no bond now) * lam: the same score with lam fixed.
const solveWith = (rand) => {
const memo = new Map();
const mk = (g) => makeParams(m.tables, { alphas: m.alphas, game, rand, given: g, memo });
if (objective !== "eventually") { const params = mk(known); return { params, sol: solve(params, game, support, X, 0, only) }; }
if (!special) { const params = mk(known); return { params, sol: solveRatio(params, game, support, X, only) }; }
const lam = solveRatio(mk(defaults), game, base, X, only).lam;
const params = mk(known);
return { params, sol: { ...solve(params, game, support, X, lam, only), lam } };
};
// "best": the best route under the posterior means. "thompson": the best route of one posterior draw of the odds
// (one per attempt: make a new advisor with a new seed for each attempt), so every option is tried about as
// often as it is likely to be the best one; as the data firm up, sampling settles on the best route.
// "uniform": every option on the screen is equally likely (recommendOption picks; see there).
const thompson = sampling === "thompson";
const { params, sol } = solveWith(thompson ? rng(seed) : null);
// the chance Thompson sampling picks each option at a history, estimated from `draws` other draws: the
// propensity to log, so the runs can be re-weighted later
let worlds = null;
const propensityAt = (key, choice) => {
if (!thompson) return 1;
if (!worlds) worlds = Array.from({ length: draws }, (_, i) => solveWith(rng(seed * 7919 + i + 1)).sol.choices);
return worlds.filter((c) => c.get(key) === choice).length / draws;
};
const VARS = new Set([...Object.keys(game.decisions), ...Object.keys(game.chance), "encounter"]);
const fmt = (v) => ({ pX: v.x, pOther: v.o, pReach: v.r });
const label = (k) => (game.decisions[k] || game.chance[k]).label;
const decisionAt = (name, key, extra) => {
const vals = sol.optVals.get(key) || {};
const choice = sol.choices.get(key);
return { kind: "decision", var: name, label: label(name), choice, propensity: propensityAt(key, choice),
options: Object.fromEntries(Object.entries(vals).map(([o, v]) => [o, fmt(v)])), ...extra };
};
/** The next thing that happens after history h: a decision, a roll, or the end of the run. */
function step(h) {
const used = new Set();
const later = () => Object.keys(h).some((k) => VARS.has(k) && h[k] != null && !used.has(k));
let id = game.start, state = {}, risk = null;
for (let guard = 0; guard < 100; guard++) {
const st = game.steps[id];
let value;
if (st.decision) {
const name = st.decision, key = name + "@" + canon(state);
if (h[name] != null) { value = h[name]; used.add(name); }
else if (later()) value = sol.choices.get(key);
else return decisionAt(name, key, risk ? { risk } : {});
risk = null;
} else {
const node = st.chance, probs = params.chance(node, state), sp = game.chance[node];
if (sp.risk_label) { risk = { label: sp.risk_label, p: probs.die }; value = "live"; }
else if (h[node] != null) { value = h[node]; used.add(node); risk = null; }
else return { kind: "chance", var: node, label: label(node), probs, ...(risk ? { risk } : {}) };
}
const t = st.then[value] || st.then.default;
if (!t) return { kind: "end", invalid: `${st.decision || st.chance} = ${value}` };
if (t.end) return { kind: "end", what: t.end };
const s = apply(t, state, value);
if (t.encounter) {
const ctx = t.encounter.replace("$", value);
if (h.encounter == null) return decisionAt("encounter", "encounter@" + canon({ ...s, enc: ctx }), { encounter: ctx, ...(risk ? { risk } : {}) });
return { kind: "end", encounter: ctx, action: h.encounter, outcomes: h.encounter === "Die on purpose" ? { burn: 1 } : params.encounter(ctx) };
}
id = t.go; state = s;
}
throw new Error("the game has no end");
}
return {
colour: X, objective, only, sampling, seed: sampling === "best" ? null : seed, given: known, fix, value: sol.value, step, params, game,
/** attempts recorded at an encounter (genuine attempts only), to show how much data a bond chance rests on */
attempts: (ctx) => Object.values(((m.tables.encounter || {})[ctx] || { outcomes: {} }).outcomes).reduce((a, b) => a + b, 0),
/** the next decision only (null when the next step is a roll or the run is over) */
next(h) {
const s = step(h);
return s.kind === "decision" ? { decision: s.var, label: s.label, choice: s.choice, propensity: s.propensity, options: s.options } : null;
},
};
}
/* ---------- the bot ---------- */
const norm = (t) => String(t || "").toLowerCase().replace(/[‘’‛`']/g, "'").replace(/[–—-]/g, " ").replace(/[^a-z0-9'\s]/g, " ").replace(/\s+/g, " ").trim();
/**
* Which of the options on the bot's screen to pick: { index, decision, choice, margin, options, reason }.
* index is null when there is no advice for this screen (use the bot's own rules). The encounter decision
* ("Attempt the bond" / "Die on purpose") is returned without an index: the bot knows which option is which.
* The on-screen text of each option is in game.yaml (bot_text).
*/
function recommendOption(adv, h, offered) {
const rec = adv.next(h);
if (!rec) return null;
const texts = offered.map(norm), pats = (adv.game.bot_text || {})[rec.decision] || {};
// mapping (sampling "uniform"): every option on the screen that the game knows is equally likely, except a
// decision held by `fix` and the bonding encounter (where the advisor's own choice stands)
if (adv.sampling === "uniform" && rec.decision !== "encounter" && !(adv.fix && adv.fix[rec.decision])) {
const on = Object.keys(rec.options).map((o) => [o, pats[o] ? texts.findIndex((t) => new RegExp(pats[o]).test(t)) : -1]).filter(([, i]) => i >= 0);
if (on.length) {
const [o, i] = on[Math.floor(rng(hash(`${adv.seed}|${rec.decision}|${canon(h)}`))() * on.length)];
return { index: i, decision: rec.decision, choice: o, propensity: 1 / on.length, margin: null, options: rec.options, reason: `${rec.label}: ${o} (mapping: 1 of ${on.length} at random)` };
}
}
// With squadmates, staying and the direction are one screen ("Go west with your squadmate", "Convince them to
// head east instead", "Leave your squadmate"): staying is answered with the direction that follows it.
if (rec.decision === "leave" && rec.choice === "Stay together") {
const then = adv.next({ ...h, leave: rec.choice });
const dp = then && then.decision === "direction" ? ((adv.game.bot_text || {}).direction || {})[then.choice] : null;
const di = dp ? texts.findIndex((t) => new RegExp(dp).test(t)) : -1;
if (di >= 0) return { index: di, decision: "leave", choice: rec.choice, also: { direction: then.choice }, propensity: rec.propensity * then.propensity, margin: null, options: rec.options, reason: `${rec.label}: ${rec.choice}, ${then.label}: ${then.choice}` };
}
const pat = pats[rec.choice];
const idx = pat ? texts.findIndex((t) => new RegExp(pat).test(t)) : -1;
const values = Object.values(rec.options).map((v) => v.pX).sort((a, b) => b - a);
return { index: idx < 0 ? null : idx, decision: rec.decision, choice: rec.choice, propensity: rec.propensity,
margin: values.length > 1 ? values[0] - values[1] : null,
options: rec.options,
reason: idx < 0 && rec.decision !== "encounter" ? "the recommended choice is not on this screen; use the bot's own rules" : `${rec.label}: ${rec.choice}` };
}
/**
* The community form's variables for a run so far (graph.trajectoryVariables(t).vars, or a coded form run) as a
* history for advisor().step(), keyed by the game's step names. seen: what the bot saw on screen that the form does
* not ask: { shadow: "yes"|"no", shadowColour, meadow }. Uses the game of the last advisor made (or pass one).
*/
function solverHistory(vars, seen = {}, game = api.game) {
const D = game.decisions, F = game.from_form, h = {};
const has = (k, v) => D[k].options.includes(v);
if (has("company", vars.company)) h.company = vars.company;
const lf = vars.left_squadmates;
if (h.company && h.company !== "Alone" && lf != null && lf !== "") h.leave = String(lf).toLowerCase() === "true" ? "Leave them" : "Stay together";
if (has("direction", vars.direction)) h.direction = vars.direction;
if (["Red", "Brown", "Green", "Orange"].includes(vars.first_sighting)) h.fs = vars.first_sighting;
if (has("react", vars.sighting_action)) h.react = vars.sighting_action;
if (vars.scream === "Ignore the scream") h.scream = "Keep walking";
else if (vars.scream === "Investigate & help" || vars.scream === "Investigate & leave" || vars.scream_investigate) h.scream = "Investigate the scream";
if (vars.scream === "Investigate & help") h.clearing = "Help your squadmate";
if (vars.scream === "Investigate & leave") h.clearing = "Walk away";
if (F.fight[vars.combat_first]) h.fight = F.fight[vars.combat_first];
if (F.dagger[vars.combat_second]) h.dagger = F.dagger[vars.combat_second];
if (F.helped.includes(vars.resolution)) h.fate = vars.resolution;
if (F.ignored.includes(vars.resolution)) h.wounded = vars.resolution;
if (has("post", vars.post_path)) h.post = vars.post_path;
if (has("hour", vars.hour)) h.hour = vars.hour;
if (vars.branch === "Descend quickly: Red" || vars.branch === "Descend quickly: let the Red pass") h.descend = "Quickly (Red)";
if (vars.branch === "Descend quickly: let the Red pass") h.red = "Let it pass (two Greens)";
if (has("red", vars.red)) h.red = vars.red;
if (vars.branch === "Descend slowly: two Greens") h.descend = "Slowly (two Greens)";
if (vars.branch === "Valley Red") h.valley = "Face the Red";
if (vars.branch === "Passed the Red: meadow") h.valley = "Pass the Red (meadow)";
for (const k of ["meadow", "shadow", "shadowColour"]) if (seen[k]) h[k] = seen[k];
if (h.hour === "Tree" && h.descend && !h.shadow) h.shadow = "no";
return h;
}
/* ---------- the experiment plan (planner/experiments.yaml, published as experiments.json) ---------- */
function hash(s) { let x = 2166136261; for (const ch of String(s)) { x ^= ch.codePointAt(0); x = Math.imul(x, 16777619) >>> 0; } return x || 1; }
/** The arm of the n-th unit (0-based) of an experiment: balanced blocks, each block a seeded shuffle of the arms. */
function armFor(experiment, n) {
const arms = experiment.arms, k = arms.length, rand = rng(hash(`${experiment.id}|${experiment.seed || 0}|${Math.floor(n / k)}`));
const order = arms.map((_, i) => i);
for (let i = k - 1; i > 0; i--) { const j = Math.floor(rand() * (i + 1)); [order[i], order[j]] = [order[j], order[i]]; }
return arms[order[n % k]];
}
/**
* What an attempt is for, under the plan: assign(plan, { accountSeq, attempt, facts }) ->
* { experimentId, arm, fix, target, objective, sampling, seed, propensity, burn, planId }, or null when no
* experiment covers the attempt (use the account's own goal).
* accountSeq: the account's number in the order the accounts were made (0, 1, 2, ...), the same for its whole
* life; attempt: the account's attempt number (1 = its first threshing); facts: what the plan's `when` rules ask
* about the account, e.g. { sawShadowBefore: true }. The answer is the same every time for
* the same plan id, so a restart mid-attempt changes nothing. Pass the result to advisor():
* advisor(policy.samples.all, a.target, a.objective, { attempt, fix: a.fix, sampling: a.sampling, seed: a.seed })
* and log experimentId, arm, planId and the propensity on the run.
*/
function assign(plan, { accountSeq, attempt, facts = {} }) {
const takes = (e) => !e.accounts || ((((accountSeq - (e.accounts.offset || 0)) % e.accounts.every) + e.accounts.every) % e.accounts.every) < e.accounts.take;
// when: facts about the account that must hold (a fact the bot does not pass counts as false)
const holds = (e) => Object.entries(e.when || {}).every(([k, v]) => (facts[k] == null ? false : facts[k]) === v);
let open = (plan.experiments || []).filter((e) => e.status === "running" && attempt >= e.attempts.from && (e.attempts.to == null || attempt <= e.attempts.to)
&& takes(e) && holds(e));
if (!open.length) return null;
if (open.some((e) => e.exclusive)) open = open.filter((e) => e.exclusive); // an exclusive experiment takes its attempts whole
const total = open.reduce((s, e) => s + e.share, 0);
let u = rng(hash(`${plan.seed || 0}|${accountSeq}|${attempt}`))() * total, exp = open[open.length - 1];
for (const e of open) { if (u < e.share) { exp = e; break; } u -= e.share; }
// the unit that is randomised: the account (one arm for life) or the attempt (blocks within the account)
// (accounts are counted among those the experiment takes, so its blocks stay balanced)
const off = exp.accounts ? (((accountSeq - (exp.accounts.offset || 0)) % exp.accounts.every) + exp.accounts.every) % exp.accounts.every : 0;
const nth = exp.accounts ? Math.floor(accountSeq / exp.accounts.every) * exp.accounts.take + off : accountSeq;
let arm = exp.unit === "account" ? armFor(exp, nth) : armFor({ ...exp, seed: `${exp.seed || 0}|${accountSeq}` }, attempt - exp.attempts.from);
// cycle: a different combination of these decisions on every attempt of the account, none repeated until all
// are used (the combinations are walked with a step that shares no factor with their number)
if (arm.cycle) {
const keys = Object.keys(arm.cycle), total = keys.reduce((n, k) => n * arm.cycle[k].length, 1);
const gcd = (a, b) => (b ? gcd(b, a % b) : a), h = hash(`${exp.seed || 0}|${exp.id}|${accountSeq}`);
let step = (h % total) || 1;
while (gcd(step, total) !== 1) step = (step % total) + 1;
let i = ((h >>> 8) + (attempt - exp.attempts.from) * step) % total;
const combo = {};
for (const k of keys) { combo[k] = arm.cycle[k][i % arm.cycle[k].length]; i = Math.floor(i / arm.cycle[k].length); }
arm = { id: keys.map((k) => `${k}=${combo[k]}`).join(" / "), fix: { ...arm.fix, ...combo } };
}
return { experimentId: exp.id, arm: arm.id, fix: arm.fix || null, target: exp.target, objective: exp.objective || "eventually",
sampling: exp.sampling || "best", seed: hash(`${plan.seed || 0}|${exp.id}|${accountSeq}|${attempt}`),
propensity: (exp.share / total) / exp.arms.length, burn: exp.burn || null, planId: plan.id };
}
/* ---------- picks made from the screen tree (analysis/tree/build_tree.py, published as tree.json) ---------- */
/**
* Which option to pick on a screen, from what the tree knows about that screen:
* screenPick(tree, sceneId, offered, { mode, seed }) -> { index, text, n, mode, reason } (null: nothing offered)
* sceneId is the bot's own id for the screen; offered the option texts on it. An option the tree has never seen
* counts as never played.
* mode "least-tried": the option played least so far (mapping: fills the tree's gaps first).
* mode "thompson": for each option, draw a survival rate from what has been seen (survived + 1, died + 1) and
* take the highest: untested options get tried, deadly ones fade out. It looks one step
* ahead only, so use it where dying is the risk (a bonding encounter).
* Ties and draws use `seed` (give a new one per attempt and screen).
*/
function screenPick(tree, sceneId, offered, { mode = "least-tried", seed = 1 } = {}) {
if (!offered || !offered.length) return null;
const sc = ((tree || {}).screens || {})[sceneId], rand = rng(hash(`${seed}|${sceneId}|${mode}`));
const known = sc ? Object.values(sc.options) : [];
const rows = offered.map((text, index) => {
const o = known.find((k) => norm(k.text) === norm(text)) || { n: 0, to: {} };
const died = (o.to.DIED || { n: 0 }).n;
return { index, text, n: o.n, survived: o.n - died, died, tie: rand() };
});
let pick;
if (mode === "thompson") {
for (const r of rows) { const a = gamma(r.survived + 1, rand), b = gamma(r.died + 1, rand); r.draw = a / (a + b); }
pick = rows.reduce((x, y) => (y.draw > x.draw ? y : x));
} else {
pick = rows.reduce((x, y) => (y.n < x.n || (y.n === x.n && y.tie < x.tie) ? y : x));
}
return { index: pick.index, text: pick.text, n: pick.n, mode,
reason: mode === "thompson" ? `survived ${pick.survived} of ${pick.n} so far` : `played ${pick.n} times, the fewest on this screen` };
}
/* ---------- known answers (analysis/known/build_known.py -> data/public/known_answers.json) ---------- */
const STOP = new Set("a an the to and or of your you its it is for at in on with this that be".split(" "));
const words = (t) => norm(t).split(" ").filter((w) => w && !STOP.has(w));
/** The guide labels a game text carries: the guide paraphrases ("Touch its talon"), the game says it in full ("Reach a
* hand slowly to touch its talon"), so a label matches when every word of it that matters is in the text. Labels of
* fewer than two such words ("Is your dragon") only match a text that is exactly the label. */
function guideMatches(known, text) {
const n = norm(text), have = new Set(words(text)), out = [];
for (const [k, e] of Object.entries(known.answers || {})) {
if (!e.guide) continue;
const w = words(e.text);
const exact = k === n;
if (exact || (w.length >= 2 && w.every((x) => have.has(x)))) e.guide.forEach((g) => out.push({ ...g, label: e.text, exact }));
}
return out;
}
/**
* A screen nothing else covers: what the Atlas knows about each choice, and a pick when it is clear.
* known data/public/known_answers.json
* offered the choice texts on screen, in order
* target the colour the account is after ("Blue"); sceneColour: the colour of this scene's dragon, if the
* bot knows it (only the guide's answers for that dragon's encounters are used then)
* Returns { pick, confidence, reason, choices }: pick is the index to take (null if nothing is clear), confidence
* "strong" (exactly one choice is on the guide's recommended path toward the target, and the bot's own runs don't
* contradict it) or "weak" (several fit, or only the bot's own record speaks for it). choices[i].verdict is "good",
* "bad" (the guide ends it in incineration, or the bot died on it at least 3 times in 4) or "unknown", with the
* evidence behind it. Anything weak or unknown goes to Clef with this evidence; a pick never skips the bot's guard.
*/
function knownAnswer(known, offered, { target, sceneColour = null } = {}) {
const T = target ? target[0].toUpperCase() + target.slice(1).toLowerCase() : null;
const choices = offered.map((text, index) => {
const e = (known.answers || {})[norm(text)] || {};
const bot = e.bot || null;
const guide = guideMatches(known, text).filter((g) => !sceneColour || (g.colours || []).includes(sceneColour));
const onPath = guide.filter((g) => T && (g.on_path || []).includes(T));
const botBad = bot && bot.n >= 2 && bot.died / bot.n >= 0.75;
const botGood = bot && bot.n >= 3 && bot.died === 0;
const guideBad = guide.length > 0 && guide.every((g) => /^Incinerated/.test(g.end));
const verdict = onPath.length && !botBad ? "good" : guideBad || botBad ? "bad" : "unknown";
return { index, text, verdict, guide, bot, onPath: onPath.length > 0, botGood: !!botGood };
});
const good = choices.filter((c) => c.verdict === "good");
let pick = null, confidence = null, reason = "nothing the Atlas knows covers these choices";
if (good.length === 1) {
pick = good[0].index; confidence = "strong";
reason = `on the guide's recommended path to the ${T} ("${good[0].onPath && good[0].guide.find((g) => (g.on_path || []).includes(T)).label}")`;
} else if (good.length > 1) {
const best = good.find((c) => c.botGood) || good[0];
pick = best.index; confidence = "weak"; reason = `${good.length} choices are on the guide's paths; the bot's record favours none clearly`;
} else {
const safe = choices.filter((c) => c.botGood && c.verdict !== "bad");
if (safe.length) {
const b = safe.reduce((x, y) => (y.bot.n > x.bot.n ? y : x));
pick = b.index; confidence = "weak"; reason = `the bot got through it ${b.bot.n} of ${b.bot.n} times`;
}
}
return { pick, confidence, reason, choices };
}
return Object.assign(api, {
advisor, recommendOption, solverHistory, norm, assign, armFor, givenFor, screenPick, knownAnswer,
makeParams: (T, { alphas, game } = {}) => makeParams(T, { alphas, game: game || api.game }),
/** remember the game of a policy sample (sets ENCOUNTERS) without solving anything */
useGame(sample) { api.game = sample.model.game; api.ENCOUNTERS = api.game.by_colour; return api.game; },
ENCOUNTERS: null, game: null,
});
});