hoi4-agent-tools 3.4.1 → 3.5.0

package/dist/hoi4_agent_tools/gui/studio.js

@@ -498,6 +498,24 @@ function scenarioTemplateNames(scenarios) {
         ...new Set(scenarios.flatMap(({ lists }) => Object.values(lists).flatMap((rows) => rows.flatMap(({ entryContainer }) => typeof entryContainer === 'string' && entryContainer.length > 0 ? [entryContainer] : [])))),
     ].sort(compareCodeUnits);
 }
+function scenarioLocalisationKeys(scenarios) {
+    const keys = new Set();
+    const pending = [...scenarios];
+    while (pending.length > 0) {
+        const value = pending.pop();
+        if (typeof value === 'string') {
+            if (/^[A-Za-z0-9_.-]{1,512}$/u.test(value))
+                keys.add(value);
+            for (const match of value.matchAll(/\$([A-Za-z0-9_.-]+)\$/gu))
+                keys.add(match[1]);
+        }
+        else if (Array.isArray(value))
+            pending.push(...value);
+        else if (value !== null && typeof value === 'object')
+            pending.push(...Object.values(value));
+    }
+    return [...keys].sort(compareCodeUnits);
+}
 /** Native row bindings admit only bounded country tokens, never caller-supplied paths or globs. */
 export function scenarioCountryFlagPatterns(scenarios) {
     const tags = new Set();
@@ -861,8 +879,8 @@ export class ScriptedGuiStudio {
         this.scanner = this.engine.scanner;
         this.artifacts = this.engine.artifacts;
     }
-    graphForFiles(files, scope) {
-        const key = `${scope}:${hashCanonical(files.map(({ displayPath, sha256, shadowedBy }) => ({
+    graphForFiles(files, scope, additionalLocalisationKeys = []) {
+        const key = `${scope}:${hashCanonical(additionalLocalisationKeys)}:${hashCanonical(files.map(({ displayPath, sha256, shadowedBy }) => ({
             displayPath,
             sha256,
             ...(shadowedBy === undefined ? {} : { shadowedBy }),
@@ -876,7 +894,7 @@ export class ScriptedGuiStudio {
         const retainedFiles = [...files];
         const scanned = {
             files: retainedFiles,
-            graph: buildGuiSourceGraph(retainedFiles, this.engine.indexFiles(retainedFiles)),
+            graph: buildGuiSourceGraph(retainedFiles, this.engine.indexFiles(retainedFiles), additionalLocalisationKeys),
         };
         this.#graphCache.set(key, scanned);
         while (this.#graphCache.size > 1) {
@@ -906,7 +924,7 @@ export class ScriptedGuiStudio {
         const files = mergeScannedFiles(snapshot.files, localisationFiles);
         return this.graphForFiles(files, `workspace:${workspaceId}`);
     }
-    async scanWindow(workspaceId, windowName, principal, signal, languages = ['l_english'], additionalSpriteNames = [], additionalTemplateNames = [], additionalAssetPatterns = []) {
+    async scanWindow(workspaceId, windowName, principal, signal, languages = ['l_english'], additionalSpriteNames = [], additionalTemplateNames = [], additionalAssetPatterns = [], additionalLocalisationKeys = []) {
         const workspace = this.resolver.get(workspaceId, principal);
         const layoutPatterns = guiLayoutPatterns(workspace);
         const overlayLayouts = await this.engine.scan(workspaceId, {
@@ -934,7 +952,7 @@ export class ScriptedGuiStudio {
             this.engine.scan(workspaceId, { patterns: guiLocalisationPatterns(workspace, languages) }, principal, signal),
         ]);
         const definitionFiles = mergeScannedFiles(layoutFiles, linkedDefinitions.files, localisation.files);
-        const definitions = this.graphForFiles(definitionFiles, `definitions:${workspaceId}`);
+        const definitions = this.graphForFiles(definitionFiles, `definitions:${workspaceId}`, additionalLocalisationKeys);
         assertTargetWindowAvailable(definitions.graph, windowName);
         const referencedPatterns = [
             ...referencedAssetPatternsForWindow(definitions.graph, windowName, additionalSpriteNames, languages, additionalTemplateNames),
@@ -973,7 +991,7 @@ export class ScriptedGuiStudio {
         const fontPages = mergeScannedFiles(exactFontPages, fallbackFontPages);
         signal?.throwIfAborted();
         const files = mergeScannedFiles(definitions.files, referenced, fontPages);
-        return this.graphForFiles(files, `window:${workspaceId}:${windowName}`);
+        return this.graphForFiles(files, `window:${workspaceId}:${windowName}`, additionalLocalisationKeys);
     }
     async lint(input) {
         input.signal?.throwIfAborted();
@@ -982,7 +1000,7 @@ export class ScriptedGuiStudio {
         const generatedOptions = input.generatedScenarios === undefined
             ? undefined
             : parseGeneratedScenarioOptions(input.generatedScenarios);
-        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [placeholderScenario.language, ...explicitRelatedScenarios.map(({ language }) => language)], scenarioSpriteNames([placeholderScenario, ...explicitRelatedScenarios], generatedOptions?.textSamples), scenarioTemplateNames([placeholderScenario, ...explicitRelatedScenarios]), scenarioCountryFlagPatterns([placeholderScenario, ...explicitRelatedScenarios]));
+        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [placeholderScenario.language, ...explicitRelatedScenarios.map(({ language }) => language)], scenarioSpriteNames([placeholderScenario, ...explicitRelatedScenarios], generatedOptions?.textSamples), scenarioTemplateNames([placeholderScenario, ...explicitRelatedScenarios]), scenarioCountryFlagPatterns([placeholderScenario, ...explicitRelatedScenarios]), scenarioLocalisationKeys([placeholderScenario, ...explicitRelatedScenarios]));
         const generatedScenarios = generatedOptions === undefined
             ? []
             : generateGuiPreviewScenarios(scanned.graph, input.windowName, placeholderScenario, generatedOptions, ClausewitzEvaluationDefinitions.build(scanned));
@@ -1012,7 +1030,7 @@ export class ScriptedGuiStudio {
         const budget = new RenderBudget();
         const beforeScenario = parsePreviewScenario(input.before);
         const afterScenario = parsePreviewScenario(input.after);
-        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [beforeScenario.language, afterScenario.language], scenarioSpriteNames([beforeScenario, afterScenario]), scenarioTemplateNames([beforeScenario, afterScenario]), scenarioCountryFlagPatterns([beforeScenario, afterScenario]));
+        const scanned = await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [beforeScenario.language, afterScenario.language], scenarioSpriteNames([beforeScenario, afterScenario]), scenarioTemplateNames([beforeScenario, afterScenario]), scenarioCountryFlagPatterns([beforeScenario, afterScenario]), scenarioLocalisationKeys([beforeScenario, afterScenario]));
         const beforeCatalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, beforeScenario.language);
         const afterCatalog = new GuiAssetCatalog(scanned.graph, scanned.files, budget, afterScenario.language);
         const before = await buildGuiScene(scanned.graph, scanned.files, input.windowName, beforeScenario, beforeCatalog);
@@ -1069,6 +1087,10 @@ export class ScriptedGuiStudio {
             placeholderScenario,
             ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
             ...explicitRelatedScenarios,
+        ]), scenarioLocalisationKeys([
+            placeholderScenario,
+            ...(requestedBaselineScenario === undefined ? [] : [requestedBaselineScenario]),
+            ...explicitRelatedScenarios,
         ]));
         const generatedScenarios = generatedOptions === undefined
             ? []
@@ -1177,7 +1199,7 @@ export class ScriptedGuiStudio {
                     loadOrder: original.loadOrder,
                 },
             ]);
-            const baselineGraph = this.graphForFiles(baselineFiles, `source-baseline:${input.workspaceId}`).graph;
+            const baselineGraph = this.graphForFiles(baselineFiles, `source-baseline:${input.workspaceId}`, scenarioLocalisationKeys([scenario])).graph;
             if (!baselineGraph.elements.some(({ name }) => name === input.windowName))
                 throw new ServiceError('GUI_SOURCE_BASELINE_WINDOW_MISSING', 'Source baseline does not define the requested GUI window', { relativePath, windowName: input.windowName });
             sourceBaselineScene = await buildGuiScene(baselineGraph, baselineFiles, input.windowName, scenario, new GuiAssetCatalog(baselineGraph, baselineFiles, budget, scenario.language));
@@ -1416,7 +1438,7 @@ export class ScriptedGuiStudio {
         const previewScenario = input.scenario === undefined ? undefined : parsePreviewScenario(input.scenario);
         const initiallyScanned = input.windowName === undefined
             ? await this.scan(input.workspaceId, input.principal, input.signal)
-            : await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [previewScenario.language], scenarioSpriteNames([previewScenario]), scenarioTemplateNames([previewScenario]), scenarioCountryFlagPatterns([previewScenario]));
+            : await this.scanWindow(input.workspaceId, input.windowName, input.principal, input.signal, [previewScenario.language], scenarioSpriteNames([previewScenario]), scenarioTemplateNames([previewScenario]), scenarioCountryFlagPatterns([previewScenario]), scenarioLocalisationKeys([previewScenario]));
         const exactTargets = await this.scanner.scan(workspace, {
             patterns: prepared.map(({ relativePath }) => relativePath),
             ...(input.signal === undefined ? {} : { signal: input.signal }),

package/dist/hoi4_agent_tools/map/model.js

@@ -169,6 +169,39 @@ function parseNumber(value) {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
+export function parseMapDate(value) {
+    const match = /^(\d{1,4})\.(\d{1,2})\.(\d{1,2})(?:\.(\d{1,2}))?$/u.exec(value);
+    if (match === null)
+        return undefined;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const hour = match[4] === undefined ? 0 : Number(match[4]);
+    if (year < 1 || month < 1 || month > 12 || day < 1 || day > 31 || hour < 0 || hour > 23)
+        return undefined;
+    return year * 1_000_000 + month * 10_000 + day * 100 + hour;
+}
+function earliestBookmarkDate(files) {
+    let earliest;
+    for (const file of files) {
+        if (!/^common\/bookmarks\/.*\.txt$/iu.test(normalizedPath(file.relativePath)))
+            continue;
+        const document = parseClausewitz(file.bytes, file.displayPath);
+        for (const root of childBlocks(document.root, 'bookmarks')) {
+            for (const bookmark of childBlocks(root, 'bookmark')) {
+                const value = firstScalar(bookmark, 'date')?.value;
+                if (value === undefined)
+                    continue;
+                const ordinal = parseMapDate(value);
+                if (ordinal === undefined)
+                    continue;
+                if (earliest === undefined || ordinal < earliest.ordinal)
+                    earliest = { value, ordinal, sourcePath: file.displayPath };
+            }
+        }
+    }
+    return earliest;
+}
 function requiredNumber(values, index, label) {
     const value = values[index];
     if (value === undefined) {
@@ -260,7 +293,7 @@ export function parseDefinitions(file, diagnostics) {
     }
     return definitions;
 }
-export function parseState(file, diagnostics) {
+export function parseState(file, diagnostics, earliestBookmark) {
     const document = parseClausewitz(file.bytes, file.displayPath);
     addMapDiagnostics(diagnostics, document.diagnostics);
     const assignment = firstTopLevelAssignment(document, 'state');
@@ -318,8 +351,85 @@ export function parseState(file, diagnostics) {
             }
         }
     }
-    const owner = firstScalar(historyBlock ?? block, 'owner')?.value;
-    const controller = firstScalar(historyBlock ?? block, 'controller')?.value;
+    let owner = firstScalar(historyBlock ?? block, 'owner')?.value;
+    let controller = firstScalar(historyBlock ?? block, 'controller')?.value;
+    let cores = historyBlock === undefined
+        ? []
+        : assignments(historyBlock, 'add_core_of').flatMap(({ value }) => value.type === 'scalar' ? [value.value] : []);
+    let claims = historyBlock === undefined
+        ? []
+        : assignments(historyBlock, 'add_claim_by').flatMap(({ value }) => value.type === 'scalar' ? [value.value] : []);
+    if (historyBlock !== undefined) {
+        const dated = assignments(historyBlock)
+            .flatMap((entry) => {
+            if (entry.value.type !== 'block')
+                return [];
+            const date = parseMapDate(entry.key.value);
+            return date === undefined ? [] : [{ entry, date }];
+        })
+            .sort((left, right) => left.date - right.date || left.entry.start - right.entry.start);
+        if (dated.length > 0 && earliestBookmark === undefined) {
+            addMapDiagnostic(diagnostics, {
+                code: 'MAP_STATE_DATED_HISTORY_UNRESOLVED',
+                severity: 'warning',
+                category: 'map',
+                message: `State ${id} has dated history but no active bookmark date was found`,
+                location: nodeLocation(document, dated[0].entry),
+            });
+        }
+        for (const { entry, date } of dated) {
+            if (earliestBookmark === undefined || date >= earliestBookmark.ordinal)
+                continue;
+            if (entry.value.type !== 'block')
+                continue;
+            for (const command of assignments(entry.value)) {
+                const value = command.value;
+                if (value.type === 'scalar') {
+                    if (command.key.value === 'owner')
+                        owner = value.value;
+                    else if (command.key.value === 'controller')
+                        controller = value.value;
+                    else if (command.key.value === 'add_core_of' && !cores.includes(value.value))
+                        cores.push(value.value);
+                    else if (command.key.value === 'remove_core_of')
+                        cores = cores.filter((tag) => tag !== value.value);
+                    else if (command.key.value === 'add_claim_by' && !claims.includes(value.value))
+                        claims.push(value.value);
+                    else if (command.key.value === 'remove_claim_by')
+                        claims = claims.filter((tag) => tag !== value.value);
+                }
+                else if (command.key.value === 'victory_points') {
+                    const values = scalarList(value);
+                    const provinceId = parseInteger(values[0]);
+                    const amount = parseNumber(values[1]);
+                    if (provinceId === undefined || amount === undefined)
+                        continue;
+                    const existing = victoryPoints.findIndex((point) => point.provinceId === provinceId);
+                    if (existing >= 0)
+                        victoryPoints.splice(existing, 1);
+                    victoryPoints.push({ provinceId, value: amount, assignment: command });
+                }
+                else if (command.key.value === 'buildings') {
+                    for (const building of assignments(value)) {
+                        if (building.value.type === 'block') {
+                            const provinceId = parseInteger(building.key.value);
+                            if (provinceId === undefined)
+                                continue;
+                            const merged = new Map(provinceBuildings.get(provinceId) ?? []);
+                            for (const [key, level] of numericMap(building.value))
+                                merged.set(key, level);
+                            provinceBuildings.set(provinceId, merged);
+                        }
+                        else {
+                            const level = parseNumber(building.value.value);
+                            if (level !== undefined)
+                                stateBuildings.set(building.key.value, level);
+                        }
+                    }
+                }
+            }
+        }
+    }
     const capital = derivedStateCapital(victoryPoints);
     return {
         id,
@@ -331,12 +441,8 @@ export function parseState(file, diagnostics) {
         resources: numericMap(resourcesBlock),
         ...(owner === undefined ? {} : { owner }),
         ...(controller === undefined ? {} : { controller }),
-        cores: historyBlock === undefined
-            ? []
-            : assignments(historyBlock, 'add_core_of').flatMap(({ value }) => value.type === 'scalar' ? [value.value] : []),
-        claims: historyBlock === undefined
-            ? []
-            : assignments(historyBlock, 'add_claim_by').flatMap(({ value }) => value.type === 'scalar' ? [value.value] : []),
+        cores,
+        claims,
         victoryPoints,
         provinceBuildings,
         stateBuildings,
@@ -825,6 +931,7 @@ export class MapWorkspaceIndex {
     /** Shared cross-domain symbol/reference authority for these exact source bytes. */
     sharedIndex;
     activeFiles;
+    earliestBookmark;
     diagnostics = [];
     definitions;
     definitionsAcrossRoots;
@@ -875,6 +982,7 @@ export class MapWorkspaceIndex {
             localisation: sourceRoots.localisation.map(normalizeConfiguredRoot),
         };
         this.activeFiles = selectActiveFiles(files);
+        this.earliestBookmark = earliestBookmarkDate(this.activeFiles.all);
         const modelBudget = new MapModelBudget();
         modelBudget.assertScriptFiles(this.sourceFiles.filter((file) => inConfiguredRoot(file.relativePath, this.sourceRoots.states) ||
             this.sourceRoots.map.some((root) => normalizedPath(file.relativePath).startsWith(`${root}/strategicregions/`)) ||
@@ -935,7 +1043,9 @@ export class MapWorkspaceIndex {
             const cached = parsedStates.get(file.displayPath);
             if (cached !== undefined)
                 return cached ?? undefined;
-            const state = parseState(file, activeStatePaths.has(file.displayPath) ? this.diagnostics : []);
+            const state = parseState(file, activeStatePaths.has(file.displayPath) ? this.diagnostics : [], this.earliestBookmark);
+            if (state !== undefined && this.earliestBookmark !== undefined)
+                state.earliestBookmark = this.earliestBookmark;
             parsedStates.set(file.displayPath, state ?? null);
             if (state !== undefined) {
                 modelBudget.addDocument(state.document);
@@ -1075,9 +1185,8 @@ export class MapWorkspaceIndex {
         this.coastalProvinceIds = this.raster?.coastalProvinceIds ?? new Set();
         const portPositionsByStateProvince = new Map();
         for (const position of this.buildingPositions) {
-            if (position.building !== 'naval_base_spawn' && position.building !== 'floating_harbor') {
+            if (position.building !== 'naval_base_spawn')
                 continue;
-            }
             const provinceId = this.provinceAtMapCoordinate(position.x, position.z);
             if (provinceId === undefined)
                 continue;

package/dist/hoi4_agent_tools/map/operations.js

@@ -5,7 +5,7 @@ import { ServiceError } from '../core/result.js';
 import { applyReplacements, assignments, encodeSource, parseLocalisation, parseClausewitz, } from '../core/source/index.js';
 import { rgbKey } from './bmp.js';
 import { MAP_MASK_CELL_LIMIT, MAP_POLYGON_WORK_LIMIT, MAP_SELECTED_OFFSET_BYTES, MAP_SELECTED_PIXEL_LIMIT, } from './limits.js';
-import { derivedStateCapital, encodeTextDocument, MapWorkspaceIndex, parseTextDocument, } from './model.js';
+import { derivedStateCapital, encodeTextDocument, MapWorkspaceIndex, parseMapDate, parseTextDocument, } from './model.js';
 function* cancellationCheckpoint(signal, iteration = 0, stride = 1) {
     if (iteration % stride !== 0)
         return;
@@ -1034,8 +1034,74 @@ function stateMembershipId(index, provinceId) {
     return states[0]?.id;
 }
 function commitState(changes, state, data, fields, operationId) {
+    assertDatedStateHistorySafe(state, fields, operationId);
     addChange(changes, state.file.relativePath, patchState(state, data, fields), operationId, 'text/plain');
 }
+function assertDatedStateHistorySafe(state, fields, operationId) {
+    if (state.historyBlock === undefined)
+        return;
+    for (const entry of assignments(state.historyBlock)) {
+        if (entry.value.type !== 'block')
+            continue;
+        const datedAt = parseMapDate(entry.key.value);
+        if (datedAt === undefined)
+            continue;
+        const keys = new Set(assignments(entry.value).map(({ key }) => key.value));
+        const applicable = state.earliestBookmark === undefined || datedAt <= state.earliestBookmark.ordinal;
+        const affected = [
+            ['owner', fields.owner === true && keys.has('owner') && applicable],
+            ['controller', fields.controller === true && keys.has('controller') && applicable],
+            [
+                'cores',
+                fields.cores === true &&
+                    (keys.has('add_core_of') || keys.has('remove_core_of')) &&
+                    applicable,
+            ],
+            [
+                'claims',
+                fields.claims === true &&
+                    (keys.has('add_claim_by') || keys.has('remove_claim_by')) &&
+                    applicable,
+            ],
+            [
+                'victoryPoints',
+                ((fields.victoryPoints === true && applicable) || fields.provinces === true) &&
+                    keys.has('victory_points'),
+            ],
+            [
+                'buildings',
+                ((fields.buildings === true && applicable) || fields.provinces === true) &&
+                    keys.has('buildings'),
+            ],
+        ];
+        const conflict = affected.find(([, selected]) => selected);
+        if (conflict === undefined)
+            continue;
+        throw new ServiceError('MAP_DATED_STATE_HISTORY_CONFLICT', `State ${state.id} has a dated ${conflict[0]} change that this map operation cannot safely rewrite`, {
+            operationId,
+            stateId: state.id,
+            field: conflict[0],
+            datedAt: entry.key.value,
+            earliestBookmark: state.earliestBookmark?.value ?? null,
+            sourcePath: state.file.displayPath,
+            sourceOffset: entry.start,
+        });
+    }
+}
+function assertNoDatedStateHistory(state, operationId) {
+    if (state.historyBlock === undefined)
+        return;
+    const dated = assignments(state.historyBlock).find((entry) => entry.value.type === 'block' && parseMapDate(entry.key.value) !== undefined);
+    if (dated === undefined)
+        return;
+    throw new ServiceError('MAP_DATED_STATE_DISTRIBUTION_UNSUPPORTED', `State ${state.id} has dated history that cannot be distributed to a new or merged state`, {
+        operationId,
+        stateId: state.id,
+        datedAt: dated.key.value,
+        sourcePath: state.file.displayPath,
+        sourceOffset: dated.start,
+    });
+}
 function commitRegion(changes, region, provinces, operationId) {
     addChange(changes, region.file.relativePath, patchRegion(region, provinces), operationId, 'text/plain');
 }
@@ -1219,6 +1285,7 @@ function* applySplitState(base, changes, allocations, operation, signal) {
     const source = index.statesById.get(sourceStateId);
     if (source === undefined)
         throw new ServiceError('MAP_STATE_NOT_FOUND', `State ${sourceStateId} does not exist`);
+    assertNoDatedStateHistory(source, operation.id);
     const selectedSet = new Set(selected);
     if (selected.length === 0 || selected.some((id) => !source.provinces.includes(id))) {
         throw new ServiceError('MAP_STATE_PROVINCE_SELECTION_INVALID', 'Every new-state province must belong to the source state');
@@ -1336,6 +1403,8 @@ function applyMergeStates(base, changes, operation) {
     if (target === undefined || sourceIds.length === 0 || sources.length !== sourceIds.length) {
         throw new ServiceError('MAP_STATE_SELECTION_INVALID', 'Merge target and source states must exist');
     }
+    for (const source of sources)
+        assertNoDatedStateHistory(source, operation.id);
     const regionIds = new Set([...target.provinces, ...sources.flatMap((state) => state.provinces)].map((id) => regionMembershipId(index, id)));
     if (regionIds.size !== 1)
         throw new ServiceError('MAP_STATE_REGION_DISTRIBUTION_CONFLICT', 'Merged states must share one strategic region');
@@ -1964,12 +2033,16 @@ function* applyUpdateProvinceDefinition(base, changes, operation, signal) {
         if (policy.ports === 'retain-if-valid') {
             for (const position of dependentPortPositions) {
                 const locatedProvince = index.provinceAtMapCoordinate(position.x, position.z);
-                if ((locatedProvince === source.id &&
-                    (targetType !== 'land' ||
-                        position.stateId !== projectedStateId ||
-                        !updated.coastal ||
-                        index.definitionsById.get(position.adjacentSeaProvince)?.type !== 'sea')) ||
-                    (position.adjacentSeaProvince === source.id && targetType !== 'sea'))
+                const incompatible = position.building === 'floating_harbor'
+                    ? (locatedProvince === source.id && targetType !== 'sea') ||
+                        (position.adjacentSeaProvince === source.id && targetType !== 'land')
+                    : (locatedProvince === source.id &&
+                        (targetType !== 'land' ||
+                            position.stateId !== projectedStateId ||
+                            !updated.coastal ||
+                            index.definitionsById.get(position.adjacentSeaProvince)?.type !== 'sea')) ||
+                        (position.adjacentSeaProvince === source.id && targetType !== 'sea');
+                if (incompatible)
                     provinceTypeDistributionConflict(source, targetType, 'ports', 'A retained port placement would no longer identify compatible land and sea provinces', {
                         stateId: position.stateId,
                         locatedProvince: locatedProvince ?? null,

package/dist/hoi4_agent_tools/map/service.js

@@ -379,6 +379,7 @@ function defaultMapPatterns(roots) {
 }
 function sourceTextPatterns(roots) {
     return [
+        'common/bookmarks/**/*.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

@@ -960,6 +960,43 @@ function* validatePositions(index, diagnostics, options) {
         const location = lineLocation(position.document, position.line);
         const state = index.statesById.get(position.stateId);
         const province = index.provinceAtMapCoordinate(position.x, position.z);
+        if (position.building === 'floating_harbor') {
+            const sea = province === undefined ? undefined : index.definitionsById.get(province);
+            const land = index.definitionsById.get(position.adjacentSeaProvince);
+            if (sea?.type !== 'sea') {
+                addDiagnostic(diagnostics, options, {
+                    code: 'MAP_FLOATING_HARBOR_POSITION_REVIEW',
+                    severity: 'warning',
+                    category: 'map',
+                    message: 'Floating-harbor position resolves outside a sea province; review the installed-map precedent',
+                    ...(location === undefined ? {} : { location }),
+                    details: { resolvedProvince: province },
+                });
+            }
+            if (land?.type !== 'land') {
+                addDiagnostic(diagnostics, options, {
+                    code: 'MAP_FLOATING_HARBOR_LAND_INVALID',
+                    severity: 'error',
+                    category: 'map',
+                    message: 'Floating-harbor final field must name an existing land province',
+                    ...(location === undefined ? {} : { location }),
+                    details: { landingProvince: position.adjacentSeaProvince, stateId: position.stateId },
+                });
+            }
+            else if (state === undefined ||
+                !state.provinces.includes(position.adjacentSeaProvince) ||
+                !index.coastalProvinceIds.has(position.adjacentSeaProvince)) {
+                addDiagnostic(diagnostics, options, {
+                    code: 'MAP_FLOATING_HARBOR_ASSOCIATION_REVIEW',
+                    severity: 'warning',
+                    category: 'map',
+                    message: 'Floating-harbor target differs from its state or computed coastal membership',
+                    ...(location === undefined ? {} : { location }),
+                    details: { landingProvince: position.adjacentSeaProvince, stateId: position.stateId },
+                });
+            }
+            continue;
+        }
         if (state === undefined || province === undefined || !state.provinces.includes(province)) {
             addDiagnostic(diagnostics, options, {
                 code: 'MAP_BUILDING_POSITION_INVALID',
@@ -970,7 +1007,7 @@ function* validatePositions(index, diagnostics, options) {
                 details: { resolvedProvince: province },
             });
         }
-        if (position.building === 'naval_base_spawn' || position.building === 'floating_harbor') {
+        if (position.building === 'naval_base_spawn') {
             if (province !== undefined)
                 navalLocatorProvinces.add(province);
             const adjacent = index.definitionsById.get(position.adjacentSeaProvince);

package/dist/hoi4_agent_tools/mcp/server/create-modern-operations.js

@@ -10,6 +10,8 @@ import { MODERN_TASK_ROUTES, ModernTaskRoutingServer } from '../transports/moder
 import { registerModernResources } from '../resources/register-modern.js';
 import { registerModernPrompts } from '../prompts/register-modern.js';
 import { jobControlTools } from '../tools/job.js';
+import { referenceTools } from '../tools/reference.js';
+import { isReferenceTool, ReferenceToolService } from '../../reference/operations.js';
 import { ModernTaskAdapter, TASKS_EXTENSION } from './modern-tasks.js';
 import { SERVER_INSTRUCTIONS } from './instructions.js';
 import { modernProgressReporter, withProgressHeartbeat } from './progress.js';
@@ -39,9 +41,13 @@ function clientCapabilities(envelope) {
 export function createModernOperationServer(engine, context = {}, tasks = new OperationTaskService(engine), options = {}) {
     const adapter = new ModernTaskAdapter(tasks);
     const controls = new JobControlService(engine);
+    const references = new ReferenceToolService(engine);
     const privateOperations = options.createPrivateTools?.(engine, context);
+    const mapEnd = taskToolCatalog.findIndex(({ name }) => name === 'hoi4.map_rewrite') + 1;
     const definitions = [
-        ...taskToolCatalog,
+        ...taskToolCatalog.slice(0, mapEnd),
+        ...referenceTools,
+        ...taskToolCatalog.slice(mapEnd),
         ...jobControlTools,
         ...(privateOperations === undefined
             ? []
@@ -109,6 +115,17 @@ export function createModernOperationServer(engine, context = {}, tasks = new Op
             };
         }
         try {
+            if (isReferenceTool(definition.name)) {
+                const name = definition.name;
+                const result = await withProgressHeartbeat(() => engine.requests.run(references, Buffer.byteLength(JSON.stringify(arguments_)), extra.mcpReq.signal, () => engine.sharedRequests.run(extra.mcpReq.signal, () => references.call(name, arguments_, operationContext, extra.mcpReq.signal))), modernProgressReporter(extra));
+                definition.outputSchema?.parse(result.structuredContent);
+                return CallToolResultSchema.parse({
+                    ...result,
+                    resultType: 'complete',
+                    ttlMs: 0,
+                    cacheScope: 'private',
+                });
+            }
             if (privateOperations !== undefined) {
                 const operations = operationContext === context || options.createPrivateTools === undefined
                     ? privateOperations

package/dist/hoi4_agent_tools/mcp/server/create.js

@@ -4,6 +4,7 @@ import { PACKAGE_NAME, PACKAGE_VERSION } from '../../version.js';
 import { registerFocusTools } from '../tools/focus.js';
 import { registerGuiTools } from '../tools/gui.js';
 import { registerMapTools } from '../tools/map.js';
+import { registerReferenceTools } from '../tools/reference.js';
 import { registerEventTools } from '../tools/event.js';
 import { registerAnalysisTools } from '../tools/analysis.js';
 import { registerTechnologyTools } from '../tools/technology.js';
@@ -53,6 +54,7 @@ export function createMcpServer(engine, context = {}) {
     registerFocusTools(server, engine, serverContext);
     registerGuiTools(server, engine, serverContext);
     registerMapTools(server, engine, serverContext);
+    registerReferenceTools(server, engine, serverContext);
     registerEventTools(server);
     registerAnalysisTools(server);
     registerTechnologyTools(server);

package/dist/hoi4_agent_tools/mcp/server/instructions.js

@@ -1,2 +1,2 @@
 /** Shared agent-facing guidance for both MCP protocol generations. */
-export const SERVER_INSTRUCTIONS = 'Use focus tools for focus trees, GUI tools for interfaces, and map tools for map data. Start unfamiliar event chains with hoi4.event_inspect. Event tools are read-only. Start cross-system source review with hoi4.impact_inspect and decision or mission scenarios with hoi4.decision_inspect. Test declared mechanic steps with hoi4.mechanic_test, package connections with hoi4.package_check, and named suites with hoi4.scenario_test. These analysis tools are read-only. Start technology and doctrine work with hoi4.tech_inspect. Technology tools are read-only. Start weighted AI, MTTH, random, and declared-pool analysis with hoi4.probability_inspect. Probability tools are read-only. Concurrent calls queue automatically and emit periodic progress when the client requests it. Long operations support negotiated MCP tasks; native background rewrites require a stable requestKey. Large evidence is linked as resources.';
+export const SERVER_INSTRUCTIONS = 'Use hoi4.reference_context for local wiki and installed documentation citations, hoi4.reference_search and hoi4.reference_read for exact sections, and hoi4.source_lookup for indexed source examples. Use focus tools for focus trees, GUI tools for interfaces, and map tools for map data. Start unfamiliar event chains with hoi4.event_inspect. Event tools are read-only. Start cross-system source review with hoi4.impact_inspect and decision or mission scenarios with hoi4.decision_inspect. Test declared mechanic steps with hoi4.mechanic_test, package connections with hoi4.package_check, and named suites with hoi4.scenario_test. These analysis tools are read-only. Start technology and doctrine work with hoi4.tech_inspect. Technology tools are read-only. Start weighted AI, MTTH, random, and declared-pool analysis with hoi4.probability_inspect. Probability tools are read-only. Concurrent calls queue automatically and emit periodic progress when the client requests it. Long operations support negotiated MCP tasks; native background rewrites require a stable requestKey. Large evidence is linked as resources.';

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

@@ -0,0 +1,60 @@
+import { errorResult, strictOperationResultSchema } from '../../core/operation-result.js';
+import { ReferenceToolService } from '../../reference/operations.js';
+import { referenceContextRequestSchema, referenceReadRequestSchema, referenceSearchRequestSchema, sourceLookupRequestSchema, referenceContextDataSchema, referenceReadDataSchema, referenceSearchDataSchema, sourceLookupDataSchema, } from '../../schemas/reference.js';
+const readOnly = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+export const referenceTools = [
+    {
+        name: 'hoi4.reference_search',
+        title: 'Search local HOI4 references',
+        description: 'Search bounded, cited sections of the configured offline wiki and installed game documentation.',
+        inputSchema: referenceSearchRequestSchema,
+        outputSchema: strictOperationResultSchema(referenceSearchDataSchema),
+        annotations: readOnly,
+    },
+    {
+        name: 'hoi4.reference_read',
+        title: 'Read cited HOI4 reference section',
+        description: 'Read at most 80 lines from one revision-bound local documentation section.',
+        inputSchema: referenceReadRequestSchema,
+        outputSchema: strictOperationResultSchema(referenceReadDataSchema),
+        annotations: readOnly,
+    },
+    {
+        name: 'hoi4.reference_context',
+        title: 'Get HOI4 task references',
+        description: 'Return a compact bundle of offline wiki and installed game documentation citations for a modding surface.',
+        inputSchema: referenceContextRequestSchema,
+        outputSchema: strictOperationResultSchema(referenceContextDataSchema),
+        annotations: readOnly,
+    },
+    {
+        name: 'hoi4.source_lookup',
+        title: 'Look up HOI4 source symbol',
+        description: 'Find exact Clausewitz definitions, override status, a bounded source block, and indexed usages in the configured game and mod.',
+        inputSchema: sourceLookupRequestSchema,
+        outputSchema: strictOperationResultSchema(sourceLookupDataSchema),
+        annotations: readOnly,
+    },
+];
+export function registerReferenceTools(server, engine, context) {
+    const service = new ReferenceToolService(engine);
+    for (const entry of referenceTools) {
+        const { name: _name, ...definition } = entry;
+        const name = entry.name;
+        server.registerTool(name, definition, async (input, extra) => {
+            try {
+                return await service.call(name, input, context, extra.signal);
+            }
+            catch (error) {
+                if (extra.signal.aborted)
+                    throw error;
+                return errorResult(error);
+            }
+        });
+    }
+}

package/dist/hoi4_agent_tools/probability/service.js

@@ -962,7 +962,7 @@ export class ProbabilityAnalyzer {
             adapter !== undefined &&
             adapter !== 'custom_weighted_pool')
             throw new ServiceError('PROBABILITY_ADAPTER_MISMATCH', 'customPoolManifest inspection requires adapter custom_weighted_pool');
-        const snapshot = await this.scan(context, [source?.path], source === undefined ? 'none' : source.inlineClausewitz === undefined ? 'domain' : 'shared');
+        const snapshot = await this.scan(context, [source?.path, source?.snapshotPath], source === undefined ? 'none' : source.inlineClausewitz === undefined ? 'domain' : 'shared');
         if (customPoolManifest !== undefined) {
             const surface = customSurface(customPoolManifest, snapshot.revision);
             const gameVersionVerification = await this.verifyGameVersion(context, 'custom_weighted_pool');
@@ -1150,7 +1150,7 @@ export class ProbabilityAnalyzer {
             request.adapter !== undefined &&
             request.adapter !== 'custom_weighted_pool')
             throw new ServiceError('PROBABILITY_ADAPTER_MISMATCH', 'customPoolManifest requires the custom_weighted_pool adapter');
-        const snapshot = await this.scan(request, [request.source?.path], usingManifest ? 'none' : request.source?.inlineClausewitz === undefined ? 'domain' : 'shared');
+        const snapshot = await this.scan(request, [request.source?.path, request.source?.snapshotPath], usingManifest ? 'none' : request.source?.inlineClausewitz === undefined ? 'domain' : 'shared');
         const resolvedAdapter = usingManifest
             ? 'custom_weighted_pool'
             : resolveSourceBackedAdapter(snapshot, request.source, request.candidatePool ?? [], request.adapter);