ravensight-playtest 0.3.1 → 0.4.0

package/src/commands/simulate.js

@@ -0,0 +1,298 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createContext, resolveGameId, CLI_VERSION, ui } from '../api/index.js';
+import { createHeartbeat } from '../run/heartbeat.js';
+import { readBridgeConfig } from '../run/drivers/stdio.js';
+import { runBatch, replayTrace, validateConfig, probeBridge } from '../simulation/index.js';
+import { jobLink } from '../dashboard.js';
+import { CliError } from '../errors.js';
+import EXIT from '../run/exit.js';
+
+const MODULES = ['balance_sim', 'aggregate_report'];
+const TERMINAL = new Set(['succeeded', 'failed', 'canceled', 'budget_exceeded', 'skipped', 'stalled']);
+const money = cents => `$${(cents / 100).toFixed(2)}`;
+const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+async function loadBridge(file) {
+  const bridge = await readBridgeConfig(file);
+  return { ...bridge, cwd: bridge.cwd || path.dirname(file) };
+}
+
+export function publicConfig(config) {
+  return { version: config.version, seed: config.seed, runs: config.runs, max_steps: config.max_steps,
+    workers: config.workers, strategies: config.strategies.map(({ name, policy }) => ({ name, policy })) };
+}
+
+async function jsonFile(file, maxBytes = 64000) {
+  if ((await stat(file)).size > maxBytes) throw new CliError(`File exceeds ${maxBytes} bytes: ${file}`);
+  return JSON.parse(await readFile(file, 'utf8'));
+}
+
+async function save(file, value) {
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+    await rename(temporary, file);
+  } finally { await unlink(temporary).catch(() => {}); }
+}
+
+// Exclusive per-journal execution. A dead process's lock is recoverable; a live
+// process cannot have its paid run restarted underneath it by another shell.
+async function acquire(file) {
+  const lock = `${file}.lock`;
+  await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const handle = await open(lock, 'wx', 0o600);
+      await handle.writeFile(String(process.pid));
+      await handle.close();
+      return () => unlink(lock).catch(() => {});
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const pid = Number(await readFile(lock, 'utf8'));
+      if (!Number.isInteger(pid) || pid < 1) throw new CliError(`Unreadable simulation lock: ${lock}`);
+      try { process.kill(pid, 0); }
+      catch (probe) {
+        if (probe.code === 'ESRCH' && attempt === 0) { await unlink(lock); continue; }
+      }
+      throw new CliError('This simulation journal is already in use. Wait for the other runner to stop.');
+    }
+  }
+}
+
+function assertQuote(quote) {
+  if (quote?.execution_mode !== 'direct_command_batch' || !quote.simulation_limits ||
+      !Number.isSafeInteger(quote.estimate_cents) || quote.estimate_cents <= 0 ||
+      quote.breakdown?.length !== 1 || quote.breakdown[0].unit !== 'playtest_run' ||
+      quote.breakdown[0].count !== 1 || quote.breakdown[0].unit_cents !== quote.estimate_cents) {
+    throw new CliError('This server did not quote a paid Simulation Runner batch. Nothing was registered or charged. Update the server and CLI together.');
+  }
+}
+
+/** One confirmed purchase, a local batch, then bounded evidence to the same job. */
+export async function simulateCommand(flags = {}, injected = {}) {
+  const output = injected.ui || ui;
+  const repoRoot = path.resolve(flags.repoRoot || process.cwd());
+  let journal, file;
+  if (flags.resume) {
+    if (flags.configFile || flags.driverConfig) throw new CliError('Resume uses the original config and bridge. Do not combine --resume with --config or --driver-config.');
+    file = path.resolve(repoRoot, flags.resume);
+    journal = await jsonFile(file, 2 * 1024 * 1024);
+    if (journal.version !== 1 || journal.kind !== 'simulation' || !journal.idempotency_key ||
+        !journal.game_id || !journal.api_url || !journal.config || !journal.registration) {
+      throw new CliError('This is not a Simulation Runner journal.');
+    }
+    if (flags.game && flags.game !== journal.game_id) throw new CliError('Resume must use the original game.');
+    if (flags.apiUrl && flags.apiUrl.replace(/\/+$/, '') !== journal.api_url) throw new CliError('Resume must use the original API host.');
+  } else {
+    if (!flags.configFile) throw new CliError('Supply --config simulation.json, or --resume <state.json>.');
+    const configFile = path.resolve(repoRoot, flags.configFile);
+    const { driver_config: configDriver, ...raw } = await jsonFile(configFile);
+    const config = validateConfig(raw);
+    const driverFile = flags.driverConfig ? path.resolve(repoRoot, flags.driverConfig)
+      : typeof configDriver === 'string' ? path.resolve(path.dirname(configFile), configDriver) : null;
+    if (!driverFile) throw new CliError('Supply --driver-config bridge.json or driver_config in the simulation config.');
+    const bridge = await loadBridge(driverFile);
+    journal = { version: 1, kind: 'simulation', idempotency_key: randomUUID(), config,
+      bridge_file: driverFile, bridge_hash: hash(bridge), created_at: new Date().toISOString(), finished: false };
+    file = path.join(repoRoot, '.ravensight', 'simulations', journal.idempotency_key, 'state.json');
+  }
+  validateConfig(journal.config);
+  const context = await (injected.createContext || createContext)({ apiUrl: journal.api_url || flags.apiUrl, repoRoot, requireAuth: true });
+  if (journal.api_url && context.apiUrl.replace(/\/+$/, '') !== journal.api_url) throw new CliError('The API host changed. Resume was refused.');
+  const api = context.api;
+  const gameId = journal.game_id || resolveGameId(flags, context.config);
+  const release = await acquire(file);
+  const controller = new AbortController();
+  const target = injected.process || process;
+  const stop = () => controller.abort(new Error('Simulation canceled.'));
+  target.once('SIGINT', stop);
+  target.once('SIGTERM', stop);
+  let heartbeat;
+  const persist = () => save(file, journal);
+  const settledExit = state => journal.canceled || state === 'canceled' ? EXIT.CANCELED
+    : state !== 'succeeded' || (journal.summary && (!journal.summary.completed_runs || journal.summary.failed_runs || journal.summary.truncated_runs)) ? EXIT.FAILED : EXIT.OK;
+  const recover = () => output.error(`Recover this same purchase with: ravensight-playtest simulate --resume ${JSON.stringify(file)}`);
+  try {
+    if (journal.finished) {
+      if (flags.json) output.json({ job_id: journal.job_id, finished: true, summary: journal.summary });
+      else output.info(`This batch is already finished: ${jobLink(gameId, journal.job_id, context.apiUrl)}`);
+      return journal.exit_code ?? EXIT.OK;
+    }
+    if (journal.job_id) {
+      const { job } = await api.jobs.get(gameId, journal.job_id);
+      if (TERMINAL.has(job.state)) {
+        journal.finished = true;
+        journal.exit_code = settledExit(job.state);
+        await persist();
+        if (flags.json) output.json({ job_id: journal.job_id, finished: true, state: job.state });
+        else output.info(`The server already settled this batch as ${job.state}. No simulation was restarted.`);
+        return journal.exit_code;
+      }
+      // A completed run can await job settlement after an interrupted finish.
+      // Neither adapter files nor local execution are needed to settle it.
+      if (!journal.summary && journal.run_id) {
+        const { run: existing } = await api.runs.get(gameId, journal.job_id, journal.run_id);
+        if (TERMINAL.has(existing.state)) {
+          await api.jobs.finish(gameId, journal.job_id, {});
+          journal.finished = true; journal.exit_code = settledExit(existing.state); await persist();
+          if (flags.json) output.json({ job_id: journal.job_id, finished: true, state: existing.state });
+          else output.info(`This run already finished as ${existing.state}; its job is now settled.`);
+          return journal.exit_code;
+        }
+      }
+      if (job.cancel_requested) controller.abort(new Error('Simulation canceled on the server.'));
+    }
+    let bridge;
+    if (!journal.summary) {
+      bridge = await loadBridge(journal.bridge_file);
+      if (hash(bridge) !== journal.bridge_hash) throw new CliError('The bridge configuration changed. Restore it before resuming this purchase.');
+      if (!controller.signal.aborted) await (injected.probeBridge || probeBridge)({ bridge, seed: journal.config.seed,
+        strategy: journal.config.strategies[0].name, max_steps: journal.config.max_steps, signal: controller.signal });
+    }
+    if (!journal.registration) {
+      const simulation = publicConfig(journal.config);
+      const quote = await api.jobs.estimate(gameId, { modules: MODULES, personas: [], simulation });
+      assertQuote(quote);
+      output.info(`One simulation batch: ${journal.config.runs} games across ${journal.config.strategies.length} strategies, ${money(quote.estimate_cents)} total from prepaid balance.`);
+      output.info('Game execution and replay traces stay local. Only the bounded summary is uploaded. This is a mechanics test, not a test of the player interface.');
+      if (quote.ok === false) throw new CliError(`Insufficient prepaid balance (${money(quote.balance_cents)}). Nothing was charged.`, EXIT.ENVIRONMENT);
+      if (!flags.yes && !await (injected.confirm || output.confirm)(`Start this batch for ${money(quote.estimate_cents)}?`)) return EXIT.CANCELED;
+      if (controller.signal.aborted) return EXIT.CANCELED;
+      journal.api_url = context.apiUrl.replace(/\/+$/, '');
+      journal.game_id = gameId;
+      journal.limits = quote.simulation_limits;
+      journal.registration = { modules: MODULES, personas: [], driver: 'cli_stdio', simulation,
+        cli_version: CLI_VERSION, confirm_price_cents: quote.estimate_cents,
+        build: { kind: 'simulation', ref: hash(simulation) } };
+      // Durable BEFORE the money request. A lost register response replays the
+      // same idempotency key, even when no job_id ever reached this machine.
+      await persist();
+      output.info(`Recovery journal: ${file}`);
+    }
+
+    let registered;
+    try { registered = await api.jobs.register(gameId, journal.registration, { idempotencyKey: journal.idempotency_key }); }
+    catch (error) { recover(); throw error; }
+    journal.job_id = registered.job_id;
+    const run = registered.runs?.find(entry => entry.module === 'balance_sim');
+    if (!run || !run.playtest_token) {
+      await api.jobs.finish(gameId, journal.job_id, { state: 'failed', reason: 'Simulation run or synthetic token missing.' });
+      throw new CliError('The server did not create an executable simulation run. The job was stopped.');
+    }
+    journal.run_id = run.run_id;
+    await persist();
+    let current = flags.resume ? (await api.runs.get(gameId, journal.job_id, run.run_id)).run : run;
+    if (TERMINAL.has(current.state)) {
+      await api.jobs.finish(gameId, journal.job_id, {});
+      journal.finished = true;
+      journal.exit_code = settledExit(current.state);
+      await persist();
+      if (flags.json) output.json({ job_id: journal.job_id, finished: true, state: current.state });
+      else output.info(`This run already finished as ${current.state}; its job is now settled.`);
+      return journal.exit_code;
+    }
+    const transition = async state => {
+      if (current.state !== state) {
+        await api.runs.transition(gameId, journal.job_id, run.run_id, state);
+        current = { ...current, state };
+      }
+    };
+    heartbeat = (injected.createHeartbeat || createHeartbeat)({ api, gameId, jobId: journal.job_id, runId: run.run_id,
+      onCancel: stop, onError: error => {
+        if ([401, 403, 404, 409].includes(error.status)) controller.abort(new Error('The server closed this run.'));
+      } });
+    heartbeat.start();
+    await heartbeat.beat();
+    if (!journal.summary) {
+      if (['reporting', 'uploading'].includes(current.state)) throw new CliError('The local simulation summary is missing. Restore the journal before finishing this paid run.');
+      if (['queued', undefined].includes(current.state)) await transition('launching');
+      await transition('playing');
+      try {
+        // A crash can leave an incomplete results.jsonl. Preserve it and use a
+        // new directory for the deterministic restart of the same paid run.
+        journal.attempt_directory = path.join(path.dirname(file), `attempt-${randomUUID()}`);
+        await persist();
+        const result = await (injected.runBatch || runBatch)({ config: journal.config,
+          bridge: { ...bridge, batchTimeoutMs: Math.min(900000, (run.limits?.wall_seconds || run.budget?.wall_seconds_max || journal.limits?.wall_seconds_max || 900) * 1000) },
+          outputDir: journal.attempt_directory,
+          playtest: { token: run.playtest_token, runId: run.run_id, jobId: journal.job_id }, signal: controller.signal,
+          onProgress: progress => {
+            if (progress.finished_runs % 100 === 0 || progress.finished_runs === progress.requested_runs) {
+              output.info(`${progress.finished_runs}/${progress.requested_runs} games processed; ${progress.completed_runs} completed, ${progress.failed_runs} failed, ${progress.truncated_runs} reached a limit.`);
+              void heartbeat.beat({ actionsTaken: progress.total_steps, checkpointStep: progress.finished_runs });
+            }
+          } });
+        journal.summary = result.summary;
+        journal.traces = result.traces;
+        journal.local_report = result.report;
+        journal.canceled = controller.signal.aborted;
+        await persist();
+      } catch (error) {
+        // No usable local result exists. Complete and settle through the same
+        // server refund path; neither a second charge nor a local refund.
+        try {
+          await api.runs.complete(gameId, journal.job_id, run.run_id, { state: 'failed', quit_reason: 'error', reason: 'Local simulation could not produce a summary.' });
+          await api.jobs.finish(gameId, journal.job_id, { reason: 'Local simulation failed.' });
+          journal.finished = true; journal.exit_code = EXIT.FAILED; await persist();
+        } catch { recover(); }
+        throw error;
+      }
+    }
+    const useful = journal.summary.completed_runs > 0;
+    try {
+      if (useful) {
+        if (current.state !== 'uploading') await transition('reporting');
+        await transition('uploading');
+      }
+      await api.runs.complete(gameId, journal.job_id, run.run_id, {
+        state: useful ? 'succeeded' : 'failed', simulation: journal.summary,
+        actions_taken: journal.summary.total_steps, quit_reason: useful ? 'goal_reached' : 'error'
+      });
+      await api.jobs.finish(gameId, journal.job_id, {});
+    } catch (error) {
+      // Keep valid results for retry. A dropped complete/finish response is
+      // ambiguous, so do not overwrite success with failed or buy another job.
+      recover();
+      throw error;
+    }
+    journal.finished = true;
+    journal.exit_code = journal.canceled ? EXIT.CANCELED :
+      (!useful || journal.summary.failed_runs || journal.summary.truncated_runs) ? EXIT.FAILED : EXIT.OK;
+    await persist();
+    if (flags.json) output.json({ job_id: journal.job_id, summary: journal.summary, traces: journal.traces, journal: file });
+    else {
+      output.info(`Simulation report: ${jobLink(gameId, journal.job_id, context.apiUrl)}`);
+      output.info(`Local summary and replay traces: ${path.dirname(file)}`);
+      if (!useful) output.info('No game reached a terminal result. The server settles this batch without keeping its Playtest unit.');
+    }
+    return journal.exit_code;
+  } finally {
+    heartbeat?.stop();
+    target.removeListener('SIGINT', stop);
+    target.removeListener('SIGTERM', stop);
+    await release();
+  }
+}
+
+export async function replayCommand(trace, flags = {}, injected = {}) {
+  const output = injected.ui || ui;
+  const repo = path.resolve(flags.repoRoot || process.cwd());
+  const bridge = await loadBridge(path.resolve(repo, flags.driverConfig));
+  const controller = new AbortController();
+  const stop = () => controller.abort(new Error('Replay canceled.'));
+  const target = injected.process || process;
+  target.once('SIGINT', stop); target.once('SIGTERM', stop);
+  try {
+    const result = await (injected.replayTrace || replayTrace)({ trace: path.resolve(repo, trace), bridge, signal: controller.signal });
+    if (flags.json) output.json(result);
+    else output.info(result.matched
+      ? result.fully_replayed === false
+        ? result.failure_reproduced ? 'Replay matched the recorded prefix and reproduced the recorded failure.'
+          : 'Replay matched the recorded prefix only. The trace does not establish a complete playthrough.'
+        : 'Replay matched every recorded state, outcome and metric.'
+      : `Replay diverged: ${JSON.stringify(result.first_divergence)}. Check the game seed, build and external dependencies.`);
+    return result.matched ? EXIT.OK : EXIT.FAILED;
+  } finally { target.removeListener('SIGINT', stop); target.removeListener('SIGTERM', stop); }
+}

package/src/run/args.js

@@ -35,6 +35,9 @@ const BOOLEAN = new Map([
   ['--headed', 'headed'],
   ['--headless', 'headless'],
   ['--verbose', 'verbose'],
+  // A long persona run: twice the actions, model budget and wall time of a
+  // standard run, priced by the server as its own unit.
+  ['--long', 'long'],
   // Native drivers only: register without the free automation probe first.
   ['--skip-preflight', 'skipPreflight'],
   // Resume only: replay an interrupted run from the start instead of writing a
@@ -106,6 +109,7 @@ export function optionsFrom(flags = {}) {
   return {
     options: {
       ...options,
+      runLength: runLengthFor(options),
       ...stripUndefined({
         repo: flags.repoRoot || flags.repo,
         apiUrl: flags.apiUrl,
@@ -128,8 +132,21 @@ export function optionsFrom(flags = {}) {
   };
 }
 
+/** The two run lengths the server prices: `standard`, and `long` at twice a standard run. */
+export const RUN_LENGTHS = Object.freeze(['standard', 'long']);
+
+/**
+ * `long` when `--long` was passed, otherwise `standard`.
+ *
+ * @param {{long?: boolean}} options
+ * @returns {'standard'|'long'}
+ */
+export function runLengthFor(options = {}) {
+  return options.long === true ? 'long' : 'standard';
+}
+
 function stripUndefined(value) {
   return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
 }
 
-export default { parseRunArgv, optionsFrom, unknownOptionNotes };
+export default { parseRunArgv, optionsFrom, unknownOptionNotes, runLengthFor };