hoi4-agent-tools 4.3.0 → 4.4.0

package/dist/hoi4_agent_tools/map/service.js

@@ -16,10 +16,49 @@ import { MAP_PROVINCE_GEOMETRY_SELECTOR_LIMIT, MAP_SELECTED_OFFSET_BYTES, MAP_SE
 import { defaultMapSelectorValue, MapWorkspaceIndex, } from './model.js';
 import { planMapOperationsAsync, } from './operations.js';
 import { prepareReferenceWorld } from './reference-preparation.js';
+import { buildImportArtifacts, buildImportReport, } from './reference-import.js';
+import { buildGeographyArtifacts } from './geography/preview.js';
+import { operationHasGeography, prepareGeography, } from './geography/preparation.js';
 import { WORLD_OUTPUT_MANIFEST } from './world-outputs.js';
 import { renderMap, renderMapDiff, } from './render.js';
 import { validateMapAsync } from './validation.js';
 import { buildWorldPreviewArtifacts, generatedWorldOperationIds } from './world-preview.js';
+/**
+ * Evidence of an imported reference: registered sheets, an exact or frame-fitted picture, or a
+ * geography model beside the picture. Plain pictures keep their previous output.
+ */
+function importEvidence(operation, loaded, geography) {
+    const reference = operation.reference;
+    if (reference === undefined ||
+        (loaded.registration === undefined &&
+            geography === undefined &&
+            reference.fit !== 'frame' &&
+            reference.paletteMatch !== 'exact'))
+        return undefined;
+    const seed = operation.seed ?? 1;
+    const built = buildImportReport({
+        operationId: operation.id,
+        surface: loaded.prepared.surface,
+        seed,
+        ...(loaded.registration === undefined ? {} : { registration: loaded.registration }),
+        ...(geography === undefined ? {} : { geography: geography.geography }),
+        ...(reference.agreement === undefined ? {} : { thresholds: reference.agreement }),
+    });
+    return {
+        diagnostics: built.diagnostics,
+        prepared: {
+            report: built.report,
+            surface: loaded.prepared.surface,
+            ...(loaded.previewBytes === undefined ? {} : { registered: loaded.previewBytes }),
+            ...(geography === undefined ? {} : { geography: geography.geography }),
+            seed,
+            sourceHashes: Object.fromEntries([...loaded.images.map(({ source }) => source), ...loaded.documents].map((evidence) => [
+                evidence.displayPath,
+                evidence.sha256,
+            ])),
+        },
+    };
+}
 function compareNumbers(left, right) {
     return left - right;
 }
@@ -404,16 +443,30 @@ function sourceTextPatterns(roots) {
         }),
     ];
 }
-function provinceBitmapPatterns(defaultMaps, mapRoots) {
+const PROVINCE_BITMAP_SELECTORS = [
+    ['provinces', 'provinces.bmp'],
+    ['heightmap', 'heightmap.bmp'],
+];
+// Border quality (opt-in) also reads the river and terrain bitmaps in the main snapshot.
+const BORDER_BITMAP_SELECTORS = [
+    ['provinces', 'provinces.bmp'],
+    ['heightmap', 'heightmap.bmp'],
+    ['rivers', 'rivers.bmp'],
+    ['terrain', 'terrain.bmp'],
+];
+const APPEARANCE_BITMAP_SELECTORS = [
+    ['terrain', 'terrain.bmp'],
+    ['rivers', 'rivers.bmp'],
+    ['tree_definition', 'trees.bmp'],
+];
+function provinceBitmapPatterns(defaultMaps, mapRoots, selectors = PROVINCE_BITMAP_SELECTORS) {
     const activeByPath = new Map(defaultMaps
         .filter(({ shadowedBy }) => shadowedBy === undefined)
         .map((file) => [file.relativePath.replaceAll('\\', '/').toLowerCase(), file]));
-    // The province bitmap, and the heightmap that gives generated positions their height.
+    // The province bitmap, and the heightmap that gives generated positions their height. Border
+    // naturalness (opt-in) also reads the river and terrain bitmaps.
     const names = new Set();
-    for (const [selector, fallback] of [
-        ['provinces', 'provinces.bmp'],
-        ['heightmap', 'heightmap.bmp'],
-    ]) {
+    for (const [selector, fallback] of selectors) {
         let activeName = fallback;
         for (const root of mapRoots) {
             const relativePath = `${normalizeSourceRoot(root)}/default.map`.toLowerCase();
@@ -572,7 +625,7 @@ export class AgentNudger {
         this.scanner = this.engine.scanner;
         this.transactions = this.engine.transactions;
     }
-    async scan(workspaceId, principal, signal, includeExternalScriptReferences = false, includeWorldContext = false) {
+    async scan(workspaceId, principal, signal, includeExternalScriptReferences = false, includeWorldContext = false, includeAppearance = false) {
         signal?.throwIfAborted();
         const workspace = this.resolver.get(workspaceId, principal);
         const sourceRoots = {
@@ -581,7 +634,7 @@ export class AgentNudger {
             localisation: workspace.registration.roots.localisation,
         };
         const selectorSnapshot = await this.engine.scan(workspaceId, { patterns: defaultMapPatterns(sourceRoots) }, principal, signal);
-        const bitmapPatterns = provinceBitmapPatterns(selectorSnapshot.files, sourceRoots.map);
+        const bitmapPatterns = provinceBitmapPatterns(selectorSnapshot.files, sourceRoots.map, includeAppearance ? BORDER_BITMAP_SELECTORS : PROVINCE_BITMAP_SELECTORS);
         const contentSnapshot = await this.engine.scan(workspaceId, { patterns: [...sourceTextPatterns(sourceRoots), ...bitmapPatterns] }, principal, signal);
         const locatorSnapshot = await this.engine.scan(workspaceId, { patterns: ['**/*.asset'], rootKinds: ['mod', 'fixture'] }, principal, signal);
         const externalScriptSnapshot = includeExternalScriptReferences
@@ -614,12 +667,30 @@ export class AgentNudger {
                 ],
             }, principal, signal)
             : undefined;
+        // Appearance validation reads the bitmaps and colour maps the mod itself ships.
+        const appearanceSnapshot = includeAppearance
+            ? await this.engine.scan(workspaceId, {
+                rootKinds: ['mod', 'fixture'],
+                patterns: [
+                    ...provinceBitmapPatterns(selectorSnapshot.files, sourceRoots.map, APPEARANCE_BITMAP_SELECTORS),
+                    ...sourceRoots.map.flatMap((root) => {
+                        const normalized = normalizeSourceRoot(root);
+                        return [
+                            `${normalized}/cities.bmp`,
+                            `${normalized}/world_normal.bmp`,
+                            `${normalized}/terrain/colormap_*.dds`,
+                        ];
+                    }),
+                ],
+            }, principal, signal)
+            : undefined;
         signal?.throwIfAborted();
         const files = [
             ...contentSnapshot.files,
             ...locatorSnapshot.files,
             ...(externalScriptSnapshot?.files ?? []),
             ...(worldContextSnapshot?.files ?? []).filter((file) => !contentSnapshot.files.some((existing) => existing.displayPath === file.displayPath)),
+            ...(appearanceSnapshot?.files ?? []).filter((file) => ![...contentSnapshot.files, ...(worldContextSnapshot?.files ?? [])].some((existing) => existing.displayPath === file.displayPath)),
             ...(generatedOutputsSnapshot?.files ?? []).filter((file) => ![...contentSnapshot.files, ...(worldContextSnapshot?.files ?? [])].some((existing) => existing.displayPath === file.displayPath)),
         ].sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
         const revision = hashCanonical(files.map(({ displayPath, loadOrder, sha256 }) => ({ displayPath, loadOrder, sha256 })));
@@ -630,8 +701,8 @@ export class AgentNudger {
             index: MapWorkspaceIndex.build(files, sourceRoots, SymbolIndex.build(files)),
         };
     }
-    async validate(workspaceId, principal, signal, scripts = false) {
-        const snapshot = await this.scan(workspaceId, principal, signal, scripts);
+    async validate(workspaceId, principal, signal, scripts = false, includeAppearance = false) {
+        const snapshot = await this.scan(workspaceId, principal, signal, scripts, false, includeAppearance);
         const validation = await validateMapAsync(snapshot.index, signal === undefined ? {} : { signal });
         if (!scripts)
             return { snapshot, validation };
@@ -663,6 +734,7 @@ export class AgentNudger {
             'remapReferences' in operation), operations.some((operation) => operation.kind === 'create_world'));
         const referenceWorlds = new Map();
         const referenceImages = [];
+        const referenceLoads = new Map();
         for (const operation of operations) {
             if (operation.kind !== 'create_world' || operation.reference === undefined)
                 continue;
@@ -670,18 +742,51 @@ export class AgentNudger {
             referenceWorlds.set(operation.id, loaded.prepared);
             referenceImages.push({
                 operationId: operation.id,
-                bytes: loaded.images[0].bytes,
+                // A registered drawing is shown as it lies in the world frame, not as drawn.
+                bytes: loaded.previewBytes ?? loaded.images[0].bytes,
                 source: loaded.images[0].source,
             });
-            for (const image of loaded.images) {
+            referenceLoads.set(operation.id, loaded);
+            for (const evidence of [...loaded.images.map(({ source }) => source), ...loaded.documents]) {
+                snapshot.referenceSources ??= [];
+                const previous = snapshot.referenceSources.findIndex((file) => file.displayPath === evidence.displayPath);
+                if (previous < 0)
+                    snapshot.referenceSources.push(evidence);
+                else
+                    snapshot.referenceSources[previous] = evidence;
+            }
+        }
+        const geographyModels = new Map();
+        for (const operation of operations) {
+            if (operation.kind !== 'create_world' || !operationHasGeography(operation))
+                continue;
+            const geography = await prepareGeography(this.resolver, workspaceId, operation, principal, signal);
+            geographyModels.set(operation.id, geography);
+            if (geography.source.kind === 'file') {
+                const evidence = geography.source.evidence;
                 snapshot.referenceSources ??= [];
-                const previous = snapshot.referenceSources.findIndex((file) => file.displayPath === image.source.displayPath);
+                const previous = snapshot.referenceSources.findIndex((file) => file.displayPath === evidence.displayPath);
                 if (previous < 0)
-                    snapshot.referenceSources.push(image.source);
+                    snapshot.referenceSources.push(evidence);
                 else
-                    snapshot.referenceSources[previous] = image.source;
+                    snapshot.referenceSources[previous] = evidence;
             }
         }
+        // An imported reference reports what it supplied and how far the model agrees with it.
+        const imports = [];
+        const importDiagnostics = [];
+        for (const operation of operations) {
+            if (operation.kind !== 'create_world')
+                continue;
+            const loaded = referenceLoads.get(operation.id);
+            if (loaded === undefined)
+                continue;
+            const built = importEvidence(operation, loaded, geographyModels.get(operation.id));
+            if (built === undefined)
+                continue;
+            imports.push(built.prepared);
+            importDiagnostics.push(...built.diagnostics);
+        }
         snapshot.files.sort((left, right) => left.loadOrder - right.loadOrder || compareCodeUnits(left.displayPath, right.displayPath));
         snapshot.revision = hashCanonical(mapSourceEvidence(snapshot).map(({ displayPath, loadOrder, sha256 }) => ({
             displayPath,
@@ -690,15 +795,24 @@ export class AgentNudger {
         })));
         const plan = await planMapOperationsAsync(snapshot.index, operations, signal, {
             referenceWorlds,
+            geographyModels,
         });
+        // Model diagnostics (including warnings of a model that is otherwise usable) travel with the plan.
+        for (const geography of geographyModels.values())
+            plan.diagnostics.push(...geography.diagnostics);
+        plan.diagnostics.push(...importDiagnostics);
         const newWorld = operations.some(({ kind }) => kind === 'create_world');
         const freshWorld = newWorld && snapshot.index.provinceBitmapFile?.rootKind !== 'mod';
         const baselineValidation = freshWorld
             ? { passed: true, diagnostics: [], checks: [] }
             : await validateMapAsync(snapshot.index, signal === undefined ? {} : { signal });
         // A new world has nothing to compare its bitmap format and pixels with.
+        const worldOperation = operations.find((operation) => operation.kind === 'create_world');
         const rawValidation = await validateMapAsync(plan.finalIndex, {
             ...(newWorld ? {} : { baseline: snapshot.index }),
+            ...(worldOperation?.kind === 'create_world' && worldOperation.edge !== undefined
+                ? { edgeMode: worldOperation.edge.mode ?? 'sea-band' }
+                : {}),
             ...(signal === undefined ? {} : { signal }),
             ...(plan.expectedChangedBounds === undefined
                 ? {}
@@ -718,6 +832,8 @@ export class AgentNudger {
             plan,
             validation: validationWithPlan(attributedValidation, plan),
             referenceImages,
+            geography: [...geographyModels.values()],
+            imports,
         };
     }
     async plan(input) {
@@ -796,7 +912,7 @@ export class AgentNudger {
         return { transaction, plan, validation };
     }
     async renderAndStore(workspaceId, options = {}) {
-        const snapshot = await this.scan(workspaceId, options.principal, options.signal);
+        const snapshot = await this.scan(workspaceId, options.principal, options.signal, false, false, options.overlays?.includes('border-quality') === true);
         const rawBundle = await renderMap(snapshot.index, {
             ...options,
             budget: options.budget ?? new RenderBudget(),
@@ -892,6 +1008,61 @@ export class AgentNudger {
                     artifact.name.endsWith('.chunks.json'))))),
         };
     }
+    async geographyArtifacts(prepared, signal, budget) {
+        const writes = [];
+        for (const [ordinal, geography] of prepared.geography.entries())
+            writes.push(...(await buildGeographyArtifacts({
+                prepared: geography,
+                ordinal,
+                sourceHashes: geography.source.kind === 'file'
+                    ? { [geography.source.evidence.displayPath]: geography.source.sha256 }
+                    : { 'inline:geography': geography.source.sha256 },
+                ...(budget === undefined ? {} : { budget }),
+                ...(signal === undefined ? {} : { signal }),
+            })));
+        return writes;
+    }
+    /**
+     * Validate and draw the geography model of every `create_world` operation without scanning or
+     * planning the map: the review step before any synthesis. Nothing in the mod changes.
+     */
+    async previewGeographyModels(input) {
+        input.signal?.throwIfAborted();
+        const geography = [];
+        const imports = [];
+        const importDiagnostics = [];
+        const referenceFiles = [];
+        for (const operation of input.operations) {
+            if (operation.kind !== 'create_world' || !operationHasGeography(operation))
+                continue;
+            const prepared = await prepareGeography(this.resolver, input.workspaceId, operation, input.principal, input.signal);
+            geography.push(prepared);
+            // The drawing beside the model is registered and compared too, without planning a map.
+            if (operation.reference === undefined)
+                continue;
+            const loaded = await prepareReferenceWorld(this.resolver, input.workspaceId, operation, input.principal, input.signal);
+            referenceFiles.push(...[...loaded.images.map(({ source }) => source), ...loaded.documents].map(({ displayPath }) => displayPath));
+            const built = importEvidence(operation, loaded, prepared);
+            if (built === undefined)
+                continue;
+            imports.push(built.prepared);
+            importDiagnostics.push(...built.diagnostics);
+        }
+        const writes = await this.geographyArtifacts({ geography }, input.signal, new RenderBudget());
+        for (const [ordinal, imported] of imports.entries())
+            writes.push(...(await buildImportArtifacts(imported, ordinal)));
+        const artifacts = await this.artifacts.withAtomicChunkedWrites(this.resolver.get(input.workspaceId, input.principal), writes, (stored) => Promise.resolve([...stored]), input.signal);
+        return {
+            geography,
+            imports: imports.map(({ report }) => report),
+            importDiagnostics,
+            artifacts,
+            filesScanned: [
+                ...geography.flatMap(({ source }) => source.kind === 'file' ? [source.evidence.displayPath] : []),
+                ...referenceFiles,
+            ],
+        };
+    }
     async renderPreparedDiffAndStore(prepared, operations, options) {
         const budget = new RenderBudget();
         const { snapshot, plan, validation } = prepared;
@@ -954,6 +1125,7 @@ export class AgentNudger {
             };
             const artifacts = await this.artifacts.withAtomicChunkedWrites(this.resolver.get(snapshot.workspaceId, options.principal), [
                 report,
+                ...(await this.geographyArtifacts(prepared, options.signal, budget)),
                 {
                     name: 'map-generation-failure.json',
                     mimeType: 'application/json',
@@ -1122,6 +1294,9 @@ export class AgentNudger {
                 content: beforeBundle.html,
                 provenance: comparisonProvenance('before'),
             });
+        writes.push(...(await this.geographyArtifacts(prepared, options.signal, budget)));
+        for (const [ordinal, imported] of prepared.imports.entries())
+            writes.push(...(await buildImportArtifacts(imported, ordinal)));
         const generatedWorlds = generatedWorldOperationIds(plan);
         if (generatedWorlds.size > 0)
             writes.push(...(await buildWorldPreviewArtifacts({

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

@@ -1,12 +1,18 @@
 import { boundedSourceHashEvidence, publicArtifactLink, } from '../core/artifacts.js';
 import { canonicalJson, hashCanonical } from '../core/canonical.js';
 import { diagnosticSeverityCounts } from '../core/diagnostic-rollup.js';
+import { sortDiagnostics } from '../core/diagnostics.js';
 import { autonomousResultArtifacts, } from '../core/transaction-execution.js';
 import { emptyServiceResult, ServiceError } from '../core/result.js';
 import { setInlineFilesScanned } from '../core/operation-result.js';
 import { PACKAGE_VERSION } from '../version.js';
 import { allocateMapIdentifiersAsync, } from './operations.js';
+import { borderQualityDiagnostics } from './border-quality.js';
+import { measureIndexBorderNaturalness, summarizeBorderQuality, } from './border-quality-input.js';
 import { buildMapCatalog, lookupMapCoordinate, searchMapCatalog } from './catalog.js';
+import { GEOGRAPHY_FEATURE_KINDS } from './geography/model.js';
+import { operationHasGeography } from './geography/preparation.js';
+import { unsupportedGeographyParts } from './relief/index.js';
 import { renderMap } from './render.js';
 import { exportProvinceGeometryRowRuns } from './service.js';
 import { generatedWorldOperationIds } from './world-preview.js';
@@ -241,6 +247,35 @@ export function normalizeMapRenderRequest(input) {
 export function normalizeMapRewriteRequest(input) {
     return input;
 }
+/** The figures of an import report an agent needs inline; the full report is an artifact. */
+function importSummary(report) {
+    return {
+        operationId: report.operationId,
+        width: report.width,
+        height: report.height,
+        landPx: report.classes.landPx,
+        seaPx: report.classes.seaPx,
+        lakePx: report.classes.lakePx,
+        ...(report.registration === undefined
+            ? {}
+            : {
+                sheets: report.registration.sheets.length,
+                hiddenSheets: report.registration.sheets
+                    .filter(({ pixels }) => pixels === 0)
+                    .map(({ id }) => id)
+                    .slice(0, 16),
+                uncoveredPx: report.registration.uncoveredPx,
+            }),
+        ...(report.agreement === undefined
+            ? {}
+            : {
+                landIou: report.agreement.landIou,
+                drawingOnlyLandPx: report.agreement.drawingOnlyLandPx,
+                modelOnlyLandPx: report.agreement.modelOnlyLandPx,
+                misplacedFeatures: report.agreement.featureCount,
+            }),
+    };
+}
 export async function prepareMapRewrite(nudger, input, context) {
     await context.progress(0, 5, 'Planning map operations and visual diff');
     const planned = await nudger.planRewriteWithDiff({
@@ -308,8 +343,131 @@ export function completeMapRewrite(workspaceId, execution, recipe) {
     ].slice(0, 100);
     return result;
 }
+const EMPTY_SEMANTIC_DIFF = {
+    definitions: [],
+    stateMembership: [],
+    regionMembership: [],
+    states: [],
+    ports: [],
+    buildingPositions: [],
+    unitPositions: [],
+    weatherPositions: [],
+    entityLocators: [],
+    supplyNodes: [],
+    railways: [],
+    adjacencies: [],
+    normalAdjacencies: [],
+    supplyNodesChanged: false,
+    railwaysChanged: false,
+    adjacenciesChanged: false,
+    normalAdjacenciesChanged: false,
+};
+function geographySummary(prepared) {
+    const counts = Object.fromEntries(GEOGRAPHY_FEATURE_KINDS.map((kind) => [kind, prepared.geography.list(kind).length]));
+    const severities = diagnosticSeverityCounts(prepared.diagnostics);
+    const unsupported = unsupportedGeographyParts(prepared.geography);
+    return {
+        operationId: prepared.operationId,
+        modelHash: prepared.geography.hash,
+        valid: prepared.valid,
+        source: prepared.source.kind,
+        sourceSha256: prepared.source.sha256,
+        width: prepared.frame.width,
+        height: prepared.frame.height,
+        featureCount: prepared.geography.featureCount,
+        pointCount: prepared.geography.pointCount,
+        counts,
+        errorCount: severities.error,
+        warningCount: severities.warning,
+        synthesis: unsupported.length === 0 ? 'available' : 'unavailable',
+        unsupported,
+    };
+}
+/**
+ * Review the geography model of a `create_world` operation: validate it, resolve its ids and areas
+ * and return an overlay and a report. No map is planned or generated and no file changes.
+ */
+async function previewGeographyRewrite(nudger, input, context) {
+    await context.progress(0, 3, 'Validating the geography model and drawing its overlay');
+    const planned = await nudger.previewGeographyModels({
+        workspaceId: context.workspaceId,
+        operations: input.operations,
+        ...(context.principal === undefined ? {} : { principal: context.principal }),
+        ...(context.signal === undefined ? {} : { signal: context.signal }),
+    });
+    const compactSemantic = compactMapSemanticDiff(EMPTY_SEMANTIC_DIFF);
+    const diagnostics = [
+        ...planned.geography.flatMap(({ diagnostics: found }) => found),
+        ...planned.importDiagnostics,
+    ];
+    const ignored = input.operations.filter((operation) => operation.kind !== 'create_world' || !operationHasGeography(operation)).length;
+    const notes = [
+        {
+            code: 'MAP_GEOGRAPHY_PREVIEW_MODEL_ONLY',
+            severity: 'info',
+            category: 'map',
+            message: 'This preview checks the geography model, and the registration and agreement of a reference picture beside it, only: no map was planned and nothing was synthesized. A request without preview builds relief, rivers and lakes from the model, and is blocked while the model declares biomes, climate, fertility or sea ice, which the climate stage does not synthesize yet.',
+        },
+        ...(ignored === 0
+            ? []
+            : [
+                {
+                    code: 'MAP_GEOGRAPHY_PREVIEW_OTHER_OPERATIONS_SKIPPED',
+                    severity: 'info',
+                    category: 'map',
+                    message: `${ignored} other operation(s) in the request were not evaluated by this model preview`,
+                },
+            ]),
+    ];
+    const all = sortDiagnostics([...diagnostics, ...notes]);
+    const valid = planned.geography.every(({ valid: ok }) => ok) &&
+        !planned.importDiagnostics.some(({ severity }) => severity === 'error' || severity === 'blocker');
+    const result = emptyServiceResult(context.workspaceId, {
+        execution: 'preview',
+        allocations: [],
+        operationBlockers: [],
+        expectedChangedBounds: null,
+        changedProvinceIds: [],
+        changedProvinceCount: 0,
+        semanticDiff: compactSemantic.semantic,
+        semanticDiffCounts: compactSemantic.counts,
+        semanticDiffTruncated: compactSemantic.truncated,
+        fileCount: 0,
+        artifactCount: planned.artifacts.length,
+        geography: planned.geography.slice(0, 16).map(geographySummary),
+        ...(planned.imports.length === 0
+            ? {}
+            : { import: planned.imports.slice(0, 16).map(importSummary) }),
+    });
+    result.status = valid ? 'ok' : 'blocked';
+    result.code = valid ? 'MAP_GEOGRAPHY_PREVIEW_READY' : 'MAP_GEOGRAPHY_PREVIEW_BLOCKED';
+    setInlineFilesScanned(result, planned.filesScanned);
+    result.proposedFiles = [];
+    result.diagnostics = all.slice(0, 100);
+    result.artifacts = planned.artifacts.map(publicArtifactLink);
+    result.validation = {
+        passed: valid,
+        checks: [
+            {
+                id: 'geography-model',
+                passed: valid,
+                message: valid
+                    ? 'The geography model resolves without errors'
+                    : 'The geography model has errors; see the MAP_GEOGRAPHY_* diagnostics and map-geography-report.json',
+            },
+        ],
+    };
+    result.blockers = all
+        .filter(({ severity }) => severity === 'error' || severity === 'blocker')
+        .slice(0, 100)
+        .map(({ code, message }) => ({ code, message }));
+    await context.progress(3, 3, 'Geography model preview complete; workspace files were not changed');
+    return result;
+}
 /** Generate and validate the same proposed map without creating a write transaction. */
 export async function previewMapRewrite(nudger, input, context) {
+    if (input.operations.some((operation) => operation.kind === 'create_world' && operationHasGeography(operation)))
+        return previewGeographyRewrite(nudger, input, context);
     await context.progress(0, 5, 'Generating and validating an offline map preview');
     const planned = await nudger.previewRewriteWithDiff({
         workspaceId: context.workspaceId,
@@ -431,8 +589,32 @@ export async function inspectMap(engine, nudger, input, context) {
         await context.progress(3, 3, 'Map lookup complete');
         return result;
     }
-    const { snapshot, validation, scriptReferences } = await nudger.validate(context.workspaceId, context.principal, context.signal, input.references);
+    const { snapshot, validation, scriptReferences } = await nudger.validate(context.workspaceId, context.principal, context.signal, input.references, input.quality);
     const sharedRevision = snapshot.revision;
+    let borderQuality;
+    const qualityDiagnostics = [];
+    if (input.quality) {
+        await context.progress(1, 3, 'Measuring how natural the borders are');
+        try {
+            const measured = await measureIndexBorderNaturalness(snapshot.index, context.signal === undefined ? {} : { signal: context.signal });
+            borderQuality = {
+                report: measured.report,
+                summary: summarizeBorderQuality(measured.report, measured.skipped),
+            };
+            qualityDiagnostics.push(...borderQualityDiagnostics(measured.report));
+        }
+        catch (error) {
+            if (!(error instanceof ServiceError) || !error.code.startsWith('MAP_BORDER_QUALITY_'))
+                throw error;
+            qualityDiagnostics.push({
+                code: 'MAP_BORDER_QUALITY_UNAVAILABLE',
+                severity: 'warning',
+                category: 'map',
+                message: `Border naturalness could not be measured: ${error.message}`,
+                details: { reason: error.code, ...error.details },
+            });
+        }
+    }
     const catalog = buildMapCatalog(snapshot.index);
     const queryMatches = input.query === undefined ? [] : searchMapCatalog(catalog, input.query, input.queryLimit);
     const coordinateMatches = input.coordinates.map((coordinate) => lookupMapCoordinate(snapshot.index, coordinate));
@@ -493,12 +675,33 @@ export async function inspectMap(engine, nudger, input, context) {
                 selected,
                 allocationPreviews,
                 validation,
+                ...(borderQuality === undefined ? {} : { borderQuality: borderQuality.report }),
                 sourceHashes: sourceEvidence.complete,
             })}\n`,
             provenance: inspectionProvenance,
             description: 'Complete searchable map catalog, inspection, validation, selected records, and allocation previews',
         },
     ];
+    if (borderQuality !== undefined)
+        artifactWrites.push({
+            name: `map-border-quality.${snapshot.revision.slice(0, 16)}.json`,
+            mimeType: 'application/json',
+            content: `${canonicalJson({
+                schemaVersion: 1,
+                revision: snapshot.revision,
+                report: borderQuality.report,
+                skippedInputs: borderQuality.summary.skippedInputs,
+                sourceHashes: sourceEvidence.complete,
+            })}\n`,
+            provenance: {
+                kind: 'map-border-quality',
+                toolVersion: PACKAGE_VERSION,
+                schemaVersion: 'map-border-quality.v1',
+                sourceHashes: sourceEvidence.bounded.sourceHashes,
+                metadata: { sharedRevision, sourceHashInventory: sourceEvidence.bounded.inventory },
+            },
+            description: 'Border naturalness: alignment with rivers, slopes, lake shores and terrain changes, enrichment over chance, straightness and the worst artificial runs for each border layer',
+        });
     if (overviewRendered) {
         const overviewLayer = 'state';
         const overviewOverlays = [
@@ -592,10 +795,13 @@ export async function inspectMap(engine, nudger, input, context) {
         unknownProvinceIds: provinceGeometry?.unknownProvinceIds ?? [],
         missingGeometryProvinceIds: provinceGeometry?.missingGeometryProvinceIds ?? [],
         ...(scriptReferences === undefined ? {} : { scriptReferences }),
+        ...(borderQuality === undefined ? {} : { quality: borderQuality.summary }),
     });
     result.code = 'MAP_INSPECTED';
     setInlineFilesScanned(result, snapshot.files.map(({ displayPath }) => displayPath));
-    result.diagnostics = validation.diagnostics.slice(0, 100);
+    result.diagnostics = (qualityDiagnostics.length === 0
+        ? validation.diagnostics
+        : sortDiagnostics([...validation.diagnostics, ...qualityDiagnostics])).slice(0, 100);
     result.artifacts = artifacts.map(publicArtifactLink);
     result.validation = validationSummary(validation);
     await context.progress(3, 3, 'Map inspection complete');

package/dist/hoi4_agent_tools/map/validation.js

@@ -2,6 +2,7 @@ import { setImmediate as yieldToEventLoop } from 'node:timers/promises';
 import { sortDiagnostics } from '../core/diagnostics.js';
 import { assertRenderDimensions } from '../core/render-budget.js';
 import { addActiveMapDiagnostic, addMapDiagnostic } from './diagnostic-limit.js';
+import { validateAppearance } from './appearance-validation.js';
 import { rgbKey } from './bmp.js';
 import { MAP_PROVINCE_ENGINE_MAX_PIXELS } from './model.js';
 const MAP_DIAGNOSTIC_DETAIL_SAMPLE_LIMIT = 100;
@@ -1207,6 +1208,8 @@ function* validateMapSteps(index, options = {}) {
     yield* cancellationCheckpoint(options.signal);
     yield* validatePositions(index, diagnostics, options);
     yield* cancellationCheckpoint(options.signal);
+    yield* validateAppearance(index, (diagnostic) => addDiagnostic(diagnostics, options, { ...diagnostic, category: 'map' }), { signal: options.signal, edgeMode: options.edgeMode });
+    yield* cancellationCheckpoint(options.signal);
     const sorted = sortDiagnostics(diagnostics);
     const checks = [
         {
@@ -1259,6 +1262,12 @@ function* validateMapSteps(index, options = {}) {
                     code.startsWith('MAP_ENTITY_LOCATOR'))),
             message: 'Map positions, ports, and entity locators are valid',
         },
+        {
+            id: 'map-appearance-files',
+            passed: !sorted.some(({ code, severity }) => (severity === 'error' || severity === 'blocker') &&
+                /^MAP_(RIVER|TERRAIN_BITMAP|HEIGHT|TREES|COLORMAP|WATER|NORMAL|CITIES|LAKE|EDGE|SEAM|POLAR)_/u.test(code)),
+            message: 'Heightmap, terrain, river, tree, colour, normal and city bitmaps, lakes and the world edge are valid',
+        },
     ];
     const passed = checks.every((check) => check.passed) &&
         !sorted.some(({ severity }) => severity === 'error' || severity === 'blocker');