hoi4-agent-tools 4.5.0 → 4.6.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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_*`.
+- Land listed in `assign_territory.unowned`, and landmasses without a seed under `islandPolicy: "unowned"`, lose their owner (and controller) with `ownership.unowned: "clear"`, the default, or keep it with `"keep"`; states outside `scope` are never edited. Refusals name the state or province of the request (`MAP_TERRITORY_SEED_UNAVAILABLE`, `_FORCED_BLOCKED`, `_FORCED_CONFLICT`, `_FORCED_UNREACHABLE` carry `stateId` or `provinceId`). Results of a territory operation add `data.territory`.
+- Add `borderQuality` (`off`, `report`, `enforce`) and `borderTargets` to the territory operations and to `create_world` (G-58). The border naturalness of the proposed map is measured after the whole request and reported (`MAP_BORDER_QUALITY_MEASURED`, artifact `map-territory-report.json`); `enforce` blocks the write below the targets (`MAP_TERRITORY_BORDER_ARTIFICIAL`, `MAP_WORLD_BORDER_ARTIFICIAL`) and is refused for the legacy partition.
+- A feature-aware `create_world` without a reference picture now grows its generated countries along natural lines instead of blind breadth-first growth; legacy worlds are byte-identical, and workspace-owned countries (`countries.source: "workspace"`) keep the realm growth of ADR 0069.
+- Public schema change: new operation kinds `assign_territory`, `repartition_states` and `update_states` and new optional fields `borderQuality` and `borderTargets` on `create_world` (minor version at release; the schemas are regenerated).
+- Plan straits, passes and walls from a geography model (ADR 0062). A world built from a geography now writes each `strait` as a named `sea` row in `adjacencies.csv` with a rule in `adjacency_rules.txt` (`open`, `army-closed`, `navy-closed`), `impassable` rows for every pair of land provinces across a range with `barrier: "impassable"` except at its passes, land forts (`bunker`) at passes with a `fort` level, and sea provinces for a lake with `gameplay: "inland-sea"` with a canal row to the open sea. The partition now uses the model's regions, named seas and walls. New optional `create_world.autoStraits` (`true` or `{ maxGapPx }`). Diagnostics: `MAP_CROSSINGS_PLANNED`, `MAP_INLAND_SEA_CREATED`, `MAP_INLAND_SEA_SEALED`, `MAP_STRAIT_UNRESOLVED`, `MAP_STRAIT_DUPLICATE`, `MAP_STRAIT_NOT_NARROW`, `MAP_PASS_BLOCKED`, `MAP_RANGE_NOT_CLOSED` and the refusal `MAP_IMPASSABLE_ROW_LIMIT`. `hoi4.map_inspect` and every created world also check rules against rows and wall rows on any map: `MAP_ADJACENCY_RULE_MISSING`, `_DUPLICATE`, `_INVALID`, `_UNUSED`, `MAP_IMPASSABLE_NOT_ADJACENT`, `MAP_IMPASSABLE_NOT_LAND`, `MAP_ADJACENCY_ROW_LIMIT`, `MAP_RAILWAY_CROSSES_IMPASSABLE`, `MAP_UNIT_POSITION_MISSING`; thresholds are set so the installed game raises nothing above information. Worlds without a geography are unchanged.
+- Plan ports, development, names and railways from a geography model (ADR 0063). Ports follow a harbour score (concavity, shelter, river mouth, depth class, sites) with levels from site importance; population, category, infrastructure, factories, resources (ranges, `mine` sites, jungle) and victory points follow fertility, rivers, coast, passes and sites with no random rolls; states, strategic regions, victory points and lake provinces are named from sites, lakes, rivers, ranges, regions, lands and seas by containment, with counted placeholders (`MAP_NAME_PLACEHOLDER`); railways use a terrain-aware cost (ground, climb, rivers, gates, roads) and trunk lines of level 2 reach large cities. New optional `create_world.development: { model: "geography" | "legacy" }` (default `geography` for a geography world) and an optional `resource` on geography `mine` sites. Other diagnostics: `MAP_DEVELOPMENT_PLANNED`, `MAP_PORT_LAKE_UNSUPPORTED`, `MAP_PORT_SITE_NOT_COASTAL`, `MAP_SITE_UNPLACED`.
+- Accept a strait between two coasts of one land as a crossing between two provinces of that land when its straight line crosses water (`MAP_GEOGRAPHY_STRAIT_SAME_LAND` is then `info`; across no water it stays an error), and add `bay` as a sea `kind` of the geography model (ADR 0062). Public schema change: one more allowed value of `seas[].kind` (minor version).
+- Public schema change: new optional fields `development` and `autoStraits` on `create_world` and `resource` on geography sites (minor version at release; the schemas are regenerated; compatibility review: additive optional input only, no output field changed, behaviour changes only for worlds built from a geography).
+- Stop reporting the validation findings of a map that a failed `create_world` left in place: a world that cannot generate now returns only its own blockers, and a successful replacement of a map is validated on the map it produces instead of being compared with the map it replaces (ADR 0070). Before, a river that could not reach its mouth came back with three `MAP_VALIDATION_OPERATION_UNOWNED` blockers about the old map.
+- Let drawn rivers carve their valleys (ADR 0071). A river whose course crosses a divide higher than 22 height units (a volcano cone, a foothill, the tip of a range) is no longer refused: its bed is cut through the rise as a gorge, and each crossing is reported as the warning `MAP_RIVER_CARVED_CROSSING` with the river, climb and divide location (world pixel, height, nearest range or volcano). Models that were refused now write; models that wrote are unchanged.
+- Report every named river with an impossible course in one run: `MAP_RIVER_UNREACHABLE_MOUTH` (a mouth on another landmass, a source or via point that cannot be reached, a lake without a shore) keeps its code and top-level fields and gains `details.rivers`, each with its reason or `blockedBy` another failed river.
+- Add `create_world.synthesisCheck` (with `preview: true` and a geography): run only the relief and river synthesis and report all impossible rivers and carved crossings without writing (`MAP_SYNTHESIS_CHECK_READY`, `MAP_SYNTHESIS_CHECK_BLOCKED`, `data.synthesisCheck`). Public schema change: one new optional field on `create_world` (minor version).
+
 ## 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.

package/dist/hoi4_agent_tools/map/border-quality.js

@@ -25,9 +25,11 @@ export const BORDER_FEATURE_BITS = {
 };
 const BORDER_FEATURES = Object.keys(BORDER_FEATURE_BITS);
 /** Barrier set: the plan's measurement (rivers, steep gradients) plus lake shores and extras. */
-const BARRIER_MASK = 1 | 2 | 4 | 16;
+export const BORDER_BARRIER_MASK = 1 | 2 | 4 | 16;
+const BARRIER_MASK = BORDER_BARRIER_MASK;
 /** Natural set: the barrier set plus terrain-class changes. */
-const NATURAL_MASK = 31;
+export const BORDER_NATURAL_MASK = 31;
+const NATURAL_MASK = BORDER_NATURAL_MASK;
 /** Province kinds used by the metric. Only land provinces have land borders. */
 export const BORDER_PROVINCE_KIND = { unknown: 0, land: 1, sea: 2, lake: 3 };
 /** Targets for an engineered world: the design's thresholds, measured against vanilla. */
@@ -374,13 +376,16 @@ function validateInput(input) {
     if (planes.terrain !== undefined && planes.terrain.classes.length !== 256)
         throw new ServiceError('MAP_BORDER_QUALITY_INPUT_INVALID', 'The terrain class table needs 256 entries');
 }
-/** One streamed pass over the raster: collect every land border edge and the chance baseline. */
-export async function buildBorderEdgeTable(input, options = {}) {
+/**
+ * One streamed pass over the raster: collect every land border edge and the chance baseline. The
+ * pass is a generator that yields every 16 rows so a synchronous planner can interleave its own
+ * checkpoints; `buildBorderEdgeTable` drives it and yields to the event loop.
+ */
+export function* buildBorderEdgeTableSteps(input, options = {}) {
     const resolved = resolveOptions(options);
     validateInput(input);
     const { width, height, provinceIds, provinceKinds } = input;
     const rows = new FeatureRows(input, resolved);
-    const pace = new Pace(resolved.signal);
     let capacity = Math.min(65_536, resolved.maxEdges);
     let keys = new Int32Array(capacity);
     let provinceA = new Int32Array(capacity);
@@ -446,8 +451,10 @@ export async function buildBorderEdgeTable(input, options = {}) {
         }
     };
     for (let y = 0; y < height; y += 1) {
-        if (y % 16 === 0)
-            await pace.tick();
+        if (y % 16 === 0) {
+            resolved.signal?.throwIfAborted();
+            yield;
+        }
         if (y + 1 < height)
             rows.rowFlags(y + 1, next);
         const rowStart = y * width;
@@ -506,6 +513,17 @@ export async function buildBorderEdgeTable(input, options = {}) {
         options: resolved,
     };
 }
+/** Drive `buildBorderEdgeTableSteps`, yielding to the event loop about every 12 milliseconds. */
+export async function buildBorderEdgeTable(input, options = {}) {
+    const steps = buildBorderEdgeTableSteps(input, options);
+    const pace = new Pace(options.signal);
+    for (;;) {
+        const step = steps.next();
+        if (step.done)
+            return step.value;
+        await pace.tick();
+    }
+}
 function round(value, places = 4) {
     const scale = 10 ** places;
     return Math.round(value * scale) / scale;

package/dist/hoi4_agent_tools/map/derived.js

@@ -623,7 +623,7 @@ function shortestRailPath(neighbors, sources, isTarget, cost) {
             return path;
         }
         for (const next of neighbors(province)) {
-            const candidate = current + cost(next);
+            const candidate = current + cost(province, next);
             if (candidate < (distance.get(next) ?? Number.POSITIVE_INFINITY)) {
                 distance.set(next, candidate);
                 previous.set(next, province);
@@ -726,12 +726,25 @@ export function planSupplyRebuild(index, request) {
         const pending = new Set(ownerScope
             .map((state) => state.provinces.find((id) => nodes.has(id)))
             .filter((id) => id !== undefined && !connected.has(id)));
+        // Trunk lines reach the major cities of the country even where no supply node stands.
+        const trunk = new Set();
+        for (const id of request.railCost?.trunk ?? [])
+            if (ownerOf(id) === owner && !connected.has(id) && neighbors(id).length > 0) {
+                trunk.add(id);
+                pending.add(id);
+            }
+        const ownerFactor = (id) => (ownerOf(id) === owner ? 1 : 4);
+        const stepCost = (from, to) => (request.railCost?.cost(from, to) ?? 1) * ownerFactor(to);
         while (pending.size > 0) {
-            const path = shortestRailPath(neighbors, connected, (id) => pending.has(id), (id) => (ownerOf(id) === owner ? 1 : 4));
+            const path = shortestRailPath(neighbors, connected, (id) => pending.has(id), stepCost);
             if (path === undefined)
                 break;
             // A path that leaves the connected set once: from its target back to the network.
-            const level = path.includes(hub) ? capitalLevel : railwayLevel;
+            const level = path.includes(hub)
+                ? capitalLevel
+                : trunk.has(path[0])
+                    ? Math.max(railwayLevel, request.trunkRailwayLevel ?? 2)
+                    : railwayLevel;
             newRailways.push({ level, provinces: [...path].reverse() });
             railways.push(path);
             for (const id of path) {

package/dist/hoi4_agent_tools/map/gameplay/crossing-validation.js

@@ -0,0 +1,268 @@
+import { assignments, firstScalar, parseClausewitz } from '../../core/source/index.js';
+import { defaultMapSelectorValue } from '../model.js';
+import { closestApproach } from './facts.js';
+/** Widest land-to-land crossing the validator accepts as a strait (the base game's is 30). */
+export const STRAIT_VALIDATOR_LIMIT_PX = 48;
+/** Total adjacency rows above which a map is reported as unusually dense with barriers. */
+export const ADJACENCY_ROW_LIMIT = 2_000;
+const ANALYSED_ROWS = 400;
+function normalized(value) {
+    return value.replaceAll('\\', '/').replace(/^\.\//u, '').toLowerCase();
+}
+function rulesFile(index) {
+    let name = 'adjacency_rules.txt';
+    try {
+        name = defaultMapSelectorValue(index.defaultMapFile, 'adjacency_rules', name);
+    }
+    catch {
+        // An untrustworthy selector is reported elsewhere; the default name is still worth checking.
+    }
+    for (const root of index.sourceRoots.map) {
+        const found = index.activeFiles.byRelativePath.get(normalized(`${root}/${name}`));
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+/** The rules a file defines; `duplicates` lists names defined more than once. */
+export function parseAdjacencyRules(file) {
+    const document = parseClausewitz(file.bytes, file.displayPath);
+    const rules = [];
+    const seen = new Set();
+    const duplicates = [];
+    for (const entry of assignments(document.root, 'adjacency_rule')) {
+        if (entry.value.type !== 'block')
+            continue;
+        const name = firstScalar(entry.value, 'name')?.value ?? '';
+        const required = [];
+        const list = assignments(entry.value, 'required_provinces')[0]?.value;
+        if (list?.type === 'block')
+            for (const item of list.entries)
+                if (item.type === 'scalar' && /^\d+$/u.test(item.value))
+                    required.push(Number(item.value));
+        const icon = firstScalar(entry.value, 'icon')?.value;
+        rules.push({
+            name,
+            required,
+            ...(icon !== undefined && /^\d+$/u.test(icon) ? { icon: Number(icon) } : {}),
+        });
+        if (name !== '') {
+            if (seen.has(name))
+                duplicates.push(name);
+            seen.add(name);
+        }
+    }
+    return { rules, duplicates };
+}
+function bounded(items, limit = 8) {
+    return items.slice(0, limit);
+}
+function* checkRules(index, report) {
+    const file = rulesFile(index);
+    if (file === undefined)
+        return;
+    const { rules, duplicates } = parseAdjacencyRules(file);
+    yield;
+    const location = {
+        path: file.displayPath,
+        start: { line: 1, column: 1, offset: 0 },
+        end: { line: 1, column: 1, offset: 0 },
+    };
+    for (const name of bounded(duplicates))
+        report({
+            code: 'MAP_ADJACENCY_RULE_DUPLICATE',
+            severity: 'error',
+            message: `Adjacency rule ${name} is defined more than once`,
+            location,
+            details: { rule: name },
+        });
+    const defined = new Map(rules.map((rule) => [rule.name, rule]));
+    for (const rule of rules) {
+        const problems = [];
+        if (rule.name === '')
+            problems.push('has no name');
+        if (rule.required.length < 2)
+            problems.push('lists fewer than two required_provinces');
+        const unknown = rule.required.filter((id) => !index.definitionsById.has(id));
+        if (unknown.length > 0)
+            problems.push(`names unknown province(s) ${bounded(unknown).join(', ')}`);
+        if (rule.icon !== undefined && !index.definitionsById.has(rule.icon))
+            problems.push(`has an icon on unknown province ${rule.icon}`);
+        if (problems.length > 0)
+            report({
+                code: 'MAP_ADJACENCY_RULE_INVALID',
+                severity: 'error',
+                message: `Adjacency rule ${rule.name === '' ? '(unnamed)' : rule.name} ${problems.join(' and ')}`,
+                location,
+                details: { rule: rule.name, problems },
+            });
+    }
+    yield;
+    const used = new Set();
+    for (const row of index.adjacencies) {
+        if (row.rule === '')
+            continue;
+        used.add(row.rule);
+        if (!defined.has(row.rule))
+            report({
+                code: 'MAP_ADJACENCY_RULE_MISSING',
+                severity: 'error',
+                message: `Adjacency ${row.from}-${row.to} uses rule ${row.rule}, which adjacency_rules.txt does not define`,
+                location,
+                details: { rule: row.rule, from: row.from, to: row.to },
+            });
+    }
+    const unused = rules.filter((rule) => rule.name !== '' && !used.has(rule.name));
+    if (unused.length > 0)
+        report({
+            code: 'MAP_ADJACENCY_RULE_UNUSED',
+            severity: 'info',
+            message: `${unused.length} adjacency rule(s) are defined but no adjacency row uses them`,
+            location,
+            details: { rules: bounded(unused.map((rule) => rule.name)) },
+        });
+}
+/** Pixels of one province, from its bounding box. */
+function pixelsOf(index, id) {
+    const raster = index.raster;
+    const geometry = raster?.geometry.get(id);
+    if (raster === undefined || geometry === undefined)
+        return [];
+    const out = [];
+    const stride = Math.max(1, Math.ceil(Math.sqrt(geometry.pixelCount / 4_000)));
+    for (let y = geometry.minY; y <= geometry.maxY; y += 1)
+        for (let x = geometry.minX; x <= geometry.maxX; x += 1)
+            if ((x + y) % stride === 0 && raster.provinceIds[y * raster.width + x] === id)
+                out.push(y * raster.width + x);
+    return out;
+}
+function* checkRows(index, report) {
+    const raster = index.raster;
+    if (raster === undefined)
+        return;
+    const impassable = index.adjacencies.filter(({ type }) => type === 'impassable');
+    const isolated = [];
+    const nonLand = [];
+    for (const row of impassable) {
+        const from = index.definitionsById.get(row.from);
+        const to = index.definitionsById.get(row.to);
+        if (from === undefined || to === undefined)
+            continue;
+        if (!(raster.adjacency.get(row.from)?.has(row.to) ?? false))
+            isolated.push(`${row.from}-${row.to}`);
+        if (from.type !== 'land' || to.type !== 'land')
+            nonLand.push(`${row.from}-${row.to}`);
+    }
+    yield;
+    // The base game has one such row among 93, so a stray row is information and a pattern a warning.
+    if (isolated.length > 0)
+        report({
+            code: 'MAP_IMPASSABLE_NOT_ADJACENT',
+            severity: isolated.length >= 3 && isolated.length > impassable.length * 0.05 ? 'warning' : 'info',
+            message: `${isolated.length} impassable row(s) join provinces that do not touch, so they block nothing`,
+            details: { rows: bounded(isolated), count: isolated.length },
+        });
+    if (nonLand.length > 0)
+        report({
+            code: 'MAP_IMPASSABLE_NOT_LAND',
+            severity: 'warning',
+            message: `${nonLand.length} impassable row(s) join a province that is not land; walls separate land provinces`,
+            details: { rows: bounded(nonLand), count: nonLand.length },
+        });
+    if (index.adjacencies.length > ADJACENCY_ROW_LIMIT)
+        report({
+            code: 'MAP_ADJACENCY_ROW_LIMIT',
+            severity: 'warning',
+            message: `adjacencies.csv has ${index.adjacencies.length} rows; the base game has 244. Large walls slow the load and the AI; consider fewer or larger provinces along the wall`,
+            details: { rows: index.adjacencies.length, limit: ADJACENCY_ROW_LIMIT },
+        });
+    // Land-to-land sea crossings narrow enough to be a strait.
+    const wide = [];
+    let analysed = 0;
+    const view = {
+        width: raster.width,
+        height: raster.height,
+        pixel: raster.provinceIds,
+        count: 0,
+    };
+    for (const row of index.adjacencies) {
+        if (row.type !== 'sea' || analysed >= ANALYSED_ROWS)
+            continue;
+        const from = index.definitionsById.get(row.from);
+        const to = index.definitionsById.get(row.to);
+        if (from?.type !== 'land' || to?.type !== 'land')
+            continue;
+        if (raster.adjacency.get(row.from)?.has(row.to) ?? false)
+            continue;
+        analysed += 1;
+        const approach = closestApproach(pixelsOf(index, row.from), pixelsOf(index, row.to), view.width, 200);
+        if (approach !== undefined && approach.gap > STRAIT_VALIDATOR_LIMIT_PX)
+            wide.push(`${row.from}-${row.to} (${Math.round(approach.gap)} px)`);
+        if (analysed % 16 === 0)
+            yield;
+    }
+    if (wide.length > 0)
+        report({
+            code: 'MAP_STRAIT_NOT_NARROW',
+            severity: 'warning',
+            message: `${wide.length} land crossing(s) span more than ${STRAIT_VALIDATOR_LIMIT_PX} pixels between their provinces (the base game's widest is 30): ${bounded(wide, 4).join(', ')}`,
+            details: { crossings: bounded(wide), count: wide.length, limitPx: STRAIT_VALIDATOR_LIMIT_PX },
+        });
+}
+function* checkRailways(index, report) {
+    if (index.railways.length === 0)
+        return;
+    const blocked = new Set();
+    for (const row of index.adjacencies)
+        if (row.type === 'impassable') {
+            blocked.add(`${row.from}:${row.to}`);
+            blocked.add(`${row.to}:${row.from}`);
+        }
+    if (blocked.size === 0)
+        return;
+    const crossing = [];
+    for (const railway of index.railways) {
+        for (let step = 1; step < railway.provinces.length; step += 1) {
+            const from = railway.provinces[step - 1];
+            const to = railway.provinces[step];
+            if (blocked.has(`${from}:${to}`))
+                crossing.push(`${from}-${to}`);
+        }
+    }
+    yield;
+    if (crossing.length > 0)
+        report({
+            code: 'MAP_RAILWAY_CROSSES_IMPASSABLE',
+            severity: 'warning',
+            message: `${crossing.length} railway step(s) run between provinces separated by an impassable row; a railway cannot cross a wall except at a gate`,
+            details: { steps: bounded(crossing), count: crossing.length },
+        });
+}
+function* checkUnitPositions(index, report) {
+    if (index.unitPositions.length === 0 || index.raster === undefined)
+        return;
+    const covered = new Set(index.unitPositions.map(({ provinceId }) => provinceId));
+    const missing = [];
+    for (const definition of index.definitions)
+        if (definition.id > 0 &&
+            index.raster.geometry.has(definition.id) &&
+            definition.type !== 'lake' &&
+            !covered.has(definition.id))
+            missing.push(definition.id);
+    yield;
+    // The base game lacks positions for 7 of 13,000 provinces: a few are information, many a warning.
+    if (missing.length > 0)
+        report({
+            code: 'MAP_UNIT_POSITION_MISSING',
+            severity: missing.length > Math.max(3, index.definitions.length * 0.01) ? 'warning' : 'info',
+            message: `${missing.length} province(s) have no unit-stack positions, so units there have no place to stand`,
+            details: { provinces: bounded(missing, 12), count: missing.length },
+        });
+}
+/** Run the crossing, wall, railway and position checks; findings go to `report`. */
+export function* validateCrossings(index, report) {
+    yield* checkRules(index, report);
+    yield* checkRows(index, report);
+    yield* checkRailways(index, report);
+    yield* checkUnitPositions(index, report);
+}