hoi4-agent-tools 4.1.0 → 4.3.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## Unreleased
 
+## 4.3.0 - 2026-10-19
+
+- Run probability analysis on every installed HOI4 version. `metadata.gameVersionVerification` records the observed build as `workspace_verified`, `workspace_observed` or `version_unknown` instead of refusing with `PROBABILITY_GAME_VERSION_UNSUPPORTED` or `PROBABILITY_GAME_VERSION_UNVERIFIED`; decision inspection evaluates AI weights on any version.
+- Recognize every effect the installed game documents in `documentation/effects_documentation.md` as native in event and focus analysis, so effects added by later patches are not reported as missing scripted helpers.
+
+## 4.2.0 - 2026-10-19
+
+- Keep job workers running when a discovered mod folder is removed after server start. Workers now resolve only workspaces whose roots still exist, while a job for the removed workspace still fails with `WORKSPACE_ROOT_MISSING`.
+- Stop `hoi4.event_inspect` `scan` from failing with `RangeError: Invalid string length` on large mods. The graph snapshot is measured before serialization and omitted above 128 MiB with the info diagnostic `EVENT_GRAPH_SNAPSHOT_OMITTED`.
+- Return `data.summary` from event inspection: selection finding counts by classification and code with the ten most severe source-linked findings, trace sizes and event IDs, and root counts.
+- Resolve `event_target:name` reads against `save_global_event_target_as` producers; `global_event_target:name` reads still require a global producer. This removes false `EVENT_TARGET_READ_BEFORE_SAVE` probable defects.
+- Record temporary-variable and temporary-array writes, `round_variable`, `modulo_variable`, `randomize_variable`, `set_variable_to_random` and `resize_array`. Link variable reads to writers inside scripted helpers, scope-prefixed names and `array^index` elements, removing most false `EVENT_GATE_WITHOUT_WRITER` warnings.
+- Stop inferring missing scripted helpers from native effect arguments, condition blocks of decisions, ideas, focuses and raids, trigger iterators and data fields of definition files.
+- Report unresolved references in event analysis only for symbol kinds that analysis indexes; sprite and interface references are left to the full index.
+- Keep distinct event findings in one owner separate instead of collapsing them to the first finding per code.
+- Report impact dynamic references only for symbol kinds the traversal reaches, list affected files in `data.affectedFilePaths`, and leave `changedFiles` empty for this read-only analysis.
+- Treat undeclared `has_variable` and `has_event_target` inputs as unresolved in open decision scenarios, matching flags; `closedFlags: true` keeps them absent.
+- Complete workspace-wide event `lint`, `state_flow`, `impact` and unselected renders on large mods. Helper expansion stops at its fixed work ceiling with an `EVENT_HELPER_PROJECTION_LIMIT` finding instead of failing with `DEPENDENCY_WORK_LIMIT`, and dependency checkpoints are spaced by the size of the previous save so their cost stays linear.
+- Remove quadratic passes from root discovery, event cycle checks, selector-scoped lint and terminal or unresolved renders. Root discovery on Chaos Redux with vanilla falls from minutes to under a second.
+- Report each recursive scripted-helper loop once instead of once per caller, and read `event_target:founder.values` as the target `founder`.
+- Return the overview and the branch renders that fit when an unselected overview spends its raster budget, with `omittedBranchRenders` and `coverage.budgetOmittedBranches`, instead of `RENDER_AGGREGATE_BLOCKED`.
+- Add `data.summary` to `explain_path` (route found, steps, event IDs, failure reason) and event `impact` (reach counts); root summaries list the mod's own callerless events first with counts by layer, and finding summaries rank the mod's files first with `byLayer` counts.
+- Keep decision gate, cost and lifecycle evidence when the installed game version is not verified for AI-weight adapters; the AI part is unresolved with a `PROBABILITY_GAME_VERSION_UNSUPPORTED` warning.
+- Raise the semantic reference ceiling for impact analysis and source lookup to its supported maximum of 1,000,000, so a large mod with the base game is analyzed completely.
+
 ## 4.1.0 - 2026-10-15
 
 - Add reference-image `create_world` requests with automatic dimensions, countries, biomes, coastline interpretation, drainage, offline English label recognition, optional aligned layers and reviewed semantic hints.

package/dist/hoi4_agent_tools/core/canonical.js

@@ -40,6 +40,48 @@ export function canonicalize(value) {
 export function canonicalJson(value) {
     return JSON.stringify(canonicalize(value));
 }
+/**
+ * UTF-8 byte length of `canonicalJson(value)`, or `undefined` as soon as it would exceed
+ * `limit`. The value is measured without building the string, so a caller can decline output
+ * that would exceed a JavaScript string or an artifact ceiling before allocating it.
+ */
+export function canonicalJsonByteLength(value, limit) {
+    let total = 0;
+    const add = (bytes) => (total += bytes) <= limit;
+    const visit = (current) => {
+        if (current === null || typeof current === 'string' || typeof current === 'boolean') {
+            return add(Buffer.byteLength(JSON.stringify(current)));
+        }
+        if (typeof current === 'number') {
+            if (!Number.isFinite(current))
+                throw new TypeError('Canonical JSON cannot contain non-finite numbers');
+            return add(Buffer.byteLength(JSON.stringify(Object.is(current, -0) ? 0 : current)));
+        }
+        if (Array.isArray(current)) {
+            if (!add(2 + Math.max(0, current.length - 1)))
+                return false;
+            for (let index = 0; index < current.length; index += 1) {
+                // A hole stays a hole in the canonical copy, which JSON writes as null.
+                if (!(index in current) ? !add(4) : !visit(current[index]))
+                    return false;
+            }
+            return true;
+        }
+        if (typeof current === 'object') {
+            const object = current;
+            const keys = Object.keys(object).filter((key) => object[key] !== undefined);
+            if (!add(2 + Math.max(0, keys.length - 1)))
+                return false;
+            for (const key of keys) {
+                if (!add(Buffer.byteLength(JSON.stringify(key)) + 1) || !visit(object[key]))
+                    return false;
+            }
+            return true;
+        }
+        throw new TypeError(`Canonical JSON cannot contain ${typeof current}`);
+    };
+    return visit(value) ? total : undefined;
+}
 export function sha256Bytes(value) {
     return createHash('sha256').update(value).digest('hex');
 }

package/dist/hoi4_agent_tools/core/condition-evaluator.js

@@ -302,19 +302,23 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
             return unresolved(assignment, candidate, `Scenario does not declare flag ${right}`, `flag.${right}`);
         return { state: flags?.includes(right) === true ? 'true' : 'false', unresolved: [] };
     }
+    // Like flags, an undeclared variable or event target is unknown in an open scenario and
+    // absent only when the scenario closes its world with `closedFlags`.
     if (key === 'has_event_target') {
         const eventTargets = scopeContext.binding.eventTargets ?? scenario.eventTargets;
-        return {
-            state: Object.hasOwn(eventTargets ?? {}, right) ? 'true' : 'false',
-            unresolved: [],
-        };
+        if (Object.hasOwn(eventTargets ?? {}, right))
+            return { state: 'true', unresolved: [] };
+        if (scenario.closedFlags === false)
+            return unresolved(assignment, candidate, `Scenario does not declare event target ${right}`, `eventTarget.${right}`);
+        return { state: 'false', unresolved: [] };
     }
     if (key === 'has_variable') {
         const state = scopeContext.expression === 'ROOT' ? scenario.state : scopeContext.binding.state;
-        return {
-            state: Object.hasOwn(state, right) || Object.hasOwn(state, `variable.${right}`) ? 'true' : 'false',
-            unresolved: [],
-        };
+        if (Object.hasOwn(state, right) || Object.hasOwn(state, `variable.${right}`))
+            return { state: 'true', unresolved: [] };
+        if (scenario.closedFlags === false)
+            return unresolved(assignment, candidate, `Scenario does not declare variable ${right}`, `variable.${right}`);
+        return { state: 'false', unresolved: [] };
     }
     if (key === 'tag' || key === 'original_tag') {
         const actor = scopeContext.expression === 'ROOT'

package/dist/hoi4_agent_tools/core/dependency-walk.js

@@ -24,6 +24,8 @@ const stateSchema = z
     current: z.object({ path: ordinal, edge: ordinal }).strict().nullable(),
     started: z.boolean(),
     complete: z.boolean(),
+    /** Set when a `truncate` walk stopped at its work ceiling before visiting every root. */
+    truncated: z.boolean().optional(),
 })
     .strict();
 /** A bounded, serializable DFS frontier; paths share prefixes instead of copying source data. */
@@ -82,7 +84,10 @@ export class DependencyWalk {
         const invalid = (message) => {
             throw new ServiceError('DEPENDENCY_CHECKPOINT_INVALID', message);
         };
-        if (this.state.complete !== (this.state.root === this.input.roots.length) ||
+        if ((this.state.truncated === true &&
+            (this.input.onWorkLimit !== 'truncate' || !this.state.complete)) ||
+            this.state.complete !==
+                (this.state.root === this.input.roots.length || this.state.truncated === true) ||
             (!this.state.started && (this.state.current !== null || this.state.stack.length !== 0)) ||
             (this.state.complete && this.state.started) ||
             this.state.paths.length > this.state.steps ||
@@ -152,6 +157,15 @@ export class DependencyWalk {
         const end = this.state.steps + maximumSteps;
         while (!this.state.complete && this.state.steps < end) {
             signal?.throwIfAborted();
+            if (this.state.steps >= this.input.maximumSteps && this.input.onWorkLimit === 'truncate') {
+                // Records found so far are complete paths; the unfinished frontier is dropped.
+                this.state.truncated = true;
+                this.state.complete = true;
+                this.state.started = false;
+                this.state.current = null;
+                this.state.stack = [];
+                break;
+            }
             if (this.state.steps >= this.input.maximumSteps)
                 throw new ServiceError('DEPENDENCY_WORK_LIMIT', 'Dependency expansion reached its explicit work ceiling', {
                     maximum: this.input.maximumSteps,
@@ -241,9 +255,14 @@ export async function walkDependenciesAsync(input, signal, checkpointSteps = 2_0
     const restored = await checkpoints?.load(key, input.sourceRevision, stateSchema);
     const walk = new DependencyWalk(input, restored);
     let savedAt = walk.state.steps;
+    // Each save serializes the whole frontier. Spacing saves by the size written last time
+    // doubles the gaps as the frontier grows, so total checkpoint work stays linear.
+    let savedSize = 0;
     while (!walk.state.complete) {
         const complete = walk.advance(256, signal);
-        if ((complete && savedAt > 0) || walk.state.steps - savedAt >= checkpointSteps) {
+        const interval = Math.max(checkpointSteps, savedSize);
+        if ((complete && savedAt > 0) || walk.state.steps - savedAt >= interval) {
+            savedSize = walk.state.paths.length + walk.state.records.length;
             await checkpoints?.save(key, input.sourceRevision, walk.checkpoint(), walk.state.root, input.roots.length);
             savedAt = walk.state.steps;
         }

package/dist/hoi4_agent_tools/core/domain-validation.js

@@ -54,7 +54,12 @@ export async function postValidateTransaction(engine, transaction, principal, si
             relativePath.toLowerCase().endsWith('.txt') &&
             changed.has(sourcePathComparisonKey(relativePath)))) {
             const document = parseClausewitz(file.bytes, file.displayPath);
-            const imported = importFocusTrees(document, { references: catalog });
+            const imported = importFocusTrees(document, {
+                references: catalog,
+                ...(snapshot.documentedEffects === undefined
+                    ? {}
+                    : { nativeEffects: snapshot.documentedEffects.names }),
+            });
             diagnostics.push(...imported.diagnostics);
             for (const plan of imported.plans) {
                 const layout = await layoutFocusTreeAsync(plan, signal === undefined ? {} : { signal });

package/dist/hoi4_agent_tools/core/engine.js

@@ -1,4 +1,5 @@
 import { compareCodeUnits, hashCanonical } from './canonical.js';
+import { installedEffectCommands } from './game-documentation.js';
 import { SymbolIndex } from './index.js';
 import { IndexSegmentCache } from './index-segments.js';
 import { PersistentAnalysisCache, } from './persistent-analysis-cache.js';
@@ -231,6 +232,7 @@ export class CoreEngine {
                         .at(-1)?.[1].index;
                     const index = await SymbolIndex.buildAsync(files, controller.signal, this.indexSegments, previous);
                     await persistentAnalysisCache?.persist(analysisScope, files, sourceDocuments, this.indexSegments, controller.signal);
+                    const documentedEffects = await installedEffectCommands(workspace.gameRoot);
                     const snapshot = {
                         workspaceId,
                         revision,
@@ -240,6 +242,7 @@ export class CoreEngine {
                         skippedSourceCount: index.skippedSourceCount,
                         skippedSources: index.skippedSources,
                         diagnostics: index.diagnostics,
+                        ...(documentedEffects === undefined ? {} : { documentedEffects }),
                     };
                     if ((this.#scanGenerations.get(workspaceId) ?? 0) === generation) {
                         // Replace this request's earlier revision and drop earlier generations; keep the

package/dist/hoi4_agent_tools/core/game-documentation.js

@@ -0,0 +1,24 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { sha256Bytes } from './canonical.js';
+/** `## name` headings of an installed `*_documentation.md` file. */
+export function documentedCommandNames(markdown) {
+    return new Set([...markdown.matchAll(/^## ([a-z_][a-z0-9_]*)[ \t]*\r?$/gmu)].map((match) => match[1]));
+}
+/**
+ * Read the effect names the installed game documents. Each game version ships this file, so
+ * effects added by a later patch are recognized without a tool update. Absent or unreadable
+ * documentation returns `undefined` and callers fall back to their built-in list.
+ */
+export async function installedEffectCommands(gameRoot) {
+    if (gameRoot === undefined)
+        return undefined;
+    try {
+        const bytes = await readFile(path.join(gameRoot, 'documentation', 'effects_documentation.md'));
+        const names = documentedCommandNames(bytes.toString('utf8'));
+        return names.size === 0 ? undefined : { names, sha256: sha256Bytes(bytes) };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/hoi4_agent_tools/core/impact-graph.js

@@ -263,6 +263,10 @@ export function inspectImpactGraph(snapshot, query) {
             queue.push({ key: consumerKey, depth: depth + 1 });
         }
     }
+    // A dynamic reference can only reach a symbol of the kind it names, so references to other
+    // kinds neither hide consumers of this selection nor make its evidence incomplete.
+    const traversedKinds = new Set([...visited].map((key) => key.slice(0, key.indexOf('\0'))));
+    const dynamicReferences = semantic.unresolved.filter(({ toKind }) => traversedKinds.has(toKind));
     const { cycles, omittedCycles } = reachedCycleEdges(visited, [
         ...directConsumers,
         ...transitiveConsumers,
@@ -276,14 +280,14 @@ export function inspectImpactGraph(snapshot, query) {
             omittedCycles === 0 &&
             !stoppedAtDepth &&
             unresolved.length === 0 &&
-            semantic.unresolved.length === 0,
+            dynamicReferences.length === 0,
         definitions,
         missingSymbols,
         directConsumers: directConsumers.sort(edgeOrder),
         transitiveConsumers: transitiveConsumers.sort(edgeOrder),
         affectedFiles: [...affectedFiles].sort(compareCodeUnits),
         unresolved,
-        dynamicReferences: semantic.unresolved,
+        dynamicReferences,
         cycles,
         coverage: {
             scannedSymbols: snapshot.index.symbols.length,

package/dist/hoi4_agent_tools/core/impact-semantic.js

@@ -1,5 +1,11 @@
 import { compareCodeUnits } from './canonical.js';
 import { assignments, firstScalar, nodeLocation, parseClausewitz, } from './source/index.js';
+/**
+ * Semantic references retained per workspace scan. A large mod with the base game holds several
+ * hundred thousand (one measured mod with vanilla held about 660,000), so the ceiling is the supported
+ * maximum rather than a fraction of it.
+ */
+export const IMPACT_SEMANTIC_MAX_REFERENCES = 1_000_000;
 const eventKeys = new Set([
     'country_event',
     'news_event',
@@ -120,8 +126,10 @@ function staticTarget(value) {
         !/^(?:ROOT|FROM|PREV|THIS)$/iu.test(value));
 }
 /** Extracts typed script edges while preserving unknown dynamic references. */
-export function scanImpactSemanticReferences(snapshot, maxReferences = 200_000, options = {}) {
-    if (!Number.isSafeInteger(maxReferences) || maxReferences < 1 || maxReferences > 1_000_000)
+export function scanImpactSemanticReferences(snapshot, maxReferences = IMPACT_SEMANTIC_MAX_REFERENCES, options = {}) {
+    if (!Number.isSafeInteger(maxReferences) ||
+        maxReferences < 1 ||
+        maxReferences > IMPACT_SEMANTIC_MAX_REFERENCES)
         throw new RangeError('Semantic reference limit is outside the supported range');
     const references = [];
     const unresolved = [];
@@ -134,6 +142,7 @@ export function scanImpactSemanticReferences(snapshot, maxReferences = 200_000,
                     path: file.displayPath,
                     location: nodeLocation(document, node, owner.id),
                     reason: `Dynamic ${referenceKind} target ${target} cannot be resolved statically`,
+                    toKind,
                 });
             else
                 complete = false;
@@ -192,6 +201,7 @@ export function scanImpactSemanticReferences(snapshot, maxReferences = 200_000,
                                 path: file.displayPath,
                                 location: nodeLocation(document, assignment, current.id),
                                 reason: `Cannot identify ${key} state key`,
+                                toKind: stateOperation.kind,
                             });
                         else
                             complete = false;

package/dist/hoi4_agent_tools/core/index.js

@@ -1440,6 +1440,7 @@ export class SymbolIndex {
                 ...(reference.location === undefined ? {} : { location: reference.location }),
                 details: {
                     referenceKind: reference.kind,
+                    toKind: reference.toKind,
                     from: reference.from,
                     ...(mayResolveFromSkippedSource ? { skippedSourceCount: this.#skippedSourceCount } : {}),
                 },

package/dist/hoi4_agent_tools/core/job-worker-host.js

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { closeSync, fstatSync, openSync, readSync, readdirSync, rmSync, statSync } from 'node:fs';
-import { mkdir } from 'node:fs/promises';
+import { mkdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { setTimeout as delay } from 'node:timers/promises';
@@ -134,6 +134,16 @@ function retainOrRemoveLog(file, evidence, logRoot) {
  * Bounded, fixed-entry child execution. Client disconnection never kills a worker; an
  * overdue or unresponsive cancelled read-only worker is stopped by its supervising host.
  */
+/**
+ * Select the workspaces a job worker resolves again. A mod folder removed after the host
+ * discovered it must not stop jobs for every other workspace, so absent roots are left out.
+ * The job's own workspace is always kept, and a missing root still fails that job explicitly.
+ */
+export async function workerWorkspaces(workspaces, workspaceId) {
+    const retained = await Promise.all(workspaces.map(async (workspace) => workspace.id === workspaceId ||
+        (await stat(workspace.modRoot).then((metadata) => metadata.isDirectory(), () => false))));
+    return workspaces.filter((_workspace, index) => retained[index]);
+}
 export class JobWorkerHost {
     engine;
     jobs;
@@ -234,7 +244,7 @@ export class JobWorkerHost {
             return;
         const configuration = this.engine.resolver.config();
         const registeredWorkspaceIds = new Set(configuration.workspaces.map((workspace) => workspace.id));
-        const resolvedWorkspaces = this.engine.resolver.list();
+        const resolvedWorkspaces = await workerWorkspaces(this.engine.resolver.list(), workspaceId);
         const discoveredWorkspaceIds = resolvedWorkspaces
             .map((workspace) => workspace.id)
             .filter((workspaceId) => !registeredWorkspaceIds.has(workspaceId));

package/dist/hoi4_agent_tools/event/algorithms.js

@@ -362,10 +362,11 @@ export function eventStronglyConnectedComponents(graph, expandHelpers = false, s
     const budget = new EventAnalysisBudget(signal);
     const components = iterativeStronglyConnectedComponents(retainedNodes, adjacency, () => budget.spend('strongly_connected_components'));
     budget.check();
+    // Collect self-loops once: scanning every edge per component is quadratic on large mods.
+    const selfLoops = new Set(edges.filter(({ from, to }) => from === to).map(({ from }) => from));
     return components
         .map((nodeIds) => {
-        const members = new Set(nodeIds);
-        const selfLoop = edges.some(({ from, to }) => from === to && members.has(from));
+        const selfLoop = nodeIds.some((nodeId) => selfLoops.has(nodeId));
         return {
             id: `scc:${nodeIds.join('|')}`,
             nodeIds,

package/dist/hoi4_agent_tools/event/graph.js

@@ -5,6 +5,7 @@ import { beginSemanticAnalysis, semanticFragment, SemanticCatalog, } from '../co
 import { runDependencyAnalysis, runDependencyAnalysisAsync, } from '../core/dependency-walk.js';
 import { EVENT_GRAPH_MAX_EDGES, EVENT_GRAPH_MAX_HELPER_DEPTH, EVENT_GRAPH_MAX_HELPER_PROJECTIONS, EVENT_GRAPH_MAX_HELPER_STATE_PROJECTIONS, EVENT_GRAPH_MAX_ISSUES, EVENT_GRAPH_MAX_NODES, EVENT_GRAPH_MAX_STATE_ACCESSES, EVENT_GRAPH_MAX_STATE_LINK_CANDIDATES, EVENT_GRAPH_MAX_STATE_LINKS, EVENT_GRAPH_MAX_UNRESOLVED, EVENT_GRAPH_WORK_LIMIT, EventAnalysisBudget, } from './limits.js';
 import { EVENT_GRAPH_PARSER_VERSION, EVENT_GRAPH_SCHEMA_VERSION, } from './model.js';
+import { compatibleProducerKeys, hasUnknownSavedScopeStorage, stateKey } from './state-keys.js';
 import { iterativeStronglyConnectedComponents } from './scc.js';
 import { analyzeEventSource, eventSemanticFragmentCacheKey } from './source-analysis.js';
 const confidenceRank = {
@@ -117,11 +118,14 @@ function locationKey(location) {
     return `${location?.path ?? ''}:${location?.start.offset ?? -1}:${location?.end.offset ?? -1}`;
 }
 function issueKey(issue) {
-    const subjectIds = issue.details.subjectIds;
+    // One finding per owner and subject: repeated accesses to the same named state collapse,
+    // while different events, targets, flags or expressions in one owner stay separate findings.
+    const { subjectIds, accessId: _accessId, stateLinkId: _stateLinkId, ...subject } = issue.details;
     return hashCanonical({
         code: issue.code,
         classification: issue.classification,
         subjectIds: Array.isArray(subjectIds) ? subjectIds : [],
+        subject,
     });
 }
 function stableIssues(values) {
@@ -360,6 +364,7 @@ function helperWalkInput(graph, revision) {
         maximumSteps: EVENT_GRAPH_WORK_LIMIT,
         visitPolicy: 'node',
         reverseEdges: true,
+        onWorkLimit: 'truncate',
     };
 }
 function helperCallerScope(nodes, parents, start) {
@@ -391,11 +396,17 @@ function helperProjections(graph, budget, walk) {
         const final = structural.at(-1);
         const helpers = structural.slice(0, -1).map(({ to }) => nodes.get(to));
         if (record.kind === 'cycle' || record.kind === 'depth') {
-            const key = `${record.kind}:${start.id}:${final.to}`;
+            const cycle = record.kind === 'cycle';
+            // One finding per recursive loop, identified by its member helpers, rather than one per
+            // caller that reaches it.
+            const chain = helpers.map(({ id }) => id);
+            const members = chain.slice(Math.max(0, chain.indexOf(final.to)));
+            const key = cycle
+                ? `cycle:${[...members].sort(compareCodeUnits).join('\0')}`
+                : `depth:${start.id}:${final.to}`;
             if (reported.has(key))
                 continue;
             reported.add(key);
-            const cycle = record.kind === 'cycle';
             addIssue(graph.issues, {
                 code: cycle ? 'EVENT_HELPER_CYCLE' : 'EVENT_HELPER_DEPTH_LIMIT',
                 classification: 'unresolved_analysis',
@@ -415,9 +426,7 @@ function helperProjections(graph, budget, walk) {
                         ...(cycle ? {} : { details: { maximumDepth: EVENT_GRAPH_MAX_HELPER_DEPTH } }),
                     },
                 ],
-                subjectIds: cycle
-                    ? [start.from, ...helpers.map(({ id }) => id), final.to]
-                    : [start.from, final.to],
+                subjectIds: cycle ? members : [start.from, final.to],
             });
             continue;
         }
@@ -617,32 +626,6 @@ function addTerminalNodes(graph) {
         });
     }
 }
-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}`;
-}
-function compatibleProducerKeys(value) {
-    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`,
-    ];
-}
-function hasUnknownSavedScopeStorage(value) {
-    return (value.kind === 'saved_scope' &&
-        value.metadata.storage !== 'global' &&
-        value.metadata.storage !== 'local');
-}
 function collapsedFlowEdges(nodes, edges) {
     return edges
         .filter((edge) => {
@@ -999,9 +982,23 @@ function structuralCallIssues(graph, budget) {
     for (const values of cyclicOutgoing.values())
         values.sort(compareCodeUnits);
     const flowComponents = iterativeStronglyConnectedComponents(collapsed.flatMap(({ from, to }) => [from, to]), cyclicOutgoing, () => budget.spend('event_cycle'));
-    for (const component of flowComponents) {
-        const members = new Set(component);
-        const internal = collapsed.filter(({ from, to }) => members.has(from) && members.has(to));
+    // Group each edge under its component once instead of filtering every edge per component.
+    const componentOf = new Map();
+    flowComponents.forEach((component, index) => {
+        for (const member of component)
+            componentOf.set(member, index);
+    });
+    const internalEdges = new Map();
+    for (const edge of collapsed) {
+        const component = componentOf.get(edge.from);
+        if (component === undefined || componentOf.get(edge.to) !== component)
+            continue;
+        const values = internalEdges.get(component) ?? [];
+        values.push(edge);
+        internalEdges.set(component, values);
+    }
+    for (const [componentIndex, component] of flowComponents.entries()) {
+        const internal = internalEdges.get(componentIndex) ?? [];
         const cyclic = component.length > 1 || internal.some(({ from, to }) => from === to);
         if (!cyclic)
             continue;
@@ -1386,14 +1383,21 @@ function analyzeFragments(snapshot, files, catalog, options, budget) {
         activeDecisionPaths: reads.bind('active-decisions', 'decision', catalog.activeDecisionPaths),
         inventoryComplete: snapshot.complete,
         catalogFingerprint: catalog.fingerprint,
+        ...(options.documentedEffects === undefined
+            ? {}
+            : { documentedEffectKeys: options.documentedEffects.names }),
     };
+    // A game update that documents new effects changes how fragments read, so it keys the cache.
+    const fragmentFingerprint = options.documentedEffects === undefined
+        ? catalog.fingerprint
+        : `${catalog.fingerprint}:${options.documentedEffects.sha256}`;
     for (const file of files) {
         budget.spend('source_fragment');
         if (!shouldAnalyzeEventFile(file))
             continue;
         if (snapshot.index.isSourceSkipped(file.displayPath))
             continue;
-        const cacheKey = eventSemanticFragmentCacheKey(file, catalog.fingerprint);
+        const cacheKey = eventSemanticFragmentCacheKey(file, fragmentFingerprint);
         const fragment = semanticFragment(dependencies, options.cache, file, cacheKey, reads, () => analyzeEventSource(file, context));
         fragments.push(fragment);
     }
@@ -1487,6 +1491,26 @@ function* eventGraphAnalysis(snapshot, options) {
     ensureReferencedNodes(graph);
     if (options.projectHelpers !== false) {
         const walk = yield helperWalkInput(graph, snapshot.revision);
+        if (walk.state.truncated === true)
+            addIssue(graph.issues, {
+                code: 'EVENT_HELPER_PROJECTION_LIMIT',
+                classification: 'unresolved_analysis',
+                severity: 'blocker',
+                message: 'Helper expansion reached its fixed work ceiling; helper calls from the remaining roots stay structural.',
+                confidence: 'unresolved',
+                blockers: [
+                    {
+                        code: 'HELPER_PROJECTION_LIMIT',
+                        message: 'Select a namespace, event or file, or use helper_expansion mode, for paths beyond the ceiling.',
+                        details: {
+                            maximum: EVENT_GRAPH_WORK_LIMIT,
+                            completedRoots: walk.state.root,
+                            totalRoots: walk.input.roots.length,
+                        },
+                    },
+                ],
+                details: { completedRoots: walk.state.root, totalRoots: walk.input.roots.length },
+            });
         for (const edge of helperProjections(graph, budget, walk))
             graph.edges.push(edge);
         for (const access of projectHelperStateAccesses(graph, budget, walk))

package/dist/hoi4_agent_tools/event/limits.js

@@ -17,6 +17,10 @@ export const EVENT_GRAPH_WORK_LIMIT = 10_000_000;
 export const EVENT_FRAGMENT_CACHE_MAX_ENTRIES = 10_000;
 export const EVENT_FRAGMENT_CACHE_MAX_SOURCE_BYTES = 134_217_728;
 export const EVENT_PROPOSED_SOURCE_MAX_FILES = 64;
+// The full graph snapshot of a scan is retained only up to this size. Larger graphs, such as a
+// mod with several thousand events and hundreds of thousands of state accesses, would exceed a
+// JavaScript string and the artifact preparation ceiling.
+export const EVENT_GRAPH_SNAPSHOT_MAX_BYTES = 134_217_728;
 export const EVENT_PROPOSED_SOURCE_MAX_BYTES = 67_108_864;
 /** One cooperative, deterministic work ceiling shared by extraction and graph construction. */
 export class EventAnalysisBudget {

package/dist/hoi4_agent_tools/event/operations.js

@@ -4,6 +4,7 @@ import { publicArtifactLink } from '../core/artifacts.js';
 import { setInlineFilesScanned } from '../core/operation-result.js';
 import { emptyServiceResult } from '../core/result.js';
 import { eventInspectRequestSchema, splitEventInspectRequest, eventRenderRequestSchema, eventCompareRequestSchema, } from '../schemas/event.js';
+import { EVENT_GRAPH_SNAPSHOT_MAX_BYTES } from './limits.js';
 import { eventDiagnostics, } from './service.js';
 export function normalizeEventInspectionRequest(input) {
     // Validated request fields are JSON-only. Match wire semantics by removing optional
@@ -87,6 +88,7 @@ export async function inspectEvents(viewer, input) {
         ...(inspected.helperExpansion === undefined
             ? {}
             : { helperExpansion: inspected.helperExpansion }),
+        ...(inspected.summary === undefined ? {} : { summary: inspected.summary }),
         boundary: {
             direction: input.direction ?? 'both',
             maxDepth: inspected.helperExpansion?.maxDepth ?? input.maxDepth ?? 8,
@@ -103,6 +105,14 @@ export async function inspectEvents(viewer, input) {
             : 'EVENT_INSPECTED_PARTIAL';
     setInlineFilesScanned(result, inspected.graph.filesScanned);
     result.artifacts = inspected.artifacts.map(publicArtifactLink);
+    if (inspected.graphSnapshotOmitted === true)
+        result.diagnostics.push({
+            category: 'configuration',
+            code: 'EVENT_GRAPH_SNAPSHOT_OMITTED',
+            severity: 'info',
+            message: 'The workspace graph is too large to retain as a snapshot artifact; the scan report is linked, and comparisons use revisions held by this server',
+            details: { maximumBytes: EVENT_GRAPH_SNAPSHOT_MAX_BYTES },
+        });
     result.validation = eventGraphValidation(inspected.graph);
     if (inspected.helperExpansion !== undefined)
         result.validation = helperExpansionValidation(inspected.helperExpansion);
@@ -122,6 +132,7 @@ export async function renderEvents(viewer, input) {
             selectedNodes: rendered.render.selectedNodeIds.length,
             omittedNodes: rendered.render.omittedNodeCount,
             branchRenders: rendered.branches.length,
+            omittedBranchRenders: rendered.budgetOmittedBranches,
         },
         boundary: {
             direction: input.direction ?? 'both',