hoi4-agent-tools 3.0.9 → 3.2.0

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,
+    };
+}

package/dist/hoi4_agent_tools/decision/service.js

@@ -0,0 +1,172 @@
+import { analysisSourceEvidence } from '../core/analysis-evidence.js';
+import { publicArtifactLink } from '../core/artifacts.js';
+import { canonicalJson, hashCanonical } from '../core/canonical.js';
+import { setInlineFilesScanned } from '../core/operation-result.js';
+import { emptyServiceResult, ServiceError } from '../core/result.js';
+import { buildProposedSourceOverlay } from '../core/source-overlay.js';
+import { PACKAGE_VERSION } from '../version.js';
+import { inspectDecisionAi } from './ai.js';
+import { compareDecisionScenarios, inspectDecisionScenario } from './comparison.js';
+import { decisionSourceInventory, decisionTargetCatalog } from './source-inventory.js';
+/** Authorized, read-only decision operation over the shared source scanner. */
+export class DecisionAnalyzer {
+    engine;
+    constructor(engine) {
+        this.engine = engine;
+    }
+    async inspect(input) {
+        const workspace = this.engine.resolver.get(input.workspaceId, input.principal);
+        if (input.refresh)
+            this.engine.invalidate(input.workspaceId);
+        const before = await this.engine.scan(input.workspaceId, {}, input.principal, input.signal);
+        if (input.expectedRevision !== undefined && before.revision !== input.expectedRevision)
+            throw new ServiceError('DECISION_SOURCE_STALE', 'Decision source revision changed since selection', {
+                expectedRevision: input.expectedRevision,
+                observedRevision: before.revision,
+            });
+        if (input.mode !== 'inventory' && input.id === undefined)
+            throw new ServiceError('DECISION_ID_REQUIRED', 'Decision analysis requires an identifier');
+        if (input.mode !== 'inventory' && input.scenarios.length === 0)
+            throw new ServiceError('DECISION_SCENARIOS_REQUIRED', 'Decision analysis requires scenarios');
+        if (input.mode === 'compare' && input.proposedSources === undefined)
+            throw new ServiceError('DECISION_PROPOSAL_REQUIRED', 'Decision comparison requires proposed sources');
+        if (input.mode !== 'compare' && input.proposedSources !== undefined)
+            throw new ServiceError('DECISION_PROPOSAL_MODE', 'Proposed sources require compare mode');
+        const inventory = decisionSourceInventory(before);
+        const overlay = input.proposedSources === undefined
+            ? undefined
+            : buildProposedSourceOverlay(before, workspace, input.proposedSources);
+        const scenarios = input.scenarios.map((scenario) => ({
+            id: scenario.id,
+            state: scenario.state,
+            ...(scenario.actor === undefined ? {} : { actor: scenario.actor }),
+            ...(scenario.date === undefined ? {} : { date: scenario.date }),
+            ...(scenario.flags === undefined ? {} : { flags: scenario.flags }),
+            ...(scenario.eventTargets === undefined ? {} : { eventTargets: scenario.eventTargets }),
+            ...(scenario.candidateOverrides === undefined
+                ? {}
+                : { candidateOverrides: scenario.candidateOverrides }),
+            ...(scenario.closedFlags === undefined ? {} : { closedFlags: scenario.closedFlags }),
+            ...(scenario.scopes === undefined
+                ? {}
+                : {
+                    scopes: Object.fromEntries(Object.entries(scenario.scopes).map(([key, binding]) => [
+                        key,
+                        {
+                            id: binding.id,
+                            state: binding.state,
+                            ...(binding.type === undefined ? {} : { type: binding.type }),
+                            ...(binding.actor === undefined ? {} : { actor: binding.actor }),
+                            ...(binding.flags === undefined ? {} : { flags: binding.flags }),
+                            ...(binding.eventTargets === undefined
+                                ? {}
+                                : { eventTargets: binding.eventTargets }),
+                            ...(binding.weight === undefined ? {} : { weight: binding.weight }),
+                        },
+                    ])),
+                }),
+        }));
+        const analysis = input.mode === 'inventory'
+            ? {
+                decisions: inventory.decisions.map((source) => ({
+                    id: source.id,
+                    category: source.category,
+                    kind: source.kind,
+                    path: source.path,
+                    rootKind: source.rootKind,
+                    loadOrder: source.loadOrder,
+                    ...(source.location === undefined ? {} : { location: source.location }),
+                    targeting: decisionTargetCatalog(source),
+                    fields: Object.fromEntries(Object.entries(source.fields)
+                        .filter(([, occurrences]) => occurrences.length > 0)
+                        .map(([field, occurrences]) => [field, occurrences.length])),
+                })),
+                categories: inventory.categories.map(({ id, path, rootKind, loadOrder, location }) => ({
+                    id,
+                    path,
+                    rootKind,
+                    loadOrder,
+                    ...(location === undefined ? {} : { location }),
+                })),
+                overrides: inventory.overrides,
+                unresolvedDefinitions: inventory.unresolvedDefinitions,
+            }
+            : input.mode === 'compare' && overlay !== undefined
+                ? compareDecisionScenarios(before, overlay.snapshot, input.id, scenarios)
+                : scenarios.map((scenario) => ({
+                    scenarioId: scenario.id,
+                    inspection: inspectDecisionScenario(before, input.id, scenario),
+                }));
+        const ai = input.mode === 'inventory'
+            ? undefined
+            : await inspectDecisionAi(this.engine, before, input.id, scenarios, overlay, input.principal, input.signal);
+        const sourceComplete = input.mode === 'inventory'
+            ? inventory.complete
+            : input.mode === 'compare'
+                ? 'complete' in analysis && analysis.complete
+                : inventory.complete &&
+                    Array.isArray(analysis) &&
+                    analysis.every(({ inspection }) => inspection !== null &&
+                        inspection.gates.complete &&
+                        inspection.cost.unresolved.length === 0 &&
+                        inspection.lifecycle.unresolved.length === 0);
+        const complete = sourceComplete &&
+            (ai === undefined ||
+                ('status' in ai &&
+                    ai.status === 'complete' &&
+                    !('proposedUnresolved' in ai) &&
+                    !('baselineUnresolved' in ai)));
+        const report = {
+            schemaVersion: 'decision-analysis.v1',
+            mode: input.mode,
+            sourceRevision: before.revision,
+            ...(overlay === undefined ? {} : { proposedRevision: overlay.snapshot.revision }),
+            ...(input.id === undefined ? {} : { id: input.id }),
+            ...(overlay === undefined ? {} : { proposedChanges: overlay.changes }),
+            analysis,
+            ...(ai === undefined ? {} : { ai }),
+        };
+        const reportHash = hashCanonical(report);
+        const provenanceSources = analysisSourceEvidence(before, overlay?.snapshot);
+        const artifact = await this.engine.artifacts.putChunked(workspace, `decision-${reportHash.slice(0, 24)}.json`, 'application/json', `${canonicalJson(report)}\n`, {
+            kind: 'decision-analysis',
+            toolVersion: PACKAGE_VERSION,
+            schemaVersion: 'decision-analysis.v1',
+            sourceHashes: provenanceSources.sourceHashes,
+            metadata: {
+                beforeRevision: before.revision,
+                ...(overlay === undefined ? {} : { afterRevision: overlay.snapshot.revision }),
+                sourceInventory: provenanceSources.inventory,
+            },
+        }, 'Revision-pinned decision inventory or declared-scenario evidence', input.signal);
+        const result = emptyServiceResult(input.workspaceId, {
+            mode: input.mode,
+            sourceRevision: before.revision,
+            ...(overlay === undefined ? {} : { proposedRevision: overlay.snapshot.revision }),
+            reportHash,
+            complete,
+            decisions: inventory.decisions.length,
+            categories: inventory.categories.length,
+            overrides: inventory.overrides.length,
+            scenarios: input.mode === 'inventory' ? 0 : input.scenarios.length,
+            unresolvedDefinitions: inventory.unresolvedDefinitions.length,
+        });
+        result.code = complete ? 'DECISION_ANALYZED' : 'DECISION_ANALYZED_PARTIAL';
+        result.artifacts = [publicArtifactLink(artifact)];
+        result.proposedFiles = overlay?.changes.map(({ path }) => path).slice(0, 64) ?? [];
+        setInlineFilesScanned(result, before.files.map(({ displayPath }) => displayPath));
+        result.validation = {
+            passed: complete,
+            checks: [
+                {
+                    id: 'decision-coverage',
+                    passed: complete,
+                    message: complete
+                        ? 'Decision evidence is complete under the declared scenarios'
+                        : 'Decision evidence contains a missing definition, unbound scenario input, or unsupported source path; inspect the linked report',
+                },
+            ],
+        };
+        return result;
+    }
+}