hoi4-agent-tools 3.2.0 → 3.4.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 3.4.0 - 2026-09-20
+
+- Add branch-local focus cleanup with pinned anchors and symmetry groups, connector measurements, source-linked crops, and scenario-backed structural route diagnostics.
+- Report GUI visibility and enabled branches, measured label and background boxes, and matched source-baseline renders alongside scenario comparisons.
+- Expose complete source-backed probability catalogs, actionable missing scenario inputs, and eligible, excluded, and unresolved inventories.
+- Add selected event-chain comparisons and revision-bound bounded helper expansion while retaining explicit lifecycle coverage limits.
+- Compose technology folders from source pixel placements, native item skins, icon and subtechnology positions, panel and background artwork, year labels, and supplied research scenarios; report unresolved placement and asset coverage honestly.
+- Resolve source `GFX_*_medium` artwork and design-team overlays at native item size for chemical and biological warfare folders.
+- Compose installed GUI backgrounds, focus inlays, container scrolling, native button and progress shaders, and scenario-driven rows from source assets and control states.
+- Bound focus connector and overlap diagnostics on anchored trees with thousands of nodes.
+- Add focused map lookups, reusable render tiles, affected-area output, and typed external script-reference updates for map renumbering.
+
+## 3.3.0 - 2026-09-20
+
+- Add `hoi4.mechanic_test` with copied versioned scenario state, bounded source effects, explicit time advancement, traces, and typed gameplay assertions.
+- Add `hoi4.package_check` for declarative package definitions, calls, registrations, localisation, assets, and required suite-case references.
+- Add `hoi4.scenario_test` for named inline or workspace-owned suites through fixed read-only operations, case artifacts, and authenticated revision-bound continuation.
+- Share declared condition state across GUI and probability adapters while preserving their public inputs and specialized evaluation semantics.
+
 ## 3.2.0 - 2026-09-20
 
 - Add read-only `hoi4.impact_inspect` with active and overridden definitions, direct and transitive source consumers, state-key access roles, cycle and coverage evidence, and in-memory source comparisons.

package/README.md

@@ -74,6 +74,9 @@ On non-Windows systems, use `hoi4-agent-tools` as the command. Agentic HOI4 repo
 | `hoi4.event_compare`        | Compare event-chain topology and diagnostics between revisions.                           |
 | `hoi4.impact_inspect`       | Trace symbol and changed-file consumers across source systems and compare proposals.      |
 | `hoi4.decision_inspect`     | Inventory and evaluate decisions or missions under declared scenarios and source changes. |
+| `hoi4.mechanic_test`        | Execute bounded source effects on a copied declared scenario and check assertions.        |
+| `hoi4.package_check`        | Check declarative package definitions, calls, registrations, assets, and case links.      |
+| `hoi4.scenario_test`        | Run named source and domain cases in resumable, revision-bound batches.                   |
 | `hoi4.job_inspect`          | Inspect durable background work or retrieve its completed tool result.                    |
 | `hoi4.job_cancel`           | Durably request cancellation of authorized background work.                               |
 | `hoi4.tech_inspect`         | Scan, trace, explain, lint, and assess technology and doctrine systems.                   |
@@ -108,6 +111,7 @@ Ask your agent in normal task language. A typical workflow is inspect, render, r
 - Maps: "Render the whole map and find this state by name," "Create a state from these provinces," "Create a province inside this exact rectangle," or "Swap these state IDs and update connected references." See [Maps](docs/map.md).
 - Event chains: "Trace every route from this event and explain where its flags and variables change," or "Compare the workspace event graph with its previous revision and render the affected routes." See [Event chains](docs/events.md).
 - Cross-system impact and decisions: "Find every direct and transitive consumer of this idea," or "Compare who can take this decision, what they pay, and its mission end paths for these actor and target scenarios." See [Cross-system impact and decisions](docs/analysis.md).
+- Mechanics and packages: "Test this transfer's conservation and payment," or "Check every declared package link and resume its named scenario suite." See [Mechanic tests and scenario suites](docs/mechanics.md).
 - Technology trees: "Explain everything this technology requires and unlocks," or "Compare this technology patch and render every affected folder and doctrine branch." See [Technology trees](docs/technology.md).
 - AI and MTTH: "Compare these focus weights across peace, defensive-war, and low-stability scenarios," or "Show when this MTTH event becomes likely and which unknown inputs control the result." See [AI and MTTH analysis](docs/probability.md).
 

package/dist/hoi4_agent_tools/core/analysis-job-operations.js

@@ -1,14 +1,21 @@
 import { z } from 'zod/v4';
 import { DecisionAnalyzer } from '../decision/service.js';
 import { ImpactAnalyzer } from '../impact/service.js';
+import { MechanicAnalyzer } from '../mechanic/service.js';
+import { PackageAnalyzer } from '../package-check/service.js';
+import { ScenarioAnalyzer } from '../scenario-suite/service.js';
 import { decisionInspectRequestSchema, impactInspectRequestSchema } from '../schemas/analysis.js';
+import { mechanicTestRequestSchema, packageCheckRequestSchema, scenarioTestRequestSchema, } from '../schemas/scenarios.js';
 import { errorResult, toolResult } from './operation-result.js';
 import { ServiceError } from './result.js';
 const wireResult = z.record(z.string(), z.json());
-/** Registers the two read-only analysis services for durable ordinary and native tasks. */
+/** Registers read-only analysis services for durable ordinary and native tasks. */
 export function registerAnalysisJobs(operations, engine) {
     const impact = new ImpactAnalyzer(engine);
     const decision = new DecisionAnalyzer(engine);
+    const mechanic = new MechanicAnalyzer(engine);
+    const packages = new PackageAnalyzer(engine);
+    const scenarios = new ScenarioAnalyzer(engine);
     const register = (name, schema, execute, progressMessage) => {
         operations.registerRead(name, schema, async (input, context) => {
             try {
@@ -35,4 +42,7 @@ export function registerAnalysisJobs(operations, engine) {
     };
     register('hoi4.impact_inspect', impactInspectRequestSchema, (input) => impact.inspect(input), 'Tracing cross-system impact');
     register('hoi4.decision_inspect', decisionInspectRequestSchema, (input) => decision.inspect(input), 'Analyzing decisions and missions');
+    register('hoi4.mechanic_test', mechanicTestRequestSchema, (input) => mechanic.test(input), 'Testing declared mechanic steps');
+    register('hoi4.package_check', packageCheckRequestSchema, (input) => packages.check(input), 'Checking package connections');
+    register('hoi4.scenario_test', scenarioTestRequestSchema, (input) => scenarios.test(input), 'Running a bounded scenario suite');
 }

package/dist/hoi4_agent_tools/core/condition-evaluator.js

@@ -96,7 +96,7 @@ function numberValue(expression, scenario, context, definitions, path, seen = ne
     }
     return undefined;
 }
-function unresolved(assignment, candidate, reason) {
+function unresolved(assignment, candidate, reason, scenarioInput) {
     return {
         state: 'unresolved',
         unresolved: [
@@ -104,6 +104,7 @@ function unresolved(assignment, candidate, reason) {
                 code: 'TRIGGER_UNRESOLVED',
                 message: reason,
                 path: assignment.key.value,
+                ...(scenarioInput === undefined ? {} : { details: { scenarioInput } }),
                 candidateId: candidate.id,
                 ...(candidate.provenance[0] === undefined ? {} : { provenance: candidate.provenance[0] }),
             },
@@ -136,7 +137,11 @@ function evaluateCheckVariable(block, scenario, candidate, assignment, scopeCont
     const leftNumber = numberValue(variable, scenario, scopeContext, definitions, path);
     const rightNumber = numberValue(target, scenario, scopeContext, definitions, path);
     if (leftNumber === undefined || rightNumber === undefined)
-        return unresolved(assignment, candidate, `Scenario does not resolve numeric operands ${variable} and ${target}`);
+        return unresolved(assignment, candidate, `Scenario does not resolve numeric operands ${variable} and ${target}`, leftNumber === undefined && !/^(?:@|constant:)/u.test(variable)
+            ? `variable.${variable}`
+            : rightNumber === undefined && !/^(?:@|constant:)/u.test(target)
+                ? `variable.${target}`
+                : undefined);
     const compareName = firstScalar(block, 'compare')?.value ??
         (short?.operator.text === '>'
             ? 'greater_than'
@@ -202,7 +207,7 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
             const array = scopeStateValue(scenario, `array.${arrayId}`, scopeContext) ??
                 rootStateValue(scenario, `array.${arrayId}`);
             if (!Array.isArray(array))
-                return unresolved(assignment, candidate, `Scenario does not declare array ${arrayId}`);
+                return unresolved(assignment, candidate, `Scenario does not declare array ${arrayId}`, `array.${arrayId}`);
             const compared = ['THIS', 'ROOT', 'PREV'].includes(declaredValue.toUpperCase()) ||
                 resolveScopeContext(scenario, declaredValue, scopeContext) !== undefined
                 ? scopeIdentity(resolveScopeContext(scenario, declaredValue, scopeContext) ?? scopeContext)
@@ -244,7 +249,7 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
         const declaredScope = bool(rootStateValue(scenario, `scope.${key}`));
         if (declaredScope !== undefined)
             return { state: declaredScope ? 'true' : 'false', unresolved: [] };
-        return unresolved(assignment, candidate, `Scoped or compound trigger ${key} is not declared by the scenario`);
+        return unresolved(assignment, candidate, `Scoped or compound trigger ${key} is not declared by the scenario`, `scope.${key}`);
     }
     const right = assignment.value.value;
     if (key === 'always') {
@@ -257,9 +262,13 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
         const explicit = bool(scopeStateValue(scenario, `flag.${right}`, scopeContext));
         if (explicit !== undefined)
             return { state: explicit ? 'true' : 'false', unresolved: [] };
-        const flags = scopeContext.expression === 'ROOT' ? scenario.flags : scopeContext.binding.flags;
+        const flags = key === 'has_global_flag' && scenario.globalFlags !== undefined
+            ? scenario.globalFlags
+            : scopeContext.expression === 'ROOT'
+                ? scenario.flags
+                : scopeContext.binding.flags;
         if (scenario.closedFlags === false && flags?.includes(right) !== true)
-            return unresolved(assignment, candidate, `Scenario does not declare flag ${right}`);
+            return unresolved(assignment, candidate, `Scenario does not declare flag ${right}`, `flag.${right}`);
         return { state: flags?.includes(right) === true ? 'true' : 'false', unresolved: [] };
     }
     if (key === 'has_event_target') {
@@ -274,7 +283,7 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
             ? scenario.actor
             : (scopeContext.binding.actor ?? scopeContext.binding.id);
         if (actor === undefined)
-            return unresolved(assignment, candidate, `Scenario does not declare actor for ${key}`);
+            return unresolved(assignment, candidate, `Scenario does not declare actor for ${key}`, 'actor');
         return {
             state: compare(actor, right, assignment.operator.text) ? 'true' : 'false',
             unresolved: [],
@@ -282,7 +291,7 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
     }
     if (key === 'date') {
         if (scenario.date === undefined)
-            return unresolved(assignment, candidate, 'Scenario does not declare date');
+            return unresolved(assignment, candidate, 'Scenario does not declare date', 'date');
         const dateNumber = (value) => {
             const parts = /^(\d+)\.(\d{1,2})\.(\d{1,2})$/u.exec(value);
             if (parts === null)
@@ -332,7 +341,7 @@ function evaluateAssignmentCore(assignment, scenario, candidate, definitions, he
     const declared = scopeStateValue(scenario, key, scopeContext) ??
         numberValue(key, scenario, scopeContext, definitions, candidate.provenance[0]?.path);
     if (declared === undefined)
-        return unresolved(assignment, candidate, `Scenario does not declare trigger ${key}`);
+        return unresolved(assignment, candidate, `Scenario does not declare trigger ${key}`, key);
     const expectedBoolean = bool(right);
     const actualBoolean = bool(declared);
     if (expectedBoolean !== undefined && actualBoolean !== undefined)

package/dist/hoi4_agent_tools/core/helper-expansion.js

@@ -104,6 +104,9 @@ export async function inspectHelperExpansion(engine, workspaceId, inventory, req
         kind,
         rootId: input.roots[root],
         path: path.map((index) => inventory.edges[index].id),
+        ...(inventory.recordDetails === undefined
+            ? {}
+            : inventory.recordDetails(path.map((index) => inventory.edges[index]))),
     }));
     const continuationName = `${inventory.domain}-helper-continuation.json`;
     const report = {

package/dist/hoi4_agent_tools/core/job-worker-host.js

@@ -39,6 +39,9 @@ export class JobWorkerHost {
         if (![
             'hoi4.impact_inspect',
             'hoi4.decision_inspect',
+            'hoi4.mechanic_test',
+            'hoi4.package_check',
+            'hoi4.scenario_test',
             'hoi4.event_inspect',
             'hoi4.event_render',
             'hoi4.event_compare',

package/dist/hoi4_agent_tools/core/operation-tasks.js

@@ -1,5 +1,6 @@
 import { z } from 'zod/v4';
 import { decisionInspectRequestSchema, impactInspectRequestSchema } from '../schemas/analysis.js';
+import { mechanicTestRequestSchema, packageCheckRequestSchema, scenarioTestRequestSchema, } from '../schemas/scenarios.js';
 import { eventCompareRequestSchema, eventInspectRequestSchema, eventRenderRequestSchema, } from '../schemas/event.js';
 import { focusInspectRequestSchema, focusRenderRequestSchema, focusRewriteRequestSchema, } from '../schemas/focus-requests.js';
 import { guiInspectRequestSchema, guiRenderRequestSchema, guiRewriteRequestSchema, } from '../schemas/gui-requests.js';
@@ -28,6 +29,9 @@ export const operationTaskCallSchema = z
     name: z.enum([
         'hoi4.impact_inspect',
         'hoi4.decision_inspect',
+        'hoi4.mechanic_test',
+        'hoi4.package_check',
+        'hoi4.scenario_test',
         'hoi4.event_inspect',
         'hoi4.event_render',
         'hoi4.event_compare',
@@ -58,6 +62,9 @@ export const operationTaskCallSchema = z
 const taskArgumentSchemas = {
     'hoi4.impact_inspect': impactInspectRequestSchema,
     'hoi4.decision_inspect': decisionInspectRequestSchema,
+    'hoi4.mechanic_test': mechanicTestRequestSchema,
+    'hoi4.package_check': packageCheckRequestSchema,
+    'hoi4.scenario_test': scenarioTestRequestSchema,
     'hoi4.event_inspect': eventInspectRequestSchema,
     'hoi4.event_render': eventRenderRequestSchema,
     'hoi4.event_compare': eventCompareRequestSchema,

package/dist/hoi4_agent_tools/core/scenario-model.js

@@ -0,0 +1,85 @@
+export function copyScenario(scenario) {
+    return {
+        scenario: structuredClone(scenario),
+        unknown: new Set(),
+        day: 0,
+    };
+}
+export function scenarioValue(state, key, scope = 'ROOT') {
+    if (state.unknown.has('*') || state.unknown.has(`${scope}.${key}`))
+        return undefined;
+    if (scope === 'ROOT' || scope === 'THIS')
+        return state.scenario.state[key];
+    return state.scenario.scopes?.[scope]?.state[key];
+}
+export function setScenarioValue(state, key, value, scope = 'ROOT') {
+    const identity = `${scope}.${key}`;
+    if (value === undefined)
+        state.unknown.add(identity);
+    else {
+        state.unknown.delete(identity);
+        if (scope === 'ROOT' || scope === 'THIS')
+            state.scenario.state[key] = value;
+        else if (state.scenario.scopes?.[scope] !== undefined)
+            state.scenario.scopes[scope].state[key] = value;
+    }
+}
+/** Preserve the GUI's existing input precedence and exploratory flag semantics. */
+export function scenarioFromGui(base, values = base.values) {
+    const state = {
+        ...base.stateValues,
+        ...base.variables,
+        ...values,
+    };
+    for (const [key, value] of Object.entries(base.flags))
+        state[`flag.${key}`] = value;
+    const scopes = structuredClone(base.scopes ?? {});
+    for (const [key, value] of Object.entries(state)) {
+        const match = /^(ROOT|THIS|FROM(?:\.FROM)*|PREV)\.(.+)$/u.exec(key);
+        if (match === null)
+            continue;
+        if (match[1] === 'ROOT' || match[1] === 'THIS')
+            state[match[2]] ??= value;
+        else {
+            const scope = (scopes[match[1]] ??= { id: match[1], state: {} });
+            scope.state[match[2]] ??= value;
+        }
+    }
+    const actor = base.country?.tag ?? base.country?.countryTag ?? base.country?.GetTag;
+    return {
+        schemaVersion: '1.0',
+        id: base.id,
+        state,
+        scopes,
+        closedFlags: false,
+        ...(typeof actor === 'string' ? { actor } : {}),
+    };
+}
+/** Probability retains pools, uncertainty, correlations and schedule in its own adapter. */
+export function scenarioFromProbability(base) {
+    return {
+        schemaVersion: '1.0',
+        id: base.id,
+        ...(base.actor === undefined ? {} : { actor: base.actor }),
+        ...(base.date === undefined ? {} : { date: base.date }),
+        state: structuredClone(base.state),
+        ...(base.flags === undefined ? {} : { flags: [...base.flags] }),
+        ...(base.eventTargets === undefined ? {} : { eventTargets: { ...base.eventTargets } }),
+        ...(base.scopes === undefined ? {} : { scopes: structuredClone(base.scopes) }),
+        ...(base.candidateOverrides === undefined
+            ? {}
+            : { candidateOverrides: { ...base.candidateOverrides } }),
+        closedFlags: true,
+        ...(base.scopePools === undefined
+            ? {}
+            : {
+                scopeCatalogs: Object.fromEntries(base.scopePools.map((pool) => [
+                    pool.id,
+                    {
+                        complete: pool.complete,
+                        members: pool.candidates.map((candidate) => candidate.id),
+                    },
+                ])),
+            }),
+    };
+}

package/dist/hoi4_agent_tools/event/comparison-selection.js

@@ -0,0 +1,78 @@
+import { compareCodeUnits } from '../core/canonical.js';
+import { traceEventGraph } from './algorithms.js';
+import { selectEventNodes } from './queries.js';
+/** Project a whole-graph comparison onto the downstream chain in each revision. */
+export function selectEventComparison(before, after, comparison, selector, maxChainNodes, signal) {
+    const trace = (graph) => {
+        const starts = selectEventNodes(graph, selector, signal).map(({ id }) => id);
+        return traceEventGraph(graph, starts, {
+            maxDepth: 64,
+            maxNodes: maxChainNodes,
+            maxEdges: Math.max(1, Math.min(20_000, graph.edges.length)),
+            direction: 'downstream',
+            expandHelpers: true,
+        }, signal);
+    };
+    const beforeTrace = trace(before);
+    const afterTrace = trace(after);
+    const beforeNodeIds = beforeTrace.nodes.map(({ id }) => id).sort(compareCodeUnits);
+    const afterNodeIds = afterTrace.nodes.map(({ id }) => id).sort(compareCodeUnits);
+    const selectedNodes = new Set([...beforeNodeIds, ...afterNodeIds]);
+    const edges = new Map([...before.edges, ...after.edges].map((edge) => [edge.id, edge]));
+    const accesses = new Map([...before.stateAccesses, ...after.stateAccesses].map((access) => [access.id, access]));
+    const links = new Map([...before.stateLinks, ...after.stateLinks].map((link) => [link.id, link]));
+    const unresolved = new Map([...before.unresolved, ...after.unresolved].map((item) => [item.id, item]));
+    const association = (change) => {
+        const { kind, subjectId } = change;
+        if (kind.startsWith('node_') || kind === 'caller_removed' || kind.endsWith('_disconnected'))
+            return selectedNodes.has(subjectId);
+        if (kind.startsWith('edge_')) {
+            const edge = edges.get(subjectId);
+            return edge === undefined
+                ? undefined
+                : selectedNodes.has(edge.from) || selectedNodes.has(edge.to);
+        }
+        if (kind.startsWith('state_access_')) {
+            const access = accesses.get(subjectId);
+            return access === undefined ? undefined : selectedNodes.has(access.ownerId);
+        }
+        if (kind.startsWith('state_link_')) {
+            const link = links.get(subjectId);
+            if (link === undefined)
+                return undefined;
+            const producer = accesses.get(link.producerId);
+            const consumer = accesses.get(link.consumerId);
+            return producer === undefined && consumer === undefined
+                ? undefined
+                : (producer !== undefined && selectedNodes.has(producer.ownerId)) ||
+                    (consumer !== undefined && selectedNodes.has(consumer.ownerId));
+        }
+        if (kind.startsWith('unresolved_')) {
+            const item = unresolved.get(subjectId);
+            return item?.ownerId === undefined ? undefined : selectedNodes.has(item.ownerId);
+        }
+        return undefined;
+    };
+    const selectedChangeIds = [];
+    const unattributedChangeIds = [];
+    for (const [index, change] of comparison.changes.entries()) {
+        if ((index & 255) === 0)
+            signal?.throwIfAborted();
+        const relevant = association(change);
+        if (relevant === true)
+            selectedChangeIds.push(change.id);
+        else if (relevant === undefined)
+            unattributedChangeIds.push(change.id);
+    }
+    return {
+        selector,
+        maxChainNodes,
+        beforeNodeIds,
+        afterNodeIds,
+        selectedChangeIds,
+        selectedChangeCount: selectedChangeIds.length,
+        omittedChangeCount: comparison.changes.length - selectedChangeIds.length,
+        unattributedChangeIds,
+        truncated: beforeTrace.truncated || afterTrace.truncated,
+    };
+}

package/dist/hoi4_agent_tools/event/helper-expansion.js

@@ -2,6 +2,14 @@ import { compareCodeUnits } from '../core/canonical.js';
 export function eventHelperInventory(graph) {
     const helpers = new Set(graph.nodes.filter(({ kind }) => kind === 'helper').map(({ id }) => id));
     const structural = graph.edges.filter(({ derived }) => !derived);
+    const structuralById = new Map(structural.map((edge) => [edge.id, edge]));
+    const nodesById = new Map(graph.nodes.map((node) => [node.id, node]));
+    const optionParents = new Map(graph.edges
+        .filter(({ reason }) => reason === 'option_branch')
+        .map(({ from, to }) => [to, from]));
+    const accessById = new Map(graph.stateAccesses
+        .filter(({ ownerId }) => helpers.has(ownerId))
+        .map((access) => [`state-access:${access.id}`, access]));
     return {
         domain: 'event',
         sourceRevision: graph.revision,
@@ -29,5 +37,45 @@ export function eventHelperInventory(graph) {
             .map(({ id }) => id)
             .sort(compareCodeUnits),
         branches: [...helpers].sort(compareCodeUnits),
+        recordDetails: (path) => {
+            let current = 'unknown';
+            const root = structuralById.get(path[0]?.id ?? '');
+            if (root !== undefined) {
+                const caller = nodesById.get(optionParents.get(root.from) ?? root.from);
+                const candidate = root.scope?.source ?? caller?.metadata.expectedScope ?? caller?.metadata.scope;
+                if (candidate === 'country' ||
+                    candidate === 'state' ||
+                    candidate === 'province' ||
+                    candidate === 'unit_leader' ||
+                    candidate === 'operative' ||
+                    candidate === 'character' ||
+                    candidate === 'global')
+                    current = candidate;
+            }
+            const transitions = [];
+            for (const { id } of path) {
+                const edge = structuralById.get(id);
+                if (edge?.scope !== undefined) {
+                    const { source, destination, confidence } = edge.scope;
+                    current =
+                        current !== 'unknown' && source !== 'unknown' && current !== source
+                            ? 'unknown'
+                            : destination;
+                    transitions.push({ edgeId: id, source, destination: current, confidence });
+                }
+                const access = accessById.get(id);
+                if (access !== undefined) {
+                    return {
+                        scopeEvidence: {
+                            stateAccessId: access.id,
+                            declaredScope: access.scope,
+                            resolvedScope: access.scope === 'unknown' ? current : access.scope,
+                            transitions,
+                        },
+                    };
+                }
+            }
+            return { scopeEvidence: { resolvedScope: current, transitions } };
+        },
     };
 }

package/dist/hoi4_agent_tools/event/operations.js

@@ -130,6 +130,15 @@ export async function compareEvents(viewer, input) {
         ...(compared.render === undefined ? {} : { renderHashes: compared.render.hashes }),
         counts: {
             changes: comparison.changes.length,
+            ...(compared.selection === undefined
+                ? {}
+                : {
+                    selectedChanges: compared.selection.selectedChangeCount,
+                    omittedChanges: compared.selection.omittedChangeCount,
+                    unattributedChanges: compared.selection.unattributedChangeIds.length,
+                    selectedBeforeNodes: compared.selection.beforeNodeIds.length,
+                    selectedAfterNodes: compared.selection.afterNodeIds.length,
+                }),
             addedNodes: comparison.addedNodeIds.length,
             removedNodes: comparison.removedNodeIds.length,
             changedNodes: comparison.changedNodeIds.length,
@@ -155,6 +164,13 @@ export async function compareEvents(viewer, input) {
         },
         boundary: {
             proposedSources: input.proposedSources?.length ?? 0,
+            ...(compared.selection === undefined
+                ? {}
+                : {
+                    selector: compared.selection.selector,
+                    maxChainNodes: compared.selection.maxChainNodes,
+                    selectionTruncated: compared.selection.truncated,
+                }),
             render: input.render ?? true,
             maxRenderNodes: input.maxRenderNodes ?? 120,
             refresh: compared.refresh,

package/dist/hoi4_agent_tools/event/service.js

@@ -13,6 +13,7 @@ import { buildEventGraph, buildEventGraphAsync } from './graph.js';
 import { EVENT_FRAGMENT_CACHE_MAX_ENTRIES, EVENT_FRAGMENT_CACHE_MAX_SOURCE_BYTES, EVENT_PROPOSED_SOURCE_MAX_BYTES, EVENT_PROPOSED_SOURCE_MAX_FILES, } from './limits.js';
 import { analyzeEventImpact, discoverEventRoots, explainEventPath, inspectEventStateFlow, lintEventGraph, traceSelectedEvents, } from './queries.js';
 import { compareEventGraphs, eventGraphHash } from './compare.js';
+import { selectEventComparison } from './comparison-selection.js';
 import { eventFlowEdges } from './algorithms.js';
 import { validateEventGraphArtifact } from './artifact-validation.js';
 import { renderEventGraph, } from './render.js';
@@ -1331,16 +1332,29 @@ export class EventChainViewer {
             after = current;
         }
         const comparison = compareEventGraphs(before, after, input.signal);
+        const selection = input.selector === undefined
+            ? undefined
+            : selectEventComparison(before, after, comparison, input.selector, input.maxChainNodes ?? 1_000, input.signal);
+        if (selection?.beforeNodeIds.length === 0 && selection.afterNodeIds.length === 0)
+            throw new ServiceError('EVENT_COMPARISON_SELECTOR_NOT_FOUND', 'The selector matched no event-chain nodes in either revision');
         graphHashCache.set(before, comparison.beforeGraphHash);
         graphHashCache.set(after, comparison.afterGraphHash);
         let render;
         if (input.render !== false) {
             const projection = comparisonRenderProjection(before, after, comparison, input.signal);
+            const selectedChainIds = selection === undefined
+                ? undefined
+                : new Set([...selection.beforeNodeIds, ...selection.afterNodeIds]);
+            const changedNodeIds = selectedChainIds === undefined
+                ? projection.selectedNodeIds
+                : projection.selectedNodeIds.filter((id) => selectedChainIds.has(id));
             const selector = {
                 kind: 'manifest',
                 manifest: {
                     id: 'comparison',
-                    nodeIds: projection.selectedNodeIds,
+                    nodeIds: changedNodeIds.length > 0
+                        ? changedNodeIds
+                        : (selection?.afterNodeIds.slice(0, 1) ?? selection?.beforeNodeIds.slice(0, 1) ?? []),
                 },
             };
             render = await renderEventGraph(projection.graph, {
@@ -1354,7 +1368,7 @@ export class EventChainViewer {
             });
         }
         const workspace = this.engine.resolver.get(input.workspaceId, input.principal);
-        const prefix = safeSlug(`event-compare-${before.revision.slice(0, 8)}-${after.revision.slice(0, 8)}`);
+        const prefix = safeSlug(`event-compare-${before.revision.slice(0, 8)}-${after.revision.slice(0, 8)}${selection === undefined ? '' : `-${hashCanonical({ selector: selection.selector, maxChainNodes: selection.maxChainNodes }).slice(0, 8)}`}`);
         const resourceNames = {
             json: `${prefix}.json`,
             ...(render === undefined
@@ -1380,6 +1394,9 @@ export class EventChainViewer {
             filters: {
                 ...(input.before === undefined ? {} : { before: input.before }),
                 ...(input.after === undefined ? {} : { after: input.after }),
+                ...(input.selector === undefined
+                    ? {}
+                    : { selector: input.selector, maxChainNodes: input.maxChainNodes ?? 1_000 }),
                 proposedSources: input.proposedSources?.map(({ relativePath, source, expectedSourceHash }) => ({
                     relativePath,
                     operation: source === null ? 'delete' : 'overlay',
@@ -1397,6 +1414,7 @@ export class EventChainViewer {
             evidence: comparisonEntityEvidence(before, after, comparison, input.signal),
             resources: resourceNames,
             comparison,
+            ...(selection === undefined ? {} : { selection }),
         })}\n`;
         const provenance = eventProvenance(after, 'event-comparison', {
             beforeRevision: before.revision,
@@ -1447,6 +1465,7 @@ export class EventChainViewer {
             after,
             refresh,
             comparison,
+            ...(selection === undefined ? {} : { selection }),
             comparisonJson,
             ...(render === undefined ? {} : { render }),
             artifacts,