hoi4-agent-tools 3.1.0 → 3.2.0

package/dist/hoi4_agent_tools/decision/cost.js

@@ -0,0 +1,177 @@
+import { ClausewitzEvaluationDefinitions } from '../core/clausewitz-evaluation.js';
+import { evaluateTriggerBlock, resolveConditionNumber } from '../core/condition-evaluator.js';
+import { rootScopeContext } from '../core/scenario-state.js';
+import { assignments, nodeLocation } from '../core/source/index.js';
+function scalar(assignment) {
+    return assignment?.value.type === 'scalar' ? assignment.value.value : undefined;
+}
+function unresolved(source, message) {
+    return {
+        code: 'DECISION_COST_UNRESOLVED',
+        message,
+        candidateId: source.id,
+        provenance: {
+            path: source.path,
+            rootKind: source.rootKind,
+            loadOrder: source.loadOrder,
+            sourceHash: source.sourceHash,
+            ...(source.location === undefined ? {} : { location: source.location }),
+            symbol: source.id,
+        },
+    };
+}
+function directPayments(snapshot, source, scenario, definitions) {
+    const paymentEffects = [];
+    const conditionalOrHelperEffects = [];
+    for (const effect of source.fields.complete_effect) {
+        if (effect.value.type !== 'block') {
+            conditionalOrHelperEffects.push('malformed complete_effect');
+            continue;
+        }
+        for (const entry of assignments(effect.value)) {
+            const key = entry.key.value;
+            let resource;
+            let operation;
+            let expression;
+            if (key === 'add_political_power' || key === 'add_command_power') {
+                resource = key.slice(4);
+                operation = 'add';
+                expression = scalar(entry);
+            }
+            else if (key === 'add_to_variable' || key === 'subtract_from_variable') {
+                if (entry.value.type === 'block') {
+                    const values = assignments(entry.value).filter(({ key: field }) => field.value !== 'tooltip');
+                    if (values.length === 1) {
+                        resource = `variable.${values[0].key.value}`;
+                        operation = key === 'add_to_variable' ? 'add' : 'subtract';
+                        expression = scalar(values[0]);
+                    }
+                }
+            }
+            if (resource !== undefined && operation !== undefined) {
+                const amount = expression === undefined
+                    ? undefined
+                    : resolveConditionNumber(expression, scenario, rootScopeContext(scenario), definitions, source.path);
+                const normalizedOperation = amount !== undefined && amount < 0
+                    ? operation === 'add'
+                        ? 'subtract'
+                        : 'add'
+                    : operation;
+                paymentEffects.push({
+                    resource,
+                    amount: amount === undefined ? null : Math.abs(amount),
+                    operation: normalizedOperation,
+                    scope: 'ROOT',
+                    location: nodeLocation(source.document, entry, key),
+                });
+                if (amount === undefined)
+                    conditionalOrHelperEffects.push(`dynamic payment: ${key}`);
+            }
+            else if (key === 'add_political_power' ||
+                key === 'add_command_power' ||
+                key === 'add_to_variable' ||
+                key === 'subtract_from_variable') {
+                conditionalOrHelperEffects.push(`unparsed payment: ${key}`);
+            }
+            else if (snapshot.index.find('scripted_effect', key) !== undefined ||
+                ['if', 'else_if', 'else', 'random', 'random_list', 'ROOT', 'FROM', 'meta_effect'].includes(key)) {
+                conditionalOrHelperEffects.push(key);
+            }
+        }
+    }
+    return { paymentEffects, conditionalOrHelperEffects };
+}
+/** Cost and payment evidence is source-bounded; a custom cost is never treated as automatic payment. */
+export function inspectDecisionCost(snapshot, source, scenario) {
+    const definitions = ClausewitzEvaluationDefinitions.build(snapshot);
+    const base = directPayments(snapshot, source, scenario, definitions);
+    const cost = source.fields.cost;
+    const custom = source.fields.custom_cost_trigger;
+    const findings = [];
+    const deductions = base.paymentEffects.filter(({ operation }) => operation === 'subtract');
+    const seenDeductions = new Set();
+    for (const deduction of deductions) {
+        if (seenDeductions.has(deduction.resource))
+            findings.push(unresolved(source, `Multiple direct payments deduct ${deduction.resource}`));
+        seenDeductions.add(deduction.resource);
+    }
+    if (cost.length > 1 || custom.length > 1 || (cost.length > 0 && custom.length > 0)) {
+        findings.push(unresolved(source, 'Conflicting or repeated decision cost declarations'));
+        return {
+            kind: 'invalid',
+            expression: null,
+            amount: null,
+            affordable: 'unresolved',
+            ...base,
+            unresolved: findings,
+        };
+    }
+    if (cost.length === 1) {
+        if (deductions.some(({ resource }) => resource === 'political_power'))
+            findings.push(unresolved(source, 'Engine political-power cost also has an explicit political-power deduction'));
+        const expression = scalar(cost[0]);
+        const amount = expression === undefined
+            ? undefined
+            : resolveConditionNumber(expression, scenario, rootScopeContext(scenario), definitions, source.path);
+        const politicalPower = resolveConditionNumber('political_power', scenario, rootScopeContext(scenario), definitions, source.path);
+        if (amount === undefined || amount < 0)
+            findings.push(unresolved(source, 'Engine political-power cost is not a resolved nonnegative number'));
+        if (politicalPower === undefined)
+            findings.push(unresolved(source, 'Scenario does not declare current political power'));
+        return {
+            kind: 'engine_political_power',
+            expression: expression ?? null,
+            amount: amount ?? null,
+            affordable: amount === undefined || amount < 0 || politicalPower === undefined
+                ? 'unresolved'
+                : politicalPower >= amount
+                    ? 'true'
+                    : 'false',
+            ...base,
+            unresolved: findings,
+        };
+    }
+    if (custom.length === 1) {
+        const trigger = custom[0].value;
+        const evaluated = trigger.type === 'block'
+            ? evaluateTriggerBlock(trigger, { ...scenario, closedFlags: scenario.closedFlags ?? false }, {
+                id: source.id,
+                document: source.document,
+                provenance: [
+                    {
+                        path: source.path,
+                        rootKind: source.rootKind,
+                        loadOrder: source.loadOrder,
+                        sourceHash: source.sourceHash,
+                        ...(source.location === undefined ? {} : { location: source.location }),
+                        symbol: source.id,
+                    },
+                ],
+            }, definitions)
+            : {
+                state: 'unresolved',
+                unresolved: [unresolved(source, 'custom_cost_trigger is not a block')],
+            };
+        findings.push(...evaluated.unresolved);
+        if (base.conditionalOrHelperEffects.length > 0)
+            findings.push(unresolved(source, 'Custom payment crosses a conditional, helper, dynamic, or unparsed effect path'));
+        if (base.paymentEffects.length === 0 && base.conditionalOrHelperEffects.length === 0)
+            findings.push(unresolved(source, 'Custom cost has no recognized direct payment effect; other effect semantics remain unverified'));
+        return {
+            kind: 'custom',
+            expression: scalar(source.fields.custom_cost_text[0]) ?? null,
+            amount: null,
+            affordable: evaluated.state,
+            ...base,
+            unresolved: findings,
+        };
+    }
+    return {
+        kind: 'none',
+        expression: null,
+        amount: 0,
+        affordable: 'true',
+        ...base,
+        unresolved: findings,
+    };
+}

package/dist/hoi4_agent_tools/decision/evaluation.js

@@ -0,0 +1,256 @@
+import { ClausewitzEvaluationDefinitions } from '../core/clausewitz-evaluation.js';
+import { evaluateTriggerBlock } from '../core/condition-evaluator.js';
+import { assignments } from '../core/source/index.js';
+import { decisionSourceInventory, } from './source-inventory.js';
+function combine(values) {
+    if (values.includes('false'))
+        return 'false';
+    return values.includes('unresolved') ? 'unresolved' : 'true';
+}
+function combineAny(values) {
+    if (values.includes('true'))
+        return 'true';
+    return values.includes('unresolved') ? 'unresolved' : 'false';
+}
+function unresolved(message, candidateId) {
+    return {
+        state: 'unresolved',
+        unresolved: [{ code: 'DECISION_UNRESOLVED', message, candidateId }],
+    };
+}
+function scalar(assignment) {
+    return assignment?.value.type === 'scalar' ? assignment.value.value : undefined;
+}
+function block(assignment) {
+    return assignment?.value.type === 'block' ? assignment.value : undefined;
+}
+function subject(source) {
+    return {
+        id: source.id,
+        document: source.document,
+        provenance: [
+            {
+                path: source.path,
+                rootKind: source.rootKind,
+                loadOrder: source.loadOrder,
+                sourceHash: source.sourceHash,
+                ...(source.location === undefined ? {} : { location: source.location }),
+                symbol: source.id,
+            },
+        ],
+    };
+}
+export function evaluateDecisionField(source, name, scenario, definitions) {
+    const occurrences = source.fields[name];
+    if (occurrences.length > 1)
+        return unresolved(`Multiple ${name} blocks in ${source.path}`, source.id);
+    const assignment = occurrences[0];
+    if (assignment !== undefined && assignment.value.type !== 'block')
+        return unresolved(`${name} is not a trigger block`, source.id);
+    return evaluateTriggerBlock(block(assignment), scenario, subject(source), definitions);
+}
+function evaluateCategoryField(categories, name, scenario, definitions, decisionId) {
+    const definitionsWithField = categories.filter(({ fields }) => fields[name].length > 0);
+    if (definitionsWithField.length > 1)
+        return unresolved(`Multiple active category fragments define ${name}; merge semantics are unresolved`, decisionId);
+    const source = definitionsWithField[0];
+    return source === undefined
+        ? { state: 'true', unresolved: [] }
+        : evaluateDecisionField(source, name, scenario, definitions);
+}
+function explicitTargets(source, scenario) {
+    const targets = source.fields.targets;
+    const arrays = source.fields.target_array;
+    const stateFilters = source.fields.state_trigger;
+    const activeStateFilters = stateFilters.filter((assignment) => scalar(assignment) !== 'no');
+    const targeted = targets.length +
+        arrays.length +
+        activeStateFilters.length +
+        source.fields.target_root_trigger.length +
+        source.fields.target_trigger.length;
+    if (targeted === 0)
+        return { state: 'true', unresolved: [] };
+    const target = scenario.scopes?.FROM;
+    if (target === undefined)
+        return unresolved('Targeted decision requires an explicit FROM scope binding', source.id);
+    const targetId = target.actor ?? target.id;
+    if (targets.length + arrays.length + stateFilters.length === 0)
+        return { state: 'true', unresolved: [] };
+    const candidateChecks = [];
+    const stateChecks = [];
+    const findings = [];
+    for (const assignment of targets) {
+        if (assignment.value.type !== 'block') {
+            findings.push({
+                code: 'DECISION_UNRESOLVED',
+                message: 'targets must be a block',
+                candidateId: source.id,
+            });
+            candidateChecks.push('unresolved');
+            continue;
+        }
+        const listed = assignment.value.entries
+            .filter((entry) => entry.type === 'scalar')
+            .map((entry) => entry.value);
+        const state = scalar(assignments(assignment.value, 'state')[0]);
+        if (state !== undefined)
+            listed.push(state);
+        candidateChecks.push(listed.includes(targetId) ? 'true' : 'false');
+    }
+    for (const assignment of arrays) {
+        const name = scalar(assignment);
+        const value = name === undefined ? undefined : scenario.state[`array.${name}`];
+        if (!Array.isArray(value)) {
+            findings.push({
+                code: 'DECISION_UNRESOLVED',
+                message: `Scenario does not declare target array ${name ?? '<unknown>'}`,
+                candidateId: source.id,
+            });
+            candidateChecks.push('unresolved');
+        }
+        else
+            candidateChecks.push(value.includes(targetId) ? 'true' : 'false');
+    }
+    for (const assignment of activeStateFilters) {
+        const filter = scalar(assignment);
+        if (target.type === undefined || target.type === 'unknown') {
+            findings.push({
+                code: 'DECISION_UNRESOLVED',
+                message: 'Scenario does not declare the target scope type',
+                candidateId: source.id,
+            });
+            stateChecks.push('unresolved');
+            continue;
+        }
+        if (target.type !== 'state') {
+            stateChecks.push('false');
+            continue;
+        }
+        if (filter === 'yes' || filter === 'any') {
+            stateChecks.push('true');
+            continue;
+        }
+        if (filter === 'any_owned_state' || filter === 'any_controlled_state') {
+            const key = filter === 'any_owned_state' ? 'owner' : 'controller';
+            const declared = target.state[key];
+            if (typeof declared !== 'string' || scenario.actor === undefined) {
+                findings.push({
+                    code: 'DECISION_UNRESOLVED',
+                    message: `State target needs declared ${key} and actor for ${filter}`,
+                    candidateId: source.id,
+                });
+                stateChecks.push('unresolved');
+            }
+            else
+                stateChecks.push(declared === scenario.actor ? 'true' : 'false');
+            continue;
+        }
+        if (filter !== undefined && /^[a-z][a-z0-9_]*$/u.test(filter)) {
+            const continent = target.state.continent;
+            if (typeof continent !== 'string') {
+                findings.push({
+                    code: 'DECISION_UNRESOLVED',
+                    message: `State target needs a declared continent for ${filter}`,
+                    candidateId: source.id,
+                });
+                stateChecks.push('unresolved');
+            }
+            else
+                stateChecks.push(continent === filter ? 'true' : 'false');
+            continue;
+        }
+        findings.push({
+            code: 'DECISION_UNRESOLVED',
+            message: `State target filter ${filter ?? '<dynamic>'} is unsupported`,
+            candidateId: source.id,
+        });
+        stateChecks.push('unresolved');
+    }
+    return {
+        state: combine([
+            ...(candidateChecks.length === 0 ? [] : [combineAny(candidateChecks)]),
+            ...stateChecks,
+        ]),
+        unresolved: findings,
+    };
+}
+/** Evaluates only declared source and scenario facts; it does not execute a decision. */
+export function evaluateDecisionGates(snapshot, id, scenario) {
+    const inventory = decisionSourceInventory(snapshot);
+    const source = inventory.decisions.find((candidate) => candidate.id === id);
+    if (source === undefined)
+        throw new Error(`Decision ${id} has no active source definition`);
+    const definitions = ClausewitzEvaluationDefinitions.build(snapshot);
+    const guardedScenario = {
+        ...scenario,
+        closedFlags: scenario.closedFlags ?? false,
+    };
+    const actorOnlyScenario = {
+        ...guardedScenario,
+        scopes: Object.fromEntries(Object.entries(guardedScenario.scopes ?? {}).filter(([scope]) => scope !== 'FROM')),
+    };
+    const categories = inventory.categories.filter(({ id: category }) => category === source.category);
+    const categoryAllowed = evaluateCategoryField(categories, 'allowed', actorOnlyScenario, definitions, id);
+    const categoryVisible = evaluateCategoryField(categories, 'visible', guardedScenario, definitions, id);
+    const categoryAvailable = evaluateCategoryField(categories, 'available', guardedScenario, definitions, id);
+    const decisionAllowed = evaluateDecisionField(source, 'allowed', actorOnlyScenario, definitions);
+    const decisionAvailable = evaluateDecisionField(source, 'available', guardedScenario, definitions);
+    const decisionVisible = source.kind === 'mission'
+        ? null
+        : evaluateDecisionField(source, 'visible', guardedScenario, definitions);
+    const targetRoot = evaluateDecisionField(source, 'target_root_trigger', actorOnlyScenario, definitions);
+    const targetSelection = explicitTargets(source, guardedScenario);
+    const targetTrigger = evaluateDecisionField(source, 'target_trigger', guardedScenario, definitions);
+    const activation = source.kind === 'mission'
+        ? evaluateDecisionField(source, 'activation', guardedScenario, definitions)
+        : null;
+    const eligible = combine([
+        categoryAllowed.state,
+        decisionAllowed.state,
+        targetRoot.state,
+        targetSelection.state,
+        targetTrigger.state,
+        ...(activation === null ? [] : [activation.state]),
+    ]);
+    const visible = decisionVisible === null
+        ? null
+        : combine([eligible, categoryVisible.state, decisionVisible.state]);
+    const available = combine([eligible, categoryAvailable.state, decisionAvailable.state]);
+    const gates = [
+        categoryAllowed,
+        decisionAllowed,
+        categoryAvailable,
+        decisionAvailable,
+        targetRoot,
+        targetSelection,
+        targetTrigger,
+        ...(decisionVisible === null ? [] : [decisionVisible]),
+        ...(decisionVisible === null ? [] : [categoryVisible]),
+        ...(activation === null ? [] : [activation]),
+    ];
+    return {
+        sourceRevision: snapshot.revision,
+        id,
+        category: source.category,
+        kind: source.kind,
+        actor: scenario.actor ?? null,
+        target: scenario.scopes?.FROM === undefined
+            ? null
+            : (scenario.scopes.FROM.actor ?? scenario.scopes.FROM.id),
+        categoryAllowed,
+        decisionAllowed,
+        categoryVisible,
+        decisionVisible,
+        categoryAvailable,
+        decisionAvailable,
+        targetRoot,
+        targetSelection,
+        targetTrigger,
+        activation,
+        eligible,
+        visible,
+        available,
+        complete: inventory.complete && gates.every(({ state }) => state !== 'unresolved'),
+        unresolved: gates.flatMap(({ unresolved: findings }) => findings),
+    };
+}

package/dist/hoi4_agent_tools/decision/lifecycle.js

@@ -0,0 +1,114 @@
+import { ClausewitzEvaluationDefinitions } from '../core/clausewitz-evaluation.js';
+import { resolveConditionNumber } from '../core/condition-evaluator.js';
+import { rootScopeContext } from '../core/scenario-state.js';
+import { evaluateDecisionField } from './evaluation.js';
+function scalar(assignment) {
+    return assignment?.value.type === 'scalar' ? assignment.value.value : undefined;
+}
+function boolean(value) {
+    if (value === 'yes')
+        return true;
+    if (value === 'no')
+        return false;
+    return null;
+}
+/** Static lifecycle paths and durations, with no claim that a campaign reached them. */
+export function inspectDecisionLifecycle(snapshot, source, scenario) {
+    const definitions = ClausewitzEvaluationDefinitions.build(snapshot);
+    const unresolved = [];
+    const duration = (field) => {
+        const entries = source.fields[field];
+        if (entries.length === 0)
+            return null;
+        if (entries.length > 1)
+            unresolved.push(`Multiple ${field} values in ${source.path}`);
+        const expression = scalar(entries[0]);
+        const days = expression === undefined
+            ? undefined
+            : resolveConditionNumber(expression, scenario, rootScopeContext(scenario), definitions, source.path);
+        if (days === undefined ||
+            !Number.isInteger(days) ||
+            (field === 'days_remove' ? days < -1 : days < 0))
+            unresolved.push(`${field} is not a supported day count`);
+        return { expression: expression ?? null, days: days ?? null };
+    };
+    const fireOnlyOnceExpression = scalar(source.fields.fire_only_once[0]);
+    const selectableExpression = scalar(source.fields.selectable_mission[0]);
+    const fireOnlyOnce = fireOnlyOnceExpression === undefined ? false : boolean(fireOnlyOnceExpression);
+    const selectableMission = selectableExpression === undefined ? false : boolean(selectableExpression);
+    if (source.fields.fire_only_once.length > 1 || (fireOnlyOnceExpression && fireOnlyOnce === null))
+        unresolved.push('fire_only_once is repeated or not a recognized Boolean');
+    if (source.fields.selectable_mission.length > 1 ||
+        (selectableExpression && selectableMission === null))
+        unresolved.push('selectable_mission is repeated or not a recognized Boolean');
+    const cooldown = duration('days_re_enable');
+    const removal = duration('days_remove');
+    const missionTimeout = duration('days_mission_timeout');
+    if (source.kind === 'mission' && missionTimeout === null)
+        unresolved.push('Mission classification has no timeout');
+    if (source.kind !== 'mission' && source.fields.timeout_effect.length > 0)
+        unresolved.push('A non-mission declares timeout_effect');
+    const guardedScenario = {
+        ...scenario,
+        closedFlags: scenario.closedFlags ?? false,
+    };
+    const removalTrigger = source.fields.remove_trigger.length === 0
+        ? null
+        : evaluateDecisionField(source, 'remove_trigger', guardedScenario, definitions);
+    const cancellationTrigger = source.fields.cancel_trigger.length === 0
+        ? null
+        : evaluateDecisionField(source, 'cancel_trigger', guardedScenario, definitions);
+    for (const result of [removalTrigger, cancellationTrigger])
+        if (result !== null)
+            unresolved.push(...result.unresolved.map(({ message }) => message));
+    const cancelIfNotVisibleExpression = scalar(source.fields.cancel_if_not_visible[0]);
+    const cancelIfNotVisible = cancelIfNotVisibleExpression === undefined ? false : boolean(cancelIfNotVisibleExpression);
+    if (source.fields.cancel_if_not_visible.length > 1 ||
+        (cancelIfNotVisibleExpression !== undefined && cancelIfNotVisible === null))
+        unresolved.push('cancel_if_not_visible is repeated or not a recognized Boolean');
+    if (cancelIfNotVisible && source.kind === 'mission')
+        unresolved.push('cancel_if_not_visible on a mission has unsupported visibility semantics');
+    const visible = cancelIfNotVisible && source.kind !== 'mission'
+        ? evaluateDecisionField(source, 'visible', guardedScenario, definitions)
+        : null;
+    if (visible !== null)
+        unresolved.push(...visible.unresolved.map(({ message }) => message));
+    const visibilityCancellation = visible === null
+        ? null
+        : visible.state === 'true'
+            ? 'false'
+            : visible.state === 'false'
+                ? 'true'
+                : 'unresolved';
+    const cancellationStates = [
+        cancellationTrigger?.state ?? 'false',
+        visibilityCancellation ?? 'false',
+    ];
+    const cancellationTriggerState = cancellationStates.includes('true')
+        ? 'true'
+        : cancellationStates.includes('unresolved')
+            ? 'unresolved'
+            : 'false';
+    return {
+        kind: source.kind,
+        fireOnlyOnce,
+        selectableMission: source.kind === 'mission' ? selectableMission : null,
+        cooldown,
+        removal,
+        missionTimeout,
+        hasActivation: source.fields.activation.length > 0,
+        hasCompletionEffect: source.fields.complete_effect.length > 0,
+        hasRemovalTrigger: source.fields.remove_trigger.length > 0,
+        hasRemovalEffect: source.fields.remove_effect.length > 0,
+        hasCancellationTrigger: source.fields.cancel_trigger.length > 0,
+        hasCancellationEffect: source.fields.cancel_effect.length > 0,
+        hasTimeoutEffect: source.fields.timeout_effect.length > 0,
+        ignoredMissionVisible: source.kind === 'mission' && source.fields.visible.length > 0,
+        removalTrigger,
+        cancellationTrigger,
+        cancelIfNotVisible,
+        visibilityCancellation,
+        cancellationTriggerState,
+        unresolved,
+    };
+}