hoi4-agent-tools 2.7.0 → 2.8.1

package/CHANGELOG.md

@@ -4,6 +4,17 @@
 
 No unreleased changes.
 
+## 2.8.1 - 2026-08-27
+
+- Added periodic MCP progress heartbeats for long GUI inspections, renders, and rewrites, with repeated progress notifications that preserve monotonic work values and still honor cancellation.
+
+## 2.8.0 - 2026-08-26
+
+- Added structured `ROOT`, `THIS`, `PREV`, `FROM` chain, saved-scope, and event-target bindings to probability scenarios.
+- Added deterministic enumeration and exact complete-pool shares for declared dynamic destination, opposition, donor, and other runtime scope pools.
+- Extended exact branching, sweeps, and simulation to update scoped and pool-candidate state without flattening it into the root scenario.
+- Added MCP resource counts, a published callable example, 2,048-candidate coverage, and source-linked trigger traces for dynamic scope pools.
+
 ## 2.7.0 - 2026-08-24
 
 - Made scripted-GUI layout follow Clausewitz orientation, element-origin, center-position, relative-dimension, local-scale, container-clipping, and fixed text-bound behavior.

package/README.md

@@ -9,7 +9,7 @@ HOI4 Agent Tools is an MCP server for coding agents to understand Hearts of Iron
 - Maps: navigate the complete rendered map by ID or localised name; inspect provinces, states, regions, adjacency, supply, railways, and positions; create states and provinces; change IDs; and repair connected map data.
 - Event chains: scan definitions and call sites, trace routes and state flow, lint references, render graphs, and compare revisions without editing event source.
 - Technology trees: reconstruct technology and doctrine paths, folder layouts, unlocks, bonuses, grants, metadata, assets, and structural changes.
-- AI and MTTH: evaluate weighted choices and timing across explicit scenarios, sweep uncertain inputs, simulate distributions, compare patches, and analyze declared stateful pools.
+- AI and MTTH: evaluate weighted choices and timing across explicit scenarios, bind special scope chains, enumerate dynamic target pools, sweep uncertain inputs, simulate distributions, compare patches, and analyze declared stateful pools.
 
 ## Setup
 

package/dist/hoi4_agent_tools/mcp/server/create.js

@@ -8,7 +8,7 @@ import { registerEventTools } from '../tools/event.js';
 import { registerTechnologyTools } from '../tools/technology.js';
 import { registerProbabilityTools } from '../tools/probability.js';
 import { registerMcpResources } from '../resources/register.js';
-export const SERVER_INSTRUCTIONS = 'Use focus tools for focus trees, GUI tools for interfaces, and map tools for map data. Start unfamiliar event chains with hoi4.event_inspect. Event tools are read-only. Start technology and doctrine work with hoi4.tech_inspect. Technology tools are read-only. Start weighted AI, MTTH, random, and declared-pool analysis with hoi4.probability_inspect. Probability tools are read-only. Large evidence is linked as resources.';
+export const SERVER_INSTRUCTIONS = 'Use focus tools for focus trees, GUI tools for interfaces, and map tools for map data. Start unfamiliar event chains with hoi4.event_inspect. Event tools are read-only. Start technology and doctrine work with hoi4.tech_inspect. Technology tools are read-only. Start weighted AI, MTTH, random, and declared-pool analysis with hoi4.probability_inspect. Probability tools are read-only. Long GUI calls emit periodic progress heartbeats when the client requests progress. Large evidence is linked as resources.';
 export function createMcpServer(engine, context = {}) {
     const server = new McpServer({
         name: PACKAGE_NAME,

package/dist/hoi4_agent_tools/mcp/server/progress.js

@@ -1,9 +1,18 @@
+/**
+ * Interval used for long-running MCP operations. It is shorter than the request timeout used by
+ * common MCP clients, while still keeping notification traffic negligible for ordinary calls.
+ */
+export const PROGRESS_HEARTBEAT_INTERVAL_MS = 10_000;
 export function progressReporter(extra) {
     let latest = Number.NEGATIVE_INFINITY;
+    let latestTotal = 1;
+    let latestMessage = '';
     return {
         signal: extra.signal,
         async report(progress, total, message) {
             extra.signal.throwIfAborted();
+            latestTotal = total;
+            latestMessage = message;
             const normalized = Math.max(latest, Math.min(progress, total));
             const progressToken = extra._meta?.progressToken;
             if (progressToken === undefined)
@@ -16,5 +25,53 @@ export function progressReporter(extra) {
                 params: { progressToken, progress: normalized, total, message },
             });
         },
+        async pulse(message = latestMessage) {
+            extra.signal.throwIfAborted();
+            const progressToken = extra._meta?.progressToken;
+            if (progressToken === undefined)
+                return;
+            await extra.sendNotification({
+                method: 'notifications/progress',
+                params: {
+                    progressToken,
+                    progress: Number.isFinite(latest) ? latest : 0,
+                    total: latestTotal,
+                    message,
+                },
+            });
+        },
+    };
+}
+/**
+ * Keep an MCP request alive while a domain service is in a long, opaque asynchronous stage.
+ * Progress notifications are best-effort: a disconnected client must not turn a successful
+ * server operation into a partial result, while the request's AbortSignal still cancels work.
+ */
+export async function withProgressHeartbeat(operation, reporter, message, intervalMs = PROGRESS_HEARTBEAT_INTERVAL_MS) {
+    if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+        throw new RangeError('Progress heartbeat interval must be a positive finite number');
+    }
+    reporter.signal.throwIfAborted();
+    let active = true;
+    let inFlight = false;
+    const tick = () => {
+        if (!active || inFlight || reporter.signal.aborted)
+            return;
+        inFlight = true;
+        void reporter
+            .pulse(message)
+            .catch(() => undefined)
+            .finally(() => {
+            inFlight = false;
+        });
     };
+    const timer = setInterval(tick, intervalMs);
+    timer.unref();
+    try {
+        return await (typeof operation === 'function' ? operation() : operation);
+    }
+    finally {
+        active = false;
+        clearInterval(timer);
+    }
 }

package/dist/hoi4_agent_tools/mcp/tools/gui.js

@@ -12,7 +12,7 @@ import { requireServerScope, resolveServerWorkspaceId, } from '../server/base-to
 import { compactValidatedInputSchema } from '../server/context-schemas.js';
 import { autonomousFailureContext, autonomousResultArtifacts, executePlannedTransaction, } from '../server/transaction-execution.js';
 import { indexSkippedSourceSchema, nonNegativeIntegerSchema, sha256Schema, } from '../server/output-schemas.js';
-import { progressReporter } from '../server/progress.js';
+import { progressReporter, withProgressHeartbeat } from '../server/progress.js';
 import { errorResult, setInlineFilesScanned, strictOperationResultSchema, toolResult, } from '../server/result.js';
 const countRecordSchema = z.record(z.string().max(256), nonNegativeIntegerSchema);
 const guiScanOutputSchema = strictOperationResultSchema(z
@@ -156,21 +156,21 @@ export function registerGuiTools(server, engine, context) {
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Building GUI source graph');
-            const inspection = windowName === undefined || scenario === undefined
-                ? studio
-                    .scan(workspaceId, context.principal, progress.signal)
-                    .then(({ graph }) => ({ graph, linted: undefined }))
-                : studio
-                    .lint({
+            const inspected = await withProgressHeartbeat(async () => {
+                if (windowName === undefined || scenario === undefined) {
+                    const { graph } = await studio.scan(workspaceId, context.principal, progress.signal);
+                    return { graph, linted: undefined };
+                }
+                const linted = await studio.lint({
                     workspaceId,
                     windowName,
                     scenario,
                     ...(relatedScenarios === undefined ? {} : { relatedScenarios }),
                     ...(context.principal === undefined ? {} : { principal: context.principal }),
                     signal: progress.signal,
-                })
-                    .then((linted) => ({ graph: linted.graph, linted }));
-            const inspected = await inspection;
+                });
+                return { graph: linted.graph, linted };
+            }, progress, 'Inspecting GUI sources and linked assets');
             const { graph, linted } = inspected;
             const sharedRevision = hashCanonical(graph.sourceHashes);
             const workspace = engine.resolver.get(workspaceId, context.principal);
@@ -268,7 +268,7 @@ export function registerGuiTools(server, engine, context) {
         try {
             const progress = progressReporter(extra);
             await progress.report(0, 4, 'Building GUI source graph');
-            const rendered = await studio.renderAndStore({
+            const rendered = await withProgressHeartbeat(() => studio.renderAndStore({
                 workspaceId,
                 windowName,
                 scenario: input.scenario,
@@ -290,7 +290,7 @@ export function registerGuiTools(server, engine, context) {
                     : { comparisonScenario: input.comparisonScenario }),
                 ...(context.principal === undefined ? {} : { principal: context.principal }),
                 signal: progress.signal,
-            });
+            }), progress, 'Rendering GUI variants and visual diagnostics');
             await progress.report(3, 4, 'Preparing GUI result');
             const diagnostics = rendered.validation.diagnostics;
             const result = emptyServiceResult(workspaceId, {
@@ -471,7 +471,7 @@ export function registerGuiTools(server, engine, context) {
             const progress = progressReporter(extra);
             await progress.report(0, 3, 'Validating the requested GUI result');
             const compilation = input.mode === 'helpers' ? compileGuiHelpers(input.helper) : undefined;
-            const plannedTransaction = await studio.planSource({
+            const plannedTransaction = await withProgressHeartbeat(() => studio.planSource({
                 workspaceId,
                 relativePath,
                 ...(input.mode === 'patches'
@@ -489,9 +489,9 @@ export function registerGuiTools(server, engine, context) {
                 scenario,
                 ...(context.principal === undefined ? {} : { principal: context.principal }),
                 signal: progress.signal,
-            });
+            }), progress, 'Preparing GUI rewrite');
             await progress.report(2, 3, 'Applying and validating the GUI rewrite');
-            const execution = await executePlannedTransaction(engine, plannedTransaction, context.principal, progress.signal);
+            const execution = await withProgressHeartbeat(() => executePlannedTransaction(engine, plannedTransaction, context.principal, progress.signal), progress, 'Applying GUI rewrite');
             const transaction = execution.transaction;
             const planned = {
                 transaction,

package/dist/hoi4_agent_tools/mcp/tools/probability.js

@@ -120,6 +120,8 @@ const analysisDataSchema = z
     cacheKey: sha256Schema,
     scenarios: nonNegativeIntegerSchema,
     candidates: nonNegativeIntegerSchema,
+    scopePools: nonNegativeIntegerSchema.optional(),
+    scopePoolCandidates: nonNegativeIntegerSchema.optional(),
     unresolved: nonNegativeIntegerSchema,
     diagnostics: nonNegativeIntegerSchema,
     sweepPoints: nonNegativeIntegerSchema.optional(),
@@ -194,6 +196,13 @@ function analysisData(result) {
         cacheKey: result.metadata.cacheKey,
         scenarios: result.scenarios.length,
         candidates: result.scenarios.reduce((sum, scenario) => sum + scenario.candidates.length, 0),
+        ...(result.scenarios.some(({ scopePools }) => (scopePools?.length ?? 0) > 0)
+            ? {
+                scopePools: result.scenarios.reduce((sum, scenario) => sum + (scenario.scopePools?.length ?? 0), 0),
+                scopePoolCandidates: result.scenarios.reduce((sum, scenario) => sum +
+                    (scenario.scopePools?.reduce((poolSum, pool) => poolSum + pool.candidates.length, 0) ?? 0), 0),
+            }
+            : {}),
         unresolved: result.unresolved.length,
         diagnostics: result.diagnostics.length,
         ...(result.sweep === undefined ? {} : { sweepPoints: result.sweep.points.length }),

package/dist/hoi4_agent_tools/probability/adapters.js

@@ -326,6 +326,11 @@ const descriptors = Object.fromEntries(Object.entries(sources).map(([id, source]
             'Apply declared external factors only after source-local operations.',
         ],
         poolNormalizationRules: normalizationRule(source.selectionRule),
+        supportedExpressions: [
+            ...source.supportedExpressions,
+            'scenario-bound ROOT/THIS/PREV/FROM scope chains, saved scopes, and event targets',
+            'declared dynamic scope-pool filters with uniform or proportional selection',
+        ],
         timingConversion: source.selectionRule === 'median_daily_hazard'
             ? [
                 'Treat the effective duration as the median of verified daily checks while active.',

package/dist/hoi4_agent_tools/probability/evaluation.js

@@ -1,6 +1,8 @@
 import { compareCodeUnits } from '../core/canonical.js';
 import { assignments } from '../core/source/index.js';
 import { Rational, sumRationals, uniformRaceProbabilities } from './rational.js';
+import { withScenarioPathValue } from './scenario-state.js';
+import { evaluateScopePools } from './scope-pools.js';
 import { evaluateTriggerBlock } from './trigger-evaluator.js';
 import { evaluateCandidateValue } from './value-evaluator.js';
 const BRANCH_LIMIT = 4_096;
@@ -305,7 +307,7 @@ function scenarioBranches(surface, scenario) {
             });
             break;
         }
-        branches = branches.flatMap((branch) => values.map((value) => ({ ...branch, state: { ...branch.state, [input.path]: value } })));
+        branches = branches.flatMap((branch) => values.map((value) => withScenarioPathValue(branch, input.path, value)));
         if (values.length > 1)
             bounded = true;
     }
@@ -599,10 +601,12 @@ export function evaluateSurfaceScenarios(surface, scenarios, definitions, horizo
             return result;
         });
         rankCandidates(candidates);
+        const scopePools = evaluateScopePools(scenario, definitions);
         const allUnresolved = [
             ...surface.unsupported,
             ...expanded.unresolved,
             ...candidates.flatMap(({ unresolved }) => unresolved),
+            ...scopePools.flatMap(({ unresolved }) => unresolved),
         ];
         const timing = horizonDays === undefined
             ? { unresolved: [] }
@@ -632,6 +636,7 @@ export function evaluateSurfaceScenarios(surface, scenarios, definitions, horizo
                             ? 'score_only'
                             : 'exact',
             candidates,
+            ...(scopePools.length === 0 ? {} : { scopePools }),
             ...(exactValues.length === candidates.length &&
                 surface.adapter.selectionRule === 'proportional_categorical'
                 ? { poolTotal: sumRationals(exactValues).toJSON() }

package/dist/hoi4_agent_tools/probability/scenario-state.js

@@ -0,0 +1,165 @@
+function caseInsensitiveEntry(record, key) {
+    if (record === undefined)
+        return undefined;
+    if (Object.hasOwn(record, key))
+        return record[key];
+    const normalized = key.toLowerCase();
+    const found = Object.entries(record).find(([candidate]) => candidate.toLowerCase() === normalized);
+    return found?.[1];
+}
+export function rootScopeContext(scenario) {
+    return {
+        expression: 'ROOT',
+        binding: {
+            id: scenario.actor ?? 'ROOT',
+            ...(scenario.actor === undefined ? {} : { actor: scenario.actor }),
+            state: scenario.state,
+            ...(scenario.flags === undefined ? {} : { flags: scenario.flags }),
+            ...(scenario.eventTargets === undefined ? {} : { eventTargets: scenario.eventTargets }),
+        },
+    };
+}
+function explicitScope(scenario, expression, parent) {
+    const binding = caseInsensitiveEntry(scenario.scopes, expression);
+    return binding === undefined ? undefined : { expression, binding, parent };
+}
+export function resolveScopeContext(scenario, expression, current) {
+    const upper = expression.toUpperCase();
+    if (upper === 'ROOT')
+        return rootScopeContext(scenario);
+    if (upper === 'THIS')
+        return current;
+    if (upper === 'PREV')
+        return current.parent ?? rootScopeContext(scenario);
+    const chained = current.expression === 'ROOT' || current.expression === 'THIS'
+        ? expression
+        : `${current.expression}.${expression}`;
+    const chainedBinding = explicitScope(scenario, chained, current);
+    if (chainedBinding !== undefined)
+        return chainedBinding;
+    const direct = explicitScope(scenario, expression, current);
+    if (direct !== undefined)
+        return direct;
+    const targetMatch = /^(?:event_target|scope):(.+)$/iu.exec(expression);
+    const targetId = targetMatch === null
+        ? undefined
+        : (caseInsensitiveEntry(current.binding.eventTargets, targetMatch[1]) ??
+            caseInsensitiveEntry(scenario.eventTargets, targetMatch[1]));
+    if (targetId !== undefined) {
+        const declaredBinding = Object.values(scenario.scopes ?? {}).find((binding) => binding.id === targetId || binding.actor === targetId);
+        return {
+            expression,
+            binding: declaredBinding ?? { id: targetId, actor: targetId, state: {} },
+            parent: current,
+        };
+    }
+    return undefined;
+}
+export function scopeStateValue(scenario, key, current) {
+    if (Object.hasOwn(current.binding.state, key))
+        return current.binding.state[key];
+    if (Object.hasOwn(current.binding.state, `trigger.${key}`))
+        return current.binding.state[`trigger.${key}`];
+    if (current.expression !== 'ROOT')
+        return undefined;
+    if (Object.hasOwn(scenario.state, key))
+        return scenario.state[key];
+    if (Object.hasOwn(scenario.state, `trigger.${key}`))
+        return scenario.state[`trigger.${key}`];
+    return undefined;
+}
+export function rootStateValue(scenario, key) {
+    if (Object.hasOwn(scenario.state, key))
+        return scenario.state[key];
+    if (Object.hasOwn(scenario.state, `trigger.${key}`))
+        return scenario.state[`trigger.${key}`];
+    return undefined;
+}
+export function scopeIdentity(current) {
+    return current.binding.actor ?? current.binding.id;
+}
+export function scopedExpressionValue(scenario, expression) {
+    const scopes = Object.entries(scenario.scopes ?? {}).sort(([left], [right]) => right.length - left.length);
+    for (const [scope, binding] of scopes) {
+        for (const prefix of [`${scope}.`, `scope.${scope}.`, `scopes.${scope}.`]) {
+            if (!expression.toLowerCase().startsWith(prefix.toLowerCase()))
+                continue;
+            const key = expression.slice(prefix.length).replace(/^state\./u, '');
+            if (Object.hasOwn(binding.state, key))
+                return binding.state[key];
+            if (Object.hasOwn(binding.state, `variable.${key}`))
+                return binding.state[`variable.${key}`];
+        }
+    }
+    return undefined;
+}
+function updateScopeState(scenario, path, value) {
+    const scopes = Object.entries(scenario.scopes ?? {}).sort(([left], [right]) => right.length - left.length);
+    for (const [scope, binding] of scopes) {
+        for (const prefix of [`scope.${scope}.`, `scopes.${scope}.`]) {
+            if (!path.toLowerCase().startsWith(prefix.toLowerCase()))
+                continue;
+            const key = path.slice(prefix.length).replace(/^state\./u, '');
+            return {
+                ...scenario,
+                scopes: {
+                    ...scenario.scopes,
+                    [scope]: { ...binding, state: { ...binding.state, [key]: value } },
+                },
+            };
+        }
+    }
+    return undefined;
+}
+function updatePoolCandidateState(scenario, path, value) {
+    if (!path.startsWith('scopePools.'))
+        return undefined;
+    for (const [poolIndex, pool] of (scenario.scopePools ?? []).entries()) {
+        const poolPrefix = `scopePools.${pool.id}.`;
+        if (!path.startsWith(poolPrefix))
+            continue;
+        for (const [candidateIndex, candidate] of pool.candidates.entries()) {
+            const candidatePrefix = `${poolPrefix}${candidate.id}.`;
+            if (!path.startsWith(candidatePrefix))
+                continue;
+            const key = path.slice(candidatePrefix.length).replace(/^state\./u, '');
+            const candidates = [...pool.candidates];
+            candidates[candidateIndex] = {
+                ...candidate,
+                state: { ...candidate.state, [key]: value },
+            };
+            const pools = [...(scenario.scopePools ?? [])];
+            pools[poolIndex] = { ...pool, candidates };
+            return { ...scenario, scopePools: pools };
+        }
+    }
+    return undefined;
+}
+export function scenarioPathValue(scenario, path) {
+    const scoped = scopedExpressionValue(scenario, path);
+    if (scoped !== undefined)
+        return scoped;
+    if (path.startsWith('scopePools.')) {
+        for (const pool of scenario.scopePools ?? []) {
+            const poolPrefix = `scopePools.${pool.id}.`;
+            if (!path.startsWith(poolPrefix))
+                continue;
+            for (const candidate of pool.candidates) {
+                const candidatePrefix = `${poolPrefix}${candidate.id}.`;
+                if (!path.startsWith(candidatePrefix))
+                    continue;
+                const key = path.slice(candidatePrefix.length).replace(/^state\./u, '');
+                if (Object.hasOwn(candidate.state, key))
+                    return candidate.state[key];
+            }
+        }
+    }
+    return rootStateValue(scenario, path);
+}
+export function withScenarioPathValue(scenario, path, value) {
+    return (updateScopeState(scenario, path, value) ??
+        updatePoolCandidateState(scenario, path, value) ?? {
+        ...scenario,
+        state: { ...scenario.state, [path]: value },
+    });
+}

package/dist/hoi4_agent_tools/probability/scope-pools.js

@@ -0,0 +1,199 @@
+import { compareCodeUnits, hashCanonical } from '../core/canonical.js';
+import { childBlocks, parseClausewitz, } from '../core/source/index.js';
+import { Rational, sumRationals } from './rational.js';
+import { rootScopeContext, scopedExpressionValue, } from './scenario-state.js';
+import { evaluateTriggerBlock } from './trigger-evaluator.js';
+function filterSource(pool) {
+    if (pool.filter?.scriptedTrigger !== undefined)
+        return `filter = { ${pool.filter.scriptedTrigger} = yes }`;
+    const inline = pool.filter?.inlineClausewitz?.trim();
+    if (inline === undefined)
+        return undefined;
+    if (/^filter\s*=/iu.test(inline))
+        return inline;
+    return inline.startsWith('{') ? `filter = ${inline}` : `filter = { ${inline} }`;
+}
+function parseFilter(scenario, pool) {
+    const source = filterSource(pool);
+    const sourceHash = hashCanonical({ scenarioId: scenario.id, poolId: pool.id, source });
+    if (source === undefined)
+        return { sourceHash, unresolved: [] };
+    const path = `scenario:${scenario.id}/scope-pool:${pool.id}`;
+    try {
+        const document = parseClausewitz(Buffer.from(source, 'utf8'), path);
+        const block = childBlocks(document.root, 'filter')[0];
+        if (block !== undefined)
+            return { document, block, sourceHash, unresolved: [] };
+    }
+    catch (error) {
+        return {
+            sourceHash,
+            unresolved: [
+                {
+                    code: 'SCOPE_POOL_FILTER_INVALID',
+                    message: `Scope pool ${pool.id} filter could not be parsed`,
+                    path: pool.id,
+                    details: { reason: error instanceof Error ? error.message : String(error) },
+                },
+            ],
+        };
+    }
+    return {
+        sourceHash,
+        unresolved: [
+            {
+                code: 'SCOPE_POOL_FILTER_INVALID',
+                message: `Scope pool ${pool.id} filter does not contain a trigger block`,
+                path: pool.id,
+            },
+        ],
+    };
+}
+function scopedScenario(scenario, pool, binding) {
+    const bindAs = pool.bindAs ?? 'THIS';
+    if (bindAs === 'ROOT') {
+        const root = {
+            ...scenario,
+            actor: binding.actor ?? binding.id,
+            state: binding.state,
+            ...(binding.flags === undefined ? {} : { flags: binding.flags }),
+            ...(binding.eventTargets === undefined ? {} : { eventTargets: binding.eventTargets }),
+            scopes: { ...scenario.scopes, ROOT: binding, THIS: binding },
+        };
+        return { scenario: root, context: rootScopeContext(root) };
+    }
+    const selected = {
+        ...scenario,
+        scopes: {
+            ...scenario.scopes,
+            THIS: binding,
+            [bindAs]: binding,
+        },
+    };
+    return {
+        scenario: selected,
+        context: {
+            expression: 'THIS',
+            binding,
+            parent: rootScopeContext(scenario),
+        },
+    };
+}
+function candidateFor(scenario, pool, binding, filter) {
+    return {
+        id: binding.id,
+        adapterId: 'custom_weighted_pool',
+        sourceKind: 'dynamic_scope_pool_candidate',
+        defaultValue: '1',
+        ...(filter.document === undefined ? {} : { document: filter.document }),
+        provenance: [
+            {
+                path: `scenario:${scenario.id}/scope-pool:${pool.id}`,
+                rootKind: 'scenario',
+                loadOrder: 0,
+                sourceHash: filter.sourceHash,
+                symbol: binding.id,
+            },
+        ],
+        metadata: { poolId: pool.id, bindAs: pool.bindAs ?? 'THIS' },
+    };
+}
+function poolWeight(pool, binding, scenario) {
+    if (pool.selection === 'uniform')
+        return Rational.one;
+    const expression = binding.weight ?? 1;
+    const direct = Rational.parse(expression);
+    if (direct !== undefined)
+        return direct.compare(Rational.zero) < 0 ? undefined : direct;
+    if (typeof expression !== 'string')
+        return undefined;
+    const value = binding.state[expression] ??
+        binding.state[`variable.${expression}`] ??
+        scopedExpressionValue(scenario, expression) ??
+        scenario.state[expression] ??
+        scenario.state[`variable.${expression}`];
+    const parsed = typeof value === 'number' || typeof value === 'string' ? Rational.parse(value) : undefined;
+    return parsed !== undefined && parsed.compare(Rational.zero) >= 0 ? parsed : undefined;
+}
+function evaluatePool(scenario, pool, definitions) {
+    const filter = parseFilter(scenario, pool);
+    const candidates = [...pool.candidates]
+        .sort((left, right) => compareCodeUnits(left.id, right.id))
+        .map((binding) => {
+        const selected = scopedScenario(scenario, pool, binding);
+        const candidate = candidateFor(scenario, pool, binding, filter);
+        const eligibility = filter.unresolved.length > 0
+            ? { state: 'unresolved', unresolved: filter.unresolved }
+            : evaluateTriggerBlock(filter.block, selected.scenario, candidate, definitions, [], selected.context);
+        const unresolved = [...eligibility.unresolved];
+        const weight = pool.selection === 'enumeration' ? undefined : poolWeight(pool, binding, selected.scenario);
+        if (pool.selection !== 'enumeration' && weight === undefined)
+            unresolved.push({
+                code: 'SCOPE_POOL_WEIGHT_UNRESOLVED',
+                message: `Scope pool ${pool.id} candidate ${binding.id} has an unresolved weight`,
+                path: pool.id,
+                candidateId: binding.id,
+                details: { weight: binding.weight ?? 1 },
+            });
+        return {
+            id: binding.id,
+            eligibility: eligibility.state,
+            ...(weight === undefined ? {} : { weight: weight.toJSON() }),
+            trace: eligibility.trace ?? [],
+            unresolved,
+        };
+    });
+    const unresolved = [
+        ...filter.unresolved,
+        ...candidates.flatMap(({ unresolved: items }) => items),
+    ];
+    if (pool.selection !== 'enumeration' && !pool.complete)
+        unresolved.push({
+            code: 'SCOPE_POOL_INCOMPLETE',
+            message: `Scope pool ${pool.id} can be enumerated, but normalized probabilities require a complete candidate catalog`,
+            path: pool.id,
+        });
+    const resolved = candidates.every(({ eligibility, weight }) => eligibility !== 'unresolved' && (pool.selection === 'enumeration' || weight !== undefined));
+    const eligibleWeights = candidates.flatMap((candidate) => candidate.eligibility === 'true' && candidate.weight !== undefined
+        ? [Rational.parse(candidate.weight.decimal)]
+        : []);
+    const total = sumRationals(eligibleWeights);
+    if (pool.selection !== 'enumeration' &&
+        pool.complete &&
+        resolved &&
+        total.compare(Rational.zero) > 0) {
+        for (const candidate of candidates) {
+            const probability = candidate.eligibility === 'true' && candidate.weight !== undefined
+                ? Rational.parse(candidate.weight.decimal).divide(total)
+                : Rational.zero;
+            candidate.conditionalProbability = probability.toNumber();
+            candidate.exactConditionalProbability = probability.toJSON();
+        }
+    }
+    else if (pool.selection !== 'enumeration' && pool.complete && resolved && total.isZero())
+        unresolved.push({
+            code: 'SCOPE_POOL_ZERO_TOTAL',
+            message: `Scope pool ${pool.id} has no positive eligible weight`,
+            path: pool.id,
+        });
+    return {
+        id: pool.id,
+        bindAs: pool.bindAs ?? 'THIS',
+        selection: pool.selection,
+        poolComplete: pool.complete,
+        candidates,
+        eligibleCandidateIds: candidates
+            .filter(({ eligibility }) => eligibility === 'true')
+            .map(({ id }) => id),
+        unresolvedCandidateIds: candidates
+            .filter(({ eligibility, unresolved: items }) => eligibility === 'unresolved' || items.length > 0)
+            .map(({ id }) => id),
+        ...(pool.selection !== 'enumeration' && resolved ? { poolTotal: total.toJSON() } : {}),
+        unresolved,
+    };
+}
+export function evaluateScopePools(scenario, definitions) {
+    return [...(scenario.scopePools ?? [])]
+        .sort((left, right) => compareCodeUnits(left.id, right.id))
+        .map((pool) => evaluatePool(scenario, pool, definitions));
+}

package/dist/hoi4_agent_tools/probability/simulation.js

@@ -1,3 +1,4 @@
+import { withScenarioPathValue } from './scenario-state.js';
 import { evaluateExactCandidates } from './evaluation.js';
 function recordUnresolved(unresolved, issue) {
     if (unresolved.some((existing) => existing.code === issue.code &&
@@ -222,7 +223,7 @@ function continuousSamples(scenario, samples, samplingMethod, random, unresolved
 }
 function sampledScenario(scenario, continuous, random, unresolved) {
     const inputs = scenario.uncertainInputs ?? [];
-    const state = { ...scenario.state };
+    let sampled = { ...scenario, state: { ...scenario.state } };
     for (const input of inputs) {
         let value;
         const plannedUniform = continuous.get(input.path);
@@ -244,9 +245,9 @@ function sampledScenario(scenario, continuous, random, unresolved) {
             });
         }
         else
-            state[input.path] = value;
+            sampled = withScenarioPathValue(sampled, input.path, value);
     }
-    return { ...scenario, state, uncertainInputs: [] };
+    return { ...sampled, uncertainInputs: [] };
 }
 function quantileForConfidence(confidence) {
     return inverseNormal(0.5 + confidence / 2);