hoi4-agent-tools 3.10.0 → 4.0.1

package/dist/hoi4_agent_tools/map/operations.js

@@ -5,7 +5,10 @@ import { ServiceError } from '../core/result.js';
 import { applyReplacements, assignments, encodeSource, parseLocalisation, parseClausewitz, } from '../core/source/index.js';
 import { rgbKey } from './bmp.js';
 import { MAP_MASK_CELL_LIMIT, MAP_POLYGON_WORK_LIMIT, MAP_SELECTED_OFFSET_BYTES, MAP_SELECTED_PIXEL_LIMIT, } from './limits.js';
-import { derivedStateCapital, encodeTextDocument, MapWorkspaceIndex, parseMapDate, parseTextDocument, } from './model.js';
+import { derivedStateCapital, encodeTextDocument, LEVEL_STATE_BUILDINGS, MapWorkspaceIndex, parseMapDate, parseTextDocument, } from './model.js';
+import { planReferenceRemap, ReferenceRemapError } from './references.js';
+import { generateWorld } from './world.js';
+import { planMapPositions, planSupplyRebuild } from './derived.js';
 function* cancellationCheckpoint(signal, iteration = 0, stride = 1) {
     if (iteration % stride !== 0)
         return;
@@ -132,6 +135,7 @@ function compileHistory(data, indent, newline) {
     if (data.stateBuildings.size > 0 || data.provinceBuildings.size > 0) {
         rows.push(`${indent}\tbuildings = ${renderBuildings(data, `${indent}\t`, newline)}`);
     }
+    rows.push(...(data.datedHistory ?? []).map((block) => `${indent}\t${block}`));
     return rows.length === 0 ? `{ }` : `{${newline}${rows.join(newline)}${newline}${indent}}`;
 }
 function compileState(data, newline = '\n') {
@@ -165,8 +169,8 @@ function removeAssignments(block, key, replacements) {
         });
     }
 }
-function patchState(state, data, fields) {
-    const replacements = [];
+function patchState(state, data, fields, extra = []) {
+    const replacements = [...extra];
     const stateInsertions = [];
     const newline = state.document.newline;
     const stateIndent = lineIndent(state.document.text, state.assignment.start);
@@ -720,10 +724,14 @@ function syntheticFile(relativePath, bytes, loadOrder) {
         bytes,
     };
 }
-export function indexWithProposedChanges(base, changes) {
+export function indexWithProposedChanges(base, changes, replacedRoots = []) {
     const maximumLoadOrder = base.sourceFiles.reduce((maximum, { loadOrder }) => Math.max(maximum, loadOrder), 0) + 1;
     const byPath = new Map(changes.map((change) => [normalizeRelative(change.relativePath), change]));
-    const files = base.sourceFiles.filter((file) => !(file.rootKind === 'mod' && byPath.has(normalizeRelative(file.relativePath))));
+    // A replace_path folder drops every lower-layer file directly inside it, as the game does.
+    const replaced = replacedRoots.map((root) => normalizeRelative(root).replace(/\/$/u, ''));
+    const files = base.sourceFiles.filter((file) => !(file.rootKind === 'mod' && byPath.has(normalizeRelative(file.relativePath))) &&
+        !(file.rootKind !== 'mod' &&
+            replaced.some((root) => path.posix.dirname(normalizeRelative(file.relativePath)) === root)));
     for (const change of changes) {
         if (change.content !== null)
             files.push(syntheticFile(change.relativePath, Buffer.from(change.content), maximumLoadOrder));
@@ -757,8 +765,12 @@ function proposedChanges(changes) {
         mediaType: change.mediaType,
     }));
 }
+/** Source folders a new world replaces, per plan, so lower layers stop counting. */
+/** Diagnostics an operation raises while applying, drained into the plan after it succeeds. */
+const diagnosticsByPlan = new WeakMap();
+const replacedRootsByPlan = new WeakMap();
 function currentIndex(base, changes) {
-    return indexWithProposedChanges(base, proposedChanges(changes));
+    return indexWithProposedChanges(base, proposedChanges(changes), replacedRootsByPlan.get(changes) ?? []);
 }
 function samePolicy(actual, expected) {
     if (actual === null || typeof actual !== 'object')
@@ -766,22 +778,38 @@ function samePolicy(actual, expected) {
     const object = actual;
     return Object.entries(expected).every(([key, value]) => object[key] === value);
 }
+const AUTOMATIC_MOVE_POLICY = {
+    stateValues: 'proportional-by-land-pixels',
+    ownership: 'retain-in-current-states',
+    provinceBuildings: 'follow-province',
+    victoryPoints: 'follow-province',
+    ports: 'follow-province',
+    supplyNodes: 'follow-province',
+    railways: 'follow-province',
+    positions: 'follow-province',
+    strategicRegion: 'require-same',
+};
 function requireMovePolicy(operation) {
-    const distribution = operation.distribution;
-    if (!samePolicy(distribution, {
-        stateValues: 'retain-in-current-states',
-        ownership: 'retain-in-current-states',
-        provinceBuildings: 'follow-province',
-        victoryPoints: 'follow-province',
-        ports: 'follow-province',
-        supplyNodes: 'follow-province',
-        railways: 'follow-province',
-        positions: 'follow-province',
-    }) ||
-        (distribution?.strategicRegion !== 'require-same' &&
-            distribution?.strategicRegion !== 'move-to-target-region')) {
-        throw new ServiceError('MAP_STATE_DISTRIBUTION_REQUIRED', 'Moving state provinces requires explicit state-value, ownership, building, victory-point, port, network, position, and strategic-region policies');
+    const requested = operation.distribution;
+    if (requested === undefined || requested === 'proportional')
+        return AUTOMATIC_MOVE_POLICY;
+    const distribution = requested;
+    if (!(samePolicy(distribution, { stateValues: 'retain-in-current-states' }) ||
+        samePolicy(distribution, { stateValues: 'proportional-by-land-pixels' })) ||
+        !samePolicy(distribution, {
+            ownership: 'retain-in-current-states',
+            provinceBuildings: 'follow-province',
+            victoryPoints: 'follow-province',
+            ports: 'follow-province',
+            supplyNodes: 'follow-province',
+            railways: 'follow-province',
+            positions: 'follow-province',
+        }) ||
+        (distribution.strategicRegion !== 'require-same' &&
+            distribution.strategicRegion !== 'move-to-target-region')) {
+        throw new ServiceError('MAP_STATE_DISTRIBUTION_REQUIRED', 'A move needs either no distribution (values follow land share) or a complete one with state-value, ownership, building, victory-point, port, network, position, and strategic-region policies');
     }
+    return distribution;
 }
 function requireSplitPolicy(operation) {
     const requested = operation.distribution;
@@ -970,15 +998,37 @@ function splitScalar(total, ratio, policy) {
     }
     return [policy.source, policy.destination];
 }
-function splitMap(total, ratio, policy) {
+/**
+ * Whether a state building is a level (infrastructure, air base, anti-air, radar) rather than a
+ * count of slot buildings. A level applies to the whole state, so a split keeps it in both parts
+ * and a merge keeps the highest; slot buildings are divided and summed.
+ */
+function isLevelStateBuilding(index, building) {
+    const definition = index.buildingDefinitions.get(building);
+    if (definition !== undefined)
+        return !definition.sharesSlots && !definition.provincial;
+    return LEVEL_STATE_BUILDINGS.has(building);
+}
+function splitMap(total, ratio, policy, isLevel = () => false) {
     if (policy.method === 'retain-in-source')
         return [new Map(total), new Map()];
     if (policy.method === 'proportional-by-land-pixels') {
         const source = new Map();
         const destination = new Map();
         for (const [key, value] of total) {
-            const moved = Math.round(value * ratio * 1_000_000) / 1_000_000;
-            source.set(key, value - moved);
+            if (isLevel(key)) {
+                source.set(key, value);
+                destination.set(key, value);
+                continue;
+            }
+            // Whole buildings and resource units stay whole; fractional source values keep two
+            // decimals.
+            const moved = Number.isInteger(value)
+                ? Math.round(value * ratio)
+                : Math.round(value * ratio * 100) / 100;
+            const kept = Math.round((value - moved) * 100) / 100;
+            if (kept !== 0)
+                source.set(key, kept);
             if (moved !== 0)
                 destination.set(key, moved);
         }
@@ -1033,9 +1083,98 @@ function stateMembershipId(index, provinceId) {
         throw new ServiceError('MAP_STATE_MEMBERSHIP_AMBIGUOUS', `Province ${provinceId} belongs to multiple states`);
     return states[0]?.id;
 }
-function commitState(changes, state, data, fields, operationId) {
-    assertDatedStateHistorySafe(state, fields, operationId);
-    addChange(changes, state.file.relativePath, patchState(state, data, fields), operationId, 'text/plain');
+function commitState(changes, state, data, fields, operationId, datedRewrite, datedRewriteFollowsProvinces = datedRewrite !== undefined) {
+    // Distributed dated history already follows the new province membership.
+    assertDatedStateHistorySafe(state, datedRewriteFollowsProvinces
+        ? { ...fields, provinces: false, victoryPoints: false, buildings: false }
+        : fields, operationId);
+    addChange(changes, state.file.relativePath, patchState(state, data, fields, datedRewrite), operationId, 'text/plain');
+}
+/**
+ * Split a state's dated history blocks between the part it keeps and a new state: ownership,
+ * cores and other dated effects apply to both, victory points and province buildings follow
+ * their provinces, level buildings keep their level, and slot buildings divide by the same land
+ * share as the undated values.
+ */
+function distributeDatedHistory(index, state, moved, ratio) {
+    const result = {
+        source: [],
+        destination: [],
+    };
+    if (state.historyBlock === undefined)
+        return result;
+    const text = state.document.text;
+    const newline = state.document.newline;
+    for (const entry of assignments(state.historyBlock)) {
+        if (entry.value.type !== 'block' || parseMapDate(entry.key.value) === undefined)
+            continue;
+        const block = entry.value;
+        // A block without province-bound entries applies unchanged to both parts.
+        if (!block.entries.some((child) => child.type === 'assignment' &&
+            (child.key.value === 'victory_points' || child.key.value === 'buildings'))) {
+            result.destination.push(text.slice(entry.start, entry.end));
+            continue;
+        }
+        const part = (keep, destination, indent) => {
+            const rows = [];
+            for (const child of block.entries) {
+                if (child.type === 'assignment' &&
+                    child.key.value === 'victory_points' &&
+                    child.value.type === 'block') {
+                    const first = child.value.entries[0];
+                    if (first?.type === 'scalar' && !keep(Number(first.value)))
+                        continue;
+                    rows.push(text.slice(child.start, child.end));
+                    continue;
+                }
+                if (child.type === 'assignment' &&
+                    child.key.value === 'buildings' &&
+                    child.value.type === 'block') {
+                    const inner = [];
+                    for (const building of child.value.entries) {
+                        if (building.type === 'assignment' && /^\d+$/u.test(building.key.value)) {
+                            if (keep(Number(building.key.value)))
+                                inner.push(text.slice(building.start, building.end));
+                            continue;
+                        }
+                        if (building.type === 'assignment' &&
+                            building.value.type === 'scalar' &&
+                            /^\d+(?:\.\d+)?$/u.test(building.value.value)) {
+                            const value = Number(building.value.value);
+                            if (isLevelStateBuilding(index, building.key.value)) {
+                                inner.push(`${building.key.value} = ${building.value.value}`);
+                                continue;
+                            }
+                            const share = Math.round(value * ratio);
+                            const kept = destination ? share : value - share;
+                            if (kept > 0)
+                                inner.push(`${building.key.value} = ${kept}`);
+                            continue;
+                        }
+                        inner.push(text.slice(building.start, building.end));
+                    }
+                    if (inner.length > 0)
+                        rows.push(`buildings = {${newline}${inner.map((row) => `${indent}\t\t${row}`).join(newline)}${newline}${indent}\t}`);
+                    continue;
+                }
+                rows.push(text.slice(child.start, child.end));
+            }
+            return rows.length === 0
+                ? undefined
+                : `${entry.key.value} = {${newline}${rows.map((row) => `${indent}\t${row}`).join(newline)}${newline}${indent}}`;
+        };
+        const sourceText = part((id) => !moved.has(id), false, lineIndent(text, entry.start));
+        result.source.push({
+            start: entry.start,
+            end: entry.end,
+            text: sourceText ?? '',
+            description: 'Keep the dated history that follows the remaining provinces',
+        });
+        const destinationText = part((id) => moved.has(id), true, '\t\t');
+        if (destinationText !== undefined)
+            result.destination.push(destinationText);
+    }
+    return result;
 }
 function assertDatedStateHistorySafe(state, fields, operationId) {
     if (state.historyBlock === undefined)
@@ -1088,20 +1227,6 @@ function assertDatedStateHistorySafe(state, fields, operationId) {
         });
     }
 }
-function assertNoDatedStateHistory(state, operationId) {
-    if (state.historyBlock === undefined)
-        return;
-    const dated = assignments(state.historyBlock).find((entry) => entry.value.type === 'block' && parseMapDate(entry.key.value) !== undefined);
-    if (dated === undefined)
-        return;
-    throw new ServiceError('MAP_DATED_STATE_DISTRIBUTION_UNSUPPORTED', `State ${state.id} has dated history that cannot be distributed to a new or merged state`, {
-        operationId,
-        stateId: state.id,
-        datedAt: dated.key.value,
-        sourcePath: state.file.displayPath,
-        sourceOffset: dated.start,
-    });
-}
 function commitRegion(changes, region, provinces, operationId) {
     addChange(changes, region.file.relativePath, patchRegion(region, provinces), operationId, 'text/plain');
 }
@@ -1222,7 +1347,7 @@ function applyUpdateState(base, changes, operation) {
     commitState(changes, state, desired, fields, operation.id);
 }
 function applyMoveStateProvinces(base, changes, operation) {
-    requireMovePolicy(operation);
+    const policy = requireMovePolicy(operation);
     const index = currentIndex(base, changes);
     const source = index.statesById.get(operation.sourceStateId);
     const target = index.statesById.get(operation.targetStateId);
@@ -1239,6 +1364,32 @@ function applyMoveStateProvinces(base, changes, operation) {
     const sourceData = cloneState(source);
     const targetData = cloneState(target);
     const movingSet = new Set(moving);
+    const redistribute = policy.stateValues === 'proportional-by-land-pixels';
+    if (redistribute) {
+        const sourcePixels = provincePixelTotal(index, source.provinces);
+        const movedPixels = provincePixelTotal(index, moving);
+        if (sourcePixels <= 0 || movedPixels <= 0)
+            throw new ServiceError('MAP_STATE_DISTRIBUTION_GEOMETRY_MISSING', 'Proportional state distribution requires province geometry');
+        const ratio = movedPixels / sourcePixels;
+        const proportional = { method: 'proportional-by-land-pixels' };
+        // The share that leaves the source joins the target: people and resources and slot
+        // buildings are carried over, and a level (infrastructure, air base) is the higher of both.
+        const [keptManpower, movedManpower] = splitScalar(source.manpower, ratio, proportional);
+        sourceData.manpower = keptManpower;
+        targetData.manpower = target.manpower + movedManpower;
+        const [keptResources, movedResources] = splitMap(source.resources, ratio, proportional);
+        sourceData.resources = keptResources;
+        targetData.resources = new Map(target.resources);
+        addMaps(targetData.resources, movedResources);
+        const isLevel = (building) => isLevelStateBuilding(index, building);
+        const [keptBuildings, movedBuildings] = splitMap(source.stateBuildings, ratio, proportional, isLevel);
+        sourceData.stateBuildings = keptBuildings;
+        targetData.stateBuildings = new Map(target.stateBuildings);
+        for (const [building, value] of movedBuildings)
+            targetData.stateBuildings.set(building, isLevel(building)
+                ? Math.max(value, targetData.stateBuildings.get(building) ?? 0)
+                : (targetData.stateBuildings.get(building) ?? 0) + value);
+    }
     sourceData.provinces = sourceData.provinces.filter((id) => !movingSet.has(id));
     targetData.provinces = uniqueSorted([...targetData.provinces, ...moving]);
     const movedVps = sourceData.victoryPoints.filter(({ provinceId }) => movingSet.has(provinceId));
@@ -1256,13 +1407,25 @@ function applyMoveStateProvinces(base, changes, operation) {
     if (targetRegionIds.size !== 1)
         throw new ServiceError('MAP_TARGET_REGION_AMBIGUOUS', 'Target state spans multiple strategic regions');
     const targetRegionId = required([...targetRegionIds][0], 'MAP_TARGET_REGION_AMBIGUOUS', 'Target state has no strategic region');
-    if (operation.distribution.strategicRegion === 'require-same' &&
+    if (policy.strategicRegion === 'require-same' &&
         [...movingRegionIds].some((id) => id !== targetRegionId)) {
         throw new ServiceError('MAP_STATE_REGION_DISTRIBUTION_CONFLICT', 'Moved provinces are not in the target strategic region');
     }
-    commitState(changes, source, sourceData, { provinces: true, victoryPoints: true, buildings: true }, operation.id);
-    commitState(changes, target, targetData, { provinces: true, victoryPoints: true, buildings: true }, operation.id);
-    if (operation.distribution.strategicRegion === 'move-to-target-region') {
+    commitState(changes, source, sourceData, {
+        provinces: true,
+        victoryPoints: true,
+        buildings: true,
+        manpower: redistribute,
+        resources: redistribute,
+    }, operation.id);
+    commitState(changes, target, targetData, {
+        provinces: true,
+        victoryPoints: true,
+        buildings: true,
+        manpower: redistribute,
+        resources: redistribute,
+    }, operation.id);
+    if (policy.strategicRegion === 'move-to-target-region') {
         for (const regionId of movingRegionIds) {
             if (regionId === targetRegionId)
                 continue;
@@ -1285,7 +1448,6 @@ function* applySplitState(base, changes, allocations, operation, signal) {
     const source = index.statesById.get(sourceStateId);
     if (source === undefined)
         throw new ServiceError('MAP_STATE_NOT_FOUND', `State ${sourceStateId} does not exist`);
-    assertNoDatedStateHistory(source, operation.id);
     const selectedSet = new Set(selected);
     if (selected.length === 0 || selected.some((id) => !source.provinces.includes(id))) {
         throw new ServiceError('MAP_STATE_PROVINCE_SELECTION_INVALID', 'Every new-state province must belong to the source state');
@@ -1329,7 +1491,7 @@ function* applySplitState(base, changes, allocations, operation, signal) {
     destinationData.provinces = selected;
     [sourceData.manpower, destinationData.manpower] = splitScalar(source.manpower, ratio, policy.manpower);
     [sourceData.resources, destinationData.resources] = splitMap(source.resources, ratio, policy.resources);
-    [sourceData.stateBuildings, destinationData.stateBuildings] = splitMap(source.stateBuildings, ratio, policy.stateBuildings);
+    [sourceData.stateBuildings, destinationData.stateBuildings] = splitMap(source.stateBuildings, ratio, policy.stateBuildings, (building) => isLevelStateBuilding(index, building));
     [sourceData.owner, destinationData.owner] = splitTag(source.owner, policy.owner);
     [sourceData.controller, destinationData.controller] = splitTag(source.controller, policy.controller);
     [sourceData.cores, destinationData.cores] = splitTags(source.cores, policy.cores);
@@ -1338,17 +1500,20 @@ function* applySplitState(base, changes, allocations, operation, signal) {
     destinationData.victoryPoints = destinationData.victoryPoints.filter(({ provinceId }) => selectedSet.has(provinceId));
     sourceData.provinceBuildings = new Map([...sourceData.provinceBuildings].filter(([provinceId]) => !selectedSet.has(provinceId)));
     destinationData.provinceBuildings = new Map([...destinationData.provinceBuildings].filter(([provinceId]) => selectedSet.has(provinceId)));
+    const dated = distributeDatedHistory(index, source, selectedSet, ratio);
+    destinationData.datedHistory = dated.destination;
     commitState(changes, source, sourceData, {
         manpower: true,
         resources: true,
         provinces: true,
-        owner: true,
-        controller: true,
-        cores: true,
-        claims: true,
+        // Copied ownership is unchanged in the source and needs no rewrite.
+        owner: policy.owner.method !== 'copy-source',
+        controller: policy.controller.method !== 'copy-source',
+        cores: policy.cores.method !== 'copy-source',
+        claims: policy.claims.method !== 'copy-source',
         victoryPoints: true,
         buildings: true,
-    }, operation.id);
+    }, operation.id, dated.source);
     const requestedName = operation.fileName ?? `${allocation.id}-AGENT_STATE.txt`;
     const safeName = requestedName.replaceAll('\\', '/').split('/').at(-1) ?? requestedName;
     if (!/^[-A-Za-z0-9_.]+\.txt$/u.test(safeName))
@@ -1360,8 +1525,17 @@ function* applySplitState(base, changes, allocations, operation, signal) {
     }
     addChange(changes, relativePath, compileState(destinationData, source.document.newline), operation.id, 'text/plain');
     remapBuildingPositionStates(index, changes, selectedSet, allocation.id, operation.id);
+    if (operation.remapReferences !== undefined)
+        remapScriptReferences(base, changes, operation.id, {
+            entity: 'state',
+            mapping: [{ from: source.id, to: [source.id, allocation.id] }],
+            readOnlySources: operation.remapReferences,
+        });
 }
 function requireMergeStatePolicy(operation) {
+    // Every merge policy field has one allowed value, so an omitted policy means that one.
+    if (operation.distribution === undefined)
+        return;
     if (!samePolicy(operation.distribution, {
         stateValues: 'sum-into-target',
         ownership: 'retain-target',
@@ -1403,8 +1577,26 @@ function applyMergeStates(base, changes, operation) {
     if (target === undefined || sourceIds.length === 0 || sources.length !== sourceIds.length) {
         throw new ServiceError('MAP_STATE_SELECTION_INVALID', 'Merge target and source states must exist');
     }
-    for (const source of sources)
-        assertNoDatedStateHistory(source, operation.id);
+    // Dated ownership, cores and effects of a merged state carry over to the target; dated
+    // building levels cannot be combined, because each part's later value replaces its own.
+    const carriedHistory = [];
+    for (const source of sources) {
+        if (source.historyBlock === undefined)
+            continue;
+        for (const entry of assignments(source.historyBlock)) {
+            if (entry.value.type !== 'block' || parseMapDate(entry.key.value) === undefined)
+                continue;
+            if (assignments(entry.value, 'buildings').length > 0)
+                throw new ServiceError('MAP_DATED_STATE_DISTRIBUTION_UNSUPPORTED', `State ${source.id} sets building levels in dated history (${entry.key.value}), which a merge cannot combine; move its provinces with move_state_provinces or edit that block first`, {
+                    operationId: operation.id,
+                    stateId: source.id,
+                    datedAt: entry.key.value,
+                    sourcePath: source.file.displayPath,
+                    sourceOffset: entry.start,
+                });
+            carriedHistory.push(source.document.text.slice(entry.start, entry.end));
+        }
+    }
     const regionIds = new Set([...target.provinces, ...sources.flatMap((state) => state.provinces)].map((id) => regionMembershipId(index, id)));
     if (regionIds.size !== 1)
         throw new ServiceError('MAP_STATE_REGION_DISTRIBUTION_CONFLICT', 'Merged states must share one strategic region');
@@ -1412,7 +1604,10 @@ function applyMergeStates(base, changes, operation) {
     for (const source of sources) {
         data.manpower += source.manpower;
         addMaps(data.resources, source.resources);
-        addMaps(data.stateBuildings, source.stateBuildings);
+        for (const [building, value] of source.stateBuildings)
+            data.stateBuildings.set(building, isLevelStateBuilding(index, building)
+                ? Math.max(data.stateBuildings.get(building) ?? 0, value)
+                : (data.stateBuildings.get(building) ?? 0) + value);
         data.provinces.push(...source.provinces);
         data.cores.push(...source.cores);
         data.claims.push(...source.claims);
@@ -1423,6 +1618,20 @@ function applyMergeStates(base, changes, operation) {
     data.provinces = uniqueSorted(data.provinces);
     data.cores = uniqueStrings(data.cores);
     data.claims = uniqueStrings(data.claims);
+    const historyClose = target.historyBlock?.close;
+    const carried = [];
+    if (carriedHistory.length > 0 && historyClose !== undefined) {
+        const indent = lineIndent(target.document.text, target.historyBlock.start);
+        const newline = target.document.newline;
+        carried.push({
+            start: historyClose.start,
+            end: historyClose.start,
+            text: carriedHistory.map((block) => `\t${block}${newline}${indent}`).join(''),
+            description: 'Carry dated history from merged states',
+        });
+    }
+    else
+        data.datedHistory = carriedHistory;
     commitState(changes, target, data, {
         manpower: true,
         resources: true,
@@ -1431,11 +1640,17 @@ function applyMergeStates(base, changes, operation) {
         claims: true,
         victoryPoints: true,
         buildings: true,
-    }, operation.id);
+    }, operation.id, carried.length === 0 ? undefined : carried, false);
     for (const source of sources) {
         addChange(changes, source.file.relativePath, removalContent(index, source.file, `State ${source.id} merged into ${target.id}`), operation.id, 'text/plain');
     }
     remapBuildingPositionStates(index, changes, new Set(sources.flatMap(({ provinces }) => provinces)), target.id, operation.id);
+    if (operation.remapReferences !== undefined)
+        remapScriptReferences(base, changes, operation.id, {
+            entity: 'state',
+            mapping: sources.map((source) => ({ from: source.id, to: target.id })),
+            readOnlySources: operation.remapReferences,
+        });
 }
 function pointInEvenOddPolygon(x, y, points) {
     let inside = false;
@@ -3026,6 +3241,149 @@ function applyRenumberMapEntity(base, changes, operation) {
     if (operation.renameLocalisation ?? true)
         renameLocalisationKeys(currentIndex(base, changes), changes, localisationKeys, operation.id);
 }
+/** Folders a new world replaces in the base game. */
+export const WORLD_REPLACED_ROOTS = [
+    'history/states',
+    'history/countries',
+    'history/units',
+    'map/strategicregions',
+    'map/supplyareas',
+    'common/bookmarks',
+];
+/** Add replace_path lines to descriptor.mod, creating a minimal descriptor when none exists. */
+function descriptorWithReplacePaths(index, roots) {
+    const existing = index.sourceFiles.find((file) => file.rootKind === 'mod' && normalizeRelative(file.relativePath) === 'descriptor.mod');
+    const textValue = existing === undefined
+        ? 'version="1.0"\nname="New World"\nsupported_version="1.*"\n'
+        : existing.bytes.toString('utf8');
+    const newline = textValue.includes('\r\n') ? '\r\n' : '\n';
+    const present = new Set([...textValue.matchAll(/replace_path\s*=\s*"([^"]+)"/gu)].map((match) => normalizeRelative(match[1])));
+    const missing = roots.filter((root) => !present.has(normalizeRelative(root)));
+    const body = textValue.endsWith('\n') ? textValue : `${textValue}${newline}`;
+    return Buffer.from(`${body}${missing.map((root) => `replace_path="${root}"`).join(newline)}${missing.length > 0 ? newline : ''}`, 'utf8');
+}
+function applyCreateWorld(base, changes, operation) {
+    const mapRoot = base.sourceRoots.map[0] ?? 'map';
+    const world = generateWorld({
+        width: operation.width ?? 1_024,
+        height: operation.height ?? 512,
+        seed: operation.seed ?? 1,
+        landCoverage: operation.landCoverage ?? 0.35,
+        continents: operation.continents ?? 3,
+        ...(operation.landPolygons === undefined ? {} : { landPolygons: operation.landPolygons }),
+        landProvincePixels: operation.landProvincePixels ?? 400,
+        seaProvincePixels: operation.seaProvincePixels ?? 2_500,
+        provincesPerState: operation.provincesPerState ?? 5,
+        landProvincesPerRegion: operation.landProvincesPerRegion ?? 25,
+        seaProvincesPerRegion: operation.seaProvincesPerRegion ?? 10,
+        countries: operation.countries,
+        ...(operation.continentNames === undefined
+            ? {}
+            : { continentNames: operation.continentNames }),
+        startDate: operation.startDate ?? '1936.1.1',
+        rivers: operation.rivers ?? 8,
+    }, {
+        palettes: {},
+        mapRoot,
+        statesRoot: base.sourceRoots.states[0] ?? 'history/states',
+        localisationRoot: base.sourceRoots.localisation[0] ?? 'localisation',
+    });
+    const roots = operation.replaceBaseGame === false ? [] : [...WORLD_REPLACED_ROOTS];
+    replacedRootsByPlan.set(changes, roots);
+    for (const file of world.files)
+        addChange(changes, file.relativePath, file.content, operation.id, file.mediaType);
+    // Start from empty derived files so no base-game position or supply line survives.
+    for (const name of [
+        'buildings.txt',
+        'unitstacks.txt',
+        'weatherpositions.txt',
+        'supply_nodes.txt',
+        'railways.txt',
+    ])
+        addChange(changes, `${mapRoot}/${name}`, Buffer.alloc(0), operation.id, 'text/plain');
+    if (roots.length > 0)
+        addChange(changes, 'descriptor.mod', descriptorWithReplacePaths(base, roots), operation.id, 'text/plain');
+    const generated = currentIndex(base, changes);
+    for (const file of planMapPositions(generated, { mode: 'replace' }))
+        addChange(changes, file.relativePath, file.content, operation.id, 'text/plain');
+    const positioned = currentIndex(base, changes);
+    for (const file of planSupplyRebuild(positioned, { mode: 'replace' }))
+        addChange(changes, file.relativePath, file.content, operation.id, 'text/plain');
+    return [
+        {
+            code: 'MAP_WORLD_CREATED',
+            severity: 'info',
+            category: 'map',
+            operationId: operation.id,
+            message: `Created a ${world.summary.width}x${world.summary.height} world: ${world.summary.landProvinces} land, ${world.summary.seaProvinces} sea and ${world.summary.lakeProvinces} lake provinces, ${world.summary.states} states, ${world.summary.landRegions + world.summary.seaRegions} strategic regions, ${world.summary.countries} countries and ${world.summary.rivers} rivers`,
+            details: world.summary,
+        },
+        ...(roots.length === 0
+            ? []
+            : [
+                {
+                    code: 'MAP_WORLD_LAUNCHER_REPLACE_PATHS',
+                    severity: 'info',
+                    category: 'map',
+                    operationId: operation.id,
+                    message: `descriptor.mod replaces ${roots.join(', ')}; the launcher's .mod file beside the mod folder needs the same replace_path lines`,
+                    details: { replacePaths: roots },
+                },
+            ]),
+    ];
+}
+function applyRegenerateMapPositions(base, changes, operation) {
+    const index = currentIndex(base, changes);
+    for (const file of planMapPositions(index, operation))
+        addChange(changes, file.relativePath, file.content, operation.id, 'text/plain');
+}
+function applyRebuildSupply(base, changes, operation) {
+    const index = currentIndex(base, changes);
+    for (const file of planSupplyRebuild(index, operation))
+        addChange(changes, file.relativePath, file.content, operation.id, 'text/plain');
+}
+/**
+ * Rewrite the script references of one entity kind in the proposed changes. Returns the number
+ * of script files changed; an empty result is an error only when the caller asks for it.
+ */
+function remapScriptReferences(base, changes, operationId, request) {
+    const index = currentIndex(base, changes);
+    let plan;
+    try {
+        plan = planReferenceRemap(index.sourceFiles, request, (document, replacements) => applyReplacements(document, replacements));
+    }
+    catch (error) {
+        if (error instanceof ReferenceRemapError)
+            throw new ServiceError(error.code, error.message, error.details);
+        throw error;
+    }
+    for (const file of plan.files)
+        addChange(changes, file.relativePath, file.content, operationId, 'text/plain');
+    if (plan.unchanged.length > 0) {
+        const raised = diagnosticsByPlan.get(changes) ?? [];
+        for (const item of plan.unchanged.slice(0, 20))
+            raised.push({
+                code: 'MAP_REFERENCE_NEEDS_REVIEW',
+                severity: 'info',
+                category: 'map',
+                message: `${item.relativePath}:${item.line} names ${request.entity} ${item.id} through ${item.key}, which takes one value; it was left as it is. Point it at the successor you want.`,
+                operationId,
+                details: { ...item, entity: request.entity },
+            });
+        diagnosticsByPlan.set(changes, raised);
+    }
+    return plan.files.length;
+}
+function applyRemapMapReferences(base, changes, operation) {
+    const changed = remapScriptReferences(base, changes, operation.id, {
+        entity: operation.entity,
+        mapping: operation.mapping,
+        readOnlySources: operation.readOnlySources ?? 'refuse',
+        ...(operation.pathPrefixes === undefined ? {} : { pathPrefixes: operation.pathPrefixes }),
+    });
+    if (changed === 0)
+        throw new ServiceError('MAP_REFERENCE_REMAP_EMPTY', `No script references the mapped ${operation.entity} IDs`, { entity: operation.entity, from: operation.mapping.map(({ from }) => from) });
+}
 function applyEntityLocator(base, changes, operation) {
     const index = currentIndex(base, changes);
     const matching = index.entityLocators.filter(({ entity, name }) => entity === operation.entity && name === operation.name);
@@ -3084,7 +3442,9 @@ function* planMapOperationSteps(base, operations, signal) {
         const allocationsCheckpoint = allocations.length;
         const boundsCheckpoint = expectedChangedBounds;
         try {
-            if (operation.kind === 'move_state_provinces')
+            if (operation.kind === 'create_world')
+                diagnostics.push(...applyCreateWorld(base, changes, operation));
+            else if (operation.kind === 'move_state_provinces')
                 applyMoveStateProvinces(base, changes, operation);
             else if (operation.kind === 'update_state')
                 applyUpdateState(base, changes, operation);
@@ -3107,10 +3467,19 @@ function* planMapOperationSteps(base, operations, signal) {
                 applyEntityLocator(base, changes, operation);
             else if (operation.kind === 'renumber_map_entity')
                 applyRenumberMapEntity(base, changes, operation);
+            else if (operation.kind === 'remap_map_references')
+                applyRemapMapReferences(base, changes, operation);
+            else if (operation.kind === 'regenerate_map_positions')
+                applyRegenerateMapPositions(base, changes, operation);
+            else if (operation.kind === 'rebuild_supply')
+                applyRebuildSupply(base, changes, operation);
             else
                 handleSimpleOperation(base, changes, operation);
+            diagnostics.push(...(diagnosticsByPlan.get(changes) ?? []));
+            diagnosticsByPlan.delete(changes);
         }
         catch (error) {
+            diagnosticsByPlan.delete(changes);
             if (signal?.aborted)
                 throw error;
             changes.clear();
@@ -3142,7 +3511,7 @@ function* planMapOperationSteps(base, operations, signal) {
     }
     const finalized = proposedChanges(changes);
     yield* cancellationCheckpoint(signal);
-    const finalIndex = indexWithProposedChanges(base, finalized);
+    const finalIndex = indexWithProposedChanges(base, finalized, replacedRootsByPlan.get(changes) ?? []);
     return {
         changes: finalized,
         diagnostics,