hoi4-agent-tools 4.0.5 → 4.2.0

package/dist/hoi4_agent_tools/event/source-analysis.js

@@ -86,6 +86,21 @@ const STATE_RULES = {
     multiply_variable: { kind: 'variable', access: 'read_write' },
     divide_variable: { kind: 'variable', access: 'read_write' },
     clamp_variable: { kind: 'variable', access: 'read_write' },
+    round_variable: { kind: 'variable', access: 'read_write' },
+    modulo_variable: { kind: 'variable', access: 'read_write' },
+    randomize_variable: { kind: 'variable', access: 'read_write' },
+    set_variable_to_random: { kind: 'variable', access: 'write' },
+    // `check_variable` and `has_variable` read a temporary variable of the same name as well.
+    set_temp_variable: { kind: 'variable', access: 'write', temporary: true },
+    set_temp_variable_to_random: { kind: 'variable', access: 'write', temporary: true },
+    add_to_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
+    subtract_from_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
+    multiply_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
+    divide_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
+    clamp_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
+    round_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
+    modulo_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
+    randomize_temp_variable: { kind: 'variable', access: 'read_write', temporary: true },
     check_variable: { kind: 'variable', access: 'read' },
     has_variable: { kind: 'variable', access: 'read' },
     is_variable_equal: { kind: 'variable', access: 'read' },
@@ -101,6 +116,16 @@ const STATE_RULES = {
     remove_from_array: { kind: 'array', access: 'read_write', nameField: 'array' },
     is_in_array: { kind: 'array', access: 'read', nameField: 'array' },
     clear_array: { kind: 'array', access: 'clear' },
+    resize_array: { kind: 'array', access: 'write', nameField: 'array' },
+    add_to_temp_array: { kind: 'array', access: 'write', nameField: 'array', temporary: true },
+    remove_from_temp_array: {
+        kind: 'array',
+        access: 'read_write',
+        nameField: 'array',
+        temporary: true,
+    },
+    resize_temp_array: { kind: 'array', access: 'write', nameField: 'array', temporary: true },
+    clear_temp_array: { kind: 'array', access: 'clear', temporary: true },
     save_event_target_as: { kind: 'event_target', access: 'replace' },
     has_event_target: { kind: 'event_target', access: 'read' },
     save_global_event_target_as: { kind: 'global_event_target', access: 'replace' },
@@ -153,7 +178,59 @@ const NON_EXECUTING_BLOCKS = new Set([
     'mean_time_to_happen',
     'effect_tooltip',
     'custom_effect_tooltip',
+    // Condition blocks of decisions, missions, ideas, focuses, raids and characters.
+    'visible',
+    'available',
+    'allowed',
+    'allowed_civil_war',
+    'allowed_to_remove',
+    'cancel_trigger',
+    'remove_trigger',
+    'target_trigger',
+    'target_root_trigger',
+    'activation',
+    'ai_will_do',
+    'bypass',
+    'allow_branch',
+    'hidden_trigger',
+    'custom_trigger_tooltip',
+    'and',
+    'or',
+    'not',
+    'nor',
+    'nand',
 ]);
+/** Native effects whose body holds further effects rather than named arguments. */
+const NATIVE_EFFECT_CONTAINERS = new Set([
+    'create_dynamic_country',
+    'custom_override_tooltip',
+    'effect_tooltip',
+    'for_each_loop',
+    'for_each_scope_loop',
+    'for_loop_effect',
+    'hidden_effect',
+    'if',
+    'random',
+    'random_list',
+    'random_scope_in_array',
+    'while_loop_effect',
+]);
+/** Inside a native effect such as `add_building_construction`, `key = yes` is an argument. */
+function isNativeArgumentBlock(normalizedKey) {
+    return (nativeEffectKeys.has(normalizedKey) &&
+        !NATIVE_EFFECT_CONTAINERS.has(normalizedKey) &&
+        !CONTROL_BLOCKS.has(normalizedKey) &&
+        SCOPE_BLOCKS[normalizedKey] === undefined &&
+        !/^(?:every|random|global_every)_/u.test(normalizedKey));
+}
+/** Effect blocks of definition files by naming convention: `on_add`, `complete_effect`, `effects`. */
+function isConventionalEffectBlock(normalizedKey) {
+    return /^on_[a-z0-9_]+$|(?:^|_)effects?$/u.test(normalizedKey);
+}
+/** Trigger iterators such as `any_owned_state` hold conditions, never effects. */
+function isTriggerIterator(normalizedKey) {
+    return /^(?:any|all)_/u.test(normalizedKey);
+}
 const TOOLTIP_ONLY_BLOCKS = new Set(['effect_tooltip', 'custom_effect_tooltip']);
 const COUNTRY_ON_ACTIONS = new Set([
     'on_startup',
@@ -836,6 +913,7 @@ class FragmentAnalyzer {
             helperStack: [],
             semanticPath: ['other'],
             effectContext: true,
+            inferMissingHelpers: false,
         });
         if (this.edges.length + this.stateAccesses.length > before) {
             this.addNode({
@@ -913,6 +991,8 @@ class FragmentAnalyzer {
                 return;
             }
             if (this.context.inventoryComplete !== false &&
+                context.nativeArguments !== true &&
+                context.inferMissingHelpers !== false &&
                 missingHelperCandidate(key, entry.value, effectContext)) {
                 const target = this.unresolvedNode('missing_helper', key, entry, context.ownerId, semanticPath);
                 this.addEdge(context.ownerId, target, 'scripted_effect_call', entry, context.conditions, {
@@ -1039,7 +1119,13 @@ class FragmentAnalyzer {
                 conditions,
                 sourceScope: scope,
                 phase,
-                effectContext: NON_EXECUTING_BLOCKS.has(normalizedKey) ? false : effectContext,
+                effectContext: NON_EXECUTING_BLOCKS.has(normalizedKey) || isTriggerIterator(normalizedKey)
+                    ? false
+                    : effectContext,
+                nativeArguments: context.nativeArguments === true || isNativeArgumentBlock(normalizedKey),
+                ...(context.inferMissingHelpers === false && isConventionalEffectBlock(normalizedKey)
+                    ? { inferMissingHelpers: true }
+                    : {}),
                 suppressSemantics: context.suppressSemantics === true || TOOLTIP_ONLY_BLOCKS.has(normalizedKey),
                 semanticPath,
                 ...(scopeExpression === undefined ? {} : { scopeExpression }),
@@ -1296,7 +1382,8 @@ class FragmentAnalyzer {
         return id;
     }
     recordState(assignment, context, semanticPath) {
-        const keyedTarget = /^(event_target|global_event_target|scope):([A-Za-z0-9_.-]+)$/u.exec(assignment.key.value);
+        // `event_target:founder.districts` names the target `founder`; the rest is a value in its scope.
+        const keyedTarget = /^(event_target|global_event_target|scope):([A-Za-z0-9_-]+)(?:\.[A-Za-z0-9_.-]+)?$/u.exec(assignment.key.value);
         if (keyedTarget !== null) {
             this.addState(context, keyedTarget[1] === 'global_event_target'
                 ? 'global_event_target'
@@ -1307,7 +1394,7 @@ class FragmentAnalyzer {
         const rule = STATE_RULES[assignment.key.value];
         if (rule === undefined) {
             const raw = valueText(this.document, assignment.value);
-            for (const match of raw.matchAll(/\b(event_target|global_event_target):([A-Za-z0-9_.-]+)/gu)) {
+            for (const match of raw.matchAll(/\b(event_target|global_event_target):([A-Za-z0-9_-]+)/gu)) {
                 this.addState(context, match[1] === 'global_event_target' ? 'global_event_target' : 'event_target', match[2], 'read', assignment, semanticPath, false);
             }
             return;
@@ -1336,7 +1423,10 @@ class FragmentAnalyzer {
         else if (access === 'write') {
             this.#seenStateWriters.add(writerKey);
         }
-        this.addState(context, kind, name, access, assignment, semanticPath, isDynamic(name), rule.storage === undefined ? {} : { storage: rule.storage });
+        this.addState(context, kind, name, access, assignment, semanticPath, isDynamic(name), {
+            ...(rule.storage === undefined ? {} : { storage: rule.storage }),
+            ...(rule.temporary === true ? { temporary: true } : {}),
+        });
     }
     addState(context, kind, name, access, node, _semanticPath, dynamic, metadata = {}) {
         const semantic = {

package/dist/hoi4_agent_tools/event/state-keys.js

@@ -0,0 +1,63 @@
+const SCOPE_KINDS = [
+    'country',
+    'state',
+    'province',
+    'unit_leader',
+    'operative',
+    'character',
+    'global',
+    'unknown',
+];
+/** Identity of one stored value: variables and arrays live per scope, saved scopes per storage. */
+export function stateKey(value) {
+    const scope = value.kind === 'variable' || value.kind === 'array' ? `:${value.scope}` : '';
+    const storage = value.kind === 'saved_scope'
+        ? `:${value.metadata.storage === 'global' || value.metadata.storage === 'local'
+            ? value.metadata.storage
+            : 'unknown'}`
+        : '';
+    return `${value.kind}:${value.name}${scope}${storage}`;
+}
+/** Keys of every write that a read of this value can observe. */
+export function compatibleProducerKeys(value) {
+    // `event_target:name` reads local and global targets alike, whereas
+    // `global_event_target:name` reads only global ones.
+    if (value.kind === 'event_target') {
+        return [stateKey(value), `global_event_target:${value.name}`];
+    }
+    // A helper body runs in whatever scope calls it, so its scope is unknown. A write there can
+    // reach a read in any scope, and a read there can observe a write in any scope.
+    if (value.kind === 'variable' || value.kind === 'array') {
+        const scopes = value.scope === 'unknown' ? SCOPE_KINDS : [value.scope, 'unknown'];
+        const keys = scopes.map((scope) => `${value.kind}:${value.name}:${scope}`);
+        // `entries^num` and `entries^3` read the array `entries`; `GER.value` and `ROOT.value` read
+        // `value` in another scope, which may be written under its bare name in any scope.
+        const element = /^([^^]+)\^/u.exec(value.name)?.[1];
+        if (element !== undefined)
+            keys.push(...SCOPE_KINDS.map((scope) => `array:${unscopedName(element)}:${scope}`));
+        const bare = unscopedName(value.name);
+        if (bare !== value.name)
+            keys.push(...SCOPE_KINDS.map((scope) => `${value.kind}:${bare}:${scope}`));
+        return [...new Set(keys)];
+    }
+    if (value.kind !== 'saved_scope' ||
+        value.metadata.storage === 'global' ||
+        value.metadata.storage === 'local') {
+        return [stateKey(value)];
+    }
+    return [
+        `saved_scope:${value.name}:global`,
+        `saved_scope:${value.name}:local`,
+        `saved_scope:${value.name}:unknown`,
+    ];
+}
+/** `GER.value`, `ROOT.FROM.value` or `var:target.value` without its scope prefix. */
+function unscopedName(name) {
+    const scoped = /^(?:(?:[A-Z][A-Z0-9]{2}|ROOT|FROM|PREV|THIS|OWNER|CONTROLLER|CAPITAL)\.|(?:var|event_target):[A-Za-z0-9_]+\.)+(.+)$/u.exec(name);
+    return scoped?.[1] ?? name;
+}
+export function hasUnknownSavedScopeStorage(value) {
+    return (value.kind === 'saved_scope' &&
+        value.metadata.storage !== 'global' &&
+        value.metadata.storage !== 'local');
+}

package/dist/hoi4_agent_tools/event/summary.js

@@ -0,0 +1,130 @@
+import { compareCodeUnits } from '../core/canonical.js';
+/** Findings returned inline, before an agent opens the linked report. */
+export const EVENT_INLINE_FINDINGS = 10;
+const EVENT_INLINE_CODES = 10;
+const EVENT_INLINE_EVENT_IDS = 20;
+const EVENT_INLINE_MESSAGE_LENGTH = 300;
+const CLASSIFICATION_ORDER = {
+    confirmed_error: 0,
+    probable_defect: 1,
+    design_warning: 2,
+    unresolved_analysis: 3,
+};
+const CONFIDENCE_ORDER = {
+    confirmed: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+    unresolved: 4,
+};
+function countBy(values, key) {
+    const counts = new Map();
+    for (const value of values)
+        counts.set(key(value), (counts.get(key(value)) ?? 0) + 1);
+    return Object.fromEntries([...counts].sort(([left], [right]) => compareCodeUnits(left, right)));
+}
+function layer(issue) {
+    const path = issue.location?.path;
+    return path === undefined ? 'unknown' : (/^([a-z]+):/u.exec(path)?.[1] ?? 'unknown');
+}
+/** The mod's own files first, then most severe: classification, confidence, source order. */
+function issueOrder(left, right) {
+    const leftMod = layer(left) === 'mod' ? 0 : 1;
+    const rightMod = layer(right) === 'mod' ? 0 : 1;
+    return (leftMod - rightMod ||
+        CLASSIFICATION_ORDER[left.classification] - CLASSIFICATION_ORDER[right.classification] ||
+        CONFIDENCE_ORDER[left.confidence] - CONFIDENCE_ORDER[right.confidence] ||
+        compareCodeUnits(left.location?.path ?? '', right.location?.path ?? '') ||
+        (left.location?.start.line ?? 0) - (right.location?.start.line ?? 0) ||
+        compareCodeUnits(left.code, right.code) ||
+        compareCodeUnits(left.message, right.message));
+}
+/** Counts and the most severe findings of a selection, small enough to return inline. */
+export function summarizeEventIssues(issues) {
+    const byCode = Object.entries(countBy(issues, ({ code }) => code))
+        .sort(([leftCode, left], [rightCode, right]) => right - left || compareCodeUnits(leftCode, rightCode))
+        .slice(0, EVENT_INLINE_CODES);
+    return {
+        issues: issues.length,
+        byClassification: countBy(issues, ({ classification }) => classification),
+        // `mod` findings are the workspace's own; `game` and `dependency` ones are context.
+        byLayer: countBy(issues, layer),
+        topCodes: Object.fromEntries(byCode),
+        findings: [...issues]
+            .sort(issueOrder)
+            .slice(0, EVENT_INLINE_FINDINGS)
+            .map((issue) => ({
+            code: issue.code,
+            classification: issue.classification,
+            confidence: issue.confidence,
+            message: issue.message.length > EVENT_INLINE_MESSAGE_LENGTH
+                ? `${issue.message.slice(0, EVENT_INLINE_MESSAGE_LENGTH - 1)}…`
+                : issue.message,
+            ...(issue.location === undefined
+                ? {}
+                : { path: issue.location.path, line: issue.location.start.line }),
+            ...(typeof issue.details.name === 'string' ? { subject: issue.details.name } : {}),
+        })),
+    };
+}
+/** Size of a traced chain and the events it reaches. */
+export function summarizeEventTrace(trace) {
+    const events = trace.nodes
+        .flatMap(({ kind, eventId }) => (kind === 'event' && eventId !== undefined ? [eventId] : []))
+        .sort(compareCodeUnits);
+    return {
+        nodes: trace.nodes.length,
+        edges: trace.edges.length,
+        events: events.length,
+        eventIds: events.slice(0, EVENT_INLINE_EVENT_IDS),
+        boundaryNodes: trace.boundaryNodeIds.length,
+        truncated: trace.truncated,
+    };
+}
+/** How many chains start where, in a form an agent can read without the report. */
+export function summarizeEventRoots(roots) {
+    const nodeLayer = ({ sourcePath }) => sourcePath === undefined ? 'unknown' : (/^([a-z]+):/u.exec(sourcePath)?.[1] ?? 'unknown');
+    // The mod's own events first: vanilla callerless events are context, not the mod's defects.
+    const ids = (nodes) => [...nodes]
+        .sort((left, right) => (nodeLayer(left) === 'mod' ? 0 : 1) - (nodeLayer(right) === 'mod' ? 0 : 1) ||
+        compareCodeUnits(left.eventId ?? '', right.eventId ?? ''))
+        .flatMap(({ eventId }) => (eventId === undefined ? [] : [eventId]))
+        .slice(0, EVENT_INLINE_EVENT_IDS);
+    return {
+        entryPoints: roots.entryPoints.length,
+        entryKinds: countBy(roots.entryPoints, ({ metadata }) => typeof metadata.entryKind === 'string' ? metadata.entryKind : 'unknown'),
+        automaticEvents: roots.automaticEvents.length,
+        callerlessTriggeredEvents: roots.callerlessTriggeredEvents.length,
+        callerlessTriggeredByLayer: countBy(roots.callerlessTriggeredEvents, nodeLayer),
+        callerlessTriggeredEventIds: ids(roots.callerlessTriggeredEvents),
+        cycles: roots.stronglyConnectedComponents.filter(({ cyclic }) => cyclic).length,
+    };
+}
+/** Whether a route exists and, if so, the events it passes through in order. */
+export function summarizeEventPath(path) {
+    return {
+        found: path.found,
+        steps: path.steps.length,
+        eventIds: path.steps
+            .flatMap(({ node }) => node.kind === 'event' && node.eventId !== undefined ? [node.eventId] : [])
+            .slice(0, EVENT_INLINE_EVENT_IDS),
+        ...(path.failureReason === undefined ? {} : { failureReason: path.failureReason }),
+        ...(path.failureMessage === undefined ? {} : { failureMessage: path.failureMessage }),
+        unresolvedAssumptions: path.unresolvedAssumptions.length,
+    };
+}
+/** How far a change to the subject reaches, by count. */
+export function summarizeEventImpact(impact) {
+    return {
+        direct: impact.directNodeIds.length,
+        upstream: impact.upstreamNodeIds.length,
+        downstream: impact.downstreamNodeIds.length,
+        stateAccesses: impact.stateAccessIds.length,
+        affectedRoots: impact.affectedRootIds.length,
+        affectedTerminals: impact.affectedTerminalIds.length,
+        wouldDisconnect: impact.wouldDisconnectNodeIds.length,
+        wouldDisconnectTerminals: impact.wouldDisconnectTerminalIds.length,
+        unresolved: impact.unresolvedNodeIds.length,
+        sampleDownstream: impact.downstreamNodeIds.slice(0, EVENT_INLINE_EVENT_IDS),
+    };
+}

package/dist/hoi4_agent_tools/impact/service.js

@@ -94,6 +94,8 @@ export class ImpactAnalyzer {
             directConsumers: graph.directConsumers.length,
             transitiveConsumers: graph.transitiveConsumers.length,
             affectedFiles: graph.affectedFiles.length,
+            // Affected files are evidence, not writes: this read-only analysis never changes a file.
+            affectedFilePaths: graph.affectedFiles.slice(0, 64),
             cycles: graph.cycles.length,
             scenarioSuites: scenarioSuites.scannedSuites,
             affectedCases: scenarioSuites.matches.length,
@@ -108,7 +110,6 @@ export class ImpactAnalyzer {
         result.code = complete ? 'IMPACT_ANALYZED' : 'IMPACT_ANALYZED_PARTIAL';
         result.artifacts = [publicArtifactLink(artifact)];
         result.proposedFiles = overlay?.changes.map(({ path }) => path).slice(0, 64) ?? [];
-        result.changedFiles = graph.affectedFiles.slice(0, 64);
         setInlineFilesScanned(result, before.files.map(({ displayPath }) => displayPath));
         result.validation = {
             passed: complete,

package/dist/hoi4_agent_tools/map/derived.js

@@ -136,9 +136,9 @@ function coastPoint(raster, shape, isSea) {
             [0, 1],
             [0, -1],
         ]) {
-            const nx = x + dx;
+            const nx = (x + dx + raster.width) % raster.width;
             const ny = y + dy;
-            if (nx < 0 || ny < 0 || nx >= raster.width || ny >= raster.height)
+            if (ny < 0 || ny >= raster.height)
                 continue;
             const other = raster.provinceIds[ny * raster.width + nx];
             if (other < 0 || !isSea(other))
@@ -154,6 +154,19 @@ function coastPoint(raster, shape, isSea) {
     const middle = points[Math.floor(points.length / 2)];
     return { ...middle, sea };
 }
+/** A sea pixel next to the landing province, staying inside narrow inlets and map edges. */
+function floatingHarborPoint(raster, coast) {
+    for (const distance of [2, 1]) {
+        const x = (coast.x + coast.dx * distance + raster.width) % raster.width;
+        const y = coast.y + coast.dy * distance;
+        if (y < 0 || y >= raster.height)
+            continue;
+        // Keep the same sea association selected from the real coastal contact.
+        if (raster.provinceIds[y * raster.width + x] === coast.sea)
+            return { x, y };
+    }
+    throw new ServiceError('MAP_FLOATING_HARBOR_WATER_UNAVAILABLE', 'The selected coastal contact has no adjacent sea pixel for a floating harbor');
+}
 function rotationFor(dx, dy) {
     // Bitmap y grows downward; map z grows upward.
     return Math.atan2(-dy, dx);
@@ -315,9 +328,8 @@ function planBuildingPositions(index, request) {
                         continue;
                     for (let copy = 0; copy < perOwner && produced < wanted - have; copy += 1, produced += 1) {
                         const floating = slot.name === 'floating_harbor';
-                        // A floating harbour sits on the water two pixels out and names its land province.
-                        const x = floating ? coast.x + coast.dx * 2 : coast.x;
-                        const y = floating ? coast.y + coast.dy * 2 : coast.y;
+                        // Prefer two pixels offshore, with a verified adjacent-water fallback.
+                        const { x, y } = floating ? floatingHarborPoint(raster, coast) : coast;
                         added.push([
                             state.id,
                             slot.name,
@@ -350,7 +362,10 @@ function planBuildingPositions(index, request) {
     }
     return {
         relativePath: document?.file.relativePath ?? `${mapRoot(index)}/buildings.txt`,
-        content: rewriteLines(document, drop, added),
+        // The native building-position reader treats a trailing newline as an empty CSV record.
+        content: Buffer.from(rewriteLines(document, drop, added)
+            .toString('utf8')
+            .replace(/\r?\n$/u, ''), 'utf8'),
     };
 }
 function planUnitPositions(index, request) {

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

@@ -4,7 +4,7 @@ import { errorResult, toolResult } from '../core/operation-result.js';
 import { ServiceError } from '../core/result.js';
 import { MAP_VIEW_FIELDS, mapInspectRequestSchema, mapRewriteRequestSchema, } from '../schemas/map-requests.js';
 import { AgentNudger } from './service.js';
-import { inspectMap, completeMapRewrite, normalizeMapInspectRequest, normalizeMapRenderRequest, normalizeMapRewriteRequest, prepareMapRewrite, renderMapView, } from './tool-operations.js';
+import { inspectMap, completeMapRewrite, normalizeMapInspectRequest, normalizeMapRenderRequest, normalizeMapRewriteRequest, prepareMapRewrite, previewMapRewrite, renderMapView, } from './tool-operations.js';
 const wireResult = z.record(z.string(), z.json());
 /** Registers read-only map operations without invoking transport handlers. */
 export function registerMapJobs(operations, engine) {
@@ -54,12 +54,18 @@ export function registerMapJobs(operations, engine) {
             throw new ServiceError('JOB_ARGUMENT_SCOPE_MISMATCH', 'The request workspace does not match the authorized job workspace');
         const release = lifetime.begin();
         try {
-            return await prepareMapRewrite(nudger, normalizeMapRewriteRequest(input), {
+            const operationContext = {
                 workspaceId: context.workspaceId,
                 ...(context.principal === undefined ? {} : { principal: context.principal }),
                 signal: context.signal,
                 progress: (completed, total, message) => context.progress({ completed, total, message }),
-            });
+            };
+            const normalized = normalizeMapRewriteRequest(input);
+            if (normalized.preview)
+                return {
+                    readOnlyPreview: wireResult.parse(JSON.parse(JSON.stringify(toolResult(await previewMapRewrite(nudger, normalized, operationContext))))),
+                };
+            return await prepareMapRewrite(nudger, normalized, operationContext);
         }
         finally {
             release();

package/dist/hoi4_agent_tools/map/operations.js

@@ -9,6 +9,8 @@ import { derivedStateCapital, encodeTextDocument, LEVEL_STATE_BUILDINGS, MapWork
 import { planReferenceRemap, ReferenceRemapError } from './references.js';
 import { generateWorld } from './world.js';
 import { planMapPositions, planSupplyRebuild } from './derived.js';
+import { buildWorldContext } from './world-context.js';
+import { reconcileWorldOutputs } from './world-outputs.js';
 function* cancellationCheckpoint(signal, iteration = 0, stride = 1) {
     if (iteration % stride !== 0)
         return;
@@ -3250,6 +3252,14 @@ export const WORLD_REPLACED_ROOTS = [
     'map/supplyareas',
     'common/bookmarks',
 ];
+const STARTING_SCENARIO_REPLACED_ROOTS = [
+    'common/on_actions',
+    'common/ai_areas',
+    'common/ai_strategy_plans',
+    'common/ai_strategy',
+    'common/decisions',
+    'events',
+];
 /** 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');
@@ -3262,36 +3272,56 @@ function descriptorWithReplacePaths(index, roots) {
     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) {
+function applyCreateWorld(base, changes, operation, context) {
+    const reference = context.referenceWorlds?.get(operation.id);
+    if (operation.reference !== undefined && reference === undefined)
+        throw new ServiceError('MAP_REFERENCE_NOT_PREPARED', 'Reference worlds must be prepared by the authorized workspace service');
     const mapRoot = base.sourceRoots.map[0] ?? 'map';
+    const startingScenario = operation.startingScenario ?? reference !== undefined;
     const world = generateWorld({
-        width: operation.width ?? 1_024,
-        height: operation.height ?? 512,
+        startingScenario,
+        ...(operation.worldName === undefined ? {} : { worldName: operation.worldName }),
+        width: operation.width ?? reference?.surface.width ?? 1_024,
+        height: operation.height ?? reference?.surface.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,
+        provincesPerState: operation.provincesPerState ?? (reference === undefined ? 5 : 12),
+        landProvincesPerRegion: operation.landProvincesPerRegion ?? (reference === undefined ? 25 : 60),
+        seaProvincesPerRegion: operation.seaProvincesPerRegion ?? (reference === undefined ? 10 : 30),
+        countries: operation.countries ??
+            reference?.countries ?? [
+            { tag: 'X01', name: 'Aster' },
+            { tag: 'X02', name: 'Brum' },
+            { tag: 'X03', name: 'Corvel' },
+            { tag: 'X04', name: 'Doran' },
+        ],
+        ...(reference === undefined
+            ? {}
+            : {
+                referenceSurface: reference.surface,
+                referenceCities: reference.cities,
+                referenceLabels: reference.labels,
+            }),
         ...(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];
+        rivers: operation.rivers ?? (reference === undefined ? 8 : 80),
+    }, buildWorldContext(base));
+    const roots = operation.replaceBaseGame === false
+        ? []
+        : [...WORLD_REPLACED_ROOTS, ...(startingScenario ? STARTING_SCENARIO_REPLACED_ROOTS : [])];
     replacedRootsByPlan.set(changes, roots);
     for (const file of world.files)
         addChange(changes, file.relativePath, file.content, operation.id, file.mediaType);
+    // Remove only unchanged outputs recorded by a previous generation, before indexing new IDs.
+    for (const file of reconcileWorldOutputs(base.sourceFiles, proposedChanges(changes), operation.id, mapRoot, base.sourceRoots.states, base.sourceRoots.localisation))
+        if (file.content === null)
+            addChange(changes, file.relativePath, null, operation.id, 'text/plain');
     // Start from empty derived files so no base-game position or supply line survives.
     for (const name of [
         'buildings.txt',
@@ -3309,7 +3339,28 @@ function applyCreateWorld(base, changes, operation) {
     const positioned = currentIndex(base, changes);
     for (const file of planSupplyRebuild(positioned, { mode: 'replace' }))
         addChange(changes, file.relativePath, file.content, operation.id, 'text/plain');
+    for (const file of reconcileWorldOutputs(base.sourceFiles, proposedChanges(changes), operation.id, mapRoot, base.sourceRoots.states, base.sourceRoots.localisation))
+        addChange(changes, file.relativePath, file.content, operation.id, file.mediaType ?? 'text/plain');
     return [
+        ...(reference?.diagnostics ?? []).map((message) => ({
+            code: 'MAP_REFERENCE_INTERPRETATION',
+            severity: 'warning',
+            category: 'map',
+            operationId: operation.id,
+            message,
+        })),
+        ...(world.warnings.length === 0
+            ? []
+            : [
+                {
+                    code: 'MAP_WORLD_GENERATION_REVIEW',
+                    severity: 'warning',
+                    category: 'map',
+                    operationId: operation.id,
+                    message: `Drainage generation reported ${world.warnings.length} review notes`,
+                    details: { warningCount: world.warnings.length, samples: world.warnings.slice(0, 5) },
+                },
+            ]),
         {
             code: 'MAP_WORLD_CREATED',
             severity: 'info',
@@ -3405,7 +3456,7 @@ function applyEntityLocator(base, changes, operation) {
     ]);
     addChange(changes, locator.file.relativePath, output, operation.id, 'text/plain');
 }
-function* planMapOperationSteps(base, operations, signal) {
+function* planMapOperationSteps(base, operations, signal, context = {}) {
     yield* cancellationCheckpoint(signal);
     const changes = new Map();
     const diagnostics = [];
@@ -3443,7 +3494,7 @@ function* planMapOperationSteps(base, operations, signal) {
         const boundsCheckpoint = expectedChangedBounds;
         try {
             if (operation.kind === 'create_world')
-                diagnostics.push(...applyCreateWorld(base, changes, operation));
+                diagnostics.push(...applyCreateWorld(base, changes, operation, context));
             else if (operation.kind === 'move_state_provinces')
                 applyMoveStateProvinces(base, changes, operation);
             else if (operation.kind === 'update_state')
@@ -3522,12 +3573,12 @@ function* planMapOperationSteps(base, operations, signal) {
         operations: manifestOperations,
     };
 }
-export function planMapOperations(base, operations, signal) {
-    return completeSynchronously(planMapOperationSteps(base, operations, signal));
+export function planMapOperations(base, operations, signal, context = {}) {
+    return completeSynchronously(planMapOperationSteps(base, operations, signal, context));
 }
 /** Plans map mutations while periodically yielding so protocol cancellation can be delivered. */
-export async function planMapOperationsAsync(base, operations, signal) {
-    return completeCooperatively(planMapOperationSteps(base, operations, signal), signal);
+export async function planMapOperationsAsync(base, operations, signal, context = {}) {
+    return completeCooperatively(planMapOperationSteps(base, operations, signal, context), signal);
 }
 export function mapOperationId(operation) {
     return deterministicId('map_operation', operation);