hoi4-agent-tools 4.1.0 → 4.3.0

package/dist/hoi4_agent_tools/event/queries.js

@@ -1,5 +1,6 @@
 import { compareCodeUnits } from '../core/canonical.js';
 import { eventFlowEdges, eventStronglyConnectedComponents, reachableEventNodeIds, shortestEventPath, traceEventGraph, } from './algorithms.js';
+import { compatibleProducerKeys, hasUnknownSavedScopeStorage, stateKey } from './state-keys.js';
 function reachableFromRootsWithout(graph, rootIds, removedNodeIds, signal) {
     signal?.throwIfAborted();
     const retainedNodeIds = new Set(graph.nodes.filter(({ id }) => !removedNodeIds.has(id)).map(({ id }) => id));
@@ -348,32 +349,6 @@ export function explainEventPath(graph, from, to, boundary, signal) {
         boundary,
     };
 }
-function stateKey(access) {
-    const scope = access.kind === 'variable' || access.kind === 'array' ? `:${access.scope}` : '';
-    const storage = access.kind === 'saved_scope'
-        ? `:${access.metadata.storage === 'global' || access.metadata.storage === 'local'
-            ? access.metadata.storage
-            : 'unknown'}`
-        : '';
-    return `${access.kind}:${access.name}${scope}${storage}`;
-}
-function compatibleProducerKeys(access) {
-    if (access.kind !== 'saved_scope' ||
-        access.metadata.storage === 'global' ||
-        access.metadata.storage === 'local') {
-        return [stateKey(access)];
-    }
-    return [
-        `saved_scope:${access.name}:global`,
-        `saved_scope:${access.name}:local`,
-        `saved_scope:${access.name}:unknown`,
-    ];
-}
-function hasUnknownSavedScopeStorage(access) {
-    return (access.kind === 'saved_scope' &&
-        access.metadata.storage !== 'global' &&
-        access.metadata.storage !== 'local');
-}
 function compatibleProducers(producers, consumer) {
     const compatible = new Map();
     for (const key of compatibleProducerKeys(consumer)) {
@@ -544,20 +519,24 @@ export function lintEventGraph(graph, selector, signal) {
     if (selector === undefined)
         return [...graph.issues];
     const selected = selectedOwnershipIds(graph, selector, signal);
-    const selectedNodes = graph.nodes.filter(({ id }, index) => {
+    // Source ranges of the selected nodes, grouped by file so each issue checks only its own file.
+    const selectedRanges = new Map();
+    for (const [index, { id, location }] of graph.nodes.entries()) {
         if ((index & 255) === 0)
             signal?.throwIfAborted();
-        return selected.has(id);
-    });
+        if (location === undefined || !selected.has(id))
+            continue;
+        const ranges = selectedRanges.get(location.path) ?? [];
+        ranges.push({ start: location.start.offset, end: location.end.offset });
+        selectedRanges.set(location.path, ranges);
+    }
     return graph.issues.filter((issue, index) => {
         if ((index & 255) === 0)
             signal?.throwIfAborted();
+        const location = issue.location;
         return (issueSubjectIds(issue).some((id) => selected.has(id)) ||
-            (issue.location !== undefined &&
-                selectedNodes.some(({ location }) => location !== undefined &&
-                    location.path === issue.location?.path &&
-                    issue.location.start.offset >= location.start.offset &&
-                    issue.location.end.offset <= location.end.offset)));
+            (location !== undefined &&
+                (selectedRanges.get(location.path) ?? []).some(({ start, end }) => location.start.offset >= start && location.end.offset <= end)));
     });
 }
 export function issueSubjectIds(issue) {

package/dist/hoi4_agent_tools/event/render.js

@@ -103,12 +103,14 @@ function boundedSelection(graph, options) {
     else if (options.view === 'terminals') {
         const terminals = withinSelector(graph.nodes.filter(({ kind }) => kind === 'terminal').map(({ id }) => id));
         add(terminals);
-        add(graph.edges.filter(({ to }) => terminals.includes(to)).flatMap(({ from, to }) => [from, to]));
+        const terminalIds = new Set(terminals);
+        add(graph.edges.filter(({ to }) => terminalIds.has(to)).flatMap(({ from, to }) => [from, to]));
     }
     else if (options.view === 'unresolved') {
         const unresolved = withinSelector(graph.nodes.filter(({ kind }) => kind === 'unresolved').map(({ id }) => id));
         add(unresolved);
-        add(graph.edges.filter(({ to }) => unresolved.includes(to)).flatMap(({ from, to }) => [from, to]));
+        const unresolvedIds = new Set(unresolved);
+        add(graph.edges.filter(({ to }) => unresolvedIds.has(to)).flatMap(({ from, to }) => [from, to]));
     }
     else if (options.view === 'neighborhood' || options.view === 'reachability') {
         add(selectorTrace);

package/dist/hoi4_agent_tools/event/service.js

@@ -2,7 +2,8 @@ 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 { installedEffectCommands } from '../core/game-documentation.js';
 import { boundedSourceHashEvidence, publicArtifactLink, } from '../core/artifacts.js';
 import { ServiceError } from '../core/result.js';
 import { RenderBudget } from '../core/render-budget.js';
@@ -10,7 +11,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 +212,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);
@@ -699,6 +715,8 @@ function coherentBranchPartitions(graph, nodeLimit, maximumGroups, signal) {
 export class EventChainViewer {
     engine;
     #state;
+    /** Effect names the installed game documented at each workspace's last scan. */
+    #documentedEffects = new Map();
     constructor(engine) {
         this.engine = engine;
         this.#state = sharedState(engine);
@@ -742,8 +760,11 @@ export class EventChainViewer {
             return cached.graph;
         const buildAnalysisMode = requestedAnalysisMode;
         const projectHelpers = buildAnalysisMode === 'focused' ? false : requestedProjectHelpers;
+        const documentedEffects = await installedEffectCommands(workspace.gameRoot);
+        this.#documentedEffects.set(workspaceId, documentedEffects);
         const graph = await buildEventGraphAsync(snapshot, {
             ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(documentedEffects === undefined ? {} : { documentedEffects }),
             cache: this.#state.fragments,
             workspaceIdentity: workspace.workspaceIdentity,
             projectHelpers,
@@ -808,17 +829,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 +863,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 +881,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 +912,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 +934,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 +951,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 +995,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 +1009,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 +1019,8 @@ export class EventChainViewer {
             report,
             reportJson,
             artifacts: [artifact, ...(graphArtifact === undefined ? [] : [graphArtifact])],
+            ...(snapshotOmitted ? { graphSnapshotOmitted: true } : {}),
+            summary,
         };
     }
     async renderAndStore(input) {
@@ -1001,25 +1052,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 +1229,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 +1240,7 @@ export class EventChainViewer {
             graphHash: cachedEventGraphHash(graph, input.signal),
             render,
             branches,
+            budgetOmittedBranches,
             manifestJson,
             artifacts,
         };
@@ -1261,8 +1327,10 @@ export class EventChainViewer {
             skippedSources: index.skippedSources,
             diagnostics: index.diagnostics,
         };
+        const documentedEffects = this.#documentedEffects.get(workspaceId);
         return buildEventGraph(snapshot, {
             ...(signal === undefined ? {} : { signal }),
+            ...(documentedEffects === undefined ? {} : { documentedEffects }),
             cache: this.#state.fragments,
             workspaceIdentity: workspace.workspaceIdentity,
             projectHelpers: false,

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,62 @@ 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 isNativeEffect(normalizedKey, documented) {
+    return nativeEffectKeys.has(normalizedKey) || documented?.has(normalizedKey) === true;
+}
+function isNativeArgumentBlock(normalizedKey, documented) {
+    return (isNativeEffect(normalizedKey, documented) &&
+        !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',
@@ -208,10 +288,10 @@ function localisationKeysFromValue(value) {
     }
     return [...new Set(keys)].sort(compareCodeUnits);
 }
-function missingHelperCandidate(key, value, effectContext) {
+function missingHelperCandidate(key, value, effectContext, documented) {
     const normalizedKey = key.toLowerCase();
     if (!effectContext ||
-        nativeEffectKeys.has(normalizedKey) ||
+        isNativeEffect(normalizedKey, documented) ||
         NON_HELPER_BLOCKS.has(normalizedKey) ||
         SCOPE_BLOCKS[normalizedKey] !== undefined ||
         STATE_RULES[normalizedKey] !== undefined ||
@@ -836,6 +916,7 @@ class FragmentAnalyzer {
             helperStack: [],
             semanticPath: ['other'],
             effectContext: true,
+            inferMissingHelpers: false,
         });
         if (this.edges.length + this.stateAccesses.length > before) {
             this.addNode({
@@ -913,7 +994,9 @@ class FragmentAnalyzer {
                 return;
             }
             if (this.context.inventoryComplete !== false &&
-                missingHelperCandidate(key, entry.value, effectContext)) {
+                context.nativeArguments !== true &&
+                context.inferMissingHelpers !== false &&
+                missingHelperCandidate(key, entry.value, effectContext, this.context.documentedEffectKeys)) {
                 const target = this.unresolvedNode('missing_helper', key, entry, context.ownerId, semanticPath);
                 this.addEdge(context.ownerId, target, 'scripted_effect_call', entry, context.conditions, {
                     phase: context.phase,
@@ -1039,7 +1122,14 @@ 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, this.context.documentedEffectKeys),
+                ...(context.inferMissingHelpers === false && isConventionalEffectBlock(normalizedKey)
+                    ? { inferMissingHelpers: true }
+                    : {}),
                 suppressSemantics: context.suppressSemantics === true || TOOLTIP_ONLY_BLOCKS.has(normalizedKey),
                 semanticPath,
                 ...(scopeExpression === undefined ? {} : { scopeExpression }),
@@ -1296,7 +1386,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 +1398,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 +1427,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');
+}