hbengine 0.2.3

package/engine-shell/host/sandbox-scenarios.js

@@ -0,0 +1,554 @@
+/** Guided sandbox checks. The game still supplies every click. */
+
+const SCENARIO_TIMEOUT_MS = 90_000;
+export const SCENARIO_TIMEOUT = Symbol('scenario-timeout');
+
+function parseLimitValue(value, fallback = 0) {
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value === 'string' && /^\d+(\.\d+)?$/.test(value)) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) return parsed;
+    }
+    return fallback;
+}
+
+function minimumStake(ctx) {
+    const configured = parseLimitValue(ctx.limits?.min);
+    if (configured > 0) return configured;
+    const decimals = Number.isInteger(ctx.walletDecimals) ? ctx.walletDecimals : 8;
+    return 10 ** -Math.min(8, Math.max(0, decimals));
+}
+
+function walletUnit(ctx) {
+    const decimals = Number.isInteger(ctx.walletDecimals) ? ctx.walletDecimals : 8;
+    return 10 ** -Math.min(8, Math.max(0, decimals));
+}
+
+function entries(ctx) {
+    return ctx.entries || [];
+}
+
+function stakeLimit(ctx, entry) {
+    const maxMap = ctx.limits?.maxStake || {};
+    const mode = maxMap[entry.mode];
+    const max = mode && mode[entry.bet] !== undefined ? parseLimitValue(mode[entry.bet]) : parseLimitValue(ctx.limits?.max);
+    return { min: minimumStake(ctx), max: max > 0 ? max : null };
+}
+
+function playEntry(ctx, predicate = () => true) {
+    return entries(ctx).find((entry) => entry?.mode && entry?.bet && predicate(entry));
+}
+
+function tableEntry(ctx, predicate = () => true) {
+    return playEntry(ctx, (entry) => entry.indices?.length === 1 && !entry.ladder && predicate(entry));
+}
+
+function ladderEntry(ctx, suffix) {
+    return entries(ctx).find((entry) => entry?.indices?.length > 1 && (!suffix || String(entry.label).includes(suffix)));
+}
+
+function topEntry(ctx) {
+    return entries(ctx)
+        .filter((entry) => entry?.mode && entry?.bet && !entry.loss && (entry.multiplier || 0) > 0)
+        .sort((a, b) => (b.multiplier || 0) - (a.multiplier || 0))[0] || playEntry(ctx);
+}
+
+function losingEntry(ctx, subject) {
+    const sameSubject = (entry) => !subject || (entry.mode === subject.mode && entry.bet === subject.bet);
+    return tableEntry(ctx, (entry) => sameSubject(entry) && (entry.loss === true || (entry.multiplier || 0) === 0 || /lose|loss/i.test(entry.label || '')))
+        || entries(ctx).find((entry) => sameSubject(entry) && entry.indices?.length > 1 && /Bust at step 1/i.test(entry.label || ''));
+}
+
+function stakeLimits(ctx) {
+    const out = {};
+    for (const entry of entries(ctx)) {
+        if (!entry?.mode || !entry?.bet) continue;
+        out[entry.mode] ||= {};
+        out[entry.mode][entry.bet] = stakeLimit(ctx, entry);
+    }
+    return out;
+}
+
+function result(status, detail, observation, extra = {}) {
+    return {
+        status,
+        detail,
+        warnings: extra.warnings || [],
+        ...(observation ? { observation } : {}),
+        ...extra,
+    };
+}
+
+function expected(detail, observation, extra = {}) {
+    const status = extra.review ? 'needs-verdict' : 'expected';
+    return result(status, detail, observation, extra);
+}
+
+function review(detail, observation) {
+    return result('needs-verdict', detail, observation, { review: true });
+}
+
+function refusalFor(observation, request = 'play') {
+    return observation?.type === 'refused' && (observation.request?.type === request || observation.request === request);
+}
+
+function describeBet(round) {
+    return round?.bet || round?.mode || 'another bet';
+}
+
+function betInstruction(ctx, entry, prefix = 'Bet') {
+    const mode = entry.modeLabel || entry.mode;
+    const bet = entry.betLabel || entry.bet;
+    return `${prefix} ${minimumStake(ctx)} on ${mode} / ${bet}`;
+}
+
+function checkRound(observation, entry, check = {}) {
+    const round = observation?.round;
+    if (!round) return result('different', 'Different: the router did not include the round.', observation);
+    if (round.mode !== entry.mode || round.bet !== entry.bet) return result('different', `Different: bet on ${describeBet(round)}, expected ${entry.bet}.`, observation);
+    if (round.forced !== true) return result('different', 'Different: the round was not forced.', observation);
+    if (check.settledState && round.state !== 'settled') return result('different', 'Different: the round was not settled.', observation);
+    if (check.settled && round.step !== entry.indices.length) return result('different', 'Different: the ladder did not settle at its final step.', observation);
+    if (check.multBp !== undefined && round.multBp !== check.multBp) return result('different', `Different: multiplier ${round.multBp}, expected ${check.multBp}.`, observation);
+    if (check.loss && round.multBp !== 0) return result('different', 'Different: the round was not a loss.', observation);
+    if (check.winAfterLoss && round.multBp <= 0) return result('different', 'Different: the second round was not a win.', observation);
+    if (check.survived && !(round.busted === false && round.survived === entry.indices.length)) return result('different', 'Different: the ladder did not survive every step.', observation);
+    if (check.busted && !(round.busted === true && round.survived === 0 && round.step === 1)) return result('different', 'Different: the ladder did not bust at step 1.', observation);
+    return expected(check.detail || 'The runner observed the expected round.', observation, check.review ? { review: true } : {});
+}
+
+async function wait(ctx, predicate, instruction) {
+    try {
+        ctx.beforeWait?.();
+        const observation = await ctx.waitFor(predicate, SCENARIO_TIMEOUT_MS);
+        if (observation === SCENARIO_TIMEOUT) return result('skipped', `Skipped after 90 seconds: ${instruction}`);
+        if (observation) return { observation };
+        const status = ctx.stopRequested?.() ? 'stopped' : ctx.skipRequested?.() ? 'skipped' : 'needs-verdict';
+        if (status === 'needs-verdict') return review(`The runner saw no observation. Did the game show the expected result?`);
+        const verb = status === 'stopped' ? 'Stopped' : 'Skipped';
+        return result(status, `${verb}: ${instruction}`);
+    } catch (error) {
+        if (error?.code === 'timeout' || error?.name === 'TimeoutError') return result('skipped', `Skipped after 90 seconds: ${instruction}`);
+        throw error;
+    }
+}
+
+async function setupBalance(ctx, amount) {
+    const response = await ctx.setBalance(amount);
+    return response?.ok === false ? result('different', `Different: setup refused (${response.error?.message || 'balance refused'}).`) : null;
+}
+
+async function setupForce(ctx, entry) {
+    if (!entry) return result('different', 'Different: no forceable bet is available.');
+    const response = await ctx.force(entry.indices, entry.mode);
+    return response?.ok === false ? result('different', `Different: setup refused (${response.error?.message || 'force refused'}).`) : null;
+}
+
+function ladderInstruction(ctx, entry, suffix) {
+    if (entry.autoAdvance) return betInstruction(ctx, entry);
+    return `${betInstruction(ctx, entry)}, ${suffix}`;
+}
+
+const definitions = [
+    {
+        id: 'cant-afford-minimum', group: 'Balance', title: "Can't afford the minimum stake", todo: 'Press Bet once', look: 'An insufficient-balance refusal', applies: (ctx) => !!playEntry(ctx),
+        async run(ctx) {
+            const setup = await setupBalance(ctx, Math.max(0, minimumStake(ctx) - walletUnit(ctx)));
+            if (setup) return setup;
+            ctx.say?.(betInstruction(ctx, playEntry(ctx)));
+            const waited = await wait(ctx, (event) => refusalFor(event) || event.type === 'settled', this.todo);
+            if (!waited.observation) return waited;
+            if (waited.observation.type === 'settled') return result('different', 'Different: a settled round occurred.', waited.observation);
+            return waited.observation.code === 'insufficient-balance'
+                ? expected('Refused with insufficient-balance', waited.observation, { review: true })
+                : result('different', `Different: refused with ${waited.observation.code}.`, waited.observation);
+        },
+    },
+    {
+        id: 'exactly-one-bet', group: 'Balance', title: 'Exactly one bet', todo: 'Bet the minimum stake', look: 'One losing round, then insufficient-balance', applies: (ctx) => !!playEntry(ctx, (entry) => !!losingEntry(ctx, entry)),
+        async run(ctx) {
+            const entry = playEntry(ctx, (candidate) => !!losingEntry(ctx, candidate));
+            let setup = await setupBalance(ctx, minimumStake(ctx));
+            if (setup) return setup;
+            setup = await setupForce(ctx, losingEntry(ctx, entry));
+            if (setup) return setup;
+            const suffix = entry.indices.length > 1 ? ', then take the first step' : '';
+            ctx.say?.(`Bet the minimum stake (${minimumStake(ctx)}) on ${entry.modeLabel || entry.mode} / ${entry.betLabel || entry.bet}${suffix}`);
+            const first = await wait(ctx, (event) => event.type === 'settled', this.todo);
+            if (!first.observation) return first;
+            const firstCheck = checkRound(first.observation, losingEntry(ctx, entry), { loss: true });
+            if (firstCheck.status !== 'expected') return firstCheck;
+            const second = await wait(ctx, (event) => refusalFor(event), this.todo);
+            if (!second.observation) return second;
+            return second.observation.code === 'insufficient-balance'
+                ? expected('Exactly one losing bet, then insufficient-balance', second.observation, { review: true })
+                : result('different', `Different: second bet refused with ${second.observation.code}.`, second.observation);
+        },
+    },
+    {
+        id: 'stake-above-balance', group: 'Balance', title: 'Stake above the balance', todo: 'Press Bet with a stake above the balance', look: 'An insufficient-balance refusal or the game explanation', applies: (ctx) => !!playEntry(ctx),
+        async run(ctx) {
+            const entry = playEntry(ctx);
+            const setup = await setupBalance(ctx, minimumStake(ctx));
+            if (setup) return setup;
+            ctx.say?.(`Bet more than the balance (${minimumStake(ctx)}) on ${entry.modeLabel || entry.mode} / ${entry.betLabel || entry.bet}`);
+            const waited = await wait(ctx, (event) => refusalFor(event) || event.type === 'settled', this.todo);
+            if (!waited.observation) return waited;
+            if (waited.observation.type === 'settled') return result('different', 'Different: a settled round occurred.', waited.observation);
+            return waited.observation.code === 'insufficient-balance'
+                ? expected('Refused with insufficient-balance', waited.observation, { review: true })
+                : result('different', `Different: refused with ${waited.observation.code}.`, waited.observation);
+        },
+    },
+    {
+        id: 'empty-wallet', group: 'Balance', title: 'Empty wallet', todo: 'Press Bet once', look: 'A refusal for insufficient balance', applies: (ctx) => !!playEntry(ctx),
+        async run(ctx) {
+            const setup = await setupBalance(ctx, 0);
+            if (setup) return setup;
+            ctx.say?.(`Empty wallet — ${betInstruction(ctx, playEntry(ctx))}`);
+            const waited = await wait(ctx, (event) => refusalFor(event) || event.type === 'settled', this.todo);
+            if (!waited.observation) return waited;
+            if (waited.observation.type === 'settled') return result('different', 'Different: a settled round occurred.', waited.observation);
+            return waited.observation.code === 'insufficient-balance'
+                ? expected('Refused with insufficient-balance', waited.observation, { review: true })
+                : result('different', `Different: refused with ${waited.observation.code}.`, waited.observation);
+        },
+    },
+    {
+        id: 'biggest-win', group: 'Outcomes', title: 'Biggest win', todo: 'Bet once', look: 'A forced round with the top multiplier', applies: (ctx) => !!tableEntry(ctx),
+        async run(ctx) {
+            const entry = topEntry(ctx);
+            const setup = await setupForce(ctx, entry);
+            if (setup) return setup;
+            ctx.say?.(betInstruction(ctx, entry));
+            const waited = await wait(ctx, (event) => event.type === 'settled', this.todo);
+            if (!waited.observation) return waited;
+            return checkRound(waited.observation, entry, { multBp: entry.multiplier, detail: `Settled at ${entry.multiplier / 10000}×.`, review: true });
+        },
+    },
+    {
+        id: 'losing-streak', group: 'Outcomes', title: 'Losing streak', todo: 'Bet five times', look: 'Five forced losses', applies: (ctx) => !!losingEntry(ctx),
+        async run(ctx) {
+            const entry = losingEntry(ctx);
+            for (let index = 0; index < 5; index += 1) {
+                const setup = await setupForce(ctx, entry);
+                if (setup) return setup;
+                ctx.say?.(`Round ${index + 1}/5 ready — ${betInstruction(ctx, entry)}`);
+                const waited = await wait(ctx, (event) => event.type === 'settled', this.todo);
+                if (!waited.observation) return waited;
+                const checked = checkRound(waited.observation, entry, { loss: true, detail: `Round ${index + 1}/5 was a loss.` });
+                if (checked.status !== 'expected') return result('different', `Different: round ${index + 1} was not a loss.`, waited.observation);
+            }
+            return expected('Five forced losses.', undefined, { review: true });
+        },
+    },
+    {
+        id: 'win-after-loss', group: 'Outcomes', title: 'Win after a loss', todo: 'Bet twice', look: 'A loss followed by a forced win', applies: (ctx) => !!losingEntry(ctx) && !!tableEntry(ctx, (entry) => !entry.loss && (entry.multiplier || 0) > 0),
+        async run(ctx) {
+            const lossEntry = losingEntry(ctx);
+            const winEntry = topEntry(ctx);
+            let setup = await setupForce(ctx, lossEntry);
+            if (setup) return setup;
+            ctx.say?.(`${betInstruction(ctx, lossEntry)} for a loss, then ${betInstruction(ctx, winEntry)}`);
+            const loss = await wait(ctx, (event) => event.type === 'settled', this.todo);
+            if (!loss.observation) return loss;
+            const lossCheck = checkRound(loss.observation, lossEntry, { loss: true });
+            if (lossCheck.status !== 'expected') return lossCheck;
+            setup = await setupForce(ctx, winEntry);
+            if (setup) return setup;
+            const win = await wait(ctx, (event) => event.type === 'settled', this.todo);
+            if (!win.observation) return win;
+            return checkRound(win.observation, winEntry, { winAfterLoss: true, detail: 'A win followed the loss.', review: true });
+        },
+    },
+    {
+        id: 'survive-every-step', group: 'Outcomes', title: 'Survive every step', todo: 'Bet and advance through every step', look: 'The ladder survives and settles', applies: (ctx) => !!ladderEntry(ctx, 'Survive every step'),
+        async run(ctx) {
+            const entry = ladderEntry(ctx, 'Survive every step');
+            const setup = await setupForce(ctx, entry);
+            if (setup) return setup;
+            ctx.say?.(ladderInstruction(ctx, entry, 'then advance through every step'));
+            const waited = await wait(ctx, (event) => event.type === 'settled', this.todo);
+            if (!waited.observation) return waited;
+            return checkRound(waited.observation, entry, {
+                survived: true,
+                settledState: true,
+                settled: entry.autoAdvance,
+                detail: 'The ladder survived every step.',
+                review: true,
+            });
+        },
+    },
+    {
+        id: 'bust-at-step-one', group: 'Outcomes', title: 'Bust at step 1', todo: 'Bet and take the first step', look: 'The ladder busts at step 1', applies: (ctx) => !!ladderEntry(ctx, 'Bust at step 1'),
+        async run(ctx) {
+            const entry = ladderEntry(ctx, 'Bust at step 1');
+            const setup = await setupForce(ctx, entry);
+            if (setup) return setup;
+            ctx.say?.(ladderInstruction(ctx, entry, 'then take the first step'));
+            const waited = await wait(ctx, (event) => event.type === 'settled', this.todo);
+            if (!waited.observation) return waited;
+            return checkRound(waited.observation, entry, {
+                busted: true,
+                settledState: true,
+                settled: entry.autoAdvance,
+                detail: 'The ladder busted at step 1.',
+                review: true,
+            });
+        },
+    },
+    {
+        id: 'server-hiccup', group: 'Failures', title: 'Server hiccup that recovers', todo: 'Bet once', look: 'The round settles after a retry', applies: (ctx) => !!playEntry(ctx),
+        async run(ctx) {
+            ctx.armFault?.('server', { times: 1, only: 'play' });
+            ctx.say?.(betInstruction(ctx, playEntry(ctx)));
+            const waited = await wait(ctx, (event) => event.type === 'settled' || refusalFor(event), this.todo);
+            if (!waited.observation) return waited;
+            if (waited.observation.type === 'settled') return expected('Settled after the server retry.', waited.observation, { review: true });
+            return result('different', `Different: refused ${waited.observation.code}.`, waited.observation);
+        },
+    },
+    {
+        id: 'outage', group: 'Failures', title: 'Outage', todo: 'Bet during the outage, then once more after it clears', look: 'Unavailable refusal, then a normal settled bet', applies: (ctx) => !!playEntry(ctx),
+        async run(ctx) {
+            ctx.armFault?.('unavailable', { times: 3, only: 'play' });
+            ctx.say?.(`${betInstruction(ctx, playEntry(ctx))} during the outage`);
+            const refused = await wait(ctx, (event) => refusalFor(event), this.todo);
+            if (!refused.observation) return refused;
+            if (refused.observation.code !== 'unavailable') return result('different', `Different: outage refused with ${refused.observation.code}.`, refused.observation);
+            ctx.clearFaults?.();
+            ctx.say?.(`The outage is clear — ${betInstruction(ctx, playEntry(ctx))}`);
+            const settled = await wait(ctx, (event) => event.type === 'settled', this.todo);
+            if (!settled.observation) return settled;
+            return expected('Unavailable, then a normal settled bet.', settled.observation, { review: true });
+        },
+    },
+    {
+        id: 'slow-network', group: 'Failures', title: 'Slow network', todo: 'Bet once', look: 'The round settles after the delay', applies: (ctx) => !!playEntry(ctx),
+        async run(ctx) {
+            ctx.armFault?.('slow', { times: 1, ms: 3000, only: 'play' });
+            ctx.say?.(betInstruction(ctx, playEntry(ctx)));
+            const waited = await wait(ctx, (event) => event.type === 'settled' || refusalFor(event), this.todo);
+            if (!waited.observation) return waited;
+            if (waited.observation.type === 'settled') return expected('Settled after the slow response.', waited.observation, { review: true });
+            return result('different', `Different: refused ${waited.observation.code}.`, waited.observation);
+        },
+    },
+    {
+        id: 'session-expires', group: 'Failures', title: 'Session expires', todo: 'Bet once', look: 'The session ends', applies: (ctx) => !!playEntry(ctx),
+        async run(ctx) {
+            ctx.armFault?.('session', { times: 1, only: 'play' });
+            ctx.say?.(`${betInstruction(ctx, playEntry(ctx))}; this is the final scenario`);
+            const waited = await wait(ctx, (event) => event.type === 'ended' || refusalFor(event), this.todo);
+            if (!waited.observation) return waited;
+            return waited.observation.type === 'ended' || waited.observation.code === 'session-ended'
+                ? expected('The session ended.', waited.observation, { review: true })
+                : result('different', `Different: refused with ${waited.observation.code}.`, waited.observation);
+        },
+    },
+    {
+        id: 'resume-interrupted-round', group: 'Recovery', title: 'Resume an interrupted round', todo: 'Bet, then wait for the reload', look: 'The open round is shown after reload', applies: (ctx) => {
+            const entry = ladderEntry(ctx, 'Survive every step');
+            return !!entry && !entry.autoAdvance && typeof ctx.reload === 'function';
+        },
+        async run(ctx) {
+            const entry = ladderEntry(ctx, 'Survive every step');
+            const setup = await setupForce(ctx, entry);
+            if (setup) return setup;
+            ctx.say?.(`${betInstruction(ctx, entry)} to open the ladder; wait for reload`);
+            const opened = await wait(ctx, (event) => event.type === 'opened' && event.round?.state === 'open', this.todo);
+            if (!opened.observation) return opened;
+            const roundId = opened.observation.round.id;
+            const refreshed = await ctx.reload();
+            if (refreshed?.ok === false) return result('different', `Different: reload refused (${refreshed.error?.message || 'unknown'}).`);
+            const active = refreshed?.body?.activeRound || refreshed?.activeRound;
+            if (active?.id !== roundId) return result('different', 'Different: reload did not restore the open round.');
+            return review('Round is in progress after reload. Is the round shown as in progress?');
+        },
+    },
+];
+
+export const scenarioDefinitions = Object.freeze(definitions);
+
+export function applicableScenarios(ctx) {
+    return scenarioDefinitions.filter((scenario) => {
+        try {
+            return scenario.applies(ctx);
+        } catch {
+            return false;
+        }
+    });
+}
+
+export function createScenarioContext({ entries: scenarioEntries = [], limits = {}, walletDecimals = 8, setBalance, force, clearForce, armFault, clearFaults, reload, currentBalance, startingBalance, say, waitFor, skip, beforeScenario, beforeWait, awaitVerdict, cancelVerdict, resolveVerdict } = {}) {
+    const context = {
+        entries: scenarioEntries,
+        limits,
+        walletDecimals,
+        setBalance,
+        force,
+        clearForce,
+        reload,
+        currentBalance: currentBalance || (async () => undefined),
+        startingBalance,
+        say: say || (() => {}),
+        waitFor: waitFor || (async () => null),
+        armFault,
+        clearFaults,
+        skip,
+        beforeScenario,
+        beforeWait,
+        awaitVerdict,
+        cancelVerdict,
+        resolveVerdict,
+    };
+    context.stakeLimits = stakeLimits(context);
+    return context;
+}
+
+function clearForceSucceeded(response) {
+    return response?.ok === true && response.status === 204;
+}
+
+export async function runScenario(scenario, ctx, { timeoutMs = SCENARIO_TIMEOUT_MS } = {}) {
+    let start;
+    try {
+        start = await ctx.currentBalance();
+    } catch {
+        start = undefined;
+    }
+    const restore = start ?? ctx.startingBalance;
+    let outcome;
+    try {
+        outcome = await scenario.run(ctx, timeoutMs);
+        outcome ||= result('different', 'The scenario returned no result.');
+    } catch (error) {
+        outcome = result('different', error?.message || 'The scenario failed.');
+    }
+    const warnings = outcome?.warnings || [];
+    const warnForce = () => {
+        const warning = 'force still armed — the next bet may be forced';
+        warnings.push(warning);
+        if (outcome) outcome.detail = `${outcome.detail} · ${warning}`;
+    };
+    try {
+        ctx.clearFaults?.();
+    } catch {
+        // Cleanup continues even when the local fault wrapper is unavailable.
+    }
+    try {
+        const cleared = await ctx.clearForce?.();
+        if (!clearForceSucceeded(cleared)) warnForce();
+    } catch {
+        warnForce();
+    }
+    try {
+        if (restore !== undefined && restore !== null) await ctx.setBalance(restore);
+    } catch {
+        // Session expiry may refuse the restoration.
+    }
+    try {
+        ctx.clearFaults?.();
+    } catch {
+        // Restoration never leaves a fault armed.
+    }
+    if (start === undefined && restore !== undefined && outcome) outcome.detail = `${outcome.detail} · server balance unavailable; restored sandbox starting balance`;
+    if (outcome) outcome.warnings = warnings;
+    return outcome || result('different', 'The scenario failed.');
+}
+
+export function createScenarioRunner({ scenarios: selected, ctx, onScenario } = {}) {
+    const chosen = [...(selected || applicableScenarios(ctx || {}))].sort((a, b) => Number(a.id === 'session-expires') - Number(b.id === 'session-expires'));
+    let skipRequested = false;
+    let stopRequested = false;
+    let cancelWait = null;
+    let stoppedAt = null;
+    const runContext = () => ({
+        ...ctx,
+        stopRequested: () => stopRequested,
+        skipRequested: () => skipRequested,
+        waitFor: (predicate, ms) => new Promise((resolve) => {
+            if (skipRequested || stopRequested) {
+                resolve(null);
+                return;
+            }
+            let finished = false;
+            let cancelUnderlying = null;
+            const finish = (value) => {
+                if (finished) return;
+                finished = true;
+                cancelWait = null;
+                resolve(value);
+            };
+            cancelWait = () => {
+                cancelUnderlying?.();
+                finish(null);
+            };
+            const pending = ctx.waitFor(predicate, ms, (cancel) => {
+                cancelUnderlying = cancel;
+            });
+            Promise.resolve(pending).then((value) => finish(skipRequested || stopRequested ? null : value), () => finish(null));
+        }),
+    });
+    return {
+        scenarios: chosen,
+        wasStopped: () => stoppedAt,
+        skip() {
+            skipRequested = true;
+            cancelWait?.();
+            ctx.cancelVerdict?.();
+            ctx.skip?.();
+        },
+        stop() {
+            stopRequested = true;
+            skipRequested = true;
+            cancelWait?.();
+            ctx.cancelVerdict?.();
+            ctx.skip?.();
+        },
+        async run(scenario) {
+            if (!scenario) return result('skipped', 'No scenario selected.');
+            skipRequested = false;
+            ctx.beforeScenario?.();
+            const outcome = await runScenario(scenario, runContext());
+            if (stopRequested) stoppedAt = 1;
+            onScenario?.({ scenario, outcome });
+            return outcome;
+        },
+        async runAll() {
+            const results = [];
+            for (const [index, scenario] of chosen.entries()) {
+                if (stopRequested) {
+                    stoppedAt = index + 1;
+                    break;
+                }
+                skipRequested = false;
+                ctx.beforeScenario?.();
+                ctx.say?.(`${index + 1} / ${chosen.length} · ${scenario.title} — ${scenario.todo}`);
+                const outcome = await runScenario(scenario, runContext());
+                const item = { scenario, outcome };
+                results.push(item);
+                onScenario?.({ ...item, index, total: chosen.length });
+                if (outcome.warnings?.length) {
+                    stopRequested = true;
+                    ctx.say?.(`${scenario.title}: ${outcome.warnings.join('; ')}`);
+                }
+                if (outcome.status === 'needs-verdict' && !stopRequested) {
+                    await ctx.awaitVerdict?.(item);
+                }
+                if (outcome.status === 'needs-verdict' && stopRequested) {
+                    outcome.status = 'stopped';
+                    outcome.detail = 'Stopped while waiting for a verdict.';
+                } else if (outcome.status === 'needs-verdict' && skipRequested) {
+                    outcome.status = 'skipped';
+                    outcome.detail = 'Skipped while waiting for a verdict.';
+                }
+                if (stopRequested) {
+                    stoppedAt = index + 1;
+                    break;
+                }
+            }
+            return results;
+        },
+    };
+}

package/engine-shell/host/site-bridge.js

@@ -0,0 +1,87 @@
+/**
+ * The shell's side of the site's housegames bridge: the same messages, in
+ * the same shapes and order, that Coin Flip sends (coinflip-frontend
+ * src/core/bridge.js), so the site's header, round tracker and wallet
+ * reconciliation treat an engine game exactly like a House Original and
+ * need no code of their own for it.
+ *
+ *   round start   round-start, then balance {minus}             debit shown at once
+ *   settled       balance {set}       + round-end               server figure known
+ *                 balance {add payout} + round-end + reconcile  server figure deferred
+ *   rollback      balance {add stake, rollback} + round-end {rollback}
+ *   unknown       round-end + reconcile                         the site reads the wallet
+ *
+ * Messages go to the parent at its known origin only, never '*'. `gameId`
+ * is the catalog slug of the page, which the site matches exactly. The
+ * site's bar buttons come back as `housebets-game-control` once the game
+ * has said `controls-ready` (coinflip src/core/host-controls.js).
+ */
+const EV = {
+    roundStart: 'housebets-game-round-start',
+    roundEnd: 'housebets-game-round-end',
+    balance: 'housebets-game-balance',
+    reconcile: 'housebets-game-balance-reconciliation-request',
+};
+
+export function createSiteBridge({ parent, parentOrigin, gameId, currencyId }) {
+    const post = (msg) => {
+        if (parent && parentOrigin) parent.postMessage(msg, parentOrigin);
+    };
+    // round-start / round-end / reconcile are flat; balance is nested, its
+    // own `type` being the currency (the site's receiver expects both).
+    const flat = (type, detail) => post({ ...detail, type });
+    const balance = (detail) => post({ type: EV.balance, payload: { type: currencyId, gameId, ...detail } });
+    const ids = (r) => ({ gameId, currencyId, roundId: r.corr, generation: r.generation });
+
+    return {
+        roundStart(r) {
+            flat(EV.roundStart, { ...ids(r), amount: r.amount });
+            balance({ amount: r.amount, minus: true, roundId: r.corr, generation: r.generation });
+        },
+        roundEnd(r) {
+            const end = { ...ids(r), amount: r.amount };
+            const round = { roundId: r.corr, generation: r.generation, moment: true };
+            switch (r.outcome) {
+                case 'settled':
+                    if (r.balance !== null) {
+                        balance({ ...round, amount: r.balance, set: true, payout: r.payout });
+                        flat(EV.roundEnd, end);
+                    } else {
+                        balance({ ...round, amount: r.payout, add: true, payout: r.payout });
+                        flat(EV.roundEnd, end);
+                        flat(EV.reconcile, ids(r));
+                    }
+                    return;
+                case 'rollback':
+                    balance({ ...round, amount: r.amount, add: true, rollback: true });
+                    flat(EV.roundEnd, { ...end, rollback: true });
+                    return;
+                default: // unknown
+                    flat(EV.roundEnd, end);
+                    flat(EV.reconcile, ids(r));
+            }
+        },
+        ready: () => {
+            post({ message: 'gameLoaded', data: { progress: 100 } });
+            post({ type: 'housebets-game-controls-ready' });
+        },
+        /**
+         * The site's bar and bet history: onControl gets the whole
+         * `housebets-game-control` envelope, as the Originals read it
+         * (limbo host-controls.js) — a bare `{action}` from the bar ('sound',
+         * 'speed', 'settings', 'rules', 'provably-fair'), the page's report
+         * of the player's own trusted press or key on it ('site-input', for
+         * the click gate), or the history's
+         * `{action: 'provably-fair', gameType, roundId, requestId}` and its
+         * `provably-fair-cancel`, whose round fields the reader needs whole.
+         * From the parent at its origin only: the game frame cannot send one.
+         */
+        listen(onControl, self = window) {
+            self.addEventListener('message', (e) => {
+                if (e.source !== parent || e.origin !== parentOrigin) return;
+                const d = e.data;
+                if (d && typeof d === 'object' && d.type === 'housebets-game-control' && typeof d.action === 'string') onControl(d);
+            });
+        },
+    };
+}