hoi4-agent-tools 3.7.0 → 3.8.1

package/dist/hoi4_agent_tools/core/transactions.js

@@ -599,10 +599,19 @@ export class TransactionManager {
                 continue;
             const manifest = await this.load(workspace, entry.name, {
                 headMode: 'none',
+                rootBinding: 'ignored',
                 ...(signal === undefined ? {} : { signal }),
             });
             this.assertRecoveryPrincipal(manifest, principal);
             const interrupted = manifest.state === 'applying' || manifest.state === 'rolling_back';
+            if (manifest.rootFingerprint !== this.rootFingerprint(workspace)) {
+                // A finished journal recorded before the roots changed, for example before an
+                // installed DLC folder became a source layer, needs no recovery and must not stop
+                // the server. An interrupted one still cannot be replayed against changed roots.
+                if (interrupted)
+                    throw new ServiceError('TRANSACTION_ROOT_CHANGED', 'Workspace root configuration changed after planning');
+                continue;
+            }
             if (!interrupted) {
                 try {
                     // Ordinary startup must not contend with a live writer just to read terminal journals.
@@ -842,6 +851,25 @@ export class TransactionManager {
                 continue;
             }
             let manifest;
+            try {
+                const recorded = await this.load(workspace, entry.name, {
+                    headMode: 'none',
+                    rootBinding: 'ignored',
+                });
+                if (recorded.rootFingerprint !== this.rootFingerprint(workspace)) {
+                    // Journals from earlier roots can no longer be applied or rolled back here. Once a
+                    // finished one expires, remove it so it stops counting against the journal quota.
+                    if (['planned', 'applied', 'rolled_back', 'failed'].includes(recorded.state) &&
+                        Date.parse(recorded.expiresAt) <= now) {
+                        this.removeManifestByteCache(this.manifestCacheKey(workspace, entry.name));
+                        await rm(directory, { recursive: true, force: true });
+                    }
+                    continue;
+                }
+            }
+            catch {
+                // Unreadable journals keep their previous handling below.
+            }
             try {
                 manifest = await this.load(workspace, entry.name, { headMode: 'reconcile' });
             }
@@ -1056,7 +1084,7 @@ export class TransactionManager {
         await hooks?.afterProtectedHeadCommit?.();
     }
     async load(workspace, transactionId, options = {}) {
-        const { headMode = 'verify', signal, cacheBytes = false } = options;
+        const { headMode = 'verify', signal, cacheBytes = false, rootBinding = 'required' } = options;
         signal?.throwIfAborted();
         let manifestText;
         let manifestPath;
@@ -1110,7 +1138,8 @@ export class TransactionManager {
         if (manifest.transactionId !== transactionId || manifest.workspaceId !== workspace.id) {
             throw new ServiceError('TRANSACTION_WORKSPACE_MISMATCH', 'Transaction manifest identity does not match its workspace or journal directory');
         }
-        if (manifest.rootFingerprint !== this.rootFingerprint(workspace)) {
+        if (rootBinding === 'required' &&
+            manifest.rootFingerprint !== this.rootFingerprint(workspace)) {
             throw new ServiceError('TRANSACTION_ROOT_CHANGED', 'Workspace root configuration changed after planning');
         }
         if (hashCanonical(manifestIntegrityPayload(manifest)) !== manifest.integrityHash) {

package/dist/hoi4_agent_tools/core/windows-sharing.js

@@ -0,0 +1,42 @@
+import { setTimeout as delay } from 'node:timers/promises';
+/**
+ * Error codes Windows reports while another handle blocks a replacement, or while a
+ * removed name is still delete-pending. Other platforms never retry them.
+ */
+const sharingCodes = new Set(['EPERM', 'EBUSY', 'EACCES']);
+/** Backoff before retry `attempt + 1`: 5, 10, 20, 40, 80, then 100 milliseconds. */
+export function sharingRetryDelay(attempt) {
+    return Math.min(100, 5 * 2 ** Math.min(attempt - 1, 5));
+}
+export function isWindowsSharingViolation(error, platform = process.platform) {
+    return (platform === 'win32' &&
+        typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        typeof error.code === 'string' &&
+        sharingCodes.has(error.code));
+}
+/**
+ * Retry one idempotent filesystem step while Windows reports a transient sharing
+ * violation. Concurrent readers, indexers, and scanners hold short-lived handles that
+ * make rename, unlink, and open fail without any persistent permission problem.
+ * The final error is rethrown unchanged once the bounded attempts are spent.
+ */
+export async function retryWindowsSharing(operation, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const wait = options.wait ?? delay;
+    const maxAttempts = options.maxAttempts ?? 200;
+    if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1)
+        throw new RangeError('Sharing-violation retry attempts must be a positive integer');
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (!isWindowsSharingViolation(error, platform) || attempt >= maxAttempts)
+                throw error;
+            options.signal?.throwIfAborted();
+            await wait(sharingRetryDelay(attempt));
+        }
+    }
+}

package/dist/hoi4_agent_tools/core/workspace.js

@@ -1,11 +1,94 @@
-import { lstat, mkdir, opendir, realpath } from 'node:fs/promises';
+import { lstat, mkdir, opendir, readFile, readdir, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { WORKSPACE_MAX_REGISTRATIONS, workspaceRegistrationSchema, } from './configuration.js';
 import { compareCodeUnits, hashCanonical, sha256Bytes } from './canonical.js';
 import { ServiceError } from './result.js';
 import { ServerState } from './server-state.js';
+import { parseClausewitz } from './source/parser.js';
 /** Omitted MCP workspace arguments resolve to the mod containing the server cwd. */
 export const CURRENT_WORKSPACE_ID = 'current';
+const DLC_CONTAINERS = ['dlc', 'integrated_dlc'];
+const MAX_DLC_LAYERS = 256;
+const MAX_DESCRIPTOR_BYTES = 64 * 1024;
+/**
+ * Installed DLC data folders in the order the engine loads them: after the base game and
+ * before mods, sorted by the internal ID in each folder's `dlcNNN.dlc` descriptor. Only real
+ * directories inside the game root are admitted; archives are not unpacked.
+ */
+async function discoverDlcLayers(gameRoot) {
+    const layers = [];
+    for (const container of DLC_CONTAINERS) {
+        let entries;
+        try {
+            entries = await readdir(path.join(gameRoot, container), { withFileTypes: true });
+        }
+        catch (error) {
+            if (['ENOENT', 'ENOTDIR'].includes(error.code ?? ''))
+                continue;
+            throw error;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || !/^[A-Za-z0-9_.-]{1,128}$/u.test(entry.name))
+                continue;
+            const folder = path.join(gameRoot, container, entry.name);
+            let names;
+            try {
+                names = await readdir(folder);
+            }
+            catch {
+                continue;
+            }
+            const descriptor = names
+                .map((name) => /^dlc(\d{1,6})\.dlc$/iu.exec(name))
+                .find((match) => match !== null);
+            if (descriptor === undefined)
+                continue;
+            const canonical = await canonicalPath(folder);
+            if (!isWithin(gameRoot, canonical) || canonical === gameRoot)
+                continue;
+            layers.push({ id: Number(descriptor[1]), folder: entry.name, path: canonical });
+        }
+    }
+    if (layers.length > MAX_DLC_LAYERS)
+        throw new ServiceError('WORKSPACE_DLC_LIMIT', `The game root lists more than ${MAX_DLC_LAYERS} DLC folders`);
+    return layers.sort((left, right) => left.id - right.id || compareCodeUnits(left.folder, right.folder));
+}
+/**
+ * `replace_path` entries from a mod descriptor. The engine unloads earlier-loaded files
+ * under each path. Entries that are not safe relative folders are ignored.
+ */
+export async function descriptorReplacePaths(root) {
+    const descriptor = path.join(root, 'descriptor.mod');
+    let bytes;
+    try {
+        const metadata = await lstat(descriptor);
+        if (!metadata.isFile() || metadata.size > MAX_DESCRIPTOR_BYTES)
+            return [];
+        bytes = await readFile(descriptor);
+    }
+    catch {
+        return [];
+    }
+    const document = parseClausewitz(bytes, descriptor);
+    const paths = [];
+    for (const entry of document.root.entries) {
+        if (entry.type !== 'assignment' ||
+            entry.key.value.toLowerCase() !== 'replace_path' ||
+            entry.value.type !== 'scalar')
+            continue;
+        const normalized = entry.value.value.replaceAll('\\', '/').replace(/\/+$/u, '');
+        if (normalized.length === 0 ||
+            normalized.length > 1024 ||
+            normalized.startsWith('/') ||
+            normalized.includes(':') ||
+            /[*?[\]{}!\0]/u.test(normalized) ||
+            normalized.split('/').some((segment) => segment === '..' || segment === '.' || segment === ''))
+            continue;
+        if (!paths.includes(normalized))
+            paths.push(normalized);
+    }
+    return paths;
+}
 async function exists(value, signal) {
     signal?.throwIfAborted();
     try {
@@ -454,7 +537,7 @@ export class WorkspaceResolver {
             this.configuration.http.principals.some((entry) => entry.principal === principal && entry.allowDiscoveredMods));
     }
     assertWorkspaceIsolation(workspace) {
-        const readRoots = workspace.roots.filter((root) => ['game', 'dependency', 'fixture'].includes(root.kind));
+        const readRoots = workspace.roots.filter((root) => ['game', 'dlc', 'dependency', 'fixture'].includes(root.kind));
         const ownedRoots = workspace.roots.filter((root) => ['mod', 'artifact', 'cache'].includes(root.kind));
         for (const existing of this.#byId.values()) {
             if (existing.roots.some((root) => pathsOverlap(workspace.modRoot, root.path))) {
@@ -479,6 +562,12 @@ export class WorkspaceResolver {
             ? registration.dependencies
             : registration.dependencyRoots.map((root) => ({ root, replacePaths: [] }));
         const dependencyRoots = await Promise.all(dependencyRegistrations.map(({ root }) => canonicalPath(root)));
+        // Descriptor `replace_path` entries join any configured ones, as the engine applies them.
+        const replacePathsFor = async (root, configured) => [
+            ...new Set([...configured, ...(await descriptorReplacePaths(root))]),
+        ];
+        const modReplacePaths = registration.kind === 'game' ? [] : await replacePathsFor(modRoot, registration.replacePaths);
+        const dependencyReplacePaths = await Promise.all(dependencyRoots.map((root, index) => replacePathsFor(root, dependencyRegistrations[index].replacePaths)));
         if (registration.kind !== 'mod' &&
             (registration.artifactRoot === undefined || registration.cacheRoot === undefined)) {
             throw new ServiceError('WORKSPACE_GENERATED_ROOT_REQUIRED', 'Read-only game and dependency workspaces require explicit operator-owned storage roots', { workspaceId: registration.id });
@@ -539,20 +628,36 @@ export class WorkspaceResolver {
         }
         await mkdir(artifactRoot, { recursive: true });
         await mkdir(cacheRoot, { recursive: true });
+        // Load order follows the engine: base game, DLC by internal ID, dependencies, then the
+        // workspace's own root. A game workspace is itself the base, so its DLC follow it.
+        const dlcBase = registration.kind === 'game' ? modRoot : gameRoot;
+        const dlcLayers = dlcBase === undefined || !registration.includeGameDlc ? [] : await discoverDlcLayers(dlcBase);
+        const dependencyOffset = registration.kind === 'game' ? 0 : dlcLayers.length;
+        const primaryOrder = dependencyRoots.length + dependencyOffset + 1;
+        const firstDlcOrder = registration.kind === 'game' ? primaryOrder + 1 : 1;
+        const generatedOrder = dependencyRoots.length + dlcLayers.length + 2;
         const roots = [
             {
                 kind: registration.kind,
                 path: modRoot,
                 writable: registration.kind === 'mod',
-                loadOrder: dependencyRoots.length + 1,
-                replacePaths: [...registration.replacePaths],
+                loadOrder: primaryOrder,
+                replacePaths: modReplacePaths,
             },
             ...dependencyRoots.map((dependency, index) => ({
                 kind: 'dependency',
                 path: dependency,
                 writable: false,
-                loadOrder: index + 1,
-                replacePaths: [...dependencyRegistrations[index].replacePaths],
+                loadOrder: index + 1 + dependencyOffset,
+                replacePaths: dependencyReplacePaths[index],
+            })),
+            ...dlcLayers.map((layer, index) => ({
+                kind: 'dlc',
+                path: layer.path,
+                writable: false,
+                loadOrder: firstDlcOrder + index,
+                replacePaths: [],
+                label: layer.folder,
             })),
             ...(gameRoot === undefined
                 ? []
@@ -569,14 +674,14 @@ export class WorkspaceResolver {
                 kind: 'artifact',
                 path: artifactRoot,
                 writable: true,
-                loadOrder: dependencyRoots.length + 2,
+                loadOrder: generatedOrder,
                 replacePaths: [],
             },
             {
                 kind: 'cache',
                 path: cacheRoot,
                 writable: true,
-                loadOrder: dependencyRoots.length + 2,
+                loadOrder: generatedOrder,
                 replacePaths: [],
             },
             ...(fixtureRoot === undefined
@@ -602,6 +707,7 @@ export class WorkspaceResolver {
             modRoot,
             ...(gameRoot === undefined ? {} : { gameRoot }),
             dependencyRoots,
+            dlcLayers,
             artifactRoot,
             cacheRoot,
             ...(fixtureRoot === undefined ? {} : { fixtureRoot }),

package/dist/hoi4_agent_tools/event/artifact-validation.js

@@ -103,7 +103,7 @@ const unresolvedKinds = new Set([
     'state',
     'partial_source',
 ]);
-const rootKinds = new Set(['mod', 'game', 'dependency', 'artifact', 'cache', 'fixture']);
+const rootKinds = new Set(['mod', 'game', 'dlc', 'dependency', 'artifact', 'cache', 'fixture']);
 const symbolKinds = new Set([
     'focus_tree',
     'focus',

package/dist/hoi4_agent_tools/event/service.js

@@ -196,7 +196,7 @@ async function scanEventSources(engine, workspaceId, workspace, focused = false,
     if (workspace.roots.some(({ kind }) => kind === 'game'))
         files.push(...(await engine.scanner.scan(workspace, {
             patterns: gamePatterns,
-            rootKinds: ['game'],
+            rootKinds: ['game', 'dlc'],
             ...(signal === undefined ? {} : { signal }),
         })));
     recomputeShadowing(files);

package/dist/hoi4_agent_tools/focus/service.js

@@ -108,7 +108,7 @@ export class FocusWorkbench {
         this.artifactStore = artifactStore;
     }
     async importPath(workspaceId, relativePath, principal, sidecar, references) {
-        const resolved = await this.resolver.resolvePath(workspaceId, relativePath, 'read', ['mod', 'dependency', 'game', 'fixture'], principal);
+        const resolved = await this.resolver.resolvePath(workspaceId, relativePath, 'read', ['mod', 'dependency', 'game', 'dlc', 'fixture'], principal);
         const document = parseClausewitz(await readFile(resolved.path), `${resolved.root.kind}:${relativePath}`);
         const result = importFocusTrees(document, references === undefined ? {} : { references });
         if (sidecar !== undefined) {
@@ -121,7 +121,7 @@ export class FocusWorkbench {
         return { document, result };
     }
     async importContinuousPath(workspaceId, relativePath, principal) {
-        const resolved = await this.resolver.resolvePath(workspaceId, relativePath, 'read', ['mod', 'dependency', 'game', 'fixture'], principal);
+        const resolved = await this.resolver.resolvePath(workspaceId, relativePath, 'read', ['mod', 'dependency', 'game', 'dlc', 'fixture'], principal);
         const document = parseClausewitz(await readFile(resolved.path), `${resolved.root.kind}:${relativePath}`);
         return { document, result: importContinuousFocusPalettes(document) };
     }

package/dist/hoi4_agent_tools/gui/studio.js

@@ -8,6 +8,7 @@ import { sortDiagnostics } from '../core/diagnostics.js';
 import { CoreEngine } from '../core/engine.js';
 import { ClausewitzEvaluationDefinitions } from '../core/clausewitz-evaluation.js';
 import { assertRenderDimensions, RenderBudget, RENDER_MAX_PIXELS } from '../core/render-budget.js';
+import { escapeFileGlob } from '../core/file-glob.js';
 import { ServiceError } from '../core/result.js';
 import { WorkspaceScanner } from '../core/scanner.js';
 import { applyReplacements, decodeSource, encodeSource, parseClausewitz, parseLocalisation, SOURCE_MAX_BYTES, sourcePartialLimitDiagnostics, } from '../core/source/index.js';
@@ -239,15 +240,27 @@ function referenceVariants(value) {
             : [normalized];
     return candidates;
 }
+const FALLBACK_NAMES_PER_PATTERN = 100;
 function basenameFallbackPatterns(exactPaths, exactFiles) {
     const resolved = new Set(exactFiles
         .filter(({ shadowedBy }) => shadowedBy === undefined)
         .map(({ relativePath }) => relativePath.replaceAll('\\', '/').toLowerCase()));
-    return [
+    const names = [
         ...new Set(exactPaths
             .filter((candidate) => !/[*?[\]{}!]/u.test(candidate) && !resolved.has(candidate.toLowerCase()))
-            .map((candidate) => `**/${path.posix.basename(candidate)}`)),
+            .map((candidate) => path.posix.basename(candidate))),
     ].sort((left, right) => compareCodeUnits(left, right));
+    // One brace group searches many names in a single bounded wildcard pattern, so a window
+    // with hundreds of unresolved assets stays inside the scanner's wildcard-pattern ceiling.
+    const grouped = names.filter((name) => !/[,{}]/u.test(name));
+    const patterns = names
+        .filter((name) => /[,{}]/u.test(name))
+        .map((name) => `**/${escapeFileGlob(name)}`);
+    for (let start = 0; start < grouped.length; start += FALLBACK_NAMES_PER_PATTERN) {
+        const chunk = grouped.slice(start, start + FALLBACK_NAMES_PER_PATTERN).map(escapeFileGlob);
+        patterns.push(chunk.length === 1 ? `**/${chunk[0]}` : `**/{${chunk.join(',')}}`);
+    }
+    return patterns.sort((left, right) => compareCodeUnits(left, right));
 }
 function selectedElements(graph, windowName, additionalTemplateNames = []) {
     const byId = new Map(graph.elements.map((element) => [element.id, element]));
@@ -987,7 +1000,7 @@ export class ScriptedGuiStudio {
             collectNamedAttributes(element.attributes, new Set(['verticalScrollbar', 'horizontalScrollbar', 'scrollbarType', 'scrollbartype']), requiredNames);
         const availableNames = new Set(layoutGraph.elements.map(({ name }) => name));
         if ([...requiredNames].some((name) => !availableNames.has(name))) {
-            const gameLayouts = await this.engine.scan(workspaceId, { patterns: layoutPatterns, rootKinds: ['game'] }, principal, signal);
+            const gameLayouts = await this.engine.scan(workspaceId, { patterns: layoutPatterns, rootKinds: ['game', 'dlc'] }, principal, signal);
             const gameGraph = this.graphForFiles(gameLayouts.files, `game-layout:${workspaceId}`).graph;
             const selectedPaths = new Set(selectedElements(gameGraph, windowName, [...requiredNames]).map(({ sourcePath }) => sourcePath));
             layoutFiles = mergeScannedFiles(layoutFiles, gameLayouts.files.filter(({ displayPath }) => selectedPaths.has(displayPath)));

package/dist/hoi4_agent_tools/map/model.js

@@ -456,6 +456,44 @@ export function parseState(file, diagnostics, earliestBookmark) {
         ...(buildingsBlock === undefined ? {} : { buildingsBlock }),
     };
 }
+/**
+ * Provincial terrain categories from the active `common/terrain` files. Files are read in
+ * ASCII path order, so a later file's category replaces an earlier one of the same name.
+ */
+export function parseTerrainCategories(files, diagnostics) {
+    const categories = new Map();
+    for (const file of [...files].sort((left, right) => compareCodeUnits(normalizedPath(left.relativePath), normalizedPath(right.relativePath)))) {
+        const document = parseClausewitz(file.bytes, file.displayPath);
+        addMapDiagnostics(diagnostics, document.diagnostics);
+        for (const entry of document.root.entries) {
+            if (entry.type !== 'assignment' || entry.key.value !== 'categories')
+                continue;
+            if (entry.value.type !== 'block')
+                continue;
+            for (const category of entry.value.entries) {
+                if (category.type !== 'assignment' || category.value.type !== 'block')
+                    continue;
+                const flag = (key) => firstScalar(category.value, key)?.value === 'yes';
+                categories.set(category.key.value, {
+                    name: category.key.value,
+                    water: flag('is_water'),
+                    naval: flag('naval_terrain'),
+                    file,
+                });
+            }
+        }
+    }
+    return categories;
+}
+/** Continent names in `continent.txt`; their one-based positions are the continent IDs. */
+export function parseContinents(file, diagnostics) {
+    const document = parseClausewitz(file.bytes, file.displayPath);
+    addMapDiagnostics(diagnostics, document.diagnostics);
+    const assignment = firstTopLevelAssignment(document, 'continents');
+    if (assignment?.value.type !== 'block')
+        return undefined;
+    return scalarList(assignment.value);
+}
 export function parseStrategicRegion(file, diagnostics) {
     const document = parseClausewitz(file.bytes, file.displayPath);
     addMapDiagnostics(diagnostics, document.diagnostics);
@@ -499,13 +537,22 @@ export function parseAdjacencies(file, diagnostics) {
     const document = parseTextDocument(file);
     const result = [];
     let dataIndex = 0;
+    let terminator;
+    const ignored = [];
     for (const line of document.lines) {
         const trimmed = line.text.trim();
         if (line.index === 0 || trimmed === '' || trimmed.startsWith('#'))
             continue;
+        // The engine stops reading at the first -1 row; later rows have no effect.
+        if (terminator !== undefined) {
+            ignored.push(line);
+            continue;
+        }
         const parts = splitDelimitedRow(line.text, 10);
-        if (parts[0] === '-1')
-            break;
+        if (parts[0] === '-1') {
+            terminator = line;
+            continue;
+        }
         if (parts.length < 9) {
             addMapDiagnostic(diagnostics, {
                 code: 'MAP_ADJACENCY_ROW_MALFORMED',
@@ -545,6 +592,23 @@ export function parseAdjacencies(file, diagnostics) {
         });
         dataIndex += 1;
     }
+    if (ignored.length > 0)
+        addMapDiagnostic(diagnostics, {
+            code: 'MAP_ADJACENCY_AFTER_TERMINATOR',
+            severity: 'warning',
+            category: 'map',
+            message: `${ignored.length} adjacency row(s) follow the -1 terminator row and are not read`,
+            location: lineLocation(document, ignored[0]),
+            details: { ignoredRows: ignored.length },
+        });
+    if (terminator === undefined)
+        addMapDiagnostic(diagnostics, {
+            code: 'MAP_ADJACENCY_TERMINATOR_MISSING',
+            severity: 'warning',
+            category: 'map',
+            message: 'Adjacency file has no -1;-1;-1;-1;-1;-1;-1;-1;-1 terminator row',
+            location: lineLocation(document, document.lines.at(-1) ?? document.lines[0]),
+        });
     return result;
 }
 function parseWhitespaceRows(file, diagnostics) {
@@ -971,6 +1035,11 @@ export class MapWorkspaceIndex {
     defaultMapFile;
     definitionFile;
     adjacencyFile;
+    continentFile;
+    /** Continent names when `continent.txt` was read; its positions are the IDs. */
+    continents;
+    /** Terrain categories when any `common/terrain` file was read. */
+    terrainCategories;
     supplyNodeFile;
     railwayFile;
     constructor(files, sourceRoots = defaultMapIndexSourceRoots, sharedIndex = SymbolIndex.build(files)) {
@@ -1119,6 +1188,16 @@ export class MapWorkspaceIndex {
                 this.regionsByProvince.set(provinceId, memberships);
             }
         }
+        this.continentFile = mapFile(this.activeFiles, defaultMapSelectorValue(this.defaultMapFile, 'continent', 'continent.txt'), this.sourceRoots.map);
+        this.continents =
+            this.continentFile === undefined
+                ? undefined
+                : parseContinents(this.continentFile, this.diagnostics);
+        const terrainFiles = this.activeFiles.all.filter((file) => /^common\/terrain\/[^/]+\.txt$/iu.test(normalizedPath(file.relativePath)));
+        this.terrainCategories =
+            terrainFiles.length === 0
+                ? undefined
+                : parseTerrainCategories(terrainFiles, this.diagnostics);
         this.adjacencyFile = mapFile(this.activeFiles, defaultMapSelectorValue(this.defaultMapFile, 'adjacencies', 'adjacencies.csv'), this.sourceRoots.map);
         this.adjacencies =
             this.adjacencyFile === undefined

package/dist/hoi4_agent_tools/map/service.js

@@ -380,6 +380,7 @@ function defaultMapPatterns(roots) {
 function sourceTextPatterns(roots) {
     return [
         'common/bookmarks/**/*.txt',
+        'common/terrain/*.txt',
         ...roots.map.flatMap((root) => {
             const normalized = normalizeSourceRoot(root);
             return ['map', 'csv', 'txt'].map((extension) => `${normalized}/**/*.${extension}`);

package/dist/hoi4_agent_tools/map/validation.js

@@ -546,6 +546,36 @@ function* validateDefinitions(index, diagnostics, options) {
     }
     for (const [definitionIndex, definition] of index.definitions.entries()) {
         yield* cancellationCheckpoint(options.signal, definitionIndex, 256);
+        const terrain = index.terrainCategories?.get(definition.terrain);
+        if (index.terrainCategories !== undefined && terrain === undefined) {
+            addDiagnostic(diagnostics, options, {
+                code: 'MAP_TERRAIN_UNKNOWN',
+                severity: 'error',
+                category: 'map',
+                message: `Province ${definition.id} uses terrain ${definition.terrain}, which no common/terrain category defines`,
+                location: definitionLocation(definition),
+            });
+        }
+        if (definition.type === 'land' &&
+            index.continents !== undefined &&
+            definition.continent > index.continents.length) {
+            addDiagnostic(diagnostics, options, {
+                code: 'MAP_CONTINENT_UNKNOWN',
+                severity: 'error',
+                category: 'map',
+                message: `Land province ${definition.id} uses continent ${definition.continent}, but continent.txt defines ${index.continents.length}`,
+                location: definitionLocation(definition),
+            });
+        }
+        if (definition.type === 'land' && terrain?.water === true) {
+            addDiagnostic(diagnostics, options, {
+                code: 'MAP_LAND_TERRAIN_WATER',
+                severity: 'error',
+                category: 'map',
+                message: `Land province ${definition.id} uses water terrain ${definition.terrain}`,
+                location: definitionLocation(definition),
+            });
+        }
         if (definition.type === 'land' && definition.continent === 0) {
             addDiagnostic(diagnostics, options, {
                 code: 'MAP_LAND_CONTINENT_MISSING',
@@ -555,21 +585,30 @@ function* validateDefinitions(index, diagnostics, options) {
                 location: definitionLocation(definition),
             });
         }
-        if (definition.type === 'sea' && definition.terrain !== 'ocean') {
+        // With terrain categories available, any is_water category suits seas and lakes; without
+        // them, the base game's ocean and lakes categories are the only known water terrains.
+        const water = (fallback) => index.terrainCategories === undefined
+            ? definition.terrain === fallback
+            : terrain === undefined || terrain.water;
+        if (definition.type === 'sea' && !water('ocean')) {
             addDiagnostic(diagnostics, options, {
                 code: 'MAP_SEA_TERRAIN_INVALID',
                 severity: 'error',
                 category: 'map',
-                message: `Sea province ${definition.id} must use ocean terrain`,
+                message: index.terrainCategories === undefined
+                    ? `Sea province ${definition.id} must use ocean terrain`
+                    : `Sea province ${definition.id} must use a water terrain (is_water = yes)`,
                 location: definitionLocation(definition),
             });
         }
-        if (definition.type === 'lake' && definition.terrain !== 'lakes') {
+        if (definition.type === 'lake' && !water('lakes')) {
             addDiagnostic(diagnostics, options, {
                 code: 'MAP_LAKE_TERRAIN_INVALID',
                 severity: 'error',
                 category: 'map',
-                message: `Lake province ${definition.id} must use lakes terrain`,
+                message: index.terrainCategories === undefined
+                    ? `Lake province ${definition.id} must use lakes terrain`
+                    : `Lake province ${definition.id} must use a water terrain (is_water = yes)`,
                 location: definitionLocation(definition),
             });
         }
@@ -711,6 +750,23 @@ function* validateStatesAndRegions(index, diagnostics, options) {
             });
         }
     }
+    if (index.terrainCategories !== undefined)
+        for (const region of index.regions) {
+            if (region.navalTerrain === undefined)
+                continue;
+            const category = index.terrainCategories.get(region.navalTerrain);
+            if (category?.naval === true)
+                continue;
+            addDiagnostic(diagnostics, options, {
+                code: 'MAP_REGION_NAVAL_TERRAIN_INVALID',
+                severity: 'error',
+                category: 'map',
+                message: category === undefined
+                    ? `Strategic region ${region.id} names naval terrain ${region.navalTerrain}, which no common/terrain category defines`
+                    : `Strategic region ${region.id} names ${region.navalTerrain}, which is not a naval terrain (naval_terrain = yes)`,
+                location: regionLocation(region),
+            });
+        }
     for (const [id, regions] of duplicateValues(index.regions, (region) => String(region.id))) {
         const firstRegion = regions[0];
         if (firstRegion === undefined)

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

@@ -36,7 +36,7 @@ export const referenceTools = [
     {
         name: 'hoi4.source_lookup',
         title: 'Look up HOI4 source symbol',
-        description: 'Find exact Clausewitz definitions and usages; navigate nested keyPath blocks or list bounded child structure with view=structure.',
+        description: 'Find exact Clausewitz definitions and usages; navigate nested keyPath blocks or list bounded child structure with view=structure. Or pass path and line to get the definitions and keyPath containing that line.',
         inputSchema: sourceLookupRequestSchema,
         outputSchema: strictOperationResultSchema(sourceLookupDataSchema),
         annotations: readOnly,

package/dist/hoi4_agent_tools/package-check/service.js

@@ -100,7 +100,7 @@ export class PackageAnalyzer {
             });
         const results = indexedChecks(snapshot, input.manifest);
         const read = async (relativePath) => {
-            const resolved = await this.engine.resolver.resolvePath(input.workspaceId, relativePath, 'read', ['mod', 'game', 'dependency', 'fixture'], input.principal);
+            const resolved = await this.engine.resolver.resolvePath(input.workspaceId, relativePath, 'read', ['mod', 'game', 'dlc', 'dependency', 'fixture'], input.principal);
             const metadata = await stat(resolved.path);
             if (!metadata.isFile() || metadata.size > MAX_FILE_BYTES)
                 throw new ServiceError('PACKAGE_FILE_LIMIT', 'Package file exceeds the bounded reader');