hoi4-agent-tools 4.0.5 → 4.1.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## 4.1.0 - 2026-10-15
+
+- Add reference-image `create_world` requests with automatic dimensions, countries, biomes, coastline interpretation, drainage, offline English label recognition, optional aligned layers and reviewed semantic hints.
+- Add `preview: true` to map rewrites. Previews validate and render without creating or applying a rewrite transaction; failed generation is never illustrated using the unchanged base-game map.
+- Guard local reference inputs with canonical workspace checks, bounded decoding, fixed-memory original-source hashing and stale-source verification. OCR uses packaged local model data and bounded worker lifetimes.
+- Generate smoother relief, connected terrain-dependent provinces and downhill rivers; use installed palette conventions, distinct country filenames and actual urban footprints.
+- Cache map colors per province instead of hashing them for every rendered pixel. Retain deterministic pixels and artifact contents.
+- Preserve reviewed city, state, sea and region names and report uncertain interpretation. Map generation remains an offline foundation, with live acceptance evidence reported separately.
+- Add starter bookmarks, country histories, infantry templates, units, stockpiles and production; isolate old-world AI and startup hooks while retaining shared continent identifiers.
+- Track generated outputs and safely remove obsolete files on regeneration; reject edited outputs and malformed inventories. Bound complete-world inline diffs so preview links remain available.
+- Clean detached water speckles without turning lake islands into ocean pockets, preserve native province extent limits, and emit building positions without a spurious final record.
+
 ## 4.0.5 - 2026-10-14
 
 - Keep child anchors independent of parent `origo`, so centered native windows place their controls inside the frame.

package/README.md

@@ -17,6 +17,8 @@ Make focus trees, events and decisions. Edit maps and generate a new world. Prev
 ## What it does
 
 Your agent can build and edit focus trees, events, decisions and maps, and generate a new world.
+
+For a new map, give it a cleaned local reference image and preview the interpreted geography before writing. The [map workflow](docs/map.md#generate-a-world-from-one-image) creates provinces, states, terrain, cities, countries, supply and a provisional starting scenario. Reviewed names and masks refine ambiguous artwork; offline validation is separate from [native campaign acceptance](https://github.com/klimPaskov/hoi4-agent-tools/blob/v4.1.0/docs/evaluations/worldgen_acceptance_2026-10-15.md).
 It previews focus trees, technology folders, windows and maps, finds the right rule in the game's documentation, fixes broken script and tunes AI choices.
 You describe what you want; the agent picks the right tools.
 

package/dist/hoi4_agent_tools/core/bounded-source.js

@@ -0,0 +1,210 @@
+import { ServiceError } from './result.js';
+import { prepareSource, verifySource } from './scanner.js';
+import { isWithin } from './workspace.js';
+import { createHash } from 'node:crypto';
+import { lstat, mkdtemp, open, realpath, rmdir, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import sharp from 'sharp';
+import { TemporaryDirectoryLifetime, sweepTemporaryDirectories } from './temporary-directories.js';
+export const REFERENCE_SOURCE_MAX_BYTES = 1_073_741_824;
+export const REFERENCE_WORKING_MAX_SIDE = 3_072;
+export const REFERENCE_WORKING_MAX_BYTES = 33_554_432;
+function supportedRasterHeader(bytes) {
+    return ((bytes.length >= 8 &&
+        [137, 80, 78, 71, 13, 10, 26, 10].every((value, index) => bytes[index] === value)) ||
+        (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) ||
+        (bytes.length >= 12 &&
+            [82, 73, 70, 70].every((value, index) => bytes[index] === value) &&
+            [87, 69, 66, 80].every((value, index) => bytes[index + 8] === value)));
+}
+function assertSnapshotIsolation(resolver, candidate, checkDescendants) {
+    for (const workspace of resolver.list())
+        for (const root of [
+            ...workspace.roots,
+            { path: workspace.artifactRoot },
+            { path: workspace.cacheRoot },
+        ])
+            if (isWithin(root.path, candidate) || (checkDescendants && isWithin(candidate, root.path)))
+                throw new ServiceError('REFERENCE_SNAPSHOT_UNSAFE', 'Reference snapshots must be outside workspace capability roots');
+}
+async function assertSnapshotDirectory(resolver, directory, parent) {
+    const canonical = path.normalize(await realpath(directory));
+    const metadata = await lstat(directory);
+    if (canonical !== path.normalize(directory) ||
+        !isWithin(parent, canonical) ||
+        canonical === parent ||
+        metadata.isSymbolicLink() ||
+        !metadata.isDirectory())
+        throw new ServiceError('REFERENCE_SNAPSHOT_UNSAFE', 'Reference snapshot directory is not a private canonical directory');
+    if (process.platform !== 'win32' &&
+        ((metadata.mode & 0o077) !== 0 ||
+            (process.getuid !== undefined && metadata.uid !== process.getuid())))
+        throw new ServiceError('REFERENCE_SNAPSHOT_UNSAFE', 'Reference snapshot directory permissions are not private');
+    assertSnapshotIsolation(resolver, canonical, true);
+}
+async function createPrivateSnapshot(resolver) {
+    const parent = path.normalize(await realpath(resolver.serverState()?.root ?? tmpdir()));
+    assertSnapshotIsolation(resolver, parent, false);
+    const parentMetadata = await lstat(parent);
+    if (!parentMetadata.isDirectory() ||
+        parentMetadata.isSymbolicLink() ||
+        (process.platform !== 'win32' &&
+            (parentMetadata.mode & 0o022) !== 0 &&
+            (parentMetadata.mode & 0o1000) === 0))
+        throw new ServiceError('REFERENCE_SNAPSHOT_UNSAFE', 'Reference snapshot parent is not protected against directory replacement');
+    // Hidden directories are excluded by mod-root discovery even with a temporary-root fallback.
+    await sweepTemporaryDirectories(parent, {
+        referenceSnapshotsOnly: true,
+        staleMs: 0,
+        maxBytes: REFERENCE_SOURCE_MAX_BYTES,
+        protectedRoots: resolver
+            .list()
+            .flatMap((workspace) => [
+            ...workspace.roots.map(({ path }) => path),
+            workspace.artifactRoot,
+            workspace.cacheRoot,
+        ]),
+    });
+    const directory = await mkdtemp(path.join(parent, '.reference-snapshot-'));
+    const lifetime = new TemporaryDirectoryLifetime(REFERENCE_SOURCE_MAX_BYTES);
+    try {
+        await assertSnapshotDirectory(resolver, directory, parent);
+        await lifetime.own(directory);
+        const filePath = path.join(directory, 'source.raster');
+        const handle = await open(filePath, 'wx', 0o600);
+        try {
+            await assertSnapshotDirectory(resolver, directory, parent);
+            return { directory, filePath, handle, closed: false, lifetime };
+        }
+        catch (error) {
+            await handle.close();
+            await unlink(filePath);
+            throw error;
+        }
+    }
+    catch (error) {
+        await lifetime.dispose();
+        if (await lstat(directory).catch(() => undefined))
+            await rmdir(directory);
+        throw error;
+    }
+}
+async function removePrivateSnapshot(snapshot) {
+    try {
+        let closeFailed = false;
+        try {
+            if (!snapshot.closed)
+                await snapshot.handle.close();
+        }
+        catch {
+            closeFailed = true;
+        }
+        await snapshot.lifetime.dispose();
+        if (closeFailed || (await lstat(snapshot.directory).catch(() => undefined)))
+            throw new Error('Private snapshot ownership changed before cleanup');
+    }
+    catch {
+        throw new ServiceError('REFERENCE_SNAPSHOT_CLEANUP_FAILED', 'Private reference snapshot cleanup failed');
+    }
+}
+/** Decode a private snapshot copied and hashed from the same verified FD, using fixed memory. */
+export async function readReferenceImageSource(resolver, workspaceId, relativePath, principal, signal) {
+    if (!/\.(?:png|jpe?g|webp)$/iu.test(relativePath) || relativePath.includes(':'))
+        throw new ServiceError('REFERENCE_IMAGE_PATH_INVALID', 'Reference must name a local raster image');
+    const resolved = await resolver.resolvePath(workspaceId, relativePath, 'read', ['mod'], principal);
+    const source = await prepareSource(resolved.root, relativePath, signal);
+    let snapshot;
+    try {
+        if (!source.metadata.isFile())
+            throw new ServiceError('SOURCE_NOT_REGULAR_FILE', 'Reference source must be a regular file');
+        if (source.metadata.size < 1 || source.metadata.size > REFERENCE_SOURCE_MAX_BYTES)
+            throw new ServiceError('SOURCE_BYTE_LIMIT', 'Reference source exceeds its byte limit', {
+                limit: REFERENCE_SOURCE_MAX_BYTES,
+            });
+        signal?.throwIfAborted();
+        snapshot = await createPrivateSnapshot(resolver);
+        const hash = createHash('sha256');
+        const chunk = Buffer.alloc(Math.min(1_048_576, source.metadata.size));
+        let offset = 0;
+        while (offset < source.metadata.size) {
+            signal?.throwIfAborted();
+            const read = await source.handle.read(chunk, 0, Math.min(chunk.length, source.metadata.size - offset), offset);
+            if (read.bytesRead === 0)
+                throw new ServiceError('SCAN_SOURCE_CHANGED', 'Reference source changed while copying its snapshot');
+            if (offset === 0 && !supportedRasterHeader(chunk.subarray(0, read.bytesRead)))
+                throw new ServiceError('REFERENCE_IMAGE_DECODE_FAILED', 'Reference source is not a supported raster image');
+            hash.update(chunk.subarray(0, read.bytesRead));
+            let written = 0;
+            while (written < read.bytesRead) {
+                const result = await snapshot.handle.write(chunk, written, read.bytesRead - written, offset + written);
+                if (result.bytesWritten === 0)
+                    throw new ServiceError('REFERENCE_SNAPSHOT_WRITE_FAILED', 'Reference snapshot could not be completed');
+                written += result.bytesWritten;
+            }
+            offset += read.bytesRead;
+        }
+        const originalHash = hash.digest('hex');
+        await snapshot.handle.close();
+        snapshot.closed = true;
+        await verifySource(resolved.root, source);
+        signal?.throwIfAborted();
+        sharp.cache({ memory: 32, files: 0, items: 32 });
+        const input = sharp(snapshot.filePath, {
+            sequentialRead: true,
+            limitInputPixels: 300_000_000,
+            failOn: 'warning',
+        });
+        const metadata = await input.metadata();
+        if (!metadata.width ||
+            !metadata.height ||
+            (metadata.pages ?? 1) > 1 ||
+            !['png', 'jpeg', 'webp'].includes(metadata.format))
+            throw new ServiceError('REFERENCE_IMAGE_UNSUPPORTED', 'Reference must be a single-frame supported raster image');
+        signal?.throwIfAborted();
+        const decoded = await input
+            .resize({
+            width: REFERENCE_WORKING_MAX_SIDE,
+            height: REFERENCE_WORKING_MAX_SIDE,
+            fit: 'inside',
+            withoutEnlargement: true,
+        })
+            .png()
+            .toBuffer({ resolveWithObject: true });
+        await verifySource(resolved.root, source);
+        signal?.throwIfAborted();
+        if (decoded.data.length > REFERENCE_WORKING_MAX_BYTES)
+            throw new ServiceError('REFERENCE_WORKING_BYTE_LIMIT', 'Reference working image exceeds its byte limit');
+        return {
+            source: {
+                absolutePath: source.canonicalPath,
+                displayPath: `mod:${relativePath.replaceAll('\\', '/')}`,
+                relativePath: relativePath.replaceAll('\\', '/'),
+                rootKind: resolved.root.kind,
+                loadOrder: resolved.root.loadOrder,
+                size: source.metadata.size,
+                modifiedMs: source.metadata.mtimeMs,
+                sha256: originalHash,
+            },
+            bytes: decoded.data,
+            originalWidth: metadata.width,
+            originalHeight: metadata.height,
+            workingWidth: decoded.info.width,
+            workingHeight: decoded.info.height,
+        };
+    }
+    catch (error) {
+        if (error instanceof ServiceError || signal?.aborted)
+            throw error;
+        throw new ServiceError('REFERENCE_IMAGE_DECODE_FAILED', 'Reference image could not be safely decoded');
+    }
+    finally {
+        try {
+            if (snapshot !== undefined)
+                await removePrivateSnapshot(snapshot);
+        }
+        finally {
+            await source.handle.close();
+        }
+    }
+}

package/dist/hoi4_agent_tools/core/diagnostic-rollup.js

@@ -0,0 +1,91 @@
+import { canonicalJson, compareCodeUnits } from './canonical.js';
+import { sortDiagnostics } from './diagnostics.js';
+const SAMPLE_LIMIT = 8;
+/** Count source occurrences represented by an original diagnostic or a soft rollup. */
+export function diagnosticOccurrenceCount(diagnostic) {
+    const value = diagnostic.details?.occurrenceCount;
+    return diagnostic.details?.rollup === 'repeated-soft-diagnostics.v1' &&
+        typeof value === 'number' &&
+        Number.isSafeInteger(value) &&
+        value > 0
+        ? value
+        : 1;
+}
+/** Include omission evidence emitted by bounded validators without counting their marker twice. */
+export function diagnosticSeverityCounts(diagnostics) {
+    const counts = { info: 0, warning: 0, error: 0, blocker: 0 };
+    for (const diagnostic of diagnostics) {
+        if (diagnostic.code !== 'MAP_DIAGNOSTICS_TRUNCATED') {
+            counts[diagnostic.severity] += diagnosticOccurrenceCount(diagnostic);
+            continue;
+        }
+        const omissions = diagnostic.details?.omittedBySeverity;
+        if (typeof omissions !== 'object' || omissions === null)
+            continue;
+        for (const severity of ['info', 'warning', 'error', 'blocker']) {
+            const value = omissions[severity];
+            if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0)
+                counts[severity] += value;
+        }
+    }
+    return counts;
+}
+/** Keep every hard diagnostic; summarize repeated informational and warning codes only. */
+export function rollupRepeatedSoftDiagnostics(diagnostics, evidence) {
+    const hard = [];
+    const groups = new Map();
+    const ordered = diagnostics
+        .map((diagnostic) => ({ diagnostic, key: canonicalJson(diagnostic) }))
+        .sort((left, right) => compareCodeUnits(left.key, right.key))
+        .map(({ diagnostic }) => diagnostic);
+    for (const diagnostic of ordered) {
+        if (diagnostic.severity === 'error' ||
+            diagnostic.severity === 'blocker' ||
+            diagnostic.code === 'MAP_DIAGNOSTICS_TRUNCATED') {
+            hard.push(diagnostic);
+            continue;
+        }
+        const key = `${diagnostic.severity}:${diagnostic.code}`;
+        const group = groups.get(key) ?? [];
+        group.push(diagnostic);
+        groups.set(key, group);
+    }
+    const soft = [...groups.values()].map((group) => {
+        if (group.length === 1)
+            return group[0];
+        const first = group[0];
+        const occurrences = group.reduce((total, diagnostic) => total + diagnosticOccurrenceCount(diagnostic), 0);
+        const locations = new Map();
+        for (const diagnostic of group)
+            for (const location of [diagnostic.location, ...(diagnostic.related ?? [])])
+                if (location !== undefined)
+                    locations.set(canonicalJson(location), location);
+        const samples = [...locations]
+            .sort(([left], [right]) => compareCodeUnits(left, right))
+            .slice(0, SAMPLE_LIMIT)
+            .map(([, location]) => location);
+        const operationIds = [
+            ...new Set(group.flatMap(({ operationId }) => (operationId === undefined ? [] : [operationId]))),
+        ].sort(compareCodeUnits);
+        return {
+            code: first.code,
+            severity: first.severity,
+            category: first.category,
+            message: `${occurrences} occurrences of ${first.code}; ${first.message}`.slice(0, 4096),
+            ...(samples[0] === undefined ? {} : { location: samples[0] }),
+            ...(samples.length < 2 ? {} : { related: samples.slice(1) }),
+            ...(operationIds.length === 1 ? { operationId: operationIds[0] } : {}),
+            details: {
+                rollup: 'repeated-soft-diagnostics.v1',
+                occurrenceCount: occurrences,
+                retainedSamples: Math.min(SAMPLE_LIMIT, group.length),
+                samples: group.slice(0, SAMPLE_LIMIT),
+                operationCount: operationIds.length,
+                operationIds: operationIds.slice(0, SAMPLE_LIMIT),
+                locationCount: locations.size,
+                ...(evidence === undefined ? {} : { completeDiagnosticEvidence: evidence }),
+            },
+        };
+    });
+    return sortDiagnostics([...hard, ...soft]);
+}

package/dist/hoi4_agent_tools/core/domain-validation.js

@@ -1,6 +1,7 @@
 import { boundedSourceHashEvidence, publicArtifactLink } from './artifacts.js';
 import { canonicalJson } from './canonical.js';
 import { exactChangedFilePatterns, focusDomainScanPatterns, mapChangeScanPatterns, } from './domain-scan-patterns.js';
+import { rollupRepeatedSoftDiagnostics } from './diagnostic-rollup.js';
 import { parseClausewitz } from './source/index.js';
 import { TRANSACTION_MAX_DIAGNOSTICS } from './transaction-limits.js';
 import { importContinuousFocusPalettes, importFocusTrees, layoutFocusTreeAsync, lintContinuousFocusPalette, lintFocusTree, } from '../focus/index.js';
@@ -158,6 +159,17 @@ export async function postValidateTransaction(engine, transaction, principal, si
             .slice(0, retainedLimit - retainedHard.length);
         const omittedHard = hard.length - retainedHard.length;
         const artifactLink = publicArtifactLink(artifact);
+        if (transaction.operationKind === 'agent-nudger-map-changes') {
+            const rolled = rollupRepeatedSoftDiagnostics(diagnostics, artifactLink);
+            if (rolled.length <= availableDiagnostics) {
+                checks.push({
+                    id: 'post-write-diagnostics-artifact',
+                    passed: true,
+                    message: `Complete bounded post-write diagnostics are stored at ${artifactLink.uri}`,
+                });
+                return { diagnostics: rolled, checks, artifacts: [artifactLink] };
+            }
+        }
         checks.push({
             id: 'post-write-diagnostics-artifact',
             passed: omittedHard === 0,

package/dist/hoi4_agent_tools/core/engine.js

@@ -10,6 +10,7 @@ import { RequestScheduler } from './request-scheduler.js';
 import { SharedRequestCapacity } from './shared-request-capacity.js';
 import { JobStore } from './job-store.js';
 import { ServiceError } from './result.js';
+import { TRANSACTION_MAX_JOURNAL_BYTES } from './transaction-limits.js';
 /**
  * Completed scans kept per workspace. One tool call often scans several pattern sets (a GUI
  * preview scans layouts, linked definitions and localisation), so a single slot made every
@@ -17,7 +18,7 @@ import { ServiceError } from './result.js';
  */
 const SCAN_CACHE_ENTRIES_PER_WORKSPACE = 4;
 const RECOVERY_TTL_SECONDS = 3_600;
-const RECOVERY_MAX_BYTES = 536_870_912;
+const RECOVERY_MAX_BYTES = TRANSACTION_MAX_JOURNAL_BYTES;
 const RECOVERY_MAX_RECORDS = 128;
 function abortReason(signal) {
     return signal.reason instanceof Error

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

@@ -34,6 +34,8 @@ export class JobOperations {
             mutation: true,
             prepare: async (input, context) => {
                 const prepared = await prepare(schema.parse(input), context);
+                if ('readOnlyPreview' in prepared)
+                    return { readOnlyPreview: jsonObject.parse(prepared.readOnlyPreview) };
                 if (!('transaction' in prepared))
                     return { transaction: prepared };
                 return {
@@ -161,6 +163,13 @@ export class JobExecutor {
                     if (claimed.record.transaction !== undefined)
                         return writes.reconcile(workspaceId, id, owner.token, principal, undefined, true, (execution, reconciled, recipe) => operation.complete(initial.request.arguments, execution, reconciled, recipe, context));
                     const prepared = await operation.prepare(initial.request.arguments, context);
+                    if ('readOnlyPreview' in prepared) {
+                        controller.signal.throwIfAborted();
+                        return this.jobs.store.updateOwned(scope, id, owner.token, {
+                            status: 'completed',
+                            result: prepared.readOnlyPreview,
+                        });
+                    }
                     return writes.execute(workspaceId, id, owner.token, prepared.transaction, principal, controller.signal, prepared.recipe, (execution, reconciled, recipe) => operation.complete(initial.request.arguments, execution, reconciled, recipe, context));
                 }
                 const result = jsonObject.parse(await withAnalysisCheckpoints(jobAnalysisCheckpoints(context), () => operation.run(initial.request.arguments, context)));

package/dist/hoi4_agent_tools/core/managed-outputs.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { canonicalJson, compareCodeUnits, sha256Bytes } from './canonical.js';
+import { ServiceError } from './result.js';
+const manifestSchema = z
+    .object({
+    version: z.literal(1),
+    files: z
+        .array(z
+        .object({
+        relativePath: z.string().min(1).max(512),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    })
+        .strict())
+        .max(5000),
+})
+    .strict();
+/** Pure planning only: the shared transaction engine performs every replacement and deletion. */
+export function reconcileManagedOutputs(input) {
+    const sources = new Map(input.sources
+        .filter((f) => f.rootKind === 'mod')
+        .map((f) => [f.relativePath.replaceAll('\\', '/').toLowerCase(), f]));
+    const manifest = sources.get(input.manifestPath.toLowerCase());
+    const previous = manifest === undefined
+        ? []
+        : (() => {
+            if (manifest.bytes.length > 2_000_000)
+                throw new ServiceError('MANAGED_OUTPUT_MANIFEST_INVALID', 'Generated-output inventory exceeds its byte limit');
+            try {
+                return manifestSchema.parse(JSON.parse(manifest.bytes.toString('utf8'))).files;
+            }
+            catch {
+                throw new ServiceError('MANAGED_OUTPUT_MANIFEST_INVALID', 'Generated-output inventory is invalid');
+            }
+        })();
+    const seen = new Set();
+    for (const file of previous) {
+        const key = file.relativePath.toLowerCase();
+        if (file.relativePath.includes('\\') ||
+            file.relativePath.split('/').some((s) => !s || s === '.' || s === '..') ||
+            /^[a-z]:/iu.test(file.relativePath) ||
+            !input.permitsPath(file.relativePath) ||
+            seen.has(key))
+            throw new ServiceError('MANAGED_OUTPUT_MANIFEST_INVALID', 'Generated-output inventory contains an unsupported or duplicate path');
+        seen.add(key);
+        const current = sources.get(key);
+        if (current !== undefined && sha256Bytes(current.bytes) !== file.sha256)
+            throw new ServiceError('MANAGED_OUTPUT_EDITED', 'A generated file has been edited; regeneration would discard those changes', { relativePath: file.relativePath });
+    }
+    const outputs = input.proposed.filter((f) => f.content !== null && input.permitsPath(f.relativePath));
+    const next = new Set(outputs.map((f) => f.relativePath.toLowerCase()));
+    const deletions = previous
+        .filter((f) => !next.has(f.relativePath.toLowerCase()) && sources.has(f.relativePath.toLowerCase()))
+        .map((f) => ({
+        relativePath: f.relativePath,
+        content: null,
+        operationIds: [input.operationId],
+    }));
+    return [
+        ...deletions,
+        {
+            relativePath: input.manifestPath,
+            content: Buffer.from(canonicalJson({
+                version: 1,
+                files: outputs
+                    .map((f) => ({ relativePath: f.relativePath, sha256: sha256Bytes(f.content) }))
+                    .sort((a, b) => compareCodeUnits(a.relativePath, b.relativePath)),
+            }) + '\n'),
+            operationIds: [input.operationId],
+            mediaType: 'application/json',
+        },
+    ];
+}

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

@@ -500,10 +500,36 @@ export function errorResult(error, workspaceId = '', context = {}) {
         ? `REWRITE_${serviceError.code.slice('TRANSACTION_'.length)}`
         : serviceError.code;
     const publicMessage = internalWriteError
-        ? 'Rewrite could not be completed'
+        ? serviceError.code === 'TRANSACTION_STRUCTURE_LIMIT'
+            ? 'Rewrite exceeds the supported file, operation, validation, or evidence limits'
+            : serviceError.code === 'TRANSACTION_JOURNAL_LIMIT'
+                ? 'The requested rewrite exceeds the bounded rollback storage allowance'
+                : 'Rewrite could not be completed'
         : serviceError.message;
     const publicDetails = internalWriteError
-        ? {}
+        ? ['TRANSACTION_STRUCTURE_LIMIT', 'TRANSACTION_JOURNAL_LIMIT'].includes(serviceError.code)
+            ? Object.fromEntries(Object.entries(serviceError.details).filter(([key, value]) => [
+                'files',
+                'filesLimit',
+                'operations',
+                'operationsLimit',
+                'readDependencies',
+                'readDependenciesLimit',
+                'artifacts',
+                'artifactsLimit',
+                'diagnostics',
+                'diagnosticsLimit',
+                'checks',
+                'checksLimit',
+                'requestedWorkBytes',
+                'plannedJournalBytes',
+                'retainedBytes',
+                'maximumBytes',
+            ].includes(key) &&
+                typeof value === 'number' &&
+                Number.isSafeInteger(value) &&
+                value >= 0))
+            : {}
         : Object.fromEntries(Object.entries(serviceError.details).filter(([key]) => ![
             'cause',
             'stack',

package/dist/hoi4_agent_tools/core/scanner.js

@@ -1,4 +1,5 @@
 import { open, realpath, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { iterateFiles } from './file-glob.js';
 import { compareCodeUnits, sha256Bytes } from './canonical.js';
@@ -7,6 +8,22 @@ import { ServiceError } from './result.js';
 import { isWithin } from './workspace.js';
 const SCAN_IO_CONCURRENCY = 8;
 const SCAN_READ_BATCH_BYTES = 16_777_216;
+/** Hash an open source using fixed memory; callers verify its canonical identity afterwards. */
+export async function hashSourceBytes(source, signal) {
+    const hash = createHash('sha256');
+    const chunk = Buffer.alloc(Math.max(1, Math.min(1_048_576, source.metadata.size)));
+    let offset = 0;
+    while (offset < source.metadata.size) {
+        signal?.throwIfAborted();
+        const read = await source.handle.read(chunk, 0, Math.min(chunk.length, source.metadata.size - offset), offset);
+        if (!read.bytesRead)
+            throw new ServiceError('SCAN_SOURCE_CHANGED', 'Source changed while being hashed');
+        hash.update(chunk.subarray(0, read.bytesRead));
+        offset += read.bytesRead;
+    }
+    signal?.throwIfAborted();
+    return hash.digest('hex');
+}
 export async function verifySource(root, source) {
     const resolved = await realpath(source.absolutePath);
     if (!isWithin(root.path, resolved))

package/dist/hoi4_agent_tools/core/server-state.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { z } from 'zod/v4';
 import { compareCodeUnits, canonicalJson, secureId } from './canonical.js';
 import { ServiceError } from './result.js';
+import { TRANSACTION_MAX_MANIFEST_BYTES } from './transaction-limits.js';
 const journalKeyFile = 'journal-hmac.key';
 const journalKeyBytes = 32;
 const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/u);
@@ -157,7 +158,14 @@ export class ServerState {
         return new ServerState(canonicalRoot, Buffer.from(key));
     }
     authenticateJournal(payload) {
-        return createHmac('sha256', this.journalKey).update(canonicalJson(payload)).digest('hex');
+        return this.authenticateCanonicalJournal(canonicalJson(payload));
+    }
+    /** Internal canonical-byte path; the signature is identical to authenticateJournal. */
+    authenticateCanonicalJournal(payload) {
+        if (Buffer.byteLength(payload, 'utf8') > TRANSACTION_MAX_MANIFEST_BYTES) {
+            throw stateError('TRANSACTION_MANIFEST_LIMIT', 'Transaction manifest exceeds its fixed byte limit');
+        }
+        return createHmac('sha256', this.journalKey).update(payload).digest('hex');
     }
     verifyJournal(payload, authenticationTag) {
         if (!/^[a-f0-9]{64}$/u.test(authenticationTag))

package/dist/hoi4_agent_tools/core/temporary-directories.js

@@ -10,6 +10,7 @@ export const TEMPORARY_MAX_BYTES = 256 * 1024 * 1024;
 export const TEMPORARY_STALE_MS = 3 * 60 * 60 * 1000;
 // Dated event evaluation directories contain retained benchmark evidence, not scratch files.
 const scratchName = /^hoi4-(?:reference-source|event-eval)-[A-Za-z0-9]{6}$/u;
+const referenceSnapshotName = /^\.reference-snapshot-[A-Za-z0-9]{6}$/u;
 const ownerSchema = z
     .object({
     version: z.literal(1),
@@ -100,7 +101,8 @@ export async function sweepTemporaryDirectories(parent, options = {}) {
         }
     }))).flat();
     const candidates = [];
-    for (const name of (await readdir(root)).filter((name) => scratchName.test(name)).sort()) {
+    const names = options.referenceSnapshotsOnly ? referenceSnapshotName : scratchName;
+    for (const name of (await readdir(root)).filter((name) => names.test(name)).sort()) {
         const directory = path.join(root, name);
         if (protectedRoots.some((protectedRoot) => overlaps(directory, protectedRoot)))
             continue;
@@ -112,6 +114,8 @@ export async function sweepTemporaryDirectories(parent, options = {}) {
                 (await realpath(directory)) !== directory)
                 continue;
             const record = await owner(directory);
+            if (options.referenceSnapshotsOnly && record == null)
+                continue;
             // An interrupted sweep must not leave a permanent lock. Malformed or live locks
             // stay protected; only a confirmed dead local owner can relinquish its lock.
             const previousSweep = await owner(directory, SWEEP_LOCK);

package/dist/hoi4_agent_tools/core/transaction-canonical.js

@@ -0,0 +1,43 @@
+import { canonicalJson, compareCodeUnits } from './canonical.js';
+import { ServiceError } from './result.js';
+import { TRANSACTION_MAX_MANIFEST_BYTES } from './transaction-limits.js';
+/** A request-local snapshot of canonical immutable fields, without shared writable references. */
+export class TransactionCanonicalSnapshot {
+    immutable = new Map();
+    mutable;
+    constructor(source, mutableKeys) {
+        this.mutable = new Set(mutableKeys);
+        let bytes = 2;
+        for (const [key, value] of Object.entries(source)) {
+            if (this.mutable.has(key) || value === undefined)
+                continue;
+            const encoded = canonicalJson(value);
+            bytes += Buffer.byteLength(JSON.stringify(key)) + Buffer.byteLength(encoded) + 2;
+            this.assertBound(bytes);
+            this.immutable.set(key, encoded);
+        }
+    }
+    serialize(source, excludedKeys = []) {
+        const mutable = source;
+        const excluded = new Set(excludedKeys);
+        const keys = [...new Set([...this.immutable.keys(), ...this.mutable])]
+            .filter((key) => !excluded.has(key) && (this.immutable.has(key) || mutable[key] !== undefined))
+            .sort(compareCodeUnits);
+        // JSON objects emit integer keys before other keys, including after canonical insertion.
+        const orderedKeys = Object.keys(Object.fromEntries(keys.map((key) => [key, null])));
+        let bytes = 2;
+        const entries = orderedKeys.map((key) => {
+            const value = this.immutable.get(key) ?? canonicalJson(mutable[key]);
+            const entry = `${JSON.stringify(key)}:${value}`;
+            bytes += Buffer.byteLength(entry) + 1;
+            this.assertBound(bytes);
+            return entry;
+        });
+        return `{${entries.join(',')}}`;
+    }
+    assertBound(bytes) {
+        if (bytes > TRANSACTION_MAX_MANIFEST_BYTES) {
+            throw new ServiceError('TRANSACTION_MANIFEST_LIMIT', 'Transaction manifest exceeds its fixed byte limit');
+        }
+    }
+}

package/dist/hoi4_agent_tools/core/transaction-limits.js

@@ -1,8 +1,13 @@
-export const TRANSACTION_MAX_FILES = 1_000;
+// A generated world can contain thousands of state/region files. Review collections
+// remain bounded independently of the unchanged 16 MiB authenticated manifest cap.
+export const TRANSACTION_MAX_FILES = 5_000;
 export const TRANSACTION_MAX_OPERATIONS = 1_000;
 export const TRANSACTION_MAX_VALIDATION_CHECKS = 100;
 export const TRANSACTION_MAX_DIAGNOSTICS = 100;
-export const TRANSACTION_MAX_ARTIFACTS = 512;
+export const TRANSACTION_MAX_ARTIFACTS = 6_000;
 export const TRANSACTION_MAX_APPLIED_FILES = TRANSACTION_MAX_FILES;
 export const TRANSACTION_MAX_READ_DEPENDENCIES = 10_000;
 export const TRANSACTION_MAX_MANIFEST_BYTES = 16_777_216;
+export const TRANSACTION_MAX_PENDING_FILES = 16;
+// A maximum-size world needs before/after blobs plus staging and rollback copies.
+export const TRANSACTION_MAX_JOURNAL_BYTES = 1_073_741_824;