@datamoc/mw_games 0.43.0 → 0.45.0

package/dist/simulation/Training.d.ts

@@ -1,220 +0,0 @@
-import { Generator } from '../core/Random.ts';
-import type { ReplayEvent } from '../core/Replay.ts';
-import type { NeuralModel, NeuralObservation } from '../ai/Neural.ts';
-import type { SimulationRule, SimulationStep } from './Scenario.ts';
-export interface TrainingRules<State, Command, Event> {
-    observationVersion: string;
-    initial(random: Generator): State;
-    /** Same rule used by the playable game; a command may advance a turn or fixed ticks. */
-    rule: SimulationRule<State, Command, Event, Generator>;
-    observe(state: State): readonly NeuralObservation[];
-    command(state: State, actions: readonly (number | null)[]): Command;
-    /** One reward per agent, in the observation's stable roster order. */
-    rewards(before: State, command: Command, outcome: SimulationStep<State, Event>): readonly number[];
-    /** Detect an already-terminal reset, without taking a dummy action. */
-    finished?(state: State): boolean;
-}
-export interface TrainingFrame {
-    observations: readonly NeuralObservation[];
-    rewards: readonly number[];
-    terminated: boolean;
-    truncated: boolean;
-}
-export interface TrainingSnapshot<State> {
-    version: 1;
-    observationVersion: string;
-    state: State;
-    seed: number;
-    random: readonly [number, number, number, number];
-    steps: number;
-    maxSteps: number;
-    terminated: boolean;
-    truncated: boolean;
-}
-/** A trainer persists its optimizer/exploration state alongside the environment and model. */
-export interface TrainingCheckpoint<State, TrainerState> {
-    version: 1;
-    model: NeuralModel;
-    environment: TrainingSnapshot<State>;
-    trainerState: TrainerState;
-}
-/**
- * Seeded, UI-free reset/step adapter over a game's existing SimulationRule.
- * Observations and rewards use a fixed agent roster within each episode. A null
- * action is legal only when all actions for that agent are masked. The rule owns
- * idle semantics. No presentation events or command journal are retained.
- *
- * @example
- * ```ts
- * import { TrainingEnvironment } from '@datamoc/mw_games/simulation';
- * const env = new TrainingEnvironment({ observationVersion: 'counter-v1',
- *   initial: () => ({ x: 0 }), observe: s => [{ input: [s.x], mask: [true] }],
- *   command: (_s, actions) => actions[0],
- *   rule: s => ({ state: { x: s.x + 1 }, events: [], status: 'ready' }),
- *   rewards: () => [1],
- * }, { maxSteps: 10 });
- * env.reset(7);
- * const frame = env.step([0]);
- * const checkpoint = env.snapshot();
- * env.restore(checkpoint); // resumes state and RNG, without replaying reset
- * ```
- */
-export declare class TrainingEnvironment<State, Command, Event> {
-    private state;
-    private random;
-    private steps;
-    private terminated;
-    private ready;
-    private agentCount;
-    readonly maxSteps: number;
-    readonly observationVersion: string;
-    private readonly rules;
-    private readonly Random;
-    private get truncated();
-    constructor(rules: TrainingRules<State, Command, Event>, options: {
-        maxSteps: number;
-    }, Random?: typeof Generator);
-    reset(seed: number): TrainingFrame;
-    step(actions: readonly (number | null)[]): TrainingFrame;
-    snapshot(): TrainingSnapshot<State>;
-    restore(snapshot: TrainingSnapshot<State>): TrainingFrame;
-    private observations;
-}
-export interface RolloutOptions {
-    seeds: readonly number[];
-    /** Sample softmax scores using a separate seeded stream, leaving game RNG unchanged. */
-    sample?: boolean;
-    /** First transitions per episode to keep; defaults to zero, at most 10000 total per batch. */
-    trajectoryLimit?: number;
-    signal?: AbortSignal;
-}
-export interface TrainingTransition {
-    before: TrainingFrame;
-    actions: readonly (number | null)[];
-    after: TrainingFrame;
-}
-export interface RolloutEpisode {
-    seed: number;
-    steps: number;
-    rewards: number[];
-    terminated: boolean;
-    truncated: boolean;
-    trajectory: TrainingTransition[];
-}
-/**
- * Interactive rollouts at simulation speed, with a fresh seeded reset per episode.
- * The evaluator is created once per batch and shares its buffers across agents.
- * A synchronous signal is checked between steps; cancellation from another event
- * on the same thread requires the async worker path.
- *
- * @example
- * ```ts
- * import { runRollouts, TrainingEnvironment } from '@datamoc/mw_games/simulation';
- * import type { NeuralModel } from '@datamoc/mw_games/ai';
- * declare const env: TrainingEnvironment<{ x: number }, number, never>;
- * declare const model: NeuralModel;
- * const episodes = runRollouts(env, model, { seeds: [1, 2, 3], trajectoryLimit: 2 });
- * ```
- */
-export declare function runRollouts<State, Command, Event>(environment: TrainingEnvironment<State, Command, Event>, model: NeuralModel, options: RolloutOptions): RolloutEpisode[];
-/** Factory must be self-contained, like threads.spawn; use the supplied constructor rather than imports. */
-export type TrainingFactory<Config, State, Command, Event> = (tools: {
-    TrainingEnvironment: typeof TrainingEnvironment;
-}, config: Config) => TrainingEnvironment<State, Command, Event>;
-/**
- * One worker per episode shard, with isolated environments and bounded concurrency.
- * A model and environment stay loaded for the shard's whole batch. Returned episodes
- * stay in seed order independent of worker completion order. Abort or failure kills
- * every lane; no partial result is applied to a game. Keep the factory self-contained
- * and pass structured-cloneable configuration, not closures or class instances.
- *
- * @example
- * ```ts
- * import { runRolloutsAsync, type TrainingFactory } from '@datamoc/mw_games/simulation';
- * import type { NeuralModel } from '@datamoc/mw_games/ai';
- * declare const factory: TrainingFactory<{ maxSteps: number }, { x: number }, number, never>;
- * declare const model: NeuralModel;
- * const episodes = await runRolloutsAsync(factory, { maxSteps: 20 }, model, { seeds: [1, 2], jobs: 2 });
- * ```
- */
-export declare function runRolloutsAsync<Config, State, Command, Event>(factory: TrainingFactory<Config, State, Command, Event>, config: Config, model: NeuralModel, options: RolloutOptions & {
-    jobs?: number;
-    timeout?: number;
-}): Promise<RolloutEpisode[]>;
-export interface ImitationSample {
-    /** the observation the recorded action was taken against */
-    observation: NeuralObservation;
-    /** the recorded action's index in the caller's `actions` list */
-    action: number;
-    /** the frame the action was recorded on */
-    frame: number;
-}
-export interface ImitationResult {
-    samples: readonly ImitationSample[];
-    /** env steps taken, one per recorded event reached */
-    steps: number;
-    terminated: boolean;
-    truncated: boolean;
-}
-/**
- * Turns a persisted run into imitation targets: walks the recorded actions against the same
- * seeded environment they were played on, and hands back the (observation, action) pairs a
- * game's own trainer fits - the same shape the maze chase example fits, but sourced from how
- * the game's own players played rather than a generated expert.
- *
- * One recorded event is one environment step, so a turn-based game steps once per action
- * taken; a tick-based game whose rule needs an explicit idle records one, since a frame
- * without an event advances nothing here. The environment must expose exactly one agent
- * (the recorded player); anything else that moves is part of the rule, the way the maze
- * chase's ghosts are. A recorded action outside the list is a named error, not a skipped
- * event: every sample after a skipped one would be off-trajectory.
- *
- * @example
- * ```ts
- * import { TrainingEnvironment, imitationFromReplay } from '@datamoc/mw_games/simulation';
- * declare const env: TrainingEnvironment<{ x: number }, number, never>;
- * const result = imitationFromReplay(env, {
- * 	actions: ['left', 'right'],
- * 	events: [{ frame: 0, action: 'right' }],
- * 	seed: 7,
- * });
- * console.log(result.samples[0].action); // 1: 'right'
- * ```
- */
-export declare function imitationFromReplay<State, Command, Event>(environment: TrainingEnvironment<State, Command, Event>, options: {
-    actions: readonly string[];
-    events: readonly ReplayEvent[];
-    seed: number;
-}): ImitationResult;
-/** The record of one AI-played run from a seed, reproducible on demand. */
-export interface SeededRun {
-    seed: number;
-    steps: number;
-    /** the chosen actions, one array per step, in the env's roster order */
-    actions: readonly (readonly (number | null)[])[];
-    /** cumulative reward per agent over the whole run */
-    rewards: readonly number[];
-    terminated: boolean;
-    truncated: boolean;
-}
-/**
- * Plays one whole run with the AI choosing, from a named seed: the same seed and the same
- * `choose` make the same decisions, so a run is comparable between builds, policies and
- * machines. `choose` must be deterministic for that to hold - the deterministic argmax of a
- * `NeuralPolicy`, a heuristic's fixed candidate order - and receives the env's full roster,
- * returning one action per agent. Unlike `runRollouts`, the chooser is not a `NeuralModel`:
- * a heuristic policy, a trained model behind `NeuralPolicy.selectAction`, or any function a
- * benchmark can name works the same way. The env's own `maxSteps` is the truncation bound.
- *
- * @example
- * ```ts
- * import { TrainingEnvironment, runSeededEpisode } from '@datamoc/mw_games/simulation';
- * declare const env: TrainingEnvironment<{ x: number }, number, never>;
- * const run = runSeededEpisode(env, (observations) => [0], { seed: 7 });
- * console.log(run.steps, run.terminated);
- * ```
- */
-export declare function runSeededEpisode<State, Command, Event>(environment: TrainingEnvironment<State, Command, Event>, choose: (observations: readonly NeuralObservation[]) => readonly (number | null)[], options: {
-    seed: number;
-}): SeededRun;
-//# sourceMappingURL=Training.d.ts.map

package/dist/simulation/Training.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Training.d.ts","sourceRoot":"","sources":["../../src/simulation/Training.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpE,MAAM,WAAW,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK;IACnD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG,KAAK,CAAC;IAClC,wFAAwF;IACxF,IAAI,EAAE,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;IACvD,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,iBAAiB,EAAE,CAAC;IACpD,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,OAAO,CAAC;IACpE,sEAAsE;IACtE,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,SAAS,MAAM,EAAE,CAAC;IACnG,uEAAuE;IACvE,QAAQ,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC7B,YAAY,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC3C,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB,CAAC,KAAK;IACtC,OAAO,EAAE,CAAC,CAAC;IACX,kBAAkB,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACnB;AAED,8FAA8F;AAC9F,MAAM,WAAW,kBAAkB,CAAC,KAAK,EAAE,YAAY;IACtD,OAAO,EAAE,CAAC,CAAC;IACX,KAAK,EAAE,WAAW,CAAC;IACnB,WAAW,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACrC,YAAY,EAAE,YAAY,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK;IACrD,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,UAAU,CAAK;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAE1C,OAAO,KAAK,SAAS,GAEpB;IAED,YAAY,KAAK,EAAE,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,MAAM,mBAAY,EAUzG;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAWjC;IAED,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,aAAa,CA6BvD;IAED,QAAQ,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAalC;IAED,OAAO,CAAC,QAAQ,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,aAAa,CAsCxD;IAED,OAAO,CAAC,YAAY;CAkBpB;AAED,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,wFAAwF;IACxF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8FAA8F;IAC9F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC;IACpC,KAAK,EAAE,aAAa,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,kBAAkB,EAAE,CAAC;CACjC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAChD,WAAW,EAAE,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EACvD,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,cAAc,GACrB,cAAc,EAAE,CAGlB;AAmDD,4GAA4G;AAC5G,MAAM,MAAM,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,CAC5D,KAAK,EAAE;IAAE,mBAAmB,EAAE,OAAO,mBAAmB,CAAA;CAAE,EAC1D,MAAM,EAAE,MAAM,KACV,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;AAwBhD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EACnE,OAAO,EAAE,eAAe,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EACvD,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,cAAc,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3D,OAAO,CAAC,cAAc,EAAE,CAAC,CAsC3B;AAED,MAAM,WAAW,eAAe;IAC/B,4DAA4D;IAC5D,WAAW,EAAE,iBAAiB,CAAC;IAC/B,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EACxD,WAAW,EAAE,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EACvD,OAAO,EAAE;IAAE,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACnF,eAAe,CAoBjB;AAED,2EAA2E;AAC3E,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;IACjD,qDAAqD;IACrD,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EACrD,WAAW,EAAE,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EACvD,MAAM,EAAE,CAAC,YAAY,EAAE,SAAS,iBAAiB,EAAE,KAAK,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,EAClF,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GACvB,SAAS,CAmBX"}

package/dist/simulation/Training.js

@@ -1,366 +0,0 @@
-import { Generator } from '../core/Random.js';
-import { parseReplayEvents } from '../core/Replay.js';
-import { createNeuralEvaluator } from '../ai/Neural.js';
-import { spawn } from '../threads/index.js';
-/**
- * Seeded, UI-free reset/step adapter over a game's existing SimulationRule.
- * Observations and rewards use a fixed agent roster within each episode. A null
- * action is legal only when all actions for that agent are masked. The rule owns
- * idle semantics. No presentation events or command journal are retained.
- *
- * @example
- * ```ts
- * import { TrainingEnvironment } from '@datamoc/mw_games/simulation';
- * const env = new TrainingEnvironment({ observationVersion: 'counter-v1',
- *   initial: () => ({ x: 0 }), observe: s => [{ input: [s.x], mask: [true] }],
- *   command: (_s, actions) => actions[0],
- *   rule: s => ({ state: { x: s.x + 1 }, events: [], status: 'ready' }),
- *   rewards: () => [1],
- * }, { maxSteps: 10 });
- * env.reset(7);
- * const frame = env.step([0]);
- * const checkpoint = env.snapshot();
- * env.restore(checkpoint); // resumes state and RNG, without replaying reset
- * ```
- */
-export class TrainingEnvironment {
-    get truncated() {
-        return !this.terminated && this.steps >= this.maxSteps;
-    }
-    constructor(rules, options, Random = Generator) {
-        this.steps = 0;
-        this.terminated = false;
-        this.ready = false;
-        this.agentCount = 0;
-        this.rules = rules;
-        this.Random = Random;
-        this.random = new this.Random(0);
-        if (!Number.isInteger(options.maxSteps) || options.maxSteps < 1 || options.maxSteps > 1_000_000)
-            throw new RangeError('training maxSteps must be in 1..1000000');
-        if (typeof rules.observationVersion !== 'string' || !rules.observationVersion.length)
-            throw new TypeError('training requires an observation version');
-        this.maxSteps = options.maxSteps;
-        this.observationVersion = rules.observationVersion;
-    }
-    reset(seed) {
-        if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff)
-            throw new RangeError('training seed must be uint32');
-        this.random = new this.Random(seed);
-        this.state = this.rules.initial(this.random);
-        this.steps = 0;
-        this.terminated = this.rules.finished?.(this.state) ?? false;
-        this.ready = true;
-        const observations = this.observations();
-        this.agentCount = observations.length;
-        return { observations, rewards: observations.map(() => 0), terminated: this.terminated, truncated: false };
-    }
-    step(actions) {
-        if (!this.ready || this.terminated || this.truncated)
-            throw new Error('training episode needs reset before step');
-        const observations = this.observations();
-        if (actions.length !== this.agentCount)
-            throw new RangeError('training action count must match the agent roster');
-        for (let i = 0; i < actions.length; i++) {
-            const action = actions[i];
-            const mask = observations[i].mask;
-            if (action === null
-                ? !mask || mask.some(Boolean)
-                : !Number.isInteger(action) || action < 0 || (mask && (action >= mask.length || !mask[action])))
-                throw new RangeError('training action is not legal');
-        }
-        //Rewards can inspect a mutable rule's pre-transition state without keeping a history.
-        const before = structuredClone(this.state);
-        const command = this.rules.command(this.state, actions);
-        const outcome = this.rules.rule(this.state, command, this.random);
-        const rewards = Array.from(this.rules.rewards(before, command, outcome));
-        if (rewards.length !== this.agentCount || !rewards.every(Number.isFinite))
-            throw new TypeError('training rewards must be finite and match the agent roster');
-        this.state = outcome.state;
-        this.steps++;
-        this.terminated = outcome.status === 'finished';
-        const next = this.observations();
-        if (next.length !== this.agentCount)
-            throw new RangeError('training agent roster changed during an episode');
-        return { observations: next, rewards, terminated: this.terminated, truncated: this.truncated };
-    }
-    snapshot() {
-        if (!this.ready)
-            throw new Error('training environment needs reset before snapshot');
-        return structuredClone({
-            version: 1,
-            observationVersion: this.observationVersion,
-            state: this.state,
-            seed: this.random.seed,
-            random: this.random.getState().map((value) => value >>> 0),
-            steps: this.steps,
-            maxSteps: this.maxSteps,
-            terminated: this.terminated,
-            truncated: this.truncated,
-        });
-    }
-    restore(snapshot) {
-        if (snapshot.version !== 1 ||
-            snapshot.observationVersion !== this.observationVersion ||
-            snapshot.maxSteps !== this.maxSteps)
-            throw new TypeError('training snapshot version, schema or step limit does not match');
-        if (!Number.isInteger(snapshot.steps) ||
-            snapshot.steps < 0 ||
-            snapshot.steps > this.maxSteps ||
-            !Number.isInteger(snapshot.seed) ||
-            snapshot.seed < 0 ||
-            snapshot.seed > 0xffffffff ||
-            !Array.isArray(snapshot.random) ||
-            snapshot.random.length !== 4 ||
-            !snapshot.random.every((value) => Number.isInteger(value) && value >= 0 && value <= 0xffffffff) ||
-            !snapshot.random.some((value) => value !== 0) ||
-            typeof snapshot.terminated !== 'boolean' ||
-            typeof snapshot.truncated !== 'boolean' ||
-            (snapshot.terminated && snapshot.truncated) ||
-            snapshot.truncated !== (!snapshot.terminated && snapshot.steps === this.maxSteps))
-            throw new TypeError('invalid training snapshot');
-        this.state = structuredClone(snapshot.state);
-        this.random = new this.Random(snapshot.seed);
-        this.random.setState(snapshot.random);
-        this.steps = snapshot.steps;
-        this.terminated = snapshot.terminated;
-        this.ready = true;
-        const observations = this.observations();
-        this.agentCount = observations.length;
-        return {
-            observations,
-            rewards: observations.map(() => 0),
-            terminated: this.terminated,
-            truncated: this.truncated,
-        };
-    }
-    observations() {
-        const observations = structuredClone(Array.from(this.rules.observe(this.state)));
-        if (!observations.length || observations.length > 4096)
-            throw new RangeError('training requires 1..4096 agents');
-        for (const observation of observations) {
-            if (!observation.input.length ||
-                observation.input.length > 4096 ||
-                !Array.from(observation.input).every(Number.isFinite) ||
-                (observation.mask &&
-                    (!observation.mask.length ||
-                        observation.mask.length > 4096 ||
-                        !Array.from(observation.mask).every((value) => typeof value === 'boolean'))))
-                throw new TypeError('invalid training observation');
-        }
-        return observations;
-    }
-}
-/**
- * Interactive rollouts at simulation speed, with a fresh seeded reset per episode.
- * The evaluator is created once per batch and shares its buffers across agents.
- * A synchronous signal is checked between steps; cancellation from another event
- * on the same thread requires the async worker path.
- *
- * @example
- * ```ts
- * import { runRollouts, TrainingEnvironment } from '@datamoc/mw_games/simulation';
- * import type { NeuralModel } from '@datamoc/mw_games/ai';
- * declare const env: TrainingEnvironment<{ x: number }, number, never>;
- * declare const model: NeuralModel;
- * const episodes = runRollouts(env, model, { seeds: [1, 2, 3], trajectoryLimit: 2 });
- * ```
- */
-export function runRollouts(environment, model, options) {
-    validateRolloutOptions(options);
-    return rolloutKernel(environment, model, options, { Generator, createNeuralEvaluator });
-}
-function validateRolloutOptions(options) {
-    const limit = options.trajectoryLimit ?? 0;
-    if (!options.seeds.length ||
-        options.seeds.length > 10000 ||
-        !Array.from(options.seeds).every((seed) => Number.isInteger(seed) && seed >= 0 && seed <= 0xffffffff) ||
-        !Number.isInteger(limit) ||
-        limit < 0 ||
-        limit * options.seeds.length > 10000)
-        throw new RangeError('rollouts require 1..10000 uint32 seeds and at most 10000 stored transitions');
-}
-//Explicit dependencies survive identifier renaming in a bundled file:// game.
-function rolloutKernel(environment, model, options, tools) {
-    if (model.observationVersion !== environment.observationVersion)
-        throw new TypeError('model observation schema does not match environment');
-    const limit = options.trajectoryLimit ?? 0;
-    const policy = tools.createNeuralEvaluator(model);
-    return Array.from(options.seeds, (seed) => {
-        if (options.signal?.aborted)
-            throw options.signal.reason;
-        const random = new tools.Generator((seed ^ 0x9e3779b9) >>> 0);
-        let frame = environment.reset(seed);
-        const rewards = frame.rewards.map(() => 0);
-        const trajectory = [];
-        let steps = 0;
-        while (!frame.terminated && !frame.truncated) {
-            if (options.signal?.aborted)
-                throw options.signal.reason;
-            const actions = frame.observations.map((observation) => policy.select(observation, options.sample ? () => random.float() : undefined));
-            const next = environment.step(actions);
-            for (let i = 0; i < rewards.length; i++) {
-                rewards[i] += next.rewards[i];
-                if (!Number.isFinite(rewards[i]))
-                    throw new RangeError('training cumulative reward overflow');
-            }
-            if (trajectory.length < limit)
-                trajectory.push({ before: frame, actions, after: next });
-            frame = next;
-            steps++;
-        }
-        return { seed, steps, rewards, terminated: frame.terminated, truncated: frame.truncated, trajectory };
-    });
-}
-//Rehydrate the very same classes and runner, not a second implementation of simulation or inference.
-function rolloutBatch(sources, config, model, options) {
-    const Generator = new Function(`return (${sources[0]});`)();
-    const createNeuralEvaluator = new Function(`return (${sources[1]});`)();
-    const Environment = new Function(`return (${sources[2]});`)();
-    //The serialized class's optional RNG default may be renamed by a bundler.
-    //Always inject it explicitly, so that expression is never evaluated in a worker.
-    const TrainingEnvironment = class extends Environment {
-        constructor(rules, options) {
-            super(rules, options, Generator);
-        }
-    };
-    const run = new Function(`return (${sources[3]});`)();
-    const factory = new Function(`return (${sources[4]});`)();
-    return run(factory({ TrainingEnvironment }, config), model, options, { Generator, createNeuralEvaluator });
-}
-/**
- * One worker per episode shard, with isolated environments and bounded concurrency.
- * A model and environment stay loaded for the shard's whole batch. Returned episodes
- * stay in seed order independent of worker completion order. Abort or failure kills
- * every lane; no partial result is applied to a game. Keep the factory self-contained
- * and pass structured-cloneable configuration, not closures or class instances.
- *
- * @example
- * ```ts
- * import { runRolloutsAsync, type TrainingFactory } from '@datamoc/mw_games/simulation';
- * import type { NeuralModel } from '@datamoc/mw_games/ai';
- * declare const factory: TrainingFactory<{ maxSteps: number }, { x: number }, number, never>;
- * declare const model: NeuralModel;
- * const episodes = await runRolloutsAsync(factory, { maxSteps: 20 }, model, { seeds: [1, 2], jobs: 2 });
- * ```
- */
-export async function runRolloutsAsync(factory, config, model, options) {
-    const jobs = options.jobs ?? 4;
-    if (!Number.isInteger(jobs) || jobs < 1 || jobs > 64)
-        throw new RangeError('rollout jobs must be in 1..64');
-    if (options.signal?.aborted)
-        throw options.signal.reason;
-    //Validate and bound the whole batch before sharding, without taking a simulation step.
-    const limit = options.trajectoryLimit ?? 0;
-    validateRolloutOptions(options);
-    createNeuralEvaluator(model);
-    const abort = new AbortController();
-    const cancel = () => abort.abort(options.signal?.reason);
-    options.signal?.addEventListener('abort', cancel, { once: true });
-    const sources = [
-        Generator.toString(),
-        createNeuralEvaluator.toString(),
-        TrainingEnvironment.toString(),
-        rolloutKernel.toString(),
-        factory.toString(),
-    ];
-    const lanes = Math.min(jobs, options.seeds.length);
-    try {
-        return (await Promise.all(Array.from({ length: lanes }, (_, lane) => {
-            const start = Math.floor((lane * options.seeds.length) / lanes);
-            const end = Math.floor(((lane + 1) * options.seeds.length) / lanes);
-            const seeds = options.seeds.slice(start, end);
-            return spawn(rolloutBatch, [sources, config, model, { seeds, sample: options.sample, trajectoryLimit: limit }], { signal: abort.signal, timeout: options.timeout });
-        }))).flat();
-    }
-    finally {
-        abort.abort();
-        options.signal?.removeEventListener('abort', cancel);
-    }
-}
-/**
- * Turns a persisted run into imitation targets: walks the recorded actions against the same
- * seeded environment they were played on, and hands back the (observation, action) pairs a
- * game's own trainer fits - the same shape the maze chase example fits, but sourced from how
- * the game's own players played rather than a generated expert.
- *
- * One recorded event is one environment step, so a turn-based game steps once per action
- * taken; a tick-based game whose rule needs an explicit idle records one, since a frame
- * without an event advances nothing here. The environment must expose exactly one agent
- * (the recorded player); anything else that moves is part of the rule, the way the maze
- * chase's ghosts are. A recorded action outside the list is a named error, not a skipped
- * event: every sample after a skipped one would be off-trajectory.
- *
- * @example
- * ```ts
- * import { TrainingEnvironment, imitationFromReplay } from '@datamoc/mw_games/simulation';
- * declare const env: TrainingEnvironment<{ x: number }, number, never>;
- * const result = imitationFromReplay(env, {
- * 	actions: ['left', 'right'],
- * 	events: [{ frame: 0, action: 'right' }],
- * 	seed: 7,
- * });
- * console.log(result.samples[0].action); // 1: 'right'
- * ```
- */
-export function imitationFromReplay(environment, options) {
-    const names = [...options.actions];
-    if (!names.length || names.some((name) => typeof name !== 'string'))
-        throw new TypeError('imitation needs the recorded action names in policy order');
-    const events = parseReplayEvents(options.events);
-    const frame = environment.reset(options.seed);
-    if (frame.observations.length !== 1)
-        throw new Error('imitation trains the recorded player alone: the environment must expose one agent');
-    const samples = [];
-    let current = frame;
-    let steps = 0;
-    for (const event of events) {
-        if (current.terminated || current.truncated)
-            break;
-        const action = names.indexOf(event.action);
-        if (action < 0)
-            throw new Error(`a recorded action ${JSON.stringify(event.action)} is not in the action list`);
-        samples.push({ observation: current.observations[0], action, frame: event.frame });
-        current = environment.step([action]);
-        steps++;
-    }
-    return { samples, steps, terminated: current.terminated, truncated: current.truncated };
-}
-/**
- * Plays one whole run with the AI choosing, from a named seed: the same seed and the same
- * `choose` make the same decisions, so a run is comparable between builds, policies and
- * machines. `choose` must be deterministic for that to hold - the deterministic argmax of a
- * `NeuralPolicy`, a heuristic's fixed candidate order - and receives the env's full roster,
- * returning one action per agent. Unlike `runRollouts`, the chooser is not a `NeuralModel`:
- * a heuristic policy, a trained model behind `NeuralPolicy.selectAction`, or any function a
- * benchmark can name works the same way. The env's own `maxSteps` is the truncation bound.
- *
- * @example
- * ```ts
- * import { TrainingEnvironment, runSeededEpisode } from '@datamoc/mw_games/simulation';
- * declare const env: TrainingEnvironment<{ x: number }, number, never>;
- * const run = runSeededEpisode(env, (observations) => [0], { seed: 7 });
- * console.log(run.steps, run.terminated);
- * ```
- */
-export function runSeededEpisode(environment, choose, options) {
-    let frame = environment.reset(options.seed);
-    const rewards = frame.rewards.map(() => 0);
-    const actions = [];
-    let steps = 0;
-    while (!frame.terminated && !frame.truncated) {
-        const chosen = choose(frame.observations);
-        if (!Array.isArray(chosen) || chosen.length !== frame.observations.length)
-            throw new RangeError('the seeded-run chooser must return one action per agent');
-        actions.push([...chosen]);
-        const next = environment.step(chosen);
-        for (let i = 0; i < rewards.length; i++) {
-            rewards[i] += next.rewards[i];
-            if (!Number.isFinite(rewards[i]))
-                throw new RangeError('seeded-run cumulative reward overflow');
-        }
-        frame = next;
-        steps++;
-    }
-    return { seed: options.seed, steps, actions, rewards, terminated: frame.terminated, truncated: frame.truncated };
-}
-//# sourceMappingURL=Training.js.map

package/dist/simulation/Training.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Training.js","sourceRoot":"","sources":["../../src/simulation/Training.ts"],"names":[],"mappings":"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"}

package/dist/simulation/Turns.d.ts

@@ -1,40 +0,0 @@
-/** Minimum scheduling surface required by the runner. */
-export interface ScheduledTurns<Actor> {
-    peek(): Actor | null;
-    spend(cost: number): void;
-}
-export interface TurnRules<Actor> {
-    scheduler: ScheduledTurns<Actor>;
-    finished(): boolean;
-    needsInput(actor: Actor): boolean;
-    /** Return the cost to spend on the current queue entry, or null if no entry should be charged. */
-    act(actor: Actor): number | null;
-}
-export type TurnResult<Actor> = {
-    status: 'input';
-    actor: Actor;
-    steps: number;
-} | {
-    status: 'finished' | 'empty' | 'limit';
-    steps: number;
-};
-/**
- * Advance automatic actions with an explicit work budget. Input actors are never spent.
- * Rules own actor removal and queue replacement. A returned cost is charged after act(),
- * even if that action ends the game; return null when the action already handled its cost.
- * Reaching the budget returns limit without another peek or action. The caller decides
- * whether to resume, report a stalled simulation, or yield to its host.
- *
- * @example
- * ```ts
- * import { advanceToInput, type TurnRules } from '@datamoc/mw_games/simulation';
- *
- * declare const rules: TurnRules<{ id: string; isPlayer: boolean }>;
- *
- * // runs monster turns automatically, stopping the moment the player needs to act
- * const result = advanceToInput(rules, 1000);
- * if (result.status === 'input') console.log('waiting on', result.actor.id);
- * ```
- */
-export declare function advanceToInput<Actor>(rules: TurnRules<Actor>, budget: number): TurnResult<Actor>;
-//# sourceMappingURL=Turns.d.ts.map