@series-inc/rundot-syncplay 5.23.0-beta.7

package/dist/bot-documents.d.ts

@@ -0,0 +1,115 @@
+import { type DeterministicBehaviorTreeNode, type DeterministicBotBlackboard, type DeterministicHfsmDefinition, type DeterministicUtilityConsideration } from './bot-primitives.js';
+export interface DeterministicBotDocument {
+    readonly id: string;
+    readonly version: 1;
+    readonly blackboard?: readonly {
+        readonly key: string;
+        readonly value: boolean | number | string;
+    }[];
+    readonly hfsm?: DeterministicHfsmDefinition;
+    readonly behaviorTree?: DeterministicBehaviorTreeNode;
+    readonly utility?: readonly DeterministicUtilityConsideration[];
+    readonly assetRefs?: readonly string[];
+}
+export interface CompiledDeterministicBotDocument {
+    readonly id: string;
+    readonly hash: string;
+    readonly bytes: string;
+    readonly blackboard: DeterministicBotBlackboard;
+    readonly debugMetadata: {
+        readonly stateCount: number;
+        readonly behaviorNodeCount: number;
+        readonly utilityCount: number;
+        readonly assetRefs: readonly string[];
+    };
+}
+export interface DeterministicBotDocumentTrace {
+    readonly frame: number;
+    readonly slot: number;
+    readonly hfsmState?: string;
+    readonly hfsmTransitionKey?: string;
+    readonly behaviorStatus?: string;
+    readonly behaviorActions: readonly string[];
+    readonly behaviorServiceActions: readonly string[];
+    readonly behaviorServiceNodeIds: readonly string[];
+    readonly visitedBehaviorNodes: readonly string[];
+    readonly resumedBehaviorNodes: readonly string[];
+    readonly behaviorRunningNodes: readonly string[];
+    readonly utilityAction?: string;
+    readonly utilityConsiderationId?: string;
+    readonly utilityScoredConsiderationIds: readonly string[];
+    readonly utilityScores: readonly {
+        readonly id: string;
+        readonly score: number;
+        readonly baseScore: number;
+        readonly nestedScore: number;
+        readonly momentumScore: number;
+        readonly cooldownPenalty: number;
+    }[];
+    readonly checksum: string;
+}
+export interface DeterministicBotDocumentTraceCoverage {
+    readonly declaredModelKinds: readonly string[];
+    readonly executedModelKinds: readonly string[];
+    readonly hfsmTransitionTicks: number;
+    readonly behaviorActionTicks: number;
+    readonly behaviorServiceTicks: number;
+    readonly utilitySelectionTicks: number;
+    readonly utilityCurveTicks: number;
+    readonly utilityNestedTicks: number;
+    readonly utilityMomentumTicks: number;
+    readonly utilityCooldownTicks: number;
+    readonly assetRefCount: number;
+    readonly declaredHfsmStates: readonly string[];
+    readonly visitedHfsmStates: readonly string[];
+    readonly unvisitedHfsmStates: readonly string[];
+    readonly declaredHfsmTransitions: readonly string[];
+    readonly coveredHfsmTransitions: readonly string[];
+    readonly uncoveredHfsmTransitions: readonly string[];
+    readonly declaredBehaviorNodes: readonly string[];
+    readonly visitedBehaviorNodes: readonly string[];
+    readonly unvisitedBehaviorNodes: readonly string[];
+    readonly declaredUtilityConsiderations: readonly string[];
+    readonly scoredUtilityConsiderations: readonly string[];
+    readonly unscoredUtilityConsiderations: readonly string[];
+    readonly declaredModelCoverageComplete: boolean;
+    readonly fullModelCoverageComplete: boolean;
+    readonly advancedCoverageComplete: boolean;
+    readonly advancedCoverageFailures: readonly string[];
+    readonly failures: readonly string[];
+}
+export interface DeterministicBotDocumentTraceCounterDelta {
+    readonly transitions: number;
+    readonly utilitySelections: number;
+    readonly behaviorRunningTicks: number;
+    readonly behaviorResumeTicks: number;
+    readonly behaviorDecoratorTicks: number;
+    readonly behaviorServiceTicks: number;
+    readonly utilityCurveSelections: number;
+    readonly utilityNestedSelections: number;
+    readonly utilityMomentumSelections: number;
+    readonly utilityCooldownSuppressions: number;
+}
+export declare function compileDeterministicBotDocument(document: DeterministicBotDocument, validAssetRefs?: readonly string[]): CompiledDeterministicBotDocument;
+export declare function traceDeterministicBotDocument(document: DeterministicBotDocument, slots: readonly number[], frames: number, validAssetRefs?: readonly string[]): readonly DeterministicBotDocumentTrace[];
+export declare function summarizeDeterministicBotDocumentTraceCoverage(document: DeterministicBotDocument, traces: readonly DeterministicBotDocumentTrace[]): DeterministicBotDocumentTraceCoverage;
+export declare function runDeterministicBotDocumentFixture(players: number, frames: number, document?: DeterministicBotDocument): {
+    readonly checksum: string;
+    readonly compiledAssetHash: string;
+    readonly blackboardHash: string;
+    readonly frames: number;
+    readonly transitions: number;
+    readonly ticks: number;
+    readonly utilitySelections: number;
+    readonly behaviorRunningTicks: number;
+    readonly behaviorResumeTicks: number;
+    readonly behaviorDecoratorTicks: number;
+    readonly behaviorServiceTicks: number;
+    readonly utilityCurveSelections: number;
+    readonly utilityNestedSelections: number;
+    readonly utilityMomentumSelections: number;
+    readonly utilityCooldownSuppressions: number;
+    readonly botReplacementSlots: number;
+    readonly debugTraceCount: number;
+};
+export declare function summarizeDeterministicBotDocumentTraceCounterDelta(trace: Pick<DeterministicBotDocumentTrace, 'hfsmState' | 'utilityAction' | 'behaviorStatus' | 'resumedBehaviorNodes' | 'visitedBehaviorNodes' | 'behaviorServiceActions' | 'utilityScores'>): DeterministicBotDocumentTraceCounterDelta;

package/dist/bot-documents.js

@@ -0,0 +1,549 @@
+import { canonicalStringify, defaultChecksum } from './canonical.js';
+import { cookDeterministicBotAsset, createDeterministicBotBlackboard, selectDeterministicUtility, tickDeterministicBehaviorTreeWithMemory, tickDeterministicHfsm, } from './bot-primitives.js';
+export function compileDeterministicBotDocument(document, validAssetRefs = []) {
+    validateBotDocument(document, validAssetRefs);
+    const normalized = {
+        id: document.id,
+        version: document.version,
+        blackboard: createDeterministicBotBlackboard(document.blackboard ?? []),
+        cooked: cookDeterministicBotAsset({
+            id: document.id,
+            hfsm: document.hfsm,
+            behaviorTree: document.behaviorTree,
+            utility: document.utility,
+        }),
+        assetRefs: [...(document.assetRefs ?? [])].sort(compareStrings),
+    };
+    const bytes = canonicalStringify(normalized);
+    return {
+        id: document.id,
+        hash: defaultChecksum(bytes),
+        bytes,
+        blackboard: normalized.blackboard,
+        debugMetadata: {
+            stateCount: document.hfsm?.states.length ?? 0,
+            behaviorNodeCount: document.behaviorTree === undefined ? 0 : countBehaviorNodes(document.behaviorTree),
+            utilityCount: document.utility?.length ?? 0,
+            assetRefs: normalized.assetRefs,
+        },
+    };
+}
+export function traceDeterministicBotDocument(document, slots, frames, validAssetRefs = document.assetRefs ?? []) {
+    const compiled = compileDeterministicBotDocument(document, validAssetRefs);
+    const traces = [];
+    const stateBySlot = new Map([...slots].sort(compareNumbers).map((slot) => [slot, createBotDocumentRuntimeState(compiled.blackboard, document.hfsm)]));
+    for (let frame = 0; frame < frames; frame += 1) {
+        for (const slot of [...slots].sort((left, right) => left - right)) {
+            const runtimeState = stateBySlot.get(slot);
+            let blackboard = advanceBotDocumentBlackboard(runtimeState.blackboard, frame);
+            let hfsm = runtimeState.hfsm;
+            const hfsmTransitionKey = document.hfsm === undefined || hfsm === undefined
+                ? undefined
+                : selectBotDocumentHfsmTransitionKey(document.hfsm, hfsm, blackboard);
+            if (document.hfsm !== undefined && hfsm !== undefined) {
+                const advanced = tickDeterministicHfsm(document.hfsm, hfsm, blackboard);
+                hfsm = {
+                    ...advanced,
+                    actionLog: advanced.actionLog.slice(-4),
+                };
+            }
+            const behavior = document.behaviorTree === undefined
+                ? emptyBotDocumentBehaviorTick(runtimeState.behaviorMemory)
+                : tickDeterministicBehaviorTreeWithMemory(document.behaviorTree, blackboard, runtimeState.behaviorMemory);
+            const utility = document.utility === undefined ? undefined : selectDeterministicUtility(document.utility, blackboard);
+            traces.push({
+                frame,
+                slot,
+                hfsmState: hfsm?.state,
+                hfsmTransitionKey,
+                behaviorStatus: behavior.status,
+                behaviorActions: behavior.actions,
+                behaviorServiceActions: behavior.serviceActions,
+                behaviorServiceNodeIds: behavior.serviceNodeIds,
+                visitedBehaviorNodes: behavior.visitedNodeIds,
+                resumedBehaviorNodes: behavior.resumedNodeIds,
+                behaviorRunningNodes: behavior.memory.runningNodeIds,
+                utilityAction: utility?.action,
+                utilityConsiderationId: utility?.considerationId,
+                utilityScoredConsiderationIds: utility?.scores.map((score) => score.id).sort(compareStrings) ?? [],
+                utilityScores: utility?.scores ?? [],
+                checksum: defaultChecksum({ frame, slot, hfsm, behavior, utility }),
+            });
+            stateBySlot.set(slot, { blackboard, hfsm, behaviorMemory: behavior.memory });
+        }
+    }
+    return traces;
+}
+export function summarizeDeterministicBotDocumentTraceCoverage(document, traces) {
+    const declaredModelKinds = [
+        ...(document.hfsm === undefined ? [] : ['hfsm']),
+        ...(document.behaviorTree === undefined ? [] : ['behavior-tree']),
+        ...(document.utility === undefined ? [] : ['utility']),
+    ];
+    const hfsmTransitionTicks = document.hfsm === undefined
+        ? 0
+        : traces.filter((trace) => trace.hfsmState !== undefined && trace.hfsmState !== document.hfsm?.initialState).length;
+    const behaviorActionTicks = traces.filter((trace) => trace.behaviorActions.length > 0).length;
+    const behaviorServiceTicks = traces.filter((trace) => trace.behaviorServiceActions.length > 0).length;
+    const utilitySelectionTicks = traces.filter((trace) => trace.utilityAction !== undefined).length;
+    const utilityCurveTicks = traces.filter((trace) => trace.utilityScores.some((score) => score.baseScore !== 0)).length;
+    const utilityNestedTicks = traces.filter((trace) => trace.utilityScores.some((score) => score.nestedScore !== 0)).length;
+    const utilityMomentumTicks = traces.filter((trace) => trace.utilityScores.some((score) => score.momentumScore !== 0)).length;
+    const utilityCooldownTicks = traces.filter((trace) => trace.utilityScores.some((score) => score.cooldownPenalty > 0)).length;
+    const declaredHfsmStates = [...(document.hfsm?.states.map((state) => state.id) ?? [])].sort(compareStrings);
+    const visitedHfsmStates = [...new Set([
+            ...(document.hfsm === undefined ? [] : [document.hfsm.initialState]),
+            ...traces.map((trace) => trace.hfsmState).filter(isDefinedString),
+        ])].sort(compareStrings);
+    const unvisitedHfsmStates = declaredHfsmStates.filter((state) => !visitedHfsmStates.includes(state));
+    const declaredHfsmTransitions = [...(document.hfsm?.transitions.map(botDocumentHfsmTransitionKey) ?? [])].sort(compareStrings);
+    const coveredHfsmTransitions = [...new Set(traces.map((trace) => trace.hfsmTransitionKey).filter(isDefinedString))].sort(compareStrings);
+    const uncoveredHfsmTransitions = declaredHfsmTransitions.filter((transition) => !coveredHfsmTransitions.includes(transition));
+    const declaredBehaviorNodes = document.behaviorTree === undefined ? [] : [...collectBehaviorNodeIds(document.behaviorTree)].sort(compareStrings);
+    const visitedBehaviorNodes = [...new Set(traces.flatMap((trace) => trace.visitedBehaviorNodes))].sort(compareStrings);
+    const unvisitedBehaviorNodes = declaredBehaviorNodes.filter((node) => !visitedBehaviorNodes.includes(node));
+    const declaredUtilityConsiderations = [...(document.utility?.map((consideration) => consideration.id) ?? [])].sort(compareStrings);
+    const scoredUtilityConsiderations = [...new Set(traces.flatMap((trace) => trace.utilityScoredConsiderationIds))].sort(compareStrings);
+    const unscoredUtilityConsiderations = declaredUtilityConsiderations.filter((consideration) => !scoredUtilityConsiderations.includes(consideration));
+    const declaresBehaviorServices = document.behaviorTree !== undefined && collectBehaviorServices(document.behaviorTree).length > 0;
+    const declaresUtilityCurves = (document.utility ?? []).some((consideration) => consideration.curve !== undefined && consideration.curve !== 'linear');
+    const declaresUtilityNested = (document.utility ?? []).some((consideration) => (consideration.nested?.length ?? 0) > 0);
+    const declaresUtilityMomentum = (document.utility ?? []).some((consideration) => consideration.momentumKey !== undefined);
+    const declaresUtilityCooldown = (document.utility ?? []).some((consideration) => consideration.cooldownKey !== undefined);
+    const assetRefCount = document.assetRefs?.length ?? 0;
+    const advancedCoverageFailures = [
+        ...(declaresBehaviorServices && behaviorServiceTicks === 0 ? ['behavior services declared but none executed'] : []),
+        ...(declaresUtilityNested && utilityNestedTicks === 0 ? ['nested utility considerations declared but none affected scoring'] : []),
+        ...(declaresUtilityMomentum && utilityMomentumTicks === 0 ? ['utility momentum declared but none affected scoring'] : []),
+        ...(declaresUtilityCooldown && utilityCooldownTicks === 0 ? ['utility cooldowns declared but none suppressed scoring'] : []),
+    ];
+    const executedModelKinds = [
+        ...(hfsmTransitionTicks > 0 ? ['hfsm'] : []),
+        ...(behaviorActionTicks > 0 ? ['behavior-tree'] : []),
+        ...(utilitySelectionTicks > 0 ? ['utility'] : []),
+    ];
+    const failures = [
+        ...(declaredModelKinds.length === 0 ? ['bot document declares no executable model'] : []),
+        ...(document.hfsm !== undefined && hfsmTransitionTicks === 0 ? ['HFSM declared but no transition executed'] : []),
+        ...(document.behaviorTree !== undefined && behaviorActionTicks === 0 ? ['behavior tree declared but no action executed'] : []),
+        ...(declaresBehaviorServices && behaviorServiceTicks === 0 ? ['behavior services declared but none executed'] : []),
+        ...(document.utility !== undefined && utilitySelectionTicks === 0 ? ['utility model declared but no selection executed'] : []),
+        ...(declaresUtilityCurves && utilityCurveTicks === 0 ? ['utility curves declared but none affected scoring'] : []),
+        ...(declaresUtilityNested && utilityNestedTicks === 0 ? ['nested utility considerations declared but none affected scoring'] : []),
+        ...(declaresUtilityMomentum && utilityMomentumTicks === 0 ? ['utility momentum declared but none affected scoring'] : []),
+        ...(declaresUtilityCooldown && utilityCooldownTicks === 0 ? ['utility cooldowns declared but none suppressed scoring'] : []),
+        ...unvisitedHfsmStates.map((state) => `unvisited HFSM state ${state}`),
+        ...uncoveredHfsmTransitions.map((transition) => `uncovered HFSM transition ${transition}`),
+        ...unvisitedBehaviorNodes.map((node) => `unvisited behavior node ${node}`),
+        ...unscoredUtilityConsiderations.map((consideration) => `unscored utility consideration ${consideration}`),
+        ...(assetRefCount === 0 ? ['bot document has no asset-backed action refs'] : []),
+    ];
+    const hfsmCoverageComplete = document.hfsm === undefined
+        || (unvisitedHfsmStates.length === 0 && uncoveredHfsmTransitions.length === 0);
+    const behaviorCoverageComplete = document.behaviorTree === undefined || unvisitedBehaviorNodes.length === 0;
+    const utilityCoverageComplete = document.utility === undefined || unscoredUtilityConsiderations.length === 0;
+    const advancedBehaviorCoverageComplete = !declaresBehaviorServices || behaviorServiceTicks > 0;
+    const advancedUtilityCoverageComplete = (!declaresUtilityCurves || utilityCurveTicks > 0)
+        && (!declaresUtilityNested || utilityNestedTicks > 0)
+        && (!declaresUtilityMomentum || utilityMomentumTicks > 0)
+        && (!declaresUtilityCooldown || utilityCooldownTicks > 0);
+    return {
+        declaredModelKinds,
+        executedModelKinds,
+        hfsmTransitionTicks,
+        behaviorActionTicks,
+        behaviorServiceTicks,
+        utilitySelectionTicks,
+        utilityCurveTicks,
+        utilityNestedTicks,
+        utilityMomentumTicks,
+        utilityCooldownTicks,
+        assetRefCount,
+        declaredHfsmStates,
+        visitedHfsmStates,
+        unvisitedHfsmStates,
+        declaredHfsmTransitions,
+        coveredHfsmTransitions,
+        uncoveredHfsmTransitions,
+        declaredBehaviorNodes,
+        visitedBehaviorNodes,
+        unvisitedBehaviorNodes,
+        declaredUtilityConsiderations,
+        scoredUtilityConsiderations,
+        unscoredUtilityConsiderations,
+        declaredModelCoverageComplete: declaredModelKinds.length > 0
+            && declaredModelKinds.every((kind) => executedModelKinds.includes(kind)),
+        fullModelCoverageComplete: hfsmTransitionTicks > 0
+            && behaviorActionTicks > 0
+            && utilitySelectionTicks > 0
+            && hfsmCoverageComplete
+            && behaviorCoverageComplete
+            && utilityCoverageComplete
+            && advancedBehaviorCoverageComplete
+            && advancedUtilityCoverageComplete
+            && assetRefCount > 0,
+        advancedCoverageComplete: advancedCoverageFailures.length === 0,
+        advancedCoverageFailures,
+        failures,
+    };
+}
+export function runDeterministicBotDocumentFixture(players, frames, document = defaultBotDocument()) {
+    const compiled = compileDeterministicBotDocument(document, document.assetRefs ?? []);
+    const botSlots = Array.from({ length: players }, (_, slot) => slot).filter((slot) => slot % 4 !== 0);
+    const stateBySlot = new Map(botSlots.map((slot) => [slot, createBotDocumentRuntimeState(compiled.blackboard, document.hfsm)]));
+    let checksum = defaultChecksum({ id: document.id, frames, botSlots });
+    let transitions = 0;
+    let ticks = 0;
+    let utilitySelections = 0;
+    let behaviorRunningTicks = 0;
+    let behaviorResumeTicks = 0;
+    let behaviorDecoratorTicks = 0;
+    let behaviorServiceTicks = 0;
+    let utilityCurveSelections = 0;
+    let utilityNestedSelections = 0;
+    let utilityMomentumSelections = 0;
+    let utilityCooldownSuppressions = 0;
+    for (let frame = 0; frame < frames; frame += 1) {
+        for (const slot of botSlots) {
+            const runtimeState = stateBySlot.get(slot);
+            let blackboard = advanceBotDocumentBlackboard(runtimeState.blackboard, frame);
+            let hfsm = runtimeState.hfsm;
+            if (document.hfsm !== undefined && hfsm !== undefined) {
+                const advanced = tickDeterministicHfsm(document.hfsm, hfsm, blackboard);
+                hfsm = {
+                    ...advanced,
+                    actionLog: advanced.actionLog.slice(-4),
+                };
+            }
+            const behavior = document.behaviorTree === undefined
+                ? emptyBotDocumentBehaviorTick(runtimeState.behaviorMemory)
+                : tickDeterministicBehaviorTreeWithMemory(document.behaviorTree, blackboard, runtimeState.behaviorMemory);
+            const utility = document.utility === undefined ? undefined : selectDeterministicUtility(document.utility, blackboard);
+            const trace = {
+                frame,
+                slot,
+                hfsmState: hfsm?.state,
+                behaviorStatus: behavior.status,
+                behaviorActions: behavior.actions,
+                behaviorServiceActions: behavior.serviceActions,
+                behaviorServiceNodeIds: behavior.serviceNodeIds,
+                visitedBehaviorNodes: behavior.visitedNodeIds,
+                resumedBehaviorNodes: behavior.resumedNodeIds,
+                behaviorRunningNodes: behavior.memory.runningNodeIds,
+                utilityAction: utility?.action,
+                utilityConsiderationId: utility?.considerationId,
+                utilityScoredConsiderationIds: utility?.scores.map((score) => score.id).sort(compareStrings) ?? [],
+                utilityScores: utility?.scores ?? [],
+            };
+            checksum = defaultChecksum({ checksum, trace });
+            const counterDelta = summarizeDeterministicBotDocumentTraceCounterDelta(trace);
+            transitions += counterDelta.transitions;
+            ticks += 1;
+            utilitySelections += counterDelta.utilitySelections;
+            behaviorRunningTicks += counterDelta.behaviorRunningTicks;
+            behaviorResumeTicks += counterDelta.behaviorResumeTicks;
+            behaviorDecoratorTicks += counterDelta.behaviorDecoratorTicks;
+            behaviorServiceTicks += counterDelta.behaviorServiceTicks;
+            utilityCurveSelections += counterDelta.utilityCurveSelections;
+            utilityNestedSelections += counterDelta.utilityNestedSelections;
+            utilityMomentumSelections += counterDelta.utilityMomentumSelections;
+            utilityCooldownSuppressions += counterDelta.utilityCooldownSuppressions;
+            stateBySlot.set(slot, { blackboard, hfsm, behaviorMemory: behavior.memory });
+        }
+    }
+    return {
+        checksum,
+        compiledAssetHash: compiled.hash,
+        blackboardHash: compiled.blackboard.hash,
+        frames,
+        transitions,
+        ticks,
+        utilitySelections,
+        behaviorRunningTicks,
+        behaviorResumeTicks,
+        behaviorDecoratorTicks,
+        behaviorServiceTicks,
+        utilityCurveSelections,
+        utilityNestedSelections,
+        utilityMomentumSelections,
+        utilityCooldownSuppressions,
+        botReplacementSlots: botSlots.length,
+        debugTraceCount: ticks,
+    };
+}
+export function summarizeDeterministicBotDocumentTraceCounterDelta(trace) {
+    return {
+        transitions: trace.hfsmState === 'attack' ? 1 : 0,
+        utilitySelections: trace.utilityAction === undefined ? 0 : 1,
+        behaviorRunningTicks: trace.behaviorStatus === 'running' ? 1 : 0,
+        behaviorResumeTicks: trace.resumedBehaviorNodes.length > 0 ? 1 : 0,
+        behaviorDecoratorTicks: trace.visitedBehaviorNodes.includes('maybe-patrol') ? 1 : 0,
+        behaviorServiceTicks: trace.behaviorServiceActions.length > 0 ? 1 : 0,
+        utilityCurveSelections: trace.utilityScores.some((score) => score.baseScore !== 0) ? 1 : 0,
+        utilityNestedSelections: trace.utilityScores.some((score) => score.nestedScore !== 0) ? 1 : 0,
+        utilityMomentumSelections: trace.utilityScores.some((score) => score.momentumScore !== 0) ? 1 : 0,
+        utilityCooldownSuppressions: trace.utilityScores.some((score) => score.cooldownPenalty > 0) ? 1 : 0,
+    };
+}
+function createBotDocumentRuntimeState(blackboard, hfsmDefinition) {
+    return {
+        blackboard,
+        hfsm: hfsmDefinition === undefined
+            ? undefined
+            : { state: hfsmDefinition.initialState, transitionsTaken: 0, actionLog: [] },
+        behaviorMemory: { runningNodeIds: [], completedRunningNodeIds: [] },
+    };
+}
+function emptyBotDocumentBehaviorTick(memory) {
+    return {
+        status: 'success',
+        actions: [],
+        serviceActions: [],
+        serviceNodeIds: [],
+        visitedNodeIds: [],
+        memory,
+        resumedNodeIds: [],
+    };
+}
+function advanceBotDocumentBlackboard(blackboard, frame) {
+    return createDeterministicBotBlackboard(blackboard.entries.map((entry) => {
+        if (entry.key === 'frame') {
+            return { key: entry.key, value: frame };
+        }
+        if (entry.key === 'attackCooldown') {
+            return { key: entry.key, value: frame % 5 === 0 ? 2 : 0 };
+        }
+        if (entry.key === 'lastActionAttack') {
+            return { key: entry.key, value: frame % 3 === 0 };
+        }
+        if (typeof entry.value !== 'number') {
+            return entry;
+        }
+        return { key: entry.key, value: entry.value + (frame % 2) };
+    }));
+}
+function selectBotDocumentHfsmTransitionKey(definition, agent, blackboard) {
+    const states = new Map(definition.states.map((state) => [state.id, state]));
+    const current = states.get(agent.state);
+    /* istanbul ignore if -- validated/ticked HFSM agents cannot hold undeclared states. */
+    if (current === undefined) {
+        throw new Error(`Unknown HFSM state ${agent.state}`);
+    }
+    const transition = definition.transitions
+        .filter((candidate) => candidate.from === agent.state || candidate.from === current.parent)
+        .sort(compareBotDocumentHfsmTransitions)
+        .find((candidate) => botDocumentBlackboardValue(blackboard, candidate.whenKey) === candidate.equals);
+    return transition === undefined ? undefined : botDocumentHfsmTransitionKey(transition);
+}
+function botDocumentBlackboardValue(blackboard, key) {
+    return blackboard.entries.find((entry) => entry.key === key)?.value;
+}
+function botDocumentHfsmTransitionKey(transition) {
+    return `${transition.from}->${transition.to}|when:${transition.whenKey}=${typeof transition.equals}:${String(transition.equals)}`;
+}
+function compareBotDocumentHfsmTransitions(left, right) {
+    return compareStrings(`${left.from}:${left.whenKey}:${left.to}`, `${right.from}:${right.whenKey}:${right.to}`);
+}
+function validateBotDocument(document, validAssetRefs) {
+    if (document.version !== 1) {
+        throw new Error(`Unsupported bot document version ${document.version}`);
+    }
+    const knownRefs = new Set(validAssetRefs);
+    const refs = [...(document.assetRefs ?? [])].sort(compareStrings);
+    for (const ref of refs) {
+        if (!knownRefs.has(ref)) {
+            throw new Error(`Unknown bot asset ref ${ref}`);
+        }
+    }
+    const blackboardKeys = new Set(createDeterministicBotBlackboard(document.blackboard ?? []).entries.map((entry) => entry.key));
+    if (document.hfsm !== undefined) {
+        const stateIds = uniqueIds(document.hfsm.states.map((state) => state.id), 'HFSM state');
+        if (!stateIds.has(document.hfsm.initialState)) {
+            throw new Error(`Invalid HFSM initial state ${document.hfsm.initialState}`);
+        }
+        for (const state of document.hfsm.states) {
+            if (state.parent !== undefined && !stateIds.has(state.parent)) {
+                throw new Error(`Invalid HFSM parent ${state.parent} for state ${state.id}`);
+            }
+            assertAcyclicHfsmParent(document.hfsm.states, state.id);
+        }
+        uniqueIds(document.hfsm.transitions.map((transition) => `${transition.from}->${transition.to}:${transition.whenKey}:${String(transition.equals)}`), 'HFSM transition');
+        for (const transition of document.hfsm.transitions) {
+            if (!stateIds.has(transition.from) || !stateIds.has(transition.to)) {
+                throw new Error(`Invalid HFSM transition ${transition.from}->${transition.to}`);
+            }
+            assertKnownBlackboardKey(blackboardKeys, transition.whenKey, `HFSM transition ${transition.from}->${transition.to}`);
+        }
+    }
+    if (document.behaviorTree !== undefined) {
+        uniqueIds(collectBehaviorNodeIds(document.behaviorTree), 'behavior node');
+        uniqueIds(collectBehaviorServices(document.behaviorTree).map((service) => service.id), 'behavior service');
+        validateBehaviorTreeBlackboardRefs(document.behaviorTree, blackboardKeys);
+        validateBehaviorTreeServices(document.behaviorTree);
+    }
+    if (document.utility !== undefined) {
+        if (document.utility.length === 0) {
+            throw new Error('Utility document requires at least one consideration');
+        }
+        uniqueIds(document.utility.map((consideration) => consideration.id), 'utility consideration');
+        for (const consideration of document.utility) {
+            assertKnownBlackboardKey(blackboardKeys, consideration.inputKey, `utility consideration ${consideration.id}`);
+            if (consideration.momentumKey !== undefined) {
+                assertKnownBlackboardKey(blackboardKeys, consideration.momentumKey, `utility momentum ${consideration.id}`);
+            }
+            if (consideration.cooldownKey !== undefined) {
+                assertKnownBlackboardKey(blackboardKeys, consideration.cooldownKey, `utility cooldown ${consideration.id}`);
+            }
+            uniqueIds((consideration.nested ?? []).map((nested) => nested.id), `nested utility consideration ${consideration.id}`);
+            for (const nested of consideration.nested ?? []) {
+                assertKnownBlackboardKey(blackboardKeys, nested.inputKey, `nested utility consideration ${consideration.id}.${nested.id}`);
+            }
+        }
+    }
+    uniqueIds(refs, 'bot asset ref');
+}
+function assertAcyclicHfsmParent(states, stateId) {
+    const byId = new Map(states.map((state) => [state.id, state]));
+    const seen = new Set();
+    let current = byId.get(stateId);
+    while (current?.parent !== undefined) {
+        if (seen.has(current.parent)) {
+            throw new Error(`Cyclic HFSM parent hierarchy at ${stateId}`);
+        }
+        seen.add(current.parent);
+        current = byId.get(current.parent);
+    }
+}
+function validateBehaviorTreeBlackboardRefs(node, blackboardKeys) {
+    if (node.type === 'condition') {
+        assertKnownBlackboardKey(blackboardKeys, node.key, `behavior condition ${node.id}`);
+        return;
+    }
+    if (node.type === 'decorator') {
+        validateBehaviorTreeBlackboardRefs(node.child, blackboardKeys);
+        return;
+    }
+    if (node.type === 'sequence' || node.type === 'selector') {
+        for (const child of node.children) {
+            validateBehaviorTreeBlackboardRefs(child, blackboardKeys);
+        }
+    }
+}
+function validateBehaviorTreeServices(node) {
+    for (const service of node.services ?? []) {
+        if (!Number.isInteger(service.intervalFrames) || service.intervalFrames <= 0) {
+            throw new Error(`Behavior service ${service.id} interval must be positive`);
+        }
+    }
+    if (node.type === 'decorator') {
+        validateBehaviorTreeServices(node.child);
+        return;
+    }
+    if (node.type === 'sequence' || node.type === 'selector') {
+        for (const child of node.children) {
+            validateBehaviorTreeServices(child);
+        }
+    }
+}
+function assertKnownBlackboardKey(blackboardKeys, key, owner) {
+    if (!blackboardKeys.has(key)) {
+        throw new Error(`Unknown bot blackboard key ${key} in ${owner}`);
+    }
+}
+function defaultBotDocument() {
+    return {
+        id: 'bot.document.default',
+        version: 1,
+        blackboard: [
+            { key: 'enemyNear', value: true },
+            { key: 'health', value: 8 },
+            { key: 'ammo', value: 4 },
+            { key: 'lastActionAttack', value: true },
+            { key: 'attackCooldown', value: 0 },
+            { key: 'frame', value: 0 },
+        ],
+        assetRefs: ['ability.dash'],
+        hfsm: {
+            initialState: 'idle',
+            states: [{ id: 'idle', action: 'scan' }, { id: 'attack', action: 'fire' }],
+            transitions: [{ from: 'idle', to: 'attack', whenKey: 'enemyNear', equals: true }],
+        },
+        behaviorTree: {
+            id: 'root',
+            type: 'sequence',
+            services: [{ id: 'root-target-service', action: 'refresh-target', intervalFrames: 2 }],
+            children: [
+                { id: 'enemy', type: 'condition', key: 'enemyNear', equals: true },
+                {
+                    id: 'maybe-patrol',
+                    type: 'decorator',
+                    mode: 'force-success',
+                    child: { id: 'calm', type: 'condition', key: 'health', equals: 99 },
+                },
+                { id: 'shoot', type: 'action', action: 'shoot', status: 'running' },
+            ],
+        },
+        utility: [
+            { id: 'retreat', inputKey: 'health', action: 'retreat', min: 0, max: 10, weight: 1, rank: 1, curve: 'inverse' },
+            {
+                id: 'pressure',
+                inputKey: 'health',
+                action: 'pressure',
+                min: 0,
+                max: 10,
+                weight: 2,
+                curve: 'quadratic',
+                momentumKey: 'lastActionAttack',
+                momentum: 500,
+                cooldownKey: 'attackCooldown',
+                cooldownPenalty: 500,
+                nested: [{ id: 'ammo-ready', inputKey: 'ammo', min: 0, max: 5, weight: 1, curve: 'step' }],
+            },
+        ],
+    };
+}
+function countBehaviorNodes(node) {
+    if (node.type === 'action' || node.type === 'condition') {
+        return 1;
+    }
+    if (node.type === 'decorator') {
+        return 1 + countBehaviorNodes(node.child);
+    }
+    return 1 + node.children.reduce((sum, child) => sum + countBehaviorNodes(child), 0);
+}
+function collectBehaviorNodeIds(node) {
+    if (node.type === 'action' || node.type === 'condition') {
+        return [node.id];
+    }
+    if (node.type === 'decorator') {
+        return [node.id, ...collectBehaviorNodeIds(node.child)];
+    }
+    return [node.id, ...node.children.flatMap((child) => collectBehaviorNodeIds(child))];
+}
+function collectBehaviorServices(node) {
+    const current = [...(node.services ?? [])];
+    if (node.type === 'action' || node.type === 'condition') {
+        return current;
+    }
+    if (node.type === 'decorator') {
+        return [...current, ...collectBehaviorServices(node.child)];
+    }
+    return [...current, ...node.children.flatMap((child) => collectBehaviorServices(child))];
+}
+function uniqueIds(ids, label) {
+    const sorted = [...ids].sort(compareStrings);
+    const duplicate = sorted.find((id, index) => index > 0 && id === sorted[index - 1]);
+    if (duplicate !== undefined) {
+        throw new Error(`Duplicate ${label} id ${duplicate}`);
+    }
+    return new Set(sorted);
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function compareNumbers(left, right) {
+    return left - right;
+}
+function isDefinedString(value) {
+    return value !== undefined;
+}