hoi4-agent-tools 3.0.9 → 3.1.0

package/dist/hoi4_agent_tools/core/engine.js

@@ -1,10 +1,14 @@
 import { compareCodeUnits, hashCanonical } from './canonical.js';
 import { SymbolIndex } from './index.js';
+import { IndexSegmentCache } from './index-segments.js';
+import { PersistentAnalysisCache, } from './persistent-analysis-cache.js';
+import { sourceDocuments } from './source/cache.js';
 import { WorkspaceScanner } from './scanner.js';
 import { ArtifactStore } from './artifacts.js';
-import { TransactionManager } from './transactions.js';
+import { TransactionManager, transactionRootFingerprint } from './transactions.js';
 import { RequestScheduler } from './request-scheduler.js';
 import { SharedRequestCapacity } from './shared-request-capacity.js';
+import { JobStore } from './job-store.js';
 const RECOVERY_TTL_SECONDS = 3_600;
 const RECOVERY_MAX_BYTES = 536_870_912;
 const RECOVERY_MAX_RECORDS = 128;
@@ -81,6 +85,8 @@ export class CoreEngine {
     scanner;
     artifacts;
     transactions;
+    indexSegments;
+    persistentAnalysisCache;
     #scanCache = new Map();
     #scanFlights = new Map();
     #scanGenerations = new Map();
@@ -88,14 +94,30 @@ export class CoreEngine {
     #activeScanAdmissions = new Set();
     constructor(resolver, services = {}) {
         this.resolver = resolver;
+        this.indexSegments = services.indexSegments ?? new IndexSegmentCache();
+        const state = resolver.serverState();
+        this.persistentAnalysisCache =
+            services.persistentAnalysisCache === null || state === undefined
+                ? undefined
+                : Promise.resolve(services.persistentAnalysisCache ?? PersistentAnalysisCache.create(state));
         this.requests = new RequestScheduler(resolver.config().maxConcurrentTools);
         this.sharedRequests = new SharedRequestCapacity(resolver.serverState()?.root, resolver.config().maxSharedTools);
         this.scanner =
             services.scanner ??
                 new WorkspaceScanner(resolver.config().scanMaxFiles, resolver.config().scanMaxBytes, resolver.config().scanMaxFileBytes);
+        let retentionJobs;
         this.artifacts =
             services.artifacts ??
-                new ArtifactStore(resolver.config().artifactMaxBytes, resolver.config().artifactMaxEntries, resolver.config().artifactMaxSingleBytes);
+                new ArtifactStore(resolver.config().artifactMaxBytes, resolver.config().artifactMaxEntries, resolver.config().artifactMaxSingleBytes, state === undefined
+                    ? undefined
+                    : async (workspace, signal) => {
+                        retentionJobs ??= JobStore.create(state);
+                        return (await retentionJobs).checkpointResources({
+                            workspaceId: workspace.id,
+                            workspaceIdentity: workspace.workspaceIdentity,
+                            rootFingerprint: transactionRootFingerprint(workspace),
+                        }, signal);
+                    });
         this.transactions =
             services.transactions ??
                 new TransactionManager(resolver, this.artifacts, RECOVERY_TTL_SECONDS, RECOVERY_MAX_BYTES, RECOVERY_MAX_RECORDS, resolver.serverState());
@@ -160,12 +182,28 @@ export class CoreEngine {
                         signal: controller.signal,
                     });
                     controller.signal.throwIfAborted();
-                    const revision = hashCanonical(files.map(({ displayPath, loadOrder, sha256 }) => ({ displayPath, loadOrder, sha256 })));
+                    const persistentAnalysisCache = await this.persistentAnalysisCache;
+                    const analysisScope = {
+                        workspaceIdentity: workspace.workspaceIdentity,
+                        rootFingerprint: transactionRootFingerprint(workspace),
+                        principal: principal ?? null,
+                    };
+                    await persistentAnalysisCache?.hydrate(analysisScope, files, sourceDocuments, this.indexSegments, controller.signal);
+                    const revision = hashCanonical(files.map(({ absolutePath, displayPath, relativePath, rootKind, loadOrder, shadowedBy, sha256, }) => ({
+                        absolutePath,
+                        displayPath,
+                        relativePath,
+                        rootKind,
+                        loadOrder,
+                        shadowedBy: shadowedBy ?? null,
+                        sha256,
+                    })));
                     const cacheKey = `${requestKey}:${revision}`;
                     const cached = this.#scanCache.get(cacheKey);
                     if (cached !== undefined)
                         return cached;
-                    const index = await SymbolIndex.buildAsync(files, controller.signal);
+                    const index = await SymbolIndex.buildAsync(files, controller.signal, this.indexSegments);
+                    await persistentAnalysisCache?.persist(analysisScope, files, sourceDocuments, this.indexSegments, controller.signal);
                     const snapshot = {
                         workspaceId,
                         revision,
@@ -219,12 +257,17 @@ export class CoreEngine {
     /** Drop completed scan buffers without invalidating revisions or interrupting active scans. */
     releaseScanCaches() {
         this.#scanCache.clear();
+        this.indexSegments.clear();
+        sourceDocuments.clear();
         this.scanner.clearCaches();
     }
     /** Monotonic cache generation used by domain services to invalidate derived snapshots. */
     generation(workspaceId) {
         return this.#scanGenerations.get(workspaceId) ?? 0;
     }
+    async persistentAnalysisCacheStatistics() {
+        return (await this.persistentAnalysisCache)?.statistics();
+    }
     awaitScanFlight(requestKey, flight, signal) {
         signal?.throwIfAborted();
         flight.waiters += 1;
@@ -342,6 +385,6 @@ export class CoreEngine {
         }
     }
     indexFiles(files) {
-        return SymbolIndex.build(files);
+        return SymbolIndex.build(files, this.indexSegments);
     }
 }

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

@@ -0,0 +1,186 @@
+import { z } from 'zod/v4';
+import { PACKAGE_VERSION } from '../version.js';
+import { helperExpansionRequestSchema, } from '../schemas/helper-expansion.js';
+import { canonicalJson, compareCodeUnits, hashCanonical } from './canonical.js';
+import { boundedSourceHashEvidence } from './artifacts.js';
+import { DependencyPages, dependencyPageCursorSchema } from './dependency-pages.js';
+import { ServiceError } from './result.js';
+import { transactionRootFingerprint } from './transactions.js';
+const digest = z.string().regex(/^[a-f0-9]{64}$/u);
+const querySchema = helperExpansionRequestSchema
+    .pick({ rootIds: true })
+    .extend({ maxDepth: z.number().int().min(1).max(256) });
+const continuationSchema = z
+    .object({
+    version: z.literal(1),
+    toolVersion: z.string(),
+    domain: z.enum(['event', 'technology']),
+    scope: digest,
+    sourceRevision: digest,
+    query: querySchema,
+    cursor: dependencyPageCursorSchema,
+})
+    .strict();
+export function helperExpansionValidation(summary) {
+    return {
+        passed: summary.complete,
+        checks: [
+            {
+                id: 'helper-expansion-coverage',
+                passed: summary.complete,
+                message: `${summary.completedRoots}/${summary.totalRoots} roots finished; ${summary.depthStops} depth stops; source inventory ${summary.sourceComplete ? 'complete' : 'partial'}; static source coverage only, not runtime validity`,
+            },
+        ],
+    };
+}
+/** Read-only structural evidence, with authenticated opaque continuation resources shared by both domains. */
+export async function inspectHelperExpansion(engine, workspaceId, inventory, request = {}, principal, signal) {
+    signal?.throwIfAborted();
+    const options = helperExpansionRequestSchema.parse(request);
+    const workspace = engine.resolver.get(workspaceId, principal);
+    const scope = hashCanonical({
+        workspaceId: workspace.id,
+        workspaceIdentity: workspace.workspaceIdentity,
+        ownerIdentity: workspace.ownerIdentity,
+        roots: transactionRootFingerprint(workspace),
+        principal: principal ?? null,
+    });
+    let restored;
+    if (options.continuationUri !== undefined) {
+        const resource = await engine.artifacts.readLogical(workspace, options.continuationUri, { mimeType: 'application/json', maxBytes: 8_388_608, maxChunks: 8_192 }, signal);
+        try {
+            restored = continuationSchema.parse(JSON.parse(resource.bytes.toString('utf8')));
+        }
+        catch {
+            throw new ServiceError('HELPER_CONTINUATION_INVALID', 'Helper continuation does not contain a valid bounded traversal envelope');
+        }
+        if (restored.domain !== inventory.domain || restored.scope !== scope)
+            throw new ServiceError('HELPER_CONTINUATION_SCOPE_MISMATCH', 'Helper continuation belongs to a different domain, workspace, root topology, or principal');
+        if (restored.toolVersion !== PACKAGE_VERSION ||
+            restored.sourceRevision !== inventory.sourceRevision)
+            throw new ServiceError('HELPER_CONTINUATION_STALE', 'Helper continuation requires the same tool version and exact source revision; start a new analysis');
+    }
+    const rootIds = options.rootIds === undefined
+        ? restored?.query.rootIds
+        : [...new Set(options.rootIds)].sort(compareCodeUnits);
+    const query = querySchema.parse({
+        ...(rootIds === undefined ? {} : { rootIds }),
+        maxDepth: options.maxDepth ?? restored?.query.maxDepth ?? 64,
+    });
+    if (restored !== undefined && hashCanonical(restored.query) !== hashCanonical(query))
+        throw new ServiceError('HELPER_CONTINUATION_QUERY_MISMATCH', 'Helper continuation cannot change root selection or depth; start a new analysis');
+    const knownRoots = new Set(inventory.roots);
+    if (query.rootIds?.some((id) => !knownRoots.has(id)) === true)
+        throw new ServiceError('HELPER_ROOT_UNKNOWN', 'Every selected root must be a structural helper-call root in the current source inventory');
+    const input = {
+        domain: `${inventory.domain}-helper-expansion.v1`,
+        sourceRevision: inventory.sourceRevision,
+        edges: inventory.edges.map(({ id, from, to }) => ({ id, from, to })),
+        roots: query.rootIds ?? [...inventory.roots].sort(compareCodeUnits),
+        branches: inventory.branches,
+        maximumDepth: query.maxDepth,
+        visitPolicy: 'edge_path',
+        reverseEdges: false,
+    };
+    const pager = new DependencyPages(input, restored?.cursor);
+    const page = pager.page(options.maxRecords ?? 250, options.maxWork ?? 5_000, signal);
+    const summary = {
+        complete: inventory.sourceComplete && page.finished && page.cursor.depthStops === 0,
+        finished: page.finished,
+        sourceComplete: inventory.sourceComplete,
+        maxDepth: query.maxDepth,
+        records: page.records.length,
+        totalRecords: page.cursor.emitted,
+        work: page.work,
+        totalWork: page.cursor.steps,
+        completedRoots: page.completedRoots,
+        totalRoots: page.totalRoots,
+        cycles: page.cursor.cycles,
+        depthStops: page.cursor.depthStops,
+    };
+    const used = new Set(page.records.flatMap(({ path }) => path));
+    const records = page.records.map(({ kind, root, path }) => ({
+        id: hashCanonical({ key: pager.key, kind, root, path }),
+        kind,
+        rootId: input.roots[root],
+        path: path.map((index) => inventory.edges[index].id),
+    }));
+    const continuationName = `${inventory.domain}-helper-continuation.json`;
+    const report = {
+        schemaVersion: 'helper-expansion.v1',
+        domain: inventory.domain,
+        workspaceId: workspace.id,
+        workspaceIdentity: workspace.workspaceIdentity,
+        sourceRevision: inventory.sourceRevision,
+        sourceEvidence: boundedSourceHashEvidence(inventory.sourceHashes),
+        unresolved: {
+            count: inventory.unresolved?.length ?? 0,
+            retainedCount: Math.min(100, inventory.unresolved?.length ?? 0),
+            sample: (inventory.unresolved ?? []).slice(0, 100),
+        },
+        query,
+        coverage: summary,
+        analysisBoundary: {
+            staticAnalysis: true,
+            visitPolicy: 'edge_path',
+            cyclePolicy: 'report_and_stop',
+            conditions: 'source evidence only; not evaluated',
+            directReferences: 'helper-owned leaves only; use the ordinary inspection modes for non-helper references',
+            completeness: 'recognized static call paths under report-and-stop cycle semantics; not runtime outcomes or resolution of dynamic source findings',
+        },
+        records,
+        edges: [...used].sort((left, right) => left - right).map((index) => inventory.edges[index]),
+        ...(page.finished
+            ? {}
+            : {
+                continuation: {
+                    name: continuationName,
+                    mimeType: 'application/json',
+                    resolution: 'helperExpansion.continuationUri in the tool result; also linked as a sibling artifact',
+                },
+            }),
+    };
+    const reportJson = `${canonicalJson(report)}\n`;
+    const provenance = {
+        kind: `${inventory.domain}-helper-expansion`,
+        toolVersion: PACKAGE_VERSION,
+        schemaVersion: '1',
+        sourceHashes: {},
+        metadata: { scope, sourceRevision: inventory.sourceRevision, traversal: pager.key },
+    };
+    const writes = [
+        {
+            name: `${inventory.domain}-helper-expansion.json`,
+            mimeType: 'application/json',
+            content: reportJson,
+            provenance,
+            description: 'Bounded source-linked helper path evidence and explicit traversal coverage',
+        },
+    ];
+    if (!page.finished)
+        writes.push({
+            name: continuationName,
+            mimeType: 'application/json',
+            content: canonicalJson(continuationSchema.parse({
+                version: 1,
+                toolVersion: PACKAGE_VERSION,
+                domain: inventory.domain,
+                scope,
+                sourceRevision: inventory.sourceRevision,
+                query,
+                cursor: page.cursor,
+            })),
+            provenance,
+            description: 'Opaque revision- and principal-bound helper continuation; pass as helperExpansion.continuationUri',
+        });
+    const artifacts = await engine.artifacts.withAtomicChunkedWrites(workspace, writes, (stored) => Promise.resolve([...stored]), signal);
+    return {
+        report,
+        reportJson,
+        summary: {
+            ...summary,
+            ...(artifacts[1] === undefined ? {} : { continuationUri: artifacts[1].uri }),
+        },
+        artifacts,
+    };
+}

package/dist/hoi4_agent_tools/core/index-segments.js

@@ -0,0 +1,137 @@
+import { canonicalJson, compareCodeUnits, hashCanonical } from './canonical.js';
+import { PACKAGE_VERSION } from '../version.js';
+export function indexSegmentAddress(file, isProvinceDefinition) {
+    return hashCanonical({
+        version: 'file-index-segment.v1',
+        toolVersion: PACKAGE_VERSION,
+        sourceHash: file.sha256,
+        path: file.displayPath,
+        relativePath: file.relativePath,
+        rootKind: file.rootKind,
+        loadOrder: file.loadOrder,
+        shadowedBy: file.shadowedBy ?? null,
+        isProvinceDefinition,
+    });
+}
+/** Encoded entries keep the aggregate index's mutable records out of the shared cache. */
+export class IndexSegmentCache {
+    maxBytes;
+    #entries = new Map();
+    #retainedBytes = 0;
+    #hits = 0;
+    #misses = 0;
+    #evictions = 0;
+    #oversized = 0;
+    constructor(maxBytes = 64 * 1024 * 1024) {
+        this.maxBytes = maxBytes;
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
+            throw new RangeError('Index segment cache size must be a non-negative integer');
+    }
+    get(address) {
+        const entry = this.#entries.get(address);
+        if (entry === undefined) {
+            this.#misses += 1;
+            return undefined;
+        }
+        this.#hits += 1;
+        this.#entries.delete(address);
+        this.#entries.set(address, entry);
+        return JSON.parse(entry.encoded);
+    }
+    /** Import one authenticated canonical entry without counting it as a process-local hit. */
+    importEncoded(address, encoded) {
+        const segment = JSON.parse(encoded);
+        if (typeof segment !== 'object' ||
+            segment === null ||
+            !('symbols' in segment) ||
+            !Array.isArray(segment.symbols) ||
+            !('references' in segment) ||
+            !Array.isArray(segment.references) ||
+            !('diagnostics' in segment) ||
+            !Array.isArray(segment.diagnostics) ||
+            !('complete' in segment) ||
+            typeof segment.complete !== 'boolean')
+            throw new Error('Persistent index segment is structurally invalid');
+        this.put(address, segment);
+    }
+    exportEncoded(address) {
+        return this.#entries.get(address)?.encoded;
+    }
+    put(address, segment) {
+        const encoded = canonicalJson(segment);
+        // Account for the UTF-16 string retained by V8, including conservative key overhead.
+        const bytes = encoded.length * 2 + address.length * 2 + 128;
+        if (bytes > this.maxBytes) {
+            this.#oversized += 1;
+            return;
+        }
+        const previous = this.#entries.get(address);
+        if (previous !== undefined) {
+            if (previous.encoded !== encoded)
+                throw new Error('An immutable index segment address produced different file-local facts');
+            this.#entries.delete(address);
+            this.#entries.set(address, previous);
+            return;
+        }
+        while (this.#retainedBytes + bytes > this.maxBytes) {
+            const oldest = this.#entries.entries().next().value;
+            if (oldest === undefined)
+                break;
+            this.#entries.delete(oldest[0]);
+            this.#retainedBytes -= oldest[1].bytes;
+            this.#evictions += 1;
+        }
+        this.#entries.set(address, { encoded, bytes });
+        this.#retainedBytes += bytes;
+    }
+    clear() {
+        this.#entries.clear();
+        this.#retainedBytes = 0;
+    }
+    statistics() {
+        return {
+            hits: this.#hits,
+            misses: this.#misses,
+            evictions: this.#evictions,
+            oversized: this.#oversized,
+            retainedBytes: this.#retainedBytes,
+            retainedSegments: this.#entries.size,
+        };
+    }
+}
+/** Reverse edges are derived from typed source references, never matching arbitrary strings. */
+export class ReverseSourceDependencies {
+    #consumers = new Map();
+    #definitions = new Map();
+    constructor(symbols, references) {
+        for (const symbol of symbols) {
+            const definitions = this.#definitions.get(symbol.path) ?? new Set();
+            definitions.add(`${symbol.kind}:${symbol.id}`);
+            this.#definitions.set(symbol.path, definitions);
+        }
+        for (const reference of references) {
+            const key = `${reference.toKind}:${reference.to}`;
+            const consumers = this.#consumers.get(key) ?? new Set();
+            consumers.add(reference.path);
+            this.#consumers.set(key, consumers);
+        }
+    }
+    affectedFiles(changedFiles) {
+        const affected = new Set(changedFiles);
+        const queue = [...affected];
+        for (const source of queue) {
+            for (const definition of this.#definitions.get(source) ?? []) {
+                for (const consumer of this.#consumers.get(definition) ?? []) {
+                    if (affected.has(consumer))
+                        continue;
+                    affected.add(consumer);
+                    queue.push(consumer);
+                }
+            }
+        }
+        return [...affected].sort(compareCodeUnits);
+    }
+    consumers(kind, id) {
+        return [...(this.#consumers.get(`${kind}:${id}`) ?? [])].sort(compareCodeUnits);
+    }
+}

package/dist/hoi4_agent_tools/core/index.js

@@ -1,6 +1,7 @@
 import { compareCodeUnits } from './canonical.js';
 import path from 'node:path';
 import { sortDiagnostics } from './diagnostics.js';
+import { indexSegmentAddress } from './index-segments.js';
 import { parseClausewitz, parseLocalisation, assignments, childBlocks, firstScalar, locationFor, sourcePartialLimitDiagnostics, SOURCE_MAX_BYTES, SOURCE_MAX_NESTING, nodeLocation, } from './source/index.js';
 const spriteDefinitionKeys = new Set([
     'spritetype',
@@ -269,7 +270,8 @@ export class SymbolIndex {
     #symbolLimitReported = false;
     #referenceLimitReported = false;
     #diagnosticsTruncated = false;
-    static build(files) {
+    #indexTableBlocked = new Set();
+    static build(files, segments) {
         const index = new SymbolIndex();
         const definitionSelection = selectedDefinitionFiles(files);
         for (const displayPath of definitionSelection.selected)
@@ -279,13 +281,13 @@ export class SymbolIndex {
         }
         for (const file of [...files].sort((a, b) => a.loadOrder - b.loadOrder || compareCodeUnits(a.displayPath, b.displayPath))) {
             index.files.set(file.displayPath, file);
-            index.indexFile(file);
+            index.indexFileWithSegments(file, segments);
         }
         index.finalize();
         return index;
     }
     /** Yield between source files so protocol cancellation and progress remain responsive. */
-    static async buildAsync(files, signal) {
+    static async buildAsync(files, signal, segments) {
         signal?.throwIfAborted();
         const index = new SymbolIndex();
         const definitionSelection = selectedDefinitionFiles(files);
@@ -298,7 +300,7 @@ export class SymbolIndex {
         for (const file of [...files].sort((a, b) => a.loadOrder - b.loadOrder || compareCodeUnits(a.displayPath, b.displayPath))) {
             signal?.throwIfAborted();
             index.files.set(file.displayPath, file);
-            index.indexFile(file);
+            index.indexFileWithSegments(file, segments);
             if (performance.now() - yieldedAt >= 20) {
                 await new Promise((resolve) => setImmediate(resolve));
                 signal?.throwIfAborted();
@@ -435,6 +437,45 @@ export class SymbolIndex {
         for (const diagnostic of diagnostics)
             this.addDiagnostic(diagnostic);
     }
+    indexFileWithSegments(file, cache) {
+        if (cache === undefined) {
+            this.indexFile(file);
+            return;
+        }
+        const address = indexSegmentAddress(file, this.#definitionFiles.has(file.displayPath));
+        const cached = cache.get(address);
+        if (cached?.complete === true &&
+            this.symbols.length + cached.symbols.length <= INDEX_RECORD_LIMIT &&
+            this.references.length + cached.references.length <= INDEX_RECORD_LIMIT &&
+            this.diagnostics.length + cached.diagnostics.length <= INDEX_DIAGNOSTIC_LIMIT) {
+            this.#currentFileShadowed = file.shadowedBy !== undefined;
+            for (const symbol of cached.symbols)
+                this.addSymbol(symbol);
+            for (const reference of cached.references)
+                this.addReference(reference);
+            this.addDiagnostics(cached.diagnostics);
+            return;
+        }
+        const symbols = this.symbols.length;
+        const references = this.references.length;
+        const diagnostics = this.diagnostics.length;
+        this.indexFile(file);
+        // Incomplete files and aggregate ceilings retain the full builder's exact diagnostic
+        // ordering and coverage bookkeeping. They are never cached as complete segments.
+        if (this.#indexTableBlocked.has(file.displayPath) ||
+            this.#skippedSourcePaths.has(file.displayPath) ||
+            this.#indexNestingBlocked.has(file.displayPath) ||
+            this.#symbolLimitReported ||
+            this.#referenceLimitReported ||
+            this.#diagnosticsTruncated)
+            return;
+        cache.put(address, {
+            symbols: this.symbols.slice(symbols),
+            references: this.references.slice(references),
+            diagnostics: this.diagnostics.slice(diagnostics),
+            complete: true,
+        });
+    }
     indexFile(file) {
         this.#currentFileShadowed = file.shadowedBy !== undefined;
         const diagnosticStart = this.diagnostics.length;
@@ -1163,6 +1204,7 @@ export class SymbolIndex {
         let line = 1;
         while (start <= text.length) {
             if (line > INDEX_TABLE_RECORD_LIMIT) {
+                this.#indexTableBlocked.add(file.displayPath);
                 this.#complete = false;
                 this.addDiagnostic({
                     code: 'INDEX_TABLE_RECORD_LIMIT',
@@ -1189,6 +1231,7 @@ export class SymbolIndex {
         let match;
         while ((match = matcher.exec(value)) !== null) {
             if (fields.length >= INDEX_TABLE_FIELD_LIMIT) {
+                this.#indexTableBlocked.add(file.displayPath);
                 this.#complete = false;
                 this.addDiagnostic({
                     code: 'INDEX_TABLE_FIELD_LIMIT',

package/dist/hoi4_agent_tools/core/job-controls.js

@@ -0,0 +1,109 @@
+import { z } from 'zod/v4';
+import { JobService } from './job-service.js';
+import { emptyServiceResult, ServiceError } from './result.js';
+import { errorResult, strictOperationResultSchema, toolResult } from './operation-result.js';
+import { requireOperationScope, resolveOperationWorkspaceId, } from './operation-context.js';
+import { workspaceIdSchema } from '../schemas/common.js';
+const jobIdSchema = z.string().regex(/^job_[a-f0-9]{64}$/u);
+export const jobReferenceSchema = z
+    .object({ workspaceId: workspaceIdSchema, jobId: jobIdSchema })
+    .strict();
+const jobStatusDataSchema = z
+    .object({
+    jobId: jobIdSchema,
+    toolName: z.string().max(256),
+    status: z.enum(['queued', 'running', 'reconciling', 'completed', 'cancelled', 'failed']),
+    revision: z.number().int().min(0),
+    createdAt: z.iso.datetime(),
+    updatedAt: z.iso.datetime(),
+    cancelRequested: z.boolean(),
+    resultReady: z.boolean(),
+    progress: z
+        .object({
+        completed: z.number().nonnegative(),
+        total: z.number().nonnegative().optional(),
+        message: z.string().max(4096),
+    })
+        .strict()
+        .optional(),
+    failure: z
+        .object({ code: z.string().max(256), message: z.string().max(4096) })
+        .strict()
+        .optional(),
+})
+    .strict();
+export const jobStatusOutputSchema = strictOperationResultSchema(jobStatusDataSchema);
+export function isJobControlTool(name) {
+    return name === 'hoi4.job_inspect' || name === 'hoi4.job_cancel';
+}
+function statusResult(record) {
+    const result = emptyServiceResult(record.scope.workspaceId, {
+        jobId: record.id,
+        toolName: record.request.toolName,
+        status: record.status,
+        revision: record.revision,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        cancelRequested: record.cancelRequested,
+        resultReady: record.result !== undefined,
+        ...(record.progress === undefined ? {} : { progress: record.progress }),
+        ...(record.failure === undefined ? {} : { failure: record.failure }),
+    });
+    result.code = record.status === 'failed' ? 'JOB_FAILED' : 'JOB_STATUS';
+    if (record.status === 'failed') {
+        result.status = 'error';
+        result.validation.passed = false;
+        result.blockers = [record.failure];
+    }
+    else if (record.status === 'cancelled') {
+        result.status = 'blocked';
+        result.code = 'JOB_CANCELLED';
+        result.validation.passed = false;
+    }
+    return result;
+}
+/** Bounded control traffic never acquires execution capacity or starts a worker. */
+export class JobControlService {
+    engine;
+    jobsPromise;
+    constructor(engine, jobsPromise) {
+        this.engine = engine;
+        this.jobsPromise = jobsPromise;
+    }
+    async call(name, input, context, signal) {
+        const parsed = jobReferenceSchema.parse(input);
+        let workspaceId = parsed.workspaceId;
+        try {
+            signal?.throwIfAborted();
+            workspaceId = await resolveOperationWorkspaceId(this.engine, context, parsed.workspaceId, signal);
+            this.jobsPromise ??= JobService.create(this.engine.resolver);
+            const jobs = await this.jobsPromise;
+            const record = await jobs.get(workspaceId, parsed.jobId, context.principal, signal);
+            if (name === 'hoi4.job_cancel') {
+                if (record.request.mutation)
+                    requireOperationScope(context, 'hoi4:write');
+                return toolResult(statusResult(await jobs.cancel(workspaceId, record.id, context.principal, signal)));
+            }
+            if (record.status !== 'completed')
+                return toolResult(statusResult(record));
+            if (record.result === undefined)
+                throw new ServiceError('JOB_RESULT_MISSING', 'Completed job has no authenticated result');
+            return {
+                ...record.result,
+                _meta: {
+                    ...z.record(z.string(), z.json()).parse(record.result._meta ?? {}),
+                    'io.github.klimPaskov/hoi4-agent-tools/job': {
+                        jobId: record.id,
+                        status: record.status,
+                        revision: record.revision,
+                    },
+                },
+            };
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            return errorResult(error, workspaceId);
+        }
+    }
+}