hoi4-agent-tools 4.4.0 → 4.6.0

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

@@ -6,7 +6,8 @@ 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 { allocateMapIdentifiersAsync, WORLD_OUTPUT_PATH_SAMPLE, } from './operations.js';
+import { compactTerritoryReport } from './territory-operations.js';
 import { borderQualityDiagnostics } from './border-quality.js';
 import { measureIndexBorderNaturalness, summarizeBorderQuality, } from './border-quality-input.js';
 import { buildMapCatalog, lookupMapCoordinate, searchMapCatalog } from './catalog.js';
@@ -301,6 +302,10 @@ export async function prepareMapRewrite(nudger, input, context) {
                 semanticDiff: compactSemantic.semantic,
                 semanticDiffCounts: compactSemantic.counts,
                 semanticDiffTruncated: compactSemantic.truncated,
+                ...(planned.plan.territory === undefined
+                    ? {}
+                    : { territory: planned.plan.territory.map(compactTerritoryReport) }),
+                ...worldOutputsData(planned.plan),
             }),
             filesScanned: planned.filesScanned,
             planBlockers: planned.plan.blockers
@@ -309,6 +314,44 @@ export async function prepareMapRewrite(nudger, input, context) {
         }),
     };
 }
+/** Counts and sorted samples of the managed outputs each generated world writes, retires and releases. */
+function worldOutputsData(plan) {
+    if (plan.worldOutputs === undefined)
+        return {};
+    const sample = (paths) => paths.slice(0, WORLD_OUTPUT_PATH_SAMPLE);
+    const realms = plan.worldOutputs.flatMap(({ operationId, realms: placed }) => placed === undefined
+        ? []
+        : [
+            {
+                operationId,
+                countries: placed.countries.slice(0, 100).map((country) => ({
+                    tag: country.tag,
+                    capitalState: country.capitalState,
+                    capitalProvince: country.capitalProvince,
+                    states: country.states.length,
+                    provinces: country.provinces,
+                    landShare: country.landShare,
+                    targetShare: country.targetShare,
+                })),
+                countryCount: placed.countries.length,
+                unownedStates: placed.unownedStates.slice(0, WORLD_OUTPUT_PATH_SAMPLE),
+                unownedStateCount: placed.unownedStates.length,
+            },
+        ]);
+    return {
+        ...(realms.length === 0 ? {} : { realms: realms.slice(0, 16) }),
+        outputs: plan.worldOutputs.slice(0, 16).map((world) => ({
+            operationId: world.operationId,
+            written: world.written.length,
+            retired: world.retired.length,
+            released: world.released.length,
+            retiredFiles: sample(world.retired),
+            releasedFiles: sample(world.released),
+            truncated: world.retired.length > WORLD_OUTPUT_PATH_SAMPLE ||
+                world.released.length > WORLD_OUTPUT_PATH_SAMPLE,
+        })),
+    };
+}
 export function completeMapRewrite(workspaceId, execution, recipe) {
     const parsed = mapRewriteRecipeSchema.parse(recipe);
     const transaction = execution.transaction;
@@ -464,8 +507,79 @@ async function previewGeographyRewrite(nudger, input, context) {
     await context.progress(3, 3, 'Geography model preview complete; workspace files were not changed');
     return result;
 }
+/**
+ * `create_world.synthesisCheck`: run the model's relief and river synthesis only and report every
+ * river that cannot reach its mouth, with its divide. No map is generated and nothing is written.
+ */
+async function previewSynthesisCheck(nudger, input, context) {
+    await context.progress(0, 2, 'Synthesising relief and rivers to check every river');
+    const checked = await nudger.checkSynthesis({
+        workspaceId: context.workspaceId,
+        operations: input.operations,
+        ...(context.principal === undefined ? {} : { principal: context.principal }),
+        ...(context.signal === undefined ? {} : { signal: context.signal }),
+    });
+    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
+        : []);
+    // 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] : []);
+    const compactSemantic = compactMapSemanticDiff(EMPTY_SEMANTIC_DIFF);
+    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: checked.artifacts.length,
+        geography: checked.geography.slice(0, 16).map(geographySummary),
+        synthesisCheck: {
+            passed: valid,
+            unreachableRivers: rivers.length,
+            rivers: rivers.slice(0, 200),
+            carvedCrossings: carved.length,
+            crossings: carved.slice(0, 200),
+        },
+    });
+    result.status = valid ? 'ok' : 'blocked';
+    result.code = valid ? 'MAP_SYNTHESIS_CHECK_READY' : 'MAP_SYNTHESIS_CHECK_BLOCKED';
+    setInlineFilesScanned(result, checked.filesScanned);
+    result.proposedFiles = [];
+    result.diagnostics = checked.diagnostics.slice(0, 100);
+    result.artifacts = checked.artifacts.map(publicArtifactLink);
+    result.validation = {
+        passed: valid,
+        checks: [
+            {
+                id: 'river-synthesis',
+                passed: valid,
+                message: valid
+                    ? 'Every river of the model reaches its mouth'
+                    : `${rivers.length || blocked.length} river(s) or model parts block the synthesis; see MAP_RIVER_UNREACHABLE_MOUTH details.rivers`,
+            },
+        ],
+    };
+    result.blockers = [
+        ...checked.plan.blockers.map(({ code, message, details }) => ({
+            code,
+            message,
+            ...(details === undefined ? {} : { details }),
+        })),
+    ].slice(0, 100);
+    await context.progress(2, 2, 'River check complete; nothing was written');
+    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' && operation.synthesisCheck === true))
+        return previewSynthesisCheck(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');
@@ -490,8 +604,12 @@ export async function previewMapRewrite(nudger, input, context) {
         semanticDiff: compactSemantic.semantic,
         semanticDiffCounts: compactSemantic.counts,
         semanticDiffTruncated: compactSemantic.truncated,
+        ...(planned.plan.territory === undefined
+            ? {}
+            : { territory: planned.plan.territory.map(compactTerritoryReport) }),
         fileCount: planned.plan.changes.length,
         artifactCount: planned.artifacts.length,
+        ...worldOutputsData(planned.plan),
         ...(input.operations.some(({ kind }) => kind === 'create_world') &&
             generatedWorldOperationIds(planned.plan).size === 0
             ? {}

package/dist/hoi4_agent_tools/map/validation.js

@@ -3,6 +3,7 @@ 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 { validateCrossings } from './gameplay/crossing-validation.js';
 import { rgbKey } from './bmp.js';
 import { MAP_PROVINCE_ENGINE_MAX_PIXELS } from './model.js';
 const MAP_DIAGNOSTIC_DETAIL_SAMPLE_LIMIT = 100;
@@ -1206,6 +1207,8 @@ function* validateMapSteps(index, options = {}) {
     yield* cancellationCheckpoint(options.signal);
     yield* validateNetworksAndAdjacencies(index, diagnostics, options);
     yield* cancellationCheckpoint(options.signal);
+    yield* validateCrossings(index, (diagnostic) => addDiagnostic(diagnostics, options, { ...diagnostic, category: 'map' }));
+    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 });
@@ -1247,6 +1250,7 @@ function* validateMapSteps(index, options = {}) {
             passed: !sorted.some(({ code, severity }) => (severity === 'error' || severity === 'blocker') &&
                 (code.startsWith('MAP_ADJACENCY') ||
                     code.startsWith('MAP_IMPASSABLE') ||
+                    code.startsWith('MAP_STRAIT') ||
                     code.startsWith('MAP_SEA_ADJACENCY') ||
                     code.startsWith('MAP_SUPPLY') ||
                     code.startsWith('MAP_RAILWAY'))),

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

@@ -169,3 +169,26 @@ export function buildWorldContext(base) {
     }
     return context;
 }
+/** The tag file a generated world writes for the countries it creates. */
+export const WORLD_COUNTRY_TAG_FILE = 'common/country_tags/zz_world_countries.txt';
+/** Country tags the active sources declare, apart from those of a previously generated world. */
+export function countryTagCatalog(base) {
+    const declared = new Set();
+    const dynamic = new Set();
+    for (const file of base.activeFiles.all) {
+        const name = normalized(file.relativePath);
+        if (!/^common\/country_tags\/[^/]+\.txt$/u.test(name) || name === WORLD_COUNTRY_TAG_FILE)
+            continue;
+        const entries = assignments(documentFor(file).root);
+        const isDynamic = entries.some((entry) => entry.key.value === 'dynamic_tags' &&
+            entry.value.type === 'scalar' &&
+            entry.value.value === 'yes');
+        for (const entry of entries)
+            if (/^[A-Z][A-Z0-9]{2}$/u.test(entry.key.value) && entry.value.type === 'scalar')
+                (isDynamic ? dynamic : declared).add(entry.key.value);
+    }
+    return {
+        static: [...declared].sort(compareCodeUnits),
+        dynamic: [...dynamic].filter((tag) => !declared.has(tag)).sort(compareCodeUnits),
+    };
+}

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

@@ -1,7 +1,25 @@
 import path from 'node:path';
-import { reconcileManagedOutputs } from '../core/managed-outputs.js';
+import { planManagedOutputs } from '../core/managed-outputs.js';
 export const WORLD_OUTPUT_MANIFEST = '.hoi4-agent-world.json';
+/** Country outputs of a generated world: tags, country files, histories, units, flags, bookmark. */
+export function isWorldCountryOutput(relativePath) {
+    const dir = path.posix.dirname(relativePath), file = path.posix.basename(relativePath);
+    return ((['common/countries', 'history/countries'].includes(dir) &&
+        /^[A-Z][A-Z0-9]{2} - [^/]+\.txt$/u.test(file)) ||
+        (dir === 'history/units' && /^[A-Z][A-Z0-9]{2}_world\.txt$/u.test(file)) ||
+        (['gfx/flags', 'gfx/flags/medium', 'gfx/flags/small'].includes(dir) &&
+            /^[A-Z][A-Z0-9]{2}\.tga$/u.test(file)) ||
+        [
+            'common/countries/colors.txt',
+            'common/country_tags/zz_world_countries.txt',
+            'common/bookmarks/world.txt',
+        ].includes(relativePath));
+}
 export function reconcileWorldOutputs(sources, proposed, operationId, mapRoot, stateRoots, localisationRoots) {
+    return planWorldOutputs(sources, proposed, operationId, mapRoot, stateRoots, localisationRoots)
+        .changes;
+}
+export function planWorldOutputs(sources, proposed, operationId, mapRoot, stateRoots, localisationRoots, options = {}) {
     const mapFiles = new Set([
         'provinces.bmp',
         'definition.csv',
@@ -29,15 +47,8 @@ export function reconcileWorldOutputs(sources, proposed, operationId, mapRoot, s
             (dir === `${mapRoot}/terrain` && /^colormap_[a-z0-9_]+\.dds$/u.test(file)) ||
             (dir === `${mapRoot}/strategicregions` && /^\d+.*\.txt$/u.test(file)) ||
             (stateRoots.includes(dir) && /^\d+.*\.txt$/u.test(file)) ||
-            (['common/countries', 'history/countries'].includes(dir) &&
-                /^[A-Z][A-Z0-9]{2} - [^/]+\.txt$/u.test(file)) ||
-            (dir === 'history/units' && /^[A-Z][A-Z0-9]{2}_world\.txt$/u.test(file)) ||
-            (['gfx/flags', 'gfx/flags/medium', 'gfx/flags/small'].includes(dir) &&
-                /^[A-Z][A-Z0-9]{2}\.tga$/u.test(file)) ||
+            isWorldCountryOutput(name) ||
             [
-                'common/countries/colors.txt',
-                'common/country_tags/zz_world_countries.txt',
-                'common/bookmarks/world.txt',
                 'common/on_actions/world.txt',
                 'common/ai_areas/world.txt',
                 'common/ai_strategy_plans/world.txt',
@@ -45,11 +56,12 @@ export function reconcileWorldOutputs(sources, proposed, operationId, mapRoot, s
             localisationRoots.some((root) => name === `${root}/english/world_l_english.yml` ||
                 name === `${root}/replace/world_l_english.yml`));
     };
-    return reconcileManagedOutputs({
+    return planManagedOutputs({
         manifestPath: WORLD_OUTPUT_MANIFEST,
         sources,
         proposed,
         operationId,
         permitsPath,
+        ...(options.releaseCountryOutputs === true ? { releasable: isWorldCountryOutput } : {}),
     });
 }

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

@@ -0,0 +1,152 @@
+/**
+ * Workspace-owned countries in a generated world (ADR 0069): realm points and polygons resolved to
+ * provinces, and the rule for land that no realm reached.
+ */
+import { ServiceError } from '../core/result.js';
+function inside(x, y, polygon) {
+    let result = false;
+    for (let index = 0, previous = polygon.length - 1; index < polygon.length; previous = index++) {
+        const a = polygon[index], b = polygon[previous];
+        if (a.y > y !== b.y > y && x < ((b.x - a.x) * (y - a.y)) / (b.y - a.y) + a.x)
+            result = !result;
+    }
+    return result;
+}
+/** Land provinces with more than half their pixels inside any of the polygons. */
+function coveredProvinces(polygons, raster) {
+    const counts = new Map();
+    const pixels = new Set();
+    for (const polygon of polygons) {
+        const xs = polygon.map(({ x }) => x), ys = polygon.map(({ y }) => y);
+        const left = Math.max(0, Math.floor(Math.min(...xs)));
+        const right = Math.min(raster.width - 1, Math.ceil(Math.max(...xs)));
+        const top = Math.max(0, Math.floor(Math.min(...ys)));
+        const bottom = Math.min(raster.height - 1, Math.ceil(Math.max(...ys)));
+        for (let y = top; y <= bottom; y += 1)
+            for (let x = left; x <= right; x += 1) {
+                const pixel = y * raster.width + x;
+                if (pixels.has(pixel) || !inside(x + 0.5, y + 0.5, polygon))
+                    continue;
+                pixels.add(pixel);
+                const province = raster.pixelProvince[pixel];
+                counts.set(province, (counts.get(province) ?? 0) + 1);
+            }
+    }
+    const covered = new Set();
+    for (const [province, count] of [...counts].sort((left, right) => left[0] - right[0]))
+        if (raster.isLand(province) && count * 2 > raster.provinceSize[province])
+            covered.add(province);
+    return covered;
+}
+function pointProvince(tag, role, point, raster) {
+    const x = Math.floor(point.x), y = Math.floor(point.y);
+    if (x < 0 || y < 0 || x >= raster.width || y >= raster.height)
+        throw new ServiceError('MAP_WORLD_REALM_POINT_OUTSIDE', `The ${role} of ${tag} lies outside the ${raster.width}x${raster.height} world`, { tag, role, point });
+    const province = raster.pixelProvince[y * raster.width + x];
+    if (!raster.isLand(province))
+        throw new ServiceError('MAP_WORLD_REALM_POINT_WATER', `The ${role} of ${tag} lies in water`, {
+            tag,
+            role,
+            point,
+        });
+    return province;
+}
+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));
+    const forced = new Map();
+    const claimedBy = (province) => realms.list[forced.get(province)].tag;
+    const conflict = (tag, role, other, details) => new ServiceError('MAP_WORLD_REALM_POINT_CONFLICT', `The ${role} of ${tag} lies in land ${other}`, { tag, role, ...details });
+    const capitals = [];
+    // Points first, so a claim that covers another realm's point names that point.
+    for (const [index, realm] of realms.list.entries()) {
+        for (const [role, point] of [
+            ['capital', realm.capital],
+            ...(realm.seeds ?? []).map((seed) => ['seed', seed]),
+        ]) {
+            const province = pointProvince(realm.tag, role, point, raster);
+            if (unowned.has(province))
+                throw conflict(realm.tag, role, 'marked unowned', { point, province });
+            if (excluded[index].has(province))
+                throw conflict(realm.tag, role, 'its own exclusion covers', { point, province });
+            const holder = forced.get(province);
+            if (holder !== undefined && holder !== index)
+                throw conflict(realm.tag, role, `that a point of ${claimedBy(province)} names`, {
+                    point,
+                    province,
+                    otherTag: claimedBy(province),
+                });
+            forced.set(province, index);
+            if (role === 'capital')
+                capitals.push(province);
+        }
+    }
+    for (const [index, realm] of realms.list.entries()) {
+        if (realm.claim === undefined)
+            continue;
+        for (const province of coveredProvinces(realm.claim, raster)) {
+            const holder = forced.get(province);
+            if (unowned.has(province) || excluded[index].has(province))
+                throw new ServiceError('MAP_WORLD_REALM_CLAIM_OVERLAP', `A claim of ${realm.tag} covers land that is ${unowned.has(province) ? 'marked unowned' : 'in its own exclusion'}`, { tag: realm.tag, province });
+            if (holder !== undefined && holder !== index)
+                throw new ServiceError('MAP_WORLD_REALM_CLAIM_OVERLAP', `A claim of ${realm.tag} covers land that ${claimedBy(province)} claims or names`, { tag: realm.tag, otherTag: claimedBy(province), province });
+            forced.set(province, index);
+        }
+    }
+    return { capitals, forced, excluded, unowned };
+}
+/**
+ * Land growth did not reach: a landmass that a realm already holds goes to the nearest realm that
+ * may own it; a landmass without any realm follows the island rule.
+ */
+export function assignUnreachedRealmLand(input) {
+    const held = new Set();
+    for (const id of input.owner.keys())
+        held.add(input.part(id));
+    const distance = (a, b) => (a.x - b.x) ** 2 + (a.y - b.y) ** 2;
+    const nearest = (point, allowed) => {
+        let best = -1;
+        let bestDistance = Number.POSITIVE_INFINITY;
+        for (const [realm, capital] of input.capitals.entries()) {
+            if (!allowed(realm))
+                continue;
+            const next = distance(point, input.center(capital));
+            if (next < bestDistance) {
+                best = realm;
+                bestDistance = next;
+            }
+        }
+        return best;
+    };
+    const pending = input.landIds.filter((id) => !input.owner.has(id) && !input.unowned.has(id));
+    const partOwner = new Map();
+    if (input.islands === 'one-owner') {
+        const members = new Map();
+        for (const id of pending)
+            if (!held.has(input.part(id))) {
+                const list = members.get(input.part(id)) ?? [];
+                list.push(id);
+                members.set(input.part(id), list);
+            }
+        for (const [part, ids] of members) {
+            const mean = ids.reduce((sum, id) => ({ x: sum.x + input.center(id).x, y: sum.y + input.center(id).y }), { x: 0, y: 0 });
+            partOwner.set(part, nearest({ x: mean.x / ids.length, y: mean.y / ids.length }, () => true));
+        }
+    }
+    for (const id of pending) {
+        const allowed = (realm) => !input.excluded[realm].has(id);
+        const island = !held.has(input.part(id));
+        if (island && input.islands === 'unowned') {
+            input.unowned.add(id);
+            continue;
+        }
+        const preferred = island ? partOwner.get(input.part(id)) : undefined;
+        const realm = preferred !== undefined && preferred >= 0 && allowed(preferred)
+            ? preferred
+            : nearest(input.center(id), allowed);
+        if (realm < 0)
+            input.unowned.add(id);
+        else
+            input.owner.set(id, realm);
+    }
+}