hoi4-agent-tools 3.1.0 → 3.3.0

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

package/dist/hoi4_agent_tools/decision/source-inventory.js

@@ -0,0 +1,182 @@
+import { compareCodeUnits } from '../core/canonical.js';
+import { assignments, parseClausewitz, } from '../core/source/index.js';
+export const decisionFieldNames = [
+    'allowed',
+    'visible',
+    'available',
+    'targets',
+    'target_array',
+    'state_trigger',
+    'target_root_trigger',
+    'target_trigger',
+    'cost',
+    'custom_cost_trigger',
+    'custom_cost_text',
+    'complete_effect',
+    'fire_only_once',
+    'days_re_enable',
+    'days_remove',
+    'remove_trigger',
+    'remove_effect',
+    'cancel_trigger',
+    'cancel_if_not_visible',
+    'cancel_effect',
+    'days_mission_timeout',
+    'timeout_effect',
+    'activation',
+    'selectable_mission',
+    'ai_will_do',
+];
+/** Static targeting declarations; scenario evaluation determines whether a target qualifies. */
+export function decisionTargetCatalog(source) {
+    const explicitTargets = source.fields.targets.flatMap((assignment) => {
+        if (assignment.value.type !== 'block')
+            return [];
+        return [
+            ...assignment.value.entries
+                .filter((entry) => entry.type === 'scalar')
+                .map((entry) => entry.value),
+            ...assignments(assignment.value, 'state')
+                .filter((entry) => entry.value.type === 'scalar')
+                .map((entry) => entry.value.value),
+        ];
+    });
+    const targetArrays = source.fields.target_array.flatMap((assignment) => assignment.value.type === 'scalar' ? [assignment.value.value] : []);
+    const stateFilters = source.fields.state_trigger.flatMap((assignment) => assignment.value.type === 'scalar' ? [assignment.value.value] : []);
+    const hasTargetRootTrigger = source.fields.target_root_trigger.length > 0;
+    const hasTargetTrigger = source.fields.target_trigger.length > 0;
+    return {
+        targeted: explicitTargets.length > 0 ||
+            targetArrays.length > 0 ||
+            stateFilters.some((filter) => filter !== 'no') ||
+            hasTargetRootTrigger ||
+            hasTargetTrigger,
+        explicitTargets,
+        targetArrays,
+        stateFilters,
+        hasTargetRootTrigger,
+        hasTargetTrigger,
+    };
+}
+function fields(block) {
+    return Object.fromEntries(decisionFieldNames.map((name) => [name, assignments(block, name)]));
+}
+function sourceDocument(file, documents) {
+    if (file === undefined)
+        return undefined;
+    const existing = documents.get(file.displayPath);
+    if (existing !== undefined)
+        return existing;
+    const parsed = parseClausewitz(file.bytes, file.displayPath);
+    documents.set(file.displayPath, parsed);
+    return parsed;
+}
+function categoryBlock(document, id) {
+    return assignments(document.root, id).find((assignment) => assignment.value.type === 'block')
+        ?.value;
+}
+function sourceOrder(left, right) {
+    return (compareCodeUnits(left.id, right.id) ||
+        right.loadOrder - left.loadOrder ||
+        compareCodeUnits(left.path, right.path));
+}
+/** Reuses the shared index's active/overridden selection and source inventory. */
+export function decisionSourceInventory(snapshot) {
+    const files = new Map(snapshot.files.map((file) => [file.displayPath, file]));
+    const documents = new Map();
+    const unresolvedDefinitions = [];
+    const categories = [];
+    const decisions = [];
+    const overrides = [
+        ...snapshot.index.findAll('decision_category'),
+        ...snapshot.index.findAll('decision'),
+    ]
+        .filter(({ overridden }) => overridden)
+        .sort(sourceOrder)
+        .map(({ kind, id, path, rootKind, loadOrder, location, sourceShadowed }) => ({
+        kind,
+        id,
+        path,
+        rootKind,
+        loadOrder,
+        ...(location === undefined ? {} : { location }),
+        sourceShadowed,
+    }));
+    for (const symbol of snapshot.index
+        .findAll('decision_category')
+        .filter(({ overridden }) => !overridden)
+        .sort(sourceOrder)) {
+        const file = files.get(symbol.path);
+        const document = sourceDocument(file, documents);
+        const block = document === undefined ? undefined : categoryBlock(document, symbol.id);
+        if (file === undefined || document === undefined || block === undefined) {
+            unresolvedDefinitions.push({
+                kind: 'decision_category',
+                id: symbol.id,
+                path: symbol.path,
+                reason: 'Active category index entry could not be matched to a source block',
+            });
+            continue;
+        }
+        categories.push({
+            id: symbol.id,
+            path: symbol.path,
+            rootKind: file.rootKind,
+            loadOrder: file.loadOrder,
+            sourceHash: file.sha256,
+            ...(symbol.location === undefined ? {} : { location: symbol.location }),
+            document,
+            block,
+            fields: fields(block),
+        });
+    }
+    for (const symbol of snapshot.index
+        .findAll('decision')
+        .filter(({ overridden }) => !overridden)
+        .sort(sourceOrder)) {
+        const category = typeof symbol.metadata.category === 'string' ? symbol.metadata.category : undefined;
+        const file = files.get(symbol.path);
+        const document = sourceDocument(file, documents);
+        const categoryNode = document === undefined || category === undefined
+            ? undefined
+            : categoryBlock(document, category);
+        const decisionNode = categoryNode === undefined
+            ? undefined
+            : assignments(categoryNode, symbol.id).find((assignment) => assignment.value.type === 'block')?.value;
+        if (file === undefined ||
+            document === undefined ||
+            category === undefined ||
+            decisionNode?.type !== 'block') {
+            unresolvedDefinitions.push({
+                kind: 'decision',
+                id: symbol.id,
+                path: symbol.path,
+                reason: 'Active decision index entry could not be matched to a source block',
+            });
+            continue;
+        }
+        const decisionFields = fields(decisionNode);
+        decisions.push({
+            id: symbol.id,
+            category,
+            kind: decisionFields.days_mission_timeout.length > 0 ? 'mission' : 'decision',
+            path: symbol.path,
+            rootKind: file.rootKind,
+            loadOrder: file.loadOrder,
+            sourceHash: file.sha256,
+            ...(symbol.location === undefined ? {} : { location: symbol.location }),
+            document,
+            block: decisionNode,
+            fields: decisionFields,
+        });
+    }
+    return {
+        sourceRevision: snapshot.revision,
+        complete: snapshot.complete && unresolvedDefinitions.length === 0,
+        skippedSourceCount: snapshot.skippedSourceCount,
+        decisions,
+        categories,
+        overrides,
+        unresolvedDefinitions,
+    };
+}

package/dist/hoi4_agent_tools/gui/scenario-conditions.js

@@ -1,6 +1,7 @@
 import { ClausewitzEvaluationDefinitions } from '../core/clausewitz-evaluation.js';
 import { hasBlockingDiagnostics } from '../core/diagnostics.js';
 import { evaluateTriggerBlock } from '../core/condition-evaluator.js';
+import { scenarioFromGui } from '../core/scenario-model.js';
 import { resolveScopeContext, rootScopeContext } from '../core/scenario-state.js';
 import { assignments, firstScalar, parseClausewitz } from '../core/source/index.js';
 /** Keep declared scoped scalars out of exploratory value generation. */
@@ -30,29 +31,7 @@ function parsedCondition(expression) {
     };
 }
 export function guiConditionScenario(base, values = base.values) {
-    const state = { ...base.stateValues, ...base.variables, ...values };
-    for (const [key, value] of Object.entries(base.flags))
-        state[`flag.${key}`] = value;
-    const scopes = structuredClone(base.scopes ?? {});
-    for (const [key, value] of Object.entries(state)) {
-        const match = /^(ROOT|THIS|FROM(?:\.FROM)*|PREV)\.(.+)$/u.exec(key);
-        if (match === null)
-            continue;
-        if (match[1] === 'ROOT' || match[1] === 'THIS')
-            state[match[2]] ??= value;
-        else {
-            const scope = (scopes[match[1]] ??= { id: match[1], state: {} });
-            scope.state[match[2]] ??= value;
-        }
-    }
-    const actor = base.country?.tag ?? base.country?.countryTag ?? base.country?.GetTag;
-    return {
-        id: base.id,
-        state,
-        scopes,
-        closedFlags: false,
-        ...(typeof actor === 'string' ? { actor } : {}),
-    };
+    return scenarioFromGui(base, values);
 }
 export function evaluateGuiCondition(expression, scenario, subject, definitions = new ClausewitzEvaluationDefinitions(), scope = 'ROOT') {
     const context = resolveScopeContext(scenario, scope, rootScopeContext(scenario));

package/dist/hoi4_agent_tools/impact/scenario-suites.js

@@ -0,0 +1,74 @@
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { compareCodeUnits, sha256Bytes } from '../core/canonical.js';
+import { ServiceError } from '../core/result.js';
+import { canonicalPath, isWithin } from '../core/workspace.js';
+import { impactScenarioSuiteReferenceSchema } from '../schemas/analysis.js';
+function selectorKey(selector) {
+    return `${selector.kind}:${selector.id}`;
+}
+/** Read bounded workspace-owned suite references without executing any case or assertion. */
+export async function inspectImpactScenarioSuites(workspace, paths, graph, selected, signal) {
+    const result = {
+        matches: [],
+        sourceHashes: {},
+        unresolved: [],
+        scannedSuites: 0,
+        scannedCases: 0,
+        omittedMatches: 0,
+        complete: true,
+    };
+    const relevantSymbols = new Set([
+        ...selected.map(selectorKey),
+        ...graph.directConsumers.map(({ source }) => selectorKey(source)),
+        ...graph.transitiveConsumers.map(({ source }) => selectorKey(source)),
+    ]);
+    const relevantFiles = new Set(graph.affectedFiles);
+    for (const relativePath of [...new Set(paths)].sort(compareCodeUnits)) {
+        signal?.throwIfAborted();
+        const candidate = await canonicalPath(path.join(workspace.modRoot, relativePath), signal);
+        if (!isWithin(workspace.modRoot, candidate))
+            throw new ServiceError('IMPACT_SUITE_OUTSIDE_WORKSPACE', 'Scenario suite resolves outside the authorized mod root', {
+                relativePath,
+            });
+        try {
+            const details = await stat(candidate);
+            if (!details.isFile() || details.size > 4 * 1024 * 1024)
+                throw new RangeError('Suite must be a JSON file no larger than 4 MiB');
+            const bytes = await readFile(candidate);
+            if (bytes.length > 4 * 1024 * 1024)
+                throw new RangeError('Suite file exceeds 4 MiB');
+            const suite = impactScenarioSuiteReferenceSchema.parse(JSON.parse(bytes.toString('utf8')));
+            result.sourceHashes[`suite:${relativePath}`] = sha256Bytes(bytes);
+            result.scannedSuites += 1;
+            result.scannedCases += suite.cases.length;
+            for (const item of suite.cases) {
+                const via = [
+                    ...item.sourceSelectors
+                        .map(selectorKey)
+                        .filter((key) => relevantSymbols.has(key))
+                        .map((key) => `symbol:${key}`),
+                    ...item.sourceFiles
+                        .filter((file) => relevantFiles.has(file))
+                        .map((file) => `file:${file}`),
+                ].sort(compareCodeUnits);
+                if (via.length === 0)
+                    continue;
+                if (result.matches.length < 10_000)
+                    result.matches.push({ suitePath: relativePath, suiteId: suite.id, caseId: item.id, via });
+                else
+                    result.omittedMatches += 1;
+            }
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            result.unresolved.push({
+                path: relativePath,
+                reason: error instanceof Error ? error.message : 'Scenario suite could not be read or parsed',
+            });
+        }
+    }
+    result.complete = result.unresolved.length === 0 && result.omittedMatches === 0;
+    return result;
+}

package/dist/hoi4_agent_tools/impact/service.js

@@ -0,0 +1,127 @@
+import { analysisSourceEvidence } from '../core/analysis-evidence.js';
+import { publicArtifactLink } from '../core/artifacts.js';
+import { canonicalJson, hashCanonical } from '../core/canonical.js';
+import { compareImpactGraphs } from '../core/impact-comparison.js';
+import { inspectImpactGraph } from '../core/impact-graph.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 { inspectImpactScenarioSuites } from './scenario-suites.js';
+/** Authorized, read-only impact operation shared by ordinary calls and persistent jobs. */
+export class ImpactAnalyzer {
+    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('IMPACT_SOURCE_STALE', 'Impact source revision changed since selection', {
+                expectedRevision: input.expectedRevision,
+                observedRevision: before.revision,
+            });
+        const overlay = input.proposedSources === undefined
+            ? undefined
+            : buildProposedSourceOverlay(before, workspace, input.proposedSources);
+        const availablePaths = new Set([
+            ...before.files.map(({ displayPath }) => displayPath),
+            ...(overlay?.snapshot.files.map(({ displayPath }) => displayPath) ?? []),
+            ...(overlay?.changes.map(({ path }) => path) ?? []),
+        ]);
+        for (const file of input.changedFiles)
+            if (!availablePaths.has(file))
+                throw new ServiceError('IMPACT_SOURCE_UNKNOWN', 'Changed file is not in the authorized source inventory or proposed overlay', { file });
+        const query = {
+            symbols: input.symbols,
+            changedFiles: input.changedFiles.length > 0
+                ? input.changedFiles
+                : (overlay?.changes.map(({ path }) => path) ?? []),
+            ...(input.maxNodes === undefined ? {} : { maxNodes: input.maxNodes }),
+            ...(input.maxEdges === undefined ? {} : { maxEdges: input.maxEdges }),
+            ...(input.maxDepth === undefined ? {} : { maxDepth: input.maxDepth }),
+        };
+        const comparison = overlay === undefined ? undefined : compareImpactGraphs(before, overlay.snapshot, query);
+        const graph = comparison?.after ?? inspectImpactGraph(before, query);
+        const analysis = comparison ?? graph;
+        const suiteGraph = comparison === undefined
+            ? graph
+            : {
+                ...graph,
+                directConsumers: [...comparison.before.directConsumers, ...graph.directConsumers],
+                transitiveConsumers: [
+                    ...comparison.before.transitiveConsumers,
+                    ...graph.transitiveConsumers,
+                ],
+                affectedFiles: [
+                    ...new Set([...comparison.before.affectedFiles, ...graph.affectedFiles]),
+                ],
+            };
+        const scenarioSuites = await inspectImpactScenarioSuites(workspace, input.scenarioSuites, suiteGraph, input.symbols, input.signal);
+        const complete = analysis.complete && scenarioSuites.complete;
+        const report = {
+            schemaVersion: 'impact-analysis.v1',
+            mode: overlay === undefined ? 'inspect' : 'compare',
+            query,
+            ...(overlay === undefined ? {} : { proposedChanges: overlay.changes }),
+            analysis,
+            scenarioSuites,
+        };
+        const reportHash = hashCanonical(report);
+        const artifactName = `impact-${reportHash.slice(0, 24)}.json`;
+        const provenanceSources = analysisSourceEvidence(before, overlay?.snapshot, scenarioSuites.sourceHashes);
+        const artifact = await this.engine.artifacts.putChunked(workspace, artifactName, 'application/json', `${canonicalJson(report)}\n`, {
+            kind: 'impact-analysis',
+            toolVersion: PACKAGE_VERSION,
+            schemaVersion: 'impact-analysis.v1',
+            sourceHashes: provenanceSources.sourceHashes,
+            metadata: {
+                beforeRevision: before.revision,
+                ...(overlay === undefined ? {} : { afterRevision: overlay.snapshot.revision }),
+                sourceInventory: provenanceSources.inventory,
+            },
+        }, 'Revision-pinned cross-system impact graph and source evidence', input.signal);
+        const result = emptyServiceResult(input.workspaceId, {
+            mode: overlay === undefined ? 'inspect' : 'compare',
+            sourceRevision: before.revision,
+            ...(overlay === undefined ? {} : { proposedRevision: overlay.snapshot.revision }),
+            reportHash,
+            complete,
+            definitions: graph.definitions.length,
+            directConsumers: graph.directConsumers.length,
+            transitiveConsumers: graph.transitiveConsumers.length,
+            affectedFiles: graph.affectedFiles.length,
+            cycles: graph.cycles.length,
+            scenarioSuites: scenarioSuites.scannedSuites,
+            affectedCases: scenarioSuites.matches.length,
+            unresolved: graph.unresolved.length + graph.dynamicReferences.length + scenarioSuites.unresolved.length,
+            ...(comparison === undefined
+                ? {}
+                : {
+                    addedConsumers: comparison.addedConsumers.length,
+                    removedConsumers: comparison.removedConsumers.length,
+                }),
+        });
+        result.code = complete ? 'IMPACT_ANALYZED' : 'IMPACT_ANALYZED_PARTIAL';
+        result.artifacts = [publicArtifactLink(artifact)];
+        result.proposedFiles = overlay?.changes.map(({ path }) => path).slice(0, 64) ?? [];
+        result.changedFiles = graph.affectedFiles.slice(0, 64);
+        setInlineFilesScanned(result, before.files.map(({ displayPath }) => displayPath));
+        result.validation = {
+            passed: complete,
+            checks: [
+                {
+                    id: 'impact-coverage',
+                    passed: complete,
+                    message: complete
+                        ? 'Selected impact graph is complete under the declared bounds'
+                        : 'Impact graph has source, dynamic-reference, or traversal boundaries; inspect the linked report',
+                },
+            ],
+        };
+        return result;
+    }
+}

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

@@ -5,6 +5,7 @@ import { registerFocusTools } from '../tools/focus.js';
 import { registerGuiTools } from '../tools/gui.js';
 import { registerMapTools } from '../tools/map.js';
 import { registerEventTools } from '../tools/event.js';
+import { registerAnalysisTools } from '../tools/analysis.js';
 import { registerTechnologyTools } from '../tools/technology.js';
 import { registerProbabilityTools } from '../tools/probability.js';
 import { registerJobTools } from '../tools/job.js';
@@ -53,6 +54,7 @@ export function createMcpServer(engine, context = {}) {
     registerGuiTools(server, engine, serverContext);
     registerMapTools(server, engine, serverContext);
     registerEventTools(server);
+    registerAnalysisTools(server);
     registerTechnologyTools(server);
     registerProbabilityTools(server);
     registerJobTools(server, engine, serverContext);

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

@@ -1,2 +1,2 @@
 /** Shared agent-facing guidance for both MCP protocol generations. */
-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. Concurrent calls queue automatically and emit periodic progress when the client requests it. Long operations support negotiated MCP tasks; native background rewrites require a stable requestKey. 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 cross-system source review with hoi4.impact_inspect and decision or mission scenarios with hoi4.decision_inspect. Test declared mechanic steps with hoi4.mechanic_test, package connections with hoi4.package_check, and named suites with hoi4.scenario_test. These analysis 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. Concurrent calls queue automatically and emit periodic progress when the client requests it. Long operations support negotiated MCP tasks; native background rewrites require a stable requestKey. Large evidence is linked as resources.';

package/dist/hoi4_agent_tools/mcp/server/request-lifecycle.js

@@ -5,6 +5,11 @@ import { withTaskRequestSignal } from './task-request-context.js';
 // remain responsive while every domain-execution slot is occupied.
 const controlTools = new Set(['hoi4.job_inspect', 'hoi4.job_cancel']);
 const backgroundTools = new Set([
+    'hoi4.impact_inspect',
+    'hoi4.decision_inspect',
+    'hoi4.mechanic_test',
+    'hoi4.package_check',
+    'hoi4.scenario_test',
     'hoi4.event_inspect',
     'hoi4.event_render',
     'hoi4.event_compare',

package/dist/hoi4_agent_tools/mcp/server/task-tool-catalog.js

@@ -1,3 +1,4 @@
+import { analysisTaskTools } from '../tools/analysis.js';
 import { eventTaskTools } from '../tools/event.js';
 import { focusTaskTools } from '../tools/focus.js';
 import { guiTaskTools } from '../tools/gui.js';
@@ -9,6 +10,7 @@ export const taskToolCatalog = [
     ...guiTaskTools,
     ...mapTaskTools,
     ...eventTaskTools,
+    ...analysisTaskTools,
     ...technologyTaskTools,
     ...probabilityTaskTools,
 ];