hoi4-agent-tools 4.5.0 → 4.6.1

package/dist/hoi4_agent_tools/map/relief/macro-relief.js

@@ -478,6 +478,112 @@ function applyVolcano(volcano, base, kind, mw, mh, scale, seed, targets) {
         }
 }
 // ---------------------------------------------------------------------------------------------
+/**
+ * A declared pass is authoritative over the other relief (ADR 0072). The saddle of a range's
+ * envelope is lowered by the range alone; a volcano cone, a plateau or a neighbouring range that
+ * overlaps the pass adds height back and the gap disappears. After everything is composed, the
+ * heights along the pass corridor are capped at the saddle level (base plus crest times the
+ * envelope), with a soft edge across the corridor, so the pass is lower than the crest on both
+ * sides wherever it lies.
+ */
+function carvePassSaddles(geography, tables, heights, kind, mw, mh) {
+    const aspect = mh / mw;
+    // The line of every range in cell units, one point per table entry, with its footprint.
+    const lines = new Map();
+    for (const range of geography.ranges) {
+        const table = tables.find((candidate) => candidate.id === range.id);
+        if (table === undefined)
+            continue;
+        const x = new Float64Array(table.count);
+        const y = new Float64Array(table.count);
+        let widest = 0;
+        for (let j = 0; j < table.count; j += 1) {
+            const point = sampleAlong(range.path, geography.frame, j / (table.count - 1));
+            x[j] = point.x * mw;
+            y[j] = point.y * mh;
+            widest = Math.max(widest, table.halfWidth[j]);
+        }
+        lines.set(range.id, { x, y, reach: Math.max(2, widest * mw) });
+    }
+    for (const range of geography.ranges) {
+        const table = tables.find((candidate) => candidate.id === range.id);
+        const own = lines.get(range.id);
+        if (table === undefined || own === undefined)
+            continue;
+        const lineX = own.x;
+        const lineY = own.y;
+        for (const entry of table.passes) {
+            if (entry.depth <= 0)
+                continue;
+            const k = Math.min(table.count - 1, Math.max(0, Math.round(entry.at * (table.count - 1))));
+            // Half-width of the corridor in cells: the range's footprint, at least three cells, plus a
+            // soft edge of three more.
+            const corridor = Math.max(2, table.halfWidth[k] * mw);
+            const edge = 2;
+            const entries = Math.ceil((entry.halfLength / table.length) * (table.count - 1));
+            const first = Math.max(0, k - entries);
+            const last = Math.min(table.count - 1, k + entries);
+            let minX = Infinity;
+            let maxX = -Infinity;
+            let minY = Infinity;
+            let maxY = -Infinity;
+            for (let j = first; j <= last; j += 1) {
+                minX = Math.min(minX, lineX[j]);
+                maxX = Math.max(maxX, lineX[j]);
+                minY = Math.min(minY, lineY[j]);
+                maxY = Math.max(maxY, lineY[j]);
+            }
+            const reach = Math.ceil(corridor + edge) + 1;
+            const x0 = Math.max(0, Math.floor(minX) - reach);
+            const x1 = Math.min(mw - 1, Math.ceil(maxX) + reach);
+            const y0 = Math.max(0, Math.floor(minY) - reach);
+            const y1 = Math.min(mh - 1, Math.ceil(maxY) + reach);
+            const baseLevel = table.base[k];
+            const crestLevel = table.crest[k];
+            for (let y = y0; y <= y1; y += 1)
+                for (let x = x0; x <= x1; x += 1) {
+                    const cell = y * mw + x;
+                    if (kind[cell] !== LAND)
+                        continue;
+                    // The nearest point of the range line, which must lie inside the pass window.
+                    let nearest = -1;
+                    let nearestDistance = Infinity;
+                    for (let j = 0; j < table.count; j += 1) {
+                        const distance = Math.hypot(lineX[j] - (x + 0.5), lineY[j] - (y + 0.5));
+                        if (distance < nearestDistance) {
+                            nearestDistance = distance;
+                            nearest = j;
+                        }
+                    }
+                    if (nearest < first || nearest > last || nearestDistance > corridor + edge)
+                        continue;
+                    // A cell on the body of another range belongs to that range, not to this pass.
+                    let onOther = false;
+                    for (const [id, other] of lines) {
+                        if (id === range.id)
+                            continue;
+                        for (let j = 0; j < other.x.length && !onOther; j += 1)
+                            if (Math.hypot(other.x[j] - (x + 0.5), other.y[j] - (y + 0.5)) <= other.reach)
+                                onOther = true;
+                        if (onOther)
+                            break;
+                    }
+                    if (onOther)
+                        continue;
+                    const along = ((nearest - k) / (table.count - 1)) * table.length;
+                    const s = (along * along) / (entry.halfLength * entry.halfLength);
+                    if (s >= 1)
+                        continue;
+                    const bump = (1 - s) * (1 - s);
+                    const cap = baseLevel + (crestLevel - baseLevel) * (1 - entry.depth * bump);
+                    const weight = nearestDistance <= corridor ? 1 : 1 - smoothstep((nearestDistance - corridor) / edge);
+                    if (cap < heights[cell])
+                        heights[cell] = heights[cell] + (cap - heights[cell]) * weight;
+                }
+        }
+    }
+    void aspect;
+}
 /** Build the macro relief of the model. */
 export function synthesizeMacroRelief(input) {
     const { geography, width, height, seed } = input;
@@ -519,6 +625,7 @@ export function synthesizeMacroRelief(input) {
         heights[index] = Math.min(HEIGHT_CEILING, heights[index] + targets.delta[index]);
         footprint[index] = Math.max(footprint[index], targets.footprint[index]);
     }
+    carvePassSaddles(geography, ranges, heights, kind, mw, mh);
     return {
         width: mw,
         height: mh,

package/dist/hoi4_agent_tools/map/relief/terrain-synthesis.js

@@ -85,6 +85,58 @@ function barrierField(width, height, kind, heights, riverBitmap, macro, signal)
     }
     return { width, height, strength, sources };
 }
+/**
+ * Run the macro relief and the hydrology only, which is where a model's rivers fail to reach
+ * their mouths, and return their notes. The full-resolution heights, river pixels and fields are
+ * not built, so a model can be checked in a fraction of a write. A river that cannot reach its
+ * mouth throws as in `synthesizeTerrain`, with every failing river in its details.
+ */
+export function checkTerrainRivers(input) {
+    const { geography, width, height, seed, kind } = input;
+    const relief = { ...DEFAULT_RELIEF, ...input.relief };
+    let landPixels = 0;
+    for (let index = 0; index < width * height; index += 1)
+        if (kind[index] === LAND)
+            landPixels += 1;
+    const macro = synthesizeMacroRelief({
+        geography,
+        width,
+        height,
+        seed,
+        kind,
+        relief,
+        signal: input.signal,
+    });
+    const adjust = input.adjustHeight;
+    if (adjust !== undefined)
+        for (let y = 0; y < macro.height; y += 1)
+            for (let x = 0; x < macro.width; x += 1) {
+                const cell = y * macro.width + x;
+                if (macro.kind[cell] === LAND)
+                    macro.heights[cell] = adjust(2 * x + 1, 2 * y + 1, macro.heights[cell]);
+            }
+    const hydrology = synthesizeHydrology({
+        geography,
+        macro,
+        seed,
+        density: input.rivers?.density,
+        count: input.rivers?.count,
+        rainfall: input.rainfall,
+        landPixels,
+        signal: input.signal,
+    });
+    const notes = [...hydrology.notes];
+    // The pass test of the write, on the macro grid: a declared pass must be a saddle lower than
+    // the crest on both sides. Only its error is reported, so a preview never blocks on a warning
+    // the full-resolution write would not raise.
+    const quantised = new Uint8Array(macro.width * macro.height);
+    for (let index = 0; index < quantised.length; index += 1)
+        quantised[index] = Math.max(0, Math.min(255, Math.round(hydrology.heights[index])));
+    for (const note of checkRangesAndFeatures(geography, macro.ranges, { width: macro.width, height: macro.height, kind: macro.kind, heights: quantised }, (peak) => peakHeight(peak, macro.scale), (peak) => peakHeight(peak, macro.scale)))
+        if (note.code === 'MAP_PASS_NOT_LOWER')
+            notes.push(note);
+    return notes;
+}
 /** Build relief, hydrology, normals and fields for a geography model on a map of the given size. */
 export function synthesizeTerrain(input) {
     const { geography, width, height, seed, kind } = input;

package/dist/hoi4_agent_tools/map/service.js

@@ -23,6 +23,7 @@ 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';
+import { evaluateTerritoryQuality, territoryArtifactContent, } from './territory-quality.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.
@@ -625,7 +626,7 @@ export class AgentNudger {
         this.scanner = this.engine.scanner;
         this.transactions = this.engine.transactions;
     }
-    async scan(workspaceId, principal, signal, includeExternalScriptReferences = false, includeWorldContext = false, includeAppearance = false) {
+    async scan(workspaceId, principal, signal, includeExternalScriptReferences = false, includeWorldContext = false, includeAppearance = false, includeBorderInputs = false) {
         signal?.throwIfAborted();
         const workspace = this.resolver.get(workspaceId, principal);
         const sourceRoots = {
@@ -634,7 +635,9 @@ 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, includeAppearance ? BORDER_BITMAP_SELECTORS : PROVINCE_BITMAP_SELECTORS);
+        const bitmapPatterns = provinceBitmapPatterns(selectorSnapshot.files, sourceRoots.map, includeAppearance || includeBorderInputs
+            ? 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
@@ -727,11 +730,11 @@ export class AgentNudger {
             scriptReferences: { references: consistency.references, missing: consistency.missing },
         };
     }
-    async prepareOperations(workspaceId, operations, principal, signal) {
+    async prepareOperations(workspaceId, operations, principal, signal, synthesisCheck = false) {
         signal?.throwIfAborted();
         const snapshot = await this.scan(workspaceId, principal, signal, operations.some((operation) => operation.kind === 'renumber_map_entity' ||
             operation.kind === 'remap_map_references' ||
-            'remapReferences' in operation), operations.some((operation) => operation.kind === 'create_world'));
+            'remapReferences' in operation), operations.some((operation) => operation.kind === 'create_world'), false, operations.some((operation) => operation.kind === 'assign_territory' || operation.kind === 'repartition_states'));
         const referenceWorlds = new Map();
         const referenceImages = [];
         const referenceLoads = new Map();
@@ -796,28 +799,56 @@ export class AgentNudger {
         const plan = await planMapOperationsAsync(snapshot.index, operations, signal, {
             referenceWorlds,
             geographyModels,
+            ...(synthesisCheck ? { synthesisCheck: true } : {}),
         });
         // 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);
+        // Border naturalness of what would be written, for the operations that ask for it.
+        const territoryQuality = await evaluateTerritoryQuality(plan, signal);
+        if (territoryQuality !== undefined) {
+            plan.diagnostics.push(...territoryQuality.diagnostics);
+            plan.blockers.push(...territoryQuality.blockers);
+            for (const report of plan.territory ?? []) {
+                const found = territoryQuality.operations.find(({ operationId }) => operationId === report.operationId);
+                if (found !== undefined)
+                    report.borderQuality.verdicts = found.layers.map(({ layer, report: measured, check }) => ({
+                        layer,
+                        status: measured.status,
+                        enrichment: measured.barrier.enrichment,
+                        naturalShare: measured.natural.share,
+                        straightFraction: measured.straightness.fraction,
+                        passed: check.passed,
+                    }));
+            }
+        }
         plan.diagnostics.push(...importDiagnostics);
         const newWorld = operations.some(({ kind }) => kind === 'create_world');
-        const freshWorld = newWorld && snapshot.index.provinceBitmapFile?.rootKind !== 'mod';
-        const baselineValidation = freshWorld
+        // A new world replaces the whole map: findings of the map it replaces are not its baseline,
+        // so every finding of the generated map is judged on its own and belongs to the world
+        // operation (ADR 0070).
+        const baselineValidation = newWorld
             ? { 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
-                ? {}
-                : { expectedChangedBounds: plan.expectedChangedBounds }),
-        });
+        // A world that failed to generate left the workspace map unchanged; validating that map would
+        // report only its old findings, so the generation blocker stands alone.
+        const worldFailed = worldOperation !== undefined &&
+            (plan.blockers.some(({ operationId }) => operationId === worldOperation.id) ||
+                synthesisCheck);
+        const rawValidation = worldFailed
+            ? { passed: true, diagnostics: [], checks: [] }
+            : 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
+                    ? {}
+                    : { expectedChangedBounds: plan.expectedChangedBounds }),
+            });
         const attributedValidation = {
             ...rawValidation,
             diagnostics: attributeMapValidationDiagnostics({
@@ -833,6 +864,7 @@ export class AgentNudger {
             validation: validationWithPlan(attributedValidation, plan),
             referenceImages,
             geography: [...geographyModels.values()],
+            territory: { reports: plan.territory ?? [], quality: territoryQuality },
             imports,
         };
     }
@@ -992,6 +1024,25 @@ export class AgentNudger {
         }, prepared);
         return { ...diff, ...planned };
     }
+    /**
+     * Run the relief and river synthesis of every `create_world` with `synthesisCheck` and report
+     * the model's rivers that cannot reach their mouths, without generating or writing anything.
+     */
+    async checkSynthesis(input) {
+        const prepared = await this.prepareOperations(input.workspaceId, input.operations, input.principal, input.signal, true);
+        const writes = await this.geographyArtifacts(prepared, input.signal, new RenderBudget());
+        const artifacts = await this.artifacts.withAtomicChunkedWrites(this.resolver.get(input.workspaceId, input.principal), writes, (stored) => Promise.resolve([...stored]), input.signal);
+        return {
+            plan: prepared.plan,
+            geography: prepared.geography,
+            diagnostics: sortDiagnostics([
+                ...prepared.plan.diagnostics,
+                ...prepared.geography.flatMap(({ diagnostics }) => diagnostics),
+            ]),
+            artifacts,
+            filesScanned: mapSourceEvidence(prepared.snapshot).map(({ displayPath }) => displayPath),
+        };
+    }
     /** Build validated offline evidence without planning or applying a write transaction. */
     async previewRewriteWithDiff(input) {
         const prepared = await this.prepareOperations(input.workspaceId, input.operations, input.principal, input.signal);
@@ -1295,6 +1346,17 @@ export class AgentNudger {
                 provenance: comparisonProvenance('before'),
             });
         writes.push(...(await this.geographyArtifacts(prepared, options.signal, budget)));
+        if (prepared.territory.reports.length > 0 || prepared.territory.quality !== undefined)
+            writes.push({
+                name: 'map-territory-report.json',
+                mimeType: 'application/json',
+                content: `${canonicalJson(territoryArtifactContent(prepared.territory.reports, prepared.territory.quality))}\n`,
+                provenance: {
+                    ...provenance,
+                    kind: 'map-territory-report',
+                    schemaVersion: 'map-territory.v1',
+                },
+            });
         for (const [ordinal, imported] of prepared.imports.entries())
             writes.push(...(await buildImportArtifacts(imported, ordinal)));
         if (plan.worldOutputs !== undefined)