hoi4-agent-tools 4.0.5 → 4.2.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## Unreleased
 
+## 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.
+- Add `preview: true` to map rewrites. Previews validate and render without creating or applying a rewrite transaction; failed generation is never illustrated using the unchanged base-game map.
+- Guard local reference inputs with canonical workspace checks, bounded decoding, fixed-memory original-source hashing and stale-source verification. OCR uses packaged local model data and bounded worker lifetimes.
+- Generate smoother relief, connected terrain-dependent provinces and downhill rivers; use installed palette conventions, distinct country filenames and actual urban footprints.
+- Cache map colors per province instead of hashing them for every rendered pixel. Retain deterministic pixels and artifact contents.
+- Preserve reviewed city, state, sea and region names and report uncertain interpretation. Map generation remains an offline foundation, with live acceptance evidence reported separately.
+- Add starter bookmarks, country histories, infantry templates, units, stockpiles and production; isolate old-world AI and startup hooks while retaining shared continent identifiers.
+- Track generated outputs and safely remove obsolete files on regeneration; reject edited outputs and malformed inventories. Bound complete-world inline diffs so preview links remain available.
+- Clean detached water speckles without turning lake islands into ocean pockets, preserve native province extent limits, and emit building positions without a spurious final record.
+
 ## 4.0.5 - 2026-10-14
 
 - Keep child anchors independent of parent `origo`, so centered native windows place their controls inside the frame.

package/README.md

@@ -17,6 +17,8 @@ Make focus trees, events and decisions. Edit maps and generate a new world. Prev
 ## What it does
 
 Your agent can build and edit focus trees, events, decisions and maps, and generate a new world.
+
+For a new map, give it a cleaned local reference image and preview the interpreted geography before writing. The [map workflow](docs/map.md#generate-a-world-from-one-image) creates provinces, states, terrain, cities, countries, supply and a provisional starting scenario. Reviewed names and masks refine ambiguous artwork; offline validation is separate from [native campaign acceptance](https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.1.0/docs/evaluations/worldgen_acceptance_2026-10-15.md).
 It previews focus trees, technology folders, windows and maps, finds the right rule in the game's documentation, fixes broken script and tunes AI choices.
 You describe what you want; the agent picks the right tools.
 

package/dist/hoi4_agent_tools/core/bounded-source.js

@@ -0,0 +1,210 @@
+import { ServiceError } from './result.js';
+import { prepareSource, verifySource } from './scanner.js';
+import { isWithin } from './workspace.js';
+import { createHash } from 'node:crypto';
+import { lstat, mkdtemp, open, realpath, rmdir, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import sharp from 'sharp';
+import { TemporaryDirectoryLifetime, sweepTemporaryDirectories } from './temporary-directories.js';
+export const REFERENCE_SOURCE_MAX_BYTES = 1_073_741_824;
+export const REFERENCE_WORKING_MAX_SIDE = 3_072;
+export const REFERENCE_WORKING_MAX_BYTES = 33_554_432;
+function supportedRasterHeader(bytes) {
+    return ((bytes.length >= 8 &&
+        [137, 80, 78, 71, 13, 10, 26, 10].every((value, index) => bytes[index] === value)) ||
+        (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) ||
+        (bytes.length >= 12 &&
+            [82, 73, 70, 70].every((value, index) => bytes[index] === value) &&
+            [87, 69, 66, 80].every((value, index) => bytes[index + 8] === value)));
+}
+function assertSnapshotIsolation(resolver, candidate, checkDescendants) {
+    for (const workspace of resolver.list())
+        for (const root of [
+            ...workspace.roots,
+            { path: workspace.artifactRoot },
+            { path: workspace.cacheRoot },
+        ])
+            if (isWithin(root.path, candidate) || (checkDescendants && isWithin(candidate, root.path)))
+                throw new ServiceError('REFERENCE_SNAPSHOT_UNSAFE', 'Reference snapshots must be outside workspace capability roots');
+}
+async function assertSnapshotDirectory(resolver, directory, parent) {
+    const canonical = path.normalize(await realpath(directory));
+    const metadata = await lstat(directory);
+    if (canonical !== path.normalize(directory) ||
+        !isWithin(parent, canonical) ||
+        canonical === parent ||
+        metadata.isSymbolicLink() ||
+        !metadata.isDirectory())
+        throw new ServiceError('REFERENCE_SNAPSHOT_UNSAFE', 'Reference snapshot directory is not a private canonical directory');
+    if (process.platform !== 'win32' &&
+        ((metadata.mode & 0o077) !== 0 ||
+            (process.getuid !== undefined && metadata.uid !== process.getuid())))
+        throw new ServiceError('REFERENCE_SNAPSHOT_UNSAFE', 'Reference snapshot directory permissions are not private');
+    assertSnapshotIsolation(resolver, canonical, true);
+}
+async function createPrivateSnapshot(resolver) {
+    const parent = path.normalize(await realpath(resolver.serverState()?.root ?? tmpdir()));
+    assertSnapshotIsolation(resolver, parent, false);
+    const parentMetadata = await lstat(parent);
+    if (!parentMetadata.isDirectory() ||
+        parentMetadata.isSymbolicLink() ||
+        (process.platform !== 'win32' &&
+            (parentMetadata.mode & 0o022) !== 0 &&
+            (parentMetadata.mode & 0o1000) === 0))
+        throw new ServiceError('REFERENCE_SNAPSHOT_UNSAFE', 'Reference snapshot parent is not protected against directory replacement');
+    // Hidden directories are excluded by mod-root discovery even with a temporary-root fallback.
+    await sweepTemporaryDirectories(parent, {
+        referenceSnapshotsOnly: true,
+        staleMs: 0,
+        maxBytes: REFERENCE_SOURCE_MAX_BYTES,
+        protectedRoots: resolver
+            .list()
+            .flatMap((workspace) => [
+            ...workspace.roots.map(({ path }) => path),
+            workspace.artifactRoot,
+            workspace.cacheRoot,
+        ]),
+    });
+    const directory = await mkdtemp(path.join(parent, '.reference-snapshot-'));
+    const lifetime = new TemporaryDirectoryLifetime(REFERENCE_SOURCE_MAX_BYTES);
+    try {
+        await assertSnapshotDirectory(resolver, directory, parent);
+        await lifetime.own(directory);
+        const filePath = path.join(directory, 'source.raster');
+        const handle = await open(filePath, 'wx', 0o600);
+        try {
+            await assertSnapshotDirectory(resolver, directory, parent);
+            return { directory, filePath, handle, closed: false, lifetime };
+        }
+        catch (error) {
+            await handle.close();
+            await unlink(filePath);
+            throw error;
+        }
+    }
+    catch (error) {
+        await lifetime.dispose();
+        if (await lstat(directory).catch(() => undefined))
+            await rmdir(directory);
+        throw error;
+    }
+}
+async function removePrivateSnapshot(snapshot) {
+    try {
+        let closeFailed = false;
+        try {
+            if (!snapshot.closed)
+                await snapshot.handle.close();
+        }
+        catch {
+            closeFailed = true;
+        }
+        await snapshot.lifetime.dispose();
+        if (closeFailed || (await lstat(snapshot.directory).catch(() => undefined)))
+            throw new Error('Private snapshot ownership changed before cleanup');
+    }
+    catch {
+        throw new ServiceError('REFERENCE_SNAPSHOT_CLEANUP_FAILED', 'Private reference snapshot cleanup failed');
+    }
+}
+/** Decode a private snapshot copied and hashed from the same verified FD, using fixed memory. */
+export async function readReferenceImageSource(resolver, workspaceId, relativePath, principal, signal) {
+    if (!/\.(?:png|jpe?g|webp)$/iu.test(relativePath) || relativePath.includes(':'))
+        throw new ServiceError('REFERENCE_IMAGE_PATH_INVALID', 'Reference must name a local raster image');
+    const resolved = await resolver.resolvePath(workspaceId, relativePath, 'read', ['mod'], principal);
+    const source = await prepareSource(resolved.root, relativePath, signal);
+    let snapshot;
+    try {
+        if (!source.metadata.isFile())
+            throw new ServiceError('SOURCE_NOT_REGULAR_FILE', 'Reference source must be a regular file');
+        if (source.metadata.size < 1 || source.metadata.size > REFERENCE_SOURCE_MAX_BYTES)
+            throw new ServiceError('SOURCE_BYTE_LIMIT', 'Reference source exceeds its byte limit', {
+                limit: REFERENCE_SOURCE_MAX_BYTES,
+            });
+        signal?.throwIfAborted();
+        snapshot = await createPrivateSnapshot(resolver);
+        const hash = createHash('sha256');
+        const chunk = Buffer.alloc(Math.min(1_048_576, source.metadata.size));
+        let offset = 0;
+        while (offset < source.metadata.size) {
+            signal?.throwIfAborted();
+            const read = await source.handle.read(chunk, 0, Math.min(chunk.length, source.metadata.size - offset), offset);
+            if (read.bytesRead === 0)
+                throw new ServiceError('SCAN_SOURCE_CHANGED', 'Reference source changed while copying its snapshot');
+            if (offset === 0 && !supportedRasterHeader(chunk.subarray(0, read.bytesRead)))
+                throw new ServiceError('REFERENCE_IMAGE_DECODE_FAILED', 'Reference source is not a supported raster image');
+            hash.update(chunk.subarray(0, read.bytesRead));
+            let written = 0;
+            while (written < read.bytesRead) {
+                const result = await snapshot.handle.write(chunk, written, read.bytesRead - written, offset + written);
+                if (result.bytesWritten === 0)
+                    throw new ServiceError('REFERENCE_SNAPSHOT_WRITE_FAILED', 'Reference snapshot could not be completed');
+                written += result.bytesWritten;
+            }
+            offset += read.bytesRead;
+        }
+        const originalHash = hash.digest('hex');
+        await snapshot.handle.close();
+        snapshot.closed = true;
+        await verifySource(resolved.root, source);
+        signal?.throwIfAborted();
+        sharp.cache({ memory: 32, files: 0, items: 32 });
+        const input = sharp(snapshot.filePath, {
+            sequentialRead: true,
+            limitInputPixels: 300_000_000,
+            failOn: 'warning',
+        });
+        const metadata = await input.metadata();
+        if (!metadata.width ||
+            !metadata.height ||
+            (metadata.pages ?? 1) > 1 ||
+            !['png', 'jpeg', 'webp'].includes(metadata.format))
+            throw new ServiceError('REFERENCE_IMAGE_UNSUPPORTED', 'Reference must be a single-frame supported raster image');
+        signal?.throwIfAborted();
+        const decoded = await input
+            .resize({
+            width: REFERENCE_WORKING_MAX_SIDE,
+            height: REFERENCE_WORKING_MAX_SIDE,
+            fit: 'inside',
+            withoutEnlargement: true,
+        })
+            .png()
+            .toBuffer({ resolveWithObject: true });
+        await verifySource(resolved.root, source);
+        signal?.throwIfAborted();
+        if (decoded.data.length > REFERENCE_WORKING_MAX_BYTES)
+            throw new ServiceError('REFERENCE_WORKING_BYTE_LIMIT', 'Reference working image exceeds its byte limit');
+        return {
+            source: {
+                absolutePath: source.canonicalPath,
+                displayPath: `mod:${relativePath.replaceAll('\\', '/')}`,
+                relativePath: relativePath.replaceAll('\\', '/'),
+                rootKind: resolved.root.kind,
+                loadOrder: resolved.root.loadOrder,
+                size: source.metadata.size,
+                modifiedMs: source.metadata.mtimeMs,
+                sha256: originalHash,
+            },
+            bytes: decoded.data,
+            originalWidth: metadata.width,
+            originalHeight: metadata.height,
+            workingWidth: decoded.info.width,
+            workingHeight: decoded.info.height,
+        };
+    }
+    catch (error) {
+        if (error instanceof ServiceError || signal?.aborted)
+            throw error;
+        throw new ServiceError('REFERENCE_IMAGE_DECODE_FAILED', 'Reference image could not be safely decoded');
+    }
+    finally {
+        try {
+            if (snapshot !== undefined)
+                await removePrivateSnapshot(snapshot);
+        }
+        finally {
+            await source.handle.close();
+        }
+    }
+}

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/diagnostic-rollup.js

@@ -0,0 +1,91 @@
+import { canonicalJson, compareCodeUnits } from './canonical.js';
+import { sortDiagnostics } from './diagnostics.js';
+const SAMPLE_LIMIT = 8;
+/** Count source occurrences represented by an original diagnostic or a soft rollup. */
+export function diagnosticOccurrenceCount(diagnostic) {
+    const value = diagnostic.details?.occurrenceCount;
+    return diagnostic.details?.rollup === 'repeated-soft-diagnostics.v1' &&
+        typeof value === 'number' &&
+        Number.isSafeInteger(value) &&
+        value > 0
+        ? value
+        : 1;
+}
+/** Include omission evidence emitted by bounded validators without counting their marker twice. */
+export function diagnosticSeverityCounts(diagnostics) {
+    const counts = { info: 0, warning: 0, error: 0, blocker: 0 };
+    for (const diagnostic of diagnostics) {
+        if (diagnostic.code !== 'MAP_DIAGNOSTICS_TRUNCATED') {
+            counts[diagnostic.severity] += diagnosticOccurrenceCount(diagnostic);
+            continue;
+        }
+        const omissions = diagnostic.details?.omittedBySeverity;
+        if (typeof omissions !== 'object' || omissions === null)
+            continue;
+        for (const severity of ['info', 'warning', 'error', 'blocker']) {
+            const value = omissions[severity];
+            if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0)
+                counts[severity] += value;
+        }
+    }
+    return counts;
+}
+/** Keep every hard diagnostic; summarize repeated informational and warning codes only. */
+export function rollupRepeatedSoftDiagnostics(diagnostics, evidence) {
+    const hard = [];
+    const groups = new Map();
+    const ordered = diagnostics
+        .map((diagnostic) => ({ diagnostic, key: canonicalJson(diagnostic) }))
+        .sort((left, right) => compareCodeUnits(left.key, right.key))
+        .map(({ diagnostic }) => diagnostic);
+    for (const diagnostic of ordered) {
+        if (diagnostic.severity === 'error' ||
+            diagnostic.severity === 'blocker' ||
+            diagnostic.code === 'MAP_DIAGNOSTICS_TRUNCATED') {
+            hard.push(diagnostic);
+            continue;
+        }
+        const key = `${diagnostic.severity}:${diagnostic.code}`;
+        const group = groups.get(key) ?? [];
+        group.push(diagnostic);
+        groups.set(key, group);
+    }
+    const soft = [...groups.values()].map((group) => {
+        if (group.length === 1)
+            return group[0];
+        const first = group[0];
+        const occurrences = group.reduce((total, diagnostic) => total + diagnosticOccurrenceCount(diagnostic), 0);
+        const locations = new Map();
+        for (const diagnostic of group)
+            for (const location of [diagnostic.location, ...(diagnostic.related ?? [])])
+                if (location !== undefined)
+                    locations.set(canonicalJson(location), location);
+        const samples = [...locations]
+            .sort(([left], [right]) => compareCodeUnits(left, right))
+            .slice(0, SAMPLE_LIMIT)
+            .map(([, location]) => location);
+        const operationIds = [
+            ...new Set(group.flatMap(({ operationId }) => (operationId === undefined ? [] : [operationId]))),
+        ].sort(compareCodeUnits);
+        return {
+            code: first.code,
+            severity: first.severity,
+            category: first.category,
+            message: `${occurrences} occurrences of ${first.code}; ${first.message}`.slice(0, 4096),
+            ...(samples[0] === undefined ? {} : { location: samples[0] }),
+            ...(samples.length < 2 ? {} : { related: samples.slice(1) }),
+            ...(operationIds.length === 1 ? { operationId: operationIds[0] } : {}),
+            details: {
+                rollup: 'repeated-soft-diagnostics.v1',
+                occurrenceCount: occurrences,
+                retainedSamples: Math.min(SAMPLE_LIMIT, group.length),
+                samples: group.slice(0, SAMPLE_LIMIT),
+                operationCount: operationIds.length,
+                operationIds: operationIds.slice(0, SAMPLE_LIMIT),
+                locationCount: locations.size,
+                ...(evidence === undefined ? {} : { completeDiagnosticEvidence: evidence }),
+            },
+        };
+    });
+    return sortDiagnostics([...hard, ...soft]);
+}

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

@@ -1,6 +1,7 @@
 import { boundedSourceHashEvidence, publicArtifactLink } from './artifacts.js';
 import { canonicalJson } from './canonical.js';
 import { exactChangedFilePatterns, focusDomainScanPatterns, mapChangeScanPatterns, } from './domain-scan-patterns.js';
+import { rollupRepeatedSoftDiagnostics } from './diagnostic-rollup.js';
 import { parseClausewitz } from './source/index.js';
 import { TRANSACTION_MAX_DIAGNOSTICS } from './transaction-limits.js';
 import { importContinuousFocusPalettes, importFocusTrees, layoutFocusTreeAsync, lintContinuousFocusPalette, lintFocusTree, } from '../focus/index.js';
@@ -158,6 +159,17 @@ export async function postValidateTransaction(engine, transaction, principal, si
             .slice(0, retainedLimit - retainedHard.length);
         const omittedHard = hard.length - retainedHard.length;
         const artifactLink = publicArtifactLink(artifact);
+        if (transaction.operationKind === 'agent-nudger-map-changes') {
+            const rolled = rollupRepeatedSoftDiagnostics(diagnostics, artifactLink);
+            if (rolled.length <= availableDiagnostics) {
+                checks.push({
+                    id: 'post-write-diagnostics-artifact',
+                    passed: true,
+                    message: `Complete bounded post-write diagnostics are stored at ${artifactLink.uri}`,
+                });
+                return { diagnostics: rolled, checks, artifacts: [artifactLink] };
+            }
+        }
         checks.push({
             id: 'post-write-diagnostics-artifact',
             passed: omittedHard === 0,

package/dist/hoi4_agent_tools/core/engine.js

@@ -10,6 +10,7 @@ import { RequestScheduler } from './request-scheduler.js';
 import { SharedRequestCapacity } from './shared-request-capacity.js';
 import { JobStore } from './job-store.js';
 import { ServiceError } from './result.js';
+import { TRANSACTION_MAX_JOURNAL_BYTES } from './transaction-limits.js';
 /**
  * Completed scans kept per workspace. One tool call often scans several pattern sets (a GUI
  * preview scans layouts, linked definitions and localisation), so a single slot made every
@@ -17,7 +18,7 @@ import { ServiceError } from './result.js';
  */
 const SCAN_CACHE_ENTRIES_PER_WORKSPACE = 4;
 const RECOVERY_TTL_SECONDS = 3_600;
-const RECOVERY_MAX_BYTES = 536_870_912;
+const RECOVERY_MAX_BYTES = TRANSACTION_MAX_JOURNAL_BYTES;
 const RECOVERY_MAX_RECORDS = 128;
 function abortReason(signal) {
     return signal.reason instanceof Error

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-executor.js

@@ -34,6 +34,8 @@ export class JobOperations {
             mutation: true,
             prepare: async (input, context) => {
                 const prepared = await prepare(schema.parse(input), context);
+                if ('readOnlyPreview' in prepared)
+                    return { readOnlyPreview: jsonObject.parse(prepared.readOnlyPreview) };
                 if (!('transaction' in prepared))
                     return { transaction: prepared };
                 return {
@@ -161,6 +163,13 @@ export class JobExecutor {
                     if (claimed.record.transaction !== undefined)
                         return writes.reconcile(workspaceId, id, owner.token, principal, undefined, true, (execution, reconciled, recipe) => operation.complete(initial.request.arguments, execution, reconciled, recipe, context));
                     const prepared = await operation.prepare(initial.request.arguments, context);
+                    if ('readOnlyPreview' in prepared) {
+                        controller.signal.throwIfAborted();
+                        return this.jobs.store.updateOwned(scope, id, owner.token, {
+                            status: 'completed',
+                            result: prepared.readOnlyPreview,
+                        });
+                    }
                     return writes.execute(workspaceId, id, owner.token, prepared.transaction, principal, controller.signal, prepared.recipe, (execution, reconciled, recipe) => operation.complete(initial.request.arguments, execution, reconciled, recipe, context));
                 }
                 const result = jsonObject.parse(await withAnalysisCheckpoints(jobAnalysisCheckpoints(context), () => operation.run(initial.request.arguments, context)));