hoi4-agent-tools 2.1.1 → 2.3.0

package/dist/hoi4_agent_tools/probability/adapters.js

@@ -0,0 +1,344 @@
+import { PROBABILITY_ADAPTER_VERSION, VERIFIED_GAME_VERSION, } from './model.js';
+const evidenceRoot = 'docs/research/probability-adapter-evidence.md';
+const sources = {
+    event_mean_time_to_happen: {
+        id: 'event_mean_time_to_happen',
+        version: PROBABILITY_ADAPTER_VERSION,
+        gameVersion: VERIFIED_GAME_VERSION,
+        selectionRule: 'median_daily_hazard',
+        capabilities: {
+            eligibility: true,
+            rawScore: true,
+            normalizedProbability: false,
+            timeDistribution: true,
+            sequence: false,
+        },
+        completePoolRequired: false,
+        confidence: 'documented_with_runtime_boundary',
+        sourceBlockTypes: ['event mean_time_to_happen'],
+        evaluationCadence: 'daily while active; inactive triggers are polled every 20 days',
+        scopeExpectations: ['event root scope declared by the scenario'],
+        supportedExpressions: [
+            'base/add/factor',
+            'days/months/years',
+            'modifiers',
+            'script constants',
+            'MTTH variables',
+        ],
+        evidence: [evidenceRoot],
+        limitations: [
+            'The adapter models the verified daily median-hazard check only while the event trigger remains true.',
+            'The inactive-trigger 20-day polling cadence is reported separately and is not invented from missing scheduled state.',
+        ],
+    },
+    event_option_ai_chance: {
+        id: 'event_option_ai_chance',
+        version: PROBABILITY_ADAPTER_VERSION,
+        gameVersion: VERIFIED_GAME_VERSION,
+        selectionRule: 'proportional_categorical',
+        capabilities: {
+            eligibility: true,
+            rawScore: true,
+            normalizedProbability: true,
+            timeDistribution: false,
+            sequence: false,
+        },
+        completePoolRequired: true,
+        confidence: 'documented',
+        sourceBlockTypes: ['event option ai_chance'],
+        evaluationCadence: 'when the event option pool is selected',
+        scopeExpectations: ['event option root scope declared by the scenario'],
+        supportedExpressions: ['base/add/factor', 'modifiers', 'script constants', 'scripted triggers'],
+        evidence: [evidenceRoot],
+        limitations: [
+            'Runtime selection uses the engine d100 path; sub-one-percent outcomes are flagged.',
+        ],
+    },
+    decision_ai_will_do: {
+        id: 'decision_ai_will_do',
+        version: PROBABILITY_ADAPTER_VERSION,
+        gameVersion: VERIFIED_GAME_VERSION,
+        selectionRule: 'score_only',
+        capabilities: {
+            eligibility: true,
+            rawScore: true,
+            normalizedProbability: false,
+            timeDistribution: false,
+            sequence: false,
+        },
+        completePoolRequired: false,
+        confidence: 'documented_with_runtime_boundary',
+        sourceBlockTypes: ['decision ai_will_do'],
+        evaluationCadence: 'decision AI evaluation cadence; selection probability is not modeled',
+        scopeExpectations: ['country and target scopes declared by the scenario'],
+        supportedExpressions: ['base/add/factor', 'modifiers', 'script constants', 'scripted triggers'],
+        evidence: [evidenceRoot],
+        limitations: [
+            'Decision scores are not normalized without a documented complete selection rule.',
+        ],
+    },
+    mission_ai_will_do: {
+        id: 'mission_ai_will_do',
+        version: PROBABILITY_ADAPTER_VERSION,
+        gameVersion: VERIFIED_GAME_VERSION,
+        selectionRule: 'score_only',
+        capabilities: {
+            eligibility: true,
+            rawScore: true,
+            normalizedProbability: false,
+            timeDistribution: false,
+            sequence: false,
+        },
+        completePoolRequired: false,
+        confidence: 'documented_with_runtime_boundary',
+        sourceBlockTypes: ['mission ai_will_do'],
+        evaluationCadence: 'mission AI evaluation cadence; selection probability is not modeled',
+        scopeExpectations: ['country and target scopes declared by the scenario'],
+        supportedExpressions: ['base/add/factor', 'modifiers', 'script constants', 'scripted triggers'],
+        evidence: [evidenceRoot],
+        limitations: [
+            'Mission scores are not normalized without a documented complete selection rule.',
+        ],
+    },
+    national_focus_ai_will_do: {
+        id: 'national_focus_ai_will_do',
+        version: PROBABILITY_ADAPTER_VERSION,
+        gameVersion: VERIFIED_GAME_VERSION,
+        selectionRule: 'uniform_score_race',
+        capabilities: {
+            eligibility: true,
+            rawScore: true,
+            normalizedProbability: true,
+            timeDistribution: false,
+            sequence: false,
+        },
+        completePoolRequired: true,
+        confidence: 'documented_with_runtime_boundary',
+        sourceBlockTypes: ['national focus ai_will_do'],
+        evaluationCadence: 'next-focus selection',
+        scopeExpectations: ['country scope and complete available-focus pool declared by the scenario'],
+        supportedExpressions: [
+            'base/add/factor',
+            'modifiers',
+            'script constants',
+            'scripted triggers',
+            'declared focus strategy factors',
+        ],
+        evidence: [evidenceRoot],
+        limitations: [
+            'Ordered AI strategy plans can override weighted focus selection.',
+            'The prerequisite-completion multiplier and external focus factors require declared scenario inputs.',
+        ],
+    },
+    technology_ai_will_do: {
+        id: 'technology_ai_will_do',
+        version: PROBABILITY_ADAPTER_VERSION,
+        gameVersion: VERIFIED_GAME_VERSION,
+        selectionRule: 'uniform_score_race',
+        capabilities: {
+            eligibility: true,
+            rawScore: true,
+            normalizedProbability: true,
+            timeDistribution: false,
+            sequence: false,
+        },
+        completePoolRequired: true,
+        confidence: 'documented_with_runtime_boundary',
+        sourceBlockTypes: ['technology ai_will_do'],
+        evaluationCadence: 'research-slot technology selection',
+        scopeExpectations: [
+            'country scope and complete eligible technology pool declared by the scenario',
+        ],
+        supportedExpressions: [
+            'base/add/factor',
+            'modifiers',
+            'script constants',
+            'scripted triggers',
+            'declared research strategy factors',
+        ],
+        evidence: [evidenceRoot],
+        limitations: [
+            'Exact selection probability requires the complete eligible technology pool and every external research factor.',
+            'Research duration is distinct from selection score.',
+        ],
+    },
+    doctrine_ai_will_do: {
+        id: 'doctrine_ai_will_do',
+        version: PROBABILITY_ADAPTER_VERSION,
+        gameVersion: VERIFIED_GAME_VERSION,
+        selectionRule: 'uniform_score_race',
+        capabilities: {
+            eligibility: true,
+            rawScore: true,
+            normalizedProbability: true,
+            timeDistribution: false,
+            sequence: false,
+        },
+        completePoolRequired: true,
+        confidence: 'documented_with_runtime_boundary',
+        sourceBlockTypes: ['doctrine ai_will_do'],
+        evaluationCadence: 'research-slot doctrine selection',
+        scopeExpectations: [
+            'country scope and complete eligible doctrine pool declared by the scenario',
+        ],
+        supportedExpressions: [
+            'base/add/factor',
+            'modifiers',
+            'script constants',
+            'scripted triggers',
+            'declared research strategy factors',
+        ],
+        evidence: [evidenceRoot],
+        limitations: [
+            'Exact probability requires a declared complete eligible doctrine candidate pool.',
+        ],
+    },
+    direct_random: {
+        id: 'direct_random',
+        version: PROBABILITY_ADAPTER_VERSION,
+        gameVersion: VERIFIED_GAME_VERSION,
+        selectionRule: 'independent_chance',
+        capabilities: {
+            eligibility: false,
+            rawScore: true,
+            normalizedProbability: true,
+            timeDistribution: false,
+            sequence: false,
+        },
+        completePoolRequired: false,
+        confidence: 'documented',
+        sourceBlockTypes: ['random chance'],
+        evaluationCadence: 'when the enclosing random effect executes',
+        scopeExpectations: [
+            'enclosing effect scope declared by the scenario when conditions require it',
+        ],
+        supportedExpressions: ['numeric chance', 'script constants', 'declared variables'],
+        evidence: [evidenceRoot],
+        limitations: [
+            'The chance is an independent percentage and is never normalized against nearby blocks.',
+        ],
+    },
+    random_list: {
+        id: 'random_list',
+        version: PROBABILITY_ADAPTER_VERSION,
+        gameVersion: VERIFIED_GAME_VERSION,
+        selectionRule: 'proportional_categorical',
+        capabilities: {
+            eligibility: true,
+            rawScore: true,
+            normalizedProbability: true,
+            timeDistribution: false,
+            sequence: false,
+        },
+        completePoolRequired: true,
+        confidence: 'documented',
+        sourceBlockTypes: ['random_list entry'],
+        evaluationCadence: 'when the enclosing random_list executes',
+        scopeExpectations: ['enclosing effect scope declared by the scenario'],
+        supportedExpressions: [
+            'entry weights',
+            'weight modifiers',
+            'script constants',
+            'scripted triggers',
+        ],
+        evidence: [evidenceRoot],
+        limitations: [
+            'Dynamic entry keys and effect-derived weights remain unresolved unless declared.',
+        ],
+    },
+    ai_strategy_factor: {
+        id: 'ai_strategy_factor',
+        version: PROBABILITY_ADAPTER_VERSION,
+        gameVersion: VERIFIED_GAME_VERSION,
+        selectionRule: 'score_only',
+        capabilities: {
+            eligibility: true,
+            rawScore: true,
+            normalizedProbability: false,
+            timeDistribution: false,
+            sequence: false,
+        },
+        completePoolRequired: false,
+        confidence: 'documented_with_runtime_boundary',
+        sourceBlockTypes: ['ai_strategy factor'],
+        evaluationCadence: 'when the downstream AI selection surface reads the strategy',
+        scopeExpectations: ['strategy target and owning country declared by the source or scenario'],
+        supportedExpressions: ['numeric strategy value', 'script constants', 'declared variables'],
+        evidence: [evidenceRoot],
+        limitations: [
+            'Supported strategy factors modify a target score; a strategy definition is not itself a categorical pool.',
+        ],
+    },
+    custom_weighted_pool: {
+        id: 'custom_weighted_pool',
+        version: PROBABILITY_ADAPTER_VERSION,
+        gameVersion: VERIFIED_GAME_VERSION,
+        selectionRule: 'custom_declared',
+        capabilities: {
+            eligibility: true,
+            rawScore: true,
+            normalizedProbability: true,
+            timeDistribution: true,
+            sequence: true,
+        },
+        completePoolRequired: true,
+        confidence: 'manifest_defined',
+        sourceBlockTypes: ['custom weighted-pool manifest'],
+        evaluationCadence: 'manifest-declared cadence',
+        scopeExpectations: ['manifest state only'],
+        supportedExpressions: ['declared arithmetic', 'declared conditions', 'declared transitions'],
+        evidence: [evidenceRoot],
+        limitations: [
+            'Only state and transitions explicitly declared by the manifest are modeled.',
+            'No gameplay effects are executed or inferred.',
+        ],
+    },
+};
+function normalizationRule(selectionRule) {
+    switch (selectionRule) {
+        case 'proportional_categorical':
+            return [
+                'Normalize non-negative eligible values only when the local candidate pool is complete.',
+            ];
+        case 'uniform_score_race':
+            return ['Use the independent-uniform maximum-score race only for a complete eligible pool.'];
+        case 'independent_chance':
+            return ['Clamp the resolved percentage to [0,100] and never normalize against neighbors.'];
+        case 'median_daily_hazard':
+            return ['Do not normalize; convert timing only through the verified median-hazard model.'];
+        case 'score_only':
+            return ['Return scores and ranks without inventing a categorical denominator.'];
+        case 'custom_declared':
+            return ['Use only the normalization event and selection mode declared by the manifest.'];
+    }
+}
+const descriptors = Object.fromEntries(Object.entries(sources).map(([id, source]) => [
+    id,
+    {
+        ...source,
+        supportedGameVersions: [VERIFIED_GAME_VERSION],
+        candidateDiscoveryRules: source.sourceBlockTypes.map((blockType) => `Discover active, unshadowed ${blockType} definitions through the shared index.`),
+        eligibilityRules: source.capabilities.eligibility
+            ? ['Evaluate source eligibility and declared candidate overrides with three-valued logic.']
+            : ['The surface is independently evaluated and has no candidate-pool eligibility step.'],
+        modifierOrder: [
+            'Evaluate the base expression, then source add/factor operations and modifiers in source order.',
+            'Apply declared external factors only after source-local operations.',
+        ],
+        poolNormalizationRules: normalizationRule(source.selectionRule),
+        timingConversion: source.selectionRule === 'median_daily_hazard'
+            ? [
+                'Treat the effective duration as the median of verified daily checks while active.',
+                'Bound activation through the verified 20-day inactive polling phase when its phase is undeclared.',
+            ]
+            : ['No time-distribution conversion is claimed for this adapter.'],
+        unsupportedConstructs: [...source.limitations],
+        testFixtures: ['fixtures/probability', evidenceRoot],
+    },
+]));
+export function probabilityAdapter(id) {
+    return descriptors[id];
+}
+export function probabilityAdapters() {
+    return Object.values(descriptors);
+}

package/dist/hoi4_agent_tools/probability/compare.js

@@ -0,0 +1,178 @@
+function raw(candidate) {
+    const value = candidate?.rawValue;
+    if (typeof value === 'object' && value !== null)
+        return value.value;
+    if (typeof value === 'number')
+        return value;
+    return undefined;
+}
+function traceSignature(candidate) {
+    return new Set((candidate?.trace ?? []).map(({ operation, expression, applied, after }) => `${operation}:${expression}:${applied}:${after?.decimal ?? ''}`));
+}
+function attribution(before, after) {
+    if (before === undefined)
+        return ['candidate added'];
+    if (after === undefined)
+        return ['candidate removed'];
+    const beforeTrace = traceSignature(before);
+    const afterTrace = traceSignature(after);
+    const changes = [
+        ...[...afterTrace].filter((item) => !beforeTrace.has(item)).map((item) => `added ${item}`),
+        ...[...beforeTrace].filter((item) => !afterTrace.has(item)).map((item) => `removed ${item}`),
+    ];
+    if (before.eligibility !== after.eligibility)
+        changes.unshift(`eligibility ${before.eligibility} -> ${after.eligibility}`);
+    return changes.length > 0 ? changes : ['source or scenario metadata changed'];
+}
+function changedAstPaths(before, after) {
+    const terms = (candidate) => new Map((candidate?.trace ?? []).flatMap((step) => {
+        const provenance = step.provenance;
+        if (provenance?.astPath === undefined)
+            return [];
+        const key = JSON.stringify({
+            operation: step.operation,
+            expression: step.expression,
+            applied: step.applied,
+            after: step.after?.decimal,
+            path: provenance.path,
+            astPath: provenance.astPath,
+        });
+        return [[key, { path: provenance.path, astPath: provenance.astPath }]];
+    }));
+    const previous = terms(before);
+    const current = terms(after);
+    return [
+        ...[...current]
+            .filter(([key]) => !previous.has(key))
+            .map(([, source]) => ({ change: 'added', ...source })),
+        ...[...previous]
+            .filter(([key]) => !current.has(key))
+            .map(([, source]) => ({ change: 'removed', ...source })),
+    ];
+}
+function metricValue(candidate, metric) {
+    if (candidate === undefined)
+        return undefined;
+    if (metric === 'raw_value')
+        return raw(candidate);
+    if (metric === 'conditional_probability')
+        return candidate.conditionalProbability ?? undefined;
+    if (metric === 'cumulative_chance')
+        return candidate.cumulativeChance;
+    return candidate.effectiveMtthDays;
+}
+function insideBand(value, band) {
+    return (value !== undefined &&
+        (band.min === undefined || value >= band.min) &&
+        (band.max === undefined || value <= band.max));
+}
+export function compareProbabilityResults(before, after, acceptanceBands = []) {
+    const scenarioChanges = [];
+    const regressions = [];
+    const scenarioIds = new Set([
+        ...before.scenarios.map(({ id }) => id),
+        ...after.scenarios.map(({ id }) => id),
+    ]);
+    for (const scenarioId of scenarioIds) {
+        const beforeScenario = before.scenarios.find(({ id }) => id === scenarioId);
+        const afterScenario = after.scenarios.find(({ id }) => id === scenarioId);
+        const candidateIds = new Set([
+            ...(beforeScenario?.candidates.map(({ id }) => id) ?? []),
+            ...(afterScenario?.candidates.map(({ id }) => id) ?? []),
+        ]);
+        for (const candidateId of candidateIds) {
+            const previous = beforeScenario?.candidates.find(({ id }) => id === candidateId);
+            const current = afterScenario?.candidates.find(({ id }) => id === candidateId);
+            const rawBefore = raw(previous);
+            const rawAfter = raw(current);
+            const probabilityBefore = previous?.conditionalProbability ?? undefined;
+            const probabilityAfter = current?.conditionalProbability ?? undefined;
+            const rankBefore = previous?.rank ?? undefined;
+            const rankAfter = current?.rank ?? undefined;
+            const timingBefore = previous?.effectiveMtthDays;
+            const timingAfter = current?.effectiveMtthDays;
+            const cumulativeBefore = previous?.cumulativeChance;
+            const cumulativeAfter = current?.cumulativeChance;
+            const changed = previous === undefined ||
+                current === undefined ||
+                rawBefore !== rawAfter ||
+                probabilityBefore !== probabilityAfter ||
+                rankBefore !== rankAfter ||
+                previous.eligibility !== current.eligibility ||
+                timingBefore !== timingAfter ||
+                cumulativeBefore !== cumulativeAfter ||
+                previous.unresolved.length !== current.unresolved.length;
+            if (!changed)
+                continue;
+            scenarioChanges.push({
+                scenarioId,
+                candidateId,
+                ...(rawBefore === undefined || rawAfter === undefined
+                    ? {}
+                    : { rawDelta: rawAfter - rawBefore }),
+                ...(probabilityBefore === undefined || probabilityAfter === undefined
+                    ? {}
+                    : { probabilityDelta: probabilityAfter - probabilityBefore }),
+                ...(rankBefore === undefined || rankAfter === undefined
+                    ? {}
+                    : { rankDelta: rankAfter - rankBefore }),
+                ...(timingBefore === undefined || timingAfter === undefined
+                    ? {}
+                    : { timingDeltaDays: timingAfter - timingBefore }),
+                ...(cumulativeBefore === undefined || cumulativeAfter === undefined
+                    ? {}
+                    : { cumulativeChanceDelta: cumulativeAfter - cumulativeBefore }),
+                ...(previous === undefined ||
+                    current === undefined ||
+                    previous.eligibility === current.eligibility
+                    ? {}
+                    : {
+                        eligibilityChange: {
+                            before: previous.eligibility,
+                            after: current.eligibility,
+                        },
+                    }),
+                unresolvedDelta: (current?.unresolved.length ?? 0) - (previous?.unresolved.length ?? 0),
+                attribution: attribution(previous, current),
+                changedAstPaths: changedAstPaths(previous, current),
+            });
+            if ((previous?.unresolved.length ?? 0) < (current?.unresolved.length ?? 0))
+                regressions.push({
+                    code: 'UNRESOLVED_ANALYSIS_INTRODUCED',
+                    message: `Patch introduced unresolved analysis for ${candidateId}`,
+                    scenarioId,
+                    candidateId,
+                });
+            if (probabilityBefore !== undefined && probabilityBefore > 0 && probabilityAfter === 0)
+                regressions.push({
+                    code: 'CANDIDATE_STARVED',
+                    message: `Patch reduces ${candidateId} from a selectable outcome to zero probability`,
+                    scenarioId,
+                    candidateId,
+                });
+            for (const band of acceptanceBands) {
+                if (band.candidateId !== candidateId ||
+                    (band.scenarioId !== undefined && band.scenarioId !== scenarioId))
+                    continue;
+                const previousMetric = metricValue(previous, band.metric);
+                const currentMetric = metricValue(current, band.metric);
+                if (insideBand(previousMetric, band) && !insideBand(currentMetric, band))
+                    regressions.push({
+                        code: 'ACCEPTANCE_BAND_REGRESSION',
+                        message: `Patch moves ${candidateId} outside acceptance band ${band.id}`,
+                        scenarioId,
+                        candidateId,
+                    });
+            }
+        }
+    }
+    return {
+        beforeAnalysisId: before.analysisId,
+        afterAnalysisId: after.analysisId,
+        assumptionsChanged: before.metadata.scenarioHash !== after.metadata.scenarioHash,
+        adapterChanged: before.metadata.adapterId !== after.metadata.adapterId ||
+            before.metadata.adapterVersion !== after.metadata.adapterVersion,
+        scenarioChanges,
+        regressions,
+    };
+}