@datamoc/mw_games 0.44.2 → 0.45.0

package/dist/ai/Neural.js

@@ -1,169 +0,0 @@
-import { spawn } from '../threads/index.js';
-/**
- * The self-contained evaluator shared by the local policy and serialized worker tasks.
- * Limits apply before copying weights: at most 32 layers, 4096 neurons per layer and
- * one million weights plus biases. Activations reuse buffers; returned outputs are owned
- * by the caller. Hidden layers use ReLU, output scores remain linear.
- */
-export function createNeuralEvaluator(model) {
-    if (model?.version !== 1 || typeof model.observationVersion !== 'string' || !model.observationVersion.length)
-        throw new TypeError('unsupported neural model or observation version');
-    if (!Array.isArray(model.layers) || !model.layers.length || model.layers.length > 32)
-        throw new RangeError('a neural model needs 1..32 layers');
-    let parameters = 0;
-    for (let index = 0; index < model.layers.length; index++) {
-        const layer = model.layers[index];
-        if (!layer ||
-            !Number.isInteger(layer.inputSize) ||
-            !Number.isInteger(layer.outputSize) ||
-            layer.inputSize < 1 ||
-            layer.outputSize < 1 ||
-            layer.inputSize > 4096 ||
-            layer.outputSize > 4096)
-            throw new RangeError('neural layer dimensions must be integers in 1..4096');
-        parameters += layer.inputSize * layer.outputSize + layer.outputSize;
-        if (parameters > 1_000_000)
-            throw new RangeError('neural model exceeds one million parameters');
-        if (index && model.layers[index - 1].outputSize !== layer.inputSize)
-            throw new RangeError('neural layer dimensions do not connect');
-        if (!Array.isArray(layer.weights) ||
-            !Array.isArray(layer.biases) ||
-            layer.weights.length !== layer.inputSize * layer.outputSize ||
-            layer.biases.length !== layer.outputSize ||
-            !Array.from(layer.weights).every(Number.isFinite) ||
-            !Array.from(layer.biases).every(Number.isFinite))
-            throw new TypeError('neural weights and biases must be finite and match layer dimensions');
-    }
-    const layers = model.layers.map((layer) => ({
-        ...layer,
-        weights: Float64Array.from(layer.weights),
-        biases: Float64Array.from(layer.biases),
-        buffer: new Float64Array(layer.outputSize),
-    }));
-    const predict = (input, output) => {
-        if (input.length !== layers[0].inputSize)
-            throw new TypeError('neural input must be finite and match the model');
-        for (let i = 0; i < input.length; i++)
-            if (!Number.isFinite(input[i]))
-                throw new TypeError('neural input must be finite');
-        const last = layers[layers.length - 1];
-        if (output && output.length !== last.outputSize)
-            throw new RangeError('neural output buffer has the wrong size');
-        let current = input;
-        for (let index = 0; index < layers.length; index++) {
-            const layer = layers[index];
-            for (let row = 0; row < layer.outputSize; row++) {
-                let sum = layer.biases[row];
-                for (let col = 0; col < layer.inputSize; col++)
-                    sum += layer.weights[row * layer.inputSize + col] * current[col];
-                if (!Number.isFinite(sum))
-                    throw new RangeError('neural activation overflow');
-                layer.buffer[row] = index === layers.length - 1 ? sum : Math.max(0, sum);
-            }
-            current = layer.buffer;
-        }
-        const result = output ?? new Float64Array(last.outputSize);
-        result.set(last.buffer);
-        return result;
-    };
-    const scores = new Float64Array(layers[layers.length - 1].outputSize);
-    return {
-        predict,
-        select(observation, random) {
-            const mask = observation.mask;
-            if (mask &&
-                (mask.length !== scores.length || !Array.from(mask).every((entry) => typeof entry === 'boolean')))
-                throw new TypeError('neural action mask must contain one boolean per output');
-            predict(observation.input, scores);
-            let best = null;
-            for (let i = 0; i < scores.length; i++)
-                if ((!mask || mask[i]) && (best === null || scores[i] > scores[best]))
-                    best = i;
-            if (best === null || !random)
-                return best;
-            const draw = random();
-            if (!Number.isFinite(draw) || draw < 0 || draw >= 1)
-                throw new RangeError('sampling random must return a value in [0, 1)');
-            let total = 0;
-            for (let i = 0; i < scores.length; i++)
-                if (!mask || mask[i])
-                    total += Math.exp(scores[i] - scores[best]);
-            let remaining = draw * total;
-            for (let i = 0; i < scores.length; i++) {
-                if (mask && !mask[i])
-                    continue;
-                remaining -= Math.exp(scores[i] - scores[best]);
-                if (remaining < 0)
-                    return i;
-            }
-            return best;
-        },
-    };
-}
-//One batch per worker, never a worker per agent. The evaluator source has no imports.
-function inferenceBatch(source, model, inputs) {
-    const create = new Function(`return (${source});`)();
-    const evaluator = create(model);
-    return inputs.map((input) => evaluator.predict(input));
-}
-/**
- * A small shared dense policy, usable inside existing JavaScriptAI behaviours.
- * Model weights are copied on construction. Supply a seeded random callback to sample
- * softmax scores; omit it for the first highest-scoring legal action. All-masked is idle.
- * Async batches return detached results, never mutate game state; callers must discard
- * results whose scene or position changed while awaiting them.
- *
- * @example
- * ```ts
- * import { NeuralPolicy, JavaScriptAI } from '@datamoc/mw_games/ai';
- * const policy = new NeuralPolicy({ version: 1, observationVersion: 'v1', layers: [
- *   { inputSize: 1, outputSize: 2, weights: [-1, 1], biases: [0, 0] },
- * ] });
- * console.log(policy.selectAction({ input: [2] })); // 1
- * const ai = new JavaScriptAI({ seed: 7 });
- * ai.register({ id: 'npc', behaviors: [policy.behavior('neural',
- *   [{ type: 'left' }, { type: 'right' }], () => ({ input: [2] }))] });
- * console.log(ai.decide('npc', { perception: null }).action?.type); // right
- * const scores = await policy.predictBatchAsync([[2], [-2]]);
- * ```
- */
-export class NeuralPolicy {
-    constructor(model) {
-        this.evaluator = createNeuralEvaluator(model);
-        this.model = structuredClone(model);
-    }
-    predict(input, output) {
-        return this.evaluator.predict(input, output);
-    }
-    selectAction(observation, random) {
-        return this.evaluator.select(observation, random);
-    }
-    exportModel() {
-        return structuredClone(this.model);
-    }
-    behavior(id, actions, observe, sample = false) {
-        if (actions.length !== this.model.layers[this.model.layers.length - 1].outputSize)
-            throw new RangeError('neural action mapping must match output size');
-        const mapping = structuredClone(actions);
-        return {
-            id,
-            decide: (context) => {
-                context.checkpoint();
-                const action = this.selectAction(observe(context.perception), sample ? context.random : undefined);
-                return action === null ? null : structuredClone(mapping[action]);
-            },
-        };
-    }
-    /** One cancellable worker batch: at most 65536 observations and one million input or output values. */
-    predictBatchAsync(inputs, options = {}) {
-        const inputSize = this.model.layers[0].inputSize;
-        const outputSize = this.model.layers[this.model.layers.length - 1].outputSize;
-        if (inputs.length > 65536 || inputs.length * Math.max(inputSize, outputSize) > 1_000_000)
-            return Promise.reject(new RangeError('neural batch exceeds its observation or value limit'));
-        for (const input of inputs)
-            if (!input || input.length !== inputSize)
-                return Promise.reject(new TypeError('neural batch inputs must match the model'));
-        return spawn(inferenceBatch, [createNeuralEvaluator.toString(), this.model, inputs], options);
-    }
-}
-//# sourceMappingURL=Neural.js.map

package/dist/ai/Neural.js.map

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

package/dist/ai/Suggest.d.ts

@@ -1,54 +0,0 @@
-import type { AIDecision, AIDecisionInput } from './index.ts';
-/**
- * The suggestion mode: the game's own decider, run on the live state, with the result shown
- * to the player instead of dispatched. The framework runs decisions as data by design
- * (`AIModule.decide` returns an `AIDecision`; the game applies it), so suggesting is the
- * same call pointed at a UI instead of at the world - but a hint that recomputed on every
- * frame would tax the frame budget for something the player reads once, so this owns the
- * throttle: a frame-count budget, never wall clock, the same rule the rest of the runner
- * follows (a throttled background tab must not change what is suggested).
- *
- * The decider must not mutate game state to compute a suggestion; what the player does with
- * one (accept, ignore, watch) is the game's to decide.
- */
-export interface SuggesterOptions {
-    /**
-     * Recompute only every Nth `update` call, keeping the previous suggestion in between.
-     * 1 (the default) recomputes on every update; 30 recomputes about twice a second at
-     * 60 fps. The first update always recomputes, so a hint appears immediately.
-     */
-    every?: number;
-}
-/**
- * Wraps a decision function as a throttled, non-mutating hint source.
- *
- * @example
- * ```ts
- * import { Suggester } from '@datamoc/mw_games/ai';
- * import type { AIDecision, AIDecisionInput } from '@datamoc/mw_games/ai';
- *
- * declare const module: { decide(agent: string, input: AIDecisionInput): AIDecision };
- * declare const input: AIDecisionInput;
- * const hints = new Suggester((perception) => module.decide('player', perception), { every: 30 });
- * const fresh = hints.update(input); // null on the 29 throttled frames between hints
- * const current = hints.latest; // never null between updates
- * ```
- */
-export declare class Suggester {
-    private readonly decide;
-    private readonly every;
-    private since;
-    private latestDecision;
-    constructor(decide: (input: AIDecisionInput) => AIDecision, options?: SuggesterOptions);
-    /**
-     * Runs the decider on its turn and returns the fresh suggestion; null on the throttled
-     * calls between, where `latest` keeps the previous suggestion. A decision with status
-     * `idle` (nothing to suggest) is still a suggestion: the UI reads `decision.action`.
-     */
-    update(input: AIDecisionInput): AIDecision | null;
-    /** The most recent suggestion, held across the throttled calls. */
-    get latest(): AIDecision | null;
-    /** Drops the held suggestion: a scene change, a menu opened, a turn ended. */
-    clear(): void;
-}
-//# sourceMappingURL=Suggest.d.ts.map

package/dist/ai/Suggest.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Suggest.d.ts","sourceRoot":"","sources":["../../src/ai/Suggest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE9D;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,gBAAgB;IAChC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,SAAS;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAChE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,cAAc,CAA2B;IAEjD,YAAY,MAAM,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,UAAU,EAAE,OAAO,GAAE,gBAAqB,EAOzF;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,UAAU,GAAG,IAAI,CAMhD;IAED,mEAAmE;IACnE,IAAI,MAAM,IAAI,UAAU,GAAG,IAAI,CAE9B;IAED,8EAA8E;IAC9E,KAAK,IAAI,IAAI,CAEZ;CACD"}

package/dist/ai/Suggest.js

@@ -1,48 +0,0 @@
-/**
- * Wraps a decision function as a throttled, non-mutating hint source.
- *
- * @example
- * ```ts
- * import { Suggester } from '@datamoc/mw_games/ai';
- * import type { AIDecision, AIDecisionInput } from '@datamoc/mw_games/ai';
- *
- * declare const module: { decide(agent: string, input: AIDecisionInput): AIDecision };
- * declare const input: AIDecisionInput;
- * const hints = new Suggester((perception) => module.decide('player', perception), { every: 30 });
- * const fresh = hints.update(input); // null on the 29 throttled frames between hints
- * const current = hints.latest; // never null between updates
- * ```
- */
-export class Suggester {
-    constructor(decide, options = {}) {
-        this.latestDecision = null;
-        this.decide = decide;
-        this.every = options.every ?? 1;
-        if (!Number.isInteger(this.every) || this.every < 1 || this.every > 1_000_000)
-            throw new RangeError('a suggestion budget must be a frame count in 1..1000000');
-        //the first update recomputes; the budget applies from the second on
-        this.since = this.every - 1;
-    }
-    /**
-     * Runs the decider on its turn and returns the fresh suggestion; null on the throttled
-     * calls between, where `latest` keeps the previous suggestion. A decision with status
-     * `idle` (nothing to suggest) is still a suggestion: the UI reads `decision.action`.
-     */
-    update(input) {
-        this.since++;
-        if (this.since < this.every)
-            return null;
-        this.since = 0;
-        this.latestDecision = this.decide(input);
-        return this.latestDecision;
-    }
-    /** The most recent suggestion, held across the throttled calls. */
-    get latest() {
-        return this.latestDecision;
-    }
-    /** Drops the held suggestion: a scene change, a menu opened, a turn ended. */
-    clear() {
-        this.latestDecision = null;
-    }
-}
-//# sourceMappingURL=Suggest.js.map

package/dist/ai/Suggest.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Suggest.js","sourceRoot":"","sources":["../../src/ai/Suggest.ts"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,SAAS;IAMrB,YAAY,MAA8C,EAAE,OAAO,GAAqB,EAAE;QAFlF,mBAAc,GAAsB,IAAI,CAAC;QAGhD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,GAAG,SAAS;YAC5E,MAAM,IAAI,UAAU,CAAC,yDAAyD,CAAC,CAAC;QACjF,oEAAoE;QACpE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAsB;QAC5B,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACzC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;QACf,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACzC,OAAO,IAAI,CAAC,cAAc,CAAC;IAC5B,CAAC;IAED,mEAAmE;IACnE,IAAI,MAAM;QACT,OAAO,IAAI,CAAC,cAAc,CAAC;IAC5B,CAAC;IAED,8EAA8E;IAC9E,KAAK;QACJ,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;IAC5B,CAAC;CACD"}

package/dist/ai/index.d.ts

@@ -1,136 +0,0 @@
-import type { AlphaBetaGame, AlphaBetaOptions, AlphaBetaResult } from './search.ts';
-export { NeuralPolicy } from './Neural.ts';
-export type { DenseLayer, NeuralModel, NeuralObservation } from './Neural.ts';
-export { Suggester } from './Suggest.ts';
-export type { SuggesterOptions } from './Suggest.ts';
-export { alphaBetaSearch, firstWins, rootSplits } from './search.ts';
-export type { AlphaBetaGame, AlphaBetaOptions, AlphaBetaResult, LuaAlphaBetaFunctions, LuaSearchValueAdapter, RootSplit, } from './search.ts';
-export { personalScoreView, scoreWith, sideScoreView, subjectsWhere } from './score.ts';
-export { Aspects, Difficulty, Goals, HeuristicAI, RecruitmentPattern, defaultWeigh, goalScore, keepAwayScore, } from './Heuristics.ts';
-export type { AspectValue, AspectValues, DifficultyLevel, Goal, GoalKind, HeuristicCandidate, HeuristicContext, HeuristicDecision, HeuristicStage, } from './Heuristics.ts';
-export type { ScorePersonality, ScoreSubject, ScoreSubjectFilter, ScoreView } from './score.ts';
-/** JSON-shaped values are the only values that cross the AI boundary. */
-export type AIValue = null | boolean | number | string | AIValue[] | {
-    readonly [key: string]: AIValue;
-};
-export type AIState = Record<string, AIValue>;
-export interface AIAction {
-    readonly type: string;
-    readonly [key: string]: AIValue;
-}
-/**
- * What one `decide` call receives. `perception` is the game-built snapshot; `state` overrides the agent's stored state for this call; `signal` cancels; the budget and `seed` fields override the runner's defaults.
- */
-export interface AIDecisionInput {
-    readonly perception: AIValue;
-    readonly state?: AIState;
-    readonly signal?: AbortSignal;
-    readonly seed?: number;
-    readonly maxSteps?: number;
-    readonly maxMilliseconds?: number;
-}
-export interface AIDecisionContext {
-    readonly perception: AIValue;
-    readonly state: AIState;
-    readonly random: () => number;
-    readonly checkpoint: () => void;
-    emit(name: string, payload?: AIValue): void;
-}
-/**
- * The result of one `decide` call. `status` says why `action` is or is not set; `steps` counts budget checkpoints used and `behavior` names the behaviour that decided, when one did.
- */
-export interface AIDecision {
-    readonly agent: string;
-    readonly action: AIAction | null;
-    readonly state: AIState;
-    readonly behavior?: string;
-    readonly status: 'action' | 'idle' | 'cancelled' | 'budget-exceeded';
-    readonly steps: number;
-    readonly events: readonly AIEvent[];
-}
-export interface AIEvent {
-    readonly name: string;
-    readonly payload?: AIValue;
-}
-export interface AIDiagnostics {
-    readonly onDecision?: (decision: AIDecision) => void;
-}
-export interface AIBehavior {
-    readonly id: string;
-    readonly when?: (context: AIDecisionContext) => boolean;
-    readonly decide: (context: AIDecisionContext) => AIAction | null;
-}
-/**
- * A registered agent: behaviours tried in declaration order, plus optional `scope` and search hints (`algorithm`, `depth`, `maxNodes`) that the runner itself does not act on: a game, converter or score view reads them.
- */
-export interface AIAgentDefinition {
-    readonly id: string;
-    readonly behaviors: readonly AIBehavior[];
-    readonly scope?: 'actor' | 'controller';
-    readonly algorithm?: 'rules' | 'alpha_beta';
-    readonly depth?: number;
-    readonly maxNodes?: number;
-}
-/** The versioned, JSON-shaped save format of `exportState`/`importState`: per-agent state keyed by agent id. */
-export interface AIStateEnvelope {
-    readonly version: 1;
-    readonly agents: Readonly<Record<string, AIState>>;
-}
-export interface AIModule {
-    register(agent: AIAgentDefinition): void;
-    decide(agent: string, input: AIDecisionInput): AIDecision;
-    exportState(): AIStateEnvelope;
-    importState(envelope: AIStateEnvelope): void;
-    dispose(): void;
-}
-export interface JavaScriptAIOptions extends AIDiagnostics {
-    readonly maxSteps?: number;
-    readonly maxMilliseconds?: number;
-    readonly seed?: number;
-}
-/**
- * Renderer-free AI runner for game-owned JavaScript behaviours.
- *
- * Behaviours are checked in declaration order. A matching behaviour may return
- * `null` to yield an idle decision. Long-running behaviours must call
- * `checkpoint()` regularly: JavaScript cannot interrupt a synchronous function
- * that never yields or checks its budget.
- */
-/**
- * Runs game-owned JavaScript behaviours without knowing anything about a renderer or game
- * rules.
- *
- * @example
- * ```ts
- * import { JavaScriptAI, AICancelledError, AIBudgetExceededError } from '@datamoc/mw_games/ai';
- *
- * const ai = new JavaScriptAI({ seed: 7 });
- * ai.register({ id: 'guard', behaviors: [{ id: 'wait', decide: () => ({ type: 'wait' }) }] });
- * const decision = ai.decide('guard', { perception: { visible: true } });
- * console.log(decision.action?.type); // 'wait'
- * void AICancelledError;
- * void AIBudgetExceededError;
- * ```
- */
-export declare class JavaScriptAI implements AIModule {
-    private readonly agents;
-    private readonly states;
-    private readonly options;
-    constructor(options?: JavaScriptAIOptions);
-    register(agent: AIAgentDefinition): void;
-    decide(agentId: string, input: AIDecisionInput): AIDecision;
-    /** Run alpha-beta against a game-owned state adapter for an actor or controller. */
-    search<State, Move>(game: AlphaBetaGame<State, Move>, state: State, options: AlphaBetaOptions): AlphaBetaResult<State, Move>;
-    exportState(): AIStateEnvelope;
-    importState(envelope: AIStateEnvelope): void;
-    dispose(): void;
-}
-/** Raised internally when a cooperative decision observes an aborted signal. */
-export declare class AICancelledError extends Error {
-    constructor();
-}
-/** Raised internally when a cooperative decision exceeds its configured budget. */
-export declare class AIBudgetExceededError extends Error {
-    constructor();
-}
-//# sourceMappingURL=index.d.ts.map

package/dist/ai/index.d.ts.map

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

package/dist/ai/index.js

@@ -1,207 +0,0 @@
-import { alphaBetaSearch } from './search.js';
-export { NeuralPolicy } from './Neural.js';
-export { Suggester } from './Suggest.js';
-export { alphaBetaSearch, firstWins, rootSplits } from './search.js';
-export { personalScoreView, scoreWith, sideScoreView, subjectsWhere } from './score.js';
-export { Aspects, Difficulty, Goals, HeuristicAI, RecruitmentPattern, defaultWeigh, goalScore, keepAwayScore, } from './Heuristics.js';
-const DEFAULT_MAX_STEPS = 10_000;
-const DEFAULT_MAX_MILLISECONDS = 16;
-/**
- * Renderer-free AI runner for game-owned JavaScript behaviours.
- *
- * Behaviours are checked in declaration order. A matching behaviour may return
- * `null` to yield an idle decision. Long-running behaviours must call
- * `checkpoint()` regularly: JavaScript cannot interrupt a synchronous function
- * that never yields or checks its budget.
- */
-/**
- * Runs game-owned JavaScript behaviours without knowing anything about a renderer or game
- * rules.
- *
- * @example
- * ```ts
- * import { JavaScriptAI, AICancelledError, AIBudgetExceededError } from '@datamoc/mw_games/ai';
- *
- * const ai = new JavaScriptAI({ seed: 7 });
- * ai.register({ id: 'guard', behaviors: [{ id: 'wait', decide: () => ({ type: 'wait' }) }] });
- * const decision = ai.decide('guard', { perception: { visible: true } });
- * console.log(decision.action?.type); // 'wait'
- * void AICancelledError;
- * void AIBudgetExceededError;
- * ```
- */
-export class JavaScriptAI {
-    constructor(options = {}) {
-        this.agents = new Map();
-        this.states = new Map();
-        this.options = options;
-        validatePositiveInteger(options.maxSteps ?? DEFAULT_MAX_STEPS, 'maxSteps');
-        validateNonNegativeFinite(options.maxMilliseconds ?? DEFAULT_MAX_MILLISECONDS, 'maxMilliseconds');
-    }
-    register(agent) {
-        if (!/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(agent.id))
-            throw new Error(`invalid AI agent id: ${agent.id}`);
-        if (this.agents.has(agent.id))
-            throw new Error(`AI agent already registered: ${agent.id}`);
-        if (!agent.behaviors.length)
-            throw new Error(`AI agent has no behaviours: ${agent.id}`);
-        const ids = new Set();
-        for (const behavior of agent.behaviors) {
-            if (!behavior.id || ids.has(behavior.id))
-                throw new Error(`duplicate AI behaviour: ${behavior.id}`);
-            ids.add(behavior.id);
-        }
-        this.agents.set(agent.id, agent);
-        this.states.set(agent.id, {});
-    }
-    decide(agentId, input) {
-        const agent = this.agents.get(agentId);
-        if (!agent)
-            throw new Error(`unknown AI agent: ${agentId}`);
-        const state = cloneState(input.state ?? this.states.get(agentId) ?? {});
-        const maxSteps = input.maxSteps ?? this.options.maxSteps ?? DEFAULT_MAX_STEPS;
-        const maxMilliseconds = input.maxMilliseconds ?? this.options.maxMilliseconds ?? DEFAULT_MAX_MILLISECONDS;
-        validatePositiveInteger(maxSteps, 'maxSteps');
-        validateNonNegativeFinite(maxMilliseconds, 'maxMilliseconds');
-        let steps = 0;
-        const started = performanceNow();
-        const events = [];
-        const random = seededRandom(input.seed ?? this.options.seed ?? 0x6d7767);
-        const checkpoint = () => {
-            steps++;
-            if (input.signal?.aborted)
-                throw new AICancelledError();
-            if (steps > maxSteps || performanceNow() - started > maxMilliseconds)
-                throw new AIBudgetExceededError();
-        };
-        const context = {
-            perception: cloneValue(input.perception),
-            state,
-            random: () => {
-                checkpoint();
-                return random();
-            },
-            checkpoint,
-            emit(name, payload) {
-                if (!name)
-                    throw new Error('AI event name must not be empty');
-                checkpoint();
-                events.push(payload === undefined ? { name } : { name, payload: cloneValue(payload) });
-            },
-        };
-        let action = null;
-        let behaviorId;
-        let status = 'idle';
-        try {
-            for (const behavior of agent.behaviors) {
-                checkpoint();
-                if (behavior.when && !behavior.when(context))
-                    continue;
-                behaviorId = behavior.id;
-                action = validateAction(behavior.decide(context));
-                status = action ? 'action' : 'idle';
-                break;
-            }
-        }
-        catch (error) {
-            if (error instanceof AICancelledError)
-                status = 'cancelled';
-            else if (error instanceof AIBudgetExceededError)
-                status = 'budget-exceeded';
-            else
-                throw error;
-        }
-        const decision = {
-            agent: agentId,
-            action,
-            state: cloneState(state),
-            behavior: behaviorId,
-            status,
-            steps,
-            events,
-        };
-        this.states.set(agentId, cloneState(state));
-        this.options.onDecision?.(decision);
-        return decision;
-    }
-    /** Run alpha-beta against a game-owned state adapter for an actor or controller. */
-    search(game, state, options) {
-        return alphaBetaSearch(game, state, options);
-    }
-    exportState() {
-        return {
-            version: 1,
-            agents: Object.fromEntries([...this.states].map(([id, state]) => [id, cloneState(state)])),
-        };
-    }
-    importState(envelope) {
-        if (envelope.version !== 1)
-            throw new Error(`unsupported AI state version: ${envelope.version}`);
-        for (const [id, state] of Object.entries(envelope.agents)) {
-            if (!this.agents.has(id))
-                throw new Error(`AI state names unknown agent: ${id}`);
-            this.states.set(id, cloneState(state));
-        }
-    }
-    dispose() {
-        this.agents.clear();
-        this.states.clear();
-    }
-}
-/** Raised internally when a cooperative decision observes an aborted signal. */
-export class AICancelledError extends Error {
-    constructor() {
-        super('AI decision cancelled');
-        this.name = 'AICancelledError';
-    }
-}
-/** Raised internally when a cooperative decision exceeds its configured budget. */
-export class AIBudgetExceededError extends Error {
-    constructor() {
-        super('AI decision budget exceeded');
-        this.name = 'AIBudgetExceededError';
-    }
-}
-function validateAction(action) {
-    if (action === null)
-        return null;
-    if (!action ||
-        typeof action !== 'object' ||
-        Array.isArray(action) ||
-        typeof action.type !== 'string' ||
-        !action.type) {
-        throw new Error('AI action must be an object with a non-empty string type');
-    }
-    return cloneValue(action);
-}
-function cloneState(state) {
-    return cloneValue(state);
-}
-function cloneValue(value) {
-    if (value === null || typeof value !== 'object')
-        return value;
-    if (Array.isArray(value))
-        return value.map(cloneValue);
-    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, cloneValue(entry)]));
-}
-function seededRandom(seed) {
-    if (!Number.isInteger(seed))
-        throw new TypeError('AI seed must be an integer');
-    let state = seed >>> 0;
-    return () => {
-        state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
-        return state / 0x1_0000_0000;
-    };
-}
-function validatePositiveInteger(value, name) {
-    if (!Number.isInteger(value) || value < 1)
-        throw new RangeError(`${name} must be a positive integer`);
-}
-function validateNonNegativeFinite(value, name) {
-    if (!Number.isFinite(value) || value < 0)
-        throw new RangeError(`${name} must be a non-negative number`);
-}
-function performanceNow() {
-    return typeof performance === 'undefined' ? Date.now() : performance.now();
-}
-//# sourceMappingURL=index.js.map