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

package/dist/cjs/bot-documents.js

@@ -0,0 +1,556 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileDeterministicBotDocument = compileDeterministicBotDocument;
+exports.traceDeterministicBotDocument = traceDeterministicBotDocument;
+exports.summarizeDeterministicBotDocumentTraceCoverage = summarizeDeterministicBotDocumentTraceCoverage;
+exports.runDeterministicBotDocumentFixture = runDeterministicBotDocumentFixture;
+exports.summarizeDeterministicBotDocumentTraceCounterDelta = summarizeDeterministicBotDocumentTraceCounterDelta;
+const canonical_js_1 = require("./canonical.js");
+const bot_primitives_js_1 = require("./bot-primitives.js");
+function compileDeterministicBotDocument(document, validAssetRefs = []) {
+    validateBotDocument(document, validAssetRefs);
+    const normalized = {
+        id: document.id,
+        version: document.version,
+        blackboard: (0, bot_primitives_js_1.createDeterministicBotBlackboard)(document.blackboard ?? []),
+        cooked: (0, bot_primitives_js_1.cookDeterministicBotAsset)({
+            id: document.id,
+            hfsm: document.hfsm,
+            behaviorTree: document.behaviorTree,
+            utility: document.utility,
+        }),
+        assetRefs: [...(document.assetRefs ?? [])].sort(compareStrings),
+    };
+    const bytes = (0, canonical_js_1.canonicalStringify)(normalized);
+    return {
+        id: document.id,
+        hash: (0, canonical_js_1.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,
+        },
+    };
+}
+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 = (0, bot_primitives_js_1.tickDeterministicHfsm)(document.hfsm, hfsm, blackboard);
+                hfsm = {
+                    ...advanced,
+                    actionLog: advanced.actionLog.slice(-4),
+                };
+            }
+            const behavior = document.behaviorTree === undefined
+                ? emptyBotDocumentBehaviorTick(runtimeState.behaviorMemory)
+                : (0, bot_primitives_js_1.tickDeterministicBehaviorTreeWithMemory)(document.behaviorTree, blackboard, runtimeState.behaviorMemory);
+            const utility = document.utility === undefined ? undefined : (0, bot_primitives_js_1.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: (0, canonical_js_1.defaultChecksum)({ frame, slot, hfsm, behavior, utility }),
+            });
+            stateBySlot.set(slot, { blackboard, hfsm, behaviorMemory: behavior.memory });
+        }
+    }
+    return traces;
+}
+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,
+    };
+}
+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 = (0, canonical_js_1.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 = (0, bot_primitives_js_1.tickDeterministicHfsm)(document.hfsm, hfsm, blackboard);
+                hfsm = {
+                    ...advanced,
+                    actionLog: advanced.actionLog.slice(-4),
+                };
+            }
+            const behavior = document.behaviorTree === undefined
+                ? emptyBotDocumentBehaviorTick(runtimeState.behaviorMemory)
+                : (0, bot_primitives_js_1.tickDeterministicBehaviorTreeWithMemory)(document.behaviorTree, blackboard, runtimeState.behaviorMemory);
+            const utility = document.utility === undefined ? undefined : (0, bot_primitives_js_1.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 = (0, canonical_js_1.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,
+    };
+}
+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 (0, bot_primitives_js_1.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((0, bot_primitives_js_1.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;
+}