hoi4-agent-tools 3.0.8 → 3.1.0

package/dist/hoi4_agent_tools/technology/graph.js

@@ -1,6 +1,8 @@
 import { canonicalJson, compareCodeUnits, deterministicId, hashCanonical, } from '../core/canonical.js';
 import { sortDiagnostics } from '../core/diagnostics.js';
 import { ServiceError } from '../core/result.js';
+import { beginSemanticAnalysis, semanticFragment, SemanticCatalog, } from '../core/semantic-dependencies.js';
+import { runDependencyAnalysis, runDependencyAnalysisAsync, } from '../core/dependency-walk.js';
 import { analyzeTechnologySource, technologyAnalysisDiagnostics, technologySourceFiles, technologySourceFragmentCacheKey, } from './source-analysis.js';
 import { TECHNOLOGY_GRAPH_SCHEMA_VERSION, TECHNOLOGY_PARSER_VERSION, } from './model.js';
 const MAX_TECHNOLOGIES = 100_000;
@@ -374,7 +376,24 @@ function stronglyConnectedComponents(nodeIds, edges, signal) {
     }
     return components.sort((left, right) => compareCodeUnits(left[0] ?? '', right[0] ?? ''));
 }
-function expandHelperReferences(references, calls, unresolved, analysisMode, signal) {
+function technologyHelperWalk(calls, sourceRevision) {
+    return {
+        domain: 'technology-helper-references',
+        sourceRevision,
+        edges: calls.map(({ id, sourceKind, sourceId, helperId }) => ({
+            id,
+            from: `${sourceKind}:${sourceId}`,
+            to: `scripted_effect:${helperId}`,
+        })),
+        roots: calls.filter(({ sourceKind }) => sourceKind !== 'scripted_effect').map(({ id }) => id),
+        branches: [...new Set(calls.map(({ helperId }) => `scripted_effect:${helperId}`))].sort(compareCodeUnits),
+        maximumDepth: MAX_HELPER_DEPTH,
+        maximumSteps: 10_000_000,
+        visitPolicy: 'path',
+        reverseEdges: false,
+    };
+}
+function expandHelperReferences(references, calls, unresolved, analysisMode, walk, signal) {
     const direct = references.filter(({ sourceKind }) => sourceKind === 'scripted_effect');
     const publicReferences = references.filter(({ sourceKind }) => sourceKind !== 'scripted_effect');
     if (analysisMode === 'focused') {
@@ -404,82 +423,59 @@ function expandHelperReferences(references, calls, unresolved, analysisMode, sig
         group.push(reference);
         refsByHelper.set(reference.sourceId, group);
     }
-    const callsBySource = new Map();
-    for (const call of calls) {
-        const key = `${call.sourceKind}:${call.sourceId}`;
-        const group = callsBySource.get(key) ?? [];
-        group.push(call);
-        callsBySource.set(key, group);
-    }
     const projected = [...publicReferences, ...direct];
     let projectionCount = 0;
-    for (const rootCall of calls.filter(({ sourceKind }) => sourceKind !== 'scripted_effect')) {
-        const stack = [
-            {
-                helperId: rootCall.helperId,
-                helperStack: [rootCall.helperId],
-                confidence: rootCall.confidence,
-            },
-        ];
-        const visited = new Set();
-        while (stack.length > 0) {
-            signal?.throwIfAborted();
-            const current = stack.pop();
-            const visitKey = current.helperStack.join('\0');
-            if (visited.has(visitKey))
-                continue;
-            visited.add(visitKey);
-            if (current.helperStack.length > MAX_HELPER_DEPTH) {
-                unresolved.push({
-                    id: deterministicId('tech-unresolved', { rootCall, helperStack: current.helperStack }),
-                    kind: 'unsupported_construct',
-                    expression: current.helperStack.join(' -> '),
-                    ownerId: rootCall.sourceId,
-                    location: rootCall.location,
-                    confidence: 'unresolved',
-                    blockers: [
-                        {
-                            code: 'TECH_HELPER_DEPTH_BLOCKED',
-                            message: `Scripted-effect expansion exceeds depth ${MAX_HELPER_DEPTH}`,
-                            location: rootCall.location,
-                        },
-                    ],
-                });
-                continue;
-            }
-            for (const reference of refsByHelper.get(current.helperId) ?? []) {
-                projectionCount += 1;
-                if (projectionCount > MAX_HELPER_PROJECTIONS)
-                    break;
-                projected.push({
-                    ...reference,
-                    id: deterministicId('tech-external-projection', {
-                        root: rootCall.id,
-                        reference: reference.id,
-                        helperStack: current.helperStack,
-                    }),
-                    sourceKind: rootCall.sourceKind,
-                    sourceId: rootCall.sourceId,
-                    helperStack: [...current.helperStack],
-                    confidence: worseConfidence(current.confidence, reference.confidence),
-                    metadata: {
-                        ...reference.metadata,
-                        projectedFromScriptedEffect: reference.sourceId,
-                        callLocation: canonicalJson(rootCall.location),
+    if (walk === undefined)
+        throw new Error('Full technology helper analysis requires a dependency traversal');
+    const roots = calls.filter(({ sourceKind }) => sourceKind !== 'scripted_effect');
+    const callById = new Map(calls.map((call) => [call.id, call]));
+    for (const record of walk.state.records) {
+        signal?.throwIfAborted();
+        if (record.kind !== 'visit' && record.kind !== 'depth')
+            continue;
+        const rootCall = roots[record.root];
+        const path = walk.path(record.path).map(({ id }) => callById.get(id));
+        const helperStack = path.map(({ helperId }) => helperId);
+        if (record.kind === 'depth') {
+            unresolved.push({
+                id: deterministicId('tech-unresolved', { rootCall, helperStack }),
+                kind: 'unsupported_construct',
+                expression: helperStack.join(' -> '),
+                ownerId: rootCall.sourceId,
+                location: rootCall.location,
+                confidence: 'unresolved',
+                blockers: [
+                    {
+                        code: 'TECH_HELPER_DEPTH_BLOCKED',
+                        message: `Scripted-effect expansion exceeds depth ${MAX_HELPER_DEPTH}`,
+                        location: rootCall.location,
                     },
-                });
-            }
+                ],
+            });
+            continue;
+        }
+        const confidence = path.reduce((value, call) => worseConfidence(value, call.confidence), rootCall.confidence);
+        for (const reference of refsByHelper.get(path.at(-1).helperId) ?? []) {
+            projectionCount++;
             if (projectionCount > MAX_HELPER_PROJECTIONS)
                 break;
-            for (const call of callsBySource.get(`scripted_effect:${current.helperId}`) ?? []) {
-                if (current.helperStack.includes(call.helperId))
-                    continue;
-                stack.push({
-                    helperId: call.helperId,
-                    helperStack: [...current.helperStack, call.helperId],
-                    confidence: worseConfidence(current.confidence, call.confidence),
-                });
-            }
+            projected.push({
+                ...reference,
+                id: deterministicId('tech-external-projection', {
+                    root: rootCall.id,
+                    reference: reference.id,
+                    helperStack,
+                }),
+                sourceKind: rootCall.sourceKind,
+                sourceId: rootCall.sourceId,
+                helperStack,
+                confidence: worseConfidence(confidence, reference.confidence),
+                metadata: {
+                    ...reference.metadata,
+                    projectedFromScriptedEffect: reference.sourceId,
+                    callLocation: canonicalJson(rootCall.location),
+                },
+            });
         }
         if (projectionCount > MAX_HELPER_PROJECTIONS)
             break;
@@ -1123,14 +1119,13 @@ function fragmentsFor(snapshot, options) {
     };
     const fingerprint = helperCatalogFingerprint(snapshot);
     const fragments = [];
+    const dependencies = beginSemanticAnalysis(options.cache, snapshot, 'technology', options.workspaceIdentity);
+    const reads = new SemanticCatalog();
+    context.helperIds = reads.bind('helpers', 'scripted_effect', helperIds);
     for (const file of technologySourceFiles(snapshot.files)) {
         options.signal?.throwIfAborted();
         const key = technologySourceFragmentCacheKey(file, fingerprint);
-        let fragment = options.cache?.get(key);
-        if (fragment === undefined) {
-            fragment = analyzeTechnologySource(file, context);
-            options.cache?.set(key, fragment, file.bytes.length);
-        }
+        const fragment = semanticFragment(dependencies, options.cache, file, key, reads, () => analyzeTechnologySource(file, context));
         fragments.push(fragment);
     }
     return fragments;
@@ -1143,6 +1138,12 @@ function resolveUnlocks(unlocks, targets, complete) {
     }));
 }
 export function buildTechnologyGraph(snapshot, options) {
+    return runDependencyAnalysis(technologyGraphAnalysis(snapshot, options), options.signal);
+}
+export function buildTechnologyGraphAsync(snapshot, options) {
+    return runDependencyAnalysisAsync(technologyGraphAnalysis(snapshot, options), options.signal);
+}
+function* technologyGraphAnalysis(snapshot, options) {
     options.signal?.throwIfAborted();
     const fragments = fragmentsFor(snapshot, options);
     const assets = assetMap(options.assetFiles ?? []);
@@ -1167,7 +1168,10 @@ export function buildTechnologyGraph(snapshot, options) {
     const placements = enrichPlacements(basePlacements, edges, gridboxes, technologies, unlocks, itemLayouts, options.signal);
     const unresolved = fragments.flatMap(({ unresolved }) => unresolved);
     const helperCalls = fragments.flatMap(({ helperCalls }) => helperCalls);
-    const externalReferences = expandHelperReferences(fragments.flatMap(({ externalReferences }) => externalReferences), helperCalls, unresolved, options.analysisMode ?? 'full', options.signal);
+    const walk = options.analysisMode === 'focused'
+        ? undefined
+        : yield technologyHelperWalk(helperCalls, snapshot.revision);
+    const externalReferences = expandHelperReferences(fragments.flatMap(({ externalReferences }) => externalReferences), helperCalls, unresolved, options.analysisMode ?? 'full', walk, options.signal);
     const issues = diagnose(technologies, folders, placements, gridboxes, edges, categories, doctrineDefinitions, unlocks, externalReferences, selectedTechnologies.duplicates.map((group) => group.map(({ iconSprite, effectSignatureFields, ...technology }) => ({
         ...technology,
         icon: iconStatus(iconSprite, snapshot.index, assets),
@@ -1199,6 +1203,7 @@ export function buildTechnologyGraph(snapshot, options) {
         revision,
         complete: snapshot.complete &&
             unresolved.every(({ kind }) => kind !== 'partial_source') &&
+            !unresolved.some(({ blockers }) => blockers.some(({ code }) => code === 'TECH_HELPER_DEPTH_BLOCKED' || code === 'TECH_HELPER_PROJECTION_LIMIT')) &&
             !(options.analysisMode === 'focused' && helperCalls.length > 0),
         analysisBoundary: {
             staticAnalysis: true,

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

@@ -0,0 +1,33 @@
+import { compareCodeUnits } from '../core/canonical.js';
+export function technologyHelperInventory(graph, sourceComplete) {
+    return {
+        domain: 'technology',
+        sourceRevision: graph.revision,
+        sourceComplete,
+        sourceHashes: graph.sourceHashes,
+        unresolved: graph.unresolved.filter(({ id }) => id !== 'tech-unresolved-helper-expansion-deferred'),
+        edges: [
+            ...graph.helperCalls.map((call) => ({
+                id: call.id,
+                from: `${call.sourceKind}:${call.sourceId}`,
+                to: `scripted_effect:${call.helperId}`,
+                evidence: { kind: 'helper_call', call },
+            })),
+            ...graph.externalReferences
+                .filter(({ sourceKind }) => sourceKind === 'scripted_effect')
+                .map((reference) => ({
+                id: `reference:${reference.id}`,
+                from: `scripted_effect:${reference.sourceId}`,
+                to: `reference:${reference.id}`,
+                evidence: { kind: 'technology_reference', reference },
+            })),
+        ].sort((left, right) => compareCodeUnits(left.id, right.id)),
+        roots: graph.helperCalls
+            .filter(({ sourceKind }) => sourceKind !== 'scripted_effect')
+            .map(({ id }) => id)
+            .sort(compareCodeUnits),
+        branches: [
+            ...new Set(graph.helperCalls.map(({ helperId }) => `scripted_effect:${helperId}`)),
+        ].sort(compareCodeUnits),
+    };
+}

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

@@ -0,0 +1,60 @@
+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 { technologyCompareRequestSchema, technologyInspectRequestSchema, technologyRenderRequestSchema, } from '../schemas/technology.js';
+import { compareTechnologies, inspectTechnologies, normalizeTechnologyCompareRequest, normalizeTechnologyInspectionRequest, normalizeTechnologyRenderRequest, renderTechnologies, } from './operations.js';
+import { TechnologyTreeViewer } from './service.js';
+const wireResult = z.record(z.string(), z.json());
+/** Registers typed technology operations without invoking transport handlers. */
+export function registerTechnologyJobs(operations, engine) {
+    const viewer = new TechnologyTreeViewer(engine);
+    const lifetime = new IdleCacheLifetime(() => viewer.clearCaches());
+    function register(name, schema, normalize, execute, message) {
+        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');
+                await context.progress({ completed: 0, total: 3, message });
+                const result = await execute(viewer, {
+                    ...normalize(input),
+                    workspaceId: context.workspaceId,
+                    ...(context.principal === undefined ? {} : { principal: context.principal }),
+                    signal: context.signal,
+                });
+                await context.progress({
+                    completed: 3,
+                    total: 3,
+                    message: 'Technology operation complete',
+                });
+                const wire = wireResult.parse(JSON.parse(JSON.stringify(toolResult(result))));
+                const revision = result.data !== null &&
+                    typeof result.data === 'object' &&
+                    'revision' in result.data &&
+                    typeof result.data.revision === 'string'
+                    ? result.data.revision
+                    : result.data !== null &&
+                        typeof result.data === 'object' &&
+                        'afterRevision' in result.data &&
+                        typeof result.data.afterRevision === 'string'
+                        ? result.data.afterRevision
+                        : 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.tech_inspect', technologyInspectRequestSchema, normalizeTechnologyInspectionRequest, inspectTechnologies, 'Analyzing technology trees');
+    register('hoi4.tech_render', technologyRenderRequestSchema, normalizeTechnologyRenderRequest, renderTechnologies, 'Rendering technology-tree view');
+    register('hoi4.tech_compare', technologyCompareRequestSchema, normalizeTechnologyCompareRequest, compareTechnologies, 'Comparing technology-tree graphs');
+}

package/dist/hoi4_agent_tools/technology/operations.js

@@ -0,0 +1,125 @@
+import { publicArtifactLink } from '../core/artifacts.js';
+import { helperExpansionValidation } from '../core/helper-expansion.js';
+import { compareCodeUnits, hashCanonical } from '../core/canonical.js';
+import { emptyServiceResult } from '../core/result.js';
+import { setInlineFilesScanned } from '../core/operation-result.js';
+import { technologyCompareRequestSchema, technologyInspectRequestSchema, technologyRenderRequestSchema, } from '../schemas/technology.js';
+import { technologyDiagnostics } from './service.js';
+export function normalizeTechnologyInspectionRequest(input) {
+    return JSON.parse(JSON.stringify(technologyInspectRequestSchema.parse(input)));
+}
+export function normalizeTechnologyRenderRequest(input) {
+    return JSON.parse(JSON.stringify(technologyRenderRequestSchema.parse(input)));
+}
+export function normalizeTechnologyCompareRequest(input) {
+    return JSON.parse(JSON.stringify(technologyCompareRequestSchema.parse(input)));
+}
+export function technologyGraphHash(graph) {
+    return hashCanonical({
+        schemaVersion: graph.schemaVersion,
+        analysisMode: graph.analysisMode ?? 'full',
+        workspaceIdentity: graph.workspaceIdentity,
+        revision: graph.revision,
+        statistics: graph.statistics,
+        sourceHashes: graph.sourceHashes,
+    });
+}
+export function technologyCounts(graph, artifacts) {
+    return {
+        technologies: graph.statistics.technologyCount,
+        legacyDoctrines: graph.statistics.legacyDoctrineCount,
+        folders: graph.statistics.folderCount,
+        placements: graph.statistics.placementCount,
+        edges: graph.edges.length,
+        unlocks: graph.statistics.unlockCount,
+        references: graph.statistics.externalReferenceCount,
+        issues: graph.statistics.issueCount,
+        unresolved: graph.statistics.unresolvedCount,
+        artifacts,
+    };
+}
+export function technologyValidation(graph) {
+    const blocking = technologyDiagnostics(graph).filter(({ severity }) => severity === 'error' || severity === 'blocker').length;
+    return {
+        passed: graph.complete && blocking === 0,
+        checks: [
+            {
+                id: 'technology-analysis',
+                passed: graph.complete && blocking === 0,
+                message: graph.complete
+                    ? `${blocking} blocking technology diagnostics; full evidence is linked`
+                    : graph.analysisMode === 'focused'
+                        ? 'Helper projections were deferred for this large workspace; direct evidence is linked'
+                        : graph.unresolved.some(({ blockers }) => blockers.some(({ code }) => code === 'TECH_HELPER_DEPTH_BLOCKED' ||
+                            code === 'TECH_HELPER_PROJECTION_LIMIT'))
+                            ? 'Helper expansion reached a depth or materialization boundary; helper_expansion mode provides bounded source-linked continuation'
+                            : `${graph.skippedSourceCount} source(s) were skipped; full evidence is linked`,
+            },
+        ],
+    };
+}
+export async function inspectTechnologies(viewer, input) {
+    const output = await viewer.analyze(input);
+    const result = emptyServiceResult(input.workspaceId, {
+        mode: input.mode,
+        revision: output.graph.revision,
+        graphHash: technologyGraphHash(output.graph),
+        counts: technologyCounts(output.graph, output.artifacts.length),
+        ...(output.helperExpansion === undefined ? {} : { helperExpansion: output.helperExpansion }),
+    });
+    result.code =
+        (output.helperExpansion?.complete ?? output.graph.complete)
+            ? 'TECH_INSPECTED'
+            : 'TECH_INSPECTED_PARTIAL';
+    setInlineFilesScanned(result, output.graph.filesScanned);
+    result.artifacts = output.artifacts.map(publicArtifactLink);
+    result.validation = technologyValidation(output.graph);
+    if (output.helperExpansion !== undefined)
+        result.validation = helperExpansionValidation(output.helperExpansion);
+    return result;
+}
+export async function renderTechnologies(viewer, input) {
+    const output = await viewer.renderAndStore(input);
+    const result = emptyServiceResult(input.workspaceId, {
+        view: output.render.view,
+        revision: output.graph.revision,
+        graphHash: technologyGraphHash(output.graph),
+        hashes: output.render.hashes,
+        selectedNodes: output.render.selectedIds.length,
+        omittedNodes: output.render.omittedNodeCount,
+        focusedRenders: output.focused.length,
+        sourceAccurate: output.render.sourceAccurate,
+    });
+    result.code = output.graph.complete ? 'TECH_RENDERED' : 'TECH_RENDERED_PARTIAL';
+    setInlineFilesScanned(result, output.graph.filesScanned);
+    result.artifacts = output.artifacts.map(publicArtifactLink);
+    result.validation = technologyValidation(output.graph);
+    return result;
+}
+export async function compareTechnologies(viewer, input) {
+    const output = await viewer.compareAndStore(input);
+    const comparison = output.comparison;
+    const result = emptyServiceResult(input.workspaceId, {
+        beforeRevision: comparison.beforeRevision,
+        afterRevision: comparison.afterRevision,
+        added: comparison.technologies.added.length,
+        removed: comparison.technologies.removed.length,
+        renamed: comparison.technologies.renamed.length,
+        moved: comparison.technologies.moved.length,
+        regressions: comparison.regressions.length,
+        artifacts: output.artifacts.length,
+        ...(output.render === undefined ? {} : { renderHashes: output.render.hashes }),
+    });
+    result.code =
+        output.before.complete && output.after.complete ? 'TECH_COMPARED' : 'TECH_COMPARED_PARTIAL';
+    setInlineFilesScanned(result, [...new Set([...output.before.filesScanned, ...output.after.filesScanned])].sort(compareCodeUnits));
+    result.artifacts = output.artifacts.map(publicArtifactLink);
+    result.validation = {
+        passed: technologyValidation(output.before).passed && technologyValidation(output.after).passed,
+        checks: [
+            ...technologyValidation(output.before).checks,
+            ...technologyValidation(output.after).checks,
+        ],
+    };
+    return result;
+}

package/dist/hoi4_agent_tools/technology/service.js

@@ -1,4 +1,7 @@
 import path from 'node:path';
+import { inspectHelperExpansion } from '../core/helper-expansion.js';
+import { technologyHelperInventory } from './helper-expansion.js';
+import { clearSemanticDependencies } from '../core/semantic-dependencies.js';
 import { canonicalJson, compareCodeUnits, hashCanonical, sha256Bytes } from '../core/canonical.js';
 import { boundedSourceHashEvidence, } from '../core/artifacts.js';
 import { RenderBudget } from '../core/render-budget.js';
@@ -9,7 +12,7 @@ import { PACKAGE_VERSION } from '../version.js';
 import { GuiAssetCatalog } from '../gui/assets.js';
 import { buildGuiSourceGraph } from '../gui/source-graph.js';
 import { compareTechnologyGraphs } from './compare.js';
-import { buildTechnologyGraph, technologyAssetPatterns } from './graph.js';
+import { buildTechnologyGraph, buildTechnologyGraphAsync, technologyAssetPatterns, } from './graph.js';
 import { TECHNOLOGY_GRAPH_SCHEMA_VERSION } from './model.js';
 import { analyzeTechnologyImpact, discoverTechnologyFolders, explainTechnology, inspectTechnologyUnlocks, lintTechnologyGraph, technologyBonusCoverage, technologyScanReport, traceTechnology, } from './queries.js';
 import { renderTechnologyGraph, technologyRenderIconSprites, } from './render.js';
@@ -48,6 +51,7 @@ class BoundedTechnologyFragmentCache {
         }
     }
     clear() {
+        clearSemanticDependencies(this);
         this.#values.clear();
         this.#bytes = 0;
     }
@@ -445,16 +449,17 @@ export class TechnologyTreeViewer {
         const workspace = this.engine.resolver.get(workspaceId, options.principal);
         const generation = this.engine.generation(workspaceId);
         const cached = this.#state.current.get(workspaceId);
-        if (options.refresh !== true && cached?.generation === generation)
-            return cached.graph;
         const snapshot = await scanTechnologySources(this.engine, workspaceId, workspace, options.principal, options.signal);
         const analysisMode = 'full';
-        const preliminary = buildTechnologyGraph(snapshot, {
-            workspaceIdentity: workspace.workspaceIdentity,
-            cache: this.#state.fragments,
-            analysisMode,
-            ...(options.signal === undefined ? {} : { signal: options.signal }),
-        });
+        const unchangedSource = cached?.generation === generation && cached.snapshot.revision === snapshot.revision;
+        const preliminary = unchangedSource
+            ? cached.graph
+            : await buildTechnologyGraphAsync(snapshot, {
+                workspaceIdentity: workspace.workspaceIdentity,
+                cache: this.#state.fragments,
+                analysisMode,
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+            });
         const patterns = technologyAssetPatterns(preliminary);
         const assetFiles = patterns.length === 0
             ? []
@@ -462,7 +467,15 @@ export class TechnologyTreeViewer {
                 patterns,
                 ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
-        const graph = buildTechnologyGraph(snapshot, {
+        const assetIdentity = (files) => hashCanonical(files.map(({ absolutePath, displayPath, loadOrder, sha256 }) => ({
+            absolutePath,
+            displayPath,
+            loadOrder,
+            sha256,
+        })));
+        if (unchangedSource && assetIdentity(assetFiles) === assetIdentity(cached.assetFiles))
+            return cached.graph;
+        const graph = await buildTechnologyGraphAsync(snapshot, {
             workspaceIdentity: workspace.workspaceIdentity,
             cache: this.#state.fragments,
             assetFiles,
@@ -474,6 +487,24 @@ export class TechnologyTreeViewer {
         return graph;
     }
     async analyze(input) {
+        if (input.mode === 'helper_expansion') {
+            const workspace = this.engine.resolver.get(input.workspaceId, input.principal);
+            const snapshot = await scanTechnologySources(this.engine, input.workspaceId, workspace, input.principal, input.signal);
+            const graph = await buildTechnologyGraphAsync(snapshot, {
+                workspaceIdentity: workspace.workspaceIdentity,
+                cache: this.#state.fragments,
+                analysisMode: 'focused',
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+            });
+            const expansion = await inspectHelperExpansion(this.engine, input.workspaceId, technologyHelperInventory(graph, snapshot.complete && graph.unresolved.every(({ kind }) => kind !== 'partial_source')), input.helperExpansion, input.principal, input.signal);
+            return {
+                graph,
+                report: expansion.report,
+                reportJson: expansion.reportJson,
+                artifacts: expansion.artifacts,
+                helperExpansion: expansion.summary,
+            };
+        }
         const graph = await this.scan(input.workspaceId, {
             refresh: input.refresh ?? input.mode === 'scan',
             ...(input.principal === undefined ? {} : { principal: input.principal }),
@@ -542,11 +573,37 @@ export class TechnologyTreeViewer {
             complete: graph.complete,
             analysisBoundary: graph.analysisBoundary,
             mode: input.mode,
+            resources: [
+                {
+                    name: `${safeSlug(`technology-${input.mode}`)}-${graph.revision.slice(0, 12)}.json`,
+                    mimeType: 'application/json',
+                },
+                ...(input.mode === 'scan'
+                    ? [
+                        {
+                            name: `technology-graph-${graph.revision}.json`,
+                            mimeType: 'application/json',
+                        },
+                    ]
+                    : []),
+            ],
             report,
         })}\n`;
         const workspace = this.engine.resolver.get(input.workspaceId, input.principal);
+        const graphHashValue = graphHash(graph);
         const artifact = await this.engine.artifacts.putChunked(workspace, `${safeSlug(`technology-${input.mode}`)}-${graph.revision.slice(0, 12)}.json`, 'application/json', reportJson, technologyProvenance(graph, `technology-${input.mode}`, { mode: input.mode }), `Authoritative Technology Tree Viewer ${input.mode.replaceAll('_', ' ')} report`, input.signal);
-        return { graph, report, reportJson, artifacts: [artifact] };
+        const graphArtifact = input.mode === 'scan'
+            ? await this.engine.artifacts.putChunked(workspace, `technology-graph-${graph.revision}.json`, 'application/json', `${canonicalJson({ schemaVersion: 'technology-graph-snapshot.v1', graph })}\n`, technologyProvenance(graph, 'technology-graph-snapshot', {
+                revision: graph.revision,
+                graphHash: graphHashValue,
+            }), 'Revision-addressed Technology Tree Viewer graph snapshot', input.signal)
+            : undefined;
+        return {
+            graph,
+            report,
+            reportJson,
+            artifacts: [artifact, ...(graphArtifact === undefined ? [] : [graphArtifact])],
+        };
     }
     async renderAndStore(input) {
         const graph = await this.scan(input.workspaceId, {
@@ -747,10 +804,27 @@ export class TechnologyTreeViewer {
             return graph;
         }
         if (reference?.revision !== undefined) {
-            const graph = this.#state.history.get(workspaceId)?.get(reference.revision);
-            if (graph === undefined)
-                throw new ServiceError('TECH_REVISION_NOT_CACHED', 'Requested technology revision is not cached');
-            return graph;
+            const cached = this.#state.history.get(workspaceId)?.get(reference.revision);
+            if (cached !== undefined)
+                return cached;
+            const workspace = this.engine.resolver.get(workspaceId, principal);
+            const names = new Set([
+                `technology-graph-${reference.revision}.json`,
+                `technology-scan-${reference.revision.slice(0, 12)}.json`,
+            ]);
+            const candidates = (await this.engine.artifacts.list(workspace, signal)).filter(({ name }) => names.has(name));
+            for (const artifact of candidates) {
+                const selected = parseGraphArtifact(await readLogicalArtifact(this.engine, workspaceId, artifact.uri, principal, signal));
+                if (selected.revision === reference.revision &&
+                    selected.workspaceId === workspaceId &&
+                    selected.workspaceIdentity === current.workspaceIdentity) {
+                    rememberGraph(this.#state, selected);
+                    return selected;
+                }
+            }
+            if (candidates.length === 0)
+                throw new ServiceError('TECH_REVISION_NOT_CACHED', 'Requested technology revision is not cached or retained as a graph artifact');
+            throw new ServiceError('TECH_GRAPH_WORKSPACE_MISMATCH', 'Retained technology graph evidence does not match the requested revision and workspace topology');
         }
         return current;
     }

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

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { semanticSourceIdentity } from '../core/semantic-dependencies.js';
 import { compareCodeUnits, deterministicId } from '../core/canonical.js';
 import { assignments, childBlocks, firstScalar, nodeLocation, parseClausewitz, sourcePartialLimitDiagnostics, } from '../core/source/index.js';
 const technologyStructuralFields = new Set([
@@ -1031,7 +1032,7 @@ export function analyzeTechnologySource(file, context) {
     return fragment;
 }
 export function technologySourceFragmentCacheKey(file, catalogFingerprint) {
-    return `${file.sha256}:${catalogFingerprint}`;
+    return `${semanticSourceIdentity(file)}:${catalogFingerprint}`;
 }
 export function technologySourceFiles(files) {
     return files

package/dist/hoi4_agent_tools/version.js

@@ -1,6 +1,6 @@
 import { LATEST_PROTOCOL_VERSION } from '@modelcontextprotocol/sdk/types.js';
 export const PACKAGE_NAME = 'hoi4-agent-tools';
-export const PACKAGE_VERSION = '3.0.8';
+export const PACKAGE_VERSION = '3.1.0';
 export const MCP_PROTOCOL_VERSION = LATEST_PROTOCOL_VERSION;
 export const CONFIG_VERSION = 1;
 export const TRANSACTION_VERSION = 1;

package/docs/README.md

@@ -3,6 +3,8 @@
 - [Setup](setup.md): install the server, configure HOI4 paths, and connect an MCP client.
 - [Event chains](events.md): inspect, trace, lint, render, and compare event chains.
 - [Technology trees](technology.md): inspect, trace, lint, render, and compare technologies and doctrines.
+- [Bounded helper expansion](helper-expansion.md): resume source-linked event and technology helper paths with exact coverage boundaries.
+- [Persistent jobs](jobs.md): run, inspect, cancel, and recover long operations.
 - [AI and MTTH analysis](probability.md): evaluate weighted logic, timing, uncertainty, sequences, and patches.
 - [Focus trees](focus.md): inspect, create, render, and clean national or continuous focus content.
 - [Scripted GUIs](gui.md): inspect linked UI source, render states, and create or repair GUIs.

package/docs/development.md

@@ -25,6 +25,8 @@ The technology acceptance fixture contains 1,040 project-owned technologies acro
 
 `npx vitest run tests/integration/mcp-concurrent-workloads.test.ts` tests simultaneous production calls across all six domains over six HTTP sessions and four independent stdio processes, including artifact retrieval and queued cancellation. Execution limits and connection behavior are described in [HTTP](http.md) and the [concurrency decision](https://github.com/klimPaskov/hoi4-agent-tools/blob/main/docs/adr/0026-concurrent-request-execution.md).
 
+Persistent-job qualification covers authenticated record publication, request-key conflicts, read-result checkpoints, transaction-journal reconciliation, stopped-owner takeover, native task negotiation, ordinary-call parity, reconnect isolation, rewrite cancellation before source application, and fixed-entry worker execution. The public lifecycle contract is documented in [Persistent jobs and MCP tasks](jobs.md).
+
 The probability fixture contains more than 150 weighted blocks, 250 scenarios, and a declared stateful pool. Run `npm run benchmark` after analyzer changes. On the July 22, 2026 reference run, cold indexing took 28 ms, a cached block evaluation 29 ms, the 250-row matrix 85 ms, one million draws 9 ms, 3/12/25-candidate sequence cases 20/2,079/356 ms, and retrieval of a 1.84 MB result 3 ms. Review budgets are 250 ms, 150 ms, 750 ms, 100 ms, 200/10,000/3,000 ms, and 100 ms respectively; accuracy, method metadata, and omitted probability must not be weakened to meet them.
 
 Local opt-in tests can also read an installed game and an external mod without copying their sources: