hoi4-agent-tools 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -1,6 +1,35 @@
 # Changelog
 
-## Unreleased
+## 4.4.0 - 2026-10-24
+
+- Collect test fixtures that a killed or crashed test run left in the temporary folder: the test setup now also sweeps `hoi4-*` fixtures that carry an owner record of a process that has ended (`sweepTemporaryDirectories` option `ownedFixturesOnly`). Unmarked folders and folders of a live process are never removed. Interrupted local runs had left 2,441 such folders (640 MB).
+- Fix the province count of generated worlds (found by the map import campaign, ZR-4). Extra provinces in high and wet land were added on top of `landProvincePixels`, so reference worlds, whose terrain is wet, got 50 to 95% more land provinces than requested (18,000 to 23,000 instead of about 13,000); they now redistribute the requested size, and lakes are cut at the sea size. When neither province size is given and the land would still need more than 14,000 provinces, both sizes grow towards 13,000 (`MAP_WORLD_PROVINCE_SIZE_RAISED`); chosen sizes above 21,000 provinces are refused before generation (`MAP_PARTITION_PROVINCE_COUNT_HIGH`) instead of failing on a 23 MB `unitstacks.txt`. This changes the province partition, and with it every derived file, of every `create_world` for a seed.
+- Repair a coast that crosses the east-west seam by one pixel (`MAP_WORLD_SEAM_CORNER_REPAIRED`) instead of refusing the picture with `MAP_WORLD_UNREPRESENTABLE_TOPOLOGY`. `MAP_TEXT_FILE_LIMIT` and `MAP_TEXT_RECORD_LIMIT` now name the file.
+- Register a drawing made of sheets onto the world frame: `create_world.reference.sheets` or `reference.sheetsPath` (schema `reference-sheets.schema.json`, version 1) map each sheet with anchor, target and scale (negative to mirror) or an affine, with an optional clip and an order for overlaps (ADR 0067, step 2). The picture is read at the resolution the sheets need and every layer derives from the registered picture. New errors `MAP_REFERENCE_SHEETS_*` and `MAP_REFERENCE_SHEET_*` name the sheet, pixel count and position at fault.
+- Report import evidence for registered, frame-fitted or exact-palette references and for a picture beside a geography model: `map-import-report.json`, `map-import-classes.png`, `map-import-alignment.png`, `map-import-registration.png`, the inline `data.import` of a model preview, and the land agreement between model and picture (`reference.agreement`, defaults 0.85 to block with `MAP_IMPORT_SOURCES_DISAGREE` and 0.95 to warn), with model sites, volcanoes and river ends on the wrong surface (`MAP_IMPORT_FEATURE_SURFACE`). A model preview with a picture now also loads and registers the picture. Public schema change: new optional fields and one new published schema (minor version).
+- Add `create_world.reference.paletteMatch` (`nearest`, the default, or `exact`) and `reference.fit` (`contain`, the default, or `frame`) for pictures that are already the game layout, such as a cleaned class map (ADR 0067, step 1). `exact` classifies by exact palette colour, skips the visual heuristics and fails with `MAP_REFERENCE_PALETTE_UNKNOWN_COLOR` (colours, counts, source pixels) or `MAP_REFERENCE_PALETTE_CONFLICT`; `frame` maps the picture onto `width` x `height` at the frame resolution instead of the 3,072-pixel working copy and refuses another shape with `MAP_REFERENCE_FRAME_ASPECT`. Public schema change: new optional fields (minor version). Requests without them are unchanged.
+- Carry a whole-mod apply in one transaction (ZR-5): the file ceiling rises from 5,000 to 15,000 and the authenticated manifest ceiling from 16 to 32 MiB. Large applies replace files in batches that grow with the file count (16 files up to 1,024, at most 256), so the manifest is written about 128 times instead of twice per 16 files; ordinary rewrites are unchanged. `TRANSACTION_STRUCTURE_LIMIT` now names each exceeded limit and the remedy. See the amendment to ADR 0047.
+- Resolve `workspaceId: "current"` for sessions started outside every mod, such as a coding agent working in another repository or its subagents. When the client roots and the working directory identify no mod, the server now uses the new optional configuration key `defaultWorkspace`, then the only mod workspace, then the one mod that has the named source (`relativePath` of the focus tools, `path` of `hoi4.script_validate`). `WORKSPACE_CONTEXT_NOT_FOUND` and `WORKSPACE_CONTEXT_REQUIRED` now list up to 32 workspace IDs and names and say how to fix the call. A default outside a principal's grants is never used. See ADR 0066.
+- Security update: zod 4.6.7 (GHSA-mrhx-c7xc-m3w5, memory exhaustion when validating oversized constrained collections), body-parser 2.4.0, undici 8.12.3 and vite 8.2.4, so `npm audit --audit-level=high` passes again. The regenerated schemas now state the fixed tuple lengths the server already enforced (`items: false`, `minItems`, `maxItems`), and the scalar `anyOf` in `gui-helper.schema.json` became an equivalent type list. No accepted input changes. With zod 4.6, a JSON object key `__proto__` in a strictly validated input (such as a geography model) is refused as an unknown key; zod 4.4 dropped it silently. Neither version let it reach `Object.prototype`. The `qs` override moves from 6.16.0 to 6.16.1, which body-parser 2.4.0 requires.
+- Fix lakes in generated worlds (ADR 0053). Lake pixels are written at the sea height 89 with a one to two pixel bank instead of height 93, where the engine draws water only 56% opaque, and use the ocean's graphical terrain instead of index 14, whose `lakes` entry names no atlas tile (`texture = 255`). `buildWorldContext` never selects such an entry and reports it in `unrenderedTerrain`. Enclosed water below 60 pixels becomes land (`MAP_LAKE_TOO_SMALL`) and lake water that touches the open sea becomes sea (`MAP_LAKE_CONNECTED_TO_SEA`). The water colour maps now follow the base game (shelf-to-deep gradient, lake tint). This changes the heightmap, terrain bitmap and water colour maps of every `create_world` request that has lakes, so their file hashes change; provinces, states, countries and the other files are unchanged for a seed.
+- Add optional `create_world.look` (`vanilla-temperate`, `fertile`, `arid`, `custom`) and `colormap` (`profile`: `calibrated` or `legacy`, `palette`) for a dark, varied land colour map calibrated to the base game, permanent-snow tint, and farmland, sparse-forest and grassy-mountain terrain indices (ADR 0054). Without them the colour map is unchanged.
+- Add optional `create_world.edge` (`mode`: `sea-band`, `rim`, `none`; `bandPx`, `polarPx`, `rimPx`) and `ambientFrame` for the wrapping world seam and the north and south frame borders (ADR 0061), with the diagnostics `MAP_EDGE_LAND_CLEARED`, `MAP_EDGE_FEATURE_IN_BAND`, `MAP_EDGE_BAND_TOO_WIDE` and `MAP_EDGE_RIM_ADJACENCIES`. Without them nothing changes.
+- Validate the appearance files (`MAP_RIVER_*`, `MAP_TERRAIN_BITMAP_*`, `MAP_HEIGHT_*`, `MAP_TREES_*`, `MAP_COLORMAP_*`, `MAP_WATER_COLORMAP_FLAT`, `MAP_NORMAL_*`, `MAP_CITIES_*`, `MAP_LAKE_*`, `MAP_EDGE_LAND_CUT`, `MAP_SEAM_LAND_ADJACENCY`, `MAP_POLAR_LAND`) in `hoi4.map_inspect` and in every world being created. Thresholds are set so the installed base game raises no error. Existing mods can see new warnings; only a defect that covers a whole lake, river or file is an error.
+- Public schema change: new optional fields on `create_world` (minor version at release; the schemas are regenerated).
+- Add the geography model, version 1, as an optional input of `create_world`: `geography` (inline) or `geographyPath` (a workspace-relative `.json` file of at most 4 MiB, loaded with the canonical-path guard, a verified single read and a stale-source dependency like `reference.imagePath`). A strict, versioned schema describes seas, lands, regions, ranges, passes, volcanoes, plateaus, rivers, lakes, biomes, straits, sites, roads, places and climate in normalized world coordinates; `schemas/geography-model.schema.json` is published. The public `hoi4.map_rewrite` schema change is additive (a minor version).
+- Resolve the model deterministically (features sorted by id, rings oriented, defaults filled, areas, containment and cross-references derived, one canonical hash) and validate it with `MAP_GEOGRAPHY_*` diagnostics. `hoi4.map_rewrite` with `preview: true` returns `map-geography-overlay.png`, `map-geography-report.json` and a `data.geography` summary without planning any map. Without `preview`, a model is loaded and validated and the write is blocked with `MAP_GEOGRAPHY_SYNTHESIS_UNAVAILABLE` until relief, hydrology and biome synthesis exist. See ADR 0055.
+- Measure border naturalness. `hoi4.map_inspect` accepts `quality: true` (full inspection) and returns `data.quality` for the province, state, strategic-region and country borders: alignment with rivers, steep gradients, lake shores and terrain-class changes, enrichment over chance, the plain natural share of border length, locally straight samples, long straight runs and the worst artificial runs, with the artifact `map-border-quality.<revision>.json` and the diagnostics `MAP_BORDER_ARTIFICIAL_REVIEW`, `MAP_BORDER_NOT_MEANINGFUL`, `MAP_BORDER_INPUT_MISSING` and `MAP_BORDER_QUALITY_UNAVAILABLE` (none fail validation). The new `border-quality` overlay draws natural and artificial state borders and the worst runs. Both are additive and optional, so existing requests are unchanged (compatibility review: new optional input field, new overlay value and new optional output field; next release is a minor version). See ADR 0059.
+- Add the opt-in feature-aware partition for `create_world` (ADR 0058): `partition: "feature-aware"` (default `legacy`, which keeps every old request byte-identical; a world given a geography defaults to feature-aware) cuts provinces along rivers, ridges, steep slopes, wall ranges and shores with a watershed, sizes them by terrain, fertility, coast, rivers and the geography region's density (sea provinces small on the shelf, large in the open sea, two sea provinces across a narrow strait), and clusters states and strategic regions along natural lines, geography regions and named seas. The optional `partitionTuning` (`landArea`, `seaArea`, `provincesPerState`, `regionSize`, `barrierStrength`, `minProvincePixels`, `narrowStraitPx`) sets the bands. New diagnostics `MAP_PARTITION_*`: contradictory bands, a map too small for the minimum province, `partitionTuning` with `legacy`, a plan above 21,000 provinces (also names the fields to change, closing the late `MAP_TEXT_FILE_LIMIT` failure for this partition), a warning above 14,000 provinces for both partitions, and info notes for provinces cut along rivers and straits and for coast pixels adjusted at diagonal contacts. The reusable service (`partitionWorld`, `buildProvinceGraph`, `provinceEdgeCosts`, `partitionFieldsFromBitmaps`, `partitionFieldsFromGeography`) takes a typed `PartitionFields` input that the relief and hydrology stages will also fill. For a geography world the partition reads the model's regions, named seas, region densities (`provinceAreaPx`, `provincesPerState`) and wall ranges, the synthesised heights and the walls, fort lines and crests of the synthesis barrier field, so states and strategic regions stay inside one geography region and no province straddles a wall; the mask smoothing runs before the synthesis there, so a coast pixel turned to land gets a land height. The terrain synthesis and the feature-aware partition stop when the request is cancelled. Public schema change: new optional fields on `create_world` (minor version at release; the schemas are regenerated). Compatibility review: the partition adds optional inputs only and no output schema field; the output schema change of this release is the additive `synthesis` and `unsupported` fields of the model preview (below). Responses can change without a schema change: a `create_world` above 14,000 provinces now carries the `MAP_PARTITION_PROVINCE_COUNT_HIGH` warning with the legacy partition too, while its files stay byte-identical.
+
+- Synthesize relief and rivers from a geography model (ADR 0056). `create_world` with `geography` or `geographyPath` now builds the land, `heightmap.bmp`, `world_normal.bmp`, `rivers.bmp` and the permanent-snow terrain from the model instead of being blocked: ranges as ridge, massif, escarpment and wall profiles with asymmetry, spurs, passes and snow lines, volcanoes with craters, plateaus and chasms, fractal base relief and coast ramps, on a half-size macro grid with full-resolution detail; erosion-aware rivers (priority-flood conditioning, named rivers routed as least-cost paths with bends, tributaries, deltas and lake outlets, an accumulation network at a target density, stream-power valleys, widths by catchment from 3 to 11) written as one-pixel orthogonal paths with a green source per river, red tributary ends and yellow distributary starts; the normal map from the float height field at the base game's response. A request without a geography is unchanged, byte for byte.
+- Add optional `create_world.relief` (`scale`: `vanilla`, `low`, `dramatic`; `detail` 0 to 1) and let `create_world.rivers` be `{ density }` (share of land pixels, default 0.02, at most 2.5% of land or 130,000 pixels) as well as an integer; with a geography an integer limits the unnamed river systems. Both need a geography (`MAP_RELIEF_REQUIRES_GEOGRAPHY`, `MAP_RIVER_DENSITY_REQUIRES_GEOGRAPHY`). A model that declares biomes, climate, fertility, region terrain shares or sea ice is still blocked with `MAP_GEOGRAPHY_SYNTHESIS_UNAVAILABLE`, whose message and details now name those parts; the model preview's `data.geography[].synthesis` is `available` or `unavailable` and `unsupported` lists the parts.
+- New generation-time diagnostics for geography worlds: `MAP_RELIEF_SYNTHESIZED` (statistics and the first named rivers), `MAP_PASS_NOT_LOWER` and `MAP_RIVER_UNREACHABLE_MOUTH` (errors), `MAP_RANGE_CREST_LOW`, `MAP_VOLCANO_NO_CRATER`, `MAP_RELIEF_FLAT`, `MAP_RIVER_STRAIGHT_RUN`, `MAP_RIVER_DENSITY`, `MAP_RIVER_PIXEL_ROUTE_INCOMPLETE` (warnings), `MAP_LAKE_ENDORHEIC`, `MAP_RIVER_STREAMS_DROPPED` and `MAP_RIVER_DELTA_SKIPPED` (info). The result also carries typed barrier, valley, crest-distance and mountain fields for the feature-aware partition (documented in the ADR).
+- Public schema change: new optional field `relief` and a union type for `rivers` on `create_world`, and the new output fields `synthesis` (now `available` or `unavailable`) and `unsupported` in the model preview summary (minor version at release; the schemas are regenerated).
+
+## 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
 

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

@@ -10,6 +10,10 @@ import { TemporaryDirectoryLifetime, sweepTemporaryDirectories } from './tempora
 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;
+/** Ceilings for a working copy sized to an output frame instead of the default side limit. */
+export const REFERENCE_FRAME_WORKING_MAX_PIXELS = 32_000_000;
+// A noisy drawing barely compresses: allow four bytes per pixel (RGBA) and the PNG overhead.
+export const REFERENCE_FRAME_WORKING_MAX_BYTES = REFERENCE_FRAME_WORKING_MAX_PIXELS * 4 + 1_048_576;
 function supportedRasterHeader(bytes) {
     return ((bytes.length >= 8 &&
         [137, 80, 78, 71, 13, 10, 26, 10].every((value, index) => bytes[index] === value)) ||
@@ -109,7 +113,7 @@ async function removePrivateSnapshot(snapshot) {
     }
 }
 /** Decode a private snapshot copied and hashed from the same verified FD, using fixed memory. */
-export async function readReferenceImageSource(resolver, workspaceId, relativePath, principal, signal) {
+export async function readReferenceImageSource(resolver, workspaceId, relativePath, principal, signal, working) {
     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);
@@ -162,18 +166,36 @@ export async function readReferenceImageSource(resolver, workspaceId, relativePa
             !['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,
-        })
+        const requested = working?.size(metadata.width, metadata.height);
+        if (requested !== undefined &&
+            (!Number.isSafeInteger(requested.width) ||
+                !Number.isSafeInteger(requested.height) ||
+                requested.width < 1 ||
+                requested.height < 1 ||
+                Math.min(requested.width, metadata.width) * Math.min(requested.height, metadata.height) >
+                    REFERENCE_FRAME_WORKING_MAX_PIXELS))
+            throw new ServiceError('REFERENCE_WORKING_PIXEL_LIMIT', 'Reference working copy for this frame exceeds its pixel limit', { limit: REFERENCE_FRAME_WORKING_MAX_PIXELS });
+        const decoded = await (requested === undefined
+            ? input.resize({
+                width: REFERENCE_WORKING_MAX_SIDE,
+                height: REFERENCE_WORKING_MAX_SIDE,
+                fit: 'inside',
+                withoutEnlargement: true,
+            })
+            : requested.width >= metadata.width && requested.height >= metadata.height
+                ? input
+                : input.resize({
+                    width: Math.min(requested.width, metadata.width),
+                    height: Math.min(requested.height, metadata.height),
+                    fit: 'fill',
+                    kernel: working?.kernel === 'nearest' ? sharp.kernel.nearest : sharp.kernel.lanczos3,
+                }))
             .png()
             .toBuffer({ resolveWithObject: true });
         await verifySource(resolved.root, source);
         signal?.throwIfAborted();
-        if (decoded.data.length > REFERENCE_WORKING_MAX_BYTES)
+        if (decoded.data.length >
+            (working === undefined ? REFERENCE_WORKING_MAX_BYTES : REFERENCE_FRAME_WORKING_MAX_BYTES))
             throw new ServiceError('REFERENCE_WORKING_BYTE_LIMIT', 'Reference working image exceeds its byte limit');
         return {
             source: {

package/dist/hoi4_agent_tools/core/configuration.js

@@ -192,6 +192,17 @@ export const serverConfigurationSchema = z
     workspaceStorageRoot: z.string().min(1).optional(),
     storageRoots: z.array(z.string().min(1)).max(WORKSPACE_MAX_SOURCE_ROOTS).default([]),
     workspaces: z.array(workspaceRegistrationSchema).max(WORKSPACE_MAX_REGISTRATIONS).default([]),
+    /**
+     * The mod workspace (ID or short form) used when neither the client roots nor the working
+     * directory identify one. Over HTTP it applies only to principals granted that workspace.
+     */
+    defaultWorkspace: z
+        .string()
+        .regex(/^[a-z][a-z0-9_-]{0,63}$/u)
+        .refine((value) => value !== 'current', {
+        message: 'The default workspace must name a workspace, not "current"',
+    })
+        .optional(),
     http: z
         .object({
         host: z.string().default('127.0.0.1'),

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/operation-context.js

@@ -7,7 +7,23 @@ export async function resolveOperationWorkspaceId(engine, context, workspaceId,
     return engine.resolver.resolveWorkspaceId(workspaceId, context.principal);
 }
 export async function resolveOperationWorkspaceForSource(engine, context, workspaceId, relativePath, signal) {
-    const resolvedWorkspaceId = await resolveOperationWorkspaceId(engine, context, workspaceId, signal);
+    let resolvedWorkspaceId;
+    try {
+        resolvedWorkspaceId = await resolveOperationWorkspaceId(engine, context, workspaceId, signal);
+    }
+    catch (error) {
+        // A session outside every mod still names its mod through a source only one mod has.
+        if (workspaceId !== 'current' ||
+            relativePath === undefined ||
+            !(error instanceof ServiceError) ||
+            !['WORKSPACE_CONTEXT_NOT_FOUND', 'WORKSPACE_CONTEXT_REQUIRED'].includes(error.code)) {
+            throw error;
+        }
+        const unique = await engine.resolver.resolveUniqueModSourceWorkspaceId(relativePath, context.principal, signal);
+        if (unique === undefined)
+            throw error;
+        return unique;
+    }
     if (workspaceId !== 'current' || relativePath === undefined)
         return resolvedWorkspaceId;
     try {

package/dist/hoi4_agent_tools/core/temporary-directories.js

@@ -11,6 +11,7 @@ export const TEMPORARY_STALE_MS = 3 * 60 * 60 * 1000;
 // Dated event evaluation directories contain retained benchmark evidence, not scratch files.
 const scratchName = /^hoi4-(?:reference-source|event-eval)-[A-Za-z0-9]{6}$/u;
 const referenceSnapshotName = /^\.reference-snapshot-[A-Za-z0-9]{6}$/u;
+const ownedFixtureName = /^hoi4-[a-z0-9-]{1,64}-[A-Za-z0-9]{6}$/u;
 const ownerSchema = z
     .object({
     version: z.literal(1),
@@ -101,7 +102,11 @@ export async function sweepTemporaryDirectories(parent, options = {}) {
         }
     }))).flat();
     const candidates = [];
-    const names = options.referenceSnapshotsOnly ? referenceSnapshotName : scratchName;
+    const names = options.referenceSnapshotsOnly
+        ? referenceSnapshotName
+        : options.ownedFixturesOnly
+            ? ownedFixtureName
+            : scratchName;
     for (const name of (await readdir(root)).filter((name) => names.test(name)).sort()) {
         const directory = path.join(root, name);
         if (protectedRoots.some((protectedRoot) => overlaps(directory, protectedRoot)))
@@ -114,7 +119,7 @@ export async function sweepTemporaryDirectories(parent, options = {}) {
                 (await realpath(directory)) !== directory)
                 continue;
             const record = await owner(directory);
-            if (options.referenceSnapshotsOnly && record == null)
+            if ((options.referenceSnapshotsOnly || options.ownedFixturesOnly) && record == null)
                 continue;
             // An interrupted sweep must not leave a permanent lock. Malformed or live locks
             // stay protected; only a confirmed dead local owner can relinquish its lock.

package/dist/hoi4_agent_tools/core/transaction-limits.js

@@ -1,13 +1,27 @@
-// A generated world can contain thousands of state/region files. Review collections
-// remain bounded independently of the unchanged 16 MiB authenticated manifest cap.
-export const TRANSACTION_MAX_FILES = 5_000;
+// A generated world holds thousands of state and region files, and a whole-mod content apply
+// (ADR 0047 amendment) more than 8,000; a manifest entry is about 1 KB, so 15,000 files fit
+// the 32 MiB authenticated manifest cap with room for longer paths.
+export const TRANSACTION_MAX_FILES = 15_000;
 export const TRANSACTION_MAX_OPERATIONS = 1_000;
 export const TRANSACTION_MAX_VALIDATION_CHECKS = 100;
 export const TRANSACTION_MAX_DIAGNOSTICS = 100;
 export const TRANSACTION_MAX_ARTIFACTS = 6_000;
 export const TRANSACTION_MAX_APPLIED_FILES = TRANSACTION_MAX_FILES;
 export const TRANSACTION_MAX_READ_DEPENDENCIES = 10_000;
-export const TRANSACTION_MAX_MANIFEST_BYTES = 16_777_216;
+export const TRANSACTION_MAX_MANIFEST_BYTES = 33_554_432;
+/** Smallest replacement batch: one intent and one checkpoint manifest write per batch. */
 export const TRANSACTION_MAX_PENDING_FILES = 16;
+/** Large transactions use bigger batches, so they write the manifest about this many times. */
+export const TRANSACTION_TARGET_BATCHES = 64;
+/** Largest replacement batch, bounding the identity checks one intent records. */
+export const TRANSACTION_MAX_BATCH_FILES = 256;
+/**
+ * Files per replacement batch. Every batch rewrites the whole manifest twice, and the manifest
+ * grows with the file count, so fixed batches made large applies quadratic; up to 1,024 files
+ * the batch stays at 16 as before.
+ */
+export function transactionBatchSize(files) {
+    return Math.min(TRANSACTION_MAX_BATCH_FILES, Math.max(TRANSACTION_MAX_PENDING_FILES, Math.ceil(files / TRANSACTION_TARGET_BATCHES)));
+}
 // A maximum-size world needs before/after blobs plus staging and rollback copies.
 export const TRANSACTION_MAX_JOURNAL_BYTES = 1_073_741_824;

package/dist/hoi4_agent_tools/core/transactions.js

@@ -10,7 +10,7 @@ import { hashSourceBytes, prepareSource, verifySource } from './scanner.js';
 import { ServiceError } from './result.js';
 import { decodeSource } from './source/encoding.js';
 import { containedGeneratedPath, isWithin, resolvedWorkspaceIdentity } from './workspace.js';
-import { TRANSACTION_MAX_ARTIFACTS, TRANSACTION_MAX_DIAGNOSTICS, TRANSACTION_MAX_FILES, TRANSACTION_MAX_JOURNAL_BYTES, TRANSACTION_MAX_MANIFEST_BYTES, TRANSACTION_MAX_OPERATIONS, TRANSACTION_MAX_PENDING_FILES, TRANSACTION_MAX_READ_DEPENDENCIES, TRANSACTION_MAX_VALIDATION_CHECKS, } from './transaction-limits.js';
+import { TRANSACTION_MAX_ARTIFACTS, TRANSACTION_MAX_DIAGNOSTICS, TRANSACTION_MAX_FILES, TRANSACTION_MAX_JOURNAL_BYTES, TRANSACTION_MAX_MANIFEST_BYTES, TRANSACTION_MAX_OPERATIONS, transactionBatchSize, TRANSACTION_MAX_READ_DEPENDENCIES, TRANSACTION_MAX_VALIDATION_CHECKS, } from './transaction-limits.js';
 import { PACKAGE_VERSION, TRANSACTION_VERSION } from '../version.js';
 import { transactionManifestSchema } from '../schemas/transaction.js';
 import { TransactionCanonicalSnapshot } from './transaction-canonical.js';
@@ -220,7 +220,24 @@ export class TransactionManager {
             (input.readDependencies?.length ?? 0) > TRANSACTION_MAX_READ_DEPENDENCIES ||
             (input.artifacts?.length ?? 0) > TRANSACTION_MAX_ARTIFACTS ||
             (input.diagnostics?.length ?? 0) > TRANSACTION_MAX_DIAGNOSTICS) {
-            throw new ServiceError('TRANSACTION_STRUCTURE_LIMIT', 'Transaction input exceeds the supported review structure limits', {
+            const exceeded = [
+                input.changes.length > TRANSACTION_MAX_FILES
+                    ? `${input.changes.length} files (limit ${TRANSACTION_MAX_FILES})`
+                    : '',
+                input.operations.length > TRANSACTION_MAX_OPERATIONS
+                    ? `${input.operations.length} operations (limit ${TRANSACTION_MAX_OPERATIONS})`
+                    : '',
+                (input.readDependencies?.length ?? 0) > TRANSACTION_MAX_READ_DEPENDENCIES
+                    ? `${input.readDependencies?.length} read dependencies (limit ${TRANSACTION_MAX_READ_DEPENDENCIES})`
+                    : '',
+                (input.artifacts?.length ?? 0) > TRANSACTION_MAX_ARTIFACTS
+                    ? `${input.artifacts?.length} artifacts (limit ${TRANSACTION_MAX_ARTIFACTS})`
+                    : '',
+                (input.diagnostics?.length ?? 0) > TRANSACTION_MAX_DIAGNOSTICS
+                    ? `${input.diagnostics?.length} diagnostics (limit ${TRANSACTION_MAX_DIAGNOSTICS})`
+                    : '',
+            ].filter((entry) => entry.length > 0);
+            throw new ServiceError('TRANSACTION_STRUCTURE_LIMIT', `Transaction input exceeds the supported review structure limits: ${exceeded.join(', ')}. Combine operations into fewer entries, or split the change into transactions under the limits`, {
                 files: input.changes.length,
                 filesLimit: TRANSACTION_MAX_FILES,
                 operations: input.operations.length,
@@ -518,7 +535,8 @@ export class TransactionManager {
                         'integrityHash',
                         'authenticationTag',
                     ]);
-                    const batchSize = manifest.version >= 2 ? TRANSACTION_MAX_PENDING_FILES : 1;
+                    const batchSize = manifest.version >= 2 ? transactionBatchSize(manifest.files.length) : 1;
+                    let pendingByPath;
                     for (let offset = 0; offset < manifest.files.length; offset += batchSize) {
                         const batch = manifest.files.slice(offset, offset + batchSize);
                         if (manifest.version >= 2) {
@@ -543,6 +561,7 @@ export class TransactionManager {
                                 return entry.value;
                             });
                             await this.writeManifest(workspace, manifest, options.hooks, canonicalSnapshot);
+                            pendingByPath = new Map(manifest.pendingFiles.map((pending) => [pending.relativePath, pending]));
                             await options.hooks?.afterBatchIntent?.(batch.map(({ relativePath }) => relativePath), offset / batchSize);
                         }
                         for (const [batchIndex, file] of batch.entries()) {
@@ -559,7 +578,7 @@ export class TransactionManager {
                             if (actualBeforeReplace !== file.beforeSha256) {
                                 throw new ServiceError('TRANSACTION_STALE', 'Source changed while transaction output was being staged');
                             }
-                            const pending = manifest.pendingFiles?.find(({ relativePath }) => relativePath === file.relativePath);
+                            const pending = pendingByPath?.get(file.relativePath);
                             if (pending !== undefined &&
                                 (!sameFileIdentity(await fileIdentity(target.target), pending.beforeIdentity) ||
                                     !sameFileIdentity(target.staged === null ? null : await fileIdentity(target.staged), pending.stagedIdentity))) {

package/dist/hoi4_agent_tools/core/workspace-json.js

@@ -0,0 +1,54 @@
+import { sha256Bytes } from './canonical.js';
+import { ServiceError } from './result.js';
+import { prepareSource, readBoundedFile, verifySource } from './scanner.js';
+/**
+ * Read one JSON document from the authorized mod workspace: workspace-relative `.json` only,
+ * resolved against the principal's grants, opened once, size-bounded, hashed from the very bytes
+ * that are parsed and re-verified against the opened identity afterwards. The evidence is a
+ * transaction read dependency, so a changed file blocks a write as stale. The caller validates
+ * the parsed value with its own schema.
+ */
+export async function readWorkspaceJsonSource(resolver, workspaceId, requestedPath, maxBytes, codes, principal, signal) {
+    // Backslashes separate directories on every platform, so a request resolves the same everywhere.
+    const relativePath = requestedPath.replaceAll('\\', '/');
+    if (!/\.json$/iu.test(relativePath) || relativePath.includes(':'))
+        throw new ServiceError(codes.pathInvalid, `${codes.label} must name a workspace-relative .json file`);
+    const resolved = await resolver.resolvePath(workspaceId, relativePath, 'read', ['mod'], principal);
+    const source = await prepareSource(resolved.root, relativePath, signal);
+    try {
+        if (!source.metadata.isFile())
+            throw new ServiceError('SOURCE_NOT_REGULAR_FILE', `${codes.label} must be a regular file`);
+        if (source.metadata.size < 1 || source.metadata.size > maxBytes)
+            throw new ServiceError(codes.tooLarge, `${codes.label} must hold between 1 byte and ${maxBytes} bytes`, { limit: maxBytes });
+        const bytes = await readBoundedFile(source.handle, maxBytes, signal);
+        await verifySource(resolved.root, source);
+        const sha256 = sha256Bytes(bytes);
+        let text = bytes.toString('utf8');
+        if (text.charCodeAt(0) === 0xfeff)
+            text = text.slice(1);
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            throw new ServiceError(codes.jsonInvalid, `${codes.label} is not valid JSON`);
+        }
+        return {
+            value,
+            bytes: bytes.length,
+            evidence: {
+                absolutePath: source.canonicalPath,
+                displayPath: `mod:${relativePath}`,
+                relativePath,
+                rootKind: resolved.root.kind,
+                loadOrder: resolved.root.loadOrder,
+                size: source.metadata.size,
+                modifiedMs: source.metadata.mtimeMs,
+                sha256,
+            },
+        };
+    }
+    finally {
+        await source.handle.close();
+    }
+}

package/dist/hoi4_agent_tools/core/workspace.js

@@ -207,6 +207,17 @@ function workspaceAliases(workspace) {
         `mod_${nameSlug}`,
     ]);
 }
+const WORKSPACE_CONTEXT_FIX = 'Pass workspaceId with one of the listed IDs or the mod folder name, start the client in the mod folder, or set defaultWorkspace in the server configuration';
+const WORKSPACE_CANDIDATE_LIMIT = 32;
+/** The mods a caller could name, bounded and without host paths. */
+function workspaceCandidates(workspaces) {
+    const listed = workspaces.slice(0, WORKSPACE_CANDIDATE_LIMIT);
+    return {
+        workspaceIds: listed.map(({ id }) => id),
+        workspaceNames: listed.map(({ name }) => name),
+        workspaceCount: workspaces.length,
+    };
+}
 function requestedWorkspaceAlias(value) {
     const staleDiscovered = /^mod_(.+)_[a-f0-9]{12}$/u.exec(value);
     return staleDiscovered?.[1] ?? value;
@@ -297,6 +308,7 @@ export class WorkspaceResolver {
     #workspaceStorageRoot;
     #serverStateRoot;
     #serverState;
+    #defaultWorkspaceId;
     constructor(configuration) {
         this.configuration = configuration;
     }
@@ -351,6 +363,13 @@ export class WorkspaceResolver {
             resolver.#byId.set(workspace.id, workspace);
         }
         await resolver.discoverModWorkspaces();
+        if (configuration.defaultWorkspace !== undefined) {
+            const id = resolver.resolveWorkspaceId(configuration.defaultWorkspace);
+            if (resolver.#byId.get(id)?.registration.kind !== 'mod') {
+                throw new ServiceError('WORKSPACE_DEFAULT_UNKNOWN', `The configured default workspace is not a registered mod workspace: ${configuration.defaultWorkspace}`, { defaultWorkspace: configuration.defaultWorkspace });
+            }
+            resolver.#defaultWorkspaceId = id;
+        }
         if (configuration.serverStateRoot !== undefined) {
             resolver.#serverState = await ServerState.create(configuration.serverStateRoot);
             resolver.#serverStateRoot = resolver.#serverState.root;
@@ -373,22 +392,39 @@ export class WorkspaceResolver {
         if (containing.length > 1) {
             throw new ServiceError('WORKSPACE_CONTEXT_AMBIGUOUS', 'The MCP working directory is inside more than one writable mod workspace', { currentDirectory });
         }
-        if (workspaces.length === 1)
-            return workspaces[0].id;
-        throw new ServiceError('WORKSPACE_CONTEXT_REQUIRED', 'The MCP working directory does not identify one writable mod workspace', { currentDirectory, workspaceIds: workspaces.map(({ id }) => id) });
+        const fallback = this.fallbackWorkspaceId(workspaces);
+        if (fallback !== undefined)
+            return fallback;
+        throw new ServiceError('WORKSPACE_CONTEXT_REQUIRED', `The MCP working directory does not identify one writable mod workspace. ${WORKSPACE_CONTEXT_FIX}`, { currentDirectory, ...workspaceCandidates(workspaces) });
     }
     /** Resolve the active mod from filesystem roots advertised by the connected MCP client. */
     async resolveClientWorkspaceId(rootPaths, principal) {
         const canonicalRoots = await Promise.all(rootPaths.map((rootPath) => canonicalPath(rootPath)));
-        const matches = this.list(principal).filter((workspace) => workspace.registration.kind === 'mod' &&
-            canonicalRoots.some((rootPath) => isWithin(workspace.modRoot, rootPath) || isWithin(rootPath, workspace.modRoot)));
+        const workspaces = this.list(principal).filter(({ registration }) => registration.kind === 'mod');
+        const matches = workspaces.filter((workspace) => canonicalRoots.some((rootPath) => isWithin(workspace.modRoot, rootPath) || isWithin(rootPath, workspace.modRoot)));
         if (matches.length === 1)
             return matches[0].id;
         if (matches.length === 0) {
-            throw new ServiceError('WORKSPACE_CONTEXT_NOT_FOUND', 'The active MCP client roots do not identify a registered HOI4 mod workspace');
+            const fallback = this.fallbackWorkspaceId(workspaces);
+            if (fallback !== undefined)
+                return fallback;
+            throw new ServiceError('WORKSPACE_CONTEXT_NOT_FOUND', workspaces.length === 0
+                ? 'No writable mod workspace is configured for the MCP server'
+                : `The active MCP client roots do not identify a registered HOI4 mod workspace. ${WORKSPACE_CONTEXT_FIX}`, workspaceCandidates(workspaces));
         }
         throw new ServiceError('WORKSPACE_CONTEXT_AMBIGUOUS', 'The active MCP client roots identify more than one HOI4 mod workspace', { workspaceIds: matches.map(({ id }) => id) });
     }
+    /**
+     * The mod used when neither the client roots nor the working directory name one: the
+     * configured default when the caller may use it, else the only mod the caller can see.
+     */
+    fallbackWorkspaceId(workspaces) {
+        if (this.#defaultWorkspaceId !== undefined &&
+            workspaces.some(({ id }) => id === this.#defaultWorkspaceId)) {
+            return this.#defaultWorkspaceId;
+        }
+        return workspaces.length === 1 ? workspaces[0].id : undefined;
+    }
     /** Find one mod containing an existing source path when a stale client root selected another mod. */
     async resolveUniqueModSourceWorkspaceId(relativePath, principal, signal) {
         const matches = [];

package/dist/hoi4_agent_tools/decision/service.js

@@ -99,20 +99,7 @@ export class DecisionAnalyzer {
                 }));
         const ai = input.mode === 'inventory'
             ? undefined
-            : await inspectDecisionAi(this.engine, before, input.id, scenarios, overlay, input.principal, input.signal).catch((error) => {
-                // AI weights depend on adapters verified for one game version. A game patch leaves
-                // the AI score unresolved; visibility, availability and cost evidence still stand.
-                if (error instanceof ServiceError &&
-                    (error.code === 'PROBABILITY_GAME_VERSION_UNSUPPORTED' ||
-                        error.code === 'PROBABILITY_GAME_VERSION_UNVERIFIED'))
-                    return {
-                        status: 'unresolved',
-                        code: error.code,
-                        message: error.message,
-                        details: error.details,
-                    };
-                throw error;
-            });
+            : await inspectDecisionAi(this.engine, before, input.id, scenarios, overlay, input.principal, input.signal);
         const sourceComplete = input.mode === 'inventory'
             ? inventory.complete
             : input.mode === 'compare'
@@ -193,14 +180,6 @@ export class DecisionAnalyzer {
                 : {}),
         });
         result.code = complete ? 'DECISION_ANALYZED' : 'DECISION_ANALYZED_PARTIAL';
-        if (ai !== undefined && 'code' in ai)
-            result.diagnostics.push({
-                category: 'configuration',
-                code: ai.code,
-                severity: 'warning',
-                message: `${ai.message}; AI weights are unresolved, the remaining evidence is unaffected`,
-                details: ai.details,
-            });
         result.artifacts = [publicArtifactLink(artifact)];
         result.proposedFiles = overlay?.changes.map(({ path }) => path).slice(0, 64) ?? [];
         setInlineFilesScanned(result, before.files.map(({ displayPath }) => displayPath));

package/dist/hoi4_agent_tools/event/graph.js

@@ -1383,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);
     }

package/dist/hoi4_agent_tools/event/service.js

@@ -3,6 +3,7 @@ import { inspectHelperExpansion } from '../core/helper-expansion.js';
 import { eventHelperInventory } from './helper-expansion.js';
 import { clearSemanticDependencies } from '../core/semantic-dependencies.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';
@@ -714,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);
@@ -757,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,
@@ -1321,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,