hoi4-agent-tools 4.1.0 → 4.2.0

package/dist/hoi4_agent_tools/event/service.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { inspectHelperExpansion } from '../core/helper-expansion.js';
 import { eventHelperInventory } from './helper-expansion.js';
 import { clearSemanticDependencies } from '../core/semantic-dependencies.js';
-import { canonicalJson, compareCodeUnits, hashCanonical, sha256Bytes } from '../core/canonical.js';
+import { canonicalJson, canonicalJsonByteLength, compareCodeUnits, hashCanonical, sha256Bytes, } from '../core/canonical.js';
 import { boundedSourceHashEvidence, publicArtifactLink, } from '../core/artifacts.js';
 import { ServiceError } from '../core/result.js';
 import { RenderBudget } from '../core/render-budget.js';
@@ -10,7 +10,8 @@ import { SOURCE_MAX_BYTES } from '../core/source/index.js';
 import { isPortablePathSegment } from '../core/workspace.js';
 import { PACKAGE_VERSION } from '../version.js';
 import { buildEventGraph, buildEventGraphAsync } from './graph.js';
-import { EVENT_FRAGMENT_CACHE_MAX_ENTRIES, EVENT_FRAGMENT_CACHE_MAX_SOURCE_BYTES, EVENT_PROPOSED_SOURCE_MAX_BYTES, EVENT_PROPOSED_SOURCE_MAX_FILES, } from './limits.js';
+import { summarizeEventImpact, summarizeEventIssues, summarizeEventPath, summarizeEventRoots, summarizeEventTrace, } from './summary.js';
+import { EVENT_FRAGMENT_CACHE_MAX_ENTRIES, EVENT_FRAGMENT_CACHE_MAX_SOURCE_BYTES, EVENT_GRAPH_SNAPSHOT_MAX_BYTES, EVENT_PROPOSED_SOURCE_MAX_BYTES, EVENT_PROPOSED_SOURCE_MAX_FILES, } from './limits.js';
 import { analyzeEventImpact, discoverEventRoots, explainEventPath, inspectEventStateFlow, lintEventGraph, traceSelectedEvents, } from './queries.js';
 import { compareEventGraphs, eventGraphHash } from './compare.js';
 import { selectEventComparison } from './comparison-selection.js';
@@ -210,9 +211,23 @@ async function scanEventSources(engine, workspaceId, workspace, focused = false,
         complete: index.complete,
         skippedSourceCount: index.skippedSourceCount,
         skippedSources: index.skippedSources,
-        diagnostics: index.diagnostics,
+        diagnostics: diagnosticsWithinScannedKinds(index),
     };
 }
+/**
+ * Event analysis indexes only event-relevant folders, so it holds no sprite, interface or
+ * scripted-trigger definitions. A reference to a kind with no definition in this file set says
+ * nothing about the workspace and is left to the full index, which scans those folders.
+ */
+function diagnosticsWithinScannedKinds(index) {
+    const indexedKinds = new Set(index.symbols.map(({ kind }) => kind));
+    return index.diagnostics.filter(({ code, details }) => {
+        if (code !== 'INDEX_UNRESOLVED_REFERENCE' && code !== 'INDEX_UNRESOLVED_REFERENCE_PARTIAL')
+            return true;
+        const toKind = details?.toKind;
+        return typeof toKind !== 'string' || indexedKinds.has(toKind);
+    });
+}
 function rememberGraph(state, workspaceId, graph) {
     const history = state.history.get(workspaceId) ?? new Map();
     history.delete(graph.revision);
@@ -808,17 +823,21 @@ export class EventChainViewer {
             refresh: input.refresh ?? input.mode === 'scan',
         };
         let report;
+        let summary;
         switch (input.mode) {
             case 'scan':
                 report = eventScanReport(graph);
+                summary = summarizeEventIssues(graph.issues);
                 break;
             case 'roots':
                 {
                     const unresolved = boundedUnresolved(graph);
+                    const roots = discoverEventRoots(graph, input.signal);
+                    summary = summarizeEventRoots(roots);
                     report = {
                         graphRevision: graph.revision,
                         sourceHashes: graph.sourceHashes,
-                        roots: discoverEventRoots(graph, input.signal),
+                        roots,
                         unresolved: unresolved.values,
                         ...(unresolved.inventory === undefined
                             ? {}
@@ -838,6 +857,10 @@ export class EventChainViewer {
                         expandHelpers: input.expandHelpers ?? false,
                     }, input.signal);
                     const unresolved = boundedUnresolved(graph, new Set(trace.nodes.map(({ id }) => id)));
+                    summary = {
+                        trace: summarizeEventTrace(trace),
+                        ...summarizeEventIssues(lintEventGraph(graph, input.selector, input.signal)),
+                    };
                     report = {
                         graphRevision: graph.revision,
                         sourceHashes: graph.sourceHashes,
@@ -852,16 +875,22 @@ export class EventChainViewer {
             case 'explain_path':
                 if (input.from === undefined || input.to === undefined)
                     throw new ServiceError('EVENT_PATH_SELECTORS_REQUIRED', 'Path explanation requires from and to selectors');
-                report = {
-                    graphRevision: graph.revision,
-                    sourceHashes: graph.sourceHashes,
-                    explanation: explainEventPath(graph, input.from, input.to, { maxDepth, maxNodes, expandHelpers: input.expandHelpers ?? true }, input.signal),
-                };
+                {
+                    const explanation = explainEventPath(graph, input.from, input.to, { maxDepth, maxNodes, expandHelpers: input.expandHelpers ?? true }, input.signal);
+                    summary = summarizeEventPath(explanation);
+                    report = {
+                        graphRevision: graph.revision,
+                        sourceHashes: graph.sourceHashes,
+                        explanation,
+                    };
+                }
                 break;
             case 'state_flow':
                 {
                     const unresolved = boundedUnresolved(graph);
-                    const issues = boundedEvidence(lintEventGraph(graph, input.selector, input.signal).filter(({ code }) => /(?:STATE|FLAG|VARIABLE|ARRAY|TARGET|SCOPE)/u.test(code)));
+                    const stateIssues = lintEventGraph(graph, input.selector, input.signal).filter(({ code }) => /(?:STATE|FLAG|VARIABLE|ARRAY|TARGET|SCOPE|WRITER)/u.test(code));
+                    summary = summarizeEventIssues(stateIssues);
+                    const issues = boundedEvidence(stateIssues);
                     report = {
                         graphRevision: graph.revision,
                         sourceHashes: graph.sourceHashes,
@@ -877,7 +906,9 @@ export class EventChainViewer {
                 break;
             case 'lint':
                 {
-                    const issues = boundedEvidence(lintEventGraph(graph, input.selector, input.signal));
+                    const selectedIssues = lintEventGraph(graph, input.selector, input.signal);
+                    summary = summarizeEventIssues(selectedIssues);
+                    const issues = boundedEvidence(selectedIssues);
                     const unresolved = boundedUnresolved(graph);
                     report = {
                         graphRevision: graph.revision,
@@ -897,10 +928,12 @@ export class EventChainViewer {
                     throw new ServiceError('EVENT_IMPACT_SUBJECT_REQUIRED', 'Impact analysis requires a subject');
                 {
                     const unresolved = boundedUnresolved(graph);
+                    const impact = analyzeEventImpact(graph, input.impactSubject, input.signal);
+                    summary = summarizeEventImpact(impact);
                     report = {
                         graphRevision: graph.revision,
                         sourceHashes: graph.sourceHashes,
-                        impact: analyzeEventImpact(graph, input.impactSubject, input.signal),
+                        impact,
                         unresolved: unresolved.values,
                         ...(unresolved.inventory === undefined
                             ? {}
@@ -912,6 +945,13 @@ export class EventChainViewer {
         const graphHash = cachedEventGraphHash(graph, input.signal);
         const name = `${safeSlug(`event-${input.mode}`)}-${graph.revision.slice(0, 12)}.json`;
         const graphSnapshotName = `event-graph-${graph.revision}.json`;
+        // A large workspace graph cannot be held as one JSON string or artifact. Measure it first and
+        // retain it only when it fits; comparisons then use the in-memory revision history.
+        const graphSnapshot = input.mode === 'scan' ? { schemaVersion: 'event-graph-snapshot.v1', graph } : undefined;
+        const graphSnapshotBytes = graphSnapshot === undefined
+            ? undefined
+            : canonicalJsonByteLength(graphSnapshot, EVENT_GRAPH_SNAPSHOT_MAX_BYTES);
+        const snapshotOmitted = graphSnapshot !== undefined && graphSnapshotBytes === undefined;
         const projectedScan = input.mode === 'scan' &&
             typeof report === 'object' &&
             report !== null &&
@@ -949,10 +989,13 @@ export class EventChainViewer {
                 : {}),
             resources: [
                 { name, mimeType: 'application/json' },
-                ...(input.mode === 'scan'
+                ...(input.mode === 'scan' && !snapshotOmitted
                     ? [{ name: graphSnapshotName, mimeType: 'application/json' }]
                     : []),
             ],
+            ...(snapshotOmitted
+                ? { graphSnapshotOmitted: { maximumBytes: EVENT_GRAPH_SNAPSHOT_MAX_BYTES } }
+                : {}),
             report,
         })}\n`;
         const workspace = this.engine.resolver.get(input.workspaceId, input.principal);
@@ -960,8 +1003,8 @@ export class EventChainViewer {
             mode: input.mode,
             ...(input.selector === undefined ? {} : { selector: input.selector }),
         }, input.signal), `Authoritative Event Chain Viewer ${input.mode.replaceAll('_', ' ')} report`, input.signal);
-        const graphArtifact = input.mode === 'scan'
-            ? await this.engine.artifacts.putChunked(workspace, graphSnapshotName, 'application/json', `${canonicalJson({ schemaVersion: 'event-graph-snapshot.v1', graph })}\n`, eventProvenance(graph, 'event-graph-snapshot', { revision: graph.revision, graphHash }, input.signal), 'Revision-addressed Event Chain Viewer graph snapshot', input.signal)
+        const graphArtifact = graphSnapshot !== undefined && !snapshotOmitted
+            ? await this.engine.artifacts.putChunked(workspace, graphSnapshotName, 'application/json', `${canonicalJson(graphSnapshot)}\n`, eventProvenance(graph, 'event-graph-snapshot', { revision: graph.revision, graphHash }, input.signal), 'Revision-addressed Event Chain Viewer graph snapshot', input.signal)
             : undefined;
         return {
             graph,
@@ -970,6 +1013,8 @@ export class EventChainViewer {
             report,
             reportJson,
             artifacts: [artifact, ...(graphArtifact === undefined ? [] : [graphArtifact])],
+            ...(snapshotOmitted ? { graphSnapshotOmitted: true } : {}),
+            summary,
         };
     }
     async renderAndStore(input) {
@@ -1001,25 +1046,38 @@ export class EventChainViewer {
             graph.nodes.length > render.selectedNodeIds.length
             ? coherentBranchPartitions(graph, branchNodeLimit, 64, input.signal)
             : { groups: [], omittedNodeIds: [] };
-        const branchGroups = partitions.groups;
-        for (const [branchIndex, nodeIds] of branchGroups.entries()) {
+        // Branch images share the request's raster budget with the overview. When it is spent, the
+        // remaining branches are listed as omitted instead of failing the whole render.
+        let budgetOmittedBranches = 0;
+        for (const [branchIndex, nodeIds] of partitions.groups.entries()) {
             input.signal?.throwIfAborted();
-            branches.push(await renderEventGraph(graph, {
-                view: 'neighborhood',
-                selector: {
-                    kind: 'manifest',
-                    manifest: { id: `overview-branch-${branchIndex + 1}`, nodeIds },
-                },
-                direction: 'both',
-                maxDepth: 0,
-                maxNodes: branchNodeLimit,
-                expandHelpers: input.expandHelpers ?? false,
-                includeHtml: false,
-                compactLayout: true,
-                budget,
-                ...(input.signal === undefined ? {} : { signal: input.signal }),
-            }));
+            let branch;
+            try {
+                branch = await renderEventGraph(graph, {
+                    view: 'neighborhood',
+                    selector: {
+                        kind: 'manifest',
+                        manifest: { id: `overview-branch-${branchIndex + 1}`, nodeIds },
+                    },
+                    direction: 'both',
+                    maxDepth: 0,
+                    maxNodes: branchNodeLimit,
+                    expandHelpers: input.expandHelpers ?? false,
+                    includeHtml: false,
+                    compactLayout: true,
+                    budget,
+                    ...(input.signal === undefined ? {} : { signal: input.signal }),
+                });
+            }
+            catch (error) {
+                if (!(error instanceof ServiceError) || error.code !== 'RENDER_AGGREGATE_BLOCKED')
+                    throw error;
+                budgetOmittedBranches = partitions.groups.length - branchIndex;
+                break;
+            }
+            branches.push(branch);
         }
+        const branchGroups = partitions.groups.slice(0, branches.length);
         const prefix = safeSlug(`event-${input.view}-${graph.revision.slice(0, 12)}`);
         const manifestName = `${prefix}-manifest.json`;
         const resourceNames = {
@@ -1165,7 +1223,8 @@ export class EventChainViewer {
                 omittedNodeCount: partitions.omittedNodeIds.length,
                 omittedNodeIds: partitions.omittedNodeIds,
                 omittedNodeHash: hashCanonical(partitions.omittedNodeIds),
-                truncated: partitions.omittedNodeIds.length > 0,
+                budgetOmittedBranches,
+                truncated: partitions.omittedNodeIds.length > 0 || budgetOmittedBranches > 0,
             },
         })}\n`;
         const manifestArtifact = await this.engine.artifacts.putChunked(workspace, manifestName, 'application/json', manifestJson, provenance, `Event-chain ${input.view} render and bounded branch manifest`, input.signal);
@@ -1175,6 +1234,7 @@ export class EventChainViewer {
             graphHash: cachedEventGraphHash(graph, input.signal),
             render,
             branches,
+            budgetOmittedBranches,
             manifestJson,
             artifacts,
         };

package/dist/hoi4_agent_tools/event/source-analysis.js

@@ -86,6 +86,21 @@ const STATE_RULES = {
     multiply_variable: { kind: 'variable', access: 'read_write' },
     divide_variable: { kind: 'variable', access: 'read_write' },
     clamp_variable: { kind: 'variable', access: 'read_write' },
+    round_variable: { kind: 'variable', access: 'read_write' },
+    modulo_variable: { kind: 'variable', access: 'read_write' },
+    randomize_variable: { kind: 'variable', access: 'read_write' },
+    set_variable_to_random: { kind: 'variable', access: 'write' },
+    // `check_variable` and `has_variable` read a temporary variable of the same name as well.
+    set_temp_variable: { kind: 'variable', access: 'write', temporary: true },
+    set_temp_variable_to_random: { kind: 'variable', access: 'write', temporary: true },
+    add_to_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
+    subtract_from_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
+    multiply_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
+    divide_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
+    clamp_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
+    round_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
+    modulo_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
+    randomize_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
     check_variable: { kind: 'variable', access: 'read' },
     has_variable: { kind: 'variable', access: 'read' },
     is_variable_equal: { kind: 'variable', access: 'read' },
@@ -101,6 +116,16 @@ const STATE_RULES = {
     remove_from_array: { kind: 'array', access: 'read_write', nameField: 'array' },
     is_in_array: { kind: 'array', access: 'read', nameField: 'array' },
     clear_array: { kind: 'array', access: 'clear' },
+    resize_array: { kind: 'array', access: 'write', nameField: 'array' },
+    add_to_temp_array: { kind: 'array', access: 'write', nameField: 'array', temporary: true },
+    remove_from_temp_array: {
+        kind: 'array',
+        access: 'read_write',
+        nameField: 'array',
+        temporary: true,
+    },
+    resize_temp_array: { kind: 'array', access: 'write', nameField: 'array', temporary: true },
+    clear_temp_array: { kind: 'array', access: 'clear', temporary: true },
     save_event_target_as: { kind: 'event_target', access: 'replace' },
     has_event_target: { kind: 'event_target', access: 'read' },
     save_global_event_target_as: { kind: 'global_event_target', access: 'replace' },
@@ -153,7 +178,59 @@ const NON_EXECUTING_BLOCKS = new Set([
     'mean_time_to_happen',
     'effect_tooltip',
     'custom_effect_tooltip',
+    // Condition blocks of decisions, missions, ideas, focuses, raids and characters.
+    'visible',
+    'available',
+    'allowed',
+    'allowed_civil_war',
+    'allowed_to_remove',
+    'cancel_trigger',
+    'remove_trigger',
+    'target_trigger',
+    'target_root_trigger',
+    'activation',
+    'ai_will_do',
+    'bypass',
+    'allow_branch',
+    'hidden_trigger',
+    'custom_trigger_tooltip',
+    'and',
+    'or',
+    'not',
+    'nor',
+    'nand',
 ]);
+/** Native effects whose body holds further effects rather than named arguments. */
+const NATIVE_EFFECT_CONTAINERS = new Set([
+    'create_dynamic_country',
+    'custom_override_tooltip',
+    'effect_tooltip',
+    'for_each_loop',
+    'for_each_scope_loop',
+    'for_loop_effect',
+    'hidden_effect',
+    'if',
+    'random',
+    'random_list',
+    'random_scope_in_array',
+    'while_loop_effect',
+]);
+/** Inside a native effect such as `add_building_construction`, `key = yes` is an argument. */
+function isNativeArgumentBlock(normalizedKey) {
+    return (nativeEffectKeys.has(normalizedKey) &&
+        !NATIVE_EFFECT_CONTAINERS.has(normalizedKey) &&
+        !CONTROL_BLOCKS.has(normalizedKey) &&
+        SCOPE_BLOCKS[normalizedKey] === undefined &&
+        !/^(?:every|random|global_every)_/u.test(normalizedKey));
+}
+/** Effect blocks of definition files by naming convention: `on_add`, `complete_effect`, `effects`. */
+function isConventionalEffectBlock(normalizedKey) {
+    return /^on_[a-z0-9_]+$|(?:^|_)effects?$/u.test(normalizedKey);
+}
+/** Trigger iterators such as `any_owned_state` hold conditions, never effects. */
+function isTriggerIterator(normalizedKey) {
+    return /^(?:any|all)_/u.test(normalizedKey);
+}
 const TOOLTIP_ONLY_BLOCKS = new Set(['effect_tooltip', 'custom_effect_tooltip']);
 const COUNTRY_ON_ACTIONS = new Set([
     'on_startup',
@@ -836,6 +913,7 @@ class FragmentAnalyzer {
             helperStack: [],
             semanticPath: ['other'],
             effectContext: true,
+            inferMissingHelpers: false,
         });
         if (this.edges.length + this.stateAccesses.length > before) {
             this.addNode({
@@ -913,6 +991,8 @@ class FragmentAnalyzer {
                 return;
             }
             if (this.context.inventoryComplete !== false &&
+                context.nativeArguments !== true &&
+                context.inferMissingHelpers !== false &&
                 missingHelperCandidate(key, entry.value, effectContext)) {
                 const target = this.unresolvedNode('missing_helper', key, entry, context.ownerId, semanticPath);
                 this.addEdge(context.ownerId, target, 'scripted_effect_call', entry, context.conditions, {
@@ -1039,7 +1119,13 @@ class FragmentAnalyzer {
                 conditions,
                 sourceScope: scope,
                 phase,
-                effectContext: NON_EXECUTING_BLOCKS.has(normalizedKey) ? false : effectContext,
+                effectContext: NON_EXECUTING_BLOCKS.has(normalizedKey) || isTriggerIterator(normalizedKey)
+                    ? false
+                    : effectContext,
+                nativeArguments: context.nativeArguments === true || isNativeArgumentBlock(normalizedKey),
+                ...(context.inferMissingHelpers === false && isConventionalEffectBlock(normalizedKey)
+                    ? { inferMissingHelpers: true }
+                    : {}),
                 suppressSemantics: context.suppressSemantics === true || TOOLTIP_ONLY_BLOCKS.has(normalizedKey),
                 semanticPath,
                 ...(scopeExpression === undefined ? {} : { scopeExpression }),
@@ -1296,7 +1382,8 @@ class FragmentAnalyzer {
         return id;
     }
     recordState(assignment, context, semanticPath) {
-        const keyedTarget = /^(event_target|global_event_target|scope):([A-Za-z0-9_.-]+)$/u.exec(assignment.key.value);
+        // `event_target:founder.districts` names the target `founder`; the rest is a value in its scope.
+        const keyedTarget = /^(event_target|global_event_target|scope):([A-Za-z0-9_-]+)(?:\.[A-Za-z0-9_.-]+)?$/u.exec(assignment.key.value);
         if (keyedTarget !== null) {
             this.addState(context, keyedTarget[1] === 'global_event_target'
                 ? 'global_event_target'
@@ -1307,7 +1394,7 @@ class FragmentAnalyzer {
         const rule = STATE_RULES[assignment.key.value];
         if (rule === undefined) {
             const raw = valueText(this.document, assignment.value);
-            for (const match of raw.matchAll(/\b(event_target|global_event_target):([A-Za-z0-9_.-]+)/gu)) {
+            for (const match of raw.matchAll(/\b(event_target|global_event_target):([A-Za-z0-9_-]+)/gu)) {
                 this.addState(context, match[1] === 'global_event_target' ? 'global_event_target' : 'event_target', match[2], 'read', assignment, semanticPath, false);
             }
             return;
@@ -1336,7 +1423,10 @@ class FragmentAnalyzer {
         else if (access === 'write') {
             this.#seenStateWriters.add(writerKey);
         }
-        this.addState(context, kind, name, access, assignment, semanticPath, isDynamic(name), rule.storage === undefined ? {} : { storage: rule.storage });
+        this.addState(context, kind, name, access, assignment, semanticPath, isDynamic(name), {
+            ...(rule.storage === undefined ? {} : { storage: rule.storage }),
+            ...(rule.temporary === true ? { temporary: true } : {}),
+        });
     }
     addState(context, kind, name, access, node, _semanticPath, dynamic, metadata = {}) {
         const semantic = {

package/dist/hoi4_agent_tools/event/state-keys.js

@@ -0,0 +1,63 @@
+const SCOPE_KINDS = [
+    'country',
+    'state',
+    'province',
+    'unit_leader',
+    'operative',
+    'character',
+    'global',
+    'unknown',
+];
+/** Identity of one stored value: variables and arrays live per scope, saved scopes per storage. */
+export function stateKey(value) {
+    const scope = value.kind === 'variable' || value.kind === 'array' ? `:${value.scope}` : '';
+    const storage = value.kind === 'saved_scope'
+        ? `:${value.metadata.storage === 'global' || value.metadata.storage === 'local'
+            ? value.metadata.storage
+            : 'unknown'}`
+        : '';
+    return `${value.kind}:${value.name}${scope}${storage}`;
+}
+/** Keys of every write that a read of this value can observe. */
+export function compatibleProducerKeys(value) {
+    // `event_target:name` reads local and global targets alike, whereas
+    // `global_event_target:name` reads only global ones.
+    if (value.kind === 'event_target') {
+        return [stateKey(value), `global_event_target:${value.name}`];
+    }
+    // A helper body runs in whatever scope calls it, so its scope is unknown. A write there can
+    // reach a read in any scope, and a read there can observe a write in any scope.
+    if (value.kind === 'variable' || value.kind === 'array') {
+        const scopes = value.scope === 'unknown' ? SCOPE_KINDS : [value.scope, 'unknown'];
+        const keys = scopes.map((scope) => `${value.kind}:${value.name}:${scope}`);
+        // `entries^num` and `entries^3` read the array `entries`; `GER.value` and `ROOT.value` read
+        // `value` in another scope, which may be written under its bare name in any scope.
+        const element = /^([^^]+)\^/u.exec(value.name)?.[1];
+        if (element !== undefined)
+            keys.push(...SCOPE_KINDS.map((scope) => `array:${unscopedName(element)}:${scope}`));
+        const bare = unscopedName(value.name);
+        if (bare !== value.name)
+            keys.push(...SCOPE_KINDS.map((scope) => `${value.kind}:${bare}:${scope}`));
+        return [...new Set(keys)];
+    }
+    if (value.kind !== 'saved_scope' ||
+        value.metadata.storage === 'global' ||
+        value.metadata.storage === 'local') {
+        return [stateKey(value)];
+    }
+    return [
+        `saved_scope:${value.name}:global`,
+        `saved_scope:${value.name}:local`,
+        `saved_scope:${value.name}:unknown`,
+    ];
+}
+/** `GER.value`, `ROOT.FROM.value` or `var:target.value` without its scope prefix. */
+function unscopedName(name) {
+    const scoped = /^(?:(?:[A-Z][A-Z0-9]{2}|ROOT|FROM|PREV|THIS|OWNER|CONTROLLER|CAPITAL)\.|(?:var|event_target):[A-Za-z0-9_]+\.)+(.+)$/u.exec(name);
+    return scoped?.[1] ?? name;
+}
+export function hasUnknownSavedScopeStorage(value) {
+    return (value.kind === 'saved_scope' &&
+        value.metadata.storage !== 'global' &&
+        value.metadata.storage !== 'local');
+}

package/dist/hoi4_agent_tools/event/summary.js

@@ -0,0 +1,130 @@
+import { compareCodeUnits } from '../core/canonical.js';
+/** Findings returned inline, before an agent opens the linked report. */
+export const EVENT_INLINE_FINDINGS = 10;
+const EVENT_INLINE_CODES = 10;
+const EVENT_INLINE_EVENT_IDS = 20;
+const EVENT_INLINE_MESSAGE_LENGTH = 300;
+const CLASSIFICATION_ORDER = {
+    confirmed_error: 0,
+    probable_defect: 1,
+    design_warning: 2,
+    unresolved_analysis: 3,
+};
+const CONFIDENCE_ORDER = {
+    confirmed: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+    unresolved: 4,
+};
+function countBy(values, key) {
+    const counts = new Map();
+    for (const value of values)
+        counts.set(key(value), (counts.get(key(value)) ?? 0) + 1);
+    return Object.fromEntries([...counts].sort(([left], [right]) => compareCodeUnits(left, right)));
+}
+function layer(issue) {
+    const path = issue.location?.path;
+    return path === undefined ? 'unknown' : (/^([a-z]+):/u.exec(path)?.[1] ?? 'unknown');
+}
+/** The mod's own files first, then most severe: classification, confidence, source order. */
+function issueOrder(left, right) {
+    const leftMod = layer(left) === 'mod' ? 0 : 1;
+    const rightMod = layer(right) === 'mod' ? 0 : 1;
+    return (leftMod - rightMod ||
+        CLASSIFICATION_ORDER[left.classification] - CLASSIFICATION_ORDER[right.classification] ||
+        CONFIDENCE_ORDER[left.confidence] - CONFIDENCE_ORDER[right.confidence] ||
+        compareCodeUnits(left.location?.path ?? '', right.location?.path ?? '') ||
+        (left.location?.start.line ?? 0) - (right.location?.start.line ?? 0) ||
+        compareCodeUnits(left.code, right.code) ||
+        compareCodeUnits(left.message, right.message));
+}
+/** Counts and the most severe findings of a selection, small enough to return inline. */
+export function summarizeEventIssues(issues) {
+    const byCode = Object.entries(countBy(issues, ({ code }) => code))
+        .sort(([leftCode, left], [rightCode, right]) => right - left || compareCodeUnits(leftCode, rightCode))
+        .slice(0, EVENT_INLINE_CODES);
+    return {
+        issues: issues.length,
+        byClassification: countBy(issues, ({ classification }) => classification),
+        // `mod` findings are the workspace's own; `game` and `dependency` ones are context.
+        byLayer: countBy(issues, layer),
+        topCodes: Object.fromEntries(byCode),
+        findings: [...issues]
+            .sort(issueOrder)
+            .slice(0, EVENT_INLINE_FINDINGS)
+            .map((issue) => ({
+            code: issue.code,
+            classification: issue.classification,
+            confidence: issue.confidence,
+            message: issue.message.length > EVENT_INLINE_MESSAGE_LENGTH
+                ? `${issue.message.slice(0, EVENT_INLINE_MESSAGE_LENGTH - 1)}…`
+                : issue.message,
+            ...(issue.location === undefined
+                ? {}
+                : { path: issue.location.path, line: issue.location.start.line }),
+            ...(typeof issue.details.name === 'string' ? { subject: issue.details.name } : {}),
+        })),
+    };
+}
+/** Size of a traced chain and the events it reaches. */
+export function summarizeEventTrace(trace) {
+    const events = trace.nodes
+        .flatMap(({ kind, eventId }) => (kind === 'event' && eventId !== undefined ? [eventId] : []))
+        .sort(compareCodeUnits);
+    return {
+        nodes: trace.nodes.length,
+        edges: trace.edges.length,
+        events: events.length,
+        eventIds: events.slice(0, EVENT_INLINE_EVENT_IDS),
+        boundaryNodes: trace.boundaryNodeIds.length,
+        truncated: trace.truncated,
+    };
+}
+/** How many chains start where, in a form an agent can read without the report. */
+export function summarizeEventRoots(roots) {
+    const nodeLayer = ({ sourcePath }) => sourcePath === undefined ? 'unknown' : (/^([a-z]+):/u.exec(sourcePath)?.[1] ?? 'unknown');
+    // The mod's own events first: vanilla callerless events are context, not the mod's defects.
+    const ids = (nodes) => [...nodes]
+        .sort((left, right) => (nodeLayer(left) === 'mod' ? 0 : 1) - (nodeLayer(right) === 'mod' ? 0 : 1) ||
+        compareCodeUnits(left.eventId ?? '', right.eventId ?? ''))
+        .flatMap(({ eventId }) => (eventId === undefined ? [] : [eventId]))
+        .slice(0, EVENT_INLINE_EVENT_IDS);
+    return {
+        entryPoints: roots.entryPoints.length,
+        entryKinds: countBy(roots.entryPoints, ({ metadata }) => typeof metadata.entryKind === 'string' ? metadata.entryKind : 'unknown'),
+        automaticEvents: roots.automaticEvents.length,
+        callerlessTriggeredEvents: roots.callerlessTriggeredEvents.length,
+        callerlessTriggeredByLayer: countBy(roots.callerlessTriggeredEvents, nodeLayer),
+        callerlessTriggeredEventIds: ids(roots.callerlessTriggeredEvents),
+        cycles: roots.stronglyConnectedComponents.filter(({ cyclic }) => cyclic).length,
+    };
+}
+/** Whether a route exists and, if so, the events it passes through in order. */
+export function summarizeEventPath(path) {
+    return {
+        found: path.found,
+        steps: path.steps.length,
+        eventIds: path.steps
+            .flatMap(({ node }) => node.kind === 'event' && node.eventId !== undefined ? [node.eventId] : [])
+            .slice(0, EVENT_INLINE_EVENT_IDS),
+        ...(path.failureReason === undefined ? {} : { failureReason: path.failureReason }),
+        ...(path.failureMessage === undefined ? {} : { failureMessage: path.failureMessage }),
+        unresolvedAssumptions: path.unresolvedAssumptions.length,
+    };
+}
+/** How far a change to the subject reaches, by count. */
+export function summarizeEventImpact(impact) {
+    return {
+        direct: impact.directNodeIds.length,
+        upstream: impact.upstreamNodeIds.length,
+        downstream: impact.downstreamNodeIds.length,
+        stateAccesses: impact.stateAccessIds.length,
+        affectedRoots: impact.affectedRootIds.length,
+        affectedTerminals: impact.affectedTerminalIds.length,
+        wouldDisconnect: impact.wouldDisconnectNodeIds.length,
+        wouldDisconnectTerminals: impact.wouldDisconnectTerminalIds.length,
+        unresolved: impact.unresolvedNodeIds.length,
+        sampleDownstream: impact.downstreamNodeIds.slice(0, EVENT_INLINE_EVENT_IDS),
+    };
+}

package/dist/hoi4_agent_tools/impact/service.js

@@ -94,6 +94,8 @@ export class ImpactAnalyzer {
             directConsumers: graph.directConsumers.length,
             transitiveConsumers: graph.transitiveConsumers.length,
             affectedFiles: graph.affectedFiles.length,
+            // Affected files are evidence, not writes: this read-only analysis never changes a file.
+            affectedFilePaths: graph.affectedFiles.slice(0, 64),
             cycles: graph.cycles.length,
             scenarioSuites: scenarioSuites.scannedSuites,
             affectedCases: scenarioSuites.matches.length,
@@ -108,7 +110,6 @@ export class ImpactAnalyzer {
         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,

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

@@ -16,6 +16,7 @@ const impactOutputSchema = strictOperationResultSchema(z
     directConsumers: nonNegativeIntegerSchema,
     transitiveConsumers: nonNegativeIntegerSchema,
     affectedFiles: nonNegativeIntegerSchema,
+    affectedFilePaths: z.array(z.string().max(1024)).max(64).optional(),
     cycles: nonNegativeIntegerSchema,
     scenarioSuites: nonNegativeIntegerSchema,
     affectedCases: nonNegativeIntegerSchema,