hoi4-agent-tools 4.6.0 → 4.6.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 4.6.2 - 2026-10-31
+
+- Check the points of workspace countries together and give each capital a province (ADR 0073). `create_world` now reports every capital or seed that lies outside the world or in water (with the nearest land), in the unowned area, an own exclusion or another realm's claim, or within 10 pixels of a point of another realm, in one error (`MAP_WORLD_REALM_POINTS_INVALID`, `details.problems`; a single problem keeps its own code), before the relief synthesis starts. `create_world.synthesisCheck` runs the same check and lists the points beside the failing rivers (`data.synthesisCheck.realmPoints`). In the feature-aware partition every capital and seed is a province seed of its own, so capitals that are 20 to 40 pixels apart no longer fail with `MAP_WORLD_REALM_POINT_CONFLICT`. Feature-aware worlds with workspace countries get a slightly different province partition; other worlds are unchanged.
+
+## Unreleased
+
+- Raise the pinned overrides of three transitive dependencies to their fixed releases, clearing every `npm audit --omit=dev` advisory: `fast-uri` 3.1.9 (GHSA-w74x-v6f9-j3xg, GHSA-xhq7-xmqj-769h, GHSA-wjr9-j795-jxcr, GHSA-333x-w4r6-6crp), `hono` 4.13.13 (GHSA-5r4p-p66f-jhc7) and `ip-address` 10.7.4 (GHSA-rxp7-6hxx-x8q5). No source or schema change.
+
+## 4.6.1 - 2026-10-26
+
+- Stop flagging `constant:<category>.<key>` script-constant reads as scoped temporary-variable reads (`KNOWN_MISTAKE_TEMP_VARIABLE_SCOPE_PREFIX`).
+- Make declared passes saddles whatever else stands there (ADR 0072). After the macro relief is composed, the heights in a pass's corridor are capped at the pass's saddle level, so a volcano cone, plateau or neighbouring feature that overlaps a pass no longer fills the gap and no longer fails the world with `MAP_PASS_NOT_LOWER`. Another range's body is left alone. `create_world.synthesisCheck` now also reports `MAP_PASS_NOT_LOWER`, so a preview catches what the write would block on. Models whose passes were refused now write; worlds with no overlapping feature on a pass are unchanged.
+
 ## 4.6.0 - 2026-10-25
 
 - Add the territory assignment service (ADR 0060). `assign_territory` grows up to 512 countries over the states or provinces of a map from capital and anchor seeds (state, province or pixel) with forced and blocked land, preferred strategic regions, subjects inside an overlord, merges, island policies, size targets by weight, extra cores and claims, and writes owner, controller, cores and claims. Borders follow rivers, ranges, lake shores and terrain changes (a shortest-path growth with barrier-weighted steps, size balancing, a corridor for cut-off seeds and a local search that shortens the artificial border); the result reports sizes against targets and the same seeds grown on distance alone. With `unit: "province"` the states a border cuts are regrouped in one pass, conserving population, resources and buildings exactly. `repartition_states` regroups the states of chosen owners along natural lines, and `update_states` edits up to 5,000 states in one rewrite. New diagnostics `MAP_TERRITORY_*`.

package/dist/hoi4_agent_tools/map/partition-provinces.js

@@ -653,17 +653,30 @@ export function partitionProvinces(input) {
             seeded[pixel] = 1;
         }
     };
-    addSeeds(placeSeeds({
+    const landMinArea = Math.max(tuning.minProvincePixels, plan.minLand * 0.85);
+    const pins = (input.pins ?? []).filter((pixel) => kind[pixel] === LAND);
+    addSeeds(Int32Array.from(pins));
+    // Land seeds within a province radius of a pin would cut the pinned province in two.
+    const pinRadius = Math.max(4, 0.6 * Math.sqrt(landMinArea));
+    const pinPoints = pins.map((pixel) => [pixel % width, Math.floor(pixel / width)]);
+    const landSeeds = placeSeeds({
         width,
         height,
         kind,
         wanted: LAND,
         areaAt: plan.land,
-        minArea: Math.max(tuning.minProvincePixels, plan.minLand * 0.85),
+        minArea: landMinArea,
         barrier,
         seed: input.seed,
         salt: 17,
-    }));
+    });
+    addSeeds(pins.length === 0
+        ? landSeeds
+        : landSeeds.filter((pixel) => {
+            const x = pixel % width;
+            const y = Math.floor(pixel / width);
+            return !pinPoints.some(([px, py]) => Math.hypot(px - x, py - y) < pinRadius);
+        }));
     addSeeds(placeSeeds({
         width,
         height,

package/dist/hoi4_agent_tools/map/partition.js

@@ -85,10 +85,11 @@ export function partitionWorld(input) {
     };
 }
 /** Resolve tuning against a request and partition in one call. */
-export function partitionWorldFromRequest(fields, seed, tuning, base, signal) {
+export function partitionWorldFromRequest(fields, seed, tuning, base, signal, pins) {
     return partitionWorld({
         fields,
         seed,
+        pins,
         signal,
         tuning: resolvePartitionTuning(tuning, {
             ...base,

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

@@ -115,18 +115,27 @@ export function checkTerrainRivers(input) {
                 if (macro.kind[cell] === LAND)
                     macro.heights[cell] = adjust(2 * x + 1, 2 * y + 1, macro.heights[cell]);
             }
-    return [
-        ...synthesizeHydrology({
-            geography,
-            macro,
-            seed,
-            density: input.rivers?.density,
-            count: input.rivers?.count,
-            rainfall: input.rainfall,
-            landPixels,
-            signal: input.signal,
-        }).notes,
-    ];
+    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) {

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

@@ -521,8 +521,14 @@ async function previewSynthesisCheck(nudger, input, context) {
     });
     const blocked = checked.diagnostics.filter(({ severity }) => severity === 'error' || severity === 'blocker');
     const valid = blocked.length === 0 && checked.plan.blockers.length === 0;
-    const rivers = checked.diagnostics.flatMap(({ code, details }) => code === 'MAP_RIVER_UNREACHABLE_MOUTH' && Array.isArray(details?.rivers)
-        ? details.rivers
+    // Failures of the synthesis can sit inside a realm-point error that reports both (ADR 0073).
+    const synthesisDetails = (details) => details?.synthesis?.details ?? details;
+    const rivers = checked.diagnostics.flatMap(({ details }) => {
+        const found = synthesisDetails(details)?.rivers;
+        return Array.isArray(found) ? found : [];
+    });
+    const realmPoints = checked.diagnostics.flatMap(({ code, details }) => code.startsWith('MAP_WORLD_REALM_POINT') && Array.isArray(details?.problems)
+        ? details.problems
         : []);
     // Drawn rivers are authoritative: crossings of relief they cut through are warnings (ADR 0071).
     const carved = checked.diagnostics.flatMap(({ code, details }) => code === 'MAP_RIVER_CARVED_CROSSING' && details !== undefined ? [details] : []);
@@ -546,6 +552,8 @@ async function previewSynthesisCheck(nudger, input, context) {
             rivers: rivers.slice(0, 200),
             carvedCrossings: carved.length,
             crossings: carved.slice(0, 200),
+            realmPointProblems: realmPoints.length,
+            realmPoints: realmPoints.slice(0, 500),
         },
     });
     result.status = valid ? 'ok' : 'blocked';

package/dist/hoi4_agent_tools/map/world-realms.js

@@ -51,6 +51,145 @@ function pointProvince(tag, role, point, raster) {
         });
     return province;
 }
+/** Two points of different realms closer than this many pixels cannot get a province each. */
+export const REALM_POINT_MIN_SEPARATION_PX = 10;
+/** How far from a point in water the nearest land is searched, in pixels. */
+const NEAREST_LAND_REACH_PX = 80;
+/**
+ * Check every capital and seed against the generated surface before any province exists, and
+ * return all problems at once: a point outside the frame or in water (with the nearest land), a
+ * point inside the unowned area, its own exclusion or another realm's claim, and points of
+ * different realms closer than `REALM_POINT_MIN_SEPARATION_PX`. Points of one realm may share a
+ * province; points of different realms each get their own province (ADR 0073).
+ */
+export function checkRealmPoints(realms, raster) {
+    const problems = [];
+    const points = [];
+    for (const [index, realm] of realms.list.entries()) {
+        points.push({ tag: realm.tag, role: 'capital', point: realm.capital, index });
+        for (const seed of realm.seeds ?? [])
+            points.push({ tag: realm.tag, role: 'seed', point: seed, index });
+    }
+    const nearestLand = (point) => {
+        const cx = Math.floor(point.x);
+        const cy = Math.floor(point.y);
+        let best;
+        for (let radius = 1; radius <= NEAREST_LAND_REACH_PX; radius += 1) {
+            for (let dy = -radius; dy <= radius; dy += 1)
+                for (let dx = -radius; dx <= radius; dx += 1) {
+                    if (Math.max(Math.abs(dx), Math.abs(dy)) !== radius)
+                        continue;
+                    const x = cx + dx;
+                    const y = cy + dy;
+                    if (x < 0 || y < 0 || x >= raster.width || y >= raster.height)
+                        continue;
+                    if (!raster.land(y * raster.width + x))
+                        continue;
+                    const distance = Math.hypot(dx, dy);
+                    if (best === undefined || distance < best.distance)
+                        best = { x, y, distance };
+                }
+            if (best !== undefined && best.distance <= radius)
+                return best;
+        }
+        return best;
+    };
+    for (const { tag, role, point, index } of points) {
+        const x = Math.floor(point.x);
+        const y = Math.floor(point.y);
+        if (x < 0 || y < 0 || x >= raster.width || y >= raster.height) {
+            problems.push({
+                code: 'MAP_WORLD_REALM_POINT_OUTSIDE',
+                tag,
+                role,
+                point,
+                message: `The ${role} of ${tag} lies outside the ${raster.width}x${raster.height} world`,
+            });
+            continue;
+        }
+        if (!raster.land(y * raster.width + x)) {
+            const near = nearestLand(point);
+            problems.push({
+                code: 'MAP_WORLD_REALM_POINT_WATER',
+                tag,
+                role,
+                point,
+                message: `The ${role} of ${tag} at (${x}, ${y}) lies in water${near === undefined
+                    ? ''
+                    : `; the nearest land is (${near.x}, ${near.y}), ${Math.round(near.distance)} px away`}`,
+                ...(near === undefined ? {} : { nearestLand: near }),
+            });
+            continue;
+        }
+        const px = x + 0.5;
+        const py = y + 0.5;
+        const realm = realms.list[index];
+        if (realms.unowned?.some((polygon) => inside(px, py, polygon)) === true)
+            problems.push({
+                code: 'MAP_WORLD_REALM_POINT_CONFLICT',
+                tag,
+                role,
+                point,
+                message: `The ${role} of ${tag} at (${x}, ${y}) lies in the unowned area`,
+            });
+        else if (realm.exclude?.some((polygon) => inside(px, py, polygon)) === true)
+            problems.push({
+                code: 'MAP_WORLD_REALM_POINT_CONFLICT',
+                tag,
+                role,
+                point,
+                message: `The ${role} of ${tag} at (${x}, ${y}) lies in its own exclusion`,
+            });
+        else
+            for (const [otherIndex, other] of realms.list.entries()) {
+                if (otherIndex === index)
+                    continue;
+                if (other.claim?.some((polygon) => inside(px, py, polygon)) === true) {
+                    problems.push({
+                        code: 'MAP_WORLD_REALM_POINT_CONFLICT',
+                        tag,
+                        role,
+                        point,
+                        otherTag: other.tag,
+                        message: `The ${role} of ${tag} at (${x}, ${y}) lies in a claim of ${other.tag}`,
+                    });
+                    break;
+                }
+            }
+    }
+    // Points of different realms that are too close to each have a province of their own.
+    for (let a = 0; a < points.length; a += 1)
+        for (let b = a + 1; b < points.length; b += 1) {
+            const left = points[a];
+            const right = points[b];
+            if (left.index === right.index)
+                continue;
+            const distance = Math.hypot(left.point.x - right.point.x, left.point.y - right.point.y);
+            if (distance >= REALM_POINT_MIN_SEPARATION_PX)
+                continue;
+            problems.push({
+                code: 'MAP_WORLD_REALM_POINTS_TOO_CLOSE',
+                tag: left.tag,
+                role: left.role,
+                point: left.point,
+                otherTag: right.tag,
+                otherPoint: right.point,
+                distance: Math.round(distance * 10) / 10,
+                message: `The ${left.role} of ${left.tag} and the ${right.role} of ${right.tag} are ${Math.round(distance * 10) / 10} px apart; points of different realms need ${REALM_POINT_MIN_SEPARATION_PX} px to get a province each`,
+            });
+        }
+    return problems;
+}
+/** One error for all point problems; the first one's code, every problem in `details.problems`. */
+export function realmPointsError(problems) {
+    const first = problems[0];
+    return new ServiceError(problems.length === 1 ? first.code : 'MAP_WORLD_REALM_POINTS_INVALID', problems.length === 1
+        ? first.message
+        : `${problems.length} realm points cannot be placed: ${problems
+            .slice(0, 6)
+            .map(({ message }) => message)
+            .join('; ')}${problems.length > 6 ? '; ...' : ''}`, { problems: problems.slice(0, 500), count: problems.length });
+}
 export function resolveRealmRules(realms, raster) {
     const unowned = realms.unowned === undefined ? new Set() : coveredProvinces(realms.unowned, raster);
     const excluded = realms.list.map((realm) => realm.exclude === undefined ? new Set() : coveredProvinces(realm.exclude, raster));

package/dist/hoi4_agent_tools/map/world.js

@@ -25,7 +25,7 @@ import { ambientObjectText, applyEdgePolicy, assertFeaturesOutsideBand, edgeWate
 import { landDistanceField, lakeHeight, normalizeLakes, waterColourLevel } from './water.js';
 import { overlayGeographyLakes, rasterizeGeographyKind } from './relief/land.js';
 import { checkTerrainRivers, synthesizeTerrain, } from './relief/terrain-synthesis.js';
-import { assignUnreachedRealmLand, resolveRealmRules } from './world-realms.js';
+import { assignUnreachedRealmLand, checkRealmPoints, realmPointsError, resolveRealmRules, } from './world-realms.js';
 // ---------------------------------------------------------------------------------------------
 // Deterministic randomness and noise
 export class Random {
@@ -445,6 +445,26 @@ function weatherBlock(signedLatitude, desert) {
     }
     return `\tweather={\n${periods.join('\n')}\n\t}`;
 }
+/**
+ * The land pixels that each get a province of their own: every capital and seed. A point of the
+ * same realm within a few pixels of an earlier pin shares its province.
+ */
+function realmPins(realms, width, height, kind) {
+    if (realms === undefined)
+        return undefined;
+    const pins = [];
+    for (const [index, realm] of realms.list.entries())
+        for (const point of [realm.capital, ...(realm.seeds ?? [])]) {
+            const x = Math.floor(point.x);
+            const y = Math.floor(point.y);
+            if (x < 0 || y < 0 || x >= width || y >= height || kind[y * width + x] !== LAND)
+                continue;
+            if (pins.some((pin) => pin.realm === index && Math.hypot(pin.x - x, pin.y - y) < 6))
+                continue;
+            pins.push({ pixel: y * width + x, x, y, realm: index });
+        }
+    return pins.map(({ pixel }) => pixel);
+}
 export function generateWorld(spec, context, options = {}) {
     const { width, height } = spec;
     if (width % 256 !== 0 || height % 256 !== 0)
@@ -513,30 +533,61 @@ export function generateWorld(spec, context, options = {}) {
     let seamRepaired = geography !== undefined ? repairSeamCorners(surface.kind, width, height) : [];
     // A geography model gets its relief and rivers from the synthesis of ADR 0056; every other world
     // keeps the original elevation classes and drainage, byte for byte.
-    if (options.riverCheck === true && geography !== undefined) {
-        const checked = checkTerrainRivers({
-            geography,
+    // Every capital and seed is checked against the generated surface before anything else runs, and
+    // all problems are reported together (ADR 0073).
+    const pointProblems = spec.realms === undefined
+        ? []
+        : checkRealmPoints(spec.realms, {
             width,
             height,
-            seed: spec.seed,
-            kind: surface.kind,
-            relief: spec.relief,
-            rivers: { density: spec.riverDensity, count: spec.riverCount },
-            adjustHeight: edge.mode === 'rim'
-                ? (x, _y, value) => rimHeight(value, rimStrength(edge, width, x))
-                : undefined,
-            signal: options.signal,
+            land: (pixel) => surface.kind[pixel] === LAND,
         });
-        for (const note of checked) {
-            if (note.severity === 'error')
-                throw new ServiceError(note.code, note.message, note.details);
-            notes.push({
-                code: note.code,
-                severity: note.severity,
-                message: note.message,
-                ...(note.details === undefined ? {} : { details: note.details }),
+    if (pointProblems.length > 0 && options.riverCheck !== true)
+        throw realmPointsError(pointProblems);
+    if (options.riverCheck === true && geography !== undefined) {
+        let failure;
+        try {
+            const checked = checkTerrainRivers({
+                geography,
+                width,
+                height,
+                seed: spec.seed,
+                kind: surface.kind,
+                relief: spec.relief,
+                rivers: { density: spec.riverDensity, count: spec.riverCount },
+                adjustHeight: edge.mode === 'rim'
+                    ? (x, _y, value) => rimHeight(value, rimStrength(edge, width, x))
+                    : undefined,
+                signal: options.signal,
             });
+            for (const note of checked) {
+                if (note.severity === 'error')
+                    throw new ServiceError(note.code, note.message, note.details);
+                notes.push({
+                    code: note.code,
+                    severity: note.severity,
+                    message: note.message,
+                    ...(note.details === undefined ? {} : { details: note.details }),
+                });
+            }
+        }
+        catch (error) {
+            if (!(error instanceof ServiceError))
+                throw error;
+            failure = error;
+        }
+        // The preview reports the realm points and the synthesis together.
+        if (pointProblems.length > 0) {
+            const pointError = realmPointsError(pointProblems);
+            throw failure === undefined
+                ? pointError
+                : new ServiceError(pointError.code, `${pointError.message}. The relief synthesis also failed: ${failure.message}`, {
+                    ...pointError.details,
+                    synthesis: { code: failure.code, message: failure.message, details: failure.details },
+                });
         }
+        if (failure !== undefined)
+            throw failure;
         return {
             files: [],
             warnings: [],
@@ -676,7 +727,7 @@ export function generateWorld(spec, context, options = {}) {
             provincesPerState: spec.provincesPerState,
             landProvincesPerRegion: spec.landProvincesPerRegion,
             seaProvincesPerRegion: spec.seaProvincesPerRegion,
-        }, options.signal);
+        }, options.signal, realmPins(spec.realms, width, height, surface.kind));
         provinces = featurePartition.provinces;
         for (const note of featurePartition.notes)
             notes.push(note);

package/dist/hoi4_agent_tools/reference/known-mistakes.js

@@ -256,6 +256,9 @@ const detectors = {
         const findings = [];
         for (const { node, token } of names) {
             const name = token.slice(token.lastIndexOf('.') + 1);
+            // `constant:category.key` reads a script constant, not a scoped variable.
+            if (token.startsWith('constant:'))
+                continue;
             if (!temporary.has(name) || regular.has(name))
                 continue;
             if (!/^(?:[A-Za-z_][\w]*|[a-z_]+:[\w]+)(?:\.[A-Za-z_][\w]*)+$/u.test(token))

package/dist/hoi4_agent_tools/schemas/map.js

@@ -30,7 +30,7 @@ const realmPolygonsSchema = z.array(realmPolygonSchema).min(1).max(64);
 export const workspaceRealmSchema = z
     .object({
     tag: countryTagSchema,
-    capital: pointSchema.describe('World pixel, top-left origin, on land; the capital province.'),
+    capital: pointSchema.describe('World pixel, top-left origin, on land; the capital province. Capitals and seeds of different realms must be at least 10 pixels apart; each gets a province of its own.'),
     seeds: z
         .array(pointSchema)
         .max(256)

package/dist/hoi4_agent_tools/version.js

@@ -1,6 +1,6 @@
 import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
 export const PACKAGE_NAME = 'hoi4-agent-tools';
-export const PACKAGE_VERSION = '4.6.0';
+export const PACKAGE_VERSION = '4.6.2';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 2;

package/docs/map.md

@@ -541,6 +541,8 @@ A mod that writes its own country tags, country files, histories, orders of batt
 
 Points and polygon vertices are world pixels with the origin at the top left. A capital or seed names the land province under it; a land province with more than half its pixels inside a claim belongs to that country, inside an exclusion never does, and inside `unowned` belongs to nobody. Countries grow from their capitals, seeds and claims by `weight` (default 1). Land that growth does not reach goes, on a landmass a country already holds, to the nearest country that may own it; a landmass no country starts on follows `islands`: `nearest` (each province to the nearest capital), `one-owner` (the whole landmass to the country nearest its centre) or `unowned`. At most 512 countries.
 
+Every capital and seed is checked against the generated coast before any province is built, and all problems are reported together (`MAP_WORLD_REALM_POINTS_INVALID`, `details.problems`; one problem keeps its own code): a point outside the world, in water (with the nearest land and its distance), in the unowned area, in the realm's own exclusion or in another realm's claim, and points of different realms closer than 10 pixels. `synthesisCheck` runs the same check. In the feature-aware partition each capital and seed is the centre of a province of its own, so capitals only 10 to 40 pixels apart each get a province and a state.
+
 Every tag must be declared by an active `common/country_tags` file other than the world's own (`MAP_WORLD_REALM_TAG_UNKNOWN`) and not only as a dynamic tag (`MAP_WORLD_REALM_TAG_DYNAMIC`). A point outside the world (`MAP_WORLD_REALM_POINT_OUTSIDE`) or in water (`MAP_WORLD_REALM_POINT_WATER`), a point in unowned land, in the country's own exclusion or on another country's point (`MAP_WORLD_REALM_POINT_CONFLICT`), and claims that overlap each other or unowned land (`MAP_WORLD_REALM_CLAIM_OVERLAP`) are refused with the tag and position. A reference picture's political colours are not used with this form.
 
 The world then writes no country tag file, country file, `colors.txt`, country history, order of battle, flag, country name or bookmark. Unowned land forms states with no `owner`, `controller` or `add_core_of` (`MAP_WORLD_STATE_UNOWNED`, and `MAP_STATE_OWNER_MISSING` for each); whether the game build accepts unowned land is the mod's to verify. `MAP_WORLD_REALMS_PLACED`, `data.realms` and `map-world-realms.json` give each country's capital state and province, states, provinces and land share against its target. The country histories stay the mod's: a `capital` in a state the country does not own is the existing warning `MAP_COUNTRY_CAPITAL_NOT_OWNED`.
@@ -557,7 +559,9 @@ A river the model draws is authoritative over the synthesised relief (ADR 0071).
 
 Only a course that cannot exist is refused with `MAP_RIVER_UNREACHABLE_MOUTH`: a mouth on another landmass or not reachable over land, an unreachable source or via point, a lake without a free shore. The error lists every such river in `details.rivers` with its reason, or `blockedBy` another failed river.
 
-To check all of this without a write, call `hoi4.map_rewrite` with `preview: true` and `synthesisCheck: true` on the `create_world` operation: it runs the relief and river synthesis only, writes nothing and returns `MAP_SYNTHESIS_CHECK_READY` or `MAP_SYNTHESIS_CHECK_BLOCKED` with `data.synthesisCheck` (unreachable rivers and carved crossings). It does not run the partition, the countries or the climate stage (ADR 0070). A world that fails to generate returns only its own blockers, never the findings of the map it would replace.
+A declared pass is a saddle lower than the crest on both sides (ADR 0072): the heights in its corridor are capped at the saddle level after all relief is composed, so a volcano cone or plateau on the pass is cut down there (move the volcano if the cone should stay whole). Another range's body is not touched.
+
+To check all of this without a write, call `hoi4.map_rewrite` with `preview: true` and `synthesisCheck: true` on the `create_world` operation: it runs the relief and river synthesis only, writes nothing and returns `MAP_SYNTHESIS_CHECK_READY` or `MAP_SYNTHESIS_CHECK_BLOCKED` with `data.synthesisCheck` (unreachable rivers, carved crossings and passes that are not lower than their crest). It does not run the partition, the countries or the climate stage (ADR 0070). A world that fails to generate returns only its own blockers, never the findings of the map it would replace.
 
 ### Feature-aware provinces, states and strategic regions