hoi4-agent-tools 4.4.0 → 4.5.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 4.5.0 - 2026-10-25
+
+- Refuse `hoi4.focus_rewrite` with `FOCUS_SOURCE_CHANGED_SINCE_PLAN` when the focus source changed in meaning after the plan was inspected, instead of reverting the external change to the plan's values (national trees and continuous palettes). Comment and formatting changes and a source that already equals the plan are still accepted. Reported by the HOI4 Factory S01 EXP-02 probe.
+- Refuse every rewrite of a file that is not valid UTF-8 and contains bytes Windows-1252 cannot represent (0x81, 0x8D, 0x8F, 0x90, 0x9D) with `SOURCE_ENCODING_NOT_ROUND_TRIPPABLE`. Previously the encoder wrote 0x9D for each of them without a diagnostic. Reads and inspection continue and add a warning with the same code. Valid UTF-8 and valid Windows-1252 files are unchanged.
+- Place countries the mod already owns (ADR 0069): `create_world.countries` accepts `{ "source": "workspace", "realms": [...] }` besides the array. Each realm is a declared tag with a capital point and optional seeds, claim and exclusion polygons and a weight; `unowned` polygons and `islands` (`nearest`, `one-owner`, `unowned`) decide land no country claims. The world then writes only the map, states, strategic regions and their names, and none of the countries' files. New refusals `MAP_WORLD_REALM_TAG_UNKNOWN`, `MAP_WORLD_REALM_TAG_DYNAMIC`, `MAP_WORLD_REALM_POINT_OUTSIDE`, `MAP_WORLD_REALM_POINT_WATER`, `MAP_WORLD_REALM_POINT_CONFLICT` and `MAP_WORLD_REALM_CLAIM_OVERLAP`; notes `MAP_WORLD_REALMS_PLACED` and `MAP_WORLD_STATE_UNOWNED`; result field `data.realms` and artifact `map-world-realms.json`. Public schema change: `countries` becomes a union of the existing array and the new object (minor version). Requests with the array are unchanged.
+- Report what a world write does to the previous world's files: `MAP_WORLD_OUTPUTS_RECONCILED`, `data.outputs` (written, retired and released counts with up to 200 paths each) and the artifact `map-world-outputs.json`. With workspace countries an edited country file of the previous world is released to the mod (`MAP_WORLD_OUTPUT_RELEASED`) instead of refusing the write; every other edited output still refuses with `MANAGED_OUTPUT_EDITED`.
+- Report the declared country tags after every world write (`MAP_WORLD_TAG_COUNT`) and warn above 439 (`MAP_WORLD_TAG_COUNT_HIGH`), the count at which one measured game build overflowed its flag sheet.
+
 ## 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).

package/dist/hoi4_agent_tools/core/managed-outputs.js

@@ -16,6 +16,10 @@ const manifestSchema = z
     .strict();
 /** Pure planning only: the shared transaction engine performs every replacement and deletion. */
 export function reconcileManagedOutputs(input) {
+    return planManagedOutputs(input).changes;
+}
+/** Plans the managed-output reconciliation and reports what it writes, retires and releases. */
+export function planManagedOutputs(input) {
     const sources = new Map(input.sources
         .filter((f) => f.rootKind === 'mod')
         .map((f) => [f.relativePath.replaceAll('\\', '/').toLowerCase(), f]));
@@ -32,6 +36,9 @@ export function reconcileManagedOutputs(input) {
                 throw new ServiceError('MANAGED_OUTPUT_MANIFEST_INVALID', 'Generated-output inventory is invalid');
             }
         })();
+    const outputs = input.proposed.filter((f) => f.content !== null && input.permitsPath(f.relativePath));
+    const next = new Set(outputs.map((f) => f.relativePath.toLowerCase()));
+    const released = new Set();
     const seen = new Set();
     for (const file of previous) {
         const key = file.relativePath.toLowerCase();
@@ -43,19 +50,26 @@ export function reconcileManagedOutputs(input) {
             throw new ServiceError('MANAGED_OUTPUT_MANIFEST_INVALID', 'Generated-output inventory contains an unsupported or duplicate path');
         seen.add(key);
         const current = sources.get(key);
-        if (current !== undefined && sha256Bytes(current.bytes) !== file.sha256)
-            throw new ServiceError('MANAGED_OUTPUT_EDITED', 'A generated file has been edited; regeneration would discard those changes', { relativePath: file.relativePath });
+        if (current === undefined || sha256Bytes(current.bytes) === file.sha256)
+            continue;
+        if (!next.has(key) && input.releasable?.(file.relativePath) === true) {
+            released.add(key);
+            continue;
+        }
+        throw new ServiceError('MANAGED_OUTPUT_EDITED', 'A generated file has been edited; regeneration would discard those changes', { relativePath: file.relativePath });
     }
-    const outputs = input.proposed.filter((f) => f.content !== null && input.permitsPath(f.relativePath));
-    const next = new Set(outputs.map((f) => f.relativePath.toLowerCase()));
     const deletions = previous
-        .filter((f) => !next.has(f.relativePath.toLowerCase()) && sources.has(f.relativePath.toLowerCase()))
+        .filter((f) => {
+        const key = f.relativePath.toLowerCase();
+        return !next.has(key) && !released.has(key) && sources.has(key);
+    })
         .map((f) => ({
         relativePath: f.relativePath,
         content: null,
         operationIds: [input.operationId],
     }));
-    return [
+    const sorted = (paths) => [...paths].sort(compareCodeUnits);
+    const changes = [
         ...deletions,
         {
             relativePath: input.manifestPath,
@@ -69,4 +83,10 @@ export function reconcileManagedOutputs(input) {
             mediaType: 'application/json',
         },
     ];
+    return {
+        changes,
+        written: sorted(outputs.map((f) => f.relativePath)),
+        retired: sorted(deletions.map((f) => f.relativePath)),
+        released: sorted(previous.filter((f) => released.has(f.relativePath.toLowerCase())).map((f) => f.relativePath)),
+    };
 }

package/dist/hoi4_agent_tools/core/source/encoding.js

@@ -1,6 +1,7 @@
 import iconv from 'iconv-lite';
 import { ServiceError } from '../result.js';
 const utf8Bom = Buffer.from([0xef, 0xbb, 0xbf]);
+const REPLACEMENT_CHARACTER = String.fromCharCode(0xfffd);
 function detectNewline(text) {
     const crlf = text.indexOf('\r\n');
     const lf = text.indexOf('\n');
@@ -22,10 +23,55 @@ function isUtf8(bytes) {
         return false;
     }
 }
+let windows1252RoundTrip;
+function windows1252Table() {
+    windows1252RoundTrip ??= Array.from({ length: 256 }, (_, value) => {
+        const original = Buffer.from([value]);
+        const decoded = iconv.decode(original, 'windows-1252');
+        return (decoded !== REPLACEMENT_CHARACTER && iconv.encode(decoded, 'windows-1252').equals(original));
+    });
+    return windows1252RoundTrip;
+}
+function findWindows1252Loss(bytes) {
+    const table = windows1252Table();
+    let count = 0;
+    let firstOffset = -1;
+    const seen = new Set();
+    for (let offset = 0; offset < bytes.length; offset += 1) {
+        const value = bytes[offset];
+        if (table[value])
+            continue;
+        if (firstOffset < 0)
+            firstOffset = offset;
+        count += 1;
+        seen.add(value);
+    }
+    if (count === 0)
+        return undefined;
+    return { count, firstOffset, byteValues: [...seen].sort((left, right) => left - right) };
+}
+/**
+ * Refuses a mutation of a decoded source that cannot be re-encoded to its original bytes.
+ * Reads of such a source continue to work; only writes are blocked.
+ */
+export function assertSourceEncodingPreserved(decoded, sourcePath) {
+    const loss = decoded.encodingLoss;
+    if (loss === undefined)
+        return;
+    const values = loss.byteValues.map((value) => `0x${value.toString(16).toUpperCase()}`);
+    throw new ServiceError('SOURCE_ENCODING_NOT_ROUND_TRIPPABLE', `Source is not valid UTF-8 and contains ${loss.count} byte(s) (${values.join(', ')}) that Windows-1252 cannot represent; editing it would silently rewrite them. Convert the file to UTF-8 or replace those bytes, then retry`, {
+        path: sourcePath,
+        encoding: decoded.encoding,
+        byteCount: loss.count,
+        byteValues: values,
+        firstByteOffset: loss.firstOffset,
+    });
+}
 export function decodeSource(input) {
     const bytes = Buffer.from(input);
     let encoding;
     let text;
+    let encodingLoss;
     if (bytes.subarray(0, 3).equals(utf8Bom)) {
         encoding = 'utf8-bom';
         text = bytes.subarray(3).toString('utf8');
@@ -37,16 +83,24 @@ export function decodeSource(input) {
     else {
         encoding = 'windows-1252';
         text = iconv.decode(bytes, 'windows-1252');
+        encodingLoss = findWindows1252Loss(bytes);
     }
-    return { encoding, text, bytes, newline: detectNewline(text) };
+    return {
+        encoding,
+        text,
+        bytes,
+        newline: detectNewline(text),
+        ...(encodingLoss === undefined ? {} : { encodingLoss }),
+    };
 }
 export function encodeSource(text, encoding) {
     if (encoding === 'utf8')
         return Buffer.from(text, 'utf8');
     if (encoding === 'utf8-bom')
         return Buffer.concat([utf8Bom, Buffer.from(text, 'utf8')]);
+    // U+FFFD is what undefined Windows-1252 bytes decode to; iconv-lite would write it back as 0x9D.
     const encoded = iconv.encode(text, 'windows-1252');
-    if (iconv.decode(encoded, 'windows-1252') !== text) {
+    if (text.includes(REPLACEMENT_CHARACTER) || iconv.decode(encoded, 'windows-1252') !== text) {
         throw new ServiceError('SOURCE_ENCODING_UNREPRESENTABLE', 'The edit introduces characters that cannot be represented in the source encoding', { encoding });
     }
     return encoded;

package/dist/hoi4_agent_tools/core/source/parser.js

@@ -2,7 +2,7 @@ import { hasBlockingDiagnostics } from '../diagnostics.js';
 import { ServiceError } from '../result.js';
 import { sha256Bytes } from '../canonical.js';
 import { sourceDocumentCacheKey, sourceDocuments } from './cache.js';
-import { decodeSource, encodeSource } from './encoding.js';
+import { assertSourceEncodingPreserved, decodeSource, encodeSource, } from './encoding.js';
 import { createSourceLineIndex, isTrivia, lexClausewitz, locationFor, } from './lexer.js';
 import { SOURCE_LINE_LIMIT, SOURCE_MAX_BYTES, SOURCE_MAX_NESTING, SourceDiagnosticCollector, } from './limits.js';
 function scalarValue(token) {
@@ -298,6 +298,20 @@ function parseClausewitzUncached(bytes, sourcePath) {
             sourceRevision: sha256Bytes(decoded.bytes),
         };
     }
+    const encodingLoss = decoded.encodingLoss;
+    if (encodingLoss !== undefined) {
+        diagnostics.add(() => ({
+            code: 'SOURCE_ENCODING_NOT_ROUND_TRIPPABLE',
+            severity: 'warning',
+            category: 'syntax',
+            message: 'Source is not valid UTF-8 and contains bytes that Windows-1252 cannot represent; it can be read but any rewrite is refused',
+            location: locationFor(sourcePath, lineIndex, encodingLoss.firstOffset, encodingLoss.firstOffset + 1),
+            details: {
+                byteCount: encodingLoss.count,
+                byteValues: encodingLoss.byteValues.map((value) => `0x${value.toString(16).toUpperCase()}`),
+            },
+        }));
+    }
     const lexed = lexClausewitz(decoded.text, sourcePath, { lineIndex, diagnostics });
     const parser = new Parser(lexed.tokens, decoded.text, sourcePath, lineIndex, diagnostics);
     const root = parser.parseRoot();
@@ -323,6 +337,7 @@ export function assertRewriteSafe(document) {
     }
 }
 export function encodeDocumentText(document, text) {
+    assertSourceEncodingPreserved(document, document.path);
     return encodeSource(text, document.encoding);
 }
 export function assignments(block, key) {

package/dist/hoi4_agent_tools/focus/drift.js

@@ -72,6 +72,40 @@ export function assertFocusPlanAuthority(drift, authority) {
         currentPlanHash: drift.currentPlanHash,
     });
 }
+/**
+ * True when the source changed in meaning after the plan was imported, so regenerating from the
+ * plan would overwrite those changes. A formatting-only change (the source still imports to the
+ * plan's original baseline), a source that already equals the plan, and an unchanged source are not
+ * semantic drift. This is deliberately independent of whether the plan itself was edited: a plan
+ * edit plus an external formatting change reports `conflict`, which is still safe to apply.
+ */
+export function hasSemanticSourceDrift(drift) {
+    if (!drift.sourceChanged)
+        return false;
+    if (drift.status === 'tree_removed')
+        return true;
+    return (drift.currentPlanHash !== drift.importedPlanHash &&
+        drift.currentPlanHash !== drift.savedPlanHash);
+}
+/**
+ * Refuses to regenerate a tree from a plan when the source changed in meaning after the plan was
+ * imported. Applying the plan would overwrite those external changes with stale plan values.
+ * Re-import the source with the inspect tool, reapply the intended change to the fresh plan, and
+ * retry.
+ */
+export function assertNoSemanticSourceDrift(drift, sourcePath) {
+    if (!hasSemanticSourceDrift(drift))
+        return;
+    throw new ServiceError('FOCUS_SOURCE_CHANGED_SINCE_PLAN', 'The focus source changed in meaning after the plan was imported; rewriting from the plan would overwrite those changes. Import the current source with hoi4.focus_inspect, reapply the intended edit to the fresh plan, and retry', {
+        relativePath: sourcePath,
+        status: drift.status,
+        savedSourceHash: drift.savedSourceHash,
+        currentSourceHash: drift.currentSourceHash,
+        savedPlanHash: drift.savedPlanHash,
+        currentPlanHash: drift.currentPlanHash,
+        importedPlanHash: drift.importedPlanHash,
+    });
+}
 export function detectContinuousFocusDrift(savedPlan, currentDocument) {
     const currentSourceHash = sha256Bytes(currentDocument.bytes);
     const savedPlanHash = focusPlanHash(savedPlan);

package/dist/hoi4_agent_tools/focus/service.js

@@ -5,7 +5,7 @@ import { ServiceError } from '../core/result.js';
 import { parseClausewitz } from '../core/source/index.js';
 import { TRANSACTION_MAX_DIAGNOSTICS } from '../core/transaction-limits.js';
 import { PACKAGE_VERSION } from '../version.js';
-import { assertFocusPlanAuthority, detectContinuousFocusDrift, detectFocusDrift, } from './drift.js';
+import { assertFocusPlanAuthority, assertNoSemanticSourceDrift, detectContinuousFocusDrift, detectFocusDrift, } from './drift.js';
 import { importContinuousFocusPalettes, importFocusTrees } from './importer.js';
 import { layoutFocusTree, layoutFocusTreeAsync } from './layout.js';
 import { lintContinuousFocusPalette, lintFocusTree } from './lint.js';
@@ -191,8 +191,11 @@ export class FocusWorkbench {
         const drift = targetCreated
             ? missingTargetDrift(input.plan, document)
             : detectFocusDrift(input.plan, document, input.references);
-        if (!targetCreated)
+        if (!targetCreated) {
+            if (input.onSemanticSourceDrift === 'refuse')
+                assertNoSemanticSourceDrift(drift, input.relativePath);
             assertFocusPlanAuthority(drift, input.authority ?? 'plan');
+        }
         const layout = input.layout ??
             (await layoutFocusTreeAsync(input.plan, input.signal === undefined ? {} : { signal: input.signal }));
         const after = updateFocusTreeSource(document, targetCreated ? undefined : drift.currentSourcePlan, input.plan, layout);
@@ -414,8 +417,11 @@ export class FocusWorkbench {
         const drift = targetCreated
             ? missingTargetDrift(input.plan, document)
             : detectContinuousFocusDrift(input.plan, document);
-        if (!targetCreated)
+        if (!targetCreated) {
+            if (input.onSemanticSourceDrift === 'refuse')
+                assertNoSemanticSourceDrift(drift, input.relativePath);
             assertFocusPlanAuthority(drift, input.authority ?? 'plan');
+        }
         const after = updateContinuousFocusPaletteSource(document, targetCreated ? undefined : drift.currentSourcePlan, input.plan);
         const afterHash = sha256Bytes(after);
         const operationId = deterministicId('continuous_focus_change', {

package/dist/hoi4_agent_tools/focus/tool-operations.js

@@ -147,6 +147,7 @@ export async function prepareFocusRewrite(engine, workbench, input, context) {
             plan,
             createIfMissing,
             authority: 'plan',
+            onSemanticSourceDrift: 'refuse',
             ...(context.principal === undefined ? {} : { principal: context.principal }),
             artifacts: reviewArtifacts,
             readDependencies: readDependenciesFromScannedFiles(snapshot.files),
@@ -301,6 +302,7 @@ export async function prepareFocusRewrite(engine, workbench, input, context) {
         plan,
         createIfMissing,
         authority: 'plan',
+        onSemanticSourceDrift: 'refuse',
         layout: proposed.layout,
         ...(context.principal === undefined ? {} : { principal: context.principal }),
         index: snapshot.index,

package/dist/hoi4_agent_tools/map/model.js

@@ -4,7 +4,7 @@ import { SymbolIndex } from '../core/index.js';
 import { assertRenderDimensions } from '../core/render-budget.js';
 import { addMapDiagnostic, addMapDiagnostics } from './diagnostic-limit.js';
 import { ServiceError } from '../core/result.js';
-import { assignments, childBlocks, decodeSource, encodeSource, firstScalar, nodeLocation, parseClausewitz, parseLocalisation, } from '../core/source/index.js';
+import { assignments, assertSourceEncodingPreserved, childBlocks, decodeSource, encodeSource, firstScalar, nodeLocation, parseClausewitz, parseLocalisation, } from '../core/source/index.js';
 import { BmpImage, rgbKey } from './bmp.js';
 const defaultMapIndexSourceRoots = {
     map: ['map'],
@@ -119,6 +119,7 @@ export function parseTextDocument(file) {
     return { ...decoded, file, lines };
 }
 export function encodeTextDocument(document, text) {
+    assertSourceEncodingPreserved(document, document.file.displayPath);
     return encodeSource(text, document.encoding);
 }
 function lineLocation(document, line) {

package/dist/hoi4_agent_tools/map/operations.js

@@ -10,8 +10,8 @@ import { planReferenceRemap, ReferenceRemapError } from './references.js';
 import { generateWorld } from './world.js';
 import { resolveEdge } from './world-edge.js';
 import { planMapPositions, planSupplyRebuild } from './derived.js';
-import { buildWorldContext } from './world-context.js';
-import { reconcileWorldOutputs } from './world-outputs.js';
+import { buildWorldContext, countryTagCatalog, WORLD_COUNTRY_TAG_FILE, } from './world-context.js';
+import { planWorldOutputs } from './world-outputs.js';
 import { resolvePartitionMode } from './partition.js';
 import { unsupportedGeographyParts } from './relief/index.js';
 function* cancellationCheckpoint(signal, iteration = 0, stride = 1) {
@@ -41,6 +41,8 @@ async function completeCooperatively(steps, signal) {
         yieldDeadline = performance.now() + 8;
     }
 }
+/** Paths listed per kind in diagnostics and tool results; the artifact lists them all. */
+export const WORLD_OUTPUT_PATH_SAMPLE = 200;
 function normalizeRelative(value) {
     return value.replaceAll('\\', '/').replace(/^\.\//u, '').toLowerCase();
 }
@@ -774,6 +776,7 @@ function proposedChanges(changes) {
 /** Diagnostics an operation raises while applying, drained into the plan after it succeeds. */
 const diagnosticsByPlan = new WeakMap();
 const replacedRootsByPlan = new WeakMap();
+const worldOutputsByPlan = new WeakMap();
 function currentIndex(base, changes) {
     return indexWithProposedChanges(base, proposedChanges(changes), replacedRootsByPlan.get(changes) ?? []);
 }
@@ -3314,6 +3317,20 @@ function applyCreateWorld(base, changes, operation, context, signal) {
         throw new ServiceError('MAP_LOOK_CUSTOM_PALETTE_REQUIRED', 'look "custom" needs colormap.palette with at least one class colour');
     if (colormapProfile === 'legacy' && look !== undefined)
         throw new ServiceError('MAP_LOOK_REQUIRES_CALIBRATED_COLORMAP', 'look selects a calibrated palette; remove colormap.profile "legacy" or look');
+    const workspaceCountries = operation.countries !== undefined && !Array.isArray(operation.countries)
+        ? operation.countries
+        : undefined;
+    const tagCatalog = countryTagCatalog(base);
+    if (workspaceCountries !== undefined) {
+        const declared = new Set(tagCatalog.static);
+        const dynamicTags = new Set(tagCatalog.dynamic);
+        for (const realm of workspaceCountries.realms) {
+            if (dynamicTags.has(realm.tag))
+                throw new ServiceError('MAP_WORLD_REALM_TAG_DYNAMIC', `${realm.tag} is a dynamic tag; a world can only place countries with static tags`, { tag: realm.tag });
+            if (!declared.has(realm.tag))
+                throw new ServiceError('MAP_WORLD_REALM_TAG_UNKNOWN', `No active common/country_tags file other than the generated world's declares ${realm.tag}`, { tag: realm.tag });
+        }
+    }
     const partitionMode = resolvePartitionMode(operation.partition, hasGeography);
     if (partitionMode === 'legacy' && operation.partitionTuning !== undefined)
         throw new ServiceError('MAP_PARTITION_TUNING_REQUIRES_FEATURE_AWARE', 'partitionTuning applies to the feature-aware partition; set partition to "feature-aware" or remove it');
@@ -3332,13 +3349,29 @@ function applyCreateWorld(base, changes, operation, context, signal) {
         provincesPerState: operation.provincesPerState ?? (reference === undefined ? 5 : 12),
         landProvincesPerRegion: operation.landProvincesPerRegion ?? (reference === undefined ? 25 : 60),
         seaProvincesPerRegion: operation.seaProvincesPerRegion ?? (reference === undefined ? 10 : 30),
-        countries: operation.countries ??
+        countries: workspaceCountries?.realms.map((realm) => ({
+            tag: realm.tag,
+            name: realm.tag,
+            ...(realm.weight === undefined ? {} : { share: realm.weight }),
+        })) ??
+            operation.countries ??
             reference?.countries ?? [
             { tag: 'X01', name: 'Aster' },
             { tag: 'X02', name: 'Brum' },
             { tag: 'X03', name: 'Corvel' },
             { tag: 'X04', name: 'Doran' },
         ],
+        ...(workspaceCountries === undefined
+            ? {}
+            : {
+                realms: {
+                    list: workspaceCountries.realms,
+                    ...(workspaceCountries.unowned === undefined
+                        ? {}
+                        : { unowned: workspaceCountries.unowned }),
+                    islands: workspaceCountries.islands ?? 'nearest',
+                },
+            }),
         ...(reference === undefined
             ? {}
             : {
@@ -3398,7 +3431,7 @@ function applyCreateWorld(base, changes, operation, context, signal) {
     for (const file of world.files)
         addChange(changes, file.relativePath, file.content, operation.id, file.mediaType);
     // Remove only unchanged outputs recorded by a previous generation, before indexing new IDs.
-    for (const file of reconcileWorldOutputs(base.sourceFiles, proposedChanges(changes), operation.id, mapRoot, base.sourceRoots.states, base.sourceRoots.localisation))
+    for (const file of planWorldOutputs(base.sourceFiles, proposedChanges(changes), operation.id, mapRoot, base.sourceRoots.states, base.sourceRoots.localisation, { releaseCountryOutputs: workspaceCountries !== undefined }).changes)
         if (file.content === null)
             addChange(changes, file.relativePath, null, operation.id, 'text/plain');
     // Start from empty derived files so no base-game position or supply line survives.
@@ -3418,8 +3451,16 @@ function applyCreateWorld(base, changes, operation, context, signal) {
     const positioned = currentIndex(base, changes);
     for (const file of planSupplyRebuild(positioned, { mode: 'replace' }))
         addChange(changes, file.relativePath, file.content, operation.id, 'text/plain');
-    for (const file of reconcileWorldOutputs(base.sourceFiles, proposedChanges(changes), operation.id, mapRoot, base.sourceRoots.states, base.sourceRoots.localisation))
+    const outputs = planWorldOutputs(base.sourceFiles, proposedChanges(changes), operation.id, mapRoot, base.sourceRoots.states, base.sourceRoots.localisation, { releaseCountryOutputs: workspaceCountries !== undefined });
+    for (const file of outputs.changes)
         addChange(changes, file.relativePath, file.content, operation.id, file.mediaType ?? 'text/plain');
+    worldOutputsByPlan.set(changes, {
+        operationId: operation.id,
+        written: outputs.written,
+        retired: outputs.retired,
+        released: outputs.released,
+        ...(world.realms === undefined ? {} : { realms: world.realms }),
+    });
     return [
         ...(reference?.diagnostics ?? []).map((message) => ({
             code: 'MAP_REFERENCE_INTERPRETATION',
@@ -3448,6 +3489,24 @@ function applyCreateWorld(base, changes, operation, context, signal) {
                     details: { warningCount: world.warnings.length, samples: world.warnings.slice(0, 5) },
                 },
             ]),
+        worldOutputsDiagnostic(operation.id, outputs),
+        ...worldTagDiagnostics(operation.id, tagCatalog, world, workspaceCountries !== undefined),
+        ...worldRealmDiagnostics(operation.id, world),
+        ...(outputs.released.length === 0
+            ? []
+            : [
+                {
+                    code: 'MAP_WORLD_OUTPUT_RELEASED',
+                    severity: 'info',
+                    category: 'map',
+                    operationId: operation.id,
+                    message: `${outputs.released.length} edited country file(s) of the previous world are left to the workspace and no longer recorded as generated`,
+                    details: {
+                        count: outputs.released.length,
+                        files: outputs.released.slice(0, WORLD_OUTPUT_PATH_SAMPLE),
+                    },
+                },
+            ]),
         {
             code: 'MAP_WORLD_CREATED',
             severity: 'info',
@@ -3470,6 +3529,107 @@ function applyCreateWorld(base, changes, operation, context, signal) {
             ]),
     ];
 }
+/** Tag count observed to overflow the flag sheet of one 1.19 Windows build; never a block. */
+export const WORLD_TAG_COUNT_OBSERVED_LIMIT = 439;
+function worldTagDiagnostics(operationId, catalog, world, workspaceOwned) {
+    const declared = new Set(catalog.static);
+    const generated = workspaceOwned
+        ? 0
+        : worldGeneratedTags(world).filter((tag) => !declared.has(tag)).length;
+    const total = declared.size + generated + catalog.dynamic.length;
+    const details = {
+        static: declared.size + generated,
+        generated,
+        dynamic: catalog.dynamic.length,
+        total,
+        observedLimit: WORLD_TAG_COUNT_OBSERVED_LIMIT,
+    };
+    return [
+        {
+            code: 'MAP_WORLD_TAG_COUNT',
+            severity: 'info',
+            category: 'map',
+            operationId,
+            message: `After this write ${total} country tags are declared: ${details.static} static (${generated} written by the world) and ${details.dynamic} dynamic`,
+            details,
+        },
+        ...(total <= WORLD_TAG_COUNT_OBSERVED_LIMIT
+            ? []
+            : [
+                {
+                    code: 'MAP_WORLD_TAG_COUNT_HIGH',
+                    severity: 'warning',
+                    category: 'map',
+                    operationId,
+                    message: `${total} country tags exceed ${WORLD_TAG_COUNT_OBSERVED_LIMIT}, the count at which one measured game build overflowed its flag sheet`,
+                    details,
+                },
+            ]),
+    ];
+}
+/** Tags of the country files a generated world writes. */
+function worldGeneratedTags(world) {
+    const file = world.files.find(({ relativePath }) => relativePath === WORLD_COUNTRY_TAG_FILE);
+    if (file === undefined)
+        return [];
+    return [
+        ...new Set([...file.content.toString('utf8').matchAll(/^([A-Z][A-Z0-9]{2}) =/gmu)].map((match) => match[1])),
+    ];
+}
+function worldRealmDiagnostics(operationId, world) {
+    if (world.realms === undefined)
+        return [];
+    const { countries, unownedStates } = world.realms;
+    return [
+        {
+            code: 'MAP_WORLD_REALMS_PLACED',
+            severity: 'info',
+            category: 'map',
+            operationId,
+            message: `Placed ${countries.length} workspace countries; their country files, histories, flags and names stay the workspace's`,
+            details: {
+                countries: countries
+                    .slice(0, 100)
+                    .map(({ tag, capitalState, states, landShare, targetShare }) => ({
+                    tag,
+                    capitalState,
+                    states: states.length,
+                    landShare,
+                    targetShare,
+                })),
+                truncated: countries.length > 100,
+            },
+        },
+        ...(unownedStates.length === 0
+            ? []
+            : [
+                {
+                    code: 'MAP_WORLD_STATE_UNOWNED',
+                    severity: 'info',
+                    category: 'map',
+                    operationId,
+                    message: `${unownedStates.length} state(s) have no owner, as the request asks; whether the game build accepts unowned land is for the mod to verify`,
+                    details: { count: unownedStates.length, states: unownedStates.slice(0, 200) },
+                },
+            ]),
+    ];
+}
+function worldOutputsDiagnostic(operationId, outputs) {
+    return {
+        code: 'MAP_WORLD_OUTPUTS_RECONCILED',
+        severity: 'info',
+        category: 'map',
+        operationId,
+        message: `The world records ${outputs.written.length} generated file(s), retires ${outputs.retired.length} earlier output(s) it no longer writes and releases ${outputs.released.length} to the workspace`,
+        details: {
+            written: outputs.written.length,
+            retired: outputs.retired.length,
+            released: outputs.released.length,
+            retiredFiles: outputs.retired.slice(0, WORLD_OUTPUT_PATH_SAMPLE),
+            truncated: outputs.retired.length > WORLD_OUTPUT_PATH_SAMPLE,
+        },
+    };
+}
 function applyRegenerateMapPositions(base, changes, operation) {
     const index = currentIndex(base, changes);
     for (const file of planMapPositions(index, operation))
@@ -3567,6 +3727,7 @@ function* planMapOperationSteps(base, operations, signal, context = {}) {
     const allocations = [];
     let expectedChangedBounds;
     const manifestOperations = [];
+    const worldOutputs = [];
     const ids = new Set();
     for (const [operationIndex, operation] of operations.entries()) {
         yield* cancellationCheckpoint(signal, operationIndex);
@@ -3596,8 +3757,13 @@ function* planMapOperationSteps(base, operations, signal, context = {}) {
         const allocationsCheckpoint = allocations.length;
         const boundsCheckpoint = expectedChangedBounds;
         try {
-            if (operation.kind === 'create_world')
+            if (operation.kind === 'create_world') {
                 diagnostics.push(...applyCreateWorld(base, changes, operation, context, signal));
+                const outputs = worldOutputsByPlan.get(changes);
+                worldOutputsByPlan.delete(changes);
+                if (outputs !== undefined)
+                    worldOutputs.push(outputs);
+            }
             else if (operation.kind === 'move_state_provinces')
                 applyMoveStateProvinces(base, changes, operation);
             else if (operation.kind === 'update_state')
@@ -3674,6 +3840,7 @@ function* planMapOperationSteps(base, operations, signal, context = {}) {
         ...(expectedChangedBounds === undefined ? {} : { expectedChangedBounds }),
         finalIndex,
         operations: manifestOperations,
+        ...(worldOutputs.length === 0 ? {} : { worldOutputs }),
     };
 }
 export function planMapOperations(base, operations, signal, context = {}) {

package/dist/hoi4_agent_tools/map/reference-preparation.js

@@ -248,8 +248,11 @@ export async function prepareReferenceWorld(resolver, workspaceId, operation, pr
         return id === 0 ? undefined : id;
     };
     let countries;
-    if (operation.countries !== undefined)
+    if (Array.isArray(operation.countries))
         countries = operation.countries;
+    // Workspace-owned countries are placed from their own points; the picture's colours are unused.
+    else if (operation.countries !== undefined)
+        countries = [];
     else if (surface.inferredCountries.length > 1) {
         countries = surface.inferredCountries.slice(0, 200).map((country, index) => ({
             tag: `X${(index + 1).toString(36).toUpperCase().padStart(2, '0')}`,

package/dist/hoi4_agent_tools/map/service.js

@@ -1297,6 +1297,21 @@ export class AgentNudger {
         writes.push(...(await this.geographyArtifacts(prepared, options.signal, budget)));
         for (const [ordinal, imported] of prepared.imports.entries())
             writes.push(...(await buildImportArtifacts(imported, ordinal)));
+        if (plan.worldOutputs !== undefined)
+            writes.push({
+                name: 'map-world-outputs.json',
+                mimeType: 'application/json',
+                content: `${canonicalJson({ schemaVersion: 1, worlds: plan.worldOutputs.map(({ realms: _realms, ...outputs }) => outputs) })}\n`,
+                provenance,
+            });
+        const realmWorlds = (plan.worldOutputs ?? []).flatMap(({ operationId, realms }) => realms === undefined ? [] : [{ operationId, ...realms }]);
+        if (realmWorlds.length > 0)
+            writes.push({
+                name: 'map-world-realms.json',
+                mimeType: 'application/json',
+                content: `${canonicalJson({ schemaVersion: 1, worlds: realmWorlds })}\n`,
+                provenance,
+            });
         const generatedWorlds = generatedWorldOperationIds(plan);
         if (generatedWorlds.size > 0)
             writes.push(...(await buildWorldPreviewArtifacts({