hoi4-agent-tools 3.0.9 → 3.2.0

package/dist/hoi4_agent_tools/focus/tool-support.js

@@ -0,0 +1,123 @@
+import { compareCodeUnits } from '../core/canonical.js';
+import { ServiceError } from '../core/result.js';
+import { parseClausewitz } from '../core/source/index.js';
+import { enrichFocusPlanFromSidecar, focusPlanningSidecarPath, importContinuousFocusPalettes, importFocusTrees, linkContinuousFocusPalettes, parseFocusPlanningSidecar, } from './index.js';
+function normalizedRoot(value) {
+    return value.replaceAll('\\', '/').replace(/^\.\//u, '').replace(/\/+$/u, '').toLowerCase();
+}
+export function underConfiguredRoot(relativePath, roots) {
+    const candidate = relativePath.replaceAll('\\', '/').toLowerCase();
+    return roots.some((root) => {
+        const normalized = normalizedRoot(root);
+        return candidate === normalized || candidate.startsWith(`${normalized}/`);
+    });
+}
+export function activeFocusFiles(snapshot, focusRoots) {
+    return snapshot.files.filter(({ relativePath, shadowedBy }) => shadowedBy === undefined &&
+        underConfiguredRoot(relativePath, focusRoots) &&
+        relativePath.toLowerCase().endsWith('.txt'));
+}
+export function activeContinuousFocusFiles(snapshot) {
+    return snapshot.files.filter(({ relativePath, shadowedBy }) => shadowedBy === undefined &&
+        relativePath.replaceAll('\\', '/').toLowerCase().startsWith('common/continuous_focus/') &&
+        relativePath.toLowerCase().endsWith('.txt'));
+}
+export function continuousPalettes(snapshot) {
+    const palettes = [];
+    const diagnostics = [];
+    for (const file of activeContinuousFocusFiles(snapshot)) {
+        const document = parseClausewitz(file.bytes, file.displayPath);
+        const imported = importContinuousFocusPalettes(document);
+        palettes.push(...imported.continuousFocusPalettes);
+        diagnostics.push(...imported.diagnostics);
+    }
+    return { palettes, diagnostics };
+}
+export function activeSidecar(snapshot, focusFile) {
+    const relativePath = focusPlanningSidecarPath(focusFile.relativePath).toLowerCase();
+    const file = snapshot.files.find((candidate) => candidate.shadowedBy === undefined && candidate.relativePath.toLowerCase() === relativePath);
+    return file === undefined ? undefined : { file, sidecar: parseFocusPlanningSidecar(file.bytes) };
+}
+export function importFocusFile(snapshot, file, palettes) {
+    const document = parseClausewitz(file.bytes, file.displayPath);
+    const imported = importFocusTrees(document, { references: referenceCatalog(snapshot) });
+    const sidecar = activeSidecar(snapshot, file);
+    imported.plans = imported.plans.map((plan) => {
+        const enriched = sidecar === undefined
+            ? { plan, diagnostics: [] }
+            : enrichFocusPlanFromSidecar(plan, sidecar.sidecar);
+        imported.diagnostics.push(...enriched.diagnostics);
+        return linkContinuousFocusPalettes(enriched.plan, palettes);
+    });
+    return imported;
+}
+export function selectedFocusFile(snapshot, focusRoots, relativePath) {
+    const file = activeFocusFiles(snapshot, focusRoots).find((candidate) => candidate.relativePath === relativePath);
+    if (file === undefined)
+        throw new ServiceError('FOCUS_SOURCE_NOT_FOUND', `Focus source was not found: ${relativePath}`);
+    return file;
+}
+export function selectedContinuousFocusFile(snapshot, relativePath) {
+    const file = activeContinuousFocusFiles(snapshot).find((candidate) => candidate.relativePath === relativePath);
+    if (file === undefined)
+        throw new ServiceError('CONTINUOUS_FOCUS_SOURCE_NOT_FOUND', `Continuous focus source was not found: ${relativePath}`);
+    return file;
+}
+export function selectPlan(result, treeId) {
+    if (result.plans.length === 0)
+        throw new ServiceError('FOCUS_TREE_NOT_FOUND', 'The source file contains no focus tree');
+    if (treeId === undefined) {
+        if (result.plans.length !== 1)
+            throw new ServiceError('FOCUS_TREE_ID_REQUIRED', 'The source file contains multiple focus trees; provide treeId', { treeIds: result.plans.map(({ id }) => id) });
+        return result.plans[0];
+    }
+    const plan = result.plans.find(({ id }) => id === treeId);
+    if (plan === undefined)
+        throw new ServiceError('FOCUS_TREE_NOT_FOUND', `Focus tree was not found: ${treeId}`);
+    return plan;
+}
+export function selectContinuousPlan(result, paletteId) {
+    if (result.continuousFocusPalettes.length === 0)
+        throw new ServiceError('CONTINUOUS_FOCUS_PALETTE_NOT_FOUND', 'The source file contains no continuous focus palette');
+    if (paletteId === undefined) {
+        if (result.continuousFocusPalettes.length !== 1)
+            throw new ServiceError('CONTINUOUS_FOCUS_PALETTE_ID_REQUIRED', 'The source file contains multiple continuous focus palettes; provide paletteId', { paletteIds: result.continuousFocusPalettes.map(({ id }) => id) });
+        return result.continuousFocusPalettes[0];
+    }
+    const plan = result.continuousFocusPalettes.find(({ id }) => id === paletteId);
+    if (plan === undefined)
+        throw new ServiceError('CONTINUOUS_FOCUS_PALETTE_NOT_FOUND', `Continuous focus palette was not found: ${paletteId}`);
+    return plan;
+}
+export function referenceCatalog(snapshot) {
+    const identifiers = (kind) => [
+        ...new Set(snapshot.index
+            .findAll(kind)
+            .filter(({ overridden }) => !overridden)
+            .map(({ id }) => id)),
+    ].sort((left, right) => compareCodeUnits(left, right));
+    return {
+        decision: identifiers('decision'),
+        decision_category: identifiers('decision_category'),
+        event: identifiers('event'),
+        idea: identifiers('idea'),
+        leader: identifiers('leader'),
+        formable: identifiers('formable'),
+        helper: identifiers('scripted_effect'),
+    };
+}
+export function validationFromDiagnostics(diagnostics) {
+    const blocking = diagnostics.filter(({ severity }) => severity === 'error' || severity === 'blocker');
+    return {
+        passed: blocking.length === 0,
+        checks: [
+            {
+                id: 'focus-diagnostics',
+                passed: blocking.length === 0,
+                message: blocking.length === 0
+                    ? 'Focus source, references, and layout have no blocking diagnostics'
+                    : `${blocking.length} blocking focus diagnostics`,
+            },
+        ],
+    };
+}

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

@@ -0,0 +1,81 @@
+import { z } from 'zod/v4';
+import { IdleCacheLifetime } from '../core/idle-cache-lifetime.js';
+import { errorResult, toolResult } from '../core/operation-result.js';
+import { ServiceError } from '../core/result.js';
+import { guiInspectRequestSchema, guiRenderRequestSchema, guiRewriteRequestSchema, } from '../schemas/gui-requests.js';
+import { ScriptedGuiStudio } from './studio.js';
+import { inspectGui, completeGuiRewrite, normalizeGuiInspectRequest, normalizeGuiRenderRequest, normalizeGuiRewriteRequest, prepareGuiRewrite, renderGui, } from './tool-operations.js';
+const wireResult = z.record(z.string(), z.json());
+/** Registers read-only GUI operations without invoking transport handlers. */
+export function registerGuiJobs(operations, engine) {
+    const studio = new ScriptedGuiStudio(engine);
+    const lifetime = new IdleCacheLifetime(() => studio.clearCaches());
+    function register(name, schema, normalize, execute) {
+        operations.registerRead(name, schema, async (input, context) => {
+            const release = lifetime.begin();
+            try {
+                if (input.workspaceId !== 'current' && input.workspaceId !== context.workspaceId)
+                    throw new ServiceError('JOB_ARGUMENT_SCOPE_MISMATCH', 'The request workspace does not match the authorized job workspace');
+                const result = await execute(studio, normalize(input), {
+                    workspaceId: context.workspaceId,
+                    ...(context.principal === undefined ? {} : { principal: context.principal }),
+                    signal: context.signal,
+                    progress: (completed, total, message) => context.progress({ completed, total, message }),
+                });
+                const wire = wireResult.parse(JSON.parse(JSON.stringify(toolResult(result))));
+                const revision = result.data !== null &&
+                    typeof result.data === 'object' &&
+                    'sourceRevision' in result.data &&
+                    typeof result.data.sourceRevision === 'string'
+                    ? result.data.sourceRevision
+                    : result.data !== null &&
+                        typeof result.data === 'object' &&
+                        'sharedRevision' in result.data &&
+                        typeof result.data.sharedRevision === 'string'
+                        ? result.data.sharedRevision
+                        : undefined;
+                if (revision !== undefined)
+                    await context.stageResult(wire, { sourceRevision: revision });
+                return wire;
+            }
+            catch (error) {
+                if (context.signal.aborted)
+                    throw error;
+                return wireResult.parse(JSON.parse(JSON.stringify(errorResult(error, context.workspaceId))));
+            }
+            finally {
+                release();
+            }
+        });
+    }
+    register('hoi4.gui_inspect', guiInspectRequestSchema, normalizeGuiInspectRequest, (studio, input, context) => inspectGui(engine, studio, input, context));
+    register('hoi4.gui_render', guiRenderRequestSchema, normalizeGuiRenderRequest, renderGui);
+    operations.registerWrite('hoi4.gui_rewrite', guiRewriteRequestSchema, async (input, context) => {
+        if (input.workspaceId !== 'current' && input.workspaceId !== context.workspaceId)
+            throw new ServiceError('JOB_ARGUMENT_SCOPE_MISMATCH', 'The request workspace does not match the authorized job workspace');
+        const release = lifetime.begin();
+        try {
+            return await prepareGuiRewrite(studio, normalizeGuiRewriteRequest(input), {
+                workspaceId: context.workspaceId,
+                ...(context.principal === undefined ? {} : { principal: context.principal }),
+                signal: context.signal,
+                progress: (completed, total, message) => context.progress({ completed, total, message }),
+            });
+        }
+        finally {
+            release();
+        }
+    }, async (_input, execution, _reconciled, recipe, context) => {
+        const result = completeGuiRewrite(context.workspaceId, execution, recipe);
+        await context.progress({
+            completed: 3,
+            total: 3,
+            message: execution.outcome === 'applied'
+                ? 'GUI rewrite complete'
+                : execution.outcome === 'unchanged'
+                    ? 'GUI content already satisfied the rewrite'
+                    : 'GUI rewrite blocked',
+        });
+        return wireResult.parse(JSON.parse(JSON.stringify(toolResult(result))));
+    });
+}

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

@@ -0,0 +1,270 @@
+import { z } from 'zod/v4';
+import { boundedSourceHashEvidence, publicArtifactLink } from '../core/artifacts.js';
+import { canonicalJson, compareCodeUnits, hashCanonical } from '../core/canonical.js';
+import { autonomousResultArtifacts, } from '../core/transaction-execution.js';
+import { emptyServiceResult } from '../core/result.js';
+import { setInlineFilesScanned } from '../core/operation-result.js';
+import { PACKAGE_VERSION } from '../version.js';
+import { compileGuiHelpers } from './helpers.js';
+import { encodeGuiInspectionArtifact, projectGuiGraphForArtifact } from './inspection-artifact.js';
+const guiRewriteRecipeSchema = z
+    .object({
+    mode: z.enum(['source', 'helpers', 'patches']),
+    filesScanned: z.array(z.string().min(1).max(4096)),
+    compilation: z
+        .object({
+        nodeCount: z.number().int().nonnegative(),
+        templateInstanceCount: z.number().int().nonnegative(),
+        rawEscapeCount: z.number().int().nonnegative(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+function validationSummary(validation) {
+    return {
+        passed: validation.checks.every(({ passed }) => passed) &&
+            !validation.diagnostics.some(({ severity }) => severity === 'error' || severity === 'blocker'),
+        checks: validation.checks,
+    };
+}
+export function normalizeGuiInspectRequest(input) {
+    return input;
+}
+export function normalizeGuiRenderRequest(input) {
+    return input;
+}
+export function normalizeGuiRewriteRequest(input) {
+    return input;
+}
+export async function prepareGuiRewrite(studio, input, context) {
+    await context.progress(0, 3, 'Validating the requested GUI result');
+    const compilation = input.mode === 'helpers' ? compileGuiHelpers(input.helper) : undefined;
+    const transaction = await studio.planSource({
+        workspaceId: context.workspaceId,
+        relativePath: input.relativePath,
+        ...(input.mode === 'patches'
+            ? { expectedSourceHash: input.expectedSourceHash, patches: input.patches }
+            : {
+                source: input.mode === 'source' ? input.source : compilation.source,
+                ...(input.additionalFiles === undefined
+                    ? {}
+                    : { additionalFiles: input.additionalFiles }),
+            }),
+        windowName: input.windowName,
+        scenario: input.scenario,
+        ...(context.principal === undefined ? {} : { principal: context.principal }),
+        ...(context.signal === undefined ? {} : { signal: context.signal }),
+    });
+    await context.progress(2, 3, 'GUI rewrite prepared for journaled application');
+    return {
+        transaction,
+        recipe: guiRewriteRecipeSchema.parse({
+            mode: input.mode,
+            filesScanned: [
+                input.relativePath,
+                ...(input.additionalFiles ?? []).map(({ relativePath }) => relativePath),
+            ].sort(compareCodeUnits),
+            ...(compilation === undefined
+                ? {}
+                : {
+                    compilation: {
+                        nodeCount: compilation.nodeCount,
+                        templateInstanceCount: compilation.templateInstanceCount,
+                        rawEscapeCount: compilation.rawEscapeCount,
+                    },
+                }),
+        }),
+    };
+}
+export function completeGuiRewrite(workspaceId, execution, recipe) {
+    const parsed = guiRewriteRecipeSchema.parse(recipe);
+    const transaction = execution.transaction;
+    const result = emptyServiceResult(workspaceId, {
+        mode: parsed.mode,
+        execution: execution.outcome,
+        fileCount: transaction.files.length,
+        artifactCount: transaction.artifacts.length,
+        ...(parsed.compilation ?? {}),
+    });
+    result.status = transaction.validation.passed ? 'ok' : 'blocked';
+    result.code =
+        execution.outcome === 'applied'
+            ? 'GUI_CHANGES_APPLIED'
+            : execution.outcome === 'unchanged'
+                ? 'GUI_CHANGES_UNCHANGED'
+                : 'GUI_CHANGES_BLOCKED';
+    setInlineFilesScanned(result, parsed.filesScanned);
+    result.proposedFiles = transaction.files.slice(0, 100).map(({ relativePath }) => relativePath);
+    result.changedFiles = transaction.appliedFiles.slice(0, 100);
+    result.diagnostics = transaction.diagnostics.slice(0, 100);
+    result.artifacts = autonomousResultArtifacts(execution);
+    result.validation = transaction.validation;
+    result.blockers = transaction.diagnostics
+        .filter(({ severity }) => severity === 'error' || severity === 'blocker')
+        .map(({ code, message, details }) => ({
+        code,
+        message,
+        ...(details === undefined ? {} : { details }),
+    }));
+    return result;
+}
+export async function inspectGui(engine, studio, input, context) {
+    await context.progress(0, 3, 'Building GUI source graph');
+    const inspected = input.windowName === undefined || input.scenario === undefined
+        ? {
+            graph: (await studio.scan(context.workspaceId, context.principal, context.signal)).graph,
+            linted: undefined,
+        }
+        : await (async () => {
+            const linted = await studio.lint({
+                workspaceId: context.workspaceId,
+                windowName: input.windowName,
+                scenario: input.scenario,
+                ...(input.relatedScenarios === undefined
+                    ? {}
+                    : { relatedScenarios: input.relatedScenarios }),
+                generatedScenarios: input.generatedScenarios ?? {},
+                ...(context.principal === undefined ? {} : { principal: context.principal }),
+                ...(context.signal === undefined ? {} : { signal: context.signal }),
+            });
+            return { graph: linted.graph, linted };
+        })();
+    const { graph, linted } = inspected;
+    const sharedRevision = hashCanonical(graph.sourceHashes);
+    const workspace = engine.resolver.get(context.workspaceId, context.principal);
+    const sourceEvidence = boundedSourceHashEvidence(graph.sourceHashes);
+    const artifactGraph = projectGuiGraphForArtifact(graph, linted?.scene.elements.map(({ sourceId }) => sourceId));
+    const inspectionName = `gui-inspect.${sharedRevision.slice(0, 16)}.json`;
+    const inspectionJson = `${canonicalJson({
+        schemaVersion: 1,
+        sharedRevision,
+        offline: true,
+        graph: artifactGraph.graph,
+        ...(artifactGraph.projection === undefined
+            ? {}
+            : { graphProjection: artifactGraph.projection }),
+        ...(linted === undefined
+            ? {}
+            : {
+                scenario: linted.scene.scenario,
+                fidelity: linted.scene.fidelity,
+                validation: linted.validation,
+            }),
+    })}\n`;
+    const encodedInspection = await encodeGuiInspectionArtifact(inspectionName, inspectionJson);
+    const artifact = await engine.artifacts.putChunked(workspace, encodedInspection.name, encodedInspection.mimeType, encodedInspection.content, {
+        kind: 'gui-inspect',
+        toolVersion: PACKAGE_VERSION,
+        schemaVersion: 'gui-inspect.v1',
+        sourceHashes: sourceEvidence.sourceHashes,
+        metadata: {
+            sharedRevision,
+            offline: true,
+            complete: graph.complete,
+            skippedSourceCount: graph.skippedSourceCount,
+            sourceHashInventory: sourceEvidence.inventory,
+            compressed: encodedInspection.compressed,
+            uncompressedBytes: encodedInspection.uncompressedBytes,
+            graphProjection: artifactGraph.projection?.mode ?? 'full',
+        },
+    }, encodedInspection.compressed
+        ? 'Gzip-compressed scripted GUI graph, diagnostics, and optional scenario fidelity inspection'
+        : 'Scripted GUI graph, diagnostics, and optional scenario fidelity inspection', context.signal);
+    const diagnostics = linted === undefined ? graph.diagnostics : linted.validation.diagnostics;
+    const result = emptyServiceResult(context.workspaceId, {
+        sharedRevision,
+        complete: graph.complete,
+        skippedSourceCount: graph.skippedSourceCount,
+        skippedSources: graph.skippedSources,
+        nodes: graph.nodes.length,
+        edges: graph.edges.length,
+        elements: graph.elements.length,
+        sprites: graph.sprites.length,
+        fonts: graph.fonts.length,
+        scriptedGuis: graph.scriptedGuis.length,
+        ...(linted === undefined
+            ? {}
+            : {
+                windowName: input.windowName,
+                scenarioId: linted.scene.scenario.id,
+                inspectedElementCount: linted.scene.elements.length,
+                fidelityCounts: Object.fromEntries(Object.entries(linted.scene.fidelity).map(([key, values]) => [key, values.length])),
+            }),
+    });
+    result.code = graph.complete ? 'GUI_INSPECTED' : 'GUI_INSPECTED_PARTIAL';
+    setInlineFilesScanned(result, graph.filesScanned);
+    result.diagnostics = diagnostics.slice(0, 100);
+    result.artifacts = [publicArtifactLink(artifact)];
+    result.validation =
+        linted === undefined
+            ? {
+                passed: !diagnostics.some(({ severity }) => severity === 'error' || severity === 'blocker'),
+                checks: [
+                    {
+                        id: 'gui-inspection',
+                        passed: true,
+                        message: graph.complete
+                            ? `${graph.nodes.length} GUI graph nodes connected from a complete inventory`
+                            : `${graph.nodes.length} GUI graph nodes connected; ${graph.skippedSourceCount} over-limit source(s) were skipped`,
+                    },
+                ],
+            }
+            : validationSummary({ diagnostics, checks: linted.validation.checks });
+    await context.progress(3, 3, 'GUI inspection complete');
+    return result;
+}
+export async function renderGui(studio, input, context) {
+    await context.progress(0, 4, 'Building GUI source graph');
+    const rendered = await studio.renderAndStore({
+        workspaceId: context.workspaceId,
+        windowName: input.windowName,
+        scenario: input.scenario,
+        ...(input.states === undefined ? {} : { states: input.states }),
+        ...(input.resolutions === undefined
+            ? {}
+            : {
+                resolutions: input.resolutions.map(({ width, height, uiScale }) => ({
+                    width,
+                    height,
+                    ...(uiScale === undefined ? {} : { uiScale }),
+                })),
+            }),
+        ...(input.relatedScenarios === undefined ? {} : { relatedScenarios: input.relatedScenarios }),
+        generatedScenarios: input.generatedScenarios ?? {},
+        ...(input.comparisonScenario === undefined
+            ? {}
+            : { comparisonScenario: input.comparisonScenario }),
+        ...(context.principal === undefined ? {} : { principal: context.principal }),
+        ...(context.signal === undefined ? {} : { signal: context.signal }),
+    });
+    await context.progress(3, 4, 'Preparing GUI result');
+    const diagnostics = rendered.validation.diagnostics;
+    const result = emptyServiceResult(context.workspaceId, {
+        windowName: input.windowName,
+        scenarioId: rendered.render.scene.scenario.id,
+        sourceRevision: rendered.render.scene.sourceRevision,
+        variantCount: rendered.render.images.length,
+        variants: rendered.render.images.slice(0, 64).map(({ variant, width, height }) => ({
+            variant,
+            width,
+            height,
+        })),
+        stateCount: rendered.stateScenes.length,
+        scenarioCount: rendered.scenarioScenes.length,
+        resolutionCount: rendered.resolutionScenes.length,
+        comparison: {
+            changedPixels: rendered.comparison.changedPixels,
+            changedRatio: rendered.comparison.changedRatio,
+        },
+        fidelityCounts: Object.fromEntries(Object.entries(rendered.render.fidelity).map(([key, values]) => [key, values.length])),
+        offlineRepresentation: true,
+    });
+    result.code = 'GUI_RENDERED';
+    setInlineFilesScanned(result, rendered.filesScanned);
+    result.diagnostics = diagnostics.slice(0, 100);
+    result.artifacts = rendered.artifacts.map(publicArtifactLink);
+    result.validation = validationSummary({ diagnostics, checks: rendered.validation.checks });
+    await context.progress(4, 4, 'GUI render complete');
+    return result;
+}

package/dist/hoi4_agent_tools/impact/scenario-suites.js

@@ -0,0 +1,74 @@
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { compareCodeUnits, sha256Bytes } from '../core/canonical.js';
+import { ServiceError } from '../core/result.js';
+import { canonicalPath, isWithin } from '../core/workspace.js';
+import { impactScenarioSuiteReferenceSchema } from '../schemas/analysis.js';
+function selectorKey(selector) {
+    return `${selector.kind}:${selector.id}`;
+}
+/** Read bounded workspace-owned suite references without executing any case or assertion. */
+export async function inspectImpactScenarioSuites(workspace, paths, graph, selected, signal) {
+    const result = {
+        matches: [],
+        sourceHashes: {},
+        unresolved: [],
+        scannedSuites: 0,
+        scannedCases: 0,
+        omittedMatches: 0,
+        complete: true,
+    };
+    const relevantSymbols = new Set([
+        ...selected.map(selectorKey),
+        ...graph.directConsumers.map(({ source }) => selectorKey(source)),
+        ...graph.transitiveConsumers.map(({ source }) => selectorKey(source)),
+    ]);
+    const relevantFiles = new Set(graph.affectedFiles);
+    for (const relativePath of [...new Set(paths)].sort(compareCodeUnits)) {
+        signal?.throwIfAborted();
+        const candidate = await canonicalPath(path.join(workspace.modRoot, relativePath), signal);
+        if (!isWithin(workspace.modRoot, candidate))
+            throw new ServiceError('IMPACT_SUITE_OUTSIDE_WORKSPACE', 'Scenario suite resolves outside the authorized mod root', {
+                relativePath,
+            });
+        try {
+            const details = await stat(candidate);
+            if (!details.isFile() || details.size > 4 * 1024 * 1024)
+                throw new RangeError('Suite must be a JSON file no larger than 4 MiB');
+            const bytes = await readFile(candidate);
+            if (bytes.length > 4 * 1024 * 1024)
+                throw new RangeError('Suite file exceeds 4 MiB');
+            const suite = impactScenarioSuiteReferenceSchema.parse(JSON.parse(bytes.toString('utf8')));
+            result.sourceHashes[`suite:${relativePath}`] = sha256Bytes(bytes);
+            result.scannedSuites += 1;
+            result.scannedCases += suite.cases.length;
+            for (const item of suite.cases) {
+                const via = [
+                    ...item.sourceSelectors
+                        .map(selectorKey)
+                        .filter((key) => relevantSymbols.has(key))
+                        .map((key) => `symbol:${key}`),
+                    ...item.sourceFiles
+                        .filter((file) => relevantFiles.has(file))
+                        .map((file) => `file:${file}`),
+                ].sort(compareCodeUnits);
+                if (via.length === 0)
+                    continue;
+                if (result.matches.length < 10_000)
+                    result.matches.push({ suitePath: relativePath, suiteId: suite.id, caseId: item.id, via });
+                else
+                    result.omittedMatches += 1;
+            }
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            result.unresolved.push({
+                path: relativePath,
+                reason: error instanceof Error ? error.message : 'Scenario suite could not be read or parsed',
+            });
+        }
+    }
+    result.complete = result.unresolved.length === 0 && result.omittedMatches === 0;
+    return result;
+}

package/dist/hoi4_agent_tools/impact/service.js

@@ -0,0 +1,127 @@
+import { analysisSourceEvidence } from '../core/analysis-evidence.js';
+import { publicArtifactLink } from '../core/artifacts.js';
+import { canonicalJson, hashCanonical } from '../core/canonical.js';
+import { compareImpactGraphs } from '../core/impact-comparison.js';
+import { inspectImpactGraph } from '../core/impact-graph.js';
+import { setInlineFilesScanned } from '../core/operation-result.js';
+import { emptyServiceResult, ServiceError } from '../core/result.js';
+import { buildProposedSourceOverlay } from '../core/source-overlay.js';
+import { PACKAGE_VERSION } from '../version.js';
+import { inspectImpactScenarioSuites } from './scenario-suites.js';
+/** Authorized, read-only impact operation shared by ordinary calls and persistent jobs. */
+export class ImpactAnalyzer {
+    engine;
+    constructor(engine) {
+        this.engine = engine;
+    }
+    async inspect(input) {
+        const workspace = this.engine.resolver.get(input.workspaceId, input.principal);
+        if (input.refresh)
+            this.engine.invalidate(input.workspaceId);
+        const before = await this.engine.scan(input.workspaceId, {}, input.principal, input.signal);
+        if (input.expectedRevision !== undefined && before.revision !== input.expectedRevision)
+            throw new ServiceError('IMPACT_SOURCE_STALE', 'Impact source revision changed since selection', {
+                expectedRevision: input.expectedRevision,
+                observedRevision: before.revision,
+            });
+        const overlay = input.proposedSources === undefined
+            ? undefined
+            : buildProposedSourceOverlay(before, workspace, input.proposedSources);
+        const availablePaths = new Set([
+            ...before.files.map(({ displayPath }) => displayPath),
+            ...(overlay?.snapshot.files.map(({ displayPath }) => displayPath) ?? []),
+            ...(overlay?.changes.map(({ path }) => path) ?? []),
+        ]);
+        for (const file of input.changedFiles)
+            if (!availablePaths.has(file))
+                throw new ServiceError('IMPACT_SOURCE_UNKNOWN', 'Changed file is not in the authorized source inventory or proposed overlay', { file });
+        const query = {
+            symbols: input.symbols,
+            changedFiles: input.changedFiles.length > 0
+                ? input.changedFiles
+                : (overlay?.changes.map(({ path }) => path) ?? []),
+            ...(input.maxNodes === undefined ? {} : { maxNodes: input.maxNodes }),
+            ...(input.maxEdges === undefined ? {} : { maxEdges: input.maxEdges }),
+            ...(input.maxDepth === undefined ? {} : { maxDepth: input.maxDepth }),
+        };
+        const comparison = overlay === undefined ? undefined : compareImpactGraphs(before, overlay.snapshot, query);
+        const graph = comparison?.after ?? inspectImpactGraph(before, query);
+        const analysis = comparison ?? graph;
+        const suiteGraph = comparison === undefined
+            ? graph
+            : {
+                ...graph,
+                directConsumers: [...comparison.before.directConsumers, ...graph.directConsumers],
+                transitiveConsumers: [
+                    ...comparison.before.transitiveConsumers,
+                    ...graph.transitiveConsumers,
+                ],
+                affectedFiles: [
+                    ...new Set([...comparison.before.affectedFiles, ...graph.affectedFiles]),
+                ],
+            };
+        const scenarioSuites = await inspectImpactScenarioSuites(workspace, input.scenarioSuites, suiteGraph, input.symbols, input.signal);
+        const complete = analysis.complete && scenarioSuites.complete;
+        const report = {
+            schemaVersion: 'impact-analysis.v1',
+            mode: overlay === undefined ? 'inspect' : 'compare',
+            query,
+            ...(overlay === undefined ? {} : { proposedChanges: overlay.changes }),
+            analysis,
+            scenarioSuites,
+        };
+        const reportHash = hashCanonical(report);
+        const artifactName = `impact-${reportHash.slice(0, 24)}.json`;
+        const provenanceSources = analysisSourceEvidence(before, overlay?.snapshot, scenarioSuites.sourceHashes);
+        const artifact = await this.engine.artifacts.putChunked(workspace, artifactName, 'application/json', `${canonicalJson(report)}\n`, {
+            kind: 'impact-analysis',
+            toolVersion: PACKAGE_VERSION,
+            schemaVersion: 'impact-analysis.v1',
+            sourceHashes: provenanceSources.sourceHashes,
+            metadata: {
+                beforeRevision: before.revision,
+                ...(overlay === undefined ? {} : { afterRevision: overlay.snapshot.revision }),
+                sourceInventory: provenanceSources.inventory,
+            },
+        }, 'Revision-pinned cross-system impact graph and source evidence', input.signal);
+        const result = emptyServiceResult(input.workspaceId, {
+            mode: overlay === undefined ? 'inspect' : 'compare',
+            sourceRevision: before.revision,
+            ...(overlay === undefined ? {} : { proposedRevision: overlay.snapshot.revision }),
+            reportHash,
+            complete,
+            definitions: graph.definitions.length,
+            directConsumers: graph.directConsumers.length,
+            transitiveConsumers: graph.transitiveConsumers.length,
+            affectedFiles: graph.affectedFiles.length,
+            cycles: graph.cycles.length,
+            scenarioSuites: scenarioSuites.scannedSuites,
+            affectedCases: scenarioSuites.matches.length,
+            unresolved: graph.unresolved.length + graph.dynamicReferences.length + scenarioSuites.unresolved.length,
+            ...(comparison === undefined
+                ? {}
+                : {
+                    addedConsumers: comparison.addedConsumers.length,
+                    removedConsumers: comparison.removedConsumers.length,
+                }),
+        });
+        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,
+            checks: [
+                {
+                    id: 'impact-coverage',
+                    passed: complete,
+                    message: complete
+                        ? 'Selected impact graph is complete under the declared bounds'
+                        : 'Impact graph has source, dynamic-reference, or traversal boundaries; inspect the linked report',
+                },
+            ],
+        };
+        return result;
+    }
+}